| name | design-system |
| description | Apply the docs.plus design system (tokens, themes, elevation species, component state recipes) to any UI work. Use when the user mentions theme, colors, dark/light mode, borders, shadows, radius, styling, polish, cohesion, a new component/surface, or any visual change in apps/webapp. |
Design System
Working protocol for visual changes in apps/webapp. The source of truth is
.cursor/docs/design-system.md — tokens, themes, elevation species,
state language, and the per-component catalog. AGENTS.md owns behavioral invariants
(§UI And Theme, §Pad Workspace Surfaces, §Floating Surfaces And Modal Scrims, §Motion System).
Protocol
- Read the relevant doc sections first: tokens/themes for color work; elevation species for any
new or moved surface; the component's catalog row before editing its frame or states.
- Classify before styling. Every surface is one species: docked (L0), anchored (L1), modal (L2),
tooltip, card, control, sheet — reuse its canonical export or recipe verbatim. If no species
fits, extend the doc's elevation table first, then implement.
- Change color at the token layer. New colors/effects become
:root vars (+ both dark
overrides) in globals.scss, exposed via @theme aliases when Tailwind utilities are needed.
Components never carry hex or raw palette classes (brand allowlist and media-anchored
black/white overlays excepted — see the doc's Color policy).
- States are recipes, not improvisation: hover
base-200, active is-active
(primary-10% + primary ink), context-menu-active primary-15%/8%, focus
focus-visible:ring-2 ring-primary, unread error badge, disabled /40 ink. Cover both layers —
desktop and mobile variants of the same component share tokens, not necessarily geometry.
- Keep lockstep surfaces in sync in the same change: skeleton mirrors (SlugPageLoader /
ChatroomComposerSkeleton copy the real frame classes verbatim),
_document.tsx theme-color meta,
third-party CSS-var themings (em-emoji-picker, .documentKeywordInput), and the JS motion
mirror (utils/motion.ts).
- Verify in the browser — light + dark (+ dark-HC for pad/TOC), desktop ≥1280px and mobile —
never typecheck alone. Confirm the webapp dev port before driving it (not always 3000).
- Close the loop: update the doc's affected rows (and
AGENTS.md when doctrine moved) in the
same change; after substantive design-system work, run the memory updater.
Hard guardrails
- No new shadow/radius values; no shadows on docked light surfaces; scrims are black tokens only.
- No
*Classes.ts/*Styles.ts string modules; no second floating-surface language.
- No live regions inside
.ProseMirror; overlay species and motion tiers come from AGENTS.md.
- Never
next build against a live dev server (shared .next) — tsc --noEmit + the running app.
