UI Design System

UI Design System

This skill does not have a look of its own. Its job is to take the user's design decisions — their palette, type scale, radius tiers, spacing rhythm — and (1) freeze them into one portable design-tokens.json the user owns, then (2) hold every UI they generate to that file. A generic UI helper has no memory: it picks a slightly different blue and a slightly different radius each session, and the product ends up looking assembled by five people. The durable value here is the user's own consistency, enforced deterministically.

Division of labor — what is a taste call vs a machine check

• Taste calls (which blue, serif vs sans, playful vs austere) belong to the user, reached through conversation — draw on ui-ux-pro-max for options if they want to explore. This skill never overrides those with a preferred style.
• Machine checks (is text readable on canvas, is the radius scale monotonic, does this component use a color that isn't in the system) are objective. Those are what the bundled scripts enforce — no opinion, just the user's own tokens applied consistently.

Workflow

1. Establish the tokens. If the user has existing code, harvest what it already uses — python scripts/design_tokens.py --extract src/ scans the codebase, clusters near-duplicate colors, and prints a tokens draft to rename and prune (the system already exists implicitly; you are writing it down). If starting fresh, converse to pin down choices (lean on ui-ux-pro-max for exploration), then record them — python scripts/design_tokens.py --template prints the annotated skeleton to fill. Either way the result is a design-tokens.json in the user's project. Schema lives in references/token_schema.md.
2. Validate the tokens are sound (objective, not aesthetic): python scripts/design_tokens.py --validate design-tokens.json. Checks schema completeness, WCAG contrast of each text color against its surface (< 4.5:1 body text is flagged), radius/spacing scales are monotonic, and spacing steps are consistent multiples of the base. Report failures; a pretty palette that fails contrast is not the user's friend.
3. Generate UI against the tokens. When building components (any target), every color/radius/space references a token, never a fresh literal. The target's syntax is the user's choice; the values come from their file.
4. Enforce consistency. python scripts/design_lint.py --tokens design-tokens.json --paths <files/dirs> scans generated code for color/radius literals that are NOT in the user's token set, and (per the user's declared convention) emoji-as-icon. Verdict first: violations file:line grouped by rule, then the fix routes to the token that should have been used.
5. Iterate on the system, not around it. If a screen genuinely needs a value the tokens don't have, that is a change to design-tokens.json (a considered addition the user makes), re-validated — not a one-off literal smuggled into one component.

Guardrails

• The token file is the user's, and its conventions govern. emoji_icons defaults to forbid (emoji render inconsistently across platforms, can't be tinted, carry no a11y label) but the user can set allow in their own file — the skill does not hardcode this preference.
• Never substitute a value the user didn't choose. If a token is missing, ask or flag it — do not quietly pick a color "that looks close."
• Contrast and scale checks are objective and not negotiable down for aesthetics: failing body-text contrast is an accessibility defect, reported as such regardless of how the palette looks.
• This skill enforces a system; it does not author one from nothing. With no user input to operationalize, the deliverable is the questions to ask, not a fabricated house style.

Bundled resources

• scripts/design_tokens.py — scaffolds (--template), extracts a draft from existing code (--extract PATH...), and validates (--validate) the user's design-tokens.json: schema, WCAG contrast, monotonic scales. --demo for a self-contained smoke test.
• scripts/design_lint.py — enforces generated code against the user's tokens (--tokens FILE --paths ...) across every dimension the file declares: off-system color literals (error; rounding tolerance + nearest-token suggestion) — recognized as #rrggbb, Color(red:g:b:), rgb()/rgba(), and Color(hex:"…") (the # is often omitted); chromatic system colors like Color.green/.red (warn) since they bypass the palette by definition (neutral white/black/gray are left alone); and off-system radius / font-size / spacing literals (warn; each linted only if that block exists in the tokens, each with a nearest-token hint). Emoji rule per the file's own convention. --demo for a self-contained smoke test. Exits non-zero on any error-severity violation, so it drops into a pre-commit hook or CI step — see references/methodology.md.
• references/token_schema.md — the platform-neutral design-tokens.json schema, with field meanings and target-mapping notes.
• references/methodology.md — how to establish tokens from user input (extract vs. converse), contrast/scale rationale, and how tokens map to each target's syntax.