Skip to content

ilandahan/AID / skills/atomic-design

atomic-design

Verified

Build 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.

Atomic Design System

When to Use

TriggerAction
Create a componentExtract from design spec -> Build
Style elementCheck design spec specs -> Apply
Extract tokensUse this skill
Build page/form/layoutSwitch to atomic-page-builder

Critical Rule: design spec Is Source of Truth

Extract and implement from design spec exactly. Never guess design values.

  1. READ THE APPROVED DESIGN SPEC (mandatory). Use local specification files, exported assets, screenshots and token definitions supplied by the user. Copy exact values and document their source. Ask for missing measurements instead of inventing them.
  2. COMPARE WITH EXISTING - check current tokens/*.json. If design spec differs -> UPDATE tokens (design spec wins always).
  3. IMPLEMENT EXACTLY - match design spec specs 1:1. No rounding, no improvements, no creative freedom.

Zero Deviation Policy

ForbiddenCorrect
Round 13px to 12pxUse exact 13px
Change #3B82F6 to #3F85F7Use exact #3B82F6
Add shadow not in design specNo shadow if not designed
Improve spacingExact spacing from design spec

Design input

Read approved local specification files, token definitions and exported assets. Document their source paths and exact values. Ask for missing values before coding.

Design Tokens

NeedFileKey Values
Colorstokens/colors.jsonsemantic.primary, semantic.error
Typographytokens/typography.jsonsemantic.heading-1, semantic.body
Spacingtokens/spacing.jsonsemantic.component-padding
Componentstokens/components.jsonbutton.variants, input.states
Breakpointstokens/breakpoints.jsonmd: 768px, lg: 1024px

Use semantic token names, never primitives:

color: var(--color-primary);              /* DO */
padding: var(--spacing-component-padding);/* DO */
color: var(--blue-500);  /* Wrong - primitive */
padding: 16px;           /* Wrong - hardcoded */

Atomic Hierarchy

PAGES      -> Dashboard, Settings, UserProfile
TEMPLATES  -> DashboardLayout, AuthLayout
ORGANISMS  -> Header, Sidebar, Form, DataTable
MOLECULES  -> FormField, SearchBar, Card, NavItem
ATOMS      -> Button, Input, Typography, Icon
TOKENS     -> colors, typography, spacing (FROM design spec)
LevelRuleExample
AtomUses ONLY tokensButton uses color/spacing tokens
MoleculeCombines 2+ AtomsFormField = Label + Input + ErrorText
OrganismCombines Molecules + AtomsHeader = Logo + NavItems + UserMenu
TemplateLayout structure, no contentDashboardLayout
PageTemplate + real contentDashboard

Core Rules

1. Props = Content/Behavior Only

// Correct
interface ButtonProps {
  children: ReactNode;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}
// Wrong - visual props exposed
interface ButtonProps {
  backgroundColor?: string;  // NO
  fontSize?: string;         // NO
}

2. All Styles Encapsulated

.button {
  background: var(--color-primary);
  padding: var(--spacing-button-padding-y) var(--spacing-button-padding-x);
  font-size: var(--font-size-button);
}

3. Responsive Built-In

.card { padding: var(--spacing-4); }  /* Mobile */
@media (min-width: 768px) { .card { padding: var(--spacing-6); } }  /* Tablet */
@media (min-width: 1024px) { .card { padding: var(--spacing-8); } } /* Desktop */

4. Accessibility Required

<button
  aria-label={iconOnly ? label : undefined}
  aria-busy={loading}
  aria-disabled={disabled}
>

Workflow: Create New Component

Step 0: Extract from design spec (mandatory)

  1. Open the approved local design specification or export
  2. Identify the component and its documented states
  3. Extract: dimensions, padding, colors, typography, effects, border radius
  4. Document ALL extracted values
  5. Compare with existing tokens
  6. Update tokens if design spec differs

Step 1: Classify Level

Is component breakable into smaller parts?
  No  -> ATOM
  Yes -> What does it compose?
    Only Atoms      -> MOLECULE
    Molecules+Atoms -> ORGANISM

Step 2: Create Files

src/design-system/atoms/Button/
  Button.tsx          # Component + Props
  Button.module.css   # All styles (tokens only)
  Button.test.tsx     # Tests
  index.ts            # Export

Step 3: Implement Pattern

Head every component file with the design spec provenance comment:

/**
 * @design-source ./design-spec.md
 * @extracted 2024-01-15
 * All values from design spec - DO NOT MODIFY without designer approval.
 */

Props: content/behavior only, e.g. variant?: 'primary' | 'secondary' | 'ghost' | 'danger', size?: 'sm' | 'md' | 'lg', disabled?, onClick?, children. Styles come from ./Button.module.css via clsx(styles.button, styles[variant], styles[size]). Full template: references/component-templates.md

Checklist Before Delivery

  • Specs extracted from design spec (not guessed)
  • Tokens updated if design spec values differ
  • NO values rounded or improved
  • Visual comparison shows 0% difference from design spec
  • Correct atomic level
  • Uses ONLY semantic tokens
  • Props are content/behavior only
  • Responsive at all breakpoints
  • TypeScript interfaces complete
  • Accessibility attributes
  • design spec link documented

References

FileWhen to Read
tokens/*.jsonNeed specific token values
references/design-deviation-rules.mddesign spec extraction guide
references/design-deviation-rules.mdZero deviation policy
references/atomic-hierarchy.mdComponent examples
references/component-templates.mdCopy-paste templates
references/responsive-patterns.mdResponsive patterns
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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall