@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/design-motion-principles/SKILL.md

@@ -0,0 +1,161 @@
+# Motion Principles
+
+> Purposeful animation — Disney's 12 principles adapted for UI, easing curves, duration guidelines, choreography, motion as feedback vs decoration, reducing motion
+
+## When to Use
+
+- Designing any interface element that changes state, position, size, or visibility over time
+- Evaluating whether an animation is purposeful (aids comprehension) or decorative (adds delight but no function)
+- Building a motion system or defining animation tokens for a design system
+- Choreographing multi-element transitions where several components animate simultaneously
+- Implementing reduced-motion alternatives for accessibility compliance
+- Reviewing animation performance and deciding between CSS transitions, CSS animations, and JavaScript-driven motion
+- Creating onboarding flows, page transitions, or loading sequences that use coordinated motion
+- Any decision about how something should move, how fast, and with what character
+
+## Instructions
+
+1. **Apply the "purpose test" before adding any animation.** Every animation must serve at least one of four purposes: (a) orient — show the user where they are in space or in a flow, (b) focus — direct attention to a change or new element, (c) express — reinforce brand personality through motion character, or (d) connect — show causal relationships between actions and outcomes. If an animation serves none of these, it is visual noise. Material Design 3's motion guidelines formalize this: transitions must "help users understand and navigate an app by showing how elements are related to each other." A sidebar sliding in from the left serves orient (spatial origin). A notification badge pulsing serves focus. A playful logo bounce serves express. A button morphing into a loading spinner serves connect.
+
+2. **Adapt Disney's 12 principles for UI motion selectively.** Disney's 1981 principles were designed for character animation, not interfaces. Six translate directly to UI. The remaining six are character-specific and should be ignored:
+
+   **Use these six:**
+   - **Squash and stretch** — elements compress on impact and stretch on departure. A modal landing on screen can scale from 102% to 100% on arrival (subtle squash). Material Design's FAB press applies 95% scale (squash) on press.
+   - **Anticipation** — a brief reverse motion before the main action. A card about to dismiss shifts 4-8px in the opposite direction before swiping away. Apple's delete animation retracts an item slightly before removing it.
+   - **Slow in and slow out (easing)** — natural motion accelerates and decelerates. This maps directly to CSS easing functions. Linear motion (`linear`) looks robotic. Always use curved easing.
+   - **Follow through and overlapping action** — secondary elements lag behind the primary. When a panel slides open, its content fades in 50-100ms after the panel reaches its final position. Linear's page transitions use this: the container slides in, then text elements fade up with a 40ms stagger.
+   - **Arcs** — natural motion follows curved paths, not straight lines. An element moving from a FAB position (bottom-right) to a dialog position (center) should follow a slight arc, not a straight diagonal. Material Design's "shared axis" transition uses arc paths for element relocation.
+   - **Staging** — present one idea at a time. Do not animate five elements simultaneously. Stagger entrances so the user can process each element: 40-80ms delay between items in a list, 100-150ms delay between major sections.
+
+   **Skip these six (character animation only):** Timing (subsumed by duration guidelines), secondary action (subsumed by overlapping action in UI), straight ahead / pose to pose (animation production methods), exaggeration (risks looking cartoonish in UI), solid drawing (3D modeling concept), appeal (subjective character design).
+
+3. **Define easing curves as system tokens.** Every animation in a system should use one of 3-5 named easing curves, never arbitrary `cubic-bezier` values. A production-ready easing system:
+   - **Standard** (`cubic-bezier(0.2, 0.0, 0, 1.0)`) — the default for most transitions. Starts fast, decelerates smoothly. Used for elements moving between resting positions.
+   - **Emphasized** (`cubic-bezier(0.2, 0.0, 0, 1.0)` for decelerate, `cubic-bezier(0.3, 0.0, 0.8, 0.15)` for accelerate) — for focal transitions that demand attention. Material Design 3 uses emphasized easing for hero transitions and container transforms.
+   - **Decelerate-only** (`cubic-bezier(0.0, 0.0, 0, 1.0)`) — for elements entering the screen. The element starts at full velocity and slows to a stop, matching the mental model of something arriving.
+   - **Accelerate-only** (`cubic-bezier(0.3, 0.0, 1, 1)`) — for elements exiting the screen. The element starts slow and accelerates away, matching departure.
+   - **Spring** (`spring(1, 100, 10, 0)` in frameworks that support it, or approximated as `cubic-bezier(0.34, 1.56, 0.64, 1)`) — for playful, physical interactions. Apple uses spring animations extensively: damping ratio 0.7-0.85, stiffness 200-400. The iOS keyboard uses a spring with damping 0.85 for its slide-up entrance.
+
+4. **Set duration by element size and travel distance, not by feel.** Small elements (icons, badges, checkmarks) need 100-150ms. Medium elements (cards, buttons, chips) need 200-300ms. Large elements (modals, drawers, page transitions) need 300-500ms. Full-screen transitions need 400-700ms. The rule: larger elements need more time because the eye tracks more visual change. Material Design 3's duration tokens:
+   - `duration-short1`: 50ms (micro-feedback: ripples, state layers)
+   - `duration-short2`: 100ms (small components: switch, checkbox)
+   - `duration-short3`: 150ms (selection controls, small transforms)
+   - `duration-short4`: 200ms (entering small components)
+   - `duration-medium1`: 250ms (standard component transitions)
+   - `duration-medium2`: 300ms (shared axis transitions)
+   - `duration-medium3`: 350ms (complex shape changes)
+   - `duration-medium4`: 400ms (full-screen transitions)
+   - `duration-long1` through `duration-long4`: 450-700ms (elaborate choreography)
+     Never exceed 700ms for any single animation. The user's perception of "instantaneous" ends at ~100ms and "connected to my action" ends at ~300ms.
+
+5. **Choreograph multi-element transitions with stagger and sequencing.** When multiple elements animate simultaneously, the result is chaos unless choreographed. Three choreography patterns:
+   - **Stagger:** Elements animate with identical motion but offset start times. List items entering: 40-80ms delay between each item. Linear uses 40ms stagger for issue lists — fast enough to feel fluid, slow enough that each item is individually perceivable.
+   - **Cascade:** Elements animate in dependency order — parent first, then children. A dialog enters (300ms), then its title fades in (200ms, 50ms delay), then body text (200ms, 100ms delay), then action buttons (150ms, 150ms delay). Vercel's deployment detail page uses this cascade pattern.
+   - **Shared motion:** Elements that are conceptually related animate in lockstep. A card expanding into a detail view — the card surface, the title, and the image all animate together on the same timeline with the same easing. Material Design's "container transform" is the canonical shared motion pattern.
+
+6. **Distinguish feedback motion from narrative motion.** Feedback motion is reactive — it responds to a user action (button press, toggle switch, form validation). Feedback must be fast (100-200ms), subtle, and never block the user from continuing. Narrative motion is proactive — it tells a story (onboarding sequence, loading animation, feature tour). Narrative motion can be longer (300-700ms per step), more elaborate, and is allowed to command full attention because it occurs at natural pause points. The error: using narrative-length motion for feedback actions, making the interface feel sluggish. A button press animation at 500ms is narrative motion misapplied to a feedback context.
+
+7. **Implement reduced motion as a first-class design concern, not an afterthought.** The `prefers-reduced-motion: reduce` media query indicates a user who experiences discomfort from animation. The implementation hierarchy:
+   - **Eliminate** all decorative animations (parallax, background motion, hover bounces)
+   - **Replace** transitions with instant state changes (crossfade in 1ms instead of slide over 300ms)
+   - **Preserve** essential state indicators (loading spinners become pulsing dots, progress bars remain but do not animate fill)
+   - **Never** remove information — if an animation communicates state (green checkmark drawing in), the end state must still appear (green checkmark shown instantly)
+
+   Apple's reduced-motion implementation is the gold standard: when enabled on iOS, the app-open zoom animation becomes a crossfade, the parallax home screen becomes static, and the swipe-to-go-back gesture still works but without the sliding animation — the page just appears.
+
+8. **Budget total motion per screen.** No more than 3 simultaneous animations visible to the user at any moment. Beyond 3, the eye cannot track individual movements and the experience feels chaotic. This budget means: if a page has a loading spinner, a skeleton screen pulse, and a notification badge animation all visible, adding a fourth animation (e.g., an animated gradient) exceeds the budget. Cut the least important one. Spotify's Now Playing screen respects this: album art color gradient (1), progress bar (2), and the waveform visualizer (3) — exactly three concurrent motions, each in a distinct screen region.
+
+## Details
+
+### Easing Function Mathematics
+
+An easing function maps input time `t` (0 to 1) to output progress `p` (0 to 1). A `cubic-bezier(x1, y1, x2, y2)` defines a cubic Bezier curve with fixed endpoints at (0,0) and (1,1) and two control points at (x1,y1) and (x2,y2).
+
+**Linear** (`cubic-bezier(0,0,1,1)`): `p = t`. Constant velocity. Feels mechanical. Use only for progress bars and video playback scrubbing where constant rate is the correct metaphor.
+
+**Ease-out** (`cubic-bezier(0, 0, 0.2, 1)`): Fast start, gradual deceleration. The element arrives with energy and settles. This is the most natural entry animation because it mimics an object being tossed — fast initial velocity, friction slows it. Material Design's `standard-decelerate` curve.
+
+**Ease-in** (`cubic-bezier(0.4, 0, 1, 1)`): Slow start, accelerating exit. The element gathers speed as it leaves. Less common in UI because exits are usually fast. Used for dismissal animations where the element accelerates off-screen.
+
+**Ease-in-out** (`cubic-bezier(0.4, 0, 0.2, 1)`): Accelerates then decelerates. Used for elements moving between two on-screen positions (e.g., a tab indicator sliding from one tab to another). Material Design's `standard` curve.
+
+**Spring physics** approximate overshoot — the element passes its target position, then oscillates back. Characterized by `damping` (how quickly oscillation stops; 0.7-0.85 for UI) and `stiffness` (how strong the pull to target; 200-400 for UI). Apple's iOS sheet presentation uses spring with damping 0.82, creating a single subtle overshoot that feels physically grounded without being bouncy. Frameworks: Framer Motion's `type: "spring"`, React Native's `Animated.spring()`, CSS `linear()` polyfill.
+
+### Motion Choreography Patterns
+
+**Shared-Axis Transition (Material Design 3).** When navigating along a spatial axis (list to detail, tab to tab), both the outgoing and incoming elements animate along that shared axis. Example: tapping a list item — the list fades and slides left (exit), while the detail view fades and slides in from the right (enter). Both use the x-axis as the shared axis. Duration: 300ms outgoing, 300ms incoming, with 35ms overlap. This creates spatial continuity — the user perceives a coherent space being navigated rather than disconnected pages being swapped.
+
+**Container Transform.** An element transforms into another element, maintaining visual continuity. The source element (e.g., a card) smoothly changes shape, size, and position to become the destination element (e.g., a full-screen detail view). The card's corner radius animates from 12px to 0px, its bounds expand to full screen, and its content crossfades from card layout to detail layout. Duration: 300-450ms. Easing: `emphasized`. Material Design 3 uses this for FAB-to-dialog and card-to-detail transitions.
+
+**Fade Through.** Two elements that are not spatially related transition via a sequential fade: the outgoing element fades out (90ms, `accelerate` easing), then the incoming element fades in (210ms, `decelerate` easing). Total: 300ms. A brief gap at the crossover point (both elements at low opacity) prevents the layered "double vision" effect of a simultaneous crossfade. Material Design uses fade through for bottom navigation tab switches.
+
+### Anti-Patterns
+
+1. **The Loading Screen Movie.** A 3-5 second elaborate animation sequence that plays every time the app loads or navigates between pages. Users see this animation hundreds of times. What felt impressive on first encounter becomes an infuriating delay by the tenth. The fix: loading animations should last no longer than the actual load time, and even then, they should be skeletal (skeleton screens, subtle pulsing) rather than narrative (logo animations, mascot dances). If your load time is 200ms, showing a 2-second loading animation makes the app feel 10x slower than it is.
+
+2. **Motion Sickness Roulette.** Using large-scale zoom, rotation, or parallax animations without reduced-motion alternatives. Approximately 35% of adults over 40 have vestibular sensitivity. A full-screen zoom transition or a rotating carousel can trigger nausea, dizziness, or disorientation. The fix: every animation that covers more than 50% of the viewport must have a `prefers-reduced-motion` alternative. This is not optional polish — it is an accessibility requirement equivalent to alt text for images.
+
+3. **Easing Anarchy.** Using different easing curves on every element — one card uses `ease-in-out`, another uses `ease-out`, the drawer uses a custom `cubic-bezier(0.68, -0.55, 0.27, 1.55)` with overshoot, and the tooltip uses `linear`. The interface feels like it was assembled from different physics engines. Fix: define 3-5 easing tokens and use them consistently. Every element in the system should share the same motion vocabulary.
+
+4. **Simultaneous Blast.** Animating all elements on a page at the same time with the same duration, creating a visual explosion where everything moves at once and nothing is individually trackable. The user's eye has no focal point. Fix: stagger entries by 40-80ms between elements. Lead with the most important element (the primary content), then reveal secondary elements (navigation, sidebar, auxiliary content) after the primary has settled.
+
+5. **The Un-interruptible Animation.** An animation that plays to completion regardless of user input. The user clicks a button, a 500ms animation starts, and the user cannot interact with anything until it finishes. This violates the fundamental principle that the interface should always respond to the user within 100ms. Fix: all animations should be interruptible — if the user takes a new action during an animation, the animation should be cancelled or rapidly completed (jump to end state in 50ms) so the new action can begin immediately.
+
+### Motion Budget Framework
+
+A motion budget prevents animation overload by quantifying the total animation complexity allowed per screen. The budget has three dimensions:
+
+**Concurrent animation count.** Maximum 3 simultaneous animations visible to the user at any moment. Track this by auditing each screen state: if a loading spinner, a skeleton pulse, and a background gradient animation are all visible, the budget is spent. A notification entrance animation would need to wait for one of the three to complete. Spotify's Now Playing screen exemplifies exact budget adherence: album art gradient (1), progress bar (2), waveform (3) — no fourth animation.
+
+**Cumulative animation duration per navigation action.** The total animation time between a user's action (click, tap, swipe) and the system reaching a fully settled state should not exceed 600ms. If a page transition takes 300ms and a content stagger takes 300ms, the budget is spent. Adding a third animation (e.g., sidebar slide) would push past the 600ms threshold and make the interface feel slow. Linear keeps total transition duration under 400ms by overlapping exit and entrance animations.
+
+**Animation surface area.** The percentage of the viewport undergoing animation at any moment. Full-screen transitions (100% surface area) should be reserved for major navigation events (page changes, modal opens). Partial-screen animations (cards, panels, lists) should affect less than 40% of the viewport simultaneously. Micro-interactions (buttons, toggles, icons) should affect less than 5%. When more than 40% of the viewport animates simultaneously, users report the interface feeling "chaotic" regardless of animation quality.
+
+### Motion Decision Procedure
+
+Before adding any animation, answer these questions in order:
+
+1. **Does this animation exist in the motion token system?** If yes, use the existing token (duration, easing, property). If no, check if an existing token can serve the purpose. Only create a new token if no existing one applies — and update the token documentation.
+2. **What purpose does this animation serve?** Map it to one of the four purposes (orient, focus, express, connect). If none apply, the animation is decorative — skip it unless you have explicit budget.
+3. **What is the duration?** Look up the element size in the duration scale. Do not use custom durations.
+4. **What is the easing?** Enter = decelerate. Exit = accelerate. Move = standard. Playful = spring. Do not use custom curves.
+5. **Does this exceed the concurrent animation budget?** Check what else will be animating when this fires. If the budget is spent, queue or cut.
+6. **What is the reduced-motion alternative?** Define it now, not later. If the animation is functional, provide a simplified version. If decorative, provide instant state change.
+
+### Real-World Examples
+
+**Apple's Spring Animation System.** Apple uses spring physics as the foundation for nearly all iOS animations. The home screen app icon press uses `stiffness: 400, damping: 0.72` — a quick, slightly bouncy compression. The sheet presentation (swipe up to show a modal card) uses `stiffness: 300, damping: 0.85` — a slower, more dampened slide with exactly one subtle overshoot. The key insight: spring animations feel natural because they are governed by physics equations rather than arbitrary curves. Two springs with different stiffness/damping values still feel like they belong to the same physical world because they share the same underlying motion model.
+
+**Material Design 3 Motion System.** MD3 defines three categories: transitions (between screens), component animations (within a screen), and state-layer animations (hover, press, focus). Each category has specific duration ranges and easing tokens. Transitions use 300-700ms with `emphasized` easing. Component animations use 100-300ms with `standard` easing. State-layer animations use 50-150ms with `standard` easing. This three-tier system ensures that no component animation is ever mistaken for a transition (the duration gap prevents it) and that state-layer feedback never feels sluggish (the 150ms ceiling ensures responsiveness).
+
+**Linear's Page Transition Choreography.** Linear's web app transitions between views (inbox, project board, settings) using a choreographed sequence: outgoing content fades out with a slight upward movement (150ms, `accelerate`), then incoming content fades in with a slight downward-to-resting movement (200ms, `decelerate`) with a 40ms stagger between the header, main content, and sidebar sections. The total transition feels instantaneous (~250ms perceived) despite involving 6+ individual animations. The secret: overlapping the exit and entrance by 50ms so there is no "dead" gap where the screen is empty.
+
+**Spotify's Contextual Motion Language.** Spotify uses motion to reinforce its audio-visual brand. Album art transitions use a crossfade with scale (the new album grows from 95% to 100% while fading in, the old album shrinks to 95% while fading out — 300ms, `ease-out`). The Now Playing bar slides up from the bottom with a spring animation when first invoked, then snaps between minimized and expanded states. List scrolling uses inertia-based deceleration that matches iOS physics exactly — Spotify does not override the platform scroll behavior, ensuring familiarity. The waveform visualizer uses a custom animation that synchronizes with audio amplitude, creating a motion that is impossible to separate from the content it represents.
+
+## Source
+
+- Thomas, F. and Johnston, O. — _The Illusion of Life: Disney Animation_ (1981), the 12 principles
+- Material Design 3 — Motion documentation, https://m3.material.io/styles/motion
+- Apple Human Interface Guidelines — Motion and spring animations
+- CSS Specification — `transition-timing-function`, https://www.w3.org/TR/css-transitions-1/#transition-timing-function-property
+- Google Web Fundamentals — "Animations and Performance" (compositor-only properties)
+- W3C — `prefers-reduced-motion` media query, https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion
+- Framer Motion — Spring animation configuration documentation
+- Val Head — _Designing Interface Animation_ (2016), motion design principles for UI
+- Issara Willenskomer — "Creating Usability with Motion" (UX in Motion Manifesto)
+
+## 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-motion-principles/skill.yaml

@@ -0,0 +1,37 @@
+name: design-motion-principles
+version: "1.0.0"
+description: Purposeful animation — Disney's 12 principles adapted for UI, easing curves, duration guidelines, choreography, motion as feedback vs decoration, reducing motion
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-micro-interactions
+  - design-transitions-timing
+  - design-gestalt-common-fate
+  - a11y-motion-animation
+stack_signals: []
+keywords:
+  - motion
+  - animation
+  - easing
+  - duration
+  - choreography
+  - Disney-principles
+  - reduced-motion
+  - purposeful-animation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-naming-conventions/SKILL.md

@@ -0,0 +1,200 @@
+# Naming Conventions
+
+> Design system nomenclature for semantic and descriptive names, color naming, size naming, and maintaining consistent vocabulary across design and code.
+
+## When to Use
+
+- Establishing naming patterns for a new design system's tokens, components, or variants
+- Resolving naming inconsistencies between design files (Figma) and code (React/CSS)
+- Renaming tokens or components during a system refactor without breaking consumers
+- Debating whether a color should be called "blue-500" or "brand-primary" (the answer is both, at different layers)
+- Writing a naming convention guide for contributors to follow
+
+## Instructions
+
+Names are the primary interface of a design system. A developer reads a name and must immediately understand what the thing does, where it belongs, and how it relates to other things. Bad names create ambiguity that compounds across hundreds of components and thousands of tokens.
+
+**The naming decision procedure:**
+
+1. **Determine the layer.** Is this a primitive (named by what it IS), a semantic token (named by what it DOES), or a component (named by what it RENDERS)?
+2. **Apply the layer's convention.** Primitives use descriptive names. Semantic tokens use purpose names. Components use noun-based names.
+3. **Check for collisions.** Does this name conflict with or shadow an existing name in the system? Search the token and component registries.
+4. **Check for lies.** Will this name become inaccurate if the underlying value changes? If `color-blue-primary` is renamed when the brand shifts to purple, it was a bad name from the start.
+5. **Check for ambiguity.** Can two reasonable people disagree about what this name refers to? If yes, the name is too vague.
+
+## Details
+
+### Descriptive vs Semantic Naming
+
+The core distinction in design system naming is between descriptive names (what something IS) and semantic names (what something is FOR).
+
+**Descriptive names** state the literal value or appearance:
+
+```
+color.blue.500          /* describes the hue and lightness */
+font.size.16            /* describes the pixel value */
+spacing.8               /* describes the pixel value */
+border.radius.4         /* describes the pixel value */
+```
+
+**Semantic names** state the purpose or role:
+
+```
+color.background.brand       /* describes the role in the interface */
+font.size.body              /* describes where it is used */
+spacing.inline.md           /* describes the spatial relationship */
+border.radius.control       /* describes what it rounds */
+```
+
+Both are necessary. Primitives use descriptive names because their purpose is to catalog available values. Semantic tokens use purpose names because their purpose is to encode decisions. A system with only descriptive names cannot theme. A system with only semantic names cannot be audited for palette coverage.
+
+**IBM Carbon** maintains both layers explicitly. Their SCSS exposes `$blue-60: #0f62fe` (descriptive primitive) and `$interactive-01: $blue-60` (semantic alias). Developers use `$interactive-01`; the descriptive name exists only in the token definition file.
+
+### Color Naming
+
+Color naming is the most contentious area of design system nomenclature. The decision tree:
+
+**Primitive color names** use hue + numeric scale:
+
+```
+red.50, red.100, red.200 ... red.900, red.950
+blue.50, blue.100, blue.200 ... blue.900, blue.950
+neutral.50, neutral.100 ... neutral.950
+```
+
+The numeric scale represents lightness, not importance. 50 is lightest, 950 is darkest. This convention (used by Tailwind, Radix, Stripe, GitHub Primer) is the de facto standard. Avoid inventing custom scales (1-10, light/medium/dark) unless your system has a documented reason.
+
+**Semantic color names** use role-based categories:
+
+| Category       | Examples                                                          | Purpose         |
+| -------------- | ----------------------------------------------------------------- | --------------- |
+| `background.*` | `background.default`, `background.subtle`, `background.brand`     | Surface colors  |
+| `text.*`       | `text.default`, `text.subtle`, `text.disabled`, `text.on-brand`   | Text foreground |
+| `border.*`     | `border.default`, `border.focus`, `border.error`                  | Edge colors     |
+| `icon.*`       | `icon.default`, `icon.subtle`, `icon.brand`                       | Icon foreground |
+| `status.*`     | `status.success`, `status.warning`, `status.error`, `status.info` | Feedback colors |
+
+GitHub Primer uses `--color-fg-default` (foreground/text), `--color-canvas-default` (background), `--color-border-default`. The `fg`/`canvas`/`border` prefix groups by surface type, and `default`/`subtle`/`muted`/`emphasis` suffix indicates prominence.
+
+**What NOT to name colors:**
+
+- Avoid emotion words: `color.happy`, `color.calm`. These are subjective and culture-dependent.
+- Avoid use-case specifics at the semantic layer: `color.sidebar-background`. This belongs in component tokens.
+- Avoid compound descriptors: `color.light-blue-ish`. If it does not fit a hue name, define a new hue.
+
+### Size Naming
+
+Size naming must be consistent across all dimensions: component sizes, spacing, typography, and icon sizes.
+
+**T-shirt sizes** are the most common convention:
+
+```
+xs, sm, md, lg, xl, 2xl, 3xl
+```
+
+**Rules for t-shirt size scales:**
+
+- `md` is always the default. If a component has a `size` prop, omitting it should give `md`.
+- Never go below `xs` or above `3xl`. If you need more, your scale is too granular.
+- The scale must be arithmetic or geometric, not arbitrary. Atlassian uses: xs=24, sm=32, md=40, lg=48 (linear +8). Material uses: sm=36, md=40, lg=56 (non-linear, justified by touch target research).
+
+**Numeric scales** are used when t-shirt sizes are insufficient:
+
+```
+spacing.0, spacing.1, spacing.2, spacing.3, spacing.4, spacing.6, spacing.8
+```
+
+These reference a base unit. If `spacing.1 = 4px`, then `spacing.4 = 16px`. The convention: the number IS the multiplier, not the pixel value. Tailwind uses `p-4` = `16px` (4 \* 4px base). Material uses `dp` units directly.
+
+**Never mix conventions within a category.** If component sizes use t-shirt sizes, all components use t-shirt sizes. If spacing uses numeric scales, all spacing uses numeric scales. Shopify Polaris uses t-shirt sizes for components and numeric tokens for spacing -- this is a clean split across categories, not mixing within one.
+
+### Cross-Discipline Vocabulary
+
+Design systems span design tools (Figma), code (React/CSS), and documentation. Names must survive the translation across all three.
+
+**The vocabulary alignment checklist:**
+
+1. **Figma component name = Code component name.** If Figma calls it "Action Card" and code calls it `InteractiveCard`, contributors will use the wrong name in discussions. Shopify Polaris enforces 1:1 Figma-to-code naming: `Button/Primary/Medium` in Figma maps to `<Button variant="primary" size="medium">`.
+2. **Figma variant properties = Code props.** Figma's variant axis "Type: Primary | Secondary | Ghost" must map to the code prop `variant: 'primary' | 'secondary' | 'ghost'`, not `type` or `appearance` or `kind`.
+3. **Token names are identical in Figma and code.** If Figma uses `color/background/brand` and code uses `--color-bg-brand`, the abbreviation `bg` vs `background` creates confusion. Pick one and enforce it everywhere.
+
+**Vocabulary register (maintain in your documentation):**
+
+| Concept          | Accepted Term | Rejected Alternatives                 | Rationale                                                     |
+| ---------------- | ------------- | ------------------------------------- | ------------------------------------------------------------- |
+| Visual form      | `variant`     | `type`, `kind`, `appearance`, `style` | `type` conflicts with HTML `type`; `style` conflicts with CSS |
+| Prominence level | `emphasis`    | `priority`, `weight`, `level`         | Aligns with Material Design terminology                       |
+| Size             | `size`        | `dimension`, `scale`                  | Most universally understood                                   |
+| Disabled state   | `disabled`    | `inactive`, `locked`, `frozen`        | HTML native attribute name                                    |
+| Loading state    | `loading`     | `pending`, `busy`, `processing`       | Most common in design system literature                       |
+
+Atlassian maintains a public glossary of over 60 terms that all contributors must use. Their glossary explicitly lists rejected synonyms for each term.
+
+### Component Naming
+
+Component names should be nouns that describe what the component renders, not what it does.
+
+**Good names:** `Button`, `Card`, `Dialog`, `Avatar`, `Badge`, `Tooltip`, `DataTable`
+**Bad names:** `Clickable`, `Displayable`, `Openable`, `Toggleable`
+
+**Compound component naming** uses dot notation or directory nesting:
+
+```
+/* Dot notation (React) */
+Dialog.Header, Dialog.Body, Dialog.Footer
+
+/* Directory nesting (file system) */
+Dialog/
+  DialogHeader.tsx
+  DialogBody.tsx
+  DialogFooter.tsx
+  index.tsx        /* exports Dialog with sub-components attached */
+```
+
+**Prefix conventions for sub-components:**
+
+- Same-component children: `Dialog.Header` (parent name as namespace)
+- Shared utility components: `VisuallyHidden`, `Portal`, `FocusTrap` (descriptive, no namespace)
+- Layout components: `Stack`, `Inline`, `Grid`, `Box` (abstract spatial nouns)
+
+### Anti-Patterns
+
+**Abbreviation inconsistency.** Using `bg` in some tokens and `background` in others, `sm` in some contexts and `small` in others. Every abbreviation must be listed in the vocabulary register and used uniformly. GitHub Primer uses `fg` (foreground) consistently across 200+ tokens -- it appears abbreviated everywhere or nowhere.
+
+**Semantic names that encode visual properties.** Naming a token `color.text.bold` (a visual treatment) instead of `color.text.emphasis` (a semantic role). When the emphasis style changes from bold to a different color, the name `bold` becomes misleading. Semantic names must survive implementation changes.
+
+**Platform-specific naming in shared tokens.** Naming a token `ios-blue` or `android-elevation` in the shared token file. Platform-specific mappings belong in the transform layer, not the token definition. The token is `color.background.brand`; the iOS-specific hex value is a build artifact.
+
+**Verb-based component names.** `ShowDetails`, `ToggleMenu`, `LoadData`. Components are things (nouns), not actions (verbs). The action is what the component enables; the name is what it is. `ToggleMenu` should be `Menu` with an `open` state. `ShowDetails` should be `Disclosure` or `Accordion`.
+
+**Numbered variants without meaning.** `button-1`, `button-2`, `button-3` in Figma or `CardV2`, `NewCard`, `CardFinal` in code. These names carry no information about what differs between them. If the distinction is not worth naming, it is not worth having.
+
+### Real-World Examples
+
+**Salesforce Lightning** maintains a naming matrix that maps every concept to four representations: Figma layer name, CSS class, design token, and documentation label. Their `SLDS` prefix (`slds-button`, `slds-card`) acts as a namespace to avoid collisions with consumer code. Component variants use BEM-like modifiers: `slds-button_brand`, `slds-button_neutral`, `slds-button_destructive`.
+
+**IBM Carbon** uses a strict CTI (Category-Type-Item) convention across all tokens. Colors follow `$carbon--{category}-{usage}-{property}-{variant}`: `$carbon--interactive-01` (primary interactive color), `$carbon--ui-background` (page background), `$carbon--text-01` (primary text). The numbered suffix (01, 02, 03) indicates prominence hierarchy within a category.
+
+**Shopify Polaris** aligns Figma and code naming with a published 1:1 mapping table. Their component names are plain English nouns: `Button`, `Card`, `Modal`, `Banner`, `Badge`. Variant names are adjective-like: `primary`, `critical`, `warning`, `success`. Size names use t-shirt convention without exception: `slim`, `medium`, `large` (they use `slim` instead of `small` to avoid confusion with type sizes).
+
+**Material Design 3** prefixes all tokens with `md.sys.` (system-level) or `md.comp.` (component-level), creating an unambiguous namespace. Color roles use a `on-` prefix for foreground-on-surface pairs: `md.sys.color.primary` (surface) and `md.sys.color.on-primary` (content on that surface). This pairing convention eliminates guesswork about which text color goes on which background.
+
+## Source
+
+Nathan Curtis, "Naming Tokens in Design Systems" (2020). Jina Anne, "Design Tokens W3C Community Group" naming guidelines. Brad Frost, "Naming Design System Components" (2019). Ethan Marcotte, "Naming Things" (A List Apart, 2013). Salesforce Lightning Design System Naming Conventions documentation.
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/design-naming-conventions/skill.yaml

@@ -0,0 +1,35 @@
+name: design-naming-conventions
+version: '1.0.0'
+description: Design system nomenclature for semantic and descriptive names, color naming, size naming, and cross-discipline vocabulary
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-token-architecture
+  - design-component-anatomy
+  - design-design-governance
+stack_signals: []
+keywords:
+  - naming
+  - semantic-names
+  - descriptive-names
+  - vocabulary
+  - nomenclature
+  - color-naming
+  - size-naming
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-navigation-ux/SKILL.md

@@ -0,0 +1,150 @@
+# Navigation UX
+
+> Wayfinding — navigation models (hub-spoke, hierarchy, flat, content-driven), persistent vs contextual nav, breadcrumbs, information scent
+
+## When to Use
+
+- Designing the navigation architecture for a new application or website
+- Restructuring navigation in an existing product that has grown organically and become disoriented
+- Choosing between sidebar, top bar, bottom tab, hamburger menu, or command palette navigation
+- Evaluating whether users can answer the three wayfinding questions: Where am I? Where can I go? How do I get back?
+- Building deep content hierarchies (documentation sites, e-commerce catalogs, admin dashboards)
+- Designing mobile navigation where screen real estate constrains persistent nav options
+- Adding search or command palette navigation to complement structural navigation
+- Diagnosing analytics that show high bounce rates, circular navigation paths, or users hitting the back button repeatedly
+
+## Instructions
+
+1. **Select a navigation model based on content architecture and user behavior.** There are four fundamental models, each suited to different information structures:
+
+   | Model              | Structure                         | Best For                                   | Example                  |
+   | ------------------ | --------------------------------- | ------------------------------------------ | ------------------------ |
+   | **Hub-and-Spoke**  | Central hub, independent sections | Mobile apps, task-focused tools            | iOS Settings, Uber       |
+   | **Hierarchy**      | Tree structure, parent-child      | Documentation, e-commerce, file systems    | GitHub repo, AWS Console |
+   | **Flat/Matrix**    | All sections equally accessible   | Dashboards, command palettes, social feeds | Linear, Notion sidebar   |
+   | **Content-Driven** | Navigation embedded in content    | Media, editorial, onboarding flows         | Medium, Netflix, Spotify |
+
+   Hub-and-spoke works when sections are independent — completing a task in one section does not require visiting another. Hierarchy works when content has natural parent-child relationships. Flat works when expert users need rapid access to any section. Content-driven works when the content itself suggests the next destination.
+
+2. **Ensure users can always answer three questions.** Miller and Remington's wayfinding research (2004) established that effective navigation answers: (a) Where am I? — the current location must be visually highlighted (active state in nav, breadcrumb, page title). (b) Where can I go? — available destinations must be visible or one interaction away. (c) How do I get back? — return paths must be obvious (back button, breadcrumb, persistent nav). If your navigation fails any of these three, users become disoriented. GitHub answers all three: the repository breadcrumb shows "where am I" (org/repo/path), the file tree shows "where can I go," and the breadcrumb links show "how do I get back."
+
+3. **Use persistent navigation for primary sections, contextual navigation for secondary.** Persistent navigation (always visible: sidebar, top bar, bottom tabs) should contain only the top 5-7 destinations that users visit frequently. Beyond 7, the navigation becomes a scanning task rather than a recognition task (Miller's Law). Secondary and tertiary destinations belong in contextual navigation: dropdown menus, command palettes, breadcrumb paths, or in-page links that appear only when relevant. Vercel's persistent nav has exactly 5 items: Overview, Deployments, Analytics, Logs, Settings. Everything else is contextual.
+
+4. **Implement breadcrumbs for hierarchies deeper than 2 levels.** Breadcrumbs solve the "where am I?" question for deep hierarchies and provide one-click access to any ancestor. Each breadcrumb segment must be a link. The current page should be the last item, not linked (to avoid the "clicking the current page" confusion). Separator characters (/ or >) between segments must not be clickable. GitHub's file navigation is the benchmark: `org / repo / src / components / Button.tsx` — each segment is clickable, the current file is displayed but not linked, and the hierarchy is instantly legible.
+
+5. **Design information scent that guides users toward their goal.** Information scent (Pirolli and Card, 1999) is the degree to which a navigation label predicts the content behind it. Strong scent: "Billing and Invoices" clearly leads to payment history. Weak scent: "Resources" could contain documentation, blog posts, templates, or downloads. The rules for strong information scent:
+   - Use specific nouns, not abstract categories ("Billing" not "Account," "API Keys" not "Settings")
+   - Include the most common search terms in navigation labels (what users type in search should appear in nav)
+   - Front-load distinguishing words ("Deployment Settings" not "Settings for Deployments")
+   - Test labels with a card sort: show users the label alone and ask where they expect it to lead
+
+6. **Choose the right navigation container for the platform and content depth.**
+   - **Top bar:** Best for 3-7 primary sections on desktop. Vercel, Stripe Dashboard, GitHub. Scales poorly beyond 7 items. Not suitable for deep hierarchies without a supplementary sidebar.
+   - **Sidebar:** Best for 5-20+ sections with hierarchy. AWS Console, VS Code, Notion. Supports nested groups, expandable sections, and scroll. Can be collapsed to icons for space recovery. Linear uses a collapsible sidebar with team/project hierarchy.
+   - **Bottom tabs (mobile):** Best for 3-5 primary sections on mobile. iOS tab bar standard. Instagram, Spotify, Airbnb. Must never exceed 5 tabs (Apple HIG). Icons must be paired with labels — icon-only bottom tabs fail user testing consistently.
+   - **Hamburger menu:** A concession to space constraints, not a navigation strategy. Hides all navigation behind a single icon. Research by NNGroup (2016) showed that visible navigation increases feature discovery by 25-50% compared to hamburger menus. Use only when persistent navigation genuinely cannot fit, and supplement with visible shortcuts to the most-used sections.
+   - **Command palette:** Flat-access overlay invoked by keyboard shortcut (Cmd+K / Ctrl+K). Linear, VS Code, Figma, Vercel, GitHub. Best as a supplement to structural navigation, not a replacement — it serves expert users who know what they want and can type it.
+
+7. **Maintain spatial consistency across navigation transitions.** When a user navigates from Page A to Page B via the sidebar, Page B should appear in the content area while the sidebar remains stable. The sidebar should not scroll, reorder, or collapse during navigation — the persistent frame must persist. Apple's iOS navigation controller maintains spatial consistency through push/pop animations: new content slides in from the right, back navigation slides from the left. This builds spatial memory — users develop a mental model of "forward is right, back is left." Violating spatial consistency (content appears from random directions, navigation items rearrange) destroys the user's spatial model and causes disorientation.
+
+8. **Provide multiple navigation paths to the same destination.** Expert users and novice users navigate differently. Novices browse (following hierarchical paths, reading labels). Experts search (command palette, URL manipulation, keyboard shortcuts). Both need to reach the same content. GitHub supports at least four paths to any file: (1) browse the file tree, (2) use the "Go to file" search (T shortcut), (3) modify the URL directly, (4) search with the site-wide search bar. Each path serves a different user expertise level and context.
+
+## Details
+
+### Navigation Model Deep Dives
+
+**Hub-and-Spoke** is the dominant mobile pattern. The "hub" is a home screen or dashboard. "Spokes" are independent feature areas. Users always return to the hub before navigating to a different spoke. iOS Settings is pure hub-and-spoke: tap a category (spoke), configure it, tap "Back" to return to the settings list (hub), then tap another category. The strength is simplicity — users never get lost because the hub is always one tap away. The weakness is inefficiency — moving between spokes requires a hub round-trip. Solutions: add cross-spoke shortcuts (deep links from one spoke to a related spoke) or promote the most common cross-spoke paths to the hub.
+
+**Hierarchy** reflects content with natural parent-child relationships: file systems, documentation, e-commerce catalogs. AWS Console is a deep hierarchy: Service > Resource Type > Resource > Configuration Tab > Specific Setting. Hierarchies need breadcrumbs (essential), collapsible tree views (helpful), and "jump to" search (essential for hierarchies deeper than 3 levels). The critical design decision is hierarchy width vs depth. Broad, shallow hierarchies (many items per level, few levels) support scanning. Deep, narrow hierarchies (few items per level, many levels) support drill-down. Research by Larson and Czerwinski (1998) found that broad hierarchies outperform deep ones for information retrieval — users complete tasks faster with 8x8 (64 items, 2 levels) than 2x2x2x2x2x2 (64 items, 6 levels).
+
+**Flat/Matrix navigation** gives all sections equal structural weight. There is no parent-child relationship — every section is a peer. Linear's sidebar lists Inbox, My Issues, Views, Teams, and Projects at the same level. The command palette (Cmd+K) provides flat access to everything. This model works when: (a) users have clear goals and know what they want, (b) sections are independent, and (c) the total section count is manageable (under 20). Beyond 20 flat items, users cannot scan the list efficiently and the model degrades.
+
+**Content-driven navigation** embeds navigation choices within the content itself — "related articles" links, "you might also like" recommendations, "next episode" auto-play. Netflix is almost entirely content-driven: rows of suggestions, each item linking to its detail page, which contains more suggestions. The structural navigation (home, search, my list) is minimal. Content-driven navigation works for exploration and discovery scenarios but fails for goal-directed tasks — if the user knows exactly what they want, embedded suggestions are noise.
+
+### Breadcrumb Design Specifications
+
+Breadcrumbs appear trivial but have specific design requirements:
+
+- **Position:** Top of the content area, below the global navigation bar, above the page title. Consistent across all pages.
+- **Separator:** "/" (file-path metaphor) or ">" (hierarchy metaphor). Choose one and use it consistently. Not clickable — only the segment text is clickable.
+- **Current page:** Displayed as the last segment. Not linked (prevents "click current page" confusion). Visually distinguished (bold weight or reduced opacity compared to ancestor links).
+- **Truncation:** For deep hierarchies (>5 levels), show first segment, ellipsis, last 2-3 segments: `Home / ... / Components / Button / Variants`. The ellipsis should be clickable, revealing a dropdown of hidden segments.
+- **Mobile:** Breadcrumbs often collapse to a single "Back to [parent]" link on mobile, since the full path does not fit. This is acceptable — the "back" affordance answers "how do I get back?" which is the highest-priority wayfinding question on mobile.
+
+### Command Palette Design
+
+The command palette (Cmd+K) has become a standard navigation supplement in developer and productivity tools. Design requirements:
+
+- **Invocation:** Keyboard shortcut (Cmd+K or Ctrl+K) and a visible search icon/button for discoverability. Linear shows a persistent search bar in the sidebar. VS Code shows a magnifying glass icon in the activity bar.
+- **Fuzzy matching:** Users do not type exact nav labels. "depl sett" should match "Deployment Settings." Use fuzzy search algorithms (Fuse.js, fzf-style matching) that tolerate typos and abbreviations.
+- **Result categories:** Group results by type: Pages, Actions, Settings, Recent. Vercel's command palette groups by: Navigation, Commands, Teams, Projects. Each group has a heading and results are ranked by relevance within groups.
+- **Recent/frequent prioritization:** Show recently visited pages and frequently used commands at the top before the user types anything. This makes the command palette useful as a "quick jump" tool, not just a search tool.
+- **Keyboard navigation:** Arrow keys to move between results, Enter to select, Escape to close. Tab to cycle between result categories. The entire interaction must be keyboard-only accessible — mouse is optional.
+
+### Spatial Memory and Animation Direction
+
+Users build spatial models of applications. After using an app for days, they develop a sense of "where things are" — settings feels like it is "to the right," notifications feel "above," profile feels "in the corner." Navigation animations should reinforce these spatial models:
+
+- **Horizontal push/pop:** Used for peer-to-peer or sequential navigation (pages at the same hierarchy level, wizard steps). Content slides left to go "forward," right to go "back." Apple's UINavigationController and Android's Fragment transactions use this.
+- **Vertical slide:** Used for hierarchy changes. Content slides up to go "deeper" (into a detail view), down to go "shallower" (back to a list). Bottom sheets slide up from below.
+- **Fade/crossfade:** Used for non-spatial transitions where direction is meaningless (tab switches, same-position content swaps). Vercel uses crossfade for switching between dashboard tabs — there is no spatial relationship between "Deployments" and "Analytics."
+- **Scale/zoom:** Used for focus changes. Zooming in (scaling up) to enter a detail view, zooming out (scaling down) to return to an overview. Figma uses scale transitions when zooming into a frame.
+
+### Anti-Patterns
+
+1. **The Junk Drawer.** A navigation item labeled "More," "Resources," "Other," or "Misc" that contains unrelated items that did not fit elsewhere. This is a failure of information architecture — the categories are wrong if items do not fit. Fix: restructure categories so every item has a natural home. If truly disparate items remain, consider whether they need to be in the navigation at all (maybe they belong in footer links, a help center, or a settings page).
+
+2. **Navigation Inconsistency Across Pages.** The sidebar has 6 items on the dashboard, 4 items on the settings page, and 8 items on the analytics page — the navigation itself changes depending on where you are. Users lose their spatial model. Fix: persistent navigation must be literally persistent — same items, same order, same position on every page. Contextual nav can change, but the persistent frame must not.
+
+3. **Deep Hamburger Hiding.** Hiding all navigation — including primary sections — behind a hamburger menu on desktop viewports where screen real estate is abundant. NNGroup's research (2016) found 25-50% lower feature discovery when navigation is hidden. The hamburger menu is a mobile compromise, not a desktop design choice. Fix: on desktop (>1024px), show primary navigation persistently. Use the hamburger only on mobile viewports where space genuinely requires it.
+
+4. **Breadcrumb-less Deep Hierarchies.** A documentation site or admin panel with 4+ hierarchy levels and no breadcrumbs. Users navigate in, lose track of their position, and resort to the browser back button (which may not correspond to the hierarchy path if they arrived via search or deep link). Fix: add breadcrumbs to every page deeper than level 2.
+
+5. **Icon-Only Navigation Without Labels.** A sidebar of 8 cryptic icons with no text labels, tooltips only on hover, and no visible way for a new user to learn what each icon means. Requires memorization of an arbitrary icon vocabulary. Fix: always pair icons with visible text labels. If space requires icon-only mode, add persistent tooltips on hover and ensure every icon follows established conventions (gear for settings, bell for notifications, house for home).
+
+### Real-World Examples
+
+**GitHub Repository Navigation.** GitHub's repository page is a masterclass in multi-model navigation. The top tab bar (Code, Issues, Pull Requests, Actions, etc.) is flat navigation — all sections are peers. Within Code, the file tree is hierarchical navigation with breadcrumbs. The "Go to file" shortcut (T key) is command palette navigation. The global search bar is search navigation. The breadcrumb path (org/repo/path) provides wayfinding. All four navigation models coexist, each serving a different user need: browsing (hierarchy), scanning (tabs), jumping (command palette), searching (search bar).
+
+**Linear's Keyboard-First Navigation.** Linear's navigation is designed for speed. The sidebar provides structural navigation (Teams, Projects, Views). The command palette (Cmd+K) provides flat access to everything — issues, projects, settings, actions. Keyboard shortcuts (G then I for "Go to Inbox," G then M for "Go to My Issues") provide direct access without any visual navigation interaction at all. The three layers serve three user expertise levels: sidebar for learning, command palette for intermediate, shortcuts for expert. The transition between layers is seamless — a user can use all three in a single session.
+
+**Apple iOS Navigation Hierarchy.** iOS establishes spatial navigation conventions that billions of users have internalized. Push (slide from right): navigate deeper. Pop (slide from left): navigate shallower. Modal (slide from bottom): temporary context (compose, alert, picker). Dismiss (slide to bottom): close temporary context. These four animations create a complete spatial vocabulary. Every native iOS app that follows these conventions benefits from the user's pre-existing spatial model. Apps that violate them (custom transitions that do not match the push/pop/modal/dismiss model) feel disorienting because they break the learned spatial language.
+
+**Airbnb's Content-Driven Navigation.** Airbnb's home page navigation is almost entirely content-driven. Category pills (Icons, Beach, Cabins, Pools) filter the content grid. The grid items themselves are the primary navigation — each listing card leads to a detail page. The detail page uses content-driven navigation: a "More places to stay" section at the bottom continues the browsing journey. Structural navigation (search bar, profile menu, saved, trips) is minimal and positioned to not compete with content browsing. The design optimizes for exploration — users who do not have a specific destination in mind should find one through content, not through navigation menus.
+
+### Navigation Testing Methodology
+
+Validate navigation design with these three tests:
+
+**First-click test.** Show users a screenshot of the interface and ask them to click where they would go to complete a specific task ("Find your billing history"). If more than 70% of users click the correct navigation item on their first attempt, the information scent is strong. Below 50% indicates a labeling or hierarchy problem. Tools: Optimal Workshop, UsabilityHub.
+
+**Tree test (reverse card sort).** Present the navigation hierarchy as a text-only tree (no visual design) and ask users to navigate to specific content. This isolates information architecture from visual design — if users cannot find content in the tree, no amount of visual polish will save the navigation. Target: 80%+ success rate for critical tasks. Run tree tests before any visual design work — fixing IA problems in code is 10x more expensive than fixing them in a tree test.
+
+**Back button audit.** Navigate through every major flow in the application and press the browser back button at each step. Does it return to the expected previous page? Does the previous page preserve its state (scroll position, filter selections, form data)? SPA frameworks often break back-button expectations by treating route changes as forward-only — verify that history management works correctly for every navigation path.
+
+**Navigation path analysis.** In production, track the actual navigation paths users take to reach key pages. If users consistently take 4 clicks to reach a page that should be 2 clicks away, the navigation structure has a depth problem. If users consistently use search to find pages that are in the navigation, the labels have an information scent problem. Google Analytics User Flow and Hotjar recordings both support this analysis.
+
+## Source
+
+- Pirolli, P. and Card, S. — "Information Foraging" (1999), information scent theory
+- Miller, C. and Remington, R. — "Modeling Information Navigation" (2004), wayfinding in digital spaces
+- Larson, K. and Czerwinski, M. — "Web Page Design: Implications of Memory, Structure and Scent for Information Retrieval" (1998), hierarchy breadth vs depth
+- Nielsen Norman Group — "Hamburger Menus and Hidden Navigation Hurt UX Metrics" (2016)
+- Apple Human Interface Guidelines — Navigation patterns, https://developer.apple.com/design/human-interface-guidelines/navigation
+- Material Design — Navigation patterns, https://m3.material.io/foundations/adaptive-design/large-screens
+
+## 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.