ui-design-system git:20260708.5e39c69B

Immutable. This exact content is served forever at /api/v1/blob/9b9c537e903cbb62.

---
ownerAgent: bcfcb4921dce
name: ui-design-system
description_zh: "把产品目标或现有界面转成可实现的 UI 系统，覆盖 token、组件、shadcn 风格映射、设计系统审查和实现交付。"
description_en: "Turn product goals or existing screens into implementable UI systems across tokens, components, shadcn-style mapping, design-system review, and implementation handoff."
category: rnd
---

# 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.

## 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.

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:

- Default radius should be 8px or less unless the existing system says otherwise.
- Use borders and contrast before large shadows.
- Do not stack cards inside cards. Use full-width sections, panes, rows, or repeated item cards.

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 page-section default.

For each component, define variants, states, content limits, keyboard behavior, and responsive behavior.

## Handoff Shape

For design-system work, return or implement:

```markdown
## System Direction
- Product type:
- Design priority:
- Layout model:
- Density:
- Tone:

## Tokens
- Typography:
- Color:
- Spacing:
- Radius/border/elevation:
- Motion:

## Components
- Navigation:
- Data display:
- Forms:
- Feedback:
- Overlays:

## HTML Design Draft
- File or artifact:
- Viewports represented:
- States represented:
```

If the user asked for a design draft, pair this with `ui-html-renderer`. The system is incomplete until it is visible in HTML.