(null);
function Card({ children, className }: CardProps) {
return (
{children}
);
}
Card.Header = function CardHeader({ children }: { children: ReactNode }) {
return {children}
;
};
Card.Body = function CardBody({ children }: { children: ReactNode }) {
return {children}
;
};
Card.Footer = function CardFooter({ children }: { children: ReactNode }) {
return {children}
;
};
// Usage:
Order Summary
```
### Controlled + Uncontrolled
```tsx
interface InputProps extends ComponentPropsWithoutRef<'input'> {
label: string;
error?: string;
// Controlled: pass value + onChange
// Uncontrolled: pass defaultValue
}
function Input({ label, error, id, ...props }: InputProps) {
const inputId = id ?? useId();
return (
{error && (
{error}
)}
);
}
```
### `className` Extension Point
```tsx
// ALWAYS allow consumers to extend styles
interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
variant?: 'primary' | 'secondary' | 'ghost';
size?: 'sm' | 'md' | 'lg';
}
function Button({ variant = 'primary', size = 'md', className, ...props }: ButtonProps) {
return (
);
}
```
---
## Documentation with Storybook
```tsx
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta = {
component: Button,
title: 'Components/Button',
tags: ['autodocs'],
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary', 'ghost'],
},
size: {
control: 'radio',
options: ['sm', 'md', 'lg'],
},
},
};
export default meta;
type Story = StoryObj;
export const Primary: Story = {
args: { variant: 'primary', children: 'Click me' },
};
export const Loading: Story = {
args: { variant: 'primary', loading: true, children: 'Saving...' },
};
export const Disabled: Story = {
args: { disabled: true, children: 'Unavailable' },
};
// All interactive states documented as stories
export const AllVariants: Story = {
render: () => (
),
};
```
---
## Versioning and Distribution
### Package Structure
```
@myorg/design-system/
├── src/
│ ├── components/
│ │ ├── Button/
│ │ │ ├── Button.tsx
│ │ │ ├── Button.module.css
│ │ │ ├── Button.test.tsx
│ │ │ └── Button.stories.tsx
│ ├── tokens/
│ │ └── tokens.json
│ └── index.ts ← named exports only
├── dist/
│ ├── index.js ← ESM
│ ├── index.cjs ← CJS
│ └── tokens/
│ └── variables.css
└── package.json
```
### package.json
```json
{
"name": "@myorg/design-system",
"version": "3.2.0",
"type": "module",
"exports": {
".": {
"import": "./dist/index.js",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
},
"./tokens/css": "./dist/tokens/variables.css"
},
"sideEffects": false,
"peerDependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0"
}
}
```
**Tree-shaking**: `sideEffects: false` + named exports enable bundlers to drop unused components.
### Changesets for Versioning
```bash
# When making a change
npx changeset
# → prompts for: which packages changed, semver bump type, changelog entry
# In CI, release:
npx changeset version # bumps versions, updates CHANGELOG.md
npx changeset publish # publishes to npm
```
---
## Theming
### CSS Custom Property Theming
```css
/* Light theme (default) */
:root {
--ds-color-background: #ffffff;
--ds-color-surface: #f8fafc;
--ds-color-text-primary: #0f172a;
--ds-color-text-secondary: #64748b;
--ds-color-border: #e2e8f0;
--ds-color-action-primary: #3b82f6;
}
/* Dark theme */
[data-theme="dark"] {
--ds-color-background: #0f172a;
--ds-color-surface: #1e293b;
--ds-color-text-primary: #f1f5f9;
--ds-color-text-secondary: #94a3b8;
--ds-color-border: #334155;
--ds-color-action-primary: #60a5fa;
}
/* System preference */
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
/* same dark variables */
}
}
```
### React ThemeProvider
```tsx
type Theme = 'light' | 'dark' | 'system';
const ThemeContext = createContext<{
theme: Theme;
setTheme: (t: Theme) => void;
} | null>(null);
export function ThemeProvider({ children }: { children: ReactNode }) {
const [theme, setTheme] = useState(() =>
(localStorage.getItem('theme') as Theme) ?? 'system'
);
useEffect(() => {
const root = document.documentElement;
const resolved = theme === 'system'
? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
: theme;
root.setAttribute('data-theme', resolved);
localStorage.setItem('theme', theme);
}, [theme]);
return (
{children}
);
}
export const useTheme = () => {
const ctx = useContext(ThemeContext);
if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
return ctx;
};
```
---
## Accessibility Built-in
Every component ships with accessibility baked in. Not optional.
```tsx
// Modal with full keyboard + ARIA support
function Modal({ isOpen, onClose, title, children }: ModalProps) {
const titleId = useId();
const dialogRef = useRef(null);
// Focus trap
useEffect(() => {
if (!isOpen) return;
const el = dialogRef.current;
if (!el) return;
const focusable = el.querySelectorAll(
'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
focusable[0]?.focus();
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape') onClose();
if (e.key === 'Tab') {
// Trap focus within modal
const first = focusable[0];
const last = focusable[focusable.length - 1];
if (e.shiftKey ? document.activeElement === first : document.activeElement === last) {
e.preventDefault();
(e.shiftKey ? last : first).focus();
}
}
};
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [isOpen, onClose]);
if (!isOpen) return null;
return (
{title}
{children}
);
}
```
### Accessibility Checklist Per Component
- [ ] Correct semantic element or ARIA role
- [ ] Visible label (or `aria-label` / `aria-labelledby`)
- [ ] Keyboard operable (Tab to focus, Enter/Space to activate)
- [ ] Focus indicator visible (never `outline: none` without replacement)
- [ ] Color contrast meets 4.5:1 (text) and 3:1 (UI components)
- [ ] State communicated via ARIA (`aria-expanded`, `aria-selected`, `aria-checked`)
- [ ] Motion can be disabled via `prefers-reduced-motion`
- [ ] Tested with axe-core (zero violations rule)
---
## Anti-Patterns
- **Naming components by visual appearance**: `RedButton`, `BigText` — use semantic names: `Button variant="danger"`, `Text size="xl"`
- **Token proliferation without governance**: 400 one-off color values — enforce primitives → semantic → component tiers
- **Breaking changes in patch versions**: consumer builds break silently — use Changesets; strict semver
- **No accessibility testing in CI**: a11y regressions go unnoticed — `jest-axe` on every component test
- **Blocking className customization**: `overflow: hidden` on styles — always spread `className`
- **Barrel exports importing everything**: prevents tree-shaking — keep `index.ts` minimal or use deep imports
- **Skipping Storybook stories for edge cases**: bugs in loading/error/empty states — story per state
---
## Quick Reference Checklist
- [ ] Three-tier token architecture: primitive → semantic → component
- [ ] Style Dictionary (or equivalent) generating CSS vars, JS, and platform outputs
- [ ] Compound component pattern for complex UI (Card, Tabs, Select)
- [ ] Polymorphic `as` prop for Text and layout components
- [ ] Both controlled and uncontrolled interfaces on form inputs
- [ ] `className` extension point on every component
- [ ] Storybook stories covering all variants, states, and edge cases
- [ ] Chromatic CI for visual regression
- [ ] Changesets for automated changelog and semver
- [ ] CSS custom property theming with `[data-theme]` attribute
- [ ] `ThemeProvider` with system preference detection
- [ ] Zero axe-core violations in component tests