Adoption

Agent Skills are supported by leading AI development tools.

VS Code Gemini CLI GitHub Goose Amp Cursor Claude Code Letta OpenCode Claude OpenAI Codex Factory VS Code Gemini CLI GitHub Goose Amp Cursor Claude Code Letta OpenCode Claude OpenAI Codex Factory

jaykim88/design-system-construction

Name: design-system-construction
Author: jaykim88

plugins/frontend-toolkit/skills/design-system-construction/SKILL.md

npx skillsauth add jaykim88/claude-ai-engineering design-system-construction

Clean

TrivyContainer and dependency vulnerability scanner

Clean

SemgrepStatic code analysis for vulnerabilities

Clean

mcp-scan (Snyk)Model Context Protocol security validation

Skipped

Snyk (dep)Open source security scanning

Skipped

Socket.devSupply chain security analysis

Skipped

VirusTotalMulti-engine malware detection

Skipped

CrowdStrikeAdvanced threat intelligence

Skipped

OSV-ScannerOpen Source Vulnerability database check

Skipped

OWASP Dep-Check

Design System Construction

Purpose

Establish a reusable component library and design tokens so that UI consistency is enforced mechanically (via tokens and variants) rather than relied on by convention.

Universal — design tokens (colors, typography, spacing, radius), variant systems, 4-state stories (default/loading/error/empty), and "no arbitrary values" discipline apply to any UI framework. The default Procedure illustrates them with the Tailwind + cva + shadcn/ui idiom; the Other stacks section maps each to shadcn-vue / shadcn-svelte / spartan-ng and CSS-in-JS alternatives.

Procedure

Define design tokens in two tiers
- Primitive tier — the raw palette/scale (blue-500, gray-900, spacing units). Internal; components never reference these directly.
- Semantic tier — purpose-named aliases that reference primitives: primary, background, border, destructive, muted. Components consume only semantic tokens — this is what makes theming work: you remap the semantic→primitive layer once instead of editing every component.
- Pair every surface token with a foreground (primary / primary-foreground) and verify each pair meets WCAG contrast at definition time — contrast is a token-design decision, not a per-component audit deferred to later.
- Also: typography scale (font-family / size / line-height), spacing scale (4 / 8px base), radius (sm / md / lg / full) as named tokens.
- (CSS vars in :root — see Implementation)

1b. Make theming a token-map swap, not a component concern

Define the light and dark semantic maps — same semantic names, different primitive values; switch via a .dark class or prefers-color-scheme
Because components reference only semantic tokens (step 1), adding dark mode needs zero component edits
On SSR, resolve the theme before first paint (inline script in <head>) to avoid a flash of the wrong theme (FOUC)

Apply a typed variant system when a component has 3+ variants
- Define size / intent / state axes
- Use a class-merge helper for conditional class composition (last-wins on conflicts)
- Document default variants explicitly
- (cva + cn() — see Implementation)
Adopt a component-primitive library you own the code of for common primitives (Button, Dialog, Form, Select, Toast)
- Copy-in, not an npm dependency — the source lands in your repo (e.g. components/ui/) so you can modify it freely
- You own the code, not a library — no version-lock, no upstream override fights
- A CLI that copies components in (and wires deps/config) beats manual copy-paste
- Make primitives extensible without forking: a polymorphic / asChild slot (render-as-another-element — e.g. a Button rendering an <a>), className passthrough merged last-wins, forwarded refs/props
- (shadcn CLI npx shadcn@latest add …; Radix Slot / asChild — see Implementation)
Write 4-state stories in a component workshop; run an a11y check on each
- Default — happy path
- Loading — pending / skeleton
- Error — invalid input or failed fetch
- Empty — no data
- Run an automated a11y check on every story
- (Storybook + a11y addon — see Implementation)
Eliminate arbitrary values
- Scan codebase (broader regex covers spacing, sizing, layout, color):
```
grep -rE '\b(w|h|min-w|min-h|max-w|max-h|p[xytrbl]?|m[xytrbl]?|gap|top|left|right|bottom|text|bg|border|fill|stroke|grid-cols|grid-rows)-\[' src/
```
- Replace each hit with a token or compound variant
- Document the exception when an arbitrary value is genuinely necessary
Document the system
- COMPONENTS.md listing shared components and their usage
- Variant matrix per component
Verify (validation loop)
- Re-run the arbitrary-value grep (step 5); loop until 0 (documented exceptions aside)
- Confirm every semantic surface/foreground pair meets WCAG contrast in both light and dark maps
- Toggle dark mode and confirm no component needed a per-component override (else a component is referencing a primitive — fix step 1)

Severity tiers

| Tier | Examples | Action SLA | |---|---|---| | Critical | A semantic color pair fails WCAG contrast (ships an inaccessible default); components reference primitive/raw values (blue-500) so dark mode is broken | Block release; fix immediately | | Major | Arbitrary values (w-[347px]) across many files; 3+ variants hand-rolled without a typed variant system; async component with no loading/error/empty story | Fix this sprint | | Minor | Missing story for a static component; undocumented default variants; token naming drift | Schedule within 2 sprints |

Before / After

Arbitrary value vs token + variant

// ❌ Arbitrary values — bypasses design system, untyped, hard to enforce consistency
<button className="w-[347px] h-[44px] bg-[#1a73e8] text-[14px] px-[16px]">
  Save
</button>

// ✅ Tokens + cva variant — typed, consistent, override-friendly
const buttonVariants = cva('inline-flex items-center justify-center', {
  variants: {
    size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6 text-lg' },
    intent: { primary: 'bg-primary text-primary-foreground', ghost: 'bg-transparent' },
  },
  defaultVariants: { size: 'md', intent: 'primary' },
});

<button className={cn(buttonVariants({ size: 'md', intent: 'primary' }), className)}>
  Save
</button>

Completion Criteria

[ ] Arbitrary Tailwind values = 0 (documented exceptions only)
[ ] Components reference semantic tokens only — no primitive/raw values (blue-500) in component code
[ ] Every semantic color pair (* / *-foreground) meets WCAG AA contrast in both light and dark maps
[ ] All shared components have Storybook stories
[ ] 4-state story coverage = 100% for components with async data
[ ] CVA variants used for any component with 3+ visual variations
[ ] Tokens defined as CSS variables for theme switching

Stop & Ask (AI must pause for user approval)

Before migrating arbitrary values (w-[347px]) across 10+ files — design intent may require slightly different tokens
Before introducing a new cva variant axis (e.g., adding density to all buttons) — coordinate with designer
Before replacing existing components with shadcn/ui equivalents — visual regression risk, designer review needed

Output

Tokens: tailwind.config.ts theme.extend + CSS variables in :root (one block per theme: light, dark)
Component library: components/ui/ with shadcn-style primitives, one file per component
Stories: <Component>.stories.tsx per component, 4 states (default / loading / error / empty) where applicable
Inventory: docs/COMPONENTS.md with table — component name / variants / file path / Storybook link
Migration log (paste into PR description): arbitrary values eliminated count, components migrated

Implementation

React + Next.js (default)

Tokens: primitive scale in Tailwind theme.extend; semantic aliases as CSS variables in :root (e.g. --primary: var(--blue-600)) so components reference bg-primary, never bg-blue-600
Theming: .dark class strategy with paired :root / .dark CSS-variable blocks; resolve theme in an inline <head> script to avoid FOUC (next-themes handles this on App Router)
Variants: class-variance-authority (cva)
Class merging: cn() helper (clsx + tailwind-merge)
Component library: shadcn/ui via npx shadcn@latest add <component> (you own the code); e.g. npx shadcn@latest add button dialog form select toast copies into components/ui/ (no npm dependency)
Polymorphism: Radix Slot via the asChild prop — shadcn primitives already expose it
Stories: Storybook + @storybook/addon-a11y

Other stacks

Vue / Nuxt: Tailwind tokens identical; variants via cva (works in Vue too) or vue-specific tailwind-variants; component library: shadcn-vue (port of shadcn/ui); Storybook with Vue 3 integration
SvelteKit: Tailwind tokens identical; tailwind-variants (cva-like API for any framework); component library: shadcn-svelte; Storybook 7+ supports Svelte
Angular: Tailwind tokens identical; CSS variables + Angular component library (e.g., spartan/ui — shadcn-like for Angular); Storybook supports Angular
CSS-in-JS alternatives: Vanilla Extract, Stitches, Panda CSS — all support token-based design systems with type safety
Universal anti-pattern: arbitrary values (w-[347px], text-[#1a2b3c]) — every framework that uses Tailwind suffers this; the grep pattern is framework-agnostic

Related skills

component-quality — extraction criteria for promoting components into the design system
accessibility-audit — design system must meet WCAG 2.2 AA out of the box

Reference

Key insight encoded: Split tokens into a primitive tier (raw palette) and a semantic tier (primary, background, …) that aliases it — components reference only semantic tokens, so theming/dark-mode is a one-map swap instead of a per-component edit. Bake WCAG contrast into the */*-foreground pairs at token-definition time. Variants belong in CVA (typed and composable); arbitrary values are a smell — promote to tokens or compound variants. The "ban arbitrary values" rule is a community practice (Vercel/Infinum handbooks), not in official docs — encode it as a project rule.

jaykim88/design-system-construction

plugins/frontend-toolkit/skills/design-system-construction/SKILL.md

Build or audit a Tailwind + cva + shadcn/ui design system with two-tier tokens, variants, theming, and 4-state Storybook stories. Use when starting a new project, addressing UI inconsistency, onboarding a designer, adding dark mode / theming, when arbitrary values (w-[347px]) accumulate, or when component patterns repeat across 2+ places. Not for component-level extraction decisions (use component-quality) or WCAG conformance auditing (use accessibility-audit).

development

Updated May 30, 2026

$ install --global

skillsauth

npx skillsauth add jaykim88/claude-ai-engineering design-system-construction

Install this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.

Security Scan Results

3 of 9 scanners reported clean

Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.

Scanners Passed

Scanners in report

Clean

TrivyContainer and dependency vulnerability scanner

95%

Clean

SemgrepStatic code analysis for vulnerabilities

95%

Clean

mcp-scan (Snyk)Model Context Protocol security validation

95%

Skipped

Snyk (dep)Open source security scanning

50%

Skipped

Socket.devSupply chain security analysis

50%

Skipped

VirusTotalMulti-engine malware detection

50%

Skipped

CrowdStrikeAdvanced threat intelligence

50%

Skipped

OSV-ScannerOpen Source Vulnerability database check

50%

Skipped

OWASP Dep-Check

50%

Last scanned: May 30, 2026, 7:52 AM111.1s1 file scanned

SKILL.md

name:: design-system-construction
description:: Build or audit a Tailwind + cva + shadcn/ui design system with two-tier tokens, variants, theming, and 4-state Storybook stories. Use when starting a new project, addressing UI inconsistency, onboarding a designer, adding dark mode / theming, when arbitrary values (w-[347px]) accumulate, or when component patterns repeat across 2+ places. Not for component-level extraction decisions (use component-quality) or WCAG conformance auditing (use accessibility-audit).
license:: MIT

Design System Construction

Purpose

Establish a reusable component library and design tokens so that UI consistency is enforced mechanically (via tokens and variants) rather than relied on by convention.

Procedure

Define design tokens in two tiers
- Primitive tier — the raw palette/scale (blue-500, gray-900, spacing units). Internal; components never reference these directly.
- Semantic tier — purpose-named aliases that reference primitives: primary, background, border, destructive, muted. Components consume only semantic tokens — this is what makes theming work: you remap the semantic→primitive layer once instead of editing every component.
- Pair every surface token with a foreground (primary / primary-foreground) and verify each pair meets WCAG contrast at definition time — contrast is a token-design decision, not a per-component audit deferred to later.
- Also: typography scale (font-family / size / line-height), spacing scale (4 / 8px base), radius (sm / md / lg / full) as named tokens.
- (CSS vars in :root — see Implementation)

1b. Make theming a token-map swap, not a component concern

Define the light and dark semantic maps — same semantic names, different primitive values; switch via a .dark class or prefers-color-scheme
Because components reference only semantic tokens (step 1), adding dark mode needs zero component edits
On SSR, resolve the theme before first paint (inline script in <head>) to avoid a flash of the wrong theme (FOUC)

Apply a typed variant system when a component has 3+ variants
- Define size / intent / state axes
- Use a class-merge helper for conditional class composition (last-wins on conflicts)
- Document default variants explicitly
- (cva + cn() — see Implementation)
Adopt a component-primitive library you own the code of for common primitives (Button, Dialog, Form, Select, Toast)
- Copy-in, not an npm dependency — the source lands in your repo (e.g. components/ui/) so you can modify it freely
- You own the code, not a library — no version-lock, no upstream override fights
- A CLI that copies components in (and wires deps/config) beats manual copy-paste
- Make primitives extensible without forking: a polymorphic / asChild slot (render-as-another-element — e.g. a Button rendering an <a>), className passthrough merged last-wins, forwarded refs/props
- (shadcn CLI npx shadcn@latest add …; Radix Slot / asChild — see Implementation)
Write 4-state stories in a component workshop; run an a11y check on each
- Default — happy path
- Loading — pending / skeleton
- Error — invalid input or failed fetch
- Empty — no data
- Run an automated a11y check on every story
- (Storybook + a11y addon — see Implementation)
Eliminate arbitrary values
- Scan codebase (broader regex covers spacing, sizing, layout, color):
```
grep -rE '\b(w|h|min-w|min-h|max-w|max-h|p[xytrbl]?|m[xytrbl]?|gap|top|left|right|bottom|text|bg|border|fill|stroke|grid-cols|grid-rows)-\[' src/
```
- Replace each hit with a token or compound variant
- Document the exception when an arbitrary value is genuinely necessary
Document the system
- COMPONENTS.md listing shared components and their usage
- Variant matrix per component
Verify (validation loop)
- Re-run the arbitrary-value grep (step 5); loop until 0 (documented exceptions aside)
- Confirm every semantic surface/foreground pair meets WCAG contrast in both light and dark maps
- Toggle dark mode and confirm no component needed a per-component override (else a component is referencing a primitive — fix step 1)

Severity tiers

Before / After

Arbitrary value vs token + variant

// ❌ Arbitrary values — bypasses design system, untyped, hard to enforce consistency
<button className="w-[347px] h-[44px] bg-[#1a73e8] text-[14px] px-[16px]">
  Save
</button>

// ✅ Tokens + cva variant — typed, consistent, override-friendly
const buttonVariants = cva('inline-flex items-center justify-center', {
  variants: {
    size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6 text-lg' },
    intent: { primary: 'bg-primary text-primary-foreground', ghost: 'bg-transparent' },
  },
  defaultVariants: { size: 'md', intent: 'primary' },
});

<button className={cn(buttonVariants({ size: 'md', intent: 'primary' }), className)}>
  Save
</button>

Completion Criteria

[ ] Arbitrary Tailwind values = 0 (documented exceptions only)
[ ] Components reference semantic tokens only — no primitive/raw values (blue-500) in component code
[ ] Every semantic color pair (* / *-foreground) meets WCAG AA contrast in both light and dark maps
[ ] All shared components have Storybook stories
[ ] 4-state story coverage = 100% for components with async data
[ ] CVA variants used for any component with 3+ visual variations
[ ] Tokens defined as CSS variables for theme switching

Stop & Ask (AI must pause for user approval)

Before migrating arbitrary values (w-[347px]) across 10+ files — design intent may require slightly different tokens
Before introducing a new cva variant axis (e.g., adding density to all buttons) — coordinate with designer
Before replacing existing components with shadcn/ui equivalents — visual regression risk, designer review needed

Output

Tokens: tailwind.config.ts theme.extend + CSS variables in :root (one block per theme: light, dark)
Component library: components/ui/ with shadcn-style primitives, one file per component
Stories: <Component>.stories.tsx per component, 4 states (default / loading / error / empty) where applicable
Inventory: docs/COMPONENTS.md with table — component name / variants / file path / Storybook link
Migration log (paste into PR description): arbitrary values eliminated count, components migrated

Implementation

React + Next.js (default)

Tokens: primitive scale in Tailwind theme.extend; semantic aliases as CSS variables in :root (e.g. --primary: var(--blue-600)) so components reference bg-primary, never bg-blue-600
Theming: .dark class strategy with paired :root / .dark CSS-variable blocks; resolve theme in an inline <head> script to avoid FOUC (next-themes handles this on App Router)
Variants: class-variance-authority (cva)
Class merging: cn() helper (clsx + tailwind-merge)
Component library: shadcn/ui via npx shadcn@latest add <component> (you own the code); e.g. npx shadcn@latest add button dialog form select toast copies into components/ui/ (no npm dependency)
Polymorphism: Radix Slot via the asChild prop — shadcn primitives already expose it
Stories: Storybook + @storybook/addon-a11y

Other stacks

Vue / Nuxt: Tailwind tokens identical; variants via cva (works in Vue too) or vue-specific tailwind-variants; component library: shadcn-vue (port of shadcn/ui); Storybook with Vue 3 integration
SvelteKit: Tailwind tokens identical; tailwind-variants (cva-like API for any framework); component library: shadcn-svelte; Storybook 7+ supports Svelte
Angular: Tailwind tokens identical; CSS variables + Angular component library (e.g., spartan/ui — shadcn-like for Angular); Storybook supports Angular
CSS-in-JS alternatives: Vanilla Extract, Stitches, Panda CSS — all support token-based design systems with type safety
Universal anti-pattern: arbitrary values (w-[347px], text-[#1a2b3c]) — every framework that uses Tailwind suffers this; the grep pattern is framework-agnostic

Related skills

component-quality — extraction criteria for promoting components into the design system
accessibility-audit — design system must meet WCAG 2.2 AA out of the box

Reference

Key insight encoded: Split tokens into a primitive tier (raw palette) and a semantic tier (primary, background, …) that aliases it — components reference only semantic tokens, so theming/dark-mode is a one-map swap instead of a per-component edit. Bake WCAG contrast into the */*-foreground pairs at token-definition time. Variants belong in CVA (typed and composable); arbitrary values are a smell — promote to tokens or compound variants. The "ban arbitrary values" rule is a community practice (Vercel/Infinum handbooks), not in official docs — encode it as a project rule.

Related Skills

jaykim88/third-party-scripts

development

VerifiedTrustedCommunity

Audit and optimize third-party scripts — analytics, tag managers, chat widgets, embeds — with the right loading strategy, performance budget, facades, and CSP/consent controls. Use when adding a script, when TBT/INP regress, when a GDPR/CCPA consent requirement arises, or before shipping. Not for first-party bundle size (use bundle-optimization) or broad Core Web Vitals diagnosis (use rendering-performance).

SKILL.mdUpdated May 30, 2026

jaykim88/third-party-scripts

jaykim88/test-strategy

development

VerifiedTrustedCommunity

Apply the Testing Trophy (mostly integration tests with RTL + MSW, sparing E2E with Playwright) and set coverage thresholds. Use before new feature work, after bug fixes, when CI coverage falls below target, or when tests are flaky or break on every refactor. Not for wiring coverage gates + Playwright into the GitHub Actions matrix (use cicd-pipeline) or auditing WCAG a11y compliance (use accessibility-audit).

SKILL.mdUpdated May 30, 2026

jaykim88/test-strategy

jaykim88/tech-debt-management

development

VerifiedTrustedCommunity

Inventory and prioritize technical debt — TODO/FIXME/HACK, any usage, deprecated APIs, untested logic — with impact × effort matrix. Use at quarter start, before a refactoring sprint, when a new teammate joins, or when feature velocity slows. Not for actually paying down debt (use code-refactoring) or recording a migration approach (use decision-records) — this only inventories and prioritizes.

SKILL.mdUpdated May 30, 2026

jaykim88/tech-debt-management

jaykim88/state-management-decisions

development

VerifiedTrustedCommunity

Decision framework for choosing the right state location — URL, server cache, local component, or shared/global store. Use when state-sync bugs appear, prop drilling gets deep (3+ levels), filters/tabs lose state on reload, or quarterly review. Not for form state specifically (use form-ux) or when the state is actually server data (use api-caching-optimization).

SKILL.mdUpdated May 30, 2026

jaykim88/state-management-decisions

Download

For Claude Desktop. Download once, then upload the file in the app — no terminal needed.

Need help? View full Cowork setup guide →

Install manually

Choose your platform

# Clone the repo
git clone https://github.com/jaykim88/claude-ai-engineering.git

# Copy into Claude Code skills folder (global)
cp -r claude-ai-engineering/plugins/frontend-toolkit/skills/design-system-construction ~/.claude/skills/

Claude Code Skills — official skills path docs.

Repository

jaykim88/claude-ai-engineering

Compatible with

Claude Code

OpenAI Codex CLI

ChatGPT