caiwuzongzhang/DESIGN-TOKENS.md

# Design Tokens

This file maps the shipped dark visual system to its implementation source in `web/styles.css`. `DESIGN.md` is the portable design contract; the `:root` custom properties in `web/styles.css` are the runtime source of truth.

## Architecture

- Replace tokens and component definitions in place. Do not append a legacy-compatible theme override layer.
- Keep shared primitives in `:root`; keep component behavior in its existing semantic rule group.
- Business-component rules must not use `!important`.
- Only accessibility utilities (`.sr-only`, `[hidden]`) and `prefers-reduced-motion` enforcement may force priority.
- Do not restore warm-paper, white-card, cobalt-action, cream, or light-theme aliases. New code must consume the dark semantic tokens directly.
- Keep administrator and cashier portals as independent route-level surfaces even when they share tokens and component primitives.

## Typography

| Token | Value | Use |
| --- | --- | --- |
| `--font-ui` | `"Microsoft YaHei UI", "PingFang SC", "Noto Sans CJK SC", system-ui, sans-serif` | Chinese-first interface, navigation, fields, status, and headings |
| `--font-data` | `"Segoe UI", "Microsoft YaHei UI", system-ui, sans-serif` | Amounts, dates, ratios, account suffixes, and dashboard metrics |

Body type is `13px/1.55`. Page headlines use `clamp(26px, 3vw, 35px)` with `1.15` line height. The sign-in statement alone uses `clamp(38px, 5vw, 70px)`. Letter spacing stays at `0`; numeric evidence uses `font-variant-numeric: tabular-nums`.

## Color Primitives

### Canvas and Surfaces

| Token | Value | Use |
| --- | --- | --- |
| `--color-bg` | `#050505` | Continuous application canvas |
| `--color-bg-soft` | `#0a0a0a` | Soft near-black tonal alternative |
| `--color-nav` | `#0a0a0a` | Navigation frame fallback |
| `--color-surface` | `rgba(22, 22, 22, 0.82)` | Primary neutral graphite glass |
| `--color-surface-solid` | `#161616` | Opaque graphite fallback |
| `--color-surface-raised` | `#1c1c1c` | Raised or denser surface |
| `--color-surface-muted` | `rgba(255, 255, 255, 0.035)` | Quiet inset field and row treatment |

### Structure and Ink

| Token | Value | Use |
| --- | --- | --- |
| `--color-line` | `rgba(255, 255, 255, 0.09)` | Default glass, row, and field boundary |
| `--color-line-strong` | `rgba(255, 255, 255, 0.16)` | Hover, dialog, and transient boundaries |
| `--color-ink` | `#f2f7f4` | Primary headings, values, and action labels |
| `--color-ink-soft` | `#a6b0aa` | Operational body copy and secondary values |
| `--color-ink-muted` | `#89938d` | Metadata, helper copy, cutoff dates, and descriptions |

`--color-ink-muted` has a verified 5.73:1 contrast ratio on the primary graphite glass. Do not reduce it.

### Action and State

| Token | Value | Use |
| --- | --- | --- |
| `--color-primary` | `#37eb89` | Primary commands, focus, active icons, and confirmed progress |
| `--color-primary-strong` | `#70ffae` | Primary hover and high-emphasis command state |
| `--color-primary-dark` | `#08160e` | Text and icons on filled emerald controls |
| `--color-primary-wash` | `rgba(55, 235, 137, 0.11)` | Selected and highlighted emerald fields |
| `--color-positive` | `#37eb89` | Confirmed and successful state |
| `--color-positive-wash` | `rgba(55, 235, 137, 0.10)` | Confirmed-state background |
| `--color-warning` | `#ffbc52` | Review, incomplete, expiring, or recoverable caution |
| `--color-warning-wash` | `rgba(255, 188, 82, 0.11)` | Warning background |
| `--color-danger` | `#ff626d` | Blocked, overdue, failed, or destructive consequence |
| `--color-danger-wash` | `rgba(255, 98, 109, 0.11)` | Danger background |
| `--color-info` | `#66a8ff` | Neutral evidence guidance |
| `--color-info-wash` | `rgba(102, 168, 255, 0.11)` | Informational callout background |

Emerald is the only global action accent. Amber and red must always be accompanied by status text. Never use color alone to imply financial direction or accounting classification.

## Shape

| Token | Value | Use |
| --- | --- | --- |
| `--radius-sm` | `10px` | Compact identifiers and control-adjacent shapes |
| `--radius-md` | `16px` | Inset evidence, role cards, and compact grouped content |
| `--radius-lg` | `22px` | Panels, metric cards, alerts, dialogs, and account cards |
| `--radius-xl` | `28px` | Floating sidebar and sign-in form |

Observed component-specific radii remain local: fields use `11px`, primary controls `13px`, navigation rows `14px`, and statuses `8px`. Do not promote every one-off dimension into a global token.

## Depth

| Token | Value | Use |
| --- | --- | --- |
| `--shadow-panel` | `0 24px 70px rgba(0, 0, 0, 0.34), inset 0 1px rgba(255, 255, 255, 0.035)` | Sidebar, dialog, toast, and sign-in form |
| `--shadow-low` | `0 12px 32px rgba(0, 0, 0, 0.22), inset 0 1px rgba(255, 255, 255, 0.025)` | Panels, metrics, alerts, and account cards |
| `--shadow-glow` | `0 0 28px rgba(55, 235, 137, 0.12)` | Focused search and selected identity cues |

Glass surfaces pair background, boundary, blur, and shadow. Do not add shadow without the corresponding surface and border logic, and do not nest glass surfaces as decoration.

## Motion

| Token | Value | Use |
| --- | --- | --- |
| `--duration-fast` | `150ms` | Hover, focus, row, field, and button state changes |
| `--duration-standard` | `260ms` | Metric movement and mobile sidebar structure |
| `--ease-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | Entrances and structural transitions |

First load uses a `440ms` entrance with a `38ms` stagger capped at `260ms`. It runs once. Repeat navigation uses `180ms` and cancels any prior view animation before starting. Reduced-motion mode forces animations and transitions to `0.01ms`.

## Component Contracts

### Application Frame

- Desktop: 252px application column, 234px floating sidebar, 18px viewport offset, 78px sticky top bar.
- Main content: maximum width 1560px and 32px desktop inset.
- 1180px: sidebar compresses to an icon rail; four metrics become two columns.
- 900px: global search hides and complex ledgers recompose.
- 720px: 242px off-canvas sidebar, 64px top bar, 13px main inset, two-up metrics.
- 460px: metric cards gain height for wrapping; role selection becomes one column.

### Buttons and Fields

- Primary and secondary buttons have a 40px minimum height; icon buttons are stable 40px squares.
- Primary uses emerald fill with dark ink; secondary uses graphite wash with a hairline border.
- Fields have a 40px minimum height, 11px radius, dark inset fill, persistent visible label, and emerald focus treatment.
- Keyboard focus uses a two-pixel emerald outline with three-pixel offset.

### Metric Cards

- Exactly four prominent metrics lead each portal home view.
- Desktop minimum height is 142px with 20px padding; mobile minimum height is 128px with 15px padding, increasing at very narrow width.
- Interactive cards require native button semantics or equivalent role, focusability, and keyboard activation.
- A metric contains a label, stable numeric or status value, icon tile, and consequence line. Warning and danger color only the relevant signal.

### Panels, Ledgers, and Tables

- Major panels use graphite glass, a hairline border, 22px radius, low shadow, and backdrop blur.
- Use dividers and tonal rows inside a panel, not nested floating cards.
- Data tables retain a minimum width and horizontal scrolling so financial evidence is not discarded.
- Amounts and dates use tabular figures. Every balance view keeps its cutoff and unresolved amount visible.

### Status and Feedback

- Status chips are 23px high with 8px radius and `2px 8px` padding.
- Success, warning, danger, and neutral states always include explicit text.
- Dialogs use the strong boundary and panel shadow; mobile dialogs become full-screen with square outer corners.
- Toasts use the same raised graphite material as other transient layers.

## Change Checklist

1. Update the existing `:root` primitive instead of adding a duplicate alias.
2. Update every affected component state in its current rule group.
3. Verify administrator and cashier routes independently at desktop and mobile widths.
4. Verify focus visibility, text status, muted-text contrast, stable metric dimensions, and reduced motion.
5. Search `web/styles.css` for new business-rule `!important`; only approved accessibility and reduced-motion rules may remain.
6. Confirm no warm-paper, cobalt, cream, or light-theme override vocabulary has been introduced.