nickcrew/claude-ctx-plugin/design-system-architecture

┌─────────────────────────────────────┐
│       Component Tokens              │  → button-primary-bg
│     (Specific to components)        │
├─────────────────────────────────────┤
│       Semantic Tokens               │  → color-action-primary
│     (Purpose-based naming)          │
├─────────────────────────────────────┤
│       Primitive Tokens              │  → blue-500
│     (Raw values)                    │
└─────────────────────────────────────┘

/* Primitive Tokens */
--color-blue-500: #3b82f6;
--spacing-4: 1rem;
--font-size-base: 16px;
--radius-md: 8px;
 
/* Semantic Tokens */
--color-action-primary: var(--color-blue-500);
--color-text-primary: var(--color-gray-900);
--spacing-component-gap: var(--spacing-4);
 
/* Component Tokens */
--button-bg: var(--color-action-primary);
--button-padding-x: var(--spacing-4);
--card-radius: var(--radius-md);

// tokens/themes.ts
export const lightTheme = {
  'color-bg-primary': 'var(--color-white)',
  'color-text-primary': 'var(--color-gray-900)',
  'color-border': 'var(--color-gray-200)',
}
export const darkTheme = {
  'color-bg-primary': 'var(--color-gray-900)',
  'color-text-primary': 'var(--color-gray-100)',
  'color-border': 'var(--color-gray-700)',
}

// ✅ Good: Clear, typed, with sensible defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
  isDisabled?: boolean;
  leftIcon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}
// ✅ With defaults
const Button = ({
  variant = 'primary',
  size = 'md',
  isLoading = false,
  isDisabled = false,
  ...props
}: ButtonProps) => { ... }

// Compound components for complex UIs
const Tabs = ({ children, defaultValue }) => { ... }
Tabs.List = ({ children }) => { ... }
Tabs.Tab = ({ value, children }) => { ... }
Tabs.Panel = ({ value, children }) => { ... }
// Usage
<Tabs defaultValue="tab1">
  <Tabs.List>
    <Tabs.Tab value="tab1">First</Tabs.Tab>
    <Tabs.Tab value="tab2">Second</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="tab1">Content 1</Tabs.Panel>
  <Tabs.Panel value="tab2">Content 2</Tabs.Panel>
</Tabs>

// Component that can render as different elements
interface BoxProps<C extends React.ElementType> {
  as?: C;
  children?: React.ReactNode;
}
type PolymorphicProps<C extends React.ElementType> =
  BoxProps<C> & Omit<React.ComponentPropsWithoutRef<C>, keyof BoxProps<C>>;
const Box = <C extends React.ElementType = 'div'>({
  as,
  ...props
}: PolymorphicProps<C>) => {
  const Component = as || 'div';
  return <Component {...props} />;
};
// Usage
<Box as="section" className="...">Content</Box>
<Box as="button" onClick={...}>Click me</Box>

# Button
 
Buttons trigger actions or navigate users.
 
## Usage
 
\`\`\`jsx
import { Button } from '@/components/ui'
 
<Button variant="primary" size="md">
  Click me
</Button>
\`\`\`
 
## Props
 
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size preset |
 
## Examples
 
### Variants
[Interactive examples]
 
### With Icons
[Interactive examples]
 
## Accessibility
 
-Uses `<button>` element by default
-Supports keyboard activation
-Loading state announced to screen readers