92f005895c
ui-system skill is no longer a placeholder. Full design-system and interaction-design interviews with branching, defaults, batched question clusters, and an 'accept default / skip' protocol so users move through fast when they have taste and patient when they don't. Design system interview covers: visual posture, color (with WCAG contrast verification before writing), typography, spacing, radii, shadows, density, visual motion, components, theming, and accessibility tokens (focus ring, hit targets). Interaction design interview covers: input model, state-surface declarations per action class, motion posture and triggers, breakpoints, i18n, four state postures (empty/loading/error/offline), time formatting, keyboard policy, optimistic-update strategy with rollback and conflict resolution, gestures, focus management, notification patterns, selection, and drag-and-drop. Reference banks for "make it look like Linear/Notion/Stripe/etc." translate well-known products into starting tokens — user still confirms each value, no silent invention. Templates expanded to hold the full output: - design-system/SKILL.md grew sections for accessibility tokens, density, dark-mode mapping, contrast verification, theming variants - design-system/tokens.ts now exports color (light + dark), typography (family/size/weight/line-height/letter-spacing), spacing + density- aware padding tokens, radii, shadows, motion (durations + easings), z-index scale, breakpoints, hit-target minimums - design-system/components.md gained anatomy/state/a11y coverage for 10 primitives plus an "adding a new component" workflow and a "patterns to avoid" list (nested cards, color-only meaning, etc.) - interaction-design/SKILL.md gained sections for optimistic updates, conflict resolution, gestures, focus management, notification patterns, selection/multi-select, and drag-and-drop Hard rules: never invent on the user's behalf; <TBD> instead. Verify contrast before writing color tokens. Always declare prefers-reduced- motion as honored. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
141 lines
4.8 KiB
Markdown
141 lines
4.8 KiB
Markdown
---
|
||
name: <SLUG>-design-system
|
||
description: Design system for the <PROJECT NAME> project. Color tokens, typography, spacing, radii, shadows, density, motion, accessibility tokens, and component vocabulary. Load and apply whenever building UI for this project — generating mocks, writing components, picking colors, configuring Tailwind, styling native screens, building themes, designing CSS, or making any visual decision. The canonical visual reference for this project; if anything visible is being touched, this skill should be in context. Pairs with <SLUG>-interaction-design.
|
||
---
|
||
|
||
# <PROJECT NAME> design system
|
||
|
||
> **Status: <draft | reviewed | locked>**
|
||
> Generated by Composer's `ui-system` phase. Re-running that phase
|
||
> updates this skill (with confirmation on overwrite).
|
||
|
||
## How to use this skill
|
||
|
||
When generating or editing UI for this project — a mock, a real
|
||
component, a theme, a CSS file — read this SKILL.md and `tokens.ts`
|
||
first, then use the tokens. Never hardcode visual values. Don't
|
||
introduce new components without proposing them in `components.md`.
|
||
|
||
Sidecar files in this skill directory:
|
||
- `tokens.ts` — machine-readable token export. Import in mocks/code.
|
||
- `components.md` — component vocabulary, anatomy, states.
|
||
|
||
## Visual posture
|
||
|
||
<!-- One-sentence north star. -->
|
||
|
||
<TBD: visual posture sentence>
|
||
|
||
## Color
|
||
|
||
### Brand
|
||
- **Primary**: `<#hex>` — <name>
|
||
- **Secondary** *(if any)*: `<#hex>` — <name>
|
||
|
||
### Neutrals
|
||
- **Tone**: <warm | cool | true>
|
||
- **Scale**: 50 / 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900 / 950
|
||
- See `tokens.ts` for hex values.
|
||
|
||
### Semantic
|
||
| Role | Light | Dark *(if dark mode)* |
|
||
|---|---|---|
|
||
| Success | `<#hex>` | `<#hex>` |
|
||
| Warning | `<#hex>` | `<#hex>` |
|
||
| Error | `<#hex>` | `<#hex>` |
|
||
| Info | `<#hex>` | `<#hex>` |
|
||
|
||
### Dark mode
|
||
- **Posture**: <yes | no | system-following>
|
||
- **Token mapping**: see `tokens.ts` `colorDark` (if applicable)
|
||
|
||
### Accessibility contrast
|
||
- **Target**: WCAG <AA | AAA>
|
||
- **Verified pairings** (against `neutral.50` light bg, `neutral.950` dark bg):
|
||
- body text: <ratio> — ✅
|
||
- UI components: <ratio> — ✅
|
||
- <flag any below threshold>
|
||
|
||
## Typography
|
||
|
||
- **Display family**: <name>, weights <list>
|
||
- **Body family**: <name | "(same as display)">, weights <list>
|
||
- **Mono family** *(if used)*: <name>
|
||
- **Scale base**: <px>, ratio <1.125 | 1.2 | 1.25 | 1.333 | 1.5>
|
||
- **Sizes**: see `tokens.ts` `fontSize` — xs / sm / base / lg / xl / 2xl / 3xl / 4xl
|
||
- **Line-height**:
|
||
- Tight (display): <value>
|
||
- Normal (body): <value>
|
||
- Relaxed (long-form): <value>
|
||
- **Letter-spacing** *(if customized)*: <values per size class>
|
||
|
||
## Spacing
|
||
|
||
- **Base unit**: <4px | 8px>
|
||
- **Scale (in base units)**: 0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24
|
||
- See `tokens.ts` `spacing` for px values.
|
||
|
||
## Radii
|
||
|
||
- **Posture**: <sharp | tight | medium | pillowy | mixed>
|
||
- `sm` <px> · `md` <px> · `lg` <px> · `pill` 9999px · `full` 9999px
|
||
|
||
## Shadows & elevation
|
||
|
||
- **Posture**: <flat | subtle | generous>
|
||
- Scale: `xs / sm / md / lg / xl` — see `tokens.ts` `shadow`
|
||
- (Or "no shadows in this system" if posture is flat — use borders for elevation hierarchy.)
|
||
|
||
## Density
|
||
|
||
- **Default**: <comfortable | cozy | compact>
|
||
- **Padding tokens**: see `tokens.ts` `padding` — `tight / default / loose`
|
||
- **Component impact**: list components whose default density differs from the global default.
|
||
|
||
## Visual motion
|
||
|
||
- **Default duration**: <ms> (token: `motion.duration.default`)
|
||
- **Default easing**: <named curve> (token: `motion.easing.standard`)
|
||
- **Reduced-motion fallback**: linear, instant where appropriate
|
||
|
||
Behavioral motion (when things animate, what triggers them) is in the
|
||
**interaction-design** skill, not here.
|
||
|
||
## Accessibility tokens
|
||
|
||
- **Focus ring**: <style — solid 2px brand at 60% opacity / etc.>
|
||
- **Focus ring color token**: `color.focus`
|
||
- **Focus offset**: <px>
|
||
- **Hit-target minimum**: 44×44px (mobile) / 32×32px (desktop pointer)
|
||
- **Contrast targets**: WCAG <AA | AAA> — body 4.5:1, UI 3:1
|
||
|
||
## Components
|
||
|
||
See `components.md` in this directory for the full vocabulary, anatomy,
|
||
and state coverage. The TL;DR list of primitives:
|
||
|
||
- **Button** (primary / secondary / ghost / destructive / link)
|
||
- **Input** (text / textarea / select / checkbox / radio / toggle)
|
||
- **Card / Surface**
|
||
- **Badge / Tag**
|
||
- **Avatar**
|
||
- **Tooltip**
|
||
- **Modal / Drawer / Popover** *(behavioral patterns in interaction-design skill)*
|
||
- **Tabs**
|
||
- **Menu / Dropdown**
|
||
- **Toast / Notification**
|
||
|
||
Plus project-specific components from `ia.md`: see `components.md`.
|
||
|
||
## Theming variants
|
||
|
||
- **Multi-brand / tenant theming**: <yes | no — typically no for v1>
|
||
- **Theme-switching mechanism** *(if applicable)*: <CSS variables / data-theme attr / etc.>
|
||
|
||
## TBD on return
|
||
|
||
<!-- Any phases that were skipped or had unanswered questions in the
|
||
ui-system interview. This is the worklist for the next pass. -->
|
||
|
||
- <TBD: ...>
|