design: formalize design-token spec + component standards docs #277

Summary

The Titen web dashboard needs a written design-token spec — the single source of truth for colors, spacing, type, radii, shadows, motion, and z-index — plus a component standards doc that declares which components are canonical. The token layer itself (Hallmark/Cobalt, OKLCH, hue 260) is GOOD and stays; this effort formalizes it, fixes its leaks, and closes the dual-system era.

Content

web/design/TOKENS.md:

• Layer map: primitive (--color-paper|rule|ink|accent…) → semantic aliases (--color-bg|border|danger…, shadcn mapping --background|--primary…) → component tokens (--form-*, --table-*, --sidebar-*).
• OKLCH recipe: hue 260 anchored; semantic hues: success 145, warning 85, error 25, info 260; ink/text = very low chroma (≤0.008) on the anchor hue.
• Rules: no hex fallbacks; no raw hex/palette classes in markup; semantic aliases are the API for pages; primitives only for building aliases/tokens.
• Decisions to record: --radius-full alias vs --radius-pill; names for --color-bg-subtle / --color-accent-subtle; the shadcn-name ↔ token mapping table.

web/design/COMPONENT-STANDARDS.md:

• Canonical: shadcn Button (variant matrix incl. destructive/success needs), Field+Input+Select+Switch for forms, Dialog/AlertDialog, Badge via StatusBadge, shared EmptyState, DataTable.
• Toast contract: success=polite status, error=assertive alert + icon (synced with the toast issue).
• Loading contract: skeleton on any wait >150ms (ref StatSkeleton, DataTable skeleton rows); no bare "Loading…" text.
• Empty contract: shared EmptyState everywhere (title/desc/action/icon).
• Dialog contract: long content scrolls (.detail-body pattern); mobile full-bleed ≤30rem; destructive actions inside dialogs need explicit consequence copy.
• Icon contract: Lucide only; no emoji in chrome.
• Focus/motion contract: global instant :focus-visible ring; --dur-*/--ease-out tokens; reduced-motion respected.

Acceptance criteria

• Both docs exist and are linked from web/README.md.
• Every --color-*/--radius-*/--space-* token used in markup is defined in the spec (spot-check passes).
• Standards reference the 4 remaining UX-fix issues as their implementation base.

Source: Titen UX audit 2026-09-20 — "desain token baru + standar komponen reusable" workstream.