senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/apps/web/docs/DESIGN_TOKENS.md
senke 34e1f41091 refactor: Phase 8 — Update docs, ESLint, Storybook config for SUMI 
- DESIGN_TOKENS.md: Complete rewrite to document --sumi-* token system
- APP_SHELL.md: Update layout shell docs (glass bg, backdrop-blur, z-index)
- DESIGN_DIRECTION.md: Update aesthetic direction to SUMI philosophy
- .storybook/preview.tsx: Remove deleted CSS imports, update bg colors
- eslint.config.js: Update color rule message from Kodo to SUMI tokens
- tailwind.config.ts: Fix comment referencing deleted design-tokens.css

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 02:15:11 +01:00

301 lines
10 KiB
Markdown
Raw Blame History

# Design Tokens — SUMI Design System
Source of truth: [`src/index.css`](../src/index.css). All `--sumi-*` variables are defined there. Do not create competing token files.
Theme switching uses `[data-theme="dark"]` (default, applied on `:root`) and `[data-theme="light"]` attributes.
---
## 1. Colors
### Backgrounds
| Token | Dark | Light | Role |
|-------|------|-------|------|
| `--sumi-bg-void` | `#0c0c0f` | `#f0ece4` | Deepest background |
| `--sumi-bg-base` | `#121215` | `#f6f3ed` | App background |
| `--sumi-bg-raised` | `#1a1a1f` | `#ffffff` | Cards, sidebar |
| `--sumi-bg-overlay` | `#222228` | `#ffffff` | Popovers, dropdowns |
| `--sumi-bg-hover` | `#2a2a31` | `#ede9e1` | Hover state |
| `--sumi-bg-active` | `#32323a` | `#e4e0d8` | Active/pressed state |
| `--sumi-bg-wash` | `#18181d` | `#f8f6f1` | Subtle wash area |
### Surfaces
| Token | Role |
|-------|------|
| `--sumi-surface-inset` | Inset/recessed areas |
| `--sumi-surface-subtle` | Subtle differentiation |
| `--sumi-surface-card` | Card backgrounds |
| `--sumi-surface-elevated` | Elevated panels |
### Text — Warm neutrals
| Token | Dark | Light | Role |
|-------|------|-------|------|
| `--sumi-text-primary` | `#f0ede8` | `#1a1816` | Primary content |
| `--sumi-text-secondary` | `#a8a4a0` | `#5c5854` | Secondary content |
| `--sumi-text-tertiary` | `#706c68` | `#8a8580` | Tertiary/hints |
| `--sumi-text-disabled` | `#4a4844` | `#b5b0aa` | Disabled state |
| `--sumi-text-inverse` | `#121215` | `#f0ede8` | Inverse (on accent bg) |
| `--sumi-text-link` | `#8baade` | `#4a6fa5` | Links |
### Borders
| Token | Role |
|-------|------|
| `--sumi-border-faint` | Barely visible dividers |
| `--sumi-border-default` | Standard borders |
| `--sumi-border-strong` | Emphasized borders |
| `--sumi-border-focus` | Focus rings |
| `--sumi-border-accent` | Accent-tinted borders |
### Pigments (accent colors)
4 pigments provide all accent color needs:
| Pigment | Token | Dark hex | Role |
|---------|-------|----------|------|
| **Indigo** | `--sumi-accent` | `#7c9dd6` | Primary accent, links, focus |
| **Vermillion** | `--sumi-vermillion` | `#d4634a` | Destructive, errors, live |
| **Sage** | `--sumi-sage` | `#7a9e6c` | Success, online, positive |
| **Gold** | `--sumi-gold` | `#c9a84c` | Warnings, achievements |
Each pigment has `-hover` and `-subtle` variants. Indigo also has `-active`, `-muted`, and `-emphasis`.
### Semantic aliases
| Token | Maps to |
|-------|---------|
| `--sumi-success` | `--sumi-sage` |
| `--sumi-warning` | `--sumi-gold` |
| `--sumi-error` | `--sumi-vermillion` |
| `--sumi-info` | `--sumi-accent` |
### shadcn/Radix mapping
Standard `--background`, `--foreground`, `--primary`, `--muted`, `--border`, etc. are all aliased to `--sumi-*` tokens in `index.css`. Use Tailwind classes (`bg-background`, `text-foreground`, `text-primary`, `text-muted-foreground`) as usual — they resolve to SUMI values.
**Do not** use raw Tailwind color palettes (slate, gray, zinc, etc.). Always use the semantic tokens.
---
## 2. Typography
### Font stacks
| Token | Font | Usage |
|-------|------|-------|
| `--sumi-font-body` | Inter | Body text (Tailwind `font-sans`) |
| `--sumi-font-heading` | Space Grotesk | Headings (Tailwind `font-heading`) |
| `--sumi-font-mono` | JetBrains Mono | Code (Tailwind `font-mono`) |
| `--sumi-font-serif` | Noto Serif JP | Decorative (Tailwind `font-serif`) |
### Type scale (`--sumi-text-*`)
| Token | Size | Tailwind class |
|-------|------|----------------|
| `--sumi-text-4xl` | 2.25rem | `text-4xl` |
| `--sumi-text-3xl` | 1.875rem | `text-3xl` |
| `--sumi-text-2xl` | 1.5rem | `text-2xl` |
| `--sumi-text-xl` | 1.25rem | `text-xl` |
| `--sumi-text-lg` | 1.125rem | `text-lg` |
| `--sumi-text-md` | 1rem | — |
| `--sumi-text-base` | 0.875rem | `text-sm` |
| `--sumi-text-sm` | 0.8125rem | — |
| `--sumi-text-xs` | 0.75rem | `text-xs` |
### Utility classes (Tailwind-friendly)
| Class | Definition |
|-------|------------|
| `.text-display` | `text-4xl font-bold tracking-tight` |
| `.text-heading-1` | `text-3xl font-semibold tracking-tight` |
| `.text-heading-2` | `text-2xl font-semibold` |
| `.text-heading-3` | `text-xl font-medium` |
| `.text-heading-4` | `text-lg font-medium` |
| `.text-body-lg` | `text-base leading-relaxed` |
| `.text-body` | `text-sm leading-relaxed` |
| `.text-caption` | `text-xs text-muted-foreground` |
| `.text-label` | `text-xs font-medium uppercase tracking-wider text-muted-foreground` |
### SUMI typography classes (token-driven)
`.sumi-display`, `.sumi-h1` through `.sumi-h4`, `.sumi-body-lg`, `.sumi-body`, `.sumi-body-sm`, `.sumi-caption`, `.sumi-label`, `.sumi-mono` — these use `--sumi-*` variables directly for font-size, weight, line-height, and letter-spacing. Use these for finer control over the SUMI type scale.
### Visual hierarchy (recommended usage)
| Role | Class | Context |
|------|-------|---------|
| Page title | `.text-heading-1` / `.text-display` | H1 |
| Section title | `.text-heading-2` / `.text-heading-3` | H2, H3 |
| Label / metadata | `.text-label` / `text-sm` | Field labels |
| Body | `.text-body-lg` / `.text-body` | Running text |
| Caption | `.text-caption` | Timestamps, legends |
Use `text-foreground` for primary info, `text-muted-foreground` for secondary.
---
## 3. Spacing
**Base grid: 4px.** Use the standard Tailwind spacing scale (`gap-*`, `p-*`, `m-*`, `space-*`).
SUMI spacing tokens in `index.css` (for reference — prefer Tailwind classes):
| Token | Value |
|-------|-------|
| `--sumi-space-0-5` | 2px |
| `--sumi-space-1` | 4px |
| `--sumi-space-1-5` | 6px |
| `--sumi-space-2` | 8px |
| `--sumi-space-3` | 12px |
| `--sumi-space-4` | 16px |
| `--sumi-space-5` | 20px |
| `--sumi-space-6` | 24px |
| `--sumi-space-8` | 32px |
| `--sumi-space-10` | 40px |
| `--sumi-space-12` | 48px |
| `--sumi-space-16` | 64px |
| `--sumi-space-20` | 80px |
Layout gaps: `--layout-gap` (16px), `--layout-gap-sm` (12px), `--layout-gap-lg` (24px).
---
## 4. Radius
| Token | Value | Usage |
|-------|-------|-------|
| `--sumi-radius-xs` | 2px | Badges, tags |
| `--sumi-radius-sm` | 4px | Buttons, inputs |
| `--sumi-radius-md` | 6px | Cards (default `--radius`) |
| `--sumi-radius-lg` | 12px | Panels, dialogs |
| `--sumi-radius-xl` | 16px | Large cards |
| `--sumi-radius-2xl` | 20px | Hero sections |
| `--sumi-radius-full` | 9999px | Pills, avatars |
Tailwind mapping: `rounded-sm` → `--sumi-radius-sm`, `rounded-md` → `--sumi-radius-md`, etc.
---
## 5. Shadows
Defined in `:root` and overridden in `[data-theme="light"]`.
| Token | Role |
|-------|------|
| `--sumi-shadow-xs` | Subtle elevation |
| `--sumi-shadow-sm` | Buttons, small cards |
| `--sumi-shadow-md` | Tooltips, dropdowns |
| `--sumi-shadow-lg` | Cards, panels |
| `--sumi-shadow-xl` | Modals, dialogs |
| `--sumi-shadow-2xl` | Full overlays |
| `--sumi-shadow-glow` | Focus ring glow (Indigo-tinted) |
| `--sumi-shadow-glow-lg` | Large ambient glow |
### Glass effect
| Token | Value |
|-------|-------|
| `--sumi-glass-bg` | Semi-transparent bg |
| `--sumi-glass-border` | Subtle glass border |
| `--sumi-glass-blur` | 12px blur |
Classes: `.glass` / `.sumi-glass` apply all three properties + `backdrop-filter`.
---
## 6. Z-Index
| Token | Value | Usage |
|-------|-------|-------|
| `--sumi-z-base` | 0 | Default layer |
| `--sumi-z-raised` | 10 | Raised content |
| `--sumi-z-dropdown` | 100 | Dropdown menus |
| `--sumi-z-sticky` | 200 | Sticky headers, player |
| `--sumi-z-overlay` | 300 | Overlays |
| `--sumi-z-modal` | 400 | Modals |
| `--sumi-z-popover` | 500 | Popovers |
| `--sumi-z-toast` | 600 | Toast notifications |
| `--sumi-z-tooltip` | 700 | Tooltips |
| `--sumi-z-max` | 999 | Absolute top layer |
---
## 7. Motion
### Durations
| Token | Value | Usage |
|-------|-------|-------|
| `--sumi-duration-instant` | 75ms | Immediate feedback |
| `--sumi-duration-fast` | 150ms | Hover, focus, color changes |
| `--sumi-duration-normal` | 200ms | Sidebar, modals, transforms |
| `--sumi-duration-slow` | 300ms | Complex transitions |
| `--sumi-duration-slower` | 500ms | Page-level transitions |
### Easings
| Token | Curve | Usage |
|-------|-------|-------|
| `--sumi-ease-default` | `cubic-bezier(0.25, 0.1, 0.25, 1)` | General purpose |
| `--sumi-ease-out` | `cubic-bezier(0.33, 1, 0.68, 1)` | Enter / appear |
| `--sumi-ease-in` | `cubic-bezier(0.32, 0, 0.67, 0)` | Exit / leave |
| `--sumi-ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | Symmetric transitions |
| `--sumi-ease-bounce` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Playful bounce |
| `--sumi-ease-spring` | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | Spring feel |
### Composite transition tokens
| Token | Animates |
|-------|----------|
| `--sumi-transition-colors` | color, background-color, border-color |
| `--sumi-transition-opacity` | opacity |
| `--sumi-transition-transform` | transform |
| `--sumi-transition-shadow` | box-shadow |
`prefers-reduced-motion: reduce` is respected globally — all durations collapse to near-zero.
---
## 8. Layout Shell
Full reference: [APP_SHELL.md](APP_SHELL.md).
| Token | Value | Role |
|-------|-------|------|
| `--sumi-header-height` | 56px | Header height |
| `--sumi-sidebar-width` | 240px | Sidebar expanded |
| `--sumi-sidebar-collapsed` | 64px | Sidebar collapsed |
| `--sumi-player-height` | 80px | Player bar |
| `--sumi-max-width` | 1400px | App max width |
| `--sumi-max-width-content` | 1200px | Content max width |
| `--sumi-max-width-narrow` | 800px | Narrow content |
| `--sumi-max-width-prose` | 65ch | Prose text width |
### Layout primitives (utility classes)
| Class | Token | Value |
|-------|-------|-------|
| `.max-w-layout-content` | `--layout-content-max-width` | 100rem |
| `.min-h-layout-main` | `--layout-main-min-height` | calc(100vh - 4rem) |
| `.min-h-layout-page` | `--layout-page-min-height` | 37.5rem |
| `.min-h-layout-page-sm` | `--layout-page-min-height-sm` | 25rem |
| `.min-h-layout-story` | `--layout-story-decorator-min-height` | 12rem |
Modal/drawer height constraints, lyrics, chat, and stream heights — all defined in `index.css` with matching utility classes (`.max-h-layout-modal`, `.h-layout-chat`, etc.). See `index.css` `@layer utilities` section for the full list.
---
## 9. Exceptions (arbitrary values)
Arbitrary Tailwind values (`w-[...]`, `h-[...]`, `rounded-[...]`, `shadow-[...]`) are **forbidden** unless:
- SVG/canvas rendering (e.g., `text-[2px]` for chart axes)
- Third-party component markup you don't control
- Documented here or in a PR with justification
Add `eslint-disable` comment when an exception is necessary.
See also: [.cursorrules](../.cursorrules) for layout primitives and spacing rules.
Reference in a new issue View git blame Copy permalink