| name | ui-design-principles |
| description | The design vocabulary for how a surface of this site should look — color roles and the CSS-variable palette, light/dark theming, typography and the prose column, control selection, spacing, responsive behavior, copy tone in the chrome, and accessibility intent. Design vocabulary only; implementation mechanics live in the component skill. |
| when_to_use | Use when deciding how a surface of this site should look — color roles, light/dark theming, typography, control selection, spacing, responsive behavior, or chrome copy. |
| user-invocable | false |
UI Design Principles
This skill owns how surfaces look, in design vocabulary. Construction mechanics belong to Component Guidelines; file placement belongs to Project Structure (both resolved via the AGENTS.md skill index). The visual manner follows poker.kohei.dev: a quiet, readable, single-column documentation site where content is the interface.
Color Roles
All colors come from the CSS variables in src/app/globals.css; both light and dark values are defined there and switch via prefers-color-scheme.
| Role | Variable | Used for |
|---|
| Background | --color-background | Page background |
| Surface | --color-surface | Code blocks, table headers, tooltip/popup fills |
| Border | --color-border | Hairline separators, table borders, popup outlines |
| Foreground | --color-foreground | Body text, headings, active nav |
| Muted foreground | --color-foreground-muted | Secondary text, inactive nav, footer |
| Accent | --color-accent | Links, focus outlines — interaction only |
| Accent foreground | --color-accent-foreground | Text/icon on accent-filled elements |
Guidelines:
- MUST use these roles via their variables; no literal color values in component styles.
- MUST define both light and dark values when adding a variable, and check the surface in both schemes.
- MUST reserve accent for interactive elements (links, focus); prose emphasis uses weight, not color.
- MUST pair any color that carries meaning with a non-color cue (wording, weight, icon, or underline).
Typography and Layout
- One centered content column,
--content-max-width (46rem) wide; nothing but the header and footer sits outside it.
- System font stacks (
--font-sans, --font-mono); no webfonts.
- MDX prose typography is owned by the
prose class (src/components/prose.module.css) — headings, lists, tables, code, and blockquotes are styled there once, not per page.
Guidelines:
- MUST keep body text at the base size (1rem/1.75); size changes express hierarchy only through the heading scale in the prose styles.
- MUST keep wide content (tables, code blocks) scrollable within the column rather than widening the page.
- SHOULD express hierarchy with spacing and weight before adding new visual elements (rules, boxes, backgrounds).
Controls and Interaction
| Decision shape | Control |
|---|
| Go somewhere | Link (accent color, underline on hover) |
| Site-level navigation | Header nav link with aria-current state |
| Supplementary hint on an icon | Base UI Tooltip |
| Anything requiring focus trapping / overlay | The matching Base UI primitive |
Guidelines:
- MUST have at most one accent-emphasized action per surface; everything else stays muted-foreground until hover.
- MUST show the interactive state trio (hover, focus-visible, current) on nav elements; focus uses the global accent outline.
Copy
Guidelines:
- MUST write chrome and UI copy in sentence case, short and factual ("Page not found", not "Oops! We couldn't find that page!").
- MUST keep the unofficial-fan-content disclaimer in the footer on every page (wording owned by Content Authoring Guidelines).
Responsive Behavior
Guidelines:
- MUST design mobile-first: the single column works from 320px up, with side padding from the layout, no horizontal page scroll.
- SHOULD verify new surfaces at a narrow (~375px) and a desktop (~1280px) width before calling them done.
