RonanCodes/skills/design-system-create

Design System — Create

Lay down the four-layer contract that makes UI predictable:

1. CSS custom properties per theme — colour values live here, nowhere else
2. Tailwind @theme inline bridge — maps vars to utilities (bg-background etc.)
3. Typed tokens module (src/design-system/tokens.ts) — TYPOGRAPHY, SPACING, RADIUS, ELEVATION, Z
4. cva-based component variants — Button, Input, Card with state tables baked in
5. DESIGN_SYSTEM.md at repo root — rules, state tables, review checklist

The skill generates these in that order, and leaves the project with zero hex values in component files.

Usage

/ro:design-system-create                          # interactive — inspect repo, propose layout (showcase on by default)
/ro:design-system-create --primitives=button,input,card
/ro:design-system-create --showcase               # explicit opt-in (default anyway)
/ro:design-system-create --no-showcase            # skip the /styleguide route
/ro:design-system-create --showcase-only          # ONLY add /styleguide to an existing DS
/ro:design-system-create --dry-run                # show what would be written, don't write

Process

1. Inspect the project

Run in parallel:

• ls src/components/ui/ (shadcn layout) or ls src/components/ (alternative)
• cat tailwind.config.* 2>/dev/null || cat src/styles.css | head -40
• grep -rn '#[0-9a-fA-F]\{3,8\}' src/components/ 2>/dev/null | head -20 (hex leakage)
• grep -rn 'scale-\|rounded-\[' src/components/ 2>/dev/null | head -20 (likely DS violations)

Determine:

• Stack: Tailwind v3 vs v4, shadcn-ui vs custom, cva present or not, TypeScript vs JS
• Existing primitives: what Button/Input/Card already exists — augment, don't duplicate
• Themes: does the project have multiple themes? where do vars live?

If the project already has some of this (e.g. shadcn-ui scaffolded), the skill augments rather than overwriting. Never clobber an existing DESIGN_SYSTEM.md without asking.

2. Ask the user

Via AskUserQuestion, confirm:

1. Radius scale — what rounded-* bracket matches their brand? (default: sm/md/lg/xl/full, md = default)
2. Primary button shape — square rounded-md, or pill rounded-full?
3. Elevation style — border-only (NYT/modern flat), or borders + shadows (material)?
4. Active-state feedback — translate-y-px + darker bg (recommended), or fade only?
5. Primitives to generate — Button, Input, Card, Badge, Dialog (default: Button + Input + Card)
6. Showcase route — generate a /styleguide page that renders every token + primitive? (default: yes — it's the cheapest way to keep the spec honest). If Clerk is detected, the route is gated to superadmin + staff; otherwise it's dev-only (404 when import.meta.env.PROD)

3. Write the CSS layer

If Tailwind v4, ensure src/styles.css has:

@import 'tailwindcss';

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

The vars themselves live per-theme in src/lib/themes/css/*.css (or wherever the project keeps them). Do not inline concrete colours here.

4. Write src/design-system/tokens.ts

Typed, importable, autocomplete-friendly. Template:

export const TYPOGRAPHY = {
  display: 'text-3xl md:text-4xl font-bold tracking-tight',
  h1: 'text-2xl md:text-3xl font-bold tracking-tight',
  h2: 'text-xl font-semibold',
  h3: 'text-base font-semibold',
  body: 'text-sm leading-relaxed',
  bodyLg: 'text-base leading-relaxed',
  caption: 'text-xs text-muted-foreground',
  label: 'text-sm font-medium',
  mono: 'font-mono text-xs',
} as const
export type TypographyToken = keyof typeof TYPOGRAPHY

export const SPACING = {
  xs: '1', sm: '2', md: '3', lg: '4', xl: '6', xxl: '8',
} as const
export type SpacingToken = keyof typeof SPACING

export const RADIUS = {
  none: 'rounded-none',
  sm: 'rounded-sm',
  md: 'rounded-md',
  lg: 'rounded-lg',
  xl: 'rounded-xl',
  pill: 'rounded-full',
} as const

export const ELEVATION = {
  flat: 'border border-border',
  raised: 'border border-border shadow-sm',
  floating: 'border border-border shadow-md',
  overlay: 'border border-border shadow-xl',
} as const

export const Z = {
  base: 0, dropdown: 40, overlay: 50, dialog: 60, toast: 70, tooltip: 80,
} as const

5. Write / augment the primitives

Each primitive follows the same state-table contract. Example for Button:

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium " +
  "transition-all duration-150 disabled:pointer-events-none disabled:opacity-50 " +
  "outline-none focus-visible:ring-ring/50 focus-visible:ring-[3px] active:translate-y-px",
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90 active:bg-primary/80',
        destructive: 'bg-destructive text-white hover:bg-destructive/90 active:bg-destructive/80',
        outline: 'border bg-background hover:bg-accent hover:text-accent-foreground active:bg-accent/80',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80 active:bg-secondary/70',
        ghost: 'hover:bg-accent hover:text-accent-foreground active:bg-accent/80',
        link: 'text-primary underline-offset-4 hover:underline active:text-primary/80',
      },
      size: {
        default: 'h-9 px-4 py-2',
        xs: 'h-6 gap-1 px-2 text-xs',
        sm: 'h-8 gap-1.5 px-3',
        lg: 'h-10 px-6',
        icon: 'size-9',
      },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  },
)

Invariants the generated variants enforce:

• Radius in the base class only — never per-variant, never per-state
• Every variant defines hover + active + (via base) disabled + focus
• Active is momentary: bg darkens, translate-y-px — never scales up
• Focus ring is the same everywhere

Mirror this for Input (hover border-foreground/30, focus-visible border-ring + ring, disabled opacity-50) and Card (Flat/Raised/Floating/Overlay elevation tiers).

6. Write DESIGN_SYSTEM.md

Root of the repo. Must include:

1. Source of truth table — where colours/tokens/variants live, and the change flow
2. Core rules — the six non-negotiable rules from the canonical spec (see below)
3. Per-primitive sections — variant → intent mapping + state table + sizing
4. Typography + Spacing — token names and when to use them
5. Interaction patterns — Toggle vs Active (critical, often confused)
6. Review checklist — the one-page list reviewers scan
7. When to deviate — the escape hatch with guardrails

The six core rules (lift verbatim unless the project has a well-reasoned deviation):

1. Radius is a property of the element, not the state. A button's rounded-md must be identical in rest, hover, active, focus, disabled.
2. Active means pressed, not emphasised. The active state is the momentary look during mouse-down: subtly darker or inset. Never use scale-110 or a larger ring for active — that says "emphasised", which is a different concept (toggle).
3. Every variant must define rest + hover + active + focus-visible + disabled. Missing a state = dead feel in that state.
4. Focus ring is always the same. 3px, ring-ring/50, outline-none. Don't customise per variant.
5. Colour comes from tokens, never from hex. If you need a colour the theme doesn't have, add a token; don't inline.
6. One radius scale. rounded-sm (badges), rounded-md (buttons/inputs), rounded-lg/xl (cards), rounded-full (pills). No rounded-[7px] one-offs.

7. Styleguide route (default-on)

Emit a /styleguide page that renders every token and primitive so the system is auditable in-browser across themes. Default-on; use --no-showcase to skip.

Route path: /styleguide. Picked over /design-system and /showcase because it's the term frontend devs already search for, reads cleanly as a sidebar nav entry the day a real admin panel exists, and doesn't suggest the route is dev-only (it's role-gated in production by design, see below).

Where to write it:

• TanStack Router file-based: src/routes/styleguide.tsx (route = /styleguide)
• Next.js app router: app/styleguide/page.tsx
• React Router / Vite: src/pages/Styleguide.tsx + register in the router manually
• If the router can't be detected, abort this step and tell the user where to drop the file

Gating — role-based if Clerk is wired, dev-only otherwise:

Detect Clerk by looking for @clerk/tanstack-react-start in package.json AND a src/lib/auth/roles.ts file (the requireRole() helper emitted by /ro:clerk add-roles).

• If both are present (preferred): wire the route to requireRole('superadmin', 'staff'). Production-safe — only the superadmin email + Clerk org:staff members can view. Members and signed-out visitors get a 404 (not a redirect — don't leak the existence of admin routes).

  // src/routes/styleguide.tsx
  import { createFileRoute } from '@tanstack/react-router';
  import { createServerFn } from '@tanstack/react-start';
  import { requireRole } from '@/lib/auth/roles';
  
  const guardFn = createServerFn({ method: 'GET' }).handler(async () => {
    return await requireRole('superadmin', 'staff');
  });
  
  export const Route = createFileRoute('/styleguide')({
    beforeLoad: () => guardFn(),
    component: StyleguidePage,
  });
  

• If Clerk is wired but src/lib/auth/roles.ts is missing: prompt the user to run /ro:clerk add-roles first (one command, takes <30s), then emit the gated route. Do NOT silently skip the gate — that's the failure mode where an unguarded admin surface ships to production.

• If Clerk is not wired: fall back to a dev-only gate. The route 404s in production builds, renders in dev. This is the "scaffold without auth" path; the moment auth lands, swap to the role-gated form.

  // src/routes/styleguide.tsx — no-auth fallback
  import { createFileRoute } from '@tanstack/react-router';
  
  export const Route = createFileRoute('/styleguide')({
    beforeLoad: () => {
      if (import.meta.env.PROD) {
        throw new Response('Not Found', { status: 404 });
      }
    },
    component: StyleguidePage,
  });
  

Rules for the showcase file:

• Never link to it from public nav, footer, or sitemap. Linking from an internal admin panel (once one exists) is fine because that panel is itself gated.
• Use ONLY the project's own primitives (Button, Input, Badge, Card) and tokens (TYPOGRAPHY, RADIUS, ELEVATION, SPACING, Z) — no hand-rolled styles. The showcase is itself the first audit subject.
• Include a light/dark toggle at the top (mandatory) plus a multi-theme picker if src/lib/themes/index.ts exists. The toggle lives on-page so you can A/B both modes side-by-side without leaving the route.
• Every section pairs a live example with the token/variant name it uses, so copy-paste works

Required sections (in order):

1. Header — page title, current role badge (superadmin / staff / dev-mode), light/dark toggle (mandatory), multi-theme picker (if themes exist)
2. Colour tokens — render every semantic pair (bg-background/text-foreground, bg-card/text-card-foreground, etc.) as labelled swatches. Names match the @theme inline bridge.
3. Typography — one row per TYPOGRAPHY.* key, token name on the left, rendered sample on the right (use "The quick brown fox…")
4. Radius — a square for each RADIUS.* value with the key as caption
5. Elevation — a card for each ELEVATION.* tier
6. Buttons — variants × sizes — a row per variant (default, secondary, outline, ghost, link, destructive) with every size + a disabled + an icon-included example. The user physically clicks to verify hover/active/focus
7. Icon buttons — size-icon-xs/sm/default/lg in outline, plus destructive + a spinning loader
8. Toggle button — one Button with aria-pressed state toggled via local state, showing the recommended filled+bordered on-state
9. Inputs — default, disabled, aria-invalid, with-value (in a 2-col grid)
10. Badges — one per variant
11. Cards — two Card examples demonstrating CardHeader/Title/Description/Content + actions
12. Spacing scale — bars sized by each SPACING.* value with px readout
13. Z-index scale — labelled pills showing key + numeric value
14. Footer — link to DESIGN_SYSTEM.md (relative to repo host if known)

Why it earns its keep:

• New theme? Load /styleguide and eyeball every primitive in 30 seconds
• Adding a component? Copy the section pattern, stay consistent
• Audit blind spot? If a state looks wrong here, it looks wrong everywhere — first place reviewers check
• Onboarding a designer or staff member to a live deploy? Promote them to org:staff in Clerk, share the /styleguide link, no extra access needed

See docs/showcase-template.tsx in the repo where this skill was developed (connections-helper src/routes/styleguide.tsx) for a canonical reference implementation.

8. Report

Print what was written:

✅ Design system scaffolded

Created:
  DESIGN_SYSTEM.md                    — spec + review checklist
  src/design-system/tokens.ts         — typed tokens
  src/styles.css                      — @theme inline bridge (augmented)
  src/components/ui/button.tsx        — cva variants with state table
  src/components/ui/input.tsx         — matches button state treatment
  src/components/ui/card.tsx          — elevation tiers
  src/routes/styleguide.tsx           — /styleguide showcase (role-gated to superadmin+staff if Clerk wired, dev-only otherwise)

Next:
  1. Visit /styleguide in dev to verify the scaffold renders cleanly across themes (sign in as superadmin or an org:staff member if Clerk is wired)
  2. Run /ro:design-system-audit to find callers that need migrating
  3. Review DESIGN_SYSTEM.md — deviate where your brand demands it
  4. Commit the scaffold before starting migrations

shadcn vs custom (the canonical rule)

shadcn/ui is the default component layer for every app on the stack. A custom Tailwind-token component layer is acceptable ONLY when all three hold at once: the app is already token-driven (a tokens.ts + theme bridge exists and components read from it), its tests pass, and shadcn primitives cannot pixel-match the design without churn. In every other case, take shadcn and restyle it via tokens and cva variants. A rival component framework (Chakra, MUI, Mantine, Ant) is never acceptable — that is a different decision from "hand-rolled token components" and this skill's opinions do not transplant onto it (it aborts, see Safety).

The practical test: if you are reaching for custom because shadcn "feels heavy", that is not one of the three conditions. Custom is earned by a token-driven codebase where shadcn would fight the existing primitives, not chosen up front. Decided once here so it is not re-argued per session (lekkertaal, 2026-06-06).

Design decisions this skill bakes in

• Hybrid doc + code over JSON-only (Style Dictionary, DTCG) — for solo projects, Style Dictionary's ceremony isn't worth the price. The typed tokens module gives autocomplete without the build step.
• cva for variants over inline conditionals — it forces you to name the state table, and class ordering stays stable.
• @theme inline bridge for Tailwind v4 — maps a small number of semantic vars to a much larger utility surface for free.
• Rules, not laws — every rule in the spec has a "When to deviate" escape hatch, because a rigid system is one people route around.

Safety

• Never overwrite existing DESIGN_SYSTEM.md, tokens.ts, or primitives without explicit confirmation
• Don't edit CSS theme files — those are content; this skill only writes the utility bridge
• If the project uses a non-shadcn framework (Chakra, MUI), abort and tell the user — this skill's opinions don't transplant
• The skill writes files and commits nothing. Chain with /ro:commit for the "just scaffolded" commit

See also

• /ro:design-system-audit — run after scaffolding to find callers that still violate the rules
• /ro:frontend-design — broader UI review skill; this one is narrower and more actionable
• /ro:coding-principles — simplicity principles that informed the "rules not laws" choice
• /ro:clerk add-roles — emits the requireRole() helper that /styleguide consumes when Clerk is wired