Philosophy

Methodology

guidelines

• Content drives layout, not the reverse
• Every UI element must have a clear purpose
• Progressive disclosure: show essentials first, details on demand
• Design for scanning, not reading

description

Anthropic follows a content-first, progressive disclosure approach. Design starts with information architecture before visual treatment.

testLocation

Co-located: ComponentName.test.tsx next to ComponentName.tsx

exportPattern

Named exports only. No barrel files (index.ts re-exports). Direct imports from component file.

fileStructure

atoms

src/components/atoms/ — Button, Input, Badge, Tooltip

molecules

src/components/molecules/ — SearchField, FormField, Card

organisms

src/components/organisms/ — NavigationBar, SidebarMenu, DataTable

templates

src/components/templates/ — DocumentationLayout

Token Architecture

tiers

• primitive
• semantic
• component

description

Three-tier token architecture: Primitive → Semantic → Component. Primitives are raw values. Semantic tokens map to use-cases. Component tokens are scoped to specific UI elements.

mappingRules

• {"to":"semantic","from":"primitive","rule":"One-to-many: a primitive value can feed multiple semantic tokens"}
• {"to":"component","from":"semantic","rule":"One-to-one: a component token references exactly one semantic token"}

namingConvention

kebab-case with tier prefix: --color-primitive-cream, --color-bg-primary, --button-bg-default

Colors

Typography

Spacing

grid

gutter

24px

margin

16px (mobile), 24px (tablet), 32px (desktop)

columns

12

baseUnit

4px

maxWidth

1280px

border

styles

{"dashed":"dashed","default":"solid"}

widths

{"thin":"1px","thick":"3px","medium":"2px"}

defaultColor

var(--border-default)

shapes

card

{"border":"1px solid var(--border-default)","shadow":"var(--shadow-low)","borderRadius":"8px"}

badge

{"paddingX":"8px","paddingY":"2px","borderRadius":"9999px"}

input

{"border":"1px solid var(--border-default)","height":"40px","borderRadius":"8px"}

modal

{"border":"none","shadow":"var(--shadow-high)","borderRadius":"12px"}

button

{"paddingX":"16px","minHeight":"36px","borderRadius":"8px"}

sizing

scale

• 24
• 32
• 40
• 48
• 56
• 64
• 80
• 96
• 120
• 160
• 240
• 320
• 480

iconSizes

{"lg":"24px","md":"20px","sm":"16px","xl":"32px"}

touchTarget

{"ios":"44px (Apple HIG)","web":"32px minimum, 40px recommended","android":"48dp (Material Design)"}

description

4px base unit. Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. Content areas use generous padding (32-48px). Compact UI uses 8-16px.

densityModes

compact

{"gap":"8px","usage":"Data tables, toolbars","verticalPadding":"4px","horizontalPadding":"8px"}

default

{"gap":"16px","usage":"Forms, cards, general UI","verticalPadding":"8px","horizontalPadding":"16px"}

comfortable

{"gap":"24px","usage":"Marketing, landing pages","verticalPadding":"12px","horizontalPadding":"24px"}

Shadow & Depth

zIndex

base

0

modal

400

toast

500

sticky

200

overlay

300

tooltip

600

dropdown

100

description

Minimal shadow usage. Shadows are soft and warm-toned, never blue-gray. Elevation levels: none (default), low (cards), medium (dropdowns), high (modals).

Atoms

Molecules

Organisms

Composition

description

Layout patterns: sidebar + main (documentation), centered narrow (marketing), full-bleed hero + contained body (landing pages). Max content width: 1280px.

contentAreas

main

{"padding":"32px","maxWidth":"1280px"}

footer

{"padding":"48px 32px","borderTop":"1px solid var(--border-default)"}

header

{"height":"64px","zIndex":200,"position":"sticky top-0"}

sidebar

{"width":"280px","position":"fixed left-0","breakpoint":"hidden below lg"}

boxArrangement

flex

Use for single-axis layouts (nav items, button groups, form rows)

grid

Use for two-dimensional layouts (card grids, data tables, dashboards)

stack

Use for vertical stacking with consistent gaps (section lists, form fields)

layoutPatterns

• {"css":"grid grid-cols-[280px_1fr] min-h-screen","name":"sidebar-main","usage":"Documentation, design system viewer, settings","structure":{"main":"fluid","footer":false,"header":true,"sidebar":true}}
• {"css":"flex min-h-screen items-center justify-center","name":"centered-card","usage":"Login, auth callback, error pages","maxWidth":"480px","structure":{"main":"centered","footer":false,"header":false,"sidebar":false}}
• {"css":"mx-auto max-w-3xl px-6","name":"centered-narrow","usage":"Marketing, blog posts, legal pages","maxWidth":"720px","structure":{"main":"centered","footer":true,"header":true,"sidebar":false}}
• {"css":"w-full + mx-auto max-w-7xl px-6","name":"full-bleed-hero","usage":"Landing pages, product announcements","structure":{"main":"full-width-hero + contained-body","footer":true,"header":true,"sidebar":false}}
• {"css":"grid grid-cols-[240px_1fr] min-h-screen","name":"dashboard","usage":"Admin panels, analytics, monitoring","structure":{"main":"grid","footer":false,"header":true,"sidebar":true}}

maxContentWidth

1280px

Responsive

statusBar

ios

Light content on dark backgrounds, dark content on light backgrounds. Safe area insets respected.

android

Transparent status bar with edge-to-edge rendering. System bars adapt to theme.

breakpoints

lg

1024px

md

768px

sm

640px

xl

1280px

description

Mobile-first with 3 breakpoints: sm (640px), md (768px), lg (1024px). Sidebar collapses to hamburger below lg. Typography scales down 1 step on mobile.

gridColumns

lg

12

md

8

sm

4

xl

12

typeScaleAdjust

mobile

All sizes -2px. Display XL 48→40, Display L 36→30, H1 30→26

tablet

All sizes -1px from desktop

desktop

Base scale as defined in type scales

platformNavigation

ios

Tab bar (bottom) + navigation controller (push/pop)

web

Top navbar + left sidebar (desktop), hamburger + drawer (mobile)

android

Bottom navigation bar + navigation drawer (swipe from left)

componentAdaptations

• {"behavior":"Collapsible drawer below lg. Full sidebar at lg+.","component":"SidebarMenu"}
• {"behavior":"Hamburger menu below md. Inline links at md+.","component":"NavigationBar"}
• {"behavior":"Horizontal scroll below md. Full width at md+.","component":"DataTable"}
• {"behavior":"1-col at sm, 2-col at md, 3-col at lg.","component":"Card grid"}

States

states

• default
• hover
• active
• focus
• disabled
• error
• success
• loading

description

State communication through subtle visual changes. Hover: border color shift. Active: background tint. Disabled: 40% opacity. Error: terracotta border + message. Success: muted green accent.

emptyStates

action

Primary CTA button to resolve the empty state (e.g., 'Create first item').

message

Clear explanation of why content is empty + what user can do next.

illustration

Minimal line illustration (not decorative). Optional, never required.

stateStyles

• {"state":"default","visual":"Base appearance. No special treatment."}
• {"state":"hover","visual":"Border shifts to --border-hover. Subtle background tint on interactive elements."}
• {"state":"active","visual":"Background darkens 5%. Transform scale(0.98) for buttons."}
• {"state":"focus","visual":"2px ring in --accent-primary with 2px offset. Visible on keyboard focus only (:focus-visible)."}
• {"state":"disabled","visual":"opacity: 0.4. cursor: not-allowed. No hover/active effects."}
• {"state":"error","visual":"Border color --accent-primary (terracotta). Error message text below input."}
• {"state":"success","visual":"Border color --accent-green. Check icon. Brief green tint fade."}
• {"state":"loading","visual":"Skeleton shimmer or spinner. Disabled interaction during load."}

errorPatterns

toast

Bottom-right toast notification. Auto-dismiss after 5s. Manual dismiss available.

inline

Red border + error message directly below the input field.

fullPage

Centered error illustration + error code + description + retry button.

loadingPatterns

spinner

16px circle spinner for inline, 32px for section-level, 48px for page-level.

progress

Thin progress bar at top of viewport for page transitions.

skeleton

Gray rectangular placeholders matching content shape. Shimmer animation left-to-right.

connectivityStates

online

No indicator. Default state.

offline

Yellow banner at top: 'You are offline. Changes will sync when reconnected.'

reconnecting

Pulsing dot indicator in header. Auto-retry with exponential backoff.

Naming

examples

token

--color-bg-primary

cssClass

text-slate-600

fileName

sidebar-nav.tsx

component

SidebarNav

fileNaming

kebab-case for all files: sidebar-nav.tsx, use-debounce.ts, auth-callback/page.tsx

description

BEM-inspired with Tailwind utility classes. Components use PascalCase. CSS custom properties use kebab-case with semantic prefixes.

tailwindRules

• Prefer semantic Tailwind classes (text-slate-900) over arbitrary values ([color:#3d3929])
• Group related utilities: layout → spacing → typography → color → effects
• Use @apply sparingly — only for repeated patterns in global CSS
• Responsive: mobile-first (sm: md: lg:). Never use max-width media queries.
• Dark mode: dark: prefix. Always define both light and dark variants.

cssVariableRules

• Define in :root for light, .dark for dark mode
• Prefix by category: --color-*, --space-*, --shadow-*, --radius-*
• Reference via Tailwind theme extension, not inline var()

responsiveUtilities

• Use container queries (@container) for component-level responsive behavior
• Use media queries (@media) for page-level layout changes
• Prefer min-width breakpoints (mobile-first). Never max-width.

Accessibility

target

WCAG 2.1 AA

contrast

ui

3:1

text

4.5:1

largeText

3:1

description

WCAG 2.1 AA target. All interactive elements have visible focus rings. Color is never the sole indicator. Minimum contrast ratio 4.5:1 for text, 3:1 for large text.

requirements

• Keyboard navigation for all interactions
• Screen reader labels on icons (aria-label or sr-only text)
• Reduced motion support (prefers-reduced-motion: reduce)
• Sufficient color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
• Focus indicators visible on all interactive elements
• Form inputs with associated labels (htmlFor/id pairing)
• Error messages linked to inputs via aria-describedby
• Skip-to-content link as first focusable element

Motion

defaults

easing

cubic-bezier(0.25, 0.1, 0.25, 1)

duration

300ms

enterFrom

{"y":8,"opacity":0}

description

Purposeful, restrained animation. Entry transitions only (no exit). Duration: 200-300ms. Easing: cubic-bezier(0.25, 0.1, 0.25, 1). Respect prefers-reduced-motion.

reducedMotion

When prefers-reduced-motion is set, disable all transform animations. Opacity transitions remain but execute instantly (duration: 0ms).