@harness-engineering/cli 1.23.2 → 1.24.0

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

@@ -0,0 +1,35 @@
+name: design-i18n-design
+version: "1.0.0"
+description: Designing for internationalization — text expansion, RTL layout, icon cultural sensitivity, date/number/currency formatting, pseudolocalization
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-responsive-strategy
+  - design-typography-fundamentals
+  - design-content-density
+stack_signals: []
+keywords:
+  - internationalization
+  - i18n
+  - RTL
+  - bi-directional
+  - text-expansion
+  - pseudolocalization
+  - localization
+  - cultural-sensitivity
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,169 @@
+# Iconography
+
+> Icon design principles — optical sizing, stroke consistency, pixel grid alignment, metaphor clarity, icon families, filled vs outlined states, and icon as a systematic visual language
+
+## When to Use
+
+- Building or selecting an icon set for a product or design system
+- Evaluating whether icons are optically consistent across sizes and weights
+- Choosing between filled, outlined, or two-tone icon variants for different contexts
+- Aligning icons to a pixel grid to prevent subpixel rendering blur
+- Designing custom icons that need to feel native to an existing icon family
+- Selecting icon metaphors that communicate function without ambiguity
+- Implementing icon size scales that maintain legibility from 12px to 48px
+- Auditing an icon set for visual weight consistency across different shapes
+
+## Instructions
+
+1. **Design to the pixel grid, not the mathematical center.** Every icon canvas has a pixel grid — typically 16x16, 20x20, or 24x24. Align all straight edges to full pixel boundaries. Diagonal and curved lines are exempt from grid snapping but should start and end on pixel intersections. Decision procedure: at your target render size, export the icon at 1x and zoom to 800%. If any horizontal or vertical edge falls between pixels, the renderer will anti-alias it — producing a blurry 2px line where you intended a crisp 1px line. Apple's SF Symbols enforce a 1px grid at each of 3 scales (small, medium, large) to guarantee sharpness on retina and non-retina displays alike.
+
+2. **Establish a stroke weight system and never deviate.** Stroke weight is the single most visible consistency signal in an icon family. Material Symbols uses a stroke weight axis from 100 to 700 in 100-unit increments. For a typical product icon set at 24px canvas, common stroke weights are:
+   - **1.5px** — light, editorial, minimal (Vercel, Linear)
+   - **2px** — standard, balanced (Feather Icons, Lucide)
+   - **2.5px** — medium, slightly bold (Heroicons outline)
+   - **3px** — bold, high-contrast, touch-friendly (Material Symbols at weight 400)
+
+   Decision procedure: pick ONE stroke weight for your entire icon set. If you need weight variation, define explicit weight tiers (light/regular/bold) with specific pixel values. Never approximate — a 1.75px stroke next to a 2px stroke is visibly inconsistent.
+
+3. **Apply optical sizing, not linear scaling.** A 16px icon is not a scaled-down 24px icon. At smaller sizes, details collapse: 1px gaps disappear, thin strokes become invisible, interior detail becomes noise. Optical sizing means redesigning the icon for each size tier. Apple's SF Symbols provide 3 optical scales:
+   - **Small (≤20pt):** Increased stroke weight, simplified interior detail, larger counters
+   - **Medium (20-26pt):** Standard proportions
+   - **Large (≥26pt):** Finer detail, thinner relative stroke weight, decorative elements preserved
+
+   GitHub's Octicons ship two discrete sizes — 16px and 24px — with different path geometry for each. The 16px `repo` icon has 2 simplified elements; the 24px version has 4 detailed elements. Concrete rule: if your icon set supports sizes below 20px, you need a separate optical variant with at minimum 0.5px thicker strokes and 30-50% fewer interior details.
+
+4. **Choose icon metaphors that survive the 5-second test.** Show the icon to someone unfamiliar with your product for 5 seconds. If they cannot identify the referent or action, the metaphor is too abstract. Proven metaphors:
+   - **Gear** = settings (near-universal, used by iOS, Android, Windows, web)
+   - **Magnifying glass** = search (universal)
+   - **House** = home (universal)
+   - **Pencil** = edit (universal, but "pen" variant can read as "draw")
+   - **Trash can** = delete (universal in Western UI; less clear in some Asian markets)
+   - **Hamburger (three lines)** = menu (learned convention, not intuitive — fails with older or non-tech-savvy users)
+   - **Floppy disk** = save (skeuomorphic holdover — still recognized but increasingly opaque to younger users)
+
+   When no established metaphor exists, prefer a concrete noun over an abstract concept. "Cloud with arrow" for upload is more scannable than an abstract upward-pointing triangle.
+
+5. **Define the filled vs. outlined decision systematically.** Do not mix arbitrarily. The two styles carry different visual weight and semantic implications:
+   - **Outlined icons** — lighter visual weight, recede in the interface, better for navigation bars, toolbars, and inactive states. They read well at medium-to-large sizes (20px+). At small sizes (below 16px), outlines can become indistinct.
+   - **Filled icons** — heavier visual weight, advance in the visual hierarchy, better for active/selected states, CTAs, and small sizes where outline detail would collapse. They carry more brand personality.
+
+   Google's Material Symbols uses filled for selected/active states and outlined for unselected/inactive states — a toggle pattern. iOS Tab Bar follows the same convention: outlined icons for unselected tabs, filled for the active tab. Decision procedure: use outlined as the default state. Switch to filled for selected, active, or emphasized states. Never use filled and outlined versions of the same icon at the same hierarchy level — the weight difference creates unintended emphasis.
+
+6. **Maintain consistent optical weight across shape families.** A circle, a square, and a triangle at the same bounding box size do not appear the same size. Circles and triangles look smaller than squares of identical dimensions — this is a well-documented optical illusion. Compensate:
+   - **Circles** should extend ~2% beyond the square icon's safe zone
+   - **Triangles** should extend ~4-6% beyond the safe zone vertically (apex extends past the grid)
+   - **Tall, narrow shapes** should extend ~2% horizontally past the safe zone
+
+   Material Design's icon grid includes a "trim area" (the full canvas) and a "live area" (where content sits, slightly inset). The live area is 20x20 inside a 24x24 canvas. But circular icons like the `info` circle occupy 22x22 — exceeding the live area — to optically match the weight of square icons that sit within 20x20.
+
+7. **Build icon families, not icon collections.** A family shares DNA: consistent stroke weight, consistent corner radius, consistent level of detail, consistent metaphor style (outline realism vs. geometric abstraction). When adding a new icon to an existing family, match these attributes before matching the concept. A geometrically perfect new icon that has 1px rounded corners in a set using 2px rounded corners will feel foreign regardless of how well-drawn it is. Airbnb's icon system enforces: 2px stroke, 2px corner radius, 24px canvas, no fills, single-color rendering — every icon must pass all five constraints to enter the family.
+
+## Details
+
+### Keyline Shapes and Alignment Grids
+
+Professional icon sets define keyline shapes — canonical bounding geometries that icons are designed around. Material Design defines four keylines for its 24px grid:
+
+| Keyline Shape        | Dimensions | Use Case                                  |
+| -------------------- | ---------- | ----------------------------------------- |
+| Square               | 18x18      | Rectangular content (document, screen)    |
+| Circle               | 20x20      | Circular content (avatar, globe, record)  |
+| Vertical rectangle   | 16x20      | Portrait content (person, bottle, phone)  |
+| Horizontal rectangle | 20x16      | Landscape content (laptop, car, envelope) |
+
+All four keylines produce optically equivalent weight within the 24px canvas. When designing a new icon, first determine which keyline shape it falls into, then draw within that keyline. This prevents the common failure of icons that are technically the same canvas size but visually different weights.
+
+### Icon as Interaction Affordance
+
+Icons in interactive contexts need touch/click targets that exceed their visual bounds. WCAG 2.5.8 requires a minimum 24x24 CSS pixel target size. Apple's HIG recommends 44x44pt minimum. This means:
+
+- A 16px visual icon needs at minimum 24px of tappable area (4px padding per side)
+- A 24px visual icon should have 44px tappable area on mobile (10px padding per side)
+- Interactive icon buttons should declare `min-width` and `min-height` on the button element, not on the icon SVG — the icon stays visually small while the hit target stays accessible
+
+### Stroke Caps and Joins
+
+Seemingly minor stroke attributes create visible inconsistency at scale:
+
+- **Round caps** — strokes end with a semicircle. Adds ~1px visual length to each stroke terminus. Feels softer. Used by Feather Icons, Lucide, and most modern sets.
+- **Square/butt caps** — strokes end flat. Feels more precise and technical. Used in some engineering and drafting-style icon sets.
+- **Round joins** — corners are radiused. Feels friendly and organic. Matches round caps.
+- **Miter joins** — corners are sharp. Feels precise and geometric. Can produce spiky artifacts at acute angles.
+
+Decision procedure: round caps + round joins for consumer products (friendly, approachable). Square caps + miter joins for technical/professional products. Never mix cap styles within an icon family.
+
+### Anti-Patterns
+
+1. **Stroke Weight Drift.** Mixing 1.5px, 2px, and 2.25px strokes within the same icon set because individual designers "eyeballed" the weight. At UI scale, even 0.25px differences are visible and make the set feel unpolished. Fix: define an exact stroke weight in the design system tokens, enforce it in the SVG export pipeline, and lint exported SVGs for stroke-width consistency. Lucide runs automated CI checks that reject contributions with non-conforming stroke weights.
+
+2. **Detail Overload at Small Sizes.** Designing an icon at 48px with fine interior detail (hatching, small counters, thin negative space) and rendering it at 16px where the detail becomes muddy noise. Fix: follow Apple's optical sizing model — create separate path geometry for each size tier. At minimum, remove interior detail and increase stroke weight for any icon rendered below 20px.
+
+3. **Metaphor Ambiguity.** Using a "star" icon for both "favorites" and "ratings" in the same product. Or using a "bell" for both "notifications" and "alarms." When the same visual metaphor maps to two different functions, users cannot build reliable mental models. Fix: one metaphor, one function per product. If you need both favorites and ratings, use a star for one and a heart or bookmark for the other. Document the metaphor map in your design system.
+
+4. **Pixel Grid Misalignment.** Designing icons in Figma at 1x without checking the pixel grid, resulting in paths that fall on half-pixel boundaries. The icon looks crisp in Figma's vector preview but renders blurry in the browser at 1x resolution. Fix: in Figma, enable "Snap to pixel grid" and verify at 1x export. In SVG code, audit path coordinates — values like `x="3.5"` on horizontal edges indicate half-pixel alignment. Round to integers for horizontal/vertical edges.
+
+5. **Filled/Outlined Inconsistency.** Using filled icons for some navigation items and outlined for others at the same hierarchy level, creating unintended visual weight differences that imply hierarchy where none exists. Fix: apply the Material Symbols convention — all icons at the same level use the same variant. Reserve the alternate variant for state changes (active/inactive).
+
+### Real-World Examples
+
+**Apple SF Symbols — The Gold Standard for Optical Sizing.** SF Symbols offers over 5,000 icons with 9 weights (ultralight through black) and 3 scales (small, medium, large), producing 27 variants per symbol. Each variant has unique path geometry — the small-scale, ultralight `gear` has thicker relative strokes and fewer teeth than the large-scale, bold `gear`. The system also supports variable color (progressive fill based on a 0-1 value) and automatic alignment with San Francisco text at any size. SF Symbols enforces a 1px stroke grid at each scale, ensuring pixel-perfect rendering on all Apple displays. Key lesson: optical sizing is not optional — it is the difference between a professional and an amateur icon system.
+
+**GitHub Octicons — Two-Size Discrete System.** Octicons ships exactly two sizes: 16px and 24px. Each size has independent path geometry. The 16px `alert` triangle has 2px strokes and minimal interior detail (just the exclamation mark). The 24px `alert` has 1.5px relative strokes and additional interior structure. GitHub chose discrete sizes over continuous scaling because their UI uses only these two sizes — a pragmatic constraint that eliminates optical sizing edge cases. Key lesson: you do not need a continuous size spectrum. Identify your actual render sizes and optimize for those.
+
+**Material Symbols — Weight and Fill as Axes.** Material Symbols treats stroke weight (100-700), fill (0 or 1), and optical size (20, 24, 40, 48) as independent variable font axes. A single icon file can render at any combination. At weight 400, optical size 24, fill 0: the icon shows 2px outlined strokes. At weight 700, optical size 48, fill 1: the same icon renders as a bold filled shape. This approach eliminates the need for separate icon files per variant — the browser interpolates the correct paths via variable font technology. Key lesson: if your icon system must support many contexts (navigation, content, headers, mobile, desktop), variable axes dramatically reduce maintenance cost.
+
+**Vercel — Minimalist Monochrome.** Vercel's icon set uses 1.5px strokes, no fills, single color (foreground only), and a deliberately constrained vocabulary (~60 icons). Every icon is reducible to 2-3 strokes — the `deploy` icon is a single upward arrow with a horizontal base line. This extreme minimalism aligns with Vercel's brand: developer-focused, no-nonsense, maximally functional. Key lesson: icon family personality comes from constraints. Fewer strokes, fewer icons, tighter rules = stronger visual identity.
+
+**Airbnb Icons — Hospitality Through Roundness.** Airbnb's icon system uses 2px strokes with 2px corner radius — every corner is rounded, every terminal is rounded. This produces icons that feel warm and approachable, matching the "belong anywhere" brand. The roundness is a deliberate departure from the sharp geometric style of tech-company icon sets. Even functional icons like "filter" and "map pin" carry the rounded DNA. Key lesson: corner radius is a brand signal. Sharp corners = precision, authority. Rounded corners = warmth, approachability. The choice must be consistent and intentional.
+
+### Icon Accessibility
+
+Icons carry interaction and meaning, making accessibility non-negotiable:
+
+- **Always pair icons with text labels in navigation.** Unlabeled icon-only navigation (a common pattern in mobile tab bars and sidebar menus) fails for users who cannot map abstract symbols to functions. Nielsen Norman Group research shows that icon + text labels increase discoverability by 88% compared to icon-only interfaces. If space constraints force icon-only display, provide a tooltip on hover/long-press that matches the text label exactly.
+- **Use `aria-label` or `aria-labelledby` on interactive icon buttons.** A button containing only an SVG icon has no accessible name unless explicitly provided. `<button aria-label="Close dialog"><svg>...</svg></button>` is the minimum. Never rely on the icon's visual metaphor for screen reader users.
+- **Decorative icons get `aria-hidden="true"`.** An icon next to a text label that repeats the icon's meaning (a trash can icon next to "Delete") should be hidden from screen readers to avoid redundancy: `<svg aria-hidden="true">`.
+- **Ensure 3:1 contrast ratio for non-text UI.** WCAG 2.2 Success Criterion 1.4.11 requires icons used as interactive affordances to meet 3:1 contrast against their background. A light gray icon (`#9CA3AF`, ~4.5 relative luminance) on a white background (`#FFFFFF`, 21 relative luminance) has a contrast ratio of 2.8:1 — failing the requirement. Use `#6B7280` (4.6:1) or darker.
+
+### SVG Optimization and Delivery
+
+Icon delivery affects both rendering quality and performance:
+
+- **Use inline SVG for interactive icons** that need CSS styling (hover color changes, transitions). Inline SVG allows `currentColor` inheritance and CSS custom property theming. An icon that changes color on hover needs to be inline, not an `<img>` reference.
+- **Use SVG sprite sheets for large icon sets.** A product using 60+ icons should bundle them into a single `<svg>` sprite with `<symbol>` elements, referenced via `<use href="#icon-name">`. This reduces HTTP requests to 1 and enables browser caching of the entire set.
+- **Optimize path data.** Run all production SVGs through SVGO with `removeViewBox: false` (viewBox is needed for responsive scaling) and `removeDimensions: true` (use CSS for sizing). A typical icon SVG optimizes from 800 bytes to 200 bytes — a 75% reduction.
+- **Standardize viewBox.** Every icon in a family must use the same `viewBox` — typically `"0 0 24 24"` for a 24px grid. Inconsistent viewBoxes cause icons to render at different effective sizes even when the CSS `width` and `height` are identical.
+
+### Icon Naming Conventions
+
+A systematic naming convention prevents icon confusion at scale:
+
+- **Format:** `{category}-{object}-{variant}`. Example: `nav-home-filled`, `action-delete-outlined`, `status-check-circle`.
+- **Categories:** `nav` (navigation), `action` (user actions), `status` (state indicators), `content` (content type indicators), `social` (social platform logos).
+- **Variants:** `filled`, `outlined`, `two-tone`, `sharp`. Never use ambiguous suffixes like `v2` or `alt`.
+- **Avoid synonym collision:** If the set has both `close` (X mark) and `cancel` (circle X), the names must clearly distinguish them: `action-close` vs. `action-cancel-circle`.
+
+## Source
+
+- Apple Human Interface Guidelines — SF Symbols (2024)
+- Material Design 3 — Icon Design Principles (2024)
+- GitHub Octicons — Design Guidelines
+- Feather Icons — Design Principles
+- Airbnb Design — Iconography Standards
+- WCAG 2.2 — Non-text Contrast (1.4.11), Name, Role, Value (4.1.2)
+
+## 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-iconography/skill.yaml

@@ -0,0 +1,35 @@
+name: design-iconography
+version: "1.0.0"
+description: Icon design principles — optical sizing, stroke consistency, pixel grid alignment, metaphor clarity, icon families, filled vs outlined, icon as language
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-gestalt-closure-continuity
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - icons
+  - iconography
+  - optical-sizing
+  - stroke-consistency
+  - pixel-grid
+  - metaphor
+  - filled
+  - outlined
+  - icon-family
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-illustration-style/SKILL.md

@@ -0,0 +1,170 @@
+# Illustration Style
+
+> Illustration system design — style consistency, spot vs. hero illustrations, illustration as brand voice, abstract vs. representational choices, and illustration tokens for systematic production
+
+## When to Use
+
+- Building an illustration system for a product or design system
+- Choosing between abstract and representational illustration styles
+- Defining illustration tokens (stroke weight, corner radius, color palette, perspective) for consistency
+- Deciding when to use spot illustrations vs. hero illustrations
+- Evaluating whether an illustration set feels cohesive or like a random collection
+- Commissioning illustrations from multiple artists who must produce visually unified work
+- Creating empty states, onboarding flows, or error pages that need illustration
+- Balancing illustration personality with functional clarity
+
+## Instructions
+
+1. **Choose a position on the abstract-to-representational spectrum and commit.** The spectrum runs from pure geometric abstraction (shapes that suggest concepts without depicting objects) to photorealistic illustration (rendered objects that look like photographs). Most product illustration sits in the middle. Define your position explicitly:
+
+   | Position             | Description                                        | Brands Using It             | Emotional Signal                  |
+   | -------------------- | -------------------------------------------------- | --------------------------- | --------------------------------- |
+   | **Geometric**        | Shapes, lines, gradients — no recognizable objects | Stripe, Vercel, Linear      | Technical, abstract, premium      |
+   | **Flat graphic**     | Simplified objects, no perspective, bold fills     | Shopify, Notion, Asana      | Friendly, clear, systematic       |
+   | **Isometric**        | 3D perspective on a 30-degree grid, flat color     | Dropbox (past), Slack       | Technical, dimensional, organized |
+   | **Hand-drawn**       | Visible brush/pen stroke, imperfect edges          | Basecamp, MailChimp (past)  | Human, casual, approachable       |
+   | **3D rendered**      | Full 3D objects with lighting and materials        | Apple (some), Pitch, Figma  | Polished, premium, contemporary   |
+   | **Representational** | Detailed scene illustration with characters        | Airbnb, Headspace, Duolingo | Narrative, emotional, immersive   |
+
+   Decision procedure: match the illustration style to the brand attribute map. Technical brands (developer tools, analytics) default to geometric or flat graphic. Consumer brands (travel, wellness, education) default to representational or hand-drawn. The critical rule: pick ONE position and enforce it across all illustrations. A product with geometric illustrations on the marketing page and hand-drawn illustrations in the product creates a brand identity split.
+
+   Stripe uses geometric gradients exclusively — flowing color forms that suggest technology and motion without depicting specific objects. The gradients use the brand palette (violet, blue, teal, pink) with consistent noise texture overlay at 3% opacity. No Stripe illustration contains a recognizable real-world object. This is a committed, extreme position on the abstract end.
+
+2. **Define illustration tokens for production consistency.** Just as UI components use design tokens, illustrations need codified parameters that multiple artists can follow:
+   - **Stroke weight:** If your style uses outlines, specify the exact weight. Shopify Polaris illustrations use 1.5px stroke at the default illustration canvas size (200x200px). Scale proportionally for other sizes.
+   - **Corner radius:** Rounded corners on illustrated objects should match the product's UI corner radius. Shopify uses 4px radius on illustration objects, matching the button/card radius.
+   - **Color palette:** Illustrations should use a defined subset of the brand palette. Typically: 1 primary brand color, 2-3 supporting colors, and 1-2 neutral tones. Stripe illustrations use exactly 5 colors per composition, drawn from a palette of 8 brand-adjacent hues.
+   - **Perspective:** Flat (no depth cues), isometric (30-degree 3D), or natural perspective (vanishing point). One perspective system per illustration family.
+   - **Level of detail:** Specify whether objects have interior detail (window panes on buildings, facial features on people) or are silhouette-simple. Notion's illustrations are silhouette-level — people are faceless, objects are reduced to essential contours.
+   - **Shadow and lighting:** Does the illustration system use shadows? What direction is the light source? Material Design illustrations use a consistent top-left light source with 15% opacity drop shadows offset 2px right, 4px down.
+   - **Texture:** Flat fills, noise grain, halftone dots, or gradient fills. Stripe uses subtle gradient fills with 3% noise; Shopify uses flat fills with no texture.
+
+   Document these tokens in a shared specification sheet. When onboarding a new illustrator, the tokens are the briefing — not "make it look like this other illustration."
+
+3. **Distinguish spot illustrations from hero illustrations by function and size.** These are two different classes of illustration with different design constraints:
+
+   **Spot illustrations** — Small (40-120px rendered), inline with content, functional purpose. They appear in:
+   - Empty states ("No results found" with a magnifying glass illustration)
+   - Onboarding steps (a small icon-illustration for each step)
+   - Feature callouts (a spot illustration next to a feature description)
+   - Error states ("Something went wrong" with a sympathetic character)
+
+   Spot illustration constraints: must read at small sizes, must work in single-color or two-color variants, must have transparent backgrounds, must be visually lightweight (they support text, not compete with it). GitHub's empty state illustrations are spot-sized, monochrome (single gray + one accent color), and depict a simple scene (a desert for "no repositories").
+
+   **Hero illustrations** — Large (300px+ or full-bleed), standalone visual anchors. They appear in:
+   - Landing page hero sections
+   - Feature section backgrounds
+   - Blog post headers
+   - Promotional materials
+
+   Hero illustration constraints: must carry visual interest at large scale, can use full color palette, can include detail and complexity, must have a defined focal point. Shopify's marketing pages use hero illustrations that span the full viewport width with multiple overlapping elements, gradients, and brand characters.
+
+   The critical rule: spot and hero illustrations must share the same style tokens (stroke weight, corner radius, color palette, perspective) but differ in complexity and detail level. A spot illustration is not a scaled-down hero illustration — it is a purpose-built simple version.
+
+4. **Use illustration as brand voice amplifier, not decoration.** Every illustration should reinforce the brand personality established in copy and visual design. Test this with the "mute test" — if you removed all text from a page, would the illustrations alone communicate the brand's personality?
+
+   Mailchimp's illustration system (pre-Intuit acquisition) featured Freddie the chimp in various scenarios — wearing a party hat for celebration, looking confused for error states, giving a high-five for success. Each illustration communicated an emotional state that matched the corresponding copy's tone. The illustrations were not decorative — they were a parallel communication channel that reinforced the verbal message.
+
+   Headspace's illustration system uses simple, rounded characters with closed eyes in meditative poses. The style — soft gradients, warm colors, minimal detail, organic shapes — directly communicates "calm, mindful, approachable." The illustrations are functional: they teach meditation postures, visualize breathing exercises, and represent emotional states. Remove the text, and the illustrations still communicate "meditation app."
+
+   Decision procedure: for each illustration placement, ask: "What does this illustration communicate that the text does not?" If the answer is "nothing — it just looks nice," the illustration is decorative and should either be removed or reworked to carry meaning.
+
+5. **Build an illustration component library with atomic elements.** Illustration systems scale when they are composable — built from reusable elements that combine into scenes:
+   - **Characters:** Define 1-3 character archetypes with specified body proportions, head-to-body ratio, and level of facial detail. Shopify's illustrations use a single character archetype: 4-head-tall proportion, circular head, no facial features, solid-fill clothing in brand colors.
+   - **Objects:** Common props (laptops, phones, boxes, plants, clouds) drawn once and reused across illustrations. Define each object at a canonical size relative to the character.
+   - **Environments:** Background elements (desks, rooms, landscapes) that establish context. Define 3-5 environment templates that illustrators compose characters and objects into.
+   - **Decorative elements:** Confetti, stars, lines, shapes that add energy without content meaning. Define a small set (5-8 elements) that appear consistently.
+
+   Duolingo's illustration system is highly composable: the Duo owl character, supporting animal characters, speech bubbles, hearts, and geometric backgrounds are independent components assembled into hundreds of scenes. New illustrations do not require new assets — they recombine existing components in new arrangements.
+
+6. **Define the illustration-to-UI boundary.** Where does the illustration end and the UI begin? Unclear boundaries create visual confusion:
+   - **Illustrations should not contain UI elements.** An illustration showing a "screenshot" of the product with a visible button creates confusion — is the button in the illustration clickable? It looks like a button but is an image.
+   - **Illustrations should not overlap interactive elements.** A hero illustration that partially covers a CTA button creates a z-index visual conflict. Keep illustrations within their container bounds or ensure clear separation from interactive zones.
+   - **Illustrations should respond to theme.** If the product supports dark mode, illustrations must have dark mode variants. An illustration with a white background on a dark-mode page is a visual break. Define how each illustration token adapts: background becomes transparent or dark, stroke colors invert or adjust for contrast, fill colors shift to dark-mode palette equivalents.
+
+   Notion handles theme adaptation by using illustrations with transparent backgrounds and a limited palette that works on both light and dark surfaces. The illustrations use the same foreground colors in both themes, relying on the background contrast to maintain readability.
+
+## Details
+
+### Illustration as Information Design
+
+Beyond decoration and brand expression, illustration can encode information more effectively than text in specific contexts:
+
+- **Process diagrams:** A 4-step onboarding flow with spot illustrations is scanned faster than 4 paragraphs of text. Each illustration anchors a step in visual memory.
+- **Conceptual metaphors:** Abstract concepts (security, performance, scalability) are more quickly grasped through metaphor illustration (a shield, a rocket, expanding circles) than through description.
+- **Emotional states:** Error, success, empty, and loading states communicate faster through character expression (confused face, celebration pose, searching gesture) than through text alone.
+
+The key constraint: informational illustrations must pass the 2-second comprehension test. Show the illustration to someone for 2 seconds and ask what it communicates. If they cannot answer, the illustration is too abstract or the metaphor is unclear.
+
+### Commissioning and Style Enforcement
+
+When working with multiple illustrators (internal team, freelancers, agencies), style drift is the primary risk. Enforcement mechanisms:
+
+- **Style spec sheet:** A 1-2 page document with token values (stroke weight: 1.5px, corner radius: 4px, palette: [6 hex values], perspective: flat, shadow: none). Include 3 reference illustrations that exemplify the tokens.
+- **Redline review:** Before final delivery, overlay the illustration on the token grid. Check stroke weight consistency (measure in the vector file), color compliance (every fill should match a palette hex), and proportion consistency (character height matches the spec).
+- **Illustration library in Figma/design tool:** Provide approved components (characters, objects, environments) as Figma components. Illustrators compose from these rather than drawing from scratch — eliminating the most common source of style drift.
+
+### Anti-Patterns
+
+1. **Style Mixing.** Using flat graphic illustrations on the marketing site, isometric illustrations in the product, and hand-drawn illustrations in the blog. The user experiences three different visual personalities, which fragments brand identity. Fix: pick one style position (step 1) and enforce it across all touchpoints. If the marketing site needs a different emotional register than the product, use complexity variation (hero vs. spot) rather than style variation.
+
+2. **Illustration as Afterthought.** Adding illustrations to a finished page to "make it look less boring." These illustrations are disconnected from the content, inconsistent in style, and often sourced from generic illustration libraries (unDraw, Blush) without customization. The result: the illustrations feel like clip art. Fix: plan illustration placements during the wireframe stage, define what each illustration must communicate, and commission or customize to match the brand's illustration tokens.
+
+3. **Overcomplicated Spot Illustrations.** A spot illustration for an empty state that contains 15 objects, 8 colors, a detailed background, and a full scene composition — but renders at 80px wide where none of this detail is visible. The illustration becomes a blob of color at its actual display size. Fix: spot illustrations at sub-120px sizes should use 2-3 colors maximum, 1-2 objects, no background, and simplified contours that remain legible at small scale. Test every spot illustration at its actual render size.
+
+4. **No Dark Mode Adaptation.** Illustrations designed for light backgrounds with white fills, light shadows, and pastel colors. In dark mode, the white areas become blinding rectangles that break the visual flow. Fix: design illustrations with transparent backgrounds and colors that maintain contrast in both light and dark themes. Or produce explicit light/dark variants where fill colors are swapped to dark-mode equivalents.
+
+5. **Decorative Overload.** Every page, every section, every card has an illustration — including contexts where illustration adds no communication value (a settings page, a data table, a form). Illustration fatigue sets in, and users learn to ignore the illustrations entirely. Fix: use illustration strategically in high-impact moments (onboarding, empty states, error states, marketing heroes) and leave functional screens unillustrated. The absence of illustration in functional contexts makes its presence in emotional contexts more impactful.
+
+### Real-World Examples
+
+**Stripe — Geometric Gradient as Brand Art.** Stripe's illustrations are not illustrations in the traditional sense — they are abstract gradient compositions. Flowing color forms in violet, blue, teal, and pink suggest motion, technology, and premium quality without depicting anything concrete. The gradients use a consistent production technique: layered mesh gradients with 3% noise grain, rendered at high resolution and clipped to geometric containers. The style requires no character design, no object library, and no scene composition — it is purely about color, form, and movement. This makes it highly scalable (new illustrations are new gradient compositions, not new drawings) and impossible to produce "off-brand" (the token constraints are so tight that any gradient in the brand palette with the standard noise feels like Stripe). Key lesson: the most enforceable illustration style is the most constrained one.
+
+**Shopify Polaris — Systematic Flat Illustration.** Shopify's Polaris design system includes a complete illustration library built from composable components: a character archetype (4-head proportion, circular head, no face), a set of merchant objects (boxes, storefronts, phones, charts), and environment templates (desk scene, outdoor scene, abstract background). Every illustration uses the same 1.5px stroke weight, 4px corner radius, and 6-color palette subset. New illustrations are assembled from existing components — a "shipping" illustration combines the character, a box, and a delivery truck from the object library. Illustrators follow a spec sheet that defines exact proportions, colors, and composition rules. Key lesson: composability is the scaling strategy for illustration systems.
+
+**GitHub — Mona and the Octocat Universe.** GitHub's illustration system centers on Mona (the octocat mascot) and a cast of supporting characters. Mona appears in spot illustrations (empty states, success messages) and hero illustrations (marketing, GitHub Universe conference). The style uses clean outlines, flat fills with subtle gradients, and consistent character proportions. Mona's expressions communicate emotional states: confused (404 page), happy (successful deployment), determined (GitHub Actions). The mascot approach gives GitHub a memorable visual voice that transcends individual illustrations. Key lesson: a mascot character provides automatic brand recognition and emotional range.
+
+**Vercel — Abstract Minimalism.** Vercel uses almost no representational illustration. Visual accents are geometric: circles, lines, gradients, and the triangle logo itself used as a decorative motif. Marketing pages use animated geometric patterns (dots that connect, lines that flow) rather than illustrated scenes. This extreme restraint matches Vercel's developer-focused, no-nonsense brand. The visual message: "we are too serious for whimsical illustrations." Key lesson: choosing not to illustrate is an illustration strategy — the absence of illustration communicates as strongly as its presence.
+
+**Headspace — Illustration as Product.** Headspace's illustrations are not supporting content — they ARE the product experience. Meditation sessions are accompanied by animated illustrations that guide breathing (expanding/contracting circles), visualize focus (a moving light in darkness), and represent emotional states (a character surrounded by storm clouds that gradually clear). The style — soft gradients, rounded organic shapes, warm colors, minimal detail — was designed specifically to reduce cognitive load during meditation. Every illustration decision serves a therapeutic function. Key lesson: when illustration IS the experience (not just supporting it), the style must be designed for the use context, not just the brand.
+
+### Illustration Performance and Delivery
+
+Illustration delivery impacts page performance differently depending on format:
+
+- **SVG for flat/graphic illustrations.** Flat illustrations with solid fills, clean paths, and limited gradients compress excellently as SVG. A typical spot illustration is 2-5KB as optimized SVG vs. 20-50KB as PNG. SVG scales infinitely (sharp on 4K displays without 2x/3x variants), supports CSS theming (change colors via custom properties for dark mode), and animates natively.
+- **PNG/WebP for complex illustrations.** Illustrations with gradients, textures, noise grain, or photographic elements may have simpler file representations as raster images. The break-even point: if the SVG path data exceeds 50KB, a well-compressed WebP at 2x resolution is likely smaller and renders faster.
+- **Lottie for animated illustrations.** Complex illustration animations (character movements, scene transitions, micro-interactions) should use Lottie (JSON-based animation from After Effects). A 3-second Lottie animation is typically 10-30KB — dramatically smaller than GIF or video alternatives. Headspace uses Lottie for all their meditation guide animations.
+- **Lazy loading for below-fold illustrations.** Hero illustrations load eagerly (`fetchpriority="high"`). Spot illustrations below the fold use `loading="lazy"` to avoid blocking initial page render. For SVG illustrations loaded as `<img>` tags, lazy loading works natively. For inline SVGs, use Intersection Observer to inject the SVG markup when the container enters the viewport.
+
+### Illustration Versioning and Deprecation
+
+As brand evolves, illustration style may shift. Managing the transition:
+
+- **Version illustration style in the design system.** Tag each illustration with its style version (e.g., `style: v2.0`). When a new style is introduced, existing illustrations continue to render correctly while new illustrations follow the updated tokens.
+- **Prioritize replacement by visibility.** Replace marketing hero illustrations first (highest traffic, strongest brand impression), then product empty states, then onboarding, then edge-case error states. A gradual rollout prevents the jarring effect of overnight style changes.
+- **Maintain a deprecation registry.** List every illustration using the old style with its location, size, and replacement priority. Track migration progress: "42/60 illustrations migrated to v2.0 style."
+
+## Source
+
+- Shopify Polaris — Illustration Guidelines
+- GitHub Brand Guidelines — Illustration
+- Material Design 3 — Illustration Guidance
+- Mailchimp Brand Assets — Illustration Style Guide
+- Alice Lee — "Building an Illustration System" (Design Systems Conference, 2019)
+
+## 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-illustration-style/skill.yaml

@@ -0,0 +1,34 @@
+name: design-illustration-style
+version: "1.0.0"
+description: Illustration system — style consistency, spot vs hero illustrations, illustration as brand voice, abstract vs representational, illustration tokens
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-brand-consistency
+  - design-iconography
+stack_signals: []
+keywords:
+  - illustration
+  - style-system
+  - spot-illustration
+  - hero-illustration
+  - brand-voice
+  - abstract
+  - representational
+  - illustration-tokens
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []