Agent skill

design-systems

View SKILL.md on GitHub Repository
Stars 32
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/martinholovsky/claude-skills-generator/tree/main/skills/design-systems

SKILL.md

Design Systems Skill

yaml
name: design-systems-expert
risk_level: LOW
description: Expert in token-based theming, component APIs, design system architecture, and creating scalable design foundations
version: 1.0.0
author: JARVIS AI Assistant
tags: [design-system, tokens, theming, components, architecture]

1. Overview

Risk Level: LOW-RISK

Justification: Design systems produce CSS, design tokens, and component specifications without direct code execution or data processing.

You are an expert in design system architecture. You create scalable, maintainable design foundations with token-based theming, consistent component APIs, and clear documentation.

Core Expertise

  • Design token architecture
  • Component API design
  • Theme switching
  • Documentation systems
  • Version management

Primary Use Cases

  • Creating design system foundations
  • Building component libraries
  • Implementing theming systems
  • Design system documentation

2. Core Responsibilities

Fundamental Duties

  1. Token Architecture: Build scalable token hierarchies
  2. Component Design: Create consistent, composable components
  3. Theme Support: Enable multiple themes
  4. Documentation: Keep system well-documented

Design System Principles

  • TDD First: Write tests for tokens and components before implementation
  • Performance Aware: Optimize CSS delivery, minimize repaints
  • Single source of truth: Tokens define all values
  • Composability: Components combine simply
  • Consistency: Same patterns throughout
  • Extensibility: Easy to extend, hard to break

3. Technical Foundation

Token Hierarchy

┌─────────────────────────────────────┐
│       Semantic Tokens               │
│  (purpose-specific references)      │
│  --color-text-primary               │
│  --color-bg-surface                 │
│  --spacing-component                │
└──────────────┬──────────────────────┘
               │ references
┌──────────────▼──────────────────────┐
│       Core Tokens                   │
│  (raw design values)                │
│  --color-blue-500                   │
│  --space-4                          │
│  --font-size-base                   │
└─────────────────────────────────────┘

4. Implementation Patterns

4.1 Token Architecture

css
/* tokens/core.css - Raw values */
:root {
  /* Colors - Gray scale */
  --color-gray-50: #f9fafb;
  --color-gray-500: #6b7280;
  --color-gray-900: #111827;
  /* ... gray-100 through gray-800 */

  /* Colors - Blue scale */
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;

  /* Spacing (8px base): --space-0 through --space-16 */
  --space-4: 1rem;
  --space-6: 1.5rem;

  /* Typography */
  --font-size-base: 1rem;
  --font-weight-medium: 500;
  --line-height-normal: 1.5;

  /* Radii */
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;

  /* Shadows */
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
}
css
/* tokens/semantic.css - Purpose-specific */
:root {
  /* Background */
  --color-bg-primary: var(--color-white);
  --color-bg-secondary: var(--color-gray-50);

  /* Text */
  --color-text-primary: var(--color-gray-900);
  --color-text-secondary: var(--color-gray-600);

  /* Border & Interactive */
  --color-border-default: var(--color-gray-200);
  --color-interactive-primary: var(--color-blue-600);

  /* Component spacing */
  --spacing-component-md: var(--space-3);
  --spacing-component-lg: var(--space-4);
}

4.2 Theme Switching

css
/* themes/light.css */
:root,
[data-theme="light"] {
  --color-bg-primary: var(--color-white);
  --color-text-primary: var(--color-gray-900);
  --color-border-default: var(--color-gray-200);
}

/* themes/dark.css */
[data-theme="dark"] {
  --color-bg-primary: var(--color-gray-900);
  --color-text-primary: var(--color-gray-50);
  --color-border-default: var(--color-gray-700);
}
typescript
// Theme switcher (condensed)
function ThemeProvider({ children }: Props) {
  const [theme, setTheme] = useState<"light" | "dark">("light");

  useEffect(() => {
    const saved = localStorage.getItem("theme") as "light" | "dark" | null;
    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
    setTheme(saved || (prefersDark.matches ? "dark" : "light"));
  }, []);

  useEffect(() => {
    document.documentElement.dataset.theme = theme;
  }, [theme]);

  const toggle = () => {
    const next = theme === "light" ? "dark" : "light";
    setTheme(next);
    localStorage.setItem("theme", next);
  };

  return (
    <ThemeContext.Provider value={{ theme, toggle }}>
      {children}
    </ThemeContext.Provider>
  );
}

4.3 Component API Design

typescript
// Consistent prop patterns
interface ButtonProps {
  variant?: "primary" | "secondary" | "ghost" | "danger";
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
  loading?: boolean;
  children: ReactNode;
  onClick?: () => void;
}

function Button({ variant = "primary", size = "md", ...props }: ButtonProps) {
  return (
    <button
      className={cn("button", `button--${variant}`, `button--${size}`)}
      disabled={props.disabled || props.loading}
      onClick={props.onClick}
    >
      {props.children}
    </button>
  );
}

4.4 Composition Patterns

typescript
// Compound components
function Card({ children }: { children: ReactNode }) {
  return <div className="card">{children}</div>;
}
Card.Header = ({ children }) => <div className="card-header">{children}</div>;
Card.Body = ({ children }) => <div className="card-body">{children}</div>;
Card.Footer = ({ children }) => <div className="card-footer">{children}</div>;

// Usage: <Card><Card.Header>Title</Card.Header><Card.Body>...</Card.Body></Card>

4.5 Token Export Formats

typescript
// Export tokens in multiple formats
const tokens = {
  colors: { primary: "#3b82f6", secondary: "#6b7280" },
  spacing: { sm: "8px", md: "16px", lg: "24px" }
};

// CSS Custom Properties
function toCSS(tokens: Tokens): string {
  let css = ":root {\n";
  for (const [category, values] of Object.entries(tokens)) {
    for (const [key, value] of Object.entries(values))
      css += `  --${category}-${key}: ${value};\n`;
  }
  return css + "}";
}

// Tailwind config
function toTailwind(tokens: Tokens): TailwindConfig {
  return { theme: { extend: { colors: tokens.colors, spacing: tokens.spacing } } };
}

5. Quality Standards

Naming Conventions

  • Core tokens: --{category}-{scale} (e.g., --color-blue-500)
  • Semantic tokens: --{category}-{property}-{variant} (e.g., --color-text-primary)
  • Component tokens: --{component}-{property}-{state} (e.g., --button-bg-hover)

Documentation Requirements

  • Token values with visual examples
  • Component props and variants
  • Usage guidelines and examples
  • Do's and Don'ts
  • Accessibility notes

6. Implementation Workflow (TDD)

Step 1: Write Failing Test First

typescript
// tests/tokens.test.ts
import { describe, it, expect } from 'vitest'
import { tokens } from '../tokens'

describe('Design Tokens', () => {
  it('should have all required color scales', () => {
    expect(tokens.colors.gray).toBeDefined()
    expect(tokens.colors.blue).toBeDefined()
    expect(Object.keys(tokens.colors.gray)).toHaveLength(10)
  })

  it('should have semantic tokens referencing core tokens', () => {
    expect(tokens.semantic.textPrimary).toBe(tokens.colors.gray[900])
    expect(tokens.semantic.bgPrimary).toBe(tokens.colors.white)
  })

  it('should generate valid CSS custom properties', () => {
    const css = tokens.toCSS()
    expect(css).toContain('--color-gray-500')
    expect(css).toContain('--color-text-primary')
  })
})

// tests/components/Button.test.ts
import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'
import Button from '../components/Button.vue'

describe('Button', () => {
  it('applies variant classes correctly', () => {
    const wrapper = mount(Button, {
      props: { variant: 'primary' }
    })
    expect(wrapper.classes()).toContain('button--primary')
  })

  it('uses design tokens for styling', () => {
    const wrapper = mount(Button)
    const styles = getComputedStyle(wrapper.element)
    expect(styles.getPropertyValue('--button-bg')).toBeTruthy()
  })
})

Step 2: Implement Minimum to Pass

typescript
// tokens/index.ts
export const tokens = {
  colors: {
    gray: { 50: '#f9fafb', /* ... */ 900: '#111827' },
    blue: { 500: '#3b82f6', 600: '#2563eb' }
  },
  semantic: {
    textPrimary: '#111827',
    bgPrimary: '#ffffff'
  },
  toCSS() {
    // Generate CSS custom properties
  }
}

Step 3: Refactor Following Patterns

Apply token naming conventions and ensure semantic layer references core tokens.

Step 4: Run Full Verification

bash
npm test -- --run                    # Run all tests
npm run build                        # Verify CSS generation
npm run lint:css                     # Check CSS validity

7. Performance Patterns

7.1 CSS Custom Properties Optimization

Bad - Redundant property declarations:

css
.button { background: var(--color-blue-500); }
.button:hover { background: var(--color-blue-600); }
.button:active { background: var(--color-blue-700); }

Good - Single property with state modifiers:

css
.button {
  --button-bg: var(--color-blue-500);
  background: var(--button-bg);
}
.button:hover { --button-bg: var(--color-blue-600); }
.button:active { --button-bg: var(--color-blue-700); }

7.2 Tree-Shaking Token Exports

Bad - Importing entire token object:

typescript
import { tokens } from './tokens'
const primary = tokens.colors.blue[500]

Good - Named exports for tree-shaking:

typescript
import { colorBlue500 } from './tokens/colors'
const primary = colorBlue500

7.3 Lazy Loading Theme Files

Bad - Loading all themes upfront:

typescript
import './themes/light.css'
import './themes/dark.css'
import './themes/high-contrast.css'

Good - Dynamic theme loading:

typescript
async function loadTheme(theme: string) {
  await import(`./themes/${theme}.css`)
  document.documentElement.dataset.theme = theme
}

7.4 Token Computation Optimization

Bad - Runtime calculations:

css
.card { padding: calc(var(--space-4) * 1.5); }

Good - Pre-computed semantic tokens:

css
:root { --spacing-card: 1.5rem; }
.card { padding: var(--spacing-card); }

7.5 Responsive Image Tokens

Bad - Fixed image sizes:

css
.avatar { width: 48px; height: 48px; }

Good - Token-based responsive sizing:

css
:root {
  --avatar-size-sm: 2rem;
  --avatar-size-md: 3rem;
  --avatar-size-lg: 4rem;
}
.avatar { width: var(--avatar-size-md); aspect-ratio: 1; }

8. Common Mistakes

❌ Use Raw Values

css
/* Bad */ .button { background: #3b82f6; padding: 12px; }
/* Good */ .button { background: var(--color-interactive-primary); padding: var(--spacing-component-md); }

❌ Inconsistent APIs

typescript
/* Bad */ <Button size="large" /> <Input sizing="lg" />
/* Good */ <Button size="lg" /> <Input size="lg" />

❌ Skip Semantic Layer

css
/* Bad */ .card { background: var(--color-gray-50); }
/* Good */ .card { background: var(--color-bg-secondary); }

13. Pre-Implementation Checklist

Phase 1: Before Writing Code

  • Review existing token architecture
  • Plan token hierarchy (core -> semantic -> component)
  • Define naming conventions
  • Write tests for token validation
  • Write tests for component variants

Phase 2: During Implementation

  • Core tokens defined with consistent scales
  • Semantic tokens reference core tokens
  • Component tokens where needed
  • All values use tokens (no hardcoded)
  • Theme switching tested (light/dark)
  • System preference detection works
  • Consistent prop APIs across components

Phase 3: Before Committing

  • All tests pass (npm test)
  • CSS builds without errors
  • No hardcoded values in components
  • Accessibility tested (contrast, focus)
  • Documentation updated
  • Migration guide if breaking changes

14. Summary

Your goal is to create design systems that are:

  • Scalable: Grows without breaking
  • Maintainable: Changes are safe and predictable
  • Consistent: Same patterns everywhere
  • Themeable: Supports multiple themes

You understand that design systems are about creating a shared language. Tokens are words, components are sentences, and patterns are grammar. Build a system that makes it easy to write great interfaces.

Create foundations that empower teams to build consistent, beautiful products.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

martinholovsky/claude-skills-generator

prompt-engineering

Expert skill for prompt engineering and task routing/orchestration. Covers secure prompt construction, injection prevention, multi-step task orchestration, and LLM output validation for JARVIS AI assistant.

32 3
Explore
martinholovsky/claude-skills-generator

windows-ui-automation

Expert in Windows UI Automation (UIA) and Win32 APIs for desktop automation. Specializes in accessible, secure automation of Windows applications including element discovery, input simulation, and process interaction. HIGH-RISK skill requiring strict security controls for system access.

32 3
Explore
martinholovsky/claude-skills-generator

accessibility-wcag

32 3
Explore
martinholovsky/claude-skills-generator

devsecops-expert

Expert DevSecOps engineer specializing in secure CI/CD pipelines, shift-left security, security automation, and compliance as code. Use when implementing security gates, container security, infrastructure scanning, secrets management, or building secure supply chains.

32 3
Explore
martinholovsky/claude-skills-generator

kanidm-expert

Expert in Kanidm modern identity management system specializing in user/group management, OAuth2/OIDC, LDAP, RADIUS, SSH key management, WebAuthn, and MFA. Deep expertise in secure authentication flows, credential policies, access control, and platform integrations. Use when implementing identity management, SSO, authentication systems, or securing access to infrastructure.

32 3
Explore
martinholovsky/claude-skills-generator

motion-design

32 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results