xtremflow/DESIGN_SYSTEM.md

XtremFlow Projector Noir Design System

Overview

XtremFlow uses a Projector Noir aesthetic: warm tungsten light cutting through a dark screening room. The design system prioritizes:

• Sophisticated Glassmorphism - Elegant blur effects with warm-tinted borders
• Tungsten Palette - Amber projector-beam accents on deep film-black
• Art-House Typography - Geometric headlines (Syne) + refined UI text (Instrument Sans)
• Focus-Driven Interactions - TV-friendly hover states and animations
• Responsive Layouts - Seamless adaptation from web to mobile

---

Color Palette

Backgrounds (warm film-black ladder)

• baseLevel0 (#0B0A08) - Deepest black, OLED optimized
• background / surface (#14110C) - Primary dark surface
• surfaceContainerLow (#1B1812) to surfaceContainerHighest (#363027) - Warm charcoal hierarchy

Primary Accents

• primary (#FFB35C) - Tungsten amber (main brand color)
• primaryContainer (#F39A1F) - Vivid amber (buttons, focus rings)
• secondary (#D3C6B2) - Warm taupe
• tertiary (#A4CCBE) - Verdigris teal (counterpoint accent)

Semantic Colors

• success (#6BD89B) - Success/completed state
• warning (#FFAB00) - Warning/caution state
• error (#FFB4AB) - Error/danger state (Material 3 dark)
• info (#64B6AC) - Information state (soft teal)

Text Hierarchy (warm ivory)

• textPrimary (#ECE6DA) - Main text
• textSecondary (#CDC4B4) - Secondary text
• textTertiary (#998F7C) - Tertiary text

Category Colors

• live (#FF6E5E) - Live streams (signal coral)
• movies (#E8B64C) - Movie content (warm gold)
• series (#5FC9AE) - Series content (teal)

---

Typography

Font Stack

1. Syne (headings/display) - Geometric, art-house, distinctive
2. Instrument Sans (UI/body) - Clean, readable, characterful
3. Fallback to system fonts

Sizes & Weights

Style	Size	Weight	Usage
displayLarge	56px	W800	Hero titles, billboards
displayMedium	48px	W700	Section headers
displaySmall	36px	W700	Sub-titles
headlineMedium	28px	W700	Card titles
headlineSmall	24px	W600	Smaller headings
titleLarge	20px	W600	Labels, emphasis
titleMedium	16px	W600	UI elements
titleSmall	14px	W600	Secondary labels
bodyLarge	16px	W400	Primary body text
bodyMedium	14px	W400	Standard body
bodySmall	12px	W400	Secondary text
labelLarge	14px	W700	Button text

---

Spacing System (8pt base)

spacing2 = 2.0
spacing4 = 4.0
spacing8 = 8.0
spacing12 = 12.0
spacing16 = 16.0
spacing20 = 20.0
spacing24 = 24.0
spacing32 = 32.0
spacing40 = 40.0
spacing48 = 48.0
spacing56 = 56.0
spacing64 = 64.0

TV Safe Margins: Use spacing32 (32px) for content edges on web/desktop. Mobile Safe Margins: Use spacing16 (16px) for mobile screens.

---

Radius System

Token	Value	Usage
radiusXs	4px	Tiny elements, toggles
radiusSm	8px	Badges, chips
radiusMd	12px	Buttons, inputs
radiusLg	16px	Cards, dialogs
radiusXl	24px	Large containers
radiusXxl	32px	Hero sections
radiusFull	999px	Circles, pills

---

Elevation & Shadows

Elevation Levels

elevationXs = 2.0   // Subtle lift (tooltips)
elevationSm = 4.0   // Slight elevation (cards)
elevationMd = 8.0   // Standard elevation (modals)
elevationLg = 16.0  // Prominent elevation (dialogs)
elevationXl = 24.0  // Maximum elevation (top-level modals)

Shadow System

Shadows automatically scale with elevation. Premium glass effects use dual shadows for depth:

• Primary shadow: Larger blur, higher spread (primary depth)
• Secondary shadow: Smaller blur, lower spread (edge definition)

---

Animations

Duration

durationXs = 100ms     // Quick interactions
durationSm = 150ms     // Hover states
durationBase = 200ms   // Standard transitions
durationMd = 300ms     // UI animations
durationLg = 400ms     // Page transitions
durationXl = 600ms     // Hero animations

Curves

• curveDefault (easeInOutCubic) - Standard animations
• curveSnappy (fastOutSlowIn) - Apple-like feel
• curveSmooth (easeOutCubic) - Content reveal
• curveBouncy (elasticOut) - Fun interactions

---

Core Widgets

GlassContainer

Premium glassmorphism widget with backdrop blur and gradient overlay.

GlassContainer(
  borderRadius: AppTheme.radiusLg,
  padding: EdgeInsets.all(16),
  blur: 15.0,
  opacity: 0.08,
  child: YourWidget(),
)

GlassCard

Interactive glass card with scale animations and loading states.

GlassCard(
  interactive: true,
  onTap: () => Navigator.push(...),
  child: ContentWidget(),
)

ChannelCard

Modern channel card with:

• Live indicator (with pulse animation)
• Favorite toggle button
• EPG information display
• Hover scale effects

ChannelCard(
  streamId: channel.id,
  name: channel.name,
  iconUrl: channel.logo,
  currentProgram: epg?.title,
  isLive: true,
  playlist: playlistConfig,
  onTap: () => playChannel(channel),
)

TvModernCard

Premium content card for movies, shows, or other media.

TvModernCard(
  id: item.id,
  title: item.title,
  imageUrl: item.posterUrl,
  rating: '8.7',
  year: '2024',
  badge: 'NEW',
  badgeColor: AppColors.primary,
  onTap: () => showDetails(item),
  onPlayTap: () => playContent(item),
)

HeroCarousel

Full-screen featured content carousel with auto-play.

HeroCarousel(
  items: [
    HeroCarouselItem(
      id: '1',
      title: 'Breaking Bad',
      subtitle: 'Season 5 - Now Streaming',
      imageUrl: 'https://...',
      badge: 'LIMITED TIME',
      onPlay: () => play(),
    ),
  ],
  autoPlay: true,
  autoPlayInterval: Duration(seconds: 6),
)

TvChannelGrid

Responsive grid layout for channels with flexible columns.

TvChannelGrid(
  children: channels.map((ch) => ChannelCard(...)).toList(),
  horizontalSpacing: 20,
  verticalSpacing: 20,
)

TvHorizontalList

Horizontal scrollable list with title and smooth scrolling.

TvHorizontalList(
  title: 'Trending Now',
  children: items.map((item) => TvModernCard(...)).toList(),
  itemWidth: 200,
  spacing: 16,
)

TvTopNavBar

Premium top navigation with search, notifications, profile.

TvTopNavBar(
  title: 'XtremFlow',
  onSearch: () => showSearchModal(),
  onNotifications: () => showNotifications(),
  onProfile: () => showProfile(),
  notificationCount: 3,
)

TvSideNav

Vertical navigation menu with category items.

TvSideNav(
  items: [
    TvNavItem(label: 'Home', icon: Icons.home),
    TvNavItem(label: 'Live TV', icon: Icons.tv),
    TvNavItem(label: 'Movies', icon: Icons.movie),
  ],
  selectedIndex: 0,
  onItemSelected: (index) => navigate(index),
)

---

Usage Guidelines

Color Usage

• Primary (Tungsten Amber): Call-to-action buttons, focus states, active indicators
• Secondary (Warm Taupe): Alerts, favorite toggles, urgent actions
• Tertiary (Verdigris Teal): Accent highlights, success states, featured badges
• White/Grey text: Maintain WCAG AA contrast ratio (4.5:1 minimum)

Typography

• Syne: Only for headings/hero text (sizes 20px and above)
• Instrument Sans: All UI, buttons, body text
• Letter spacing: Increase for larger sizes (hero titles: -1.0 to -1.5), decrease for body text

Spacing

• Card padding: 16px standard, 24px for premium cards
• List spacing: 20px horizontal, 20px vertical between items
• Button height: 44px standard (48px for mobile large buttons)
• Safe margins: 32px for TV, 16px for mobile

Animations

• Hover states: Always use 200-300ms animations
• Page transitions: 400-600ms for hero animations
• Loading: Use pulse/fade animations, not spinners when possible

Glassmorphism

• Blur: 15px standard, up to 20px for premium overlays
• Opacity: 8-12% for background colors, 15% for borders
• Gradient: Always include subtle gradient + border for depth
• Shadows: Dual shadow system for elevation

---

Mobile Adaptations

Touch Targets

• Minimum button size: 48x48px
• Minimum tap area: 44x44px
• Between buttons: 16px spacing minimum

Typography Scaling

• Display text: Reduced by 8px on mobile
• Body text: Standard sizes (no reduction needed)
• Buttons: Slightly smaller (14px vs 16px)

Navigation

• Bottom navigation bar for main categories
• Horizontal scrolling for content grids
• Collapsible menus for secondary options
• Modal dialogs for detailed information

Bottom Navigation

• Maximum 5 items
• Icon + label style
• Bottom safe area padding
• Glass effect with elevated background

---

Implementation Examples

Adding a New Feature

1. Use TvModernCard or ChannelCard base
2. Extend with custom styling if needed
3. Follow spacing/animation guidelines
4. Test hover states on desktop, tap on mobile
5. Ensure text contrast >= 4.5:1

Color Customization

• Never override AppColors constants directly
• Use color.withOpacity() for transparency
• Test on OLED displays for pure black background
• Avoid colors outside the defined palette

Custom Animations

• Always import AppTheme.durationMd and curveDefault
• Keep animations under 600ms unless loading indicator
• Use AnimatedScale, FadeTransition over custom controllers
• Test at 60fps on low-end devices

---

Performance Tips

1. Image Loading: Use CachedNetworkImage with placeholder
2. Scroll Performance: Enable repaint boundaries on large lists
3. Animations: Use SingleTickerProviderStateMixin for complex animations
4. Memory: Dispose controllers in dispose() method
5. Rendering: Avoid nested LayoutBuilders in scrollable areas

---

Accessibility

• Text Contrast: All text must meet WCAG AA (4.5:1)
• Touch Targets: 48x48px minimum on mobile
• Focus States: Always visible with 2px border or scale change
• Semantic HTML: Use proper widget hierarchy
• Tooltips: Always add for icon-only buttons

---

Export & Integration

Update main.dart

import 'package:flutter/material.dart';
import 'lib/core/theme/app_theme.dart';
import 'lib/mobile/theme/mobile_theme.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'XtremFlow',
      theme: AppTheme.darkTheme,
      home: const HomePage(),
    );
  }
}

Use Across App

// Colors
Container(color: AppColors.primary)

// Spacing
Padding(padding: EdgeInsets.all(AppTheme.spacing16))

// Animations
Duration animDuration = AppTheme.durationMd;
Curve animCurve = AppTheme.curveDefault;

---

Future Enhancements

• Implement animations library for transitions
• Add haptic feedback for interactions
• Create dark/light theme toggle
• Implement material motion guide (motion curves)
• Add accessibility scanner integration
• Create Storybook/documentation UI

---

Design System Version: 3.0 Projector Noir Last Updated: 2026-06-10 Status: Production Ready OK