@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/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/cursor/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/cursor/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: []

package/dist/agents/skills/cursor/design-imagery-photography/SKILL.md

@@ -0,0 +1,172 @@
+# Imagery and Photography
+
+> Image in design — art direction, aspect ratios, focal point composition, image treatments (duotone, overlay, blur), placeholder strategy, and the role of image as hero vs. supporting element
+
+## When to Use
+
+- Defining image art direction for a product, marketing site, or editorial platform
+- Choosing aspect ratios for responsive image containers across breakpoints
+- Selecting or commissioning photography that aligns with brand tone
+- Applying image treatments (duotone, gradient overlays, blur) for visual consistency
+- Designing placeholder and loading states for image-heavy interfaces
+- Deciding when an image should dominate the layout (hero) vs. support text content
+- Building an image style guide for a design system
+- Evaluating whether product photography communicates the intended emotional tone
+
+## Instructions
+
+1. **Define art direction before sourcing images.** Art direction is the set of constraints that makes 100 different photographs feel like they belong to the same product. Without it, every image is an independent aesthetic decision. Define these attributes explicitly:
+   - **Subject matter:** What is in the frame? People, products, landscapes, abstract textures?
+   - **Color temperature:** Warm (golden hour, tungsten) or cool (overcast, blue hour, fluorescent)?
+   - **Contrast level:** High contrast (dramatic shadows, punchy blacks) or low contrast (soft, flat, editorial)?
+   - **Depth of field:** Shallow (blurred background, subject isolation) or deep (everything in focus, environmental)?
+   - **Composition style:** Centered, rule-of-thirds, asymmetric, negative space dominant?
+   - **Human presence:** Faces visible, silhouettes, hands only, no people?
+
+   Airbnb's art direction specifies: warm color temperature, natural lighting, shallow-to-medium depth of field, human presence with faces visible, environments that feel lived-in (not staged). Every listing photo that matches these constraints reinforces the brand; every photo that violates them feels off-brand.
+
+2. **Choose aspect ratios systematically, not per-image.** Aspect ratios are layout constraints, not creative decisions. Define a small set of ratios for your product and use them consistently:
+
+   | Ratio | Decimal | Use Case                                                    |
+   | ----- | ------- | ----------------------------------------------------------- |
+   | 1:1   | 1.0     | Avatars, thumbnails, Instagram-style grids, product squares |
+   | 4:3   | 1.33    | Traditional photography, cards, content thumbnails          |
+   | 3:2   | 1.5     | 35mm photography standard, editorial, landscape cards       |
+   | 16:9  | 1.78    | Video, hero banners, widescreen presentations               |
+   | 21:9  | 2.33    | Ultrawide hero banners, cinematic crops                     |
+   | 2:3   | 0.67    | Portrait cards, mobile-first hero images, book covers       |
+   | 9:16  | 0.56    | Stories format, mobile full-screen, vertical video          |
+
+   Decision procedure: pick 2-3 ratios for your product. Use the same ratio for all instances of a component type. A card grid should never mix 4:3 and 16:9 cards — the inconsistency disrupts the layout rhythm. Stripe uses 16:9 for product screenshots and 1:1 for team/avatar photos — two ratios, consistently applied.
+
+3. **Compose images around a single focal point.** Every image needs one dominant subject that the eye locks onto first. Measure focal point effectiveness with the "squint test" — squint until the image blurs and see what remains prominent. If nothing stands out, the image lacks a focal point.
+   - **Rule of thirds:** Place the focal point at one of the four intersection points of a 3x3 grid overlay. This creates dynamic tension and prevents the static feel of dead-center composition.
+   - **Negative space direction:** The focal point should have breathing room in the direction it faces or moves. A person looking right needs more space on the right side of the frame.
+   - **Text overlay consideration:** If text will be placed over the image, the focal point must not compete with the text zone. Apple's product hero images place the device in the lower 60% of the frame, leaving the upper 40% as a clean gradient zone for headline text.
+
+4. **Apply image treatments for brand cohesion, not decoration.** Treatments are systematic filters that normalize disparate source imagery into a unified visual language:
+   - **Duotone** — Maps the image's luminance range to two colors (shadow color and highlight color). Spotify uses duotone aggressively: editorial playlist covers map artist photos to brand-adjacent color pairs (e.g., deep purple shadows + electric green highlights). Duotone provides: strong brand reinforcement, visual unity across diverse source images, and automatic color palette compliance. Implementation: `mix-blend-mode: multiply` on a gradient overlay, or CSS `filter: grayscale(100%)` combined with a colored overlay.
+   - **Color overlay** — A semi-transparent color layer over the image. Simpler than duotone, maintains some photographic realism. Use 40-70% opacity for text-over-image readability. Stripe applies blue-tinted overlays (`rgba(6, 27, 49, 0.6)`) on product screenshots to integrate them with the page's navy color scheme.
+   - **Blur** — Background blur (`backdrop-filter: blur(20px)`) creates depth and hierarchy. Apple's iOS uses blur extensively for layered surfaces. Use blur to de-emphasize background images when foreground content needs focus. Avoid blur values below 8px — they look like rendering errors rather than intentional effects.
+   - **Grain/noise** — Adds a subtle film-grain texture. Humanizes digital imagery, adds tactile quality. Use at 3-8% opacity for subtlety. Above 10%, grain dominates and degrades image quality.
+
+5. **Design image placeholders as first-class UI states.** Users see placeholders during loading, on error, and when no image exists. Each state needs deliberate design:
+   - **Loading placeholder:** Use a solid color matching the image's dominant color (extract via server-side color analysis), a low-resolution blurred preview (LQIP — 20x20px inline base64 scaled up with CSS blur), or a skeleton shimmer animation. Facebook pioneered the shimmer placeholder — a gradient animation that signals "content is coming" without committing to a shape.
+   - **Error placeholder:** A branded fallback — not a broken image icon. Use a solid brand color with a subtle icon (camera with X, or brand logo at low opacity). Never show the browser's default broken-image icon.
+   - **Empty state placeholder:** When no image has been uploaded, show an actionable prompt (dashed border with "Add photo" text and camera icon) rather than a blank space.
+
+   Concrete implementation: use `<img>` with `loading="lazy"`, `decoding="async"`, a `background-color` matching the image's average color, and an `onerror` handler that swaps to the branded fallback. The CSS `aspect-ratio` property on the container prevents layout shift during loading.
+
+6. **Distinguish hero images from supporting images in layout weight.** Hero images dominate the viewport and establish emotional tone. Supporting images illustrate specific content without commanding attention.
+
+   | Attribute         | Hero Image                         | Supporting Image                           |
+   | ----------------- | ---------------------------------- | ------------------------------------------ |
+   | Viewport coverage | 60-100% of viewport width          | 25-50% of column width                     |
+   | Aspect ratio      | Wide (16:9, 21:9) or full-bleed    | Standard (4:3, 3:2, 1:1)                   |
+   | Text overlay      | Common — headline + CTA over image | Rare — text adjacent, not overlaid         |
+   | Image quality     | Maximum resolution, art-directed   | Adequate resolution, may be user-generated |
+   | Count per page    | 1 (at most 2 in long-scroll pages) | Multiple                                   |
+   | Loading priority  | `fetchpriority="high"`, eager load | `loading="lazy"`, low priority             |
+
+   Apple's product pages use exactly one hero image per section — the iPhone floating on a black background, full-bleed, no competing elements. Below it, supporting images show specific features at 50% viewport width with adjacent text blocks.
+
+## Details
+
+### Responsive Image Art Direction
+
+Different viewport sizes may need different crops, not just scaled versions of the same image. The `<picture>` element with `<source>` tags enables art direction:
+
+```html
+<picture>
+  <source media="(min-width: 1024px)" srcset="hero-wide.jpg" />
+  <source media="(min-width: 640px)" srcset="hero-medium.jpg" />
+  <img src="hero-mobile.jpg" alt="Product showcase" />
+</picture>
+```
+
+The wide crop might show the full product in context (16:9). The medium crop centers on the product (4:3). The mobile crop is a tight vertical crop of just the product face (2:3). This is not responsive scaling — it is three different compositions optimized for three viewport contexts. Airbnb uses art direction for listing hero images: desktop shows the full room (16:9), mobile shows a tighter crop focused on the most compelling detail (4:3).
+
+### Image Performance as Design Constraint
+
+Image file size directly impacts perceived design quality because slow-loading images degrade the experience. Design constraints:
+
+- **Hero images:** Target 200KB maximum for LCP (Largest Contentful Paint). Use WebP or AVIF format. AVIF achieves ~50% smaller files than JPEG at equivalent quality.
+- **Thumbnails:** Target 15-30KB each. Generate server-side at exact display dimensions — never send a 2000px image for a 200px thumbnail.
+- **LQIP previews:** 200-500 bytes inline base64. A 20x20px JPEG at quality 20 is ~300 bytes and, when scaled with CSS blur, creates an effective placeholder.
+- **Cumulative Layout Shift:** Always declare `width` and `height` attributes on `<img>` tags, or use `aspect-ratio` CSS on containers. A hero image that causes 0.15 CLS (shifting the headline down by 400px on load) feels broken regardless of its artistic quality.
+
+### Anti-Patterns
+
+1. **Aspect Ratio Chaos.** A card grid where each card uses whatever aspect ratio the source image happens to be — some 4:3, some 16:9, some 1:1 — creating a ragged, uneven layout. Fix: enforce a single aspect ratio per component type using CSS `aspect-ratio` and `object-fit: cover`. Crop the image to fit the container, never stretch or letterbox.
+
+2. **Unanchored Text Overlays.** Placing white text over a photograph without a scrim, gradient, or sufficient contrast zone. The text is legible over the dark tree but disappears over the bright sky. Fix: always apply a gradient scrim (`background: linear-gradient(to top, rgba(0,0,0,0.7) 0%, transparent 60%)`) from the text edge toward the image. Apple uses a bottom-to-top black gradient on every text-over-image hero, ensuring minimum 4.5:1 contrast ratio regardless of image content.
+
+3. **Decorative Images Without Alt Text Strategy.** Marking all images as `alt=""` (decorative) or giving all images verbose literal descriptions. Neither is correct universally. Fix: hero images that convey emotional tone should have brief, contextual alt text ("Team collaborating in a sunlit office"). Decorative texture or pattern backgrounds should have `alt=""`. Product images should have descriptive alt text that adds information not available in adjacent text.
+
+4. **Stock Photo Uncanny Valley.** Using obviously staged stock photography — perfectly diverse groups of smiling people in a pristine office — that reads as inauthentic. Users have developed strong pattern recognition for stock photography and subconsciously distrust it. Fix: commission custom photography with real employees/users, use candid rather than posed shots, or use abstract/illustrated imagery that does not pretend to be photographic.
+
+5. **Loading State Neglect.** No placeholder during image load, resulting in layout shift and a flash of empty space. On slow connections, the page is broken for 2-5 seconds. Fix: implement LQIP (Low Quality Image Placeholder) with inline base64 blur-up, use CSS `aspect-ratio` to reserve space, and add skeleton shimmer animation for content-heavy grids.
+
+### Real-World Examples
+
+**Apple — Photography as Product.** Apple's product photography is the product page. The iPhone is the hero — shot on black or white backgrounds with controlled studio lighting, no environmental context, zero distractions. The device fills 60-80% of the viewport. Text is minimal and placed above or below, never competing with the product. Color accuracy is critical — the "Midnight" iPhone must look identical across apple.com, the Apple Store app, and physical retail displays. Apple achieves this with ICC color profiles embedded in every image and strict display calibration standards. Key lesson: when the product is the visual, image quality IS brand quality.
+
+**Spotify — Duotone as Brand System.** Spotify's editorial playlists (RapCaviar, Today's Top Hits, Discover Weekly) apply duotone treatments to artist photography, mapping the image to two-color palettes that shift seasonally. The treatment transforms diverse source photography — candid concert shots, studio portraits, street photography — into a unified visual system. Each playlist has a signature color pair (RapCaviar: black + gold; Discover Weekly: greens). The duotone treatment is so strongly associated with Spotify that users recognize it outside the app. Key lesson: a strong image treatment can become a brand asset more recognizable than a logo.
+
+**Airbnb — Warm Photography as Brand Promise.** Every listing photo on Airbnb is evaluated against art direction guidelines: warm color temperature, natural light, human-scale perspective (shot from eye level, not drone height), and environmental context (the room in use, not sterile and empty). Airbnb's photo quality directly correlates with booking rates — listings with professionally shot photos following these guidelines see 40% more bookings. The platform provides host photography guides that encode these art direction principles for non-professional photographers. Key lesson: art direction is not just for marketing — it is a product quality metric.
+
+**Vercel — Monochrome Imagery as Developer Identity.** Vercel uses almost exclusively monochrome or desaturated imagery. Product screenshots are rendered in dark-mode with the Vercel color palette. Marketing photography, when used, is desaturated and cool-toned. The restraint signals developer seriousness — "we do not dress up our product with colorful imagery because the product speaks for itself." Key lesson: the absence of vibrant photography is itself an art direction decision.
+
+### Image Accessibility Beyond Alt Text
+
+Accessible imagery extends beyond alt text to include:
+
+- **Color independence:** Images that encode information through color alone (a chart screenshot, a map with color-coded regions) must have supplementary text or non-color encodings. A product screenshot showing a red error banner should include alt text that describes the error state, not just "product screenshot."
+- **Motion and autoplay:** Hero images implemented as video loops or animated GIFs must respect `prefers-reduced-motion`. Provide a static fallback: `<picture><source media="(prefers-reduced-motion: no-preference)" srcset="hero-animated.webm" type="video/webm" /><img src="hero-static.jpg" alt="..." /></picture>`.
+- **Text in images:** Avoid baking text into images. Text rendered as part of a photograph or illustration cannot be resized, translated, or read by screen readers. If text must appear over an image, use HTML text with CSS positioning — never Photoshop the text into the image file.
+- **Flashing content:** Images or videos with flashing content (strobe effects, rapid color changes) can trigger seizures. WCAG 2.3.1 requires no more than 3 flashes per second. This applies to animated hero images, parallax scroll effects, and autoplay video backgrounds.
+
+### Image Governance at Scale
+
+Products with user-generated or editorial imagery need governance to maintain art direction:
+
+- **Automated quality gates:** Use server-side image analysis to enforce minimum resolution (reject uploads below 1200px on the long edge), aspect ratio compliance (auto-crop to the component's target ratio), and file size limits (reject uncompressed TIFFs).
+- **Color analysis for consistency:** Extract the dominant color palette from uploaded images and flag those that deviate significantly from the brand's color temperature. Airbnb uses color analysis to surface listing photos that look artificially blue-shifted (common in real estate photography) for manual review.
+- **Focal point metadata:** Allow editors to mark the focal point of each image (a click-to-set tool in the CMS). Use this metadata for responsive cropping — the crop algorithm keeps the focal point visible at every breakpoint. WordPress and Cloudinary both support focal-point-aware cropping.
+- **Expiration and freshness:** Photography that shows dated technology (old phones, outdated UI), expired seasonal content (Christmas imagery in March), or former employees should be flagged for review. Set metadata expiration dates on time-sensitive imagery.
+
+### Image Format Decision Matrix
+
+| Format | Best For                           | Compression                              | Browser Support | Transparency           |
+| ------ | ---------------------------------- | ---------------------------------------- | --------------- | ---------------------- |
+| WebP   | General purpose, photos + graphics | Lossy + lossless, ~30% smaller than JPEG | 97%+ global     | Yes (lossy + lossless) |
+| AVIF   | High-quality photos, hero images   | Lossy, ~50% smaller than JPEG            | 92%+ global     | Yes                    |
+| JPEG   | Fallback for legacy browsers       | Lossy only                               | 100%            | No                     |
+| PNG    | Screenshots with text, UI elements | Lossless only, large files               | 100%            | Yes                    |
+| SVG    | Icons, logos, illustrations        | Vector, infinite scale                   | 100%            | Yes                    |
+
+Decision procedure: serve AVIF with WebP fallback and JPEG as last resort using `<picture>` with multiple `<source>` elements. Use PNG only for screenshots containing text that must remain pixel-sharp. Use SVG for everything that is not photographic.
+
+## Source
+
+- Apple Human Interface Guidelines — Images and Icons (2024)
+- Airbnb Design — Photography Style Guide
+- Spotify Design — Visual Identity Guidelines
+- Web.dev — Image Performance Best Practices (2024)
+- WCAG 2.2 — Non-text Content (1.1.1), Images of Text (1.4.5), Three Flashes (2.3.1)
+
+## 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/cursor/design-imagery-photography/skill.yaml

@@ -0,0 +1,35 @@
+name: design-imagery-photography
+version: "1.0.0"
+description: Image in design — art direction, aspect ratios, focal point, image treatments (duotone, overlay, blur), placeholder strategy, image as hero vs supporting
+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-visual-hierarchy
+stack_signals: []
+keywords:
+  - imagery
+  - photography
+  - art-direction
+  - aspect-ratio
+  - focal-point
+  - duotone
+  - overlay
+  - placeholder
+  - hero-image
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []