design-system-patterns

michaellperry's avatarfrom michaellperry

Best practices for building reusable UI components. Use when creating atoms, molecules, or updating the theme.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill serves as a comprehensive guide for Design System Engineering, focusing on building scalable and reusable UI components through Atomic Design principles. It provides expert-level patterns for React development, Tailwind CSS styling, and WCAG-compliant accessibility, ensuring frontend codebases remain consistent, maintainable, and inclusive.

Use Cases

  • Standardizing UI development by creating foundational 'Atoms' (buttons, inputs) and 'Molecules' (form fields, cards) that follow a unified architectural pattern.
  • Implementing a robust theme system using Tailwind CSS tokens to ensure visual consistency and seamless dark mode support across the entire application.
  • Enhancing web accessibility (a11y) by automatically integrating semantic HTML, focus states, and ARIA attributes into reusable component structures.
  • Bridging the gap between design and code by translating design tokens and gap analyses into high-quality, production-ready frontend components.
  • Refactoring legacy UI code into a modular Atomic Design structure to improve developer efficiency and simplify long-term maintenance.
namedesign-system-patterns
descriptionBest practices for building reusable UI components. Use when creating atoms, molecules, or updating the theme.

Design System Patterns

Role & Responsibilities

The Design System Engineer acts as the bridge between design and code.

  • Input: Component Gap Analysis from the FTS.
  • Output: Reusable components in src/components/atoms and molecules.
  • Goal: Ensure visual consistency and accessibility.

Atomic Design

  • Atoms: Basic building blocks (Buttons, Inputs, Icons). No business logic.
  • Molecules: Groups of atoms (Form Fields, Cards). Minimal logic.
  • Organisms: Complex sections (Forms, Lists). Product Developer territory.

Styling (Tailwind CSS)

  • Tokens: Use values from src/theme/tokens.ts via Tailwind classes.
  • Utility Classes: Use clsx and tailwind-merge for conditional styling.
  • Dark Mode: Always implement dark: variants for every color.

Accessibility (a11y)

  • Interactive Elements: Must have focus states (focus-visible:ring).
  • Semantic HTML: Use <button>, <nav>, <main>, etc.
  • ARIA: Use aria-label or aria-describedby when text is insufficient.
  • Keyboard Navigation: Ensure all interactions work without a mouse.

Component Structure

import { cn } from '@/utils/cn';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
}

export const Button = ({ className, variant = 'primary', ...props }: ButtonProps) => {
  return (
    <button
      className={cn(
        'px-4 py-2 rounded-md transition-colors focus-visible:ring-2',
        variant === 'primary' && 'bg-blue-600 text-white',
        className
      )}
      {...props}
    />
  );
};