@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/design-color-psychology/SKILL.md

@@ -0,0 +1,151 @@
+# Color Psychology
+
+> Emotional and cultural associations of color — warmth/coolness, trust, urgency, industry conventions, and cultural variance for global product design
+
+## When to Use
+
+- Choosing a brand color for a new product or company
+- Evaluating whether a color palette matches the product's intended emotional tone
+- Designing for international audiences where color meanings vary
+- Selecting colors for emotional UI states (error, success, celebration, warning)
+- Understanding why competitor products in your industry converge on similar colors
+- Deciding between warm and cool palettes for a given product category
+- Creating marketing materials where color must drive specific emotional responses
+- Adapting a Western-origin design system for Asian, Middle Eastern, or African markets
+
+## Instructions
+
+1. **Start with arousal, not hue.** The most reliable psychological dimension of color is arousal level, not specific hue meaning. High saturation and warm hues (red, orange, yellow) increase physiological arousal — heart rate, skin conductance, attention. Low saturation and cool hues (blue, green, violet) decrease arousal. This is cross-cultural and physiological, not learned. Decision procedure: if your product needs calm focus (meditation, reading, finance dashboards), use cool, desaturated palettes. If your product needs energy and urgency (gaming, fitness, flash sales), use warm, saturated palettes.
+
+2. **Map hue families to their dominant associations.** These are Western-default associations — see step 5 for cultural overrides:
+
+   | Hue Family                   | Primary Associations                    | Saturation Effect                                             | Industry Conventions                                     |
+   | ---------------------------- | --------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------- |
+   | **Red** (0-15 degrees)       | Urgency, danger, passion, energy        | High S = alarm; Low S (pink) = warmth, care                   | Sales/clearance, food (appetite stimulant), emergency    |
+   | **Orange** (15-45 degrees)   | Enthusiasm, affordability, warmth       | High S = playful; Low S (peach) = friendly, approachable      | Budget brands, food delivery, creative tools             |
+   | **Yellow** (45-70 degrees)   | Optimism, caution, attention            | High S = warning; Low S (cream) = warmth, comfort             | Caution/warning, taxis, children's products              |
+   | **Green** (70-170 degrees)   | Growth, health, nature, success         | High S = vitality; Low S (sage) = calm, organic               | Finance (growth), health, sustainability, success states |
+   | **Blue** (170-260 degrees)   | Trust, stability, calm, professionalism | High S = authority; Low S = serenity, openness                | Finance, healthcare, technology, social media, corporate |
+   | **Violet** (260-310 degrees) | Luxury, creativity, premium, mystery    | High S = bold/confident; Low S (lavender) = gentle, spiritual | Premium fintech, creative tools, beauty, luxury goods    |
+   | **Neutral** (achromatic)     | Sophistication, timelessness, authority | N/A — controlled by lightness                                 | Luxury fashion, premium tech, editorial                  |
+
+3. **Understand why specific brands chose their colors.** Do not memorize color meanings — understand the strategic reasoning:
+   - **Stripe chose violet (`#533afd`)** because fintech traditionally defaults to blue (trust/stability). Stripe needed to signal "we are different" — premium, developer-friendly, innovative. Saturated violet at 98% saturation reads as confident and bold. The choice explicitly breaks the blue-finance convention to position Stripe as a technology company that happens to do payments, not a traditional financial institution.
+
+   - **Calm chose deep blue (`#3B5B8C`)** because the app's entire purpose is relaxation. Blue is the lowest-arousal chromatic hue. The specific shade is desaturated (S:~53%) and dark (L:~38%), which further reduces arousal compared to a bright, saturated blue. Every color choice in Calm reinforces the physiological calm response.
+
+   - **Shopify chose green (`#96BF48` / `#7AB55C`)** because their product is about commerce growth. Green maps to both "money/prosperity" and "growth/nature" — a double association that reinforces Shopify's value proposition. The specific green is warm-leaning (hue ~90) and moderately saturated, giving it an approachable, optimistic quality rather than a cold institutional feel.
+
+   - **Stripe's Deep Navy (`#061b31`)** for headings instead of black adds chromatic warmth to what would otherwise be a cold, clinical interface. Pure black (`#000000`) is achromatic and emotionally neutral — it communicates nothing. Stripe's navy has a blue undertone (hue 213) that subtly reinforces trust and professionalism while feeling more considered and intentional than default black.
+
+4. **Use saturation and lightness to modulate emotional intensity.** The same hue at different saturation/lightness levels produces different emotional responses:
+   - `hsl(0, 100%, 50%)` — pure red — alarm, emergency, "stop"
+   - `hsl(0, 70%, 60%)` — muted red — warmth, energy without panic
+   - `hsl(0, 40%, 75%)` — dusty rose — gentle, nurturing, comfort
+   - `hsl(0, 20%, 90%)` — barely-pink neutral — subtle warmth, no arousal
+
+   Airbnb's coral (`#FF5A5F`, S:100%, L:68%) is technically in the red family but reads as warm and inviting, not alarming — because the high lightness and slight orange shift move it away from danger associations toward hospitality.
+
+5. **Account for cultural variation.** Color meanings are not universal. Critical divergences for global products:
+
+   | Color      | Western                         | East Asian                               | Middle Eastern             | South Asian                        |
+   | ---------- | ------------------------------- | ---------------------------------------- | -------------------------- | ---------------------------------- |
+   | **White**  | Purity, cleanliness, minimalism | Mourning, death (China, Japan, Korea)    | Purity, peace              | Mourning (Hindu tradition), purity |
+   | **Red**    | Danger, urgency, passion        | Luck, prosperity, celebration (China)    | Danger, caution            | Fertility, prosperity, marriage    |
+   | **Yellow** | Caution, optimism               | Imperial, royal (China), courage (Japan) | Happiness, prosperity      | Sacred (turmeric), auspicious      |
+   | **Green**  | Nature, success, go             | Youth, eternity                          | Islam, paradise, fertility | Islam, festivity, nature           |
+   | **Black**  | Elegance, authority, mourning   | Power, mystery, evil                     | Mourning, evil             | Evil, negativity, death            |
+   | **Purple** | Luxury, creativity              | Privilege, wealth                        | Wealth, mourning           | Unhappiness (some regions), wealth |
+
+   Decision procedure: if your product serves a single cultural market, optimize for that market's associations. If global, avoid relying on color alone for meaning — pair with icons, text labels, and shapes that transcend cultural color associations.
+
+6. **Respect industry conventions.** Breaking convention can signal innovation (Stripe's purple in fintech) or create confusion (green for an error state). Rules:
+   - **Semantic colors are near-universal:** Red = error/danger, yellow/amber = warning, green = success/safe, blue = informational. Do not break these for brand consistency — if your brand is red, your error state still needs to feel distinct from your brand color.
+   - **Industry defaults carry trust:** Blue in finance, green in health, orange in food delivery. Breaking these requires deliberate brand strategy with sufficient budget to overcome the convention deficit.
+   - **Dark/neutral in luxury:** Black, charcoal, and gold signal premium positioning. Apple, Chanel, and most luxury automotive brands use achromatic palettes with minimal chromatic accent.
+
+## Details
+
+### The Temperature Spectrum as Design Tool
+
+Color temperature (warm vs. cool) is the most reliable cross-cultural psychological axis. Warm colors (red through yellow, 0-60 degrees) consistently increase perceived energy, urgency, and approach motivation. Cool colors (green through violet, 120-300 degrees) consistently increase perceived calm, distance, and avoidance motivation.
+
+Practical application: combine warm and cool strategically. Stripe places warm CTAs (purple-leaning, which sits at the warm edge of cool) against cool structural elements (navy text, gray backgrounds). The temperature difference creates a natural focal hierarchy — warm elements demand attention, cool elements recede.
+
+Material Design uses temperature for semantic distinction: error red (warm, high arousal = "fix this now") contrasts with informational blue (cool, low arousal = "no action needed"). The temperature difference communicates urgency without requiring the user to read the text.
+
+### Emotional Valence of Neutrals
+
+Neutrals are not emotionally empty — they carry subtle associations based on their undertone:
+
+- **Cool gray (blue undertone, hue ~220):** Professional, technological, clean. Vercel's gray scale uses cool grays, reinforcing a developer-tools identity.
+- **Warm gray (yellow/brown undertone, hue ~40):** Approachable, natural, editorial. Medium uses warm grays that make the reading experience feel physical and bookish.
+- **True neutral (no undertone):** Sterile, clinical, institutional. Pure `#808080` is emotionally flat — almost always inferior to a gray with slight chromatic warmth or coolness.
+
+Stripe's neutral palette has a deliberate slate-blue undertone, connecting the structural grays to the brand navy and creating a unified emotional tone — even the "colorless" parts of the interface feel intentional and premium.
+
+### Anti-Patterns
+
+1. **Cultural Blindness.** Deploying a single-culture color system globally. Example: using white extensively for a wedding product that also serves Chinese, Japanese, or Hindu markets — where white signals mourning. Fix: audit color semantics against your target markets' cultural associations. Use icons and text labels as the primary meaning carriers; let color reinforce, not carry, the meaning.
+
+2. **Category Confusion.** Using colors contrary to their semantic convention. Green for errors, red for success, yellow for informational messages. Even if your brand guide demands it, users have decades of conditioning that red = bad, green = good. Fix: semantic colors (error, warning, success, info) must follow universal convention regardless of brand palette.
+
+3. **Mood Mismatch.** Aggressive, high-saturation warm colors for a product that needs calm focus. Example: a meditation app with a saturated red primary (`#FF0000`) — physiologically counterproductive. Or a flash sale page with desaturated blues — suppressing the urgency the sale needs. Fix: match color arousal level to the user's desired emotional state, not to arbitrary brand preferences.
+
+4. **Saturation Uniformity.** Using the same saturation level for all colors, ignoring that different hues have different perceptual saturation. Blue at S:80% looks less saturated than red at S:80% due to the Helmholtz-Kohlrausch effect (some wavelengths appear brighter at the same luminance). Fix: adjust saturation per hue to achieve _perceptual_ uniformity — use OKLCH or CIELAB color space for calibration.
+
+5. **The "Color Means X" Trap.** Over-indexing on color meaning tables (like the one in step 2) without considering context, saturation, lightness, surrounding colors, and cultural audience. No color has a single fixed meaning. Red means danger _in a warning context_ and love _on a Valentine's card_ and luck _in a Chinese New Year context_. Fix: always interpret color psychology in the full design context, not in isolation.
+
+### Real-World Examples
+
+**Stripe — Violet as Differentiation.** In a sea of blue fintech brands (PayPal `#003087`, Square `#006AFF`, Plaid `#111111`+blue accents), Stripe's `#533afd` violet immediately reads as "not like the others." The color choice was strategic, not aesthetic — it signals developer-forward innovation. The high saturation (98%) communicates confidence, while the violet hue avoids the trusty-but-boring blue convention. Stripe compensates for the lost "trust blue" association by using navy (`#061b31`) for body text — getting the trust signal through a structural color rather than the brand accent.
+
+**Apple — Achromatic Premium.** Apple's product and interface design uses an almost entirely achromatic palette (white, silver, space gray, black) with system semantic colors for functional states. This achromatic base communicates timelessness, premium quality, and technological sophistication. The absence of a chromatic brand color is itself a psychological signal — it says "our product is so recognizable we do not need color to identify ourselves." The system blues, reds, and greens used in iOS are strictly functional, never decorative.
+
+**Spotify — Green Energy on Dark Calm.** Spotify Green (`#1DB954`) is high-saturation (86%), medium-lightness (53%), cool-warm transitional (hue 141 — between cool blue-green and warm yellow-green). It reads as energetic and optimistic — matching the emotional tone of music discovery. Placed against dark backgrounds (`#121212`), the green becomes even more energetically prominent through contrast. The dark surround creates a calm, immersive environment (low arousal) that makes the green interactive elements feel like bursts of energy within a restful space.
+
+**Airbnb — Coral as Belonging.** Airbnb's Rausch (`#FF5A5F`) is technically in the red family (hue 358) but reads as coral — warm, inviting, and approachable. The high lightness (68%) moves it away from alarm-red toward hospitality-warmth. This is deliberate: Airbnb's brand promise is "belong anywhere," and the coral evokes the warmth of welcome. The color sits between red (passion/energy) and pink (care/nurture), occupying a unique psychological position that no standard color label captures. Airbnb reinforces this with warm photography, rounded shapes, and the handwritten Belo logo — every element amplifies the warmth the color initiates.
+
+### Color Psychology in Conversion Optimization
+
+Color psychology directly impacts conversion rates, but the effect is contextual, not absolute. Red buttons do not universally outperform green buttons — what matters is contrast with the surrounding palette and alignment with the action's emotional valence:
+
+- **High-urgency actions** (buy now, limited offer): Warm, saturated colors increase urgency. Amazon's "Buy Now" uses `#FFD814` (yellow-orange) — maximum visual urgency.
+- **Trust-required actions** (sign up, enter payment): Cool, moderate-saturation colors reduce anxiety. Stripe's checkout button uses their brand purple, which balances confidence (saturation) with calm (cool-leaning hue).
+- **Low-commitment actions** (learn more, browse): Neutral or cool, low-saturation colors reduce friction. Ghost buttons (outline-only) with gray or light blue borders minimize psychological commitment.
+
+The key principle: the CTA color should match the emotional state you want the user to be in when they click, not the emotional state you want them to feel about your brand.
+
+## Source
+
+- Elliot, A. J. & Maier, M. A. (2014) — "Color Psychology: Effects of Perceiving Color on Psychological Functioning in Humans" — Annual Review of Psychology
+- Labrecque, L. I. & Milne, G. R. (2012) — "Exciting Red and Competent Blue" — Journal of the Academy of Marketing Science
+- Ou, L. C. et al. (2004) — "A Study of Colour Emotion and Colour Preference" — Color Research & Application
+- Cross-cultural color association studies — Madden, Hewett & Roth (2000)
+
+## Process
+
+1. Identify the emotional tone your product needs to convey and the cultural context of your audience.
+2. Map the desired emotional response to the appropriate hue family, saturation level, and temperature using the tables and decision procedures in this document.
+3. Verify your color choices against cultural variation tables if serving international markets. Ensure color is not the sole carrier of meaning — pair with icons, labels, and shapes.
+
+## 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.
+- **Pairs with:** design-color-harmony (for structural color relationships after emotional direction is set), design-brand-consistency (for maintaining psychological consistency across touchpoints).
+- **Sequencing:** Use this skill first to establish emotional direction, then design-color-harmony for structural relationships, then design-palette-construction for the full production palette.
+
+## Success Criteria
+
+- The chosen color palette's emotional associations align with the product's intended user experience (calm products use cool/desaturated, energetic products use warm/saturated).
+- Color choices can be justified with specific psychological reasoning, not just "it looks nice."
+- Cultural color associations have been audited for all target markets.
+- Semantic colors (error, warning, success, info) follow universal conventions regardless of brand palette.
+- Saturation and lightness modulation is used to control emotional intensity, not just hue selection.
+- Industry color conventions are either respected or deliberately broken with strategic justification.
+- No color carries meaning alone — all color-based communication is reinforced with non-color cues.
+- CTA colors match the emotional valence of the action (urgency for buy, trust for signup, low-commitment for browse).
+- The overall palette arousal level matches the product's intended user state (calm app = cool/desaturated, high-energy app = warm/saturated).
+- Neutral colors have deliberate undertones (warm or cool) that reinforce brand personality, not accidental true-gray.
+- Color psychology rationale is documented in the design system for team alignment and onboarding.

package/dist/agents/skills/claude-code/design-color-psychology/skill.yaml

@@ -0,0 +1,34 @@
+name: design-color-psychology
+version: "1.0.0"
+description: Emotional and cultural color associations — warmth/coolness, trust, urgency, industry conventions
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-color-harmony
+  - design-brand-consistency
+stack_signals: []
+keywords:
+  - color psychology
+  - color meaning
+  - emotional associations
+  - cultural color
+  - warmth
+  - coolness
+  - trust
+  - urgency
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-component-anatomy/SKILL.md

@@ -0,0 +1,243 @@
+# Component Anatomy
+
+> Anatomy of reusable components covering slots, variants, states, sizes, composition vs configuration, compound components, and when to split vs merge.
+
+## When to Use
+
+- Designing a new component's API surface (props, slots, children, events)
+- Deciding between a single configurable component and a compound component pattern
+- Reviewing a component that has accumulated too many props (the "prop sprawl" problem)
+- Determining whether a component should be split into smaller pieces or merged into a larger one
+- Establishing component patterns that will scale across a design system with 50+ components
+
+## Instructions
+
+Every reusable component has an anatomy: the structural parts that make it a coherent, predictable unit. Understanding component anatomy means being able to decompose any component into its slots, variants, states, and sizes -- and knowing which of those should be exposed as API surface vs kept as internal implementation.
+
+**The anatomy decomposition procedure:**
+
+1. **Identify the slots.** What distinct content regions does this component have? A card might have: header, media, body, footer. Each slot is a named area that accepts content.
+2. **Identify the variants.** What mutually exclusive visual forms does this component take? A button might have: primary, secondary, ghost, danger. Only one variant is active at a time.
+3. **Identify the states.** What interactive or data-driven conditions change the component's appearance? A button has: default, hover, active, focus, disabled, loading. States can combine (focused + hover).
+4. **Identify the sizes.** What size scale does this component support? A button might support: sm (32px height), md (40px), lg (48px). Sizes should align with the system's spacing scale.
+5. **Decide the API model.** Does this component use configuration (props) or composition (children/slots) for each dimension?
+
+## Details
+
+### Slots: Content Regions
+
+A slot is a named content area within a component. Slots determine the component's layout structure and define what content consumers can inject.
+
+**Named slot example -- Shopify Polaris Card:**
+
+```tsx
+<Card>
+  <Card.Header title="Orders" actions={[{ content: 'Export' }]} />
+  <Card.Section>
+    <DataTable rows={orders} columns={columns} />
+  </Card.Section>
+  <Card.Section title="Notes" subdued>
+    <TextContainer>Customer notes appear here.</TextContainer>
+  </Card.Section>
+  <Card.Footer>
+    <Pagination hasNext onNext={handleNext} />
+  </Card.Footer>
+</Card>
+```
+
+Polaris's `Card` has four slot positions: Header, Section (repeatable), and Footer. Each is a sub-component that enforces its own internal anatomy while participating in the parent's layout.
+
+**Slot optionality rules:**
+
+- **Required slots:** The component is meaningless without them. A `Dialog` requires a content body.
+- **Optional slots:** The component functions without them but gains capability when they are present. A `Card` works without a footer.
+- **Repeatable slots:** The slot can appear multiple times. `Card.Section` in Polaris is repeatable; `Card.Header` is not.
+
+GitHub Primer's `ActionList` uses a repeatable item slot with optional sub-slots: `ActionList.LeadingVisual`, `ActionList.Description`, `ActionList.TrailingVisual`. Each item's anatomy is: leading visual (optional) + label (required) + description (optional) + trailing visual (optional).
+
+### Variants: Mutually Exclusive Forms
+
+Variants represent distinct visual or behavioral modes. A component can only be in one variant at a time. Variants are typically expressed as a single prop with enumerated values.
+
+**Material Design 3 Button variants:**
+
+| Variant  | Use Case                          | Visual Treatment                             |
+| -------- | --------------------------------- | -------------------------------------------- |
+| Filled   | Primary action, high emphasis     | Solid background, `md.sys.color.primary`     |
+| Outlined | Secondary action, medium emphasis | 1px border, transparent background           |
+| Text     | Tertiary action, low emphasis     | No background, no border                     |
+| Elevated | Primary action needing lift       | Solid background + `md.sys.elevation.level1` |
+| Tonal    | Secondary action with subtle fill | `md.sys.color.secondaryContainer` background |
+
+Each variant defines its own token mapping for background, text color, border, and elevation. The `variant` prop selects which mapping applies.
+
+**Variant decision criteria:**
+
+- If two appearances share the same slots, states, and sizes but differ in visual treatment, they are variants of one component.
+- If two appearances have different slots or fundamentally different behavior, they are different components.
+- A `Button` and an `IconButton` share variants (primary, secondary) but differ in slots (text+icon vs icon-only). Material Design 3 treats them as separate components. This is correct: the slot difference changes the component's anatomy.
+
+### States: Interactive and Data Conditions
+
+States represent conditions that change a component's appearance or behavior without changing its identity. Unlike variants, states can combine.
+
+**Complete state matrix for an interactive component:**
+
+| State    | Trigger         | Visual Change                               | Combines With  |
+| -------- | --------------- | ------------------------------------------- | -------------- |
+| Default  | None            | Base appearance                             | --             |
+| Hover    | Mouse enter     | Background lightens/darkens                 | Focus          |
+| Active   | Mouse down      | Background darkens further                  | Focus          |
+| Focus    | Keyboard tab    | Focus ring (2px, offset 2px, brand color)   | Hover          |
+| Disabled | `disabled` prop | 38% opacity, no pointer events              | -- (exclusive) |
+| Loading  | `loading` prop  | Spinner replaces content, no pointer events | -- (exclusive) |
+| Selected | `selected` prop | Check mark, filled background               | Hover, Focus   |
+| Error    | `error` prop    | Red border, error icon                      | Hover, Focus   |
+
+**State combination rules:**
+
+- **Exclusive states** cannot combine with others: disabled, loading.
+- **Layered states** combine freely: hover + focus, selected + hover + focus.
+- **Data states** (error, selected) persist across interaction states.
+
+Salesforce Lightning defines state tokens per component: `--slds-c-button-color-background-hover`, `--slds-c-button-color-background-active`. Each state has its own token rather than relying on computed modifications (darken by 10%), making states deterministic and themeable.
+
+### Sizes: The Scale Dimension
+
+Components typically support 3-5 sizes that align with the system's vertical rhythm and density. Each size affects height, padding, font size, and icon size proportionally.
+
+**Atlassian Design System button sizes:**
+
+| Size    | Height | Horizontal Padding | Font Size    | Icon Size |
+| ------- | ------ | ------------------ | ------------ | --------- |
+| compact | 24px   | 4px                | 12px/16px lh | 16px      |
+| default | 32px   | 8px                | 14px/20px lh | 20px      |
+| large   | 40px   | 12px               | 14px/20px lh | 24px      |
+
+Size should scale all related dimensions proportionally. A common mistake is scaling only height while leaving padding and font size fixed, producing visually unbalanced components.
+
+**When to support custom sizes:** Almost never. If your system needs a 36px button for one specific context, the answer is usually a new size tier (`md-large`) or re-evaluating the layout, not a `height` prop. Escape hatches like `style={{height: 36}}` break system consistency.
+
+### Composition vs Configuration
+
+The fundamental API design decision: does a component accept its content as props (configuration) or as children/sub-components (composition)?
+
+**Configuration model:**
+
+```tsx
+<Select
+  label="Country"
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'ca', label: 'Canada' },
+  ]}
+  value={selected}
+  onChange={setSelected}
+/>
+```
+
+**Composition model:**
+
+```tsx
+<Select label="Country" value={selected} onChange={setSelected}>
+  <Select.Option value="us">United States</Select.Option>
+  <Select.Option value="ca">Canada</Select.Option>
+  <Select.Separator />
+  <Select.Option value="other" disabled>
+    Other
+  </Select.Option>
+</Select>
+```
+
+**Decision procedure:**
+
+| Criterion                            | Prefer Configuration | Prefer Composition |
+| ------------------------------------ | -------------------- | ------------------ |
+| Content is uniform data              | Yes                  | --                 |
+| Content includes mixed types         | --                   | Yes                |
+| Ordering matters semantically        | --                   | Yes                |
+| Consumer needs conditional rendering | --                   | Yes                |
+| Simple cases dominate (>80%)         | Yes                  | --                 |
+| Slots have custom rendering needs    | --                   | Yes                |
+
+Shopify Polaris migrated `ResourceList` from configuration (`items` prop with render callback) to composition (`ResourceList.Item` children) in v12 because consumers needed conditional items, dividers, and custom sub-groups that the configuration model could not express cleanly.
+
+### Compound Components
+
+Compound components are a set of components that work together to form a complete UI pattern, sharing implicit state through context.
+
+**GitHub Primer ActionMenu as compound component:**
+
+```tsx
+<ActionMenu>
+  <ActionMenu.Button>Menu</ActionMenu.Button>
+  <ActionMenu.Overlay>
+    <ActionList>
+      <ActionList.Item onSelect={handleEdit}>Edit</ActionList.Item>
+      <ActionList.Item onSelect={handleDelete} variant="danger">
+        Delete
+      </ActionList.Item>
+    </ActionList>
+  </ActionMenu.Overlay>
+</ActionMenu>
+```
+
+`ActionMenu`, `ActionMenu.Button`, and `ActionMenu.Overlay` share open/close state through React context. The consumer never manages `isOpen` manually.
+
+**When to use compound components:**
+
+- The parts are meaningless alone (`Tab` without `TabList` is nothing)
+- Shared state should be implicit (open/close, selected index)
+- The assembly order is flexible (header before or after body)
+
+### When to Split vs Merge
+
+**Split a component when:**
+
+- It has more than 8-10 props (Atlassian's heuristic: "if your component's TypeScript interface exceeds the viewport, split")
+- Two prop groups never interact (`icon` and `avatar` are never used together -- make `IconButton` and `AvatarButton`)
+- A boolean prop changes the fundamental structure (`isInline` that completely reorganizes layout indicates two components)
+
+**Merge components when:**
+
+- Two components share 80%+ of their code and differ only by a variant prop
+- Consumers routinely use them together in the same parent (extract the parent as the real component)
+- The "split" created artificial prop drilling between the halves
+
+### Anti-Patterns
+
+**Prop sprawl.** A component with 25+ props that tries to handle every possible configuration. Material UI's `TextField` at one point had 30+ props because it merged input, label, helper text, adornments, and validation into one component. The fix: decompose into compound components (`Input`, `InputLabel`, `FormHelperText`) that compose together.
+
+**Boolean prop explosion.** Using boolean props for what should be a variant enum: `isPrimary`, `isSecondary`, `isGhost`, `isDanger`. This allows invalid states (`isPrimary && isSecondary`). Use `variant: 'primary' | 'secondary' | 'ghost' | 'danger'` instead. Shopify Polaris enforces this with TypeScript discriminated unions.
+
+**God component.** A single component that renders differently based on a `type` prop, where each type has a completely different slot structure. If `<Card type="product">` and `<Card type="user">` have different slots, different states, and different sizes, they are not the same component. They share a name but not an anatomy. Split them.
+
+**Implicit slot ordering.** A component that changes behavior based on the order of children without documenting or enforcing that order. If `<Toolbar>` renders differently when `<ToolbarSearch>` is the first child vs the last, that is implicit coupling. Either enforce order with named slots or make order irrelevant.
+
+### Real-World Examples
+
+**Shopify Polaris `Button`** has a clean anatomy: `variant` (5 options), `size` (3 tiers: slim/medium/large with 28px/36px/44px heights), `tone` (critical for destructive variant), `icon` (optional leading/trailing), `loading`, `disabled`. This is 7 props covering 4 anatomical dimensions. They avoid prop sprawl by keeping icon-only buttons as a separate `IconButton` component.
+
+**GitHub Primer `Dialog`** uses compound components: `Dialog`, `Dialog.Header`, `Dialog.Body`, `Dialog.Footer`, `Dialog.CloseButton`. The header slot is optional (some dialogs are headerless alerts). The footer slot supports left-aligned and right-aligned action groups. State (open/close) flows through context. Width is a variant: `small` (296px), `medium` (480px), `large` (640px), `xlarge` (960px).
+
+**Salesforce Lightning `DataTable`** is the canonical complex organism. Its anatomy includes column definitions (with sort, resize, wrap), row selection (single/multi), inline editing, infinite scroll, and column reordering. Rather than 40+ props, it uses composition: `<DataTable>` wraps `<Column>` children, each column defines its own rendering, sorting, and editing behavior.
+
+## Source
+
+Robin Rendle, "Component API Design" (2021). React documentation on Composition vs Inheritance. Radix UI Primitives documentation on compound component patterns. Shopify Polaris component architecture documentation.
+
+## 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/claude-code/design-component-anatomy/skill.yaml

@@ -0,0 +1,34 @@
+name: design-component-anatomy
+version: '1.0.0'
+description: Anatomy of reusable components covering slots, variants, states, sizes, composition patterns, and compound components
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-atomic-design
+  - design-naming-conventions
+stack_signals: []
+keywords:
+  - component-anatomy
+  - slots
+  - variants
+  - states
+  - sizes
+  - composition
+  - configuration
+  - compound-components
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []