@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/design-gestalt-common-fate/SKILL.md

@@ -0,0 +1,214 @@
+# Gestalt Common Fate
+
+> Motion grouping — elements that move or change together are perceived as a unit, with implications for animation, loading states, and batch operations
+
+## When to Use
+
+- Designing animations where multiple elements should feel like a single group
+- Building loading states, skeleton screens, and shimmer effects
+- Implementing batch operations (select all, bulk delete, multi-drag)
+- Creating carousel, slider, and horizontal scroll interactions
+- Designing coordinated state transitions (page transitions, tab switches, expand/collapse)
+- Evaluating why an animation feels disconnected or a batch operation feels like separate actions
+
+## Instructions
+
+1. **Understand the law.** The Gestalt principle of common fate states that elements moving in the same direction, at the same speed, at the same time are perceived as a single group. This principle extends beyond literal motion to any synchronized change: opacity transitions, color shifts, scale transforms. If elements change together, they are perceived as a unit. If one element changes while others remain static, it is perceived as separate from the group.
+
+   **Why this matters for interfaces:** Digital interfaces are temporal — they change over time. Every animation, transition, and state change is an opportunity to communicate grouping through common fate. A well-designed animation tells the user "these things belong together" just as powerfully as proximity or similarity.
+
+2. **Synchronize grouped elements in animations.** When elements belong to the same group, their animations must share timing parameters: same duration, same easing curve, same delay. Any deviation breaks common fate and makes the elements read as independent.
+
+   **Worked example — Spotify horizontal card carousel:**
+   - When the user swipes, all visible cards translate horizontally by the same distance, at the same speed, with the same easing curve (`cubic-bezier(0.25, 0.1, 0.25, 1.0)`)
+   - This synchronized horizontal movement makes 5-6 cards feel like a single ribbon of content
+   - If one card moved faster than the others (even by 50ms), it would "detach" from the group perceptually
+   - New cards entering from the edge share the same velocity — they are immediately perceived as part of the group
+
+   **Worked example — Material Design container transform:**
+   - When a card expands to a detail view, the card's content (title, image, description) transforms together
+   - All child elements share the same timing: `duration: 300ms`, `easing: emphasized-decelerate`
+   - The content does not "fly in separately" — it scales and repositions as a unit
+   - This common fate during the transition tells the user "the detail view IS the card, expanded"
+
+   **Decision procedure for animation synchronization:**
+   1. Identify which elements form a group
+   2. Assign identical `duration`, `easing`, and `delay` values to all elements in the group
+   3. If using staggered entrance (elements appearing one by one), the stagger is the delay offset — but once visible, all elements must animate identically
+   4. Test by recording the animation and stepping through frame-by-frame — any visual separation between group members indicates a timing mismatch
+
+3. **Use staggered animation to imply sequence, not grouping.** Stagger (different delay values) creates an ordered sequence. This is the opposite of common fate — it makes elements feel sequential rather than grouped. Use stagger deliberately.
+
+   **Worked example — list item entrance animations:**
+   - Each item fades in with a 50ms stagger: item 1 at 0ms, item 2 at 50ms, item 3 at 100ms
+   - During the entrance, the items feel sequential — "item 1 leads, the others follow"
+   - After the entrance, all items are static and grouping reverts to proximity and similarity
+   - The stagger communicates: "these items have an order" (list, timeline, priority)
+
+   **When to stagger vs. synchronize:**
+   - Synchronize: items that form a single unit (cards in a carousel, filters in a bar, tabs in a row)
+   - Stagger: items that form a sequence (list entries, timeline events, step indicators)
+   - Never stagger elements that should read as a simultaneous group — a staggered navigation menu makes each item feel independent rather than part of a unified nav
+
+4. **Apply common fate to loading states.** Loading indicators that animate together signal "this is one loading process." Separate animations signal "these are independent processes."
+
+   **Worked example — skeleton screen shimmer (Facebook/Meta pattern):**
+   - Multiple placeholder rectangles (avatar, name, content lines) all share a single shimmer gradient animation
+   - The shimmer moves left-to-right across ALL placeholders simultaneously — same direction, same speed
+   - This common fate makes the entire skeleton feel like "one thing loading" rather than "six independent loading indicators"
+   - Implementation: a single `linear-gradient` animation on a parent element, with children using `overflow: hidden` to clip the gradient to their shapes. One animation, shared by all.
+
+   **Worked example — individual spinners (anti-pattern comparison):**
+   - Dashboard with 4 widget cards, each showing its own independent spinner
+   - Each spinner rotates at its own pace (started at different times, so they are out of phase)
+   - Result: 4 separate loading states competing for attention, each demanding its own "wait" from the user
+   - Fix: Use a single page-level skeleton shimmer, or synchronize all spinners to the same rotation phase
+
+5. **Apply common fate to batch operations.** When a user selects multiple items and performs a batch action, the selected items must respond as a group.
+
+   **Worked example — Gmail bulk email actions:**
+   - User selects 5 emails using checkboxes
+   - Clicks "Archive" — all 5 emails slide left simultaneously with the same duration (200ms) and easing
+   - The synchronized exit animation confirms "these 5 items were a group, and they all moved to the archive"
+   - If emails archived one by one (staggered by 100ms each), the user would perceive 5 separate archive actions, undermining the "batch" mental model
+
+   **Worked example — Figma multi-select drag:**
+   - User selects 3 design elements and drags them
+   - All 3 elements move with the cursor at exactly the same delta (same x/y offset from the drag origin)
+   - This rigid common fate makes 3 separate objects feel like a single compound object
+   - If one element lagged behind (frame rate issue), it would "detach" perceptually, creating anxiety about whether the operation is working correctly
+
+6. **Use broken common fate to signal state divergence.** When an element leaves a group (deselection, error, completion), breaking its common fate signals the departure.
+
+   **Worked example — Trello card drag between lists:**
+   - Cards in a list sit in a vertical column — static, grouped by proximity
+   - When a card is dragged, it gains elevation (shadow increases) and moves with the cursor
+   - The remaining cards animate to close the gap — they move together (common fate within the list)
+   - The dragged card moves independently from all lists — its unique motion signals "I have left the group"
+   - When dropped into a new list, the card's motion synchronizes with the target list's reflow — joining the new group through common fate
+
+   **Worked example — multi-step form with validation errors:**
+   - User submits a form. Valid fields transition smoothly to a confirmation state (fade to green check, 200ms)
+   - Invalid fields shake horizontally (150ms, 4px amplitude) — a motion completely different from the valid fields
+   - The divergent motion instantly communicates which fields need attention without reading any error messages
+   - Valid fields moved together (common fate = "these are fine"). Invalid fields moved together but differently (common fate within the error group, divergent from the success group).
+
+## Details
+
+### Timing Parameters for Common Fate
+
+Animation timing must be precise for common fate to work. Approximate values create subtle unease.
+
+**Synchronized motion — required parameters:**
+
+- **Duration:** Identical for all group members (e.g., all 200ms, not 200ms for some and 250ms for others)
+- **Easing:** Identical curve (e.g., all `cubic-bezier(0.4, 0, 0.2, 1)`, not different curves per element)
+- **Start time:** Must be within one frame (16.67ms at 60fps) of each other. Use `requestAnimationFrame` batching or CSS animation on a shared parent to guarantee synchronization.
+- **Direction:** Same vector. If the group moves right, all members move right. One element moving right while another moves down breaks common fate instantly.
+
+**Staggered sequence — acceptable parameters:**
+
+- **Delay offset:** 30-80ms between items for smooth cascade. Under 30ms, stagger is imperceptible (items feel synchronized). Over 100ms, items feel disconnected (too much gap between entries).
+- **Duration and easing:** Still identical for all items — only the delay differs.
+
+### Common Fate in Micro-Interactions
+
+Common fate operates at the micro-interaction level too:
+
+**Hover effects on grouped elements:**
+
+- A nav item with icon + text: on hover, both icon and text change color simultaneously (common fate = "these are one button")
+- If only the text changes color on hover, the icon appears to be a separate element
+
+**Toggle state changes:**
+
+- A switch component: the thumb slides right AND the track changes color AND the label updates — all in 150ms with the same easing
+- If the thumb moves in 150ms but the track color transitions in 300ms, they feel like separate components
+
+**Button press feedback:**
+
+- A button depresses: scale to 0.97, shadow reduces, background darkens — all simultaneously
+- These three property changes, occurring in common fate, create a single "press" perception
+- If the scale happens instantly but the shadow fades over 200ms, the button feels glitchy
+
+### Common Fate and Performance
+
+Synchronized animation requires consistent frame rates. If the browser drops frames on one element but not another, their common fate breaks.
+
+**Implementation strategies for reliable synchronization:**
+
+- **CSS approach:** Animate a parent container and let children inherit the transform. One animation = guaranteed synchronization.
+- **JavaScript approach:** Use `requestAnimationFrame` and update all elements in the same frame callback. Never use separate `setTimeout` or `setInterval` calls for elements that should move together.
+- **Web Animations API:** Use `element.animate()` with a shared timeline to ensure frame-level synchronization.
+- **GPU compositing:** Use `transform` and `opacity` (GPU-composited properties) rather than `top`, `left`, `width`, `height` (layout-triggering). Layout recalculation can delay one element's render relative to another, breaking common fate at the pixel level.
+
+### Anti-Patterns
+
+1. **Desynchronized loading indicators.** Multiple spinners, progress bars, or shimmer effects running at different speeds or phases. Three cards each with their own spinner, started at different times, create three independent "loading" signals. The user must track three separate processes. Fix: use a single shared animation (one shimmer gradient, one skeleton, one progress indicator) or synchronize all indicators to the same phase using a shared CSS `animation-delay: 0s`.
+
+2. **Inconsistent batch animation.** Selecting 5 items and archiving them, but each item exits with a slightly different duration or easing because the animation was applied per-element without shared timing. Fix: calculate all target positions first, then apply the animation to all elements in a single `requestAnimationFrame` tick with identical timing parameters.
+
+3. **False common fate on unrelated elements.** Two unrelated UI elements that happen to animate at the same time with the same parameters. A sidebar closing while a toast appears — if both happen to use a 200ms slide animation, they feel related when they are not. Fix: use different timing for unrelated simultaneous animations. Give the sidebar 250ms and the toast 150ms. The timing difference breaks the false common fate.
+
+4. **Breaking common fate during scroll.** Elements in a scrollable container that do not scroll together. A "sticky" header inside a scroll container that stutters (jumps between frames) appears to detach from the scrolling content, breaking the common fate of the scroll group. Fix: use CSS `position: sticky` (GPU-composited) rather than JavaScript-based scroll listeners that can lag by one or more frames.
+
+### Real-World Examples
+
+**Spotify Horizontal Carousel:**
+
+- Cards scroll as a single unit — all cards share the same translateX animation per frame
+- The scroll is momentum-based: after the user releases, all cards decelerate together using the same friction curve
+- Snap points: when the scroll settles, all cards snap to alignment simultaneously — the snap does not move one card at a time
+- This creates the perception of a continuous ribbon that the user is sliding through a viewport window
+
+**Apple iOS Page Transitions:**
+
+- When pushing a new view controller, the outgoing view translates left AND fades while the incoming view translates from right AND fades in
+- Both views use the same 350ms duration with the same spring curve
+- All elements within each view move with their parent — no element is independently animated during the transition
+- This creates a single "page turn" perception rather than "a bunch of elements rearranging"
+
+**Material Design Shared Element Transitions:**
+
+- A list item transforms into a detail view: the image scales up, the title repositions, the card boundary expands
+- All transforming elements use a single 300ms duration with `emphasized-decelerate` easing
+- Non-transforming elements fade out (list) or fade in (detail) with the same 300ms timing
+- The shared timing creates one fluid transformation rather than a disconnected disappear-and-appear
+
+**Airbnb Map Pin Clustering:**
+
+- When zooming out, nearby map pins animate toward each other and merge into a cluster pin
+- The merging pins share a common trajectory (toward the cluster centroid) and timing
+- This common fate signals "these individual listings are becoming a group"
+- When zooming in, the cluster pin splits and pins animate outward — the outward common fate signals "this group is separating into individuals"
+- The synchronized split creates a "bloom" effect that feels organic because all pins move simultaneously
+
+**Linear's Batch Operations:**
+
+- Select multiple issues, drag to a new status column
+- All selected issues lift (shadow increase) simultaneously, move with the cursor as a unit, and drop into the target column together
+- The remaining issues in the source column reflow to fill the gap — their upward movement shares common fate, signaling "we are the remaining group"
+- The dropped issues settle into the target column with a shared bounce animation, signaling "we are now part of this group"
+
+## Source
+
+- Max Wertheimer, "Experimental Studies on Seeing Motion" (1912) — foundational motion perception and grouping
+- Gunnar Johansson, "Visual Perception of Biological Motion" (1973) — common fate in motion perception
+- Material Design motion documentation (m3.material.io/styles/motion)
+- "Animation at Work" by Rachel Nabors — web animation principles and timing
+
+## 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/codex/design-gestalt-common-fate/skill.yaml

@@ -0,0 +1,33 @@
+name: design-gestalt-common-fate
+version: "1.0.0"
+description: Motion grouping — elements that move or change together are perceived as a unit, implications for animation, loading states, and batch operations
+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-state-design
+stack_signals: []
+keywords:
+  - gestalt
+  - common-fate
+  - motion-grouping
+  - animation
+  - synchronized
+  - batch-operations
+  - loading
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-gestalt-figure-ground/SKILL.md

@@ -0,0 +1,189 @@
+# Gestalt Figure-Ground
+
+> Depth perception — distinguishing foreground from background, ambiguous figure-ground as a design tool, z-axis ordering, overlay and modal perception
+
+## When to Use
+
+- Designing modals, dialogs, drawers, or overlay surfaces that must feel "above" the main content
+- Building elevation systems with shadow depths for cards, menus, popovers, and toasts
+- Creating focus states where a selected element must clearly separate from its surroundings
+- Designing dark mode color schemes where depth relationships must be maintained without shadows
+- Evaluating why an overlay feels "flat," a modal does not feel modal, or a card does not lift off the page
+- Implementing z-index strategies and preventing stacking context conflicts
+
+## Instructions
+
+1. **Understand the law.** The Gestalt principle of figure-ground states that the brain automatically separates visual input into a foreground figure (the object of attention) and a background ground (the surrounding context). This separation is not optional — the brain performs it on every visual scene. Design exploits this by controlling which elements read as "figure" (foreground, interactive, primary) and which read as "ground" (background, contextual, secondary).
+
+   **The five cues that establish figure-ground:**
+   - **Size:** Smaller elements tend to be perceived as figure; larger elements as ground
+   - **Contrast:** Higher-contrast elements read as figure against lower-contrast ground
+   - **Convexity:** Convex shapes (outward-curving) read as figure; concave regions as ground
+   - **Lower region:** Elements in the lower portion of an ambiguous display tend to be ground
+   - **Symmetry:** Symmetrical regions tend to be perceived as figure
+
+2. **Create depth through elevation and shadow.** The primary mechanism for establishing figure-ground in digital interfaces is the shadow. A shadow beneath an element signals "this element is lifted above the surface, closer to the viewer."
+
+   **Worked example — Material Design's elevation system:**
+   Material Design codifies figure-ground as literal elevation measured in dp (density-independent pixels):
+   - 0dp: page background (ground)
+   - 1dp: cards, switches (`box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)`)
+   - 4dp: app bars, elevated buttons (`box-shadow: 0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06)`)
+   - 8dp: menus, side sheets (`box-shadow: 0 8px 16px rgba(0,0,0,0.12), 0 4px 6px rgba(0,0,0,0.07)`)
+   - 16dp: navigation drawers (`box-shadow: 0 16px 24px rgba(0,0,0,0.14), 0 6px 8px rgba(0,0,0,0.1)`)
+   - 24dp: modals, dialogs (`box-shadow: 0 24px 38px rgba(0,0,0,0.14), 0 9px 46px rgba(0,0,0,0.12)`)
+
+   Each level creates a stronger figure-ground separation. The user intuitively understands: higher shadow = closer to me = more important right now.
+
+   **Decision procedure:** Assign each UI surface to one elevation level. Interactive overlays (menus, popovers, modals) must always be at a higher elevation than the content they overlay. Never place two overlapping surfaces at the same elevation — this creates ambiguous figure-ground.
+
+3. **Use scrim/overlay to reinforce modal figure-ground.** When a modal or dialog appears, the content behind it must be visually demoted to "ground." The scrim (semi-transparent overlay) accomplishes this by reducing the contrast, color saturation, and clarity of the background content.
+
+   **Worked example — Stripe's modal pattern:**
+   - Scrim: `background: rgba(0, 0, 0, 0.4)` — dims the page to 60% brightness
+   - Modal surface: white background, `border-radius: 12px`, shadow at Material 24dp equivalent
+   - The scrim simultaneously (a) establishes the modal as figure by contrast, (b) suppresses the background as ground, and (c) signals "this content is blocked until the modal is resolved"
+   - Scrim opacity matters: too light (0.1) and the background competes; too dark (0.8) and the context is lost. 0.3-0.5 is the effective range for most interfaces.
+
+   **Worked example — Apple's iOS sheet presentation:**
+   - The underlying view scales down to 95% and shifts slightly back (3D transform perspective)
+   - The sheet slides up with a white background and higher shadow
+   - This combines two figure-ground cues: shadow elevation AND size (the background becomes literally smaller, reinforcing its "ground" role)
+
+4. **Apply figure-ground to card design.** Cards are the most common figure-ground pattern in web design. A card is a figure that lifts off the page ground.
+
+   **Worked example — Stripe's pricing cards:**
+   - Background: `#f6f9fc` (light blue-gray) — this is the ground
+   - Cards: white background, subtle shadow (`0 2px 4px rgba(0,0,0,0.08)`) — these are the figures
+   - The blue-tinted ground is critical: white cards on a white background have zero figure-ground separation (no contrast between figure and ground). The tinted background creates the contrast that makes cards "lift"
+   - Shadow color: Stripe uses blue-tinted shadows (`rgba(50, 50, 93, 0.1)`) rather than pure black — this is more natural (real-world shadows pick up ambient color) and less harsh
+
+   **Decision procedure for card backgrounds:**
+   - White cards on white background: add shadow OR background tint. Shadow alone: `0 1px 3px rgba(0,0,0,0.1)`. Background tint: `#f5f5f5` to `#f0f4f8`.
+   - White cards on tinted background: shadow optional — contrast alone creates separation. If adding shadow, keep it minimal (`0 1px 2px rgba(0,0,0,0.05)`).
+   - Dark mode cards: use lighter card backgrounds on darker ground. Card: `#1e1e1e`, Ground: `#121212`. Shadow is nearly invisible in dark mode — rely on background contrast instead.
+
+5. **Handle figure-ground in dark mode.** Dark mode inverts the typical figure-ground relationship. In light mode, shadows push elements upward. In dark mode, shadows are invisible against dark backgrounds. Material Design solves this by using surface lightness as the elevation signal:
+
+   **Material Design dark mode elevation:**
+   - 0dp (ground): `#121212`
+   - 1dp (card): `#1e1e1e` (overlaid with 5% white)
+   - 4dp (app bar): `#232323` (overlaid with 9% white)
+   - 8dp (menu): `#2c2c2c` (overlaid with 12% white)
+   - 16dp (drawer): `#333333` (overlaid with 15% white)
+   - 24dp (modal): `#383838` (overlaid with 16% white)
+
+   Higher = lighter. The brain interprets lighter surfaces as closer (figure) and darker surfaces as farther (ground). This maintains the figure-ground hierarchy without any shadows.
+
+6. **Exploit ambiguous figure-ground deliberately.** In rare cases, ambiguous figure-ground creates visual interest. The classic example is Rubin's vase — the same image can be seen as a vase (figure) or two faces (ground), depending on the viewer's focus.
+
+   **Worked example — negative space logos:**
+   - FedEx: the arrow between the E and x is ground that becomes figure when noticed
+   - NBC: the white space between colored feathers forms a peacock
+   - These work because the ambiguity is resolvable — both interpretations are meaningful
+
+   **When to use ambiguity in interfaces:** Almost never. Interface design demands unambiguous figure-ground so users know what is interactive (figure) and what is context (ground). Ambiguity belongs in branding and illustration, not in functional UI.
+
+## Details
+
+### Z-Index Strategy
+
+Figure-ground in CSS is managed through z-index, and mismanaged z-index is the most common implementation failure of figure-ground design.
+
+**Define a z-index scale (not arbitrary values):**
+
+| Level    | z-index | Usage                             |
+| -------- | ------- | --------------------------------- |
+| Base     | 0       | Page content, ground              |
+| Raised   | 10      | Cards, sticky headers             |
+| Dropdown | 100     | Dropdowns, popovers, tooltips     |
+| Overlay  | 200     | Scrims, sidebar overlays          |
+| Modal    | 300     | Modals, dialogs                   |
+| Toast    | 400     | Toast notifications, snackbars    |
+| Maximum  | 500     | Development tools, debug overlays |
+
+**Never use z-index values like 9999, 99999, or 2147483647.** These indicate a z-index arms race where developers are fighting stacking context conflicts by escalating values. The fix is a defined scale — every surface has one correct level.
+
+**Stacking context isolation:** Use `isolation: isolate` on component root elements to create new stacking contexts. This prevents a z-index inside one component from competing with z-index in another component. A `z-index: 100` inside an isolated component cannot escape to compete with a `z-index: 50` in the global context.
+
+### Figure-Ground in Data Tables
+
+Tables present a figure-ground challenge: which rows are figure and which are ground?
+
+- **Zebra striping** alternates row backgrounds (`#fff` / `#f9fafb`) to create micro figure-ground separation between rows. This improves scan accuracy for wide tables where the eye might drift to an adjacent row.
+- **Hover state** temporarily promotes a row to figure: `background: #eef2ff` (blue tint) on hover signals "this row is selected as figure."
+- **Selected row** uses stronger figure treatment: `background: #e0e7ff` plus a left border accent (`border-left: 3px solid #4f46e5`). The border adds a convexity cue — the row "extends toward the viewer."
+
+### Layered Figure-Ground (Nested Depth)
+
+Complex interfaces have multiple figure-ground layers:
+
+1. Page background (deepest ground)
+2. Content cards (figure relative to page, ground relative to popovers)
+3. Popover menus (figure relative to cards)
+4. Modal dialogs (figure relative to everything)
+5. Toast notifications (figure relative to modals — the only thing above modals)
+
+Each layer must maintain unambiguous separation from adjacent layers. If a popover and a card have the same shadow depth, the popover does not feel "above" the card — its figure-ground status is ambiguous.
+
+### Anti-Patterns
+
+1. **Flat modals (no scrim, no shadow).** A modal that appears as a white box on a white page with no scrim or elevation. The brain cannot determine that this is figure — it reads as "another card appeared" rather than "an overlay is demanding my attention." Fix: always use a scrim (rgba backdrop) plus a shadow that exceeds any other shadow on the page. The modal must be at the highest elevation in the system.
+
+2. **Shadow inflation.** Every element has a drop shadow — cards, buttons, inputs, headers, footers. When everything casts a shadow, nothing lifts off the ground. Shadow becomes noise rather than signal. Fix: reserve shadows for true figure-ground separation (cards on a page, menus over content, modals over everything). Flat elements (buttons, inputs, text) should not have shadows in their default state. Stripe uses shadows on exactly two things: cards and modals.
+
+3. **Z-index escalation.** Starting with `z-index: 1` for a dropdown, then needing `z-index: 10` for a modal, then `z-index: 9999` for a toast because a third-party widget injected `z-index: 1000`. Fix: define a z-index scale as a design token. Use stacking context isolation. Audit third-party widgets for rogue z-index values.
+
+4. **Identical elevation on overlapping surfaces.** Two overlapping cards with the same shadow — which is on top? The brain cannot resolve this. Fix: any surface that overlaps another must be at a visibly different elevation. If two cards can overlap (e.g., in a draggable UI), the dragged card must gain elevation (increase shadow) to signal "I am above."
+
+### Real-World Examples
+
+**Stripe's Blue-Tinted Shadows:**
+
+- Card shadow: `0 13px 27px -5px rgba(50, 50, 93, 0.25), 0 8px 16px -8px rgba(0, 0, 0, 0.3)`
+- The first shadow is blue-tinted (Stripe's brand color influence), creating a subtle cool depth
+- The second shadow is darker and tighter, anchoring the card to the page
+- This dual-shadow technique creates more natural-feeling depth than a single shadow — real objects cast both a diffuse ambient shadow and a tighter contact shadow
+
+**Material Design Elevation System:**
+
+- The spec defines 25 elevation levels (0-24dp), but most apps use only 5-6
+- Elevation is a first-class design token: `--md-sys-elevation-level1` through `--md-sys-elevation-level5`
+- In dark mode, elevation is expressed as surface tint rather than shadow — a fundamentally different rendering that maintains the same semantic meaning (higher = figure)
+- The FAB (Floating Action Button) sits at 6dp — higher than cards (1dp) but lower than modals (24dp) — establishing a clear mid-layer figure position
+
+**Apple's Sheet Presentation:**
+
+- iOS 15+ presents sheets with the parent view scaled to ~95% and pushed slightly back
+- The sheet's white surface at full scale + the parent at reduced scale creates an unambiguous figure-ground separation using three cues simultaneously: shadow, size, and position
+- Interactive dismissal (drag down) smoothly reverses the figure-ground — the sheet shrinks as the parent grows back, maintaining the depth metaphor throughout the animation
+
+**Vercel's Minimal Elevation:**
+
+- Vercel uses almost no shadows — depth is created entirely through background contrast
+- Cards: white background on `#fafafa` ground, no shadow, 1px border `#eaeaea`
+- This "flat depth" approach works because the border provides just enough figure-ground separation
+- Modals: full scrim (`rgba(0,0,0,0.5)`) + white surface — the only place Vercel uses strong depth cues, making modals feel significantly more elevated by contrast with the normally flat interface
+
+## Source
+
+- Edgar Rubin, "Visual Figures" (1915) — original figure-ground segregation research
+- Stephen Palmer, "Vision Science: Photons to Phenomenology" — modern figure-ground perception
+- Material Design elevation documentation (m3.material.io/styles/elevation)
+- "Designing Interfaces" by Jenifer Tidwell, Charles Brewer, and Aynne Valencia
+
+## 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/codex/design-gestalt-figure-ground/skill.yaml

@@ -0,0 +1,34 @@
+name: design-gestalt-figure-ground
+version: "1.0.0"
+description: Depth perception — distinguishing foreground from background, ambiguous figure-ground as design tool, z-axis ordering, overlay and modal perception
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-elevation-shadow
+  - design-gestalt-closure-continuity
+stack_signals: []
+keywords:
+  - gestalt
+  - figure-ground
+  - depth
+  - foreground
+  - background
+  - z-axis
+  - overlay
+  - modal
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-gestalt-proximity/SKILL.md

@@ -0,0 +1,162 @@
+# Gestalt Proximity
+
+> Spatial grouping — elements near each other are perceived as related, controlling group membership through distance, with common region as a proximity amplifier
+
+## When to Use
+
+- Laying out form fields and deciding which inputs belong in the same visual group
+- Designing card layouts where internal elements must read as a unit
+- Structuring navigation menus with grouped items (primary actions, settings, account)
+- Deciding padding and gap values between related vs. unrelated content blocks
+- Evaluating why a layout feels disorganized despite having correct content
+- Building settings pages, dashboards, or data-entry interfaces with many discrete controls
+
+## Instructions
+
+1. **Understand the law.** The Gestalt principle of proximity states that elements placed close together are perceived as belonging to the same group, regardless of differences in shape, color, or size. Distance is the primary grouping mechanism in visual perception — it operates before color, before shape, before any other attribute. When a user looks at a layout, the first parse their visual system performs is spatial: what is near what?
+
+2. **Apply the proximity ratio.** For any two elements that belong to the same group, the space between them must be noticeably less than the space between either element and the nearest element of a different group. The minimum effective ratio is 1:2 — intra-group spacing should be at most half the inter-group spacing. A 1:3 ratio is stronger and preferred when space allows.
+
+   **Worked example — Stripe checkout form:**
+   - Label to input field: 4px (tightly coupled — the label describes the input)
+   - Input field to next label: 24px (separates one field from the next)
+   - Last field in section to next section heading: 48px (separates logical groups)
+   - Ratio chain: 4px : 24px : 48px = 1:6:12 relative to tightest coupling
+
+   **Decision procedure:** List all element pairs. For each pair, decide: same group or different group? Assign intra-group spacing from your scale's lower values, inter-group spacing from higher values. Verify that no intra-group gap equals or exceeds any inter-group gap.
+
+3. **Use common region to amplify proximity.** Common region — enclosing elements within a shared boundary (card, background color, border) — reinforces proximity. Elements inside the same container are perceived as more strongly grouped than elements that are merely close together without a boundary.
+
+   **Worked example — Airbnb listing card:**
+   - All listing data (photo, title, price, rating, host) sits inside a single card with a subtle border-radius of 12px and 1px border
+   - Internal padding: 16px — elements are close AND enclosed
+   - Cards are separated by 24px gap — proximity alone distinguishes "inside this listing" from "the next listing"
+   - The card boundary makes the grouping unambiguous even if a user squints at the layout
+
+   **When to add common region:** When proximity alone is insufficient — typically when intra-group and inter-group spacing cannot achieve a 1:2 ratio due to layout constraints, or when elements are so numerous that spatial grouping alone creates visual noise.
+
+4. **Handle proximity conflicts.** Sometimes the layout requires elements from different groups to be physically close. This happens in dense dashboards, multi-column forms, and responsive layouts where columns collapse. Resolution strategies:
+   - **Add a divider.** A 1px line or subtle border between groups explicitly overrides proximity. Material Design uses `border-bottom: 1px solid rgba(0,0,0,0.12)` between list sections — the divider breaks the false proximity signal.
+   - **Use common region.** Wrap one group in a background color shift. Stripe's settings page uses `background: #f6f9fc` blocks alternating with white to separate groups that are vertically adjacent with only 16px between them.
+   - **Shift alignment.** Offset one group horizontally or indent it. This breaks the proximity signal by disrupting the shared axis.
+
+5. **Calibrate proximity for different densities.** The absolute pixel values change with context, but the ratio must be preserved:
+
+   | Context             | Intra-group | Inter-group | Section gap | Ratio |
+   | ------------------- | ----------- | ----------- | ----------- | ----- |
+   | Dense dashboard     | 4-8px       | 16-24px     | 32-48px     | 1:3:6 |
+   | Standard app UI     | 8-12px      | 24-32px     | 48-64px     | 1:3:6 |
+   | Marketing / landing | 16-24px     | 48-64px     | 80-128px    | 1:3:5 |
+
+   **Decision procedure:** Pick your context density. Choose a base intra-group value from the table. Multiply by 3 for inter-group. Multiply by 5-6 for section gaps. Verify all values exist on your spacing scale (4px or 8px base).
+
+6. **Apply the isolation principle (inverse proximity).** An element placed far from all other elements attracts attention through its isolation. This is proximity in reverse — the absence of nearby elements signals "this is special, different, or primary."
+
+   **Worked example — Material Design FAB (Floating Action Button):**
+   - The FAB sits 16px from the bottom-right corner, separated from all other UI elements by at least 48px of empty space
+   - No other element is within its spatial neighborhood, making it the only occupant of its region
+   - This isolation signals "primary action" without any label, border, or color treatment (though it also uses color)
+
+   **Worked example — Apple's "Buy" button on product pages:**
+   - The purchase CTA sits beneath the product details with 40px of space above and below
+   - Surrounding elements (specs, description) are 24px apart from each other
+   - The CTA's extra breathing room creates isolation, drawing the eye to the conversion action
+
+## Details
+
+### Proximity in Form Design
+
+Forms are the highest-stakes proximity challenge because users must understand which label belongs to which input, which inputs form a logical group, and where one section ends and another begins.
+
+**The label-to-input distance must always be tighter than the input-to-next-label distance.** If both distances are equal, labels appear to float between two inputs and the association becomes ambiguous — the user must read the label text to figure out which input it describes, rather than seeing the relationship spatially.
+
+**Worked example — address form:**
+
+```
+[Street Address]          <- label
+[________________]        <- input     } 4px label-to-input
+                                       } 24px input-to-next-label
+[City]                    <- label
+[________________]        <- input     } 4px label-to-input
+                                       } 24px input-to-next-label
+[State]     [Zip Code]   <- labels (inline group)
+[______]    [______]      <- inputs    } 4px label-to-input
+                                       } 48px to next section
+
+[Payment Information]     <- section heading
+```
+
+The 4px : 24px : 48px cascade makes group membership unambiguous. A user scanning vertically sees three distinct clusters (street, city, state/zip) within a larger "address" section, all separated from "payment" by a 48px gap.
+
+### Proximity in Navigation
+
+Navigation menus use proximity to signal hierarchy:
+
+- **Apple's macOS menu bar:** Menu items within a group (File > New, Open, Close) are separated by 0px — they share adjacent rows with only the row's internal 4px padding creating micro-space. A divider line (1px) appears between conceptual groups (Close vs. Save), explicitly breaking proximity where spatial distance alone cannot.
+- **Sidebar navigation (Notion, Linear, Slack):** Primary sections (Inbox, My Issues, Teams) use 4-8px between items within a section. Between sections: 16-24px gap plus a section label in muted text. The combination of extra space + label makes the grouping redundant in the best way — even a first-time user understands the structure.
+
+### Proximity on Responsive Breakpoints
+
+When a multi-column layout collapses to single-column on mobile, previously side-by-side groups become vertically stacked. This can create false proximity — a group's last element becomes adjacent to the next group's first element with the same spacing that exists within groups.
+
+**Fix:** Increase inter-group spacing by at least one step on your scale when collapsing to single column. If desktop uses 24px between groups, mobile should use 32px or 40px to compensate for the lost column separation.
+
+### Anti-Patterns
+
+1. **Equidistant spacing.** Applying the same gap (e.g., `gap: 16px`) to every element regardless of group membership. This is the most common proximity violation. The layout becomes a flat list where nothing is grouped — labels float ambiguously, form sections bleed into each other, and navigation items all appear equally related. Fix: differentiate intra-group and inter-group spacing by at least a 1:2 ratio.
+
+2. **Label proximity inversion.** Placing a label equidistant between two inputs (or closer to the wrong input). In a vertical form with 16px between a label and the input below it, and 16px between that input and the next label, the labels are perceptually unanchored. Reduce label-to-own-input spacing to 4-8px while keeping input-to-next-label spacing at 16-24px.
+
+3. **Over-boxing (common region abuse).** Wrapping every small group in a card or bordered container when proximity alone would suffice. This creates visual noise — borders compete with content for attention, the page looks like a spreadsheet, and the hierarchy flattens. Use common region only when proximity ratios cannot achieve clear grouping (dense layouts, overlapping groups, mobile collapses).
+
+4. **Proximity without hierarchy.** Grouping elements correctly by distance but failing to establish which group is primary. All groups are equally spaced from the viewport edges, equally sized, equally prominent. Proximity creates groups but does not rank them — combine with visual hierarchy (size, color, position) to indicate importance.
+
+### Real-World Examples
+
+**Stripe's Payment Form:**
+
+- Card number, expiry, CVC grouped inside a single bordered container (common region + proximity)
+- Internal padding: 12px. Between fields inside the container: 0px — they share a border, creating a single compound input
+- Container to "Pay" button: 24px. Button to terms text: 16px
+- The compound input pattern uses zero-gap proximity + shared border to make three fields feel like one
+
+**Apple iOS Notification Grouping:**
+
+- Notifications from the same app stack with 2px between them — nearly touching
+- Between app groups: 12px gap + separate card background
+- This double signal (proximity + common region) makes it instantly clear that three stacked notifications are from Messages, not from three different apps
+
+**Material Design List Sections:**
+
+- List items: 0px gap (items share adjacent rows with `56px` row height and internal padding)
+- Between sections: a `16px` gap plus a subheader label in `14px` muted text
+- The section subheader occupies its own row, creating both spatial separation and a semantic label — redundant grouping that works at a glance
+
+**Airbnb Search Filters:**
+
+- Filter pills (Price, Type, Rooms) sit in a horizontal row with 8px gap between pills
+- The filter row itself is separated from search results by 24px + a horizontal divider
+- Within the filter row, all pills use identical spacing — proximity groups them as "the filter controls" while the divider separates them from "the results"
+
+## Source
+
+- Max Wertheimer, "Laws of Organization in Perceptual Forms" (1923) — original Gestalt proximity principle
+- Stephen Palmer, "Vision Science: Photons to Phenomenology" — perceptual grouping research
+- "Refactoring UI" by Adam Wathan and Steve Schoger — proximity spacing in web interfaces
+- "Universal Principles of Design" by William Lidwell, Kritina Holden, and Jill Butler
+
+## 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.