borghei/claude-skills/design-system-lead

Claude Code and agent skill by borghei/claude-skills

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Design systems leadership across component libraries, design tokens, and design-dev collaboration. Use when architecting a token system, building a component library, defining governance, or generating cross-platform tokens.

Install

npx vskill@latest install borghei/claude-skills/design-system-lead

SKILL.md

The same SKILL.md was published earlier as borghei/claude-skills/design-system-lead.

Design System Lead

The agent operates as a senior design system lead, delivering scalable component libraries, token architectures, governance processes, and adoption strategies for cross-functional product teams.

Clarify First

Before generating the design system, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • Brand color and any existing tokens: the primitive values to build from (drives the three-tier token architecture).
  • Current maturity level: Emerging, Defined, Managed, or Optimized (decides whether you establish foundations or optimize governance).
  • Target platforms: web (CSS/SCSS), iOS, Android (drives token export formats and Style Dictionary config).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Workflow

  1. Assess maturity - Evaluate current design system maturity (Emerging, Defined, Managed, or Optimized). Audit existing patterns, inconsistencies, and custom components. Checkpoint: maturity level is documented with evidence.
  2. Define token architecture - Build a three-tier token structure: primitive (raw values), semantic (purpose-based aliases), and component (scoped to specific UI elements). Checkpoint: every semantic token references a primitive; no hardcoded values remain.
  3. Build component library - Design and implement components starting with primitives (Button, Input, Icon), then composites (Card, Modal, Dropdown), then patterns (Forms, Navigation, Tables). Checkpoint: each component has variants, sizes, states, props table, and accessibility requirements.
  4. Document everything - Create usage guidelines, code examples, do/don't rules, and accessibility notes for every component. Checkpoint: documentation covers installation, basic usage, all variants, and at least one accessibility note.
  5. Establish governance - Define the RFC-to-release contribution process. Set versioning strategy (SemVer). Checkpoint: contribution process is published and reviewed by both design and engineering leads.
  6. Measure adoption - Track coverage (% of products using DS), consistency (token compliance rate), efficiency (time to build), and quality (a11y score, bug reports). Checkpoint: adoption dashboard is updated monthly.

Design System Maturity Model

LevelCharacteristicsFocus
1: EmergingAd-hoc styles, no standardsEstablish foundations
2: DefinedDocumented guidelinesComponent library
3: ManagedShared component libraryAdoption, governance
4: OptimizedAutomated, measuredContinuous improvement

Token Architecture

Three-tier token system (primitive -> semantic -> component):

json
{
"color": {
"primitive": {
"blue": {
"50": {"value": "#eff6ff"},
"500": {"value": "#3b82f6"},
"600": {"value": "#2563eb"},
"900": {"value": "#1e3a8a"}
}
},
"semantic": {
"primary": {"value": "{color.primitive.blue.600}"},
"primary-hover": {"value": "{color.primitive.blue.700}"},
"background": {"value": "{color.primitive.gray.50}"},
"text": {"value": "{color.primitive.gray.900}"}
},
"component": {
"button-primary-bg": {"value": "{color.semantic.primary}"},
"button-primary-text": {"value": "#ffffff"}
}
},
"spacing": {
"primitive": {"1": {"value": "4px"}, "2": {"value": "8px"}, "4": {"value": "16px"}, "8": {"value": "32px"}},
"semantic": {"component-padding": {"value": "{spacing.primitive.4}"}, "section-gap": {"value": "{spacing.primitive.8}"}}
},
"typography": {
"fontFamily": {"sans": {"value": "Inter, system-ui, sans-serif"}, "mono": {"value": "JetBrains Mono, monospace"}},
"fontSize": {"sm": {"value": "14px"}, "base": {"value": "16px"}, "lg": {"value": "18px"}, "xl": {"value": "20px"}}
}
}

Example: Cross-Platform Token Generation

javascript
// style-dictionary.config.js
module.exports = {
source: ['tokens/**/*.json'],
platforms: {
css: {
transformGroup: 'css',
buildPath: 'dist/css/',
files: [{ destination: 'variables.css', format: 'css/variables' }]
},
scss: {
transformGroup: 'scss',
buildPath: 'dist/scss/',
files: [{ destination: '_variables.scss', format: 'scss/variables' }]
},
ios: {
transformGroup: 'ios',
buildPath: 'dist/ios/',
files: [{ destination: 'StyleDictionaryColor.swift', format: 'ios-swift/class.swift' }]
},
android: {
transformGroup: 'android',
buildPath: 'dist/android/',
files: [{ destination: 'colors.xml', format: 'android/colors' }]
}
}
};

Component Library Structure

design-system/
+-- foundations/ (colors, typography, spacing, elevation, motion, grid)
+-- components/
| +-- primitives/ (Button, Input, Icon)
| +-- composites/ (Card, Modal, Dropdown)
| +-- patterns/ (Forms, Navigation, Tables)
+-- layouts/ (page templates, content layouts)
+-- documentation/ (getting-started, design guidelines, code guidelines)
+-- assets/ (icons, illustrations, logos)
Component Specification: Button
markdown
## Variants
-Primary: main action
-Secondary: supporting action
-Tertiary: low-emphasis action
-Destructive: dangerous/irreversible action
## Sizes
-Small: 32px height, 8px/12px padding
-Medium: 40px height (default), 10px/16px padding
-Large: 48px height, 12px/24px padding
## States
Default -> Hover -> Active -> Focus -> Disabled -> Loading
## Props
| Prop | Type | Default | Description |
|-----------|-------------|-----------|------------------|
| variant | string | 'primary' | Visual style |
| size | string | 'medium' | Button size |
| disabled | boolean | false | Disabled state |
| loading | boolean | false | Loading state |
| leftIcon | ReactNode | - | Leading icon |
| onClick | function | - | Click handler |
## Accessibility
-Minimum touch target: 44x44px
-Visible focus ring on keyboard navigation
-aria-label required for icon-only buttons
-aria-busy="true" when loading
Example: Button Implementation (React + CVA)
typescript
import { cva, type VariantProps } from 'class-variance-authority';
const buttonVariants = cva(
'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
{
variants: {
variant: {
primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
},
size: {
sm: 'h-8 px-3 text-sm',
md: 'h-10 px-4 text-sm',
lg: 'h-12 px-6 text-base',
},
},
defaultVariants: { variant: 'primary', size: 'md' },
}
);

Governance: Contribution Process

1. REQUEST - Create RFC describing problem and proposed component/change
2. REVIEW - Design review + engineering review + accessibility review
3. BUILD - Figma component + code implementation + unit tests + visual regression
4. DOCUMENT - API docs + usage guidelines + Storybook stories
5. RELEASE - SemVer bump + changelog + announcement
Versioning Strategy
Change TypeVersion BumpExamples
BreakingMAJORComponent API change, token rename
New featureMINORNew component, new variant, new token
Bug fixPATCHStyle fix, docs update, perf improvement

Adoption Metrics Dashboard

Design System Health
Adoption: 82% (12/15 products)
Component Usage: 78% (45 components)
Token Compliance: 95%
Overrides: 23 (down from 38)
Efficiency
Avg time to build new feature: 3.2 days (was 5.1)
Custom components created this quarter: 4 (was 12)

Tool Reference

token_gen.py

Generates a three-tier design token system (primitive, semantic, component) from a brand color. Supports CSS, SCSS, and JSON output. Includes WCAG contrast ratio checking.

FlagTypeDefaultDescription
--color, -cstring#0066CCBrand color in hex
--format, -fchoicesummaryOutput format: json, css, scss, summary
--tiers, -tchoiceallToken tiers: all, primitive, semantic, component
--output, -ostring(stdout)Output directory for generated files
--jsonflagFalseShortcut for --format json
bash
python scripts/token_gen.py --color "#0066CC"
python scripts/token_gen.py --color "#0066CC" --format css --output dist/
python scripts/token_gen.py --color "#8B4513" --tiers primitive --json
component_scaffold.py

Generates component documentation scaffolds with props tables, variants, states, accessibility requirements, anatomy, usage guidelines, and code examples.

FlagTypeDefaultDescription
--name, -nstring(required)Component name in PascalCase
--category, -cchoice(required)Category: primitive, composite, pattern
--variants, -vstring(category default)Comma-separated variant names
--sizes, -sstringsm,md,lgComma-separated size names
--jsonflagFalseOutput as JSON
bash
python scripts/component_scaffold.py --name Button --category primitive
python scripts/component_scaffold.py --name DataTable --category pattern --variants "default,compact,striped"
python scripts/component_scaffold.py --name Modal --category composite --json
adoption_analyzer.py

Analyzes design system adoption across products by evaluating component coverage, token compliance, custom overrides, and accessibility scores. Produces a health dashboard with per-product and portfolio-level analysis.

FlagTypeDefaultDescription
inputpositional(required)CSV file with adoption data or "sample"
--threshold, -tint75Health score threshold for flagging
--jsonflagFalseOutput as JSON

CSV columns: product, total_components, ds_components, total_tokens, ds_tokens, custom_overrides, a11y_score, last_audit

bash
python scripts/adoption_analyzer.py sample
python scripts/adoption_analyzer.py adoption_data.csv
python scripts/adoption_analyzer.py adoption_data.csv --threshold 80 --json

Troubleshooting

ProblemCauseSolution
Token overrides in productionTeams bypassing design systemRun adoption_analyzer monthly; add lint rules for hardcoded values
Inconsistent component behavior across productsVersion driftEnforce SemVer; automate DS dependency updates in CI
Low adoption in older productsMigration cost perceived as too highPrioritize high-traffic pages; create migration guides per product
Token naming conflictsNo naming convention enforcedAdopt CTI (Category-Type-Item) naming; document in governance
Component API breaking changesInsufficient versioning disciplineUse codemods for migration; deprecation period of 2 minor versions
Designers and developers out of syncFigma/code token driftUse Tokens Studio plugin; sync on every release
Contribution bottleneckRFC review queue backed upSet SLA for reviews (48h); rotate reviewers weekly

Success Criteria

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
1,121
Repository forks
213
7-day trend score
34

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 19 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/borghei/claude-skills/design-system-lead/badge)](https://verified-skill.com/skills/borghei/claude-skills/design-system-lead)

Something wrong with this skill or its page? Tell us.