ai-video-admin-frontend/DESIGN.md

---
version: alpha
name: ai-video-admin-design
description: A dark developer-console admin surface for managing AI video assistants. The base canvas is deep navy (`#080b13`) with cool off-white ink (`#e9eef7`); brand voltage comes from a cyan-to-blue gradient accent and soft radial glow blooms — not pastel orbs. Inter carries all UI type at 400–700 weights. CTAs use the shadcn primary blue pill; secondary actions are dark outlined panels on layered navy surfaces. The system reads as a focused ops dashboard, not a marketing site.

colors:
  primary: "#2563eb"
  primary-active: "#1d4ed8"
  accent-cyan: "#22d3ee"
  accent-blue: "#60a5fa"
  accent-blue-strong: "#3b82f6"
  ink: "#e9eef7"
  body: "#9aa6bd"
  body-sub: "#7f8aa3"
  muted: "#5d6880"
  hairline: "#161d2c"
  hairline-soft: "#1b2233"
  hairline-strong: "#2a3550"
  hairline-node: "#273249"
  canvas: "#080b13"
  canvas-sidebar: "#0a0e17"
  canvas-panel: "#0d121d"
  surface-card: "#0f1521"
  surface-hover: "#151e30"
  surface-node: "#111827"
  on-primary: "#ffffff"
  on-accent-dark: "#04121a"
  on-dark: "#ffffff"
  gradient-cyan-start: "#22d3ee"
  gradient-blue-end: "#3b82f6"
  gradient-text-start: "#67e8f9"
  gradient-text-end: "#60a5fa"
  glow-blue: "rgba(46, 161, 255, 0.18)"
  glow-cyan: "rgba(34, 211, 238, 0.16)"
  stat-cyan: "#22d3ee"
  stat-blue: "#60a5fa"
  stat-violet: "#a78bfa"
  stat-emerald: "#34d399"
  semantic-error: "#f87171"
  semantic-success: "#34d399"

typography:
  display-xl:
    fontFamily: "'Inter', sans-serif"
    fontSize: 36px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.72px
  display-lg:
    fontFamily: "'Inter', sans-serif"
    fontSize: 32px
    fontWeight: 700
    lineHeight: 1.15
    letterSpacing: -0.64px
  title-md:
    fontFamily: "'Inter', sans-serif"
    fontSize: 20px
    fontWeight: 600
    lineHeight: 1.35
    letterSpacing: 0
  title-sm:
    fontFamily: "'Inter', sans-serif"
    fontSize: 18px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0
  body-md:
    fontFamily: "'Inter', sans-serif"
    fontSize: 15px
    fontWeight: 400
    lineHeight: 1.73
    letterSpacing: 0
  body-strong:
    fontFamily: "'Inter', sans-serif"
    fontSize: 15px
    fontWeight: 600
    lineHeight: 1.73
    letterSpacing: 0
  body-sm:
    fontFamily: "'Inter', sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0
  caption:
    fontFamily: "'Inter', sans-serif"
    fontSize: 12px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0
  caption-semibold:
    fontFamily: "'Inter', sans-serif"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0
  button:
    fontFamily: "'Inter', sans-serif"
    fontSize: 14px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: 0
  nav-link:
    fontFamily: "'Inter', sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0
  brand-label:
    fontFamily: "'Inter', sans-serif"
    fontSize: 14px
    fontWeight: 700
    lineHeight: 1.4
    letterSpacing: 0

rounded:
  none: 0px
  sm: 6px
  md: 8px
  lg: 10px
  xl: 12px
  xxl: 16px
  xxxl: 24px
  pill: 9999px
  full: 9999px

spacing:
  xxs: 4px
  xs: 8px
  sm: 12px
  base: 16px
  md: 20px
  lg: 24px
  xl: 32px
  xxl: 48px
  section: 64px

components:
  app-shell:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
  sidebar:
    backgroundColor: "{colors.canvas-sidebar}"
    textColor: "{colors.body}"
    borderColor: "{colors.hairline}"
    width: 252px
    width-collapsed: 76px
  topbar:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    borderColor: "{colors.hairline}"
    height: 81px
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.xl}"
    padding: 10px 16px
    height: 40px
  button-outline:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.body}"
    typography: "{typography.button}"
    rounded: "{rounded.xl}"
    borderColor: "{colors.hairline-soft}"
    padding: 10px 16px
    height: 40px
  button-accent-cyan:
    backgroundColor: "{colors.accent-cyan}"
    textColor: "{colors.on-accent-dark}"
    typography: "{typography.button}"
    rounded: "{rounded.xl}"
    padding: 10px 16px
    height: 40px
  nav-item:
    backgroundColor: transparent
    textColor: "{colors.body}"
    typography: "{typography.nav-link}"
    rounded: "{rounded.xl}"
    height: 44px
  nav-item-active:
    backgroundColor: "rgba(59, 130, 246, 0.15)"
    textColor: "{colors.accent-blue}"
  hero-band:
    backgroundColor: "{colors.canvas-panel}"
    textColor: "{colors.ink}"
    typography: "{typography.display-xl}"
    rounded: "{rounded.xxxl}"
    padding: 32px
  stat-card:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.xxl}"
    padding: 20px
  feature-card:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.ink}"
    typography: "{typography.title-sm}"
    rounded: "{rounded.xxl}"
    padding: 24px
  text-input:
    backgroundColor: "{colors.canvas-panel}"
    textColor: "{colors.on-dark}"
    typography: "{typography.body-md}"
    rounded: "{rounded.lg}"
    padding: 12px 16px
    borderColor: "{colors.hairline-soft}"
  badge-pill:
    backgroundColor: "rgba(34, 211, 238, 0.10)"
    textColor: "#67e8f9"
    typography: "{typography.caption-semibold}"
    rounded: "{rounded.pill}"
    padding: 4px 12px
  brand-icon:
    backgroundColor: "linear-gradient(135deg, {colors.gradient-cyan-start}, {colors.gradient-blue-end})"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.xxl}"
    size: 44px
  avatar:
    backgroundColor: "linear-gradient(135deg, {colors.gradient-cyan-start}, {colors.gradient-blue-end})"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.full}"
    size: 32px
---

## Overview

AI 视频助手管理台 reads as a focused dark ops dashboard for configuring and monitoring AI video assistants. The base canvas is deep navy `{colors.canvas}` (#080b13) holding cool off-white ink `{colors.ink}` (#e9eef7). Brand voltage is **chromatic and directional**: a cyan-to-blue gradient accent (`{colors.gradient-cyan-start}` → `{colors.gradient-blue-end}`) marks logos, avatars, and primary CTAs; soft radial blue/cyan glow blooms add depth behind hero panels — not pastel atmospheric orbs.

Type runs **Inter** at 400–700 across all surfaces. Headings are bold (700), labels semibold (600), body at 400. There is no display serif — the voice is utilitarian and developer-console.

CTAs split into three tiers: shadcn primary blue pill (`{component.button-primary}`), dark outlined panel (`{component.button-outline}`), and cyan solid for workflow-mode emphasis (`{component.button-accent-cyan}`). Layered navy surfaces (`#0a0e17` → `#0f1521` → `#0d121d`) create depth without heavy shadows.

**Key Characteristics:**
- Deep navy canvas, cool off-white ink. Blue/cyan gradient as brand accent.
- Layered surface stack: shell → sidebar → card → panel/input.
- Inter at 400–700 — no display serif, no weight-300 editorial voice.
- Radial glow blooms (blue/cyan) behind hero and workflow panels only.
- Rounded-xl (12px) for buttons and nav; rounded-2xl/3xl for cards and heroes.
- 81px header/sidebar-brand height; 32px page padding.

## Colors

### Brand & Accent
- **Primary** (`{colors.primary}` — #2563eb): shadcn primary blue — default CTA pill fill. Source: `oklch(0.55 0.22 255)`.
- **Primary Active** (`{colors.primary-active}` — #1d4ed8): Press/hover darkening on primary.
- **Accent Cyan** (`{colors.accent-cyan}` — #22d3ee): Workflow-mode CTA, status dots, glow accents. Tailwind `cyan-400`.
- **Accent Blue** (`{colors.accent-blue}` — #60a5fa): Active nav text, labels, stat icons. Tailwind `blue-400`.
- **Accent Blue Strong** (`{colors.accent-blue-strong}` — #3b82f6): Gradient end-stop, active states. Tailwind `blue-500`.

### Surface Stack (darkest → lightest)
- **Canvas** (`{colors.canvas}` — #080b13): App shell floor, topbar background.
- **Canvas Sidebar** (`{colors.canvas-sidebar}` — #0a0e17): Sidebar panel — one step lighter than shell.
- **Canvas Panel** (`{colors.canvas-panel}` — #0d121d): Recessed inputs, toggle rows, hero base under glow.
- **Surface Card** (`{colors.surface-card}` — #0f1521): Cards, outline buttons, dropdowns.
- **Surface Hover** (`{colors.surface-hover}` — #151e30): Hover state for outline buttons and interactive panels.
- **Surface Node** (`{colors.surface-node}` — #111827): Workflow step nodes.

### Hairlines
- **Hairline** (`{colors.hairline}` — #161d2c): Sidebar/topbar dividers, structural borders.
- **Hairline Soft** (`{colors.hairline-soft}` — #1b2233): Default card, input, and button borders.
- **Hairline Strong** (`{colors.hairline-strong}` — #2a3550): Hover border accent on cards and buttons.
- **Hairline Node** (`{colors.hairline-node}` — #273249): Workflow node outlines.

### Text
- **Ink** (`{colors.ink}` — #e9eef7): Headings, primary labels, input text.
- **Body** (`{colors.body}` — #9aa6bd): Nav links, descriptions, secondary copy.
- **Body Sub** (`{colors.body-sub}` — #7f8aa3): Sub-navigation items.
- **Muted** (`{colors.muted}` — #5d6880): Captions, placeholders, metadata.
- **On Primary** (`{colors.on-primary}` — #ffffff): Text on blue/cyan buttons and gradient icons.
- **On Accent Dark** (`{colors.on-accent-dark}` — #04121a): Text on solid cyan CTA buttons.

### Gradient & Glow (signature)
- **Gradient Cyan Start** (`{colors.gradient-cyan-start}` — #22d3ee): Brand icon/avatar gradient start.
- **Gradient Blue End** (`{colors.gradient-blue-end}` — #3b82f6): Brand icon/avatar gradient end.
- **Gradient Text Start** (`{colors.gradient-text-start}` — #67e8f9): Brand wordmark gradient start (`cyan-300`).
- **Gradient Text End** (`{colors.gradient-text-end}` — #60a5fa): Brand wordmark gradient end (`blue-400`).
- **Glow Blue** (`{colors.glow-blue}` — rgba(46,161,255,0.18)): Hero panel radial bloom.
- **Glow Cyan** (`{colors.glow-cyan}` — rgba(34,211,238,0.16)): Workflow panel radial bloom.

These appear as radial-gradient backgrounds behind hero/workflow sections and as box-shadow halos on status dots. Never as flat card fills.

### Stat Accents (dashboard metrics only)
- **Stat Cyan** (`{colors.stat-cyan}` — #22d3ee): Assistant count icon plate.
- **Stat Blue** (`{colors.stat-blue}` — #60a5fa): Session count icon plate.
- **Stat Violet** (`{colors.stat-violet}` — #a78bfa): Response time icon plate.
- **Stat Emerald** (`{colors.stat-emerald}` — #34d399): Resolution rate icon plate.

Each stat uses `{color}/10` opacity background with matching text color.

### Semantic
- **Success** (`{colors.semantic-success}` — #34d399): Trend badges, confirmation. Tailwind `emerald-400`.
- **Error** (`{colors.semantic-error}` — #f87171): Validation errors. shadcn destructive light mode.

### shadcn CSS Variables (globals.css)

The project also defines semantic tokens in `:root` / `.dark` via oklch. Key mappings:

| Token | Light | Dark |
|---|---|---|
| `--background` | white | near-black |
| `--foreground` | near-black | near-white |
| `--primary` | `oklch(0.55 0.22 255)` | `oklch(0.6 0.22 255)` |
| `--card` | white | `oklch(0.205 0 0)` |
| `--border` | light gray | white 10% |
| `--destructive` | red | lighter red |

Page components currently use hardcoded hex values above; shadcn tokens apply to base UI primitives (`Button`, `Select`, `Card` defaults).

## Typography

### Font Family
**Inter** is the primary UI font (`--font-sans`). **Geist Sans** and **Geist Mono** are loaded as fallbacks/utilities. No display serif.

### Hierarchy

| Token | Size | Weight | Line Height | Use |
|---|---|---|---|---|
| `{typography.display-xl}` | 36px | 700 | 1.1 | Page hero h1 |
| `{typography.display-lg}` | 32px | 700 | 1.15 | Section heads |
| `{typography.title-md}` | 20px | 600 | 1.35 | Card titles |
| `{typography.title-sm}` | 18px | 600 | 1.4 | Sub-section heads |
| `{typography.body-md}` | 15px | 400 | 1.73 | Default body |
| `{typography.body-strong}` | 15px | 600 | 1.73 | Emphasized body |
| `{typography.body-sm}` | 14px | 400 | 1.5 | Compact body |
| `{typography.caption}` | 12px | 400 | 1.4 | Metadata |
| `{typography.caption-semibold}` | 12px | 600 | 1.4 | Badges, trend pills |
| `{typography.button}` | 14px | 500 | 1.0 | Button labels |
| `{typography.nav-link}` | 14px | 400 | 1.4 | Sidebar nav |
| `{typography.brand-label}` | 14px | 700 | 1.4 | Sidebar brand name |

### Principles
- **Bold headings.** Page titles at 700 — this is an admin console, not editorial.
- **Semibold for labels.** Form labels and card titles at 600.
- **Tight tracking on display.** `-0.72px` on hero h1; body stays at 0 tracking.

## Layout

### Spacing System
- **Base unit:** 4px.
- **Tokens:** `{spacing.xxs}` 4px · `{spacing.xs}` 8px · `{spacing.sm}` 12px · `{spacing.base}` 16px · `{spacing.md}` 20px · `{spacing.lg}` 24px · `{spacing.xl}` 32px · `{spacing.xxl}` 48px · `{spacing.section}` 64px.
- **Page padding:** 32px horizontal (`px-8`), 28px vertical (`py-7`).

### Grid & Container
- Max content width: 1180px.
- Stat cards: 4-up grid at desktop.
- Sidebar: 252px expanded, 76px collapsed.

### Whitespace Philosophy
Compact ops-dashboard pacing. Cards sit 16–24px apart inside the main scroll area. Hero band gets generous internal padding (32px) with a radial glow occupying the top-left quadrant.

## Elevation & Depth

The system uses **layered navy surfaces + hairline borders**. Depth comes from surface color steps, not drop shadows.

| Level | Treatment | Use |
|---|---|---|
| Shell | `{colors.canvas}` (#080b13) | App background |
| Sidebar | `{colors.canvas-sidebar}` (#0a0e17) | Navigation panel |
| Card | `{colors.surface-card}` (#0f1521) | Content cards, buttons |
| Recessed | `{colors.canvas-panel}` (#0d121d) | Inputs, toggle rows |
| Hairline border | 1px `{colors.hairline-soft}` | Card/input outlines |
| Hover border | 1px `{colors.hairline-strong}` | Interactive hover accent |
| Radial glow | `{colors.glow-blue}` or `{colors.glow-cyan}` | Hero/workflow atmospheric depth |
| Gradient shadow | `shadow-cyan-500/30` | Brand icon elevation |

### Decorative Depth
- **Radial glow blooms** sit behind hero and workflow panels — blue for prompt mode, cyan for workflow mode.
- **Status dots** use colored glow halos: `box-shadow: 0 0 0 4px rgba(...,.16), 0 0 14px rgba(...,.35)`.

## Shapes

### Border Radius Scale

| Token | Value | Use |
|---|---|---|
| `{rounded.sm}` | 6px | Compact elements |
| `{rounded.lg}` | 10px | shadcn base (`--radius: 0.625rem`) |
| `{rounded.xl}` | 12px | Buttons, nav items, inputs |
| `{rounded.xxl}` | 16px | Stat cards, brand icon |
| `{rounded.xxxl}` | 24px | Hero bands, workflow panels |
| `{rounded.pill}` | 9999px | Trend badges, status pills |
| `{rounded.full}` | 9999px | Avatars |

## Components

### App Shell

**`app-shell`** — Background `{colors.canvas}`, text `{colors.ink}`. Flex row: sidebar left, main column right (topbar + scrollable content).

### Sidebar

**`sidebar`** — Background `{colors.canvas-sidebar}`, border-right `{colors.hairline}`, width 252px (76px collapsed). Brand block at top with `{component.brand-icon}` + gradient text label. Nav items at `{component.nav-item}` height 44px; active state uses `{component.nav-item-active}`.

### Top Bar

**`topbar`** — Background `{colors.canvas}`, border-bottom `{colors.hairline}`, height 81px. Right-aligned: Help button, notification bell, user avatar dropdown — all `{component.button-outline}` style.

### Buttons

**`button-primary`** — Blue pill. Background `{colors.primary}`, text `{colors.on-primary}`, rounded `{rounded.xl}`, height 40px.

**`button-outline`** — Dark panel with border. Background `{colors.surface-card}`, text `{colors.body}`, border `{colors.hairline-soft}`. Hover: background `{colors.surface-hover}`, text `{colors.ink}`, border `{colors.hairline-strong}`.

**`button-accent-cyan`** — Workflow-mode CTA. Background `{colors.accent-cyan}`, text `{colors.on-accent-dark}`, rounded `{rounded.xl}`.

### Hero & Panels

**`hero-band`** — Background `{colors.canvas-panel}` with `{colors.glow-blue}` radial gradient overlay. Rounded `{rounded.xxxl}`, border `{colors.hairline-soft}`, padding 32px. Contains brand icon, blue accent label, bold h1, body copy, and two CTAs.

**`stat-card`** — 4-up metric grid. Background `{colors.surface-card}`, rounded `{rounded.xxl}`, padding 20px. Icon plate uses stat accent colors at 10% opacity background.

### Forms

**`text-input`** — Background `{colors.canvas-panel}`, text white, placeholder `{colors.muted}`, border `{colors.hairline-soft}`, rounded `{rounded.xl}`.

**`badge-pill`** — Cyan-tinted pill for workflow status. Background cyan 10%, text cyan-300, rounded `{rounded.pill}`.

### Brand Elements

**`brand-icon`** — 44×44px rounded `{rounded.xxl}` with `linear-gradient(135deg, cyan-400, blue-500)`, white icon, `shadow-cyan-500/30`, inset `ring-white/20`.

**`avatar`** — 32×32px circle with same gradient, bold initial letter.

## Do's and Don'ts

### Do
- Use the layered navy surface stack for depth — don't flatten everything to one background.
- Use cyan-to-blue gradient for brand marks (logo, avatars) only.
- Use `{colors.accent-blue}` at 15% opacity for active nav backgrounds.
- Use `{rounded.xl}` for interactive controls; `{rounded.xxl}` / `{rounded.xxxl}` for containers.
- Use Inter at 700 for page titles, 600 for labels, 400 for body.

### Don't
- Don't introduce warm/off-white editorial palettes — this is a dark admin console.
- Don't use pastel gradient orbs — glows are blue/cyan radial blooms only.
- Don't use a display serif — Inter only.
- Don't use pill-shaped CTAs for primary actions — rounded-xl (12px) is the button geometry.
- Don't use saturated stat colors as primary CTAs — reserve `{colors.primary}` and `{colors.accent-cyan}` for actions.

## Responsive Behavior

### Breakpoints

| Name | Width | Key Changes |
|---|---|---|
| Mobile | < 640px | Stat cards 1-up; sidebar collapsed; user name hidden |
| Tablet | 640–1024px | Stat cards 2-up |
| Desktop | 1024–1280px | Stat cards 4-up; full sidebar |
| Wide | > 1280px | Content caps at 1180px |

### Touch Targets
- Nav items at 44px height.
- Primary buttons at 40px height (`size="lg"`).

### Collapsing Strategy
- Sidebar collapses to 76px icon-only via toggle button.
- Stat grid: 4-up → 2-up → 1-up.

## Iteration Guide

1. Focus on a single component at a time.
2. CTAs default to `{rounded.xl}`. Cards use `{rounded.xxl}` or `{rounded.xxxl}`.
3. Variants live as separate entries.
4. Use `{token.refs}` everywhere — never inline hex in new code (migrate existing hardcoded values over time).
5. Hover states: surface step up + border accent to `{colors.hairline-strong}`.
6. Inter 700 for display, 600 for labels, 400/500 for body and buttons.
7. Glow blooms scoped to hero/workflow panels only.

## Known Gaps

- Page components use hardcoded hex values; shadcn CSS variables exist but aren't fully wired to page-level surfaces yet.
- Light mode tokens exist in `:root` but the app renders dark-only (no `.dark` class toggle).
- Animation timings (glow pulse, sidebar collapse) out of scope.
- Form validation states beyond defaults not fully documented.