ui-design-system

# ui-design-system

Use this skill when creating, extending, or auditing a product UI system. It adapts Better Design-style design-system discipline without requiring an external runtime package.

Pair this skill with `ui-design-contract` when the user provides references, screenshots, brand material, or asks for a reusable direction. The contract defines what the system must preserve; this skill turns it into tokens and components.

When `ui-reference-packs` selects a design-system pack, treat it as advisory style DNA. Translate it into the local token model and component map; do not copy named-brand assets, exact layouts, or proprietary product chrome.

Use public UI libraries and design systems as behavior references, not default dependencies. shadcn/ui, Radix, Headless UI, React Spectrum, Ant Design, MUI, Carbon, and similar systems can inform component states, keyboard behavior, density, and token discipline; only implement with one of them when the target app already uses it or the user explicitly asks.

## Design System Job

A UI system is not a moodboard. It must define reusable decisions that help the product ship:

- Who the product serves and what workflow the UI optimizes.
- What layout model organizes repeated work.
- Which component families exist, with variants and states.
- Which tokens drive typography, color, spacing, radius, borders, elevation, motion, and density.
- Which rules prevent one-off styling and component drift.
- How the design becomes HTML or target-app implementation.

For reusable systems, express the result in a `DESIGN.md`-compatible shape when useful:

- Visual theme and atmosphere.
- Color.
- Typography.
- Spacing and grid.
- Layout and composition.
- Components.
- Motion and interaction.
- Voice and brand.
- Anti-patterns.

## Context To Extract

Before designing, inspect or infer:

- Product domain: operational tool, creative app, developer tool, finance, education, commerce, content, or consumer.
- Main workflow: create, review, compare, monitor, configure, analyze, search, or collaborate.
- Existing UI framework and components.
- Selected reference pack, if any, plus rejected patterns from `ui-reference-packs`.
- For screenshots or image references: visible copy, page type, major regions, controls, repeated items, and what content is unknown.
- Current token source: CSS variables, Tailwind config, design-token files, component library, or ad hoc CSS.
- Navigation model: sidebar, top nav, split pane, command palette, tabs, wizard, canvas, or feed.
- Data density: sparse editorial, balanced product UI, or dense operational cockpit.
- Constraints: mobile, desktop, accessibility, brand, localization, dark mode, and real data variability.

For screenshot-based redesigns, the source screen is the contract. Preserve its workflow, content groups, and component families unless the user explicitly asks to change them. Do not replace a landing/input page with a dashboard, table, chart, sidebar, or operational cockpit simply because the user selected a broad page category.

## Token Model

Define tokens by role, not by vague color or size names.

For reusable systems, keep tokens close to the Design Tokens Community Group (DTCG) and Style Dictionary mental model: a token has a name, value, type, purpose, and optional mode. For example: `color.bg` (`color`, page background), `color.accent` (`color`, primary action/selected state), and `space.md` (`dimension`, default component gap). Do not require external build tooling unless the repo already uses it.

When writing CSS, export the same intent as custom properties such as `--color-bg`, `--color-accent`, `--space-md`, and `--radius-control`. This preserves portability without forcing Style Dictionary into every project.

Typography:

- `display`: only for true page or hero titles.
- `title`: screen or panel headings.
- `body`: readable paragraph or field content.
- `label`: form labels, metadata, table headers.
- `data`: numbers, metrics, monospace identifiers, code-like content.
- `caption`: secondary notes and timestamps.

Color:

- `bg`: page background.
- `surface`: panels, controls, rows, inputs.
- `surface-raised`: menus, popovers, dialogs.
- `text`: primary content.
- `text-muted`: metadata, placeholders, helper text.
- `border`: dividers and component outlines.
- `accent`: primary action or selection.
- `danger`, `warning`, `success`, `info`: semantic statuses only.

Spacing and density:

- Use a compact scale for operational products, usually 4/8/12/16/24/32.
- Reserve large whitespace for reading or marketing, not dashboards or repeated workflows.
- Keep table rows, forms, filters, and sidebars dense but scannable.

Shape and elevation:

- Derive radius from the existing system or Visual Thesis. Compact operational controls often benefit from restrained radius, while consumer, playful, or tactile products may justify softer geometry; do not force one house value across domains.
- Use borders and contrast before large shadows.
- Avoid stacking cards inside cards when grouping, spacing, panes, or rows communicate the same hierarchy more clearly. Nested surfaces are valid when they represent a real containment or interaction boundary.

Motion:

- Use motion to explain state changes, reveal hierarchy, or maintain spatial continuity.
- Avoid ambient motion in work tools unless it is part of the domain.

## Component Map

Map UI to components before styling:

- Navigation: sidebar, top bar, breadcrumbs, tabs, command menu.
- Action controls: primary button, secondary button, icon button, split button, menu item.
- Data controls: table, grid, list, filters, sort, search, pagination, batch actions.
- Forms: input, textarea, select, combobox, checkbox, radio, toggle, slider, stepper.
- Feedback: toast, inline alert, empty state, loading skeleton, error state, validation message.
- Surfaces: panel, drawer, modal, popover, tooltip, detail pane.
- Content: cards only for repeated items or framed tools, not as a