ilandahan/AID / skills/atomic-design
atomic-design
VerifiedBuild an Atomic Design system from design spec style guides - extract tokens, create atoms/molecules/organisms/templates/pages as reusable component libraries. Use when building or extending a design system or component library.
| File | Kind | Size |
|---|---|---|
| SKILL.extended.md | markdown | 14.6 KB |
| SKILL.md | skill md | 6.0 KB |
| references/atomic-hierarchy.extended.md | markdown | 15.5 KB |
| references/atomic-hierarchy.md | markdown | 4.2 KB |
| references/component-templates.extended.md | markdown | 23.0 KB |
| references/component-templates.md | markdown | 7.8 KB |
| references/design-deviation-rules.extended.md | markdown | 12.1 KB |
| references/design-deviation-rules.md | markdown | 3.5 KB |
| references/responsive-patterns.extended.md | markdown | 14.3 KB |
| references/responsive-patterns.md | markdown | 4.6 KB |
| tokens/breakpoints.json | config | 659 B |
| tokens/colors.json | config | 1.6 KB |
| tokens/components.json | config | 3.1 KB |
| tokens/spacing.json | config | 1.4 KB |
| tokens/typography.json | config | 1.8 KB |
references/atomic-hierarchy.extended.md
View on GitHub# Atomic Design Hierarchy
Complete breakdown of component levels with implementation patterns.
## ⚠️ CRITICAL: Extract from design spec First
```
┌─────────────────────────────────────────────────────────────────────┐
│ 🚨 BEFORE CREATING ANY COMPONENT: │
│ │
│ 1. Extract specs from local design specifications │
│ 2. Document the design spec link in your component │
│ 3. Use EXACT values - no rounding or "improving" │
│ │
│ The examples below show STRUCTURE, not actual values. │
│ Your values MUST come from your design spec design system. │
└─────────────────────────────────────────────────────────────────────┘
```
**Related documents:**
- `design-deviation-rules.md` - Complete extraction workflow
- `design-deviation-rules.md` - Zero deviation policy
- `design-deviation-rules.md` - Specification fidelity rules
## Level 1: Atoms
**Definition:** Smallest, indivisible UI elements. Cannot be broken down further.
### Typography Atoms
```typescript
/**
* Typography Atom
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* ⚠️ All font sizes, weights, and line-heights from design spec - DO NOT MODIFY
*/
// atoms/Typography/Typography.tsx
import { ReactNode } from 'react';
import styles from './Typography.module.css';
type TypographyVariant =
| 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
| 'body-lg' | 'body' | 'body-sm'
| 'caption' | 'overline' | 'label';
interface TypographyProps {
children: ReactNode;
variant?: TypographyVariant;
as?: keyof JSX.IntrinsicElements;
color?: 'primary' | 'secondary' | 'muted' | 'inverse' | 'error' | 'success';
}
export const Typography = ({
children,
variant = 'body',
as,
color = 'primary'
}: TypographyProps) => {
const Component = as || getDefaultTag(variant);
return (
<Component className={`${styles[variant]} ${styles[`color-${color}`]}`}>
{children}
</Component>
);
};
/* Typography.module.css - ALL styles encapsulated */
/* ⚠️ ALL values EXACT from design spec - verify before using */
.h1 {
font-family: var(--font-heading); /* From design spec */
font-size: var(--font-size-4xl); /* From design spec */
font-weight: var(--font-weight-bold); /* From design spec */
line-height: var(--line-height-tight); /* From design spec */
letter-spacing: var(--letter-spacing-tight); /* From design spec */
}
/* Responsive: Check design spec Mobile frame for these values */
@media (max-width: 768px) {
.h1 { font-size: var(--font-size-2xl); } /* From design spec Mobile */
}
/* ... all variants defined - ALL from design spec */
```
### Button Atom
```typescript
/**
* Button Atom
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* ⚠️ All sizes, padding, colors from design spec - DO NOT MODIFY
*/
// atoms/Button/Button.tsx
interface ButtonProps {
label: string;
onClick?: () => void;
type?: 'button' | 'submit' | 'reset';
variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
icon?: ReactNode;
iconPosition?: 'left' | 'right';
fullWidth?: boolean;
}
export const Button = ({
label,
onClick,
type = 'button',
variant = 'primary',
size = 'md',
disabled = false,
loading = false,
icon,
iconPosition = 'left',
fullWidth = false,
}: ButtonProps) => {
return (
<button
type={type}
onClick={onClick}
disabled={disabled || loading}
className={clsx(
styles.button,
styles[variant],
styles[size],
fullWidth && styles.fullWidth
)}
aria-busy={loading}
>
{loading ? <Spinner size="sm" /> : (
<>
{icon && iconPosition === 'left' && <span className={styles.icon}>{icon}</span>}
<span>{label}</span>
{icon && iconPosition === 'right' && <span className={styles.icon}>{icon}</span>}
</>
)}
</button>
);
};
```
### Input Atom
```typescript
/**
* Input Atom
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* ⚠️ All sizes, padding, border styles from design spec - DO NOT MODIFY
*/
// atoms/Input/Input.tsx
interface InputProps {
value: string;
onChange: (value: string) => void;
placeholder?: string;
type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
disabled?: boolean;
error?: boolean;
id?: string;
name?: string;
autoComplete?: string;
'aria-describedby'?: string;
}
export const Input = ({
value,
onChange,
placeholder,
type = 'text',
disabled = false,
error = false,
...props
}: InputProps) => {
return (
<input
type={type}
value={value}
onChange={(e) => onChange(e.target.value)}
placeholder={placeholder}
disabled={disabled}
className={clsx(styles.input, error && styles.error)}
aria-invalid={error}
{...props}
/>
);
};
```
### Other Atoms
- **Icon** - SVG wrapper with size/color variants
- **Badge** - Status indicators (label + variant)
- **Avatar** - Image/initials display (src + alt + size)
- **Divider** - Visual separator (orientation)
- **Spinner** - Loading indicator (size)
- **Checkbox** - Toggle (checked + onChange + label)
- **Radio** - Selection (checked + onChange + label)
- **Switch** - Toggle switch (checked + onChange)
---
## Level 2: Molecules
**Definition:** Groups of atoms functioning together as a unit.
### FormField Molecule
```typescript
/**
* FormField Molecule
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* Composes: Typography (label) + Input + Typography (error/hint)
* ⚠️ Layout spacing from design spec - DO NOT MODIFY
*/
// molecules/FormField/FormField.tsx
interface FormFieldProps {
label: string;
value: string;
onChange: (value: string) => void;
placeholder?: string;
type?: 'text' | 'email' | 'password' | 'number';
error?: string;
hint?: string;
required?: boolean;
disabled?: boolean;
}
export const FormField = ({
label,
value,
onChange,
placeholder,
type = 'text',
error,
hint,
required = false,
disabled = false,
}: FormFieldProps) => {
const id = useId();
const errorId = `${id}-error`;
const hintId = `${id}-hint`;
return (
<div className={styles.field}>
<Typography
as="label"
variant="label"
htmlFor={id}
className={styles.label}
>
{label}
{required && <span className={styles.required}>*</span>}
</Typography>
<Input
id={id}
type={type}
value={value}
onChange={onChange}
placeholder={placeholder}
disabled={disabled}
error={!!error}
aria-describedby={error ? errorId : hint ? hintId : undefined}
/>
{error && (
<Typography id={errorId} variant="caption" color="error">
{error}
</Typography>
)}
{hint && !error && (
<Typography id={hintId} variant="caption" color="muted">
{hint}
</Typography>
)}
</div>
);
};
```
### Card Molecule
```typescript
/**
* Card Molecule
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* ⚠️ All padding, shadows, border-radius from design spec - DO NOT MODIFY
*/
// molecules/Card/Card.tsx
interface CardProps {
title?: string;
subtitle?: string;
children: ReactNode;
footer?: ReactNode;
variant?: 'elevated' | 'outlined' | 'filled';
onClick?: () => void;
as?: 'article' | 'section' | 'div';
}
export const Card = ({
title,
subtitle,
children,
footer,
variant = 'elevated',
onClick,
as: Component = 'div',
}: CardProps) => {
const isInteractive = !!onClick;
return (
<Component
className={clsx(styles.card, styles[variant], isInteractive && styles.interactive)}
onClick={onClick}
role={isInteractive ? 'button' : undefined}
tabIndex={isInteractive ? 0 : undefined}
>
{(title || subtitle) && (
<div className={styles.header}>
{title && <Typography variant="h4">{title}</Typography>}
{subtitle && <Typography variant="body-sm" color="secondary">{subtitle}</Typography>}
</div>
)}
<div className={styles.content}>{children}</div>
{footer && <div className={styles.footer}>{footer}</div>}
</Component>
);
};
```
### Other Molecules
- **SearchBar** - Input + Button + Icon
- **MenuItem** - Icon + Label + Badge (optional)
- **ListItem** - Avatar + Content + Actions
- **Breadcrumb** - Icon + Links + Separator
- **Pagination** - Buttons + Page numbers
- **Tabs** - Tab buttons + active state
- **Toast** - Icon + Message + Close button
- **Modal Header** - Title + Close button
---
## Level 3: Organisms
**Definition:** Complex UI sections composed of molecules and atoms.
### Header Organism
```typescript
/**
* Header Organism
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* Composes: Logo + NavItems + UserMenu + MobileMenu
* ⚠️ All heights, spacing, responsive behavior from design spec - DO NOT MODIFY
*/
// organisms/Header/Header.tsx
interface NavItem {
label: string;
href: string;
isActive?: boolean;
}
interface HeaderProps {
logo: ReactNode;
navItems: NavItem[];
onLogoClick?: () => void;
actions?: ReactNode;
userMenu?: {
userName: string;
userAvatar?: string;
menuItems: { label: string; onClick: () => void }[];
};
}
export const Header = ({
logo,
navItems,
onLogoClick,
actions,
userMenu,
}: HeaderProps) => {
const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
return (
<header className={styles.header}>
<div className={styles.container}>
<div className={styles.logoSection} onClick={onLogoClick}>
{logo}
</div>
<nav className={styles.nav} aria-label="Main navigation">
<ul className={styles.navList}>
{navItems.map((item) => (
<li key={item.href}>
<a
href={item.href}
className={clsx(styles.navLink, item.isActive && styles.active)}
aria-current={item.isActive ? 'page' : undefined}
>
{item.label}
</a>
</li>
))}
</ul>
</nav>
<div className={styles.actions}>
{actions}
{userMenu && (
<UserMenu
userName={userMenu.userName}
userAvatar={userMenu.userAvatar}
menuItems={userMenu.menuItems}
/>
)}
</div>
<Button
label="Menu"
variant="ghost"
icon={<MenuIcon />}
onClick={() => setMobileMenuOpen(true)}
className={styles.mobileMenuButton}
/>
</div>
<MobileMenu
isOpen={mobileMenuOpen}
onClose={() => setMobileMenuOpen(false)}
navItems={navItems}
/>
</header>
);
};
```
### Form Organism
```typescript
/**
* Form Organism
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* Composes: FormFields + Buttons
* ⚠️ All field gaps, button alignment from design spec - DO NOT MODIFY
*/
// organisms/Form/Form.tsx
interface FormField {
name: string;
label: string;
type: 'text' | 'email' | 'password' | 'textarea' | 'select';
placeholder?: string;
required?: boolean;
options?: { value: string; label: string }[]; // For select
}
interface FormProps {
fields: FormField[];
values: Record<string, string>;
errors: Record<string, string>;
onChange: (name: string, value: string) => void;
onSubmit: () => void;
submitLabel: string;
loading?: boolean;
secondaryAction?: {
label: string;
onClick: () => void;
};
}
export const Form = ({
fields,
values,
errors,
onChange,
onSubmit,
submitLabel,
loading = false,
secondaryAction,
}: FormProps) => {
return (
<form onSubmit={(e) => { e.preventDefault(); onSubmit(); }} className={styles.form}>
{fields.map((field) => (
<FormField
key={field.name}
label={field.label}
type={field.type}
value={values[field.name] || ''}
onChange={(value) => onChange(field.name, value)}
placeholder={field.placeholder}
error={errors[field.name]}
required={field.required}
/>
))}
<div className={styles.actions}>
{secondaryAction && (
<Button
label={secondaryAction.label}
variant="ghost"
onClick={secondaryAction.onClick}
/>
)}
<Button
label={submitLabel}
type="submit"
variant="primary"
loading={loading}
/>
</div>
</form>
);
};
```
### Other Organisms
- **DataTable** - Headers + Rows + Pagination + Sorting
- **Sidebar** - Navigation + User section + Logo
- **Footer** - Links + Social + Copyright
- **HeroSection** - Heading + CTA + Image/Video
- **FeatureGrid** - Cards grid + Section header
- **PricingTable** - Plan cards + Comparison
- **CommentSection** - Comments list + Reply form
---
## Level 4: Templates
**Definition:** Page-level layouts that arrange organisms without specific content.
```typescript
/**
* DashboardLayout Template
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* ⚠️ All grid columns, sidebar width, main area padding from design spec
* Check design spec for Desktop, Tablet, Mobile frame variations
*/
// templates/DashboardLayout/DashboardLayout.tsx
interface DashboardLayoutProps {
header: ReactNode;
sidebar: ReactNode;
children: ReactNode;
footer?: ReactNode;
}
export const DashboardLayout = ({
header,
sidebar,
children,
footer,
}: DashboardLayoutProps) => {
const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
return (
<div className={styles.layout}>
<div className={styles.headerArea}>{header}</div>
<div className={clsx(styles.sidebarArea, sidebarCollapsed && styles.collapsed)}>
{sidebar}
</div>
<main className={styles.mainArea}>{children}</main>
{footer && <div className={styles.footerArea}>{footer}</div>}
</div>
);
};
```
---
## Level 5: Pages
**Definition:** Specific instances of templates with real content.
```typescript
/**
* Dashboard Page
*
* @design-source ./design-spec.md
* @extracted [DATE]
*
* Uses: DashboardLayout template + real content
* ⚠️ All layout, spacing, responsive behavior from design spec page frames
*/
// pages/Dashboard/Dashboard.tsx
export const DashboardPage = () => {
const { user } = useAuth();
const { data: stats } = useDashboardStats();
return (
<DashboardLayout
header={
<Header
logo={<Logo />}
navItems={NAV_ITEMS}
userMenu={{
userName: user.name,
userAvatar: user.avatar,
menuItems: USER_MENU_ITEMS,
}}
/>
}
sidebar={
<Sidebar
items={SIDEBAR_ITEMS}
activeItem="dashboard"
/>
}
>
<Typography variant="h1">Welcome back, {user.firstName}</Typography>
<StatsGrid stats={stats} />
<RecentActivityTable />
</DashboardLayout>
);
};
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |