@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/design-navigation-ux/skill.yaml

@@ -0,0 +1,34 @@
+name: design-navigation-ux
+version: "1.0.0"
+description: Wayfinding — navigation models (hub-spoke, hierarchy, flat, content-driven), persistent vs contextual nav, breadcrumbs, information scent
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-affordances
+  - design-information-architecture
+stack_signals: []
+keywords:
+  - navigation
+  - wayfinding
+  - hub-spoke
+  - hierarchy
+  - flat-nav
+  - breadcrumbs
+  - information-scent
+  - spatial-memory
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-palette-construction/SKILL.md

@@ -0,0 +1,152 @@
+# Palette Construction
+
+> Building functional palettes — primary/secondary/accent selection, neutral scales, semantic colors, and tint/shade generation for production design systems
+
+## When to Use
+
+- Building a color system for a new product or design system from scratch
+- Extending an existing brand color into a full functional palette
+- Creating tint/shade scales for a component library
+- Defining semantic color tokens (success, warning, error, info)
+- Generating a neutral gray scale with intentional warm or cool undertone
+- Auditing a palette for missing functional roles (no accent, no semantic, incomplete neutral scale)
+- Migrating from ad-hoc color values to a systematic, tokenized palette
+- Building a palette that must support both light and dark modes
+
+## Instructions
+
+1. **Understand palette anatomy.** Every production palette has five functional categories. Missing any category forces ad-hoc color decisions that erode consistency:
+
+   | Category      | Role                                                                    | Typical Count           | Example (Stripe)                                                          |
+   | ------------- | ----------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
+   | **Primary**   | Brand identity, primary CTAs, key interactive elements                  | 1 color + 10-step scale | Purple `#533afd`                                                          |
+   | **Secondary** | Supporting brand elements, secondary buttons, active states             | 0-1 color + scale       | (Stripe uses navy `#061b31` structurally, not as a secondary brand color) |
+   | **Accent**    | Decorative highlights, illustrations, marketing flourishes              | 0-2 colors              | Ruby `#ea2261`, Magenta `#f96bee`                                         |
+   | **Neutral**   | Text, backgrounds, borders, dividers, shadows — the structural backbone | 1 scale of 10-13 steps  | Slate gray scale from near-white to near-black                            |
+   | **Semantic**  | Status communication (success, warning, error, info)                    | 4 colors + scales       | Green/amber/red/blue, each with 3-5 variants                              |
+
+2. **Generate tint/shade scales using perceptually uniform steps.** A 10-step scale from 50 (lightest) to 950 (darkest) is the industry standard. Do not interpolate linearly in RGB — the results are perceptually uneven. Use HSL lightness interpolation at minimum, or OKLCH/CIELAB for perceptual uniformity.
+
+   **Tailwind CSS's approach:** Tailwind generates its color scales (50, 100, 200, ... 900, 950) with perceptual uniformity as the goal. Each step represents an approximately equal perceived lightness shift. The 500 step is the "base" — the color as you would name it in conversation ("that's blue"). Steps below 500 are tints (mixed toward white), steps above are shades (mixed toward black).
+
+   **Practical generation procedure:**
+   - Start with your base color (e.g., Primary 500 = `#533afd`)
+   - Generate lightness stops: 50 (L:97%), 100 (L:93%), 200 (L:86%), 300 (L:76%), 400 (L:64%), 500 (L:50%), 600 (L:40%), 700 (L:32%), 800 (L:24%), 900 (L:17%), 950 (L:10%)
+   - Adjust saturation: tints (50-300) reduce saturation by 10-30% to avoid pastel fluorescence; shades (700-950) reduce saturation by 5-15% to avoid muddy darkness
+   - Verify each step has sufficient contrast against both white and black backgrounds for its intended use
+
+3. **Build the neutral scale with intentional undertone.** Pure gray (`hsl(0, 0%, X%)`) is emotionally sterile. Every respected design system tints its neutrals:
+   - **Tailwind Slate:** Blue undertone (hue ~215, S:15-25%) — cool, technical, modern
+   - **Tailwind Zinc:** Blue-violet undertone (hue ~240, S:3-8%) — nearly true neutral with slight cool bias
+   - **Tailwind Stone:** Warm undertone (hue ~25, S:5-10%) — earthy, editorial, organic
+   - **Stripe:** Slate-blue undertone matching their navy brand — creates chromatic unity between colored and "gray" elements
+
+   Decision procedure: match neutral undertone to your primary color's hue family. If primary is blue, use cool neutrals (Slate). If primary is orange or red, use warm neutrals (Stone). This creates subliminal harmony between the structural gray and the chromatic brand.
+
+4. **Define semantic colors independently from brand colors.** Semantic colors must be recognizable regardless of brand context. Never reuse your primary brand color as a semantic color — if your brand is green, your "success" green must be a different green (shifted in hue, saturation, or lightness) so users do not confuse brand elements with success states.
+
+   **Standard semantic mapping:**
+   - **Success:** Green (hue 120-160). Tailwind: `#22c55e` (green-500). Material: `#4caf50`.
+   - **Warning:** Amber/yellow (hue 35-50). Tailwind: `#f59e0b` (amber-500). Material: `#ff9800`.
+   - **Error/Destructive:** Red (hue 0-15). Tailwind: `#ef4444` (red-500). Material: `#f44336`.
+   - **Info:** Blue (hue 200-220). Tailwind: `#3b82f6` (blue-500). Material: `#2196f3`.
+
+   Each semantic color needs at least 3 variants: a strong variant (for filled backgrounds/badges), a subtle variant (for tinted backgrounds), and a text variant (for inline status text). Example for error: `error-500` for filled badges, `error-50` for background tints, `error-700` for text on light backgrounds.
+
+5. **Apply the 60-30-10 rule at the palette level.** This is a surface area budget, not a color count:
+   - **60% — Neutrals.** Backgrounds, text, borders, dividers. This is your neutral scale doing the structural work.
+   - **30% — Primary/Secondary.** Brand presence through headings, navigation, cards, section backgrounds.
+   - **10% — Accent + Semantic.** Buttons, links, badges, status indicators. The scarcity makes them visually powerful.
+
+   Stripe's implementation: approximately 60% white/light gray (neutral), 30% navy text and dark sections (primary structural), 10% purple for interactive elements and semantic colors for states. This distribution makes the purple CTAs unmissable precisely because they are rare.
+
+6. **Test the complete palette in a component matrix.** Before finalizing, render your palette across these components: button (primary, secondary, ghost, destructive), input (default, focused, error, disabled), card (default, elevated, selected), badge (success, warning, error, info), text (heading, body, secondary, disabled). If any component looks wrong, the palette has a gap.
+
+## Details
+
+### Material Design 3's HCT Color Space
+
+Material Design 3 introduced the HCT (Hue, Chroma, Tone) color space for palette generation. HCT separates three perceptually independent dimensions:
+
+- **Hue** (0-360): the color family
+- **Chroma** (0-~120): colorfulness (similar to saturation but perceptually uniform)
+- **Tone** (0-100): lightness from black (0) to white (100)
+
+From a single seed color, MD3 generates:
+
+- **Primary palette:** Seed hue, full chroma, tones 0-100
+- **Secondary palette:** Seed hue, chroma reduced by ~67%, same tones
+- **Tertiary palette:** Hue shifted +60 degrees, moderate chroma, same tones
+- **Neutral palette:** Seed hue, chroma reduced to ~4, same tones
+- **Neutral variant:** Seed hue, chroma reduced to ~8, same tones
+
+This algorithmic approach guarantees harmony because every palette shares a hue relationship with the seed. The tonal system maps directly to accessibility: Tone 40 on Tone 100 (white) guarantees 7:1+ contrast; Tone 80 on Tone 10 guarantees similar contrast in dark mode.
+
+### Palette Sizing: How Many Colors Are Enough?
+
+A common trap is building either too few colors (everything is a one-off) or too many (the palette is an unusable rainbow). Guidelines by product type:
+
+- **Marketing site / landing page:** 1 primary + 1 neutral scale + semantics = ~30 total values. Minimal UI, maximum brand impact.
+- **SaaS application / dashboard:** 1 primary + 1 secondary + 1 neutral scale + semantics = ~50-60 total values. Enough for complex UI without confusion.
+- **Design system / component library:** 1-2 primary + 1 neutral scale + semantics + 2-3 extended accent scales = ~80-100 total values. Covers all possible component states.
+- **Data visualization addition:** Add 6-8 categorical colors, each with 3 variants (strong, medium, subtle) = ~24 additional values.
+
+Stripe's public-facing palette contains approximately 60 total color values. Tailwind CSS ships approximately 220 (22 hues x 10 steps + black/white). Material Design 3 generates approximately 130 from a single seed.
+
+### Anti-Patterns
+
+1. **Too Many Primaries.** Having 3+ "brand colors" that all compete for attention. Symptoms: every page section uses a different bold color, and no single color owns the "primary action" role. Fix: one color is primary (owns buttons and links), at most one is secondary (owns navigation or section backgrounds), everything else is accent (illustrations only) or neutral. Spotify has one primary (green). Stripe has one primary (purple). Apple has zero chromatic primaries (achromatic).
+
+2. **Missing Neutral Scale.** Using only 2-3 grays (`#333`, `#666`, `#999`) instead of a full 10+ step scale. Symptoms: text hierarchy feels flat, borders blend into backgrounds, disabled states are indistinguishable from secondary text. Fix: generate a full 10-step neutral scale with intentional undertone. Even a simple project needs at least 7 neutral steps: background, surface, border, disabled, tertiary text, secondary text, primary text.
+
+3. **Semantic Ambiguity.** Using the same green for both "success" and "go/proceed" — or worse, using the brand green as the success color. Symptoms: users cannot tell if a green badge means "success" or is just brand decoration. Fix: semantic colors must be visually distinct from brand colors. If your brand is green, shift your success green to a different hue (more teal or more lime) or use a different lightness level.
+
+4. **Tint/Shade Scale Gaps.** Having a base color and a light variant but nothing in between. Symptoms: hover states use opacity hacks (`rgba(primary, 0.1)`) instead of real palette steps, dark mode has no intermediate surface colors. Fix: generate the full 10-step scale for every primary and semantic color. The intermediate steps (200-400, 600-800) are what make a palette feel production-ready.
+
+5. **RGB Interpolation.** Generating tints and shades by linearly interpolating in RGB color space. Symptoms: midpoint colors look muddy or desaturated (the "brown muddle" when mixing blue and orange). Fix: interpolate in HSL at minimum, OKLCH or CIELAB for best perceptual results. Modern tools (Figma, the `oklch()` CSS function) support perceptually uniform interpolation natively.
+
+### Real-World Examples
+
+**Tailwind CSS — The Reference Scale.** Tailwind's color system provides 22 named color families, each with 11 stops (50-950). The scales are designed for perceptual uniformity: stepping from gray-200 to gray-300 looks like the same lightness jump as gray-600 to gray-700. Each 100-step represents approximately 7-10% lightness change in OKLCH space. The 500 stop is always the "name-worthy" shade — the color you would call "blue" or "red" in conversation. This makes the system predictable: if you need a lighter version, go down the scale; darker, go up.
+
+**Stripe — Functional Minimalism.** Stripe's palette demonstrates that a world-class design system does not need many colors. The functional palette: purple `#533afd` (primary), navy `#061b31` (structural text), a slate-blue neutral scale (backgrounds, borders, secondary text), and standard semantics (red error, green success, amber warning, blue info). Decorative colors (ruby `#ea2261`, magenta `#f96bee`, cyan, green gradients) exist only in marketing illustrations and the homepage gradient — they never appear in the product dashboard. This discipline keeps the product interface clean while the marketing surface feels vibrant.
+
+**Material Design 3 — Algorithmic Generation.** MD3 proves that a full production palette can be generated algorithmically from a single color. Input: one hex value (e.g., `#6750A4`). Output: 5 tonal palettes (primary, secondary, tertiary, neutral, neutral-variant) x 13 tones each = 65 color values, plus semantic colors. Every generated color is guaranteed to meet contrast requirements when used at its designated tone pairing (e.g., "on-primary" text at Tone 100 on primary container at Tone 90). This eliminates manual contrast checking for standard component combinations.
+
+## Source
+
+- Material Design 3 Color System — https://m3.material.io/styles/color/the-color-system
+- Tailwind CSS Color Palette — https://tailwindcss.com/docs/colors
+- RefactoringUI — "Building Your Color Palette" chapter
+- OKLCH Color Space — https://oklch.com/ — perceptually uniform space for palette generation
+
+## Process
+
+1. Select your primary brand color and determine the harmony type (from design-color-harmony). Generate the full 10-step tint/shade scale.
+2. Build the neutral scale with undertone matching the primary hue. Add semantic colors (success, warning, error, info) with 3+ variants each.
+3. Test the complete palette in a component matrix (button, input, card, badge, text). Verify 60-30-10 distribution in a representative layout.
+4. Document every color value with its functional role, contrast relationships, and usage guidelines.
+
+## 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 (harmony type determines how many chromatic scales to generate), design-color-accessibility (palette must pass colorblind simulation), design-dark-mode-color (palette must have dark mode variants), design-token-architecture (palette values become design tokens).
+- **Sequencing:** Use after design-color-harmony and design-color-psychology have established direction. This skill produces the concrete palette values that all other skills reference.
+
+## Success Criteria
+
+- The palette has all five functional categories: primary, secondary (optional), accent (optional), neutral, and semantic.
+- Every chromatic color has a full 10-step tint/shade scale (50-950), not just a base value.
+- The neutral scale has an intentional undertone matching the primary hue family.
+- Semantic colors are visually distinct from brand colors — no ambiguity between "brand" and "status."
+- The 60-30-10 distribution is observable in representative layouts.
+- Every palette step has documented contrast ratios against white, black, and the palette's own background colors.
+- The palette renders correctly across the component matrix (button, input, card, badge, text).
+- Tint/shade generation uses perceptually uniform interpolation (HSL minimum, OKLCH preferred), not RGB.
+- The palette supports both light and dark modes through tone-based mapping (not simple inversion).
+- Total palette size is appropriate for the product type (30-60 for marketing sites, 50-80 for SaaS, 80-100 for design systems).
+- No opacity hacks (rgba with alpha) are needed for standard states — the scale provides real values for hover, pressed, and disabled states.
+- Palette documentation includes functional role for every color (not just hex values without context).
+- The palette has been tested in a component matrix across all standard component types.
+- Intermediate scale steps (200-400, 600-800) exist and serve distinct functional purposes.

package/dist/agents/skills/cursor/design-palette-construction/skill.yaml

@@ -0,0 +1,37 @@
+name: design-palette-construction
+version: "1.0.0"
+description: Building functional palettes — primary/secondary/accent, neutral scales, semantic colors, tint/shade generation
+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-color-accessibility
+  - design-dark-mode-color
+  - design-token-architecture
+stack_signals: []
+keywords:
+  - palette
+  - primary color
+  - secondary color
+  - accent
+  - neutral scale
+  - semantic colors
+  - tint
+  - shade
+  - color system
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-parallax-scroll/SKILL.md

@@ -0,0 +1,200 @@
+# Parallax & Scroll Effects
+
+> Scroll-driven depth — rate-differential parallax, scroll-triggered reveals, sticky sections, scroll narrative, performance constraints, motion sensitivity
+
+## When to Use
+
+- Building marketing or landing pages where scroll position drives visual storytelling
+- Implementing layered backgrounds that move at different rates to create depth
+- Designing scroll-triggered content reveals (fade-in on scroll, slide-up on enter viewport)
+- Building sticky section headers, navigation bars, or progress indicators that respond to scroll position
+- Creating immersive product showcases where scroll acts as a timeline or progression control
+- Evaluating whether a scroll effect is enhancing comprehension or just adding visual noise
+- Implementing scroll-linked animations with the CSS Scroll-Driven Animations API or Intersection Observer
+- Any situation where the scroll position should control visual state beyond simple content displacement
+
+## Instructions
+
+1. **Understand rate-differential parallax as the core mechanism.** Parallax is the perception of depth created when visual layers move at different speeds relative to the viewer's motion. In scroll-driven parallax, the "viewer's motion" is the scroll position. Background layers move slower than the scroll rate (creating depth — they appear "far away"), foreground layers move faster than the scroll rate (creating proximity — they appear "close"). The speed ratio determines perceived depth: a background at 0.3x scroll speed appears distant; a foreground at 1.5x appears close. A midground at 1.0x moves with normal scroll. Stripe's marketing pages use a 3-layer system: background illustrations at 0.3x, content cards at 1.0x (normal), and decorative floating elements at 0.7x — the differential between 0.3x and 0.7x creates perceivable depth without aggressive motion.
+
+2. **Limit parallax rate differentials to prevent motion sickness.** The maximum comfortable rate differential is 0.5x (one layer moves at half the speed of another). Differentials above 0.5x create rapid visual displacement that triggers vestibular discomfort in approximately 35% of adults over 40. Safe ranges:
+   - **Subtle depth (recommended):** Background at 0.8x, content at 1.0x. Differential: 0.2x. Barely perceptible but creates subconscious depth. Suitable for all audiences.
+   - **Moderate depth:** Background at 0.5x, content at 1.0x. Differential: 0.5x. Clearly visible parallax. Must have `prefers-reduced-motion` alternative.
+   - **Aggressive depth (use sparingly):** Background at 0.2x, foreground at 1.3x. Differential: 1.1x. Strong parallax for hero sections only. Must be limited to a single viewport height. Must have `prefers-reduced-motion` alternative. Apple's tvOS uses aggressive parallax on app icons (foreground shifts up to 30px relative to background), but the effect is bounded to a small surface area — a 400x240px card, not a full screen.
+
+3. **Implement scroll-triggered reveals with Intersection Observer, not scroll events.** Scroll event listeners fire on every frame during scrolling (~60-120 times per second), consuming main thread budget. Intersection Observer is asynchronous, fires only at threshold crossings, and does not block the main thread. The standard reveal pattern:
+
+   ```javascript
+   const observer = new IntersectionObserver(
+     (entries) => {
+       entries.forEach((entry) => {
+         if (entry.isIntersecting) {
+           entry.target.classList.add('revealed');
+           observer.unobserve(entry.target); // One-shot reveal
+         }
+       });
+     },
+     { threshold: 0.15, rootMargin: '0px 0px -50px 0px' }
+   );
+   ```
+
+   The `threshold: 0.15` means the element is revealed when 15% visible — early enough that the animation completes before the element is fully in view. The `rootMargin: '0px 0px -50px 0px'` shrinks the bottom of the observation area by 50px, preventing elements right at the viewport edge from triggering. Vercel uses this exact pattern: section headings and feature cards fade up from 20px below their resting position over 400ms with `ease-out` when they cross the 15% visibility threshold.
+
+4. **Design scroll narrative as a three-act structure.** Scroll-driven pages are temporal experiences — the user's scroll position is the timeline. Structure the narrative:
+   - **Act 1 (Hero, 0-100vh):** Establish context. Full-viewport hero with primary message. Minimal parallax — the user has not committed to scrolling yet. Apple's product pages start with a static hero image and a single headline.
+   - **Act 2 (Features, 100vh-N\*100vh):** Deliver value. Each scroll section reveals a feature or benefit. Use sticky sections (the section pins while content scrolls through it) to create controlled reading pace. Stripe's "Payments" page uses sticky phone mockups that update as the user scrolls through feature descriptions.
+   - **Act 3 (Resolution, final 100vh):** Call to action. The scroll narrative concludes with a clear next step. Reduce motion complexity — the user should focus on the CTA, not be distracted by animations. Vercel's landing pages end with a clean, static pricing/signup section after elaborate scroll-driven feature reveals.
+
+5. **Implement sticky sections for pacing control.** Sticky positioning (`position: sticky; top: 0`) pins an element within its scrolling container. Use sticky sections to create "scroll-through" experiences where a visual element stays fixed while text content scrolls alongside it. The implementation pattern:
+
+   ```css
+   .sticky-container {
+     display: grid;
+     grid-template-columns: 1fr 1fr;
+     min-height: 300vh; /* 3x viewport height for scroll-through */
+   }
+   .sticky-visual {
+     position: sticky;
+     top: 0;
+     height: 100vh;
+   }
+   .scrolling-content {
+     padding: 100vh 0; /* Space above and below for scroll room */
+   }
+   ```
+
+   The sticky visual occupies the left half of the screen while the right half scrolls through 3 viewports of content. Material Design's component documentation pages use this pattern: a live component preview stays sticky on the left while specifications scroll on the right. Apple's iPhone product pages use a variation: a phone image stays sticky-centered while feature text sections scroll past it, with the phone screen updating to match the current feature.
+
+6. **Use the CSS Scroll-Driven Animations API for performance-critical scroll effects.** The Scroll-Driven Animations API (Chrome 115+, progressive enhancement for other browsers) moves scroll-linked animations entirely off the main thread. Instead of JavaScript scroll listeners that calculate and apply transforms per frame, the browser's compositor handles the animation directly:
+
+   ```css
+   @keyframes parallax-shift {
+     from {
+       transform: translateY(0);
+     }
+     to {
+       transform: translateY(-100px);
+     }
+   }
+   .parallax-bg {
+     animation: parallax-shift linear;
+     animation-timeline: scroll();
+     animation-range: 0vh 100vh;
+   }
+   ```
+
+   This achieves jank-free parallax without any JavaScript. The `animation-timeline: scroll()` binds the animation progress to scroll position. The `animation-range` defines which scroll range maps to the animation's 0%-100%. For browsers without support, fall back to Intersection Observer for reveal effects and accept static backgrounds. Do not fall back to JavaScript scroll listeners for parallax — the performance cost is not worth the effect.
+
+7. **Always provide a complete `prefers-reduced-motion` alternative.** Parallax and scroll-triggered animations are among the most motion-sickness-inducing patterns in web design. The reduced-motion implementation must:
+   - **Eliminate all parallax.** All layers move at 1.0x scroll speed (normal scrolling).
+   - **Replace reveals with pre-revealed state.** Elements that would fade-in-on-scroll appear immediately in their final position.
+   - **Keep sticky sections.** Sticky positioning is not motion — it is a layout pattern. Sticky sections can remain in reduced-motion mode.
+   - **Remove scroll-driven animations.** Any animation tied to scroll position is eliminated. Content is visible in its final state.
+
+   ```css
+   @media (prefers-reduced-motion: reduce) {
+     .parallax-bg {
+       animation: none;
+       transform: none;
+     }
+     .reveal-on-scroll {
+       opacity: 1;
+       transform: none;
+     }
+     /* Sticky sections remain unchanged */
+   }
+   ```
+
+   Apple's macOS System Preferences demonstrates this: when "Reduce motion" is enabled, all parallax effects on Apple's marketing pages are disabled. Content appears in its final state with no scroll-linked position changes.
+
+8. **Performance-budget scroll effects strictly.** Scroll-driven animations must maintain 60fps (16.67ms per frame) without exception. The budget:
+   - **Compositor-only properties:** Only animate `transform` and `opacity` in response to scroll. No `background-position` animation (triggers paint), no `filter` animation (triggers paint), no dimension animations (`width`, `height` — trigger layout).
+   - **Layer count:** No more than 5 composited layers for parallax. Each layer with `will-change: transform` consumes GPU memory. On a mobile device with 512MB GPU memory, each full-viewport layer can consume 8-12MB. Five layers = 40-60MB — near the limit for low-end devices.
+   - **Image optimization:** Parallax background images must be decoded and GPU-resident. Use `<img loading="eager">` for parallax images (not `lazy`, which causes pop-in on scroll). Size images to 1.5x the container size to accommodate parallax travel without exposing edges.
+   - **Avoid `background-attachment: fixed`.** This CSS property creates a pseudo-parallax effect but forces the entire page to repaint on every scroll frame. Performance is catastrophic on mobile and poor on desktop. Modern Chrome no longer hardware-accelerates `background-attachment: fixed`. Use `transform: translateY()` with Scroll-Driven Animations API instead.
+
+## Details
+
+### Scroll Position as a Design Variable
+
+Scroll position is a continuous input (0 to max-scroll-height) that can drive any visual property. The key insight: scroll is not just navigation — it is an input device, like a slider. Effective scroll-driven design treats scroll position as a value that maps to visual states:
+
+**Linear mapping:** `visualProperty = scrollPosition * rate`. The property changes proportionally with scroll. Used for parallax (position changes linearly with scroll) and progress indicators (a bar fills proportionally as the user scrolls through a page).
+
+**Threshold mapping:** `visualProperty = scrollPosition > threshold ? stateB : stateA`. The property snaps between two states at a scroll position. Used for sticky navigation (transparent to opaque at scroll > 50px), scroll-triggered reveals (hidden to visible at element-in-viewport), and header collapse (full header to compact header at scroll > 200px).
+
+**Range mapping:** `visualProperty = clamp(0, (scrollPosition - start) / (end - start), 1) * valueRange`. The property interpolates between two values within a scroll range, then holds steady outside that range. Used for scroll-linked animations within a specific page section. The CSS Scroll-Driven Animations API's `animation-range` implements this directly.
+
+### Sticky Section Patterns
+
+**Sticky sidebar with scrolling content.** The standard documentation/marketing pattern. One column is sticky (visual, navigation, or media), the other scrolls. The sticky column's height must equal `100vh` — if it exceeds the viewport, the bottom will be clipped. If sticky content is taller than the viewport, use `overflow-y: auto` on the sticky element to make it independently scrollable.
+
+**Sticky-then-scroll (pin-and-release).** A section pins at the top of the viewport for a specific scroll range, then releases and scrolls normally. Implementation: the section's container has height = `100vh + pinDuration`. The section has `position: sticky; top: 0; height: 100vh`. While the user scrolls through the container's excess height (`pinDuration`), the section stays pinned. Once the container scrolls past, the section releases. Apple's product pages use this extensively: a phone image pins while 3 feature descriptions scroll through, then the phone releases and the next section enters.
+
+**Sticky header with progressive collapse.** A navigation bar that compresses from full height (80px) to compact height (48px) as the user scrolls. Implementation: use `scroll()` timeline to animate `height`, `padding`, and `font-size` between scroll positions 0 and 200px. This creates a "shrinking header" that preserves navigation access while reclaiming vertical space. Stripe's documentation site collapses its header from a full logo + navigation to a compact bar with a hamburger menu.
+
+### Scroll Performance Debugging
+
+**Diagnosing jank.** Open Chrome DevTools > Performance > Record while scrolling. Look for:
+
+- **Long tasks (>50ms)** on the main thread during scroll — indicates JavaScript scroll listeners doing too much work.
+- **Paint events** during scroll — indicates non-compositor properties being animated.
+- **Layout events** during scroll — indicates dimension/position properties being animated.
+
+**Common jank sources:**
+
+1. `background-attachment: fixed` — forces repaint on every scroll frame. Replace with `transform`-based parallax.
+2. `box-shadow` animated on scroll — triggers paint. Use `filter: drop-shadow()` or pre-rendered shadow layers.
+3. `element.getBoundingClientRect()` in scroll handlers — triggers forced synchronous layout. Cache values and use Intersection Observer instead.
+4. Unthrottled scroll listeners — fire 60-120 times per second. If you must use scroll listeners (no Scroll-Driven Animations support), use `requestAnimationFrame` to batch reads and writes.
+
+### Anti-Patterns
+
+1. **Scroll Hijacking.** Overriding the browser's native scroll behavior to control scroll speed, snap to sections, or change scroll direction. This breaks the user's fundamental expectation of how scrolling works. Users who use trackpads, mice, touchscreens, keyboards (Page Up/Down), and assistive devices all have different scroll velocities and expectations. Overriding any of them creates frustration. Specific violations: `event.preventDefault()` on wheel events, `scroll-snap-type: y mandatory` on the document (not containers), custom scroll velocity multipliers, horizontal scroll triggered by vertical wheel input. Fix: use native scroll behavior. Use `scroll-snap-type` only on bounded containers (carousels, galleries), never on the document root. If sections need to "snap," use `scroll-snap-type: y proximity` which suggests snapping but does not force it.
+
+2. **Perpetual Animation Loops on Scroll.** Attaching infinite CSS animations (`animation-iteration-count: infinite`) to elements and using scroll position only to toggle their visibility. The animation runs whether or not the user is looking at it, consuming GPU cycles for off-screen elements. Fix: use Intersection Observer to add/remove animation classes when elements enter/leave the viewport. Alternatively, use `animation-play-state: paused` by default and set `running` when in view.
+
+3. **Parallax on Mobile Without Touch Consideration.** Mobile scroll is fundamentally different from desktop — it uses momentum-based inertia (the page continues scrolling after the finger lifts), rubber-banding at scroll boundaries, and 120Hz refresh on modern devices. Parallax that looks smooth at 60fps on desktop may stutter at 120fps on mobile because the animation calculations cannot keep pace with the faster refresh rate. Fix: disable parallax on mobile entirely (`@media (hover: none) { .parallax { transform: none; } }`) or use the CSS Scroll-Driven Animations API which is compositor-driven and refresh-rate-independent. Many production sites (Apple, Stripe) disable parallax on mobile viewports.
+
+4. **Edge Exposure.** When a parallax layer moves slower than the scroll rate, it travels less than the content. If the layer is exactly viewport-sized, scrolling reveals the edge of the image. The user sees a gap — a colored background or the end of an image — where the parallax layer does not cover. Fix: size parallax images to cover the maximum travel distance. For a background at 0.5x scroll speed on a viewport of 900px, the background must be at least `900px + (900px * 0.5) = 1350px` tall. General formula: `image_height = viewport_height + (scroll_distance * (1 - parallax_rate))`.
+
+5. **Reveal Fatigue.** Every single element on the page fades in on scroll — headings, paragraphs, images, buttons, dividers, icons, badges. The first few reveals feel polished. By the twentieth, the user is waiting for content to appear rather than reading it. The page feels like it is loading slowly, not revealing elegantly. Fix: limit reveals to major section entries (3-5 per page). Body text, inline images, and secondary UI elements should be present in the DOM without animation. Reserve reveals for moments of narrative emphasis — a key statistic, a product screenshot, a testimonial quote.
+
+### Real-World Examples
+
+**Apple's iPhone Product Pages.** Apple's product marketing pages are the reference implementation for scroll-driven narrative. The page is structured as a linear story: hero image (static, full bleed), followed by 4-6 feature sections. Each feature section uses a sticky phone mockup on center-screen while feature descriptions scroll alongside. As the user scrolls through a feature section, the phone screen transitions (crossfade, 300ms) to show the relevant feature. The parallax is subtle — background gradients shift at approximately 0.85x scroll speed, a 0.15x differential that creates depth without triggering motion sensitivity. On mobile, parallax is disabled entirely; the page uses sequential full-bleed images instead. All scroll-linked animations respect `prefers-reduced-motion` — with reduced motion enabled, phone screens swap instantly and gradients are static.
+
+**Stripe's Multi-Layer Marketing Parallax.** Stripe's homepage uses a 4-layer depth system: a distant grid pattern (0.3x scroll speed), mid-ground gradient orbs (0.6x), content sections (1.0x, normal), and foreground code snippets that float above content (1.15x on desktop). The differential between layers creates a convincing sense of depth. The grid pattern uses CSS Scroll-Driven Animations API where supported and falls back to `transform: translate3d()` updated via `requestAnimationFrame` elsewhere. Stripe limits parallax to the first 3 viewports of the page — deeper sections use standard scroll behavior, creating a natural transition from "immersive showcase" to "informational content."
+
+**Vercel's Section Reveal System.** Vercel's landing page uses scroll-triggered reveals with a consistent pattern: each major section (feature cards, code examples, deployment previews) fades in from 20px below its final position with 400ms `ease-out` when 15% visible (Intersection Observer with `threshold: 0.15`). Within each section, elements stagger: heading at 0ms, subheading at 60ms, visual at 120ms, and CTA at 180ms. Total entrance time per section: ~580ms. The reveals are one-shot (`observer.unobserve()` after trigger) — scrolling back up shows the elements in their final state, not the pre-reveal state. On `prefers-reduced-motion`, all elements appear in their final state immediately.
+
+**Spotify's Album Art Parallax.** In Spotify's mobile Now Playing view, the album art uses a subtle parallax effect when scrolling between the album art and the track list. The album art scales from 1.0 to 0.85 and shifts upward at 0.7x scroll rate as the track list scrolls up to replace it. The background gradient (sampled from the album art colors) fades from full opacity to 40% as the list appears, creating a smooth transition from visual-focused (album art) to text-focused (track list) context. The parallax rate of 0.7x (0.3x differential) is within the comfortable range. On iOS, this uses UIKit's scroll view delegate for 120Hz-synchronized updates. With reduced motion enabled, the album art crossfades to the track list without position animation.
+
+## Source
+
+- CSS Scroll-Driven Animations Specification — https://www.w3.org/TR/scroll-animations-1/
+- Intersection Observer API — https://www.w3.org/TR/intersection-observer/
+- Apple — Product page scroll design patterns (iPhone, Mac product pages)
+- Stripe — Marketing page parallax implementation (DevTools analysis)
+- Material Design — Scrolling behavior documentation
+- Google Web Fundamentals — "Performant Parallaxing" (Paul Lewis, 2016)
+- CSS `position: sticky` specification — https://www.w3.org/TR/css-position-3/#sticky-pos
+- Web.dev — "Scroll-driven animations" (Bramus Van Damme, 2023)
+- Vestibular Disorders Association — Motion sensitivity and scroll-linked animation guidance
+- Chrome DevTools — Performance profiling for scroll jank diagnosis
+
+## 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-parallax-scroll/skill.yaml

@@ -0,0 +1,34 @@
+name: design-parallax-scroll
+version: "1.0.0"
+description: Scroll-driven depth — rate-differential parallax, scroll-triggered reveals, sticky sections, scroll narrative, performance constraints, motion sensitivity
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-motion-principles
+  - design-elevation-shadow
+stack_signals: []
+keywords:
+  - parallax
+  - scroll
+  - scroll-driven
+  - sticky
+  - reveal
+  - performance
+  - motion-sensitivity
+  - narrative
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []