@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/design-apple-hig/SKILL.md

@@ -0,0 +1,237 @@
+# Apple Human Interface Guidelines
+
+> Apple's design philosophy covering clarity/deference/depth, vibrancy and material effects, SF Symbols integration, semantic color system, safe area management, and platform-specific navigation patterns across iOS, iPadOS, macOS, watchOS, and visionOS.
+
+## When to Use
+
+- Building native Apple platform apps where adherence to HIG conventions affects App Store review outcomes
+- Implementing a SwiftUI or UIKit component library that must integrate with system-provided materials, vibrancy, and semantic colors
+- Designing navigation architecture for an app targeting multiple Apple platforms (iPhone, iPad, Mac Catalyst, visionOS)
+- Handling safe areas for devices with notches, Dynamic Island, home indicators, and rounded display corners
+- Choosing SF Symbols and configuring their rendering modes, weight matching, and variable color behavior
+
+## Instructions
+
+Apple's HIG is organized around three foundational principles: **clarity** (text is legible at every size, icons are precise, adornments are subtle), **deference** (content is the focus, UI chrome recedes through materials and vibrancy), and **depth** (visual layers and transitions convey hierarchy and position). Unlike Material Design's generative token system, Apple's design language relies on semantic system resources that adapt automatically to appearance (light/dark), accessibility settings (increased contrast, reduced transparency), and device context.
+
+**Key architectural rule:** Never hardcode colors, font sizes, or layout constants. Apple provides semantic resources (`UIColor.systemBackground`, `Font.body`, `safeAreaInsets`) that automatically adapt. Hardcoding `#FFFFFF` for a background means your app breaks in Dark Mode, ignores Increased Contrast, and fails to adapt to platform-specific surface tints.
+
+**Platform divergence is intentional.** A `NavigationSplitView` on iPhone shows a single column with push navigation. On iPad, it shows two or three columns. On Mac, it adds a toolbar. The same semantic component renders differently per platform. Designing for Apple means designing for adaptive presentation, not fixed layouts.
+
+## Details
+
+### Clarity, Deference, and Depth
+
+**Clarity** dictates that every element serves a communicative purpose. Apply the San Francisco (SF Pro) system font at Dynamic Type sizes, not arbitrary point values. SF Pro's optical sizes adjust weight and spacing automatically: at 20pt, SF Pro uses wider letter-spacing than at 11pt, ensuring legibility without manual kerning.
+
+**Dynamic Type scale (default sizes, not accessibility sizes):**
+
+```
+.largeTitle     34pt   weight: regular
+.title1         28pt   weight: regular
+.title2         22pt   weight: regular
+.title3         20pt   weight: regular
+.headline       17pt   weight: semibold
+.body           17pt   weight: regular
+.callout        16pt   weight: regular
+.subheadline    15pt   weight: regular
+.footnote       13pt   weight: regular
+.caption1       12pt   weight: regular
+.caption2       11pt   weight: regular
+```
+
+When the user increases Dynamic Type to AX5 (the largest accessibility size), `.body` scales from 17pt to 53pt. Your layout must accommodate this without truncation. Use `ScrollView` instead of fixed-height containers for text regions.
+
+**Deference** means the UI fades behind content. Apple achieves this through materials -- translucent layers that blur and tint the content behind them. A navigation bar in iOS uses `.regularMaterial` (or `.bar` in UIKit), not an opaque color. The material samples the colors beneath it, creating a contextual background that shifts as the user scrolls.
+
+**Depth** uses layering with distinct z-planes. iOS defines three depth planes: the base content, a raised overlay (sheets, popovers), and an alert level (alerts, action sheets). Each plane has its own material weight: base uses `.systemBackground`, overlays use `.systemGroupedBackground` or `.secondarySystemBackground`, and alerts use `.thickMaterial` for maximum separation.
+
+### Vibrancy and Materials
+
+Materials are translucent layers defined by their blur radius, saturation, and tint. Apple provides five material weights:
+
+```
+.ultraThinMaterial    Minimal blur, maximum transparency    (widgets)
+.thinMaterial         Light blur, high transparency          (inactive overlays)
+.regularMaterial      Balanced blur and tint                 (navigation bars, tab bars)
+.thickMaterial        Heavy blur, reduced transparency       (alerts, action sheets)
+.ultraThickMaterial   Maximum blur, minimal transparency     (full-screen overlays)
+```
+
+**Vibrancy** is a label rendering mode that makes text and icons vibrant against material backgrounds. It amplifies the luminance of content placed on translucent materials so text remains legible regardless of what is behind the blur.
+
+Three vibrancy levels exist:
+
+```
+.primary              Full vibrancy    (titles, primary labels)
+.secondary            Muted vibrancy   (subtitles, secondary text)
+.tertiary             Faint vibrancy   (disabled text, placeholders)
+```
+
+**Concrete implementation in SwiftUI:**
+
+```swift
+ZStack {
+    Image("background")
+        .resizable()
+    VStack {
+        Text("Title")
+            .foregroundStyle(.primary)    // vibrant white/black
+        Text("Subtitle")
+            .foregroundStyle(.secondary)  // muted vibrancy
+    }
+    .padding()
+    .background(.regularMaterial)
+}
+```
+
+**Fallback in Increased Contrast mode:** When the user enables "Increase Contrast" in Accessibility settings, materials become opaque. `.regularMaterial` renders as solid `systemBackground` with no blur. Your layout must not depend on seeing content through the material -- all essential information must be on the foreground layer.
+
+### SF Symbols
+
+SF Symbols is a library of 5,000+ vector icons designed to align with SF Pro text. Every symbol has 9 weights (ultralight through black) and 3 scales (small, medium, large) that automatically match the surrounding text.
+
+**Rendering modes:**
+
+```
+.monochrome        Single color, inherits foreground       (toolbar icons)
+.hierarchical      Single tint, automatic opacity layers   (multi-part icons)
+.palette           2-3 explicit colors you assign          (tab bar, badges)
+.multicolor        Fixed colors defined by Apple           (weather, file types)
+```
+
+**Weight matching rule:** An SF Symbol adjacent to `.body` text (regular weight) renders at regular weight. Adjacent to `.headline` (semibold) it renders semibold. This matching is automatic in SwiftUI when using `Label("Text", systemImage: "icon.name")`. Manual `Image(systemName:)` requires explicit `.fontWeight()` to match.
+
+**Variable color:** Some symbols support continuous fill levels (0.0 to 1.0). `speaker.wave.3` at value 0.33 fills one wave, at 0.66 fills two, at 1.0 fills all three. This enables smooth animations for volume, signal strength, and progress.
+
+```swift
+Image(systemName: "wifi", variableValue: signalStrength)
+    .symbolRenderingMode(.hierarchical)
+    .foregroundStyle(.blue)
+```
+
+**Custom symbol creation:** Export from SF Symbols app as SVG template. The template defines 3 layers (background, base, accent) and 9 weight variants. Each weight variant must be a distinct path -- interpolation between weights is not supported for custom symbols.
+
+### Semantic Colors
+
+Apple defines colors by purpose, not value. The exact hex value changes across platform, appearance, and accessibility setting.
+
+**System background colors (light / dark / increased contrast dark):**
+
+```
+.systemBackground              #FFFFFF / #000000 / #000000
+.secondarySystemBackground     #F2F2F7 / #1C1C1E / #2C2C2E
+.tertiarySystemBackground      #FFFFFF / #2C2C2E / #3A3A3C
+```
+
+**System content colors:**
+
+```
+.label                         #000000 / #FFFFFF
+.secondaryLabel                #3C3C43 at 60% / #EBEBF5 at 60%
+.tertiaryLabel                 #3C3C43 at 30% / #EBEBF5 at 30%
+.quaternaryLabel               #3C3C43 at 18% / #EBEBF5 at 18%
+```
+
+**Tint colors** are the seven system-provided accent colors:
+
+```
+.systemRed       #FF3B30 / #FF453A
+.systemOrange    #FF9500 / #FF9F0A
+.systemYellow    #FFCC00 / #FFD60A
+.systemGreen     #34C759 / #30D158
+.systemBlue      #007AFF / #0A84FF
+.systemIndigo    #5856D6 / #5E5CE6
+.systemPurple    #AF52DE / #BF5AF2
+```
+
+Dark mode tint variants are slightly brighter (higher luminance) than their light mode equivalents. `systemBlue` shifts from `#007AFF` (L*=48) to `#0A84FF` (L*=53) to maintain the same perceived contrast against a dark background.
+
+**Platform differences:** macOS `systemBackground` resolves to `#ECECEC` (a warm gray), not `#FFFFFF`. macOS windows have distinct content backgrounds (`windowBackgroundColor`) that differ from iOS backgrounds. Never assume cross-platform color parity.
+
+### Safe Areas
+
+Safe areas define the region of the screen guaranteed to be unobstructed by hardware (notch, Dynamic Island, rounded corners, home indicator) and system UI (status bar, navigation bar, tab bar).
+
+**iPhone 15 Pro safe area insets:**
+
+```
+Top:      59pt   (status bar + Dynamic Island)
+Bottom:   34pt   (home indicator)
+Leading:  0pt
+Trailing: 0pt
+```
+
+**iPad Pro 12.9" safe area insets (no hardware obstructions):**
+
+```
+Top:      24pt   (status bar only)
+Bottom:   20pt   (home indicator)
+Leading:  0pt
+Trailing: 0pt
+```
+
+**Keyboard safe area:** When the keyboard appears, `safeAreaInset(edge: .bottom)` expands to include the keyboard height (~336pt on iPhone). Use `.safeAreaInset(edge: .bottom)` in SwiftUI or `keyboardLayoutGuide` in UIKit to push content above the keyboard.
+
+**When to ignore safe areas:** Full-bleed images and backgrounds should extend into the unsafe region using `.ignoresSafeArea()`. Content (text, buttons, interactive elements) must never extend into unsafe areas. A common pattern: background ignores safe area, content respects it.
+
+```swift
+ZStack {
+    Color.blue.ignoresSafeArea()        // extends behind notch
+    VStack {
+        Text("Content stays safe")       // respects safe area
+    }
+}
+```
+
+### Platform-Specific Navigation
+
+**iPhone:** `NavigationStack` with push/pop. Tab bar at bottom (maximum 5 tabs). No visible back button label on small screens -- the chevron and swipe-back gesture suffice.
+
+**iPad:** `NavigationSplitView` with 2 or 3 columns. Sidebar collapses in compact width. Tab bar transforms into a sidebar in iPadOS 18+. Popovers replace action sheets.
+
+**Mac (Catalyst / native):** `NavigationSplitView` with toolbar. Menu bar integration. Window resizing. `Settings` scene replaces the iOS settings bundle. Hover states on all interactive elements -- mandatory because Mac has a cursor.
+
+**visionOS:** Ornaments replace toolbars. Content floats in a window at `z: 0`. Modals push to `z: 50pt` depth. Navigation uses tab bars rendered as ornaments below the window. Eye tracking drives hover states -- interactive targets minimum 60pt diameter (larger than iOS 44pt) because eye fixation is less precise than finger touch.
+
+### Anti-Patterns
+
+**Hardcoding hex colors instead of using semantic system colors.** Setting `background: #F2F2F7` works in light mode but becomes invisible in dark mode. Use `.secondarySystemBackground` which resolves to `#F2F2F7` in light and `#1C1C1E` in dark. This also handles Increased Contrast mode automatically. Hardcoded colors fail four adaptations: light/dark, standard/increased contrast.
+
+**Using fixed font sizes instead of Dynamic Type text styles.** Setting `font-size: 17px` ignores the user's preferred content size. When a visually impaired user sets AX3, your text stays at 17pt while system apps scale to 40pt. Use `.font(.body)` which maps to the user's chosen size. Fixed font sizes can also cause App Store review rejection under accessibility guidelines.
+
+**Placing interactive content in unsafe areas.** A "Skip" button at the absolute top of the screen is obscured by the Dynamic Island on iPhone 15 Pro. A floating action button at the absolute bottom overlaps the home indicator. All interactive elements must be within `safeAreaLayoutGuide`. Background decorations may extend outside; buttons, text fields, and links must not.
+
+**Using opaque navigation bars on scrollable content.** iOS navigation bars use `.regularMaterial` by default -- translucent with blur. Overriding with an opaque background color breaks the deference principle and creates a harsh visual boundary. Users expect to see content scroll behind the bar. The exception is when the bar contains complex content (search fields, segmented controls) where blur would reduce legibility.
+
+**Ignoring platform-specific navigation conventions.** Showing a bottom tab bar on macOS (where the convention is a sidebar or toolbar), or using a hamburger menu on iOS (where tab bars are standard), violates user expectations built from using the platform. Each Apple platform has distinct navigation paradigms. A single navigation approach forced across all platforms signals non-native design.
+
+### Real-World Examples
+
+**Apple Weather** exemplifies deference: the background is a full-screen animated weather condition, and all UI elements sit on materials of varying thickness. The hourly forecast uses `.thinMaterial`, the daily forecast uses `.regularMaterial`, and alert banners use `.thickMaterial`. Each layer's legibility is maintained through vibrancy-rendered text.
+
+**Apple Maps** demonstrates safe area handling across every iPhone variant. The floating search card respects bottom safe area insets, expanding upward. On iPad, the same search card becomes a sidebar panel. On Mac, it transforms into a toolbar search field. One semantic component, three platform presentations.
+
+**Fantastical** uses SF Symbols with variable color for event indicators: a circle symbol at `variableValue: 0.5` indicates a half-day event, `1.0` a full-day event. Their calendar icons match the surrounding text weight automatically, scaling from ultralight in the month header to regular in the day cells.
+
+**Things 3** demonstrates the depth principle: the task list sits at base depth, a new-task sheet slides up at overlay depth with `.regularMaterial`, and a delete confirmation alert appears at alert depth with `.thickMaterial`. Each depth transition uses a spring animation (`response: 0.35, dampingFraction: 0.86`) matching the system default.
+
+## Source
+
+Apple Human Interface Guidelines (developer.apple.com/design/human-interface-guidelines, 2024). Apple Developer Documentation for UIKit and SwiftUI. WWDC sessions: "What's new in SF Symbols" (2023), "Design for spatial computing" (2023), "Get started with Dynamic Type" (2022). Apple Design Resources Figma/Sketch libraries.
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/design-apple-hig/skill.yaml

@@ -0,0 +1,37 @@
+name: design-apple-hig
+version: '1.0.0'
+description: Apple Human Interface Guidelines covering clarity/deference/depth, vibrancy and materials, SF Symbols, semantic colors, safe areas, and platform-specific navigation
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-elevation-shadow
+  - design-navigation-ux
+  - design-typography-fundamentals
+stack_signals: []
+keywords:
+  - apple
+  - HIG
+  - human-interface-guidelines
+  - iOS
+  - macOS
+  - SF-Symbols
+  - vibrancy
+  - materials
+  - safe-areas
+  - semantic-colors
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-atomic-design/SKILL.md

@@ -0,0 +1,172 @@
+# Atomic Design
+
+> Composition methodology for building design systems using five distinct levels of abstraction: atoms, molecules, organisms, templates, and pages.
+
+## When to Use
+
+- Starting a new design system from scratch and need a structural taxonomy for components
+- Refactoring an existing component library that has inconsistent granularity
+- Deciding whether a UI element should be a standalone component or part of a larger one
+- Onboarding developers or designers who need a shared vocabulary for component hierarchy
+- Evaluating whether your system is over-atomized (too many tiny pieces) or under-decomposed (too many monoliths)
+
+## Instructions
+
+Apply Brad Frost's atomic design methodology as a mental model for component decomposition, not as a rigid folder structure. The five levels describe a spectrum of complexity and composition. Every component in your system should map to exactly one level, and that mapping should be defensible.
+
+**The decision procedure for level assignment:**
+
+1. Does this element wrap zero child components and render a single HTML concept? It is an **atom**.
+2. Does this element compose 2-4 atoms into a single functional unit with one responsibility? It is a **molecule**.
+3. Does this element compose molecules and/or atoms into a distinct section of interface with its own domain logic? It is an **organism**.
+4. Does this element define the layout and content placement for a full view without real data? It is a **template**.
+5. Does this element hydrate a template with real data, forming the final user-facing screen? It is a **page**.
+
+If you cannot cleanly assign a component to one level, the component likely has mixed responsibilities and should be split.
+
+## Details
+
+### The Five Levels in Depth
+
+**Atoms** are the foundational building blocks. They cannot be broken down further without ceasing to be functional. An atom is self-describing: it has a single visual and semantic purpose.
+
+- A `Button` atom: renders `<button>` with `variant` (primary, secondary, ghost), `size` (sm, md, lg), `disabled`, and `loading` props. It contains no knowledge of where it appears.
+- A `TextInput` atom: renders `<input>` with `label`, `placeholder`, `error`, `helperText`. It does not know it lives in a search bar or a login form.
+- An `Avatar` atom: renders a circular image with `src`, `size` (24px, 32px, 40px, 48px), `fallback` (initials). It does not know it is part of a user card.
+
+Stripe's design system treats `Badge`, `Button`, `Icon`, `Spinner`, and `Text` as atoms. Each has zero child component dependencies.
+
+**Molecules** combine atoms into functional groups. The litmus test: does removing any atom from the molecule break its purpose?
+
+- A `SearchInput` molecule: composes `TextInput` + `Icon` (search) + `Button` (clear). Remove the input and it is not a search bar. Remove the icon and it loses affordance.
+- A `FormField` molecule: composes `Label` + `TextInput` + `HelperText` + `ErrorMessage`. The field is the unit of validation feedback.
+- GitHub Primer's `TextInputWithTokens` is a molecule: `TextInput` + multiple `Token` atoms, composed to handle multi-value input.
+
+**Organisms** are complex, self-contained interface sections. They often have internal state or connect to domain logic.
+
+- A `NavigationHeader` organism: composes `Logo` (atom) + `NavLinks` (molecule) + `SearchInput` (molecule) + `UserMenu` (molecule). It manages responsive collapse behavior internally.
+- Shopify Polaris's `ResourceList` is an organism: it composes `ResourceItem` molecules, handles selection state, sorting, filtering, and bulk actions.
+- Salesforce Lightning's `DataTable` is an organism: it composes `Column`, `Row`, `Cell` atoms/molecules and manages sort, resize, and infinite scroll.
+
+**Templates** define the structural layout of a complete view using placeholder content. They answer "where does each organism go?" without answering "what data fills it?"
+
+- A `DashboardTemplate` places `NavigationHeader` at top, `Sidebar` at left (240px), `MainContent` in a 12-column grid, `Footer` at bottom. All content slots accept children.
+- Material Design's responsive layout grid (12 columns, 8px baseline grid, breakpoints at 600/905/1240/1440px) is a template-level concern.
+
+**Pages** are templates hydrated with real or representative data. They are the final artifact for testing, review, and QA.
+
+- A `DashboardPage` fills `DashboardTemplate` with fetched analytics data, user profile, notification count. This is what Storybook shows under the "Pages" section.
+
+### The Abstraction Decision Framework
+
+The hardest design system decision is choosing the right level of abstraction. Use this framework:
+
+**Reuse frequency test.** Count how many places a component appears in your application. If a molecule appears in only one organism, question whether it needs to be extracted. Premature extraction creates inventory bloat.
+
+| Occurrences | Recommendation                                     |
+| ----------- | -------------------------------------------------- |
+| 1           | Keep inline unless it has independent test value   |
+| 2-3         | Extract if the instances are identical in behavior |
+| 4+          | Extract unconditionally                            |
+
+**Independence test.** Can the component be understood without its parent context? A `PriceTag` molecule (icon + formatted currency + label) is independently meaningful. A `DashboardHeaderLeftSection` is not -- it is a layout fragment, not a reusable concept.
+
+**Stability test.** How often does the component's interface change? Atoms should be extremely stable (change less than once per quarter). Organisms may change monthly. If an atom's props churn frequently, it is probably a molecule or organism in disguise.
+
+### Mapping to File Structure
+
+Atomic design is a mental model, not a mandatory folder layout. Two viable approaches:
+
+**Flat by level** (recommended for systems under 100 components):
+
+```
+components/
+  atoms/       Button, Icon, Text, Avatar, Badge
+  molecules/   SearchInput, FormField, NavLink
+  organisms/   Header, DataTable, Modal
+  templates/   DashboardLayout, SettingsLayout
+  pages/       DashboardPage, SettingsPage
+```
+
+**Grouped by domain** (recommended for systems over 100 components):
+
+```
+components/
+  navigation/  NavLink (molecule), Header (organism), Sidebar (organism)
+  forms/       TextInput (atom), FormField (molecule), LoginForm (organism)
+  data/        Badge (atom), DataTable (organism), Chart (organism)
+```
+
+IBM Carbon uses domain grouping: `DataTable`, `DatePicker`, `Notification` each in their own directory, with sub-components (atoms/molecules) co-located.
+
+### Anti-Patterns
+
+**Over-atomization.** Extracting every `<span>`, `<div>`, or styled wrapper into a component. If your atoms directory has `Wrapper`, `Spacer`, `Divider`, `Container`, and `Box` that are each under 10 lines, you have decomposed past the point of utility. A `Spacer` component with a single `margin` prop is not an atom -- it is a CSS utility masquerading as a component. Tailwind's utility classes or a spacing token solve this better.
+
+**Level-skipping composition.** An organism that directly uses raw HTML elements instead of atoms. If your `Header` organism renders `<button className="...">` instead of using `<Button>`, you have bypassed the system. Every visual element in an organism should trace back to a system atom. Stripe enforces this by making raw HTML elements a linting violation inside organism-level components.
+
+**Template-organism conflation.** Building organisms that assume a specific layout position. A `Sidebar` organism that hardcodes `position: fixed; left: 0; width: 240px` is not reusable -- it has absorbed template-level layout concerns. The sidebar's position should be controlled by the template; the organism should only define its internal layout.
+
+**Premature page extraction.** Creating page-level components before the template layer is stable. Pages are the most volatile level and should be built last. If you start with pages and extract downward, you get organisms shaped to one specific page rather than reusable across templates.
+
+**Molecule bloat.** A molecule that composes 6+ atoms is likely an organism. If your `UserCard` has avatar, name, title, department, email, phone, and action buttons, it has grown past molecule complexity. The test: can you identify two sub-groups within it that are independently meaningful? If yes, those sub-groups are molecules and the whole thing is an organism.
+
+### Cross-Level Dependency Rules
+
+The atomic hierarchy implies strict dependency direction: higher levels depend on lower levels, never the reverse.
+
+**Allowed dependencies:**
+
+```
+Pages -> Templates -> Organisms -> Molecules -> Atoms
+```
+
+**Forbidden dependencies:**
+
+- An atom importing a molecule (e.g., `Button` importing `SearchInput`)
+- A molecule importing an organism (e.g., `FormField` importing `Header`)
+- A template importing a page (templates are data-agnostic)
+
+**Same-level dependencies** are allowed but should be minimized. A molecule can use another molecule (a `DateRangePicker` molecule composes two `DatePicker` molecules), but excessive same-level coupling suggests a missing intermediate abstraction.
+
+**Dependency audit procedure:** For each component, list its imports. If any import is from the same level or higher, flag it for review. GitHub Primer automates this with an ESLint rule that enforces import direction based on directory structure.
+
+### Handling Edge Cases
+
+**Components that span levels.** A `Popover` seems like an atom (it is a single visual element) but it composes internal atoms (arrow, backdrop, content container) and manages complex state (positioning, focus trap). It is a molecule. The test is not visual simplicity but compositional complexity.
+
+**Utility components.** `Portal`, `VisuallyHidden`, `FocusTrap`, and `AnimatePresence` do not fit cleanly into atomic levels because they produce no visible output. Treat them as infrastructure -- they live outside the atomic hierarchy in a `utilities/` directory and can be imported by any level.
+
+**Design tokens as sub-atomic.** Tokens (colors, spacing, typography values) exist below the atomic level. They are the properties that atoms consume, not components themselves. Brad Frost calls them "the protons and neutrons" that make up atoms.
+
+### Real-World Examples
+
+**Shopify Polaris** organizes components into four tiers (Actions, Layout, Navigation, Overlays) but the internal structure follows atomic principles. Their `Button` (atom) is composed into `ButtonGroup` (molecule), which appears inside `Card` headers (organism). The `Page` component is explicitly a template: it defines title area, primary/secondary actions, and a content slot. Their Storybook organizes stories by atomic level, making the hierarchy browsable.
+
+**Atlassian Design System** serves multiple products (Jira, Confluence, Bitbucket) from a shared atomic foundation. Their `@atlaskit/button` atom has 12 appearances (default, primary, subtle, link, etc.) and is composed into toolbar molecules across all products. They found that organisms are the level where product-specific divergence starts -- so atoms and molecules are shared, but organisms may be product-scoped. Their package structure reflects this: `@atlaskit/button` (atom, 1.2M weekly downloads) vs `@atlaskit/jira-issue-view` (organism, Jira-only).
+
+**Material Design 3** defines atoms as "building blocks" (FAB, IconButton, Chip), molecules as "communication" components (Snackbar, Dialog), and organisms as "containment" patterns (Card, NavigationDrawer). Their component spec sheets explicitly list which lower-level components each higher-level component uses, creating a traceable dependency graph. Every M3 component page includes a "Components used" section showing its atomic dependencies.
+
+**Apple Human Interface Guidelines** do not use atomic terminology but follow the same decomposition. SF Symbols are atoms. A `Toggle` with label is a molecule. A `Settings` pane with grouped toggles, navigation, and search is an organism. Apple's platform-specific templates (NavigationSplitView on macOS, TabView on iOS) define the layout skeleton that organisms fill. Their SwiftUI component library enforces composition through view modifiers -- atoms accept modifiers but never compose other named components internally.
+
+**GitHub Primer** maps their React component library to atomic levels in their architecture documentation. `Button`, `Label`, `Avatar`, and `CounterLabel` are atoms. `ButtonGroup`, `AvatarPair`, and `BranchName` are molecules. `ActionMenu`, `Dialog`, and `SelectPanel` are organisms. Their compound component pattern (e.g., `ActionMenu.Button` + `ActionMenu.Overlay`) demonstrates how organisms compose molecules through React context rather than prop drilling.
+
+## Source
+
+Brad Frost, _Atomic Design_ (2016). Chapter 2: "Atomic Design Methodology." The five levels were first proposed as a blog post in 2013 and refined through application across hundreds of design systems. Dan Mall's "Design System in 90 Days" extends the methodology with adoption-focused heuristics.
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/design-atomic-design/skill.yaml

@@ -0,0 +1,35 @@
+name: design-atomic-design
+version: '1.0.0'
+description: Composition methodology for building design systems using atoms, molecules, organisms, templates, and pages
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-component-anatomy
+  - design-design-governance
+stack_signals: []
+keywords:
+  - atomic-design
+  - atoms
+  - molecules
+  - organisms
+  - templates
+  - pages
+  - Brad-Frost
+  - composition
+  - abstraction
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []