@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/design-design-governance/skill.yaml

@@ -0,0 +1,34 @@
+name: design-design-governance
+version: '1.0.0'
+description: Living system maintenance covering contribution models, deprecation, versioning, adoption metrics, and documentation standards
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-atomic-design
+  - design-naming-conventions
+  - design-design-documentation
+stack_signals: []
+keywords:
+  - governance
+  - contribution
+  - deprecation
+  - versioning
+  - adoption
+  - documentation
+  - design-system-product
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-elevation-shadow/SKILL.md

@@ -0,0 +1,163 @@
+# Elevation & Shadow
+
+> Depth as information — shadow anatomy (offset, blur, spread, color), elevation scale, chromatic shadows, material metaphor, dark mode shadows
+
+## When to Use
+
+- Designing card, modal, dropdown, or popover components that need to communicate z-axis position
+- Building an elevation system or design token scale for a component library
+- Choosing between shadow-based depth and tonal surface color for hierarchy
+- Implementing dark mode where traditional black shadows disappear against dark backgrounds
+- Evaluating whether a shadow is communicating interaction state (hover lift, press sink) or static hierarchy
+- Debugging visual clutter caused by too many competing shadow layers
+- Creating chromatic shadows that match a brand palette rather than defaulting to neutral gray
+- Any decision about which element should appear "above" or "below" another in visual stacking order
+
+## Instructions
+
+1. **Treat elevation as a semantic variable, not a decorative effect.** Every shadow in a system must answer the question: "Why is this element above that one?" Elevation encodes hierarchy — a dropdown menu floats above the page because it is temporary and demands immediate attention; a card sits slightly above the canvas because it is a discrete, interactive object. If you cannot articulate why an element is elevated, it should not have a shadow. Material Design 3 defines elevation levels 0 through 5, where each level corresponds to a semantic role: Level 0 is the canvas, Level 1 is cards and rails, Level 2 is buttons and chips, Level 3 is navigation bars, Level 4 is dialogs and menus, Level 5 is modals and FABs.
+
+2. **Understand the four parameters of box-shadow and what each communicates.** The CSS `box-shadow` property accepts `offset-x`, `offset-y`, `blur-radius`, `spread-radius`, and `color`. Each parameter carries visual meaning: offset defines light direction (consistent offset across all shadows implies a single global light source), blur defines altitude (higher elements cast softer, wider shadows), spread defines edge sharpness (negative spread creates inner glow, positive spread creates ambient fill), and color defines atmosphere (neutral gray shadows feel clinical, tinted shadows feel integrated). A shadow with `0 4px 6px -1px rgba(0,0,0,0.1)` communicates a light source directly above, moderate elevation, sharp contact edge, and neutral atmosphere.
+
+3. **Use multi-layer shadows for photorealistic depth.** Real-world objects cast at least two shadow types simultaneously: a sharp, dark contact shadow directly beneath the object (small offset, minimal blur, darker opacity) and a diffuse ambient shadow that spreads broadly (larger offset, more blur, lighter opacity). Single-layer shadows look flat and synthetic. Stripe uses a consistent two-layer pattern: `0 1px 3px rgba(50,50,93,0.15), 0 1px 0 rgba(0,0,0,0.02)` — the first layer is a soft ambient shadow with a blue-gray tint, the second is a razor-thin contact shadow. This dual-layer approach creates convincing depth from just two declarations.
+
+4. **Build an elevation scale as design tokens.** Define 4-6 elevation levels as named tokens, not ad-hoc values. Each level should increase blur by 1.5-2x and offset by 1.5x from the previous level. A concrete scale:
+   - `--shadow-xs`: `0 1px 2px 0 rgba(0,0,0,0.05)` — subtle lift, input fields, dividers
+   - `--shadow-sm`: `0 1px 3px 0 rgba(0,0,0,0.1), 0 1px 2px -1px rgba(0,0,0,0.1)` — cards, buttons
+   - `--shadow-md`: `0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)` — dropdowns, popovers
+   - `--shadow-lg`: `0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)` — dialogs, drawers
+   - `--shadow-xl`: `0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.1)` — modals, overlays
+   - `--shadow-2xl`: `0 25px 50px -12px rgba(0,0,0,0.25)` — maximum elevation, full-screen overlays
+     Tailwind CSS uses exactly this 6-step scale. Never invent shadow values outside your scale.
+
+5. **Maintain a consistent light source direction across the entire interface.** If your shadows cast downward (positive y-offset), every element in the system must cast downward. A top-bar with `0 2px 4px` and a bottom-bar with `0 -2px 4px` implies two light sources, which creates visual incoherence. Material Design specifies a single key light at top-center and an ambient fill light, producing shadows that always fall downward and slightly outward. The only exception: inset shadows (e.g., pressed buttons) which represent the inverse — a concavity rather than a protrusion.
+
+6. **Use chromatic shadows to create visual warmth and brand integration.** Traditional shadows use `rgba(0,0,0,opacity)`, which produces cold, detached depth. Chromatic shadows tint the shadow color to match the element or the brand palette. Stripe's signature shadow uses `rgba(50,50,93,0.25)` — a desaturated indigo that matches their brand blue. The formula: take your dominant brand hue, desaturate by 40-60%, darken by 20-30%, and use at 15-25% opacity. For colored cards or buttons, sample the background color of the element, darken it by 30-40%, and apply at 25-40% opacity. A red button with shadow `0 4px 14px rgba(220,38,38,0.35)` creates a colored glow that makes the button appear to emit light.
+
+7. **Handle dark mode shadows with surface tinting instead of shadow darkening.** On dark backgrounds, shadows become nearly invisible because there is no contrast between a dark shadow and a dark surface. Material Design 3 solves this by replacing shadow-based elevation with tonal surface color — higher-elevation surfaces receive a lighter tint of the primary color. At Level 0, the surface is the base dark color (`#1C1B1F`). At Level 1, a 5% primary color overlay is applied. At Level 2, 8%. At Level 3, 11%. At Level 5, 14%. This preserves hierarchy without relying on shadows that would disappear. If you must use shadows in dark mode, increase opacity to 40-60% (versus 10-15% in light mode) and add a 1px top border at 5-8% white opacity to simulate the rim light that gives real-world objects definition in low-light environments.
+
+8. **Use elevation transitions to communicate interaction state.** Interactive elements should change elevation on hover and press to create physical metaphor. On hover, a card rises: increase shadow from `--shadow-sm` to `--shadow-md` over 200ms with `ease-out`. On press, a button sinks: decrease shadow from `--shadow-sm` to `--shadow-xs` (or inset) over 100ms with `ease-in`. Material Design specifies: resting state = base elevation, hover = base + 2dp, pressed = base - 1dp, dragged = base + 8dp. The transition must be smooth — never snap between shadow levels. Animate `box-shadow` directly (acceptable performance in modern browsers) or use `filter: drop-shadow()` for GPU-accelerated transitions on elements with complex shapes.
+
+## Details
+
+### Shadow Anatomy Deep Dive
+
+**Offset (x, y).** The offset pair defines the shadow's displacement from the element. In UI design, x-offset is almost always 0 (light from directly above) and y-offset is positive (light casts downward). Non-zero x-offset implies a lateral light source, which can work for stylistic effects but breaks the physical metaphor when mixed with zero-offset shadows elsewhere. Material Design's key light produces y-offset proportional to elevation: 1dp elevation = 1px y-offset, 4dp = 4px, 8dp = 8px. This linear relationship is a simplification — real shadow offset follows trigonometry based on light angle — but it works perceptually.
+
+**Blur.** Blur radius controls shadow softness. A 0px blur creates a hard-edged shadow (like a cutout). Blur increases with elevation because higher objects are farther from the surface they cast onto. The mapping: blur = 2 _ y-offset for ambient shadows, blur = 0.5 _ y-offset for contact shadows. A card at 4px offset might have an ambient layer with 8px blur and a contact layer with 2px blur.
+
+**Spread.** Spread expands (positive) or contracts (negative) the shadow before blur is applied. Negative spread is the secret to realistic multi-layer shadows — it prevents the ambient shadow from creating a visible hard edge beyond the element boundary. Tailwind's `--shadow-md` uses `-1px` spread on its first layer and `-2px` on its second layer, pulling the shadow inward so it only appears as soft diffusion, not as a visible border.
+
+**Color and Opacity.** Shadow opacity should decrease as blur increases. Contact shadows (small blur) are 10-20% opacity. Ambient shadows (large blur) are 5-10% opacity. In total, no shadow stack should exceed 30% cumulative perceived darkness — beyond this, the shadow becomes a visual distraction rather than a depth cue. Stripe keeps total shadow opacity around 17-27%: `rgba(50,50,93,0.25)` plus `rgba(0,0,0,0.02)`.
+
+### Elevation Scale: Material Design 3 vs. Practice
+
+Material Design 3 defines elevation as a 0-5 scale mapped to dp values:
+
+| Level | dp  | Semantic Role               | Shadow + Tint (Light) | Tint Only (Dark)     |
+| ----- | --- | --------------------------- | --------------------- | -------------------- |
+| 0     | 0   | Canvas, background          | No shadow             | Base surface color   |
+| 1     | 1   | Cards, navigation rail      | Subtle shadow         | +5% primary overlay  |
+| 2     | 3   | Buttons, chips, text fields | Light shadow          | +8% primary overlay  |
+| 3     | 6   | Navigation bar, snackbar    | Medium shadow         | +11% primary overlay |
+| 4     | 8   | Menus, dialogs (temporary)  | Strong shadow         | +12% primary overlay |
+| 5     | 12  | Modal, FAB                  | Maximum shadow        | +14% primary overlay |
+
+In practice, most design systems collapse this to 3-4 meaningful levels: resting (cards), raised (hover/focus), floating (dropdowns/popovers), and overlay (modals/dialogs). The intermediate distinctions (Level 2 vs Level 3) are rarely perceptible to users and add token complexity without visual payoff.
+
+### Chromatic Shadow Recipes
+
+**Brand-tinted neutral shadow (Stripe-style):** Take your brand primary (e.g., `#635BFF` Stripe indigo). Desaturate to ~35% saturation, darken to ~30% lightness. Result: `rgb(50,50,93)`. Apply at 20-25% opacity. Pair with a near-black contact shadow at 2-5% opacity.
+
+**Element-colored glow shadow:** For colored UI elements (colored buttons, tags, cards), sample the element's background. Increase saturation by 10%, reduce lightness by 25%. Apply at 30-40% opacity with large blur (14-20px). Example: a button with `bg: #3B82F6` gets shadow `0 4px 14px rgba(37,99,235,0.35)`. This creates a "glowing" effect that makes the element appear self-luminous.
+
+**Warm ambient shadow:** For interfaces aiming for warmth (consumer apps, lifestyle brands), use `rgba(0,0,0,opacity)` only for the contact layer. Replace the ambient layer with a warm tint: `rgba(120,80,40,0.08)` — a desaturated brown-amber. This eliminates the clinical coldness of pure black shadows without being obviously colored.
+
+### Anti-Patterns
+
+1. **Shadow Soup.** Applying shadows to every element on the page — every card, every button, every divider, every section, every icon container. When everything is elevated, nothing is. Shadows work through contrast: an elevated element stands out because the elements around it are flat. If 15 cards on a page all have identical `--shadow-md`, the shadows communicate nothing about relative importance. Fix: use shadows only on interactive elements and temporary surfaces (dropdowns, modals). Let non-interactive content sit at Level 0.
+
+2. **Inconsistent Light Sources.** A card has shadow `0 4px 8px` (light from above) while a sidebar has shadow `4px 0 8px` (light from the left) and a footer has shadow `0 -4px 8px` (light from below). Three different light sources on one page create subconscious visual anxiety — the scene is physically impossible. Fix: audit all shadows in the system and normalize to a single light direction. Use a design token for shadow direction so it cannot drift.
+
+3. **Dark Mode Shadow Copy-Paste.** Using the same `rgba(0,0,0,0.1)` shadows in dark mode as in light mode. Against a `#1A1A1A` background, a 10% black shadow is invisible. The elevation hierarchy vanishes entirely. Fix: implement tonal surface color for dark mode (Material Design 3 approach) or increase dark mode shadow opacity to 40-60% and add a subtle top-edge rim highlight (`border-top: 1px solid rgba(255,255,255,0.06)`).
+
+4. **Elevation Inflation.** Starting with `--shadow-xl` for basic cards because "it looks more dramatic." This leaves no headroom for dropdowns, dialogs, and modals that genuinely need higher elevation. The result: modals that do not feel like they are above the page because cards already used the maximum shadow. Fix: start at the lowest elevation that creates perceptible depth (usually `--shadow-sm` for cards) and reserve higher levels for progressively more temporary, attention-demanding surfaces.
+
+5. **Animating Box-Shadow Without Compositor Fallback.** Transitioning `box-shadow` directly triggers paint on every frame, which causes jank on lower-powered devices. For high-performance shadow transitions, use a pseudo-element (`::after`) with the target shadow applied at full opacity, and animate only the pseudo-element's `opacity` — a compositor-only property. The element appears to transition between shadow states smoothly while only opacity is actually being interpolated.
+
+### Shadow Performance and Implementation
+
+**The pseudo-element opacity technique.** Animating `box-shadow` directly triggers paint on every frame. The performant alternative: create a `::after` pseudo-element with the target (hover/active) shadow applied at `opacity: 0`. On state change, animate only `opacity` to 1. The browser composites the opacity change on the GPU without repainting the shadow.
+
+```css
+.card {
+  position: relative;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12);
+}
+.card::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
+  opacity: 0;
+  transition: opacity 200ms ease-out;
+  pointer-events: none;
+}
+.card:hover::after {
+  opacity: 1;
+}
+```
+
+This technique is used by Tailwind UI and Radix Themes for their card hover effects. The shadow itself never animates — only its visibility changes, which is a compositor-only operation.
+
+**`filter: drop-shadow()` vs `box-shadow`.** `box-shadow` applies to the element's box model — it follows the rectangular boundary (plus border-radius). `filter: drop-shadow()` applies to the element's alpha channel — it follows the visual shape of the content, including transparent regions in PNGs and SVGs. For non-rectangular elements (icons, irregularly shaped images, clipped elements), `drop-shadow` produces correct shadows while `box-shadow` produces a rectangular shadow that ignores the element's visual shape. However, `drop-shadow` does not support `spread` or `inset` parameters, and it applies to the entire stacking context including children.
+
+**Shadow tokens in design systems.** When building tokens, encode both the shadow value and its semantic role. Tailwind's approach (`shadow-sm`, `shadow-md`) encodes only size. A more expressive system encodes intent: `--shadow-card-resting`, `--shadow-card-hover`, `--shadow-dropdown`, `--shadow-modal`, `--shadow-inset-pressed`. This prevents developers from choosing shadows by visual inspection ("this one looks about right") and instead choosing by semantic role ("this is a dropdown, so it uses the dropdown shadow"). Radix Themes uses semantic shadow tokens: `shadow-2` for cards, `shadow-3` for raised buttons, `shadow-4` for dropdowns, `shadow-5` for dialogs, `shadow-6` for popovers.
+
+### Elevation Decision Framework
+
+When deciding on elevation for a new component, run this procedure:
+
+1. **Is the element persistent or temporary?** Persistent elements (cards, sidebars, toolbars) use Level 1-2 shadows. Temporary elements (dropdowns, tooltips, modals) use Level 3-5 shadows. Temporary elements must be visually "above" persistent elements.
+2. **Does the element overlap other content?** If yes, it must have a shadow to explain the overlap. A dropdown that covers page content without a shadow looks like a rendering bug. Modals without shadows (or scrims) create visual confusion about what is interactive.
+3. **Is the element interactive?** Interactive elements benefit from elevation change on hover/press. Non-interactive elements (static cards, info panels) should not change elevation because elevation change implies clickability.
+4. **Is this dark mode?** If yes, favor tonal surface color over shadows. Reserve shadows for high-elevation temporary surfaces (modals, dialogs) where tonal difference alone is insufficient.
+5. **What is the highest elevation on this screen?** Ensure your new element does not exceed the modal/dialog level unless it is a modal/dialog. Elevation inflation makes true overlays less effective.
+
+### Real-World Examples
+
+**Stripe's Elevation Language.** Stripe uses a consistent two-layer chromatic shadow system across their entire dashboard and marketing pages. Their signature shadow — `0 13px 27px -5px rgba(50,50,93,0.25), 0 8px 16px -8px rgba(0,0,0,0.3)` — appears on elevated cards in their pricing page. The indigo tint (`rgba(50,50,93,...)`) ties the shadow to Stripe's brand palette. On hover, cards transition to a higher elevation with increased blur and offset over 250ms, creating a physical "lift" that signals interactivity. Their payment form inputs use the lowest elevation: `0 1px 3px rgba(50,50,93,0.15), 0 1px 0 rgba(0,0,0,0.02)` — barely-there depth that differentiates inputs from the background without competing with card-level elevation.
+
+**Material Design 3 Tonal Elevation.** MD3 broke from its own MD2 convention by making shadow optional in many contexts. In MD3's dark theme, a Level 2 surface is not "base color + shadow" but "base color + 8% primary color overlay." A surface with primary `#D0BCFF` at Level 2 in dark mode becomes `#1C1B1F` blended with 8% of `#D0BCFF`, producing `#2B2930`. This tonal approach creates a visible hierarchy even on OLED screens where true black (`#000000`) backgrounds make shadows impossible. The key insight: elevation can be communicated through lightness alone, without any shadow geometry.
+
+**Apple's Vibrancy and Layer Depth.** Apple's design system uses material layers — thin, ultra-thin, thick — that combine blur, opacity, and vibrancy to communicate depth. A notification popup on macOS uses `NSVisualEffectView` with a material that blurs the background content underneath, creating depth through occlusion rather than shadow. The shadow is present but secondary: `0 22px 70px 4px rgba(0,0,0,0.56)` — a very large, dark shadow that exists primarily to darken the content beneath the overlay, not to create an edge effect. Apple pairs this with a 1px separator stroke at 12% white opacity that defines the modal's edge sharply against the blurred background.
+
+**Vercel's Minimal Shadow System.** Vercel uses shadows sparingly, relying primarily on border and background color to communicate hierarchy. Their card component uses `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)` — technically a shadow but functioning as a border (zero offset, zero blur, 1px spread). On hover, this transitions to `0 0 0 1px rgba(0,0,0,0.12), 0 4px 8px rgba(0,0,0,0.04)` — the border darkens slightly and a subtle ambient shadow appears. The total maximum opacity is 16%, making their shadows among the lightest in production design systems. This restraint works because Vercel's interface is primarily flat with strong contrast from black text on white backgrounds — shadows are supplementary rather than structural.
+
+## Source
+
+- Material Design 3 — Elevation documentation, https://m3.material.io/styles/elevation
+- CSS Specification — `box-shadow` property, https://www.w3.org/TR/css-backgrounds-3/#box-shadow
+- Stripe — Dashboard and marketing page shadow inspection (DevTools analysis)
+- Tailwind CSS — Shadow scale documentation, https://tailwindcss.com/docs/box-shadow
+- Apple Human Interface Guidelines — Materials and vibrancy
+- Tobias Ahlin — "Smoother & sharper shadows with layered box-shadows" (blog post on multi-layer technique)
+- Josh Comeau — "Designing Beautiful Shadows" (blog post on shadow design methodology)
+- Material Design 2 to 3 migration — Elevation changes and tonal surface color adoption
+
+## 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-elevation-shadow/skill.yaml

@@ -0,0 +1,34 @@
+name: design-elevation-shadow
+version: "1.0.0"
+description: Depth as information — shadow anatomy (offset, blur, spread, color), elevation scale, chromatic shadows, material metaphor, dark mode shadows
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-gestalt-figure-ground
+  - design-dark-mode-color
+stack_signals: []
+keywords:
+  - elevation
+  - shadow
+  - depth
+  - box-shadow
+  - chromatic-shadow
+  - material
+  - z-axis
+  - dark-mode-shadow
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-empty-error-states/SKILL.md

@@ -0,0 +1,154 @@
+# Empty and Error State Design
+
+> Empty and error state design — empty states as onboarding, error states as recovery, 404 pages, zero-data states, degraded states, constructive error messages
+
+## When to Use
+
+- Designing any view that fetches data from an API, database, or external service — every such view has at least one empty state and one error state
+- Building onboarding flows where the user's first experience is an empty dashboard, empty list, or empty workspace
+- Creating search or filter interfaces that may return zero results
+- Designing 404 pages, permission-denied screens, or other system-level error pages
+- Building applications that must function gracefully under degraded conditions (slow network, partial API failure, expired sessions)
+- Auditing an existing product where empty and error states were never designed — they default to blank screens or raw error strings
+- Implementing offline-capable applications where network loss must not destroy the user experience
+- Any time the "happy path" design is complete and the team is ready to address the other 80% of real-world user encounters
+
+## Instructions
+
+1. **Treat empty states as the first impression, not an afterthought.** For every new user, the empty state is the first screen they see. An empty dashboard is not a missing feature — it is the onboarding experience. The empty state must answer three questions: What is this page for? Why is there nothing here? What should I do next? GitHub's empty repository page answers all three: "This is your repository" (purpose), "You just created it" (why empty), and "Run these commands to push your first code" (what to do). If your empty state is a blank white page with the text "No items," you have failed at onboarding.
+
+2. **Distinguish the three types of empty states.** Not all empty states are the same, and conflating them creates confusion:
+
+   | Type               | Trigger                           | User Expectation              | Correct Response                                           |
+   | ------------------ | --------------------------------- | ----------------------------- | ---------------------------------------------------------- |
+   | First-use empty    | New account, no data created yet  | "Show me what to do"          | Onboarding illustration + primary CTA + example content    |
+   | User-cleared empty | User deleted all items            | "Confirm this is intentional" | Confirmation + re-creation CTA + undo option               |
+   | No-results empty   | Search or filter returned nothing | "Help me find what I want"    | Search suggestions + broaden-filter prompt + popular items |
+
+   Airbnb handles no-results masterfully: when a search returns zero listings, the page shows "No exact matches" followed by flexible date suggestions, nearby location alternatives, and a prompt to adjust filters — turning a dead end into a discovery tool.
+
+3. **Design error states for recovery, not blame.** Every error state must include: (a) what happened in plain language, (b) why it might have happened, (c) at least one concrete action the user can take. "Something went wrong" is useless. "We couldn't save your changes because the connection was lost. Your draft is saved locally. Try again when you're back online." tells the user what happened, why, and what to do. Stripe's payment error messages are the benchmark: "Your card was declined. Try a different payment method or contact your bank" gives the user two clear recovery paths.
+
+4. **Use the error severity and scope matrix to choose the right treatment.**
+
+   | Scope           | Low Severity (recoverable)                            | High Severity (terminal)                                |
+   | --------------- | ----------------------------------------------------- | ------------------------------------------------------- |
+   | Field-level     | Inline error below field, red border, suggestion text | Field disabled + explanation of why                     |
+   | Component-level | Error message within component + retry button         | Component replaced with error card + alternative action |
+   | Page-level      | Toast or banner at top + auto-retry in background     | Full-page error with illustration + recovery options    |
+   | System-level    | Status bar indicator + cached data visible            | Maintenance page with expected resolution time          |
+
+   The key principle: error scope should match the failure scope. A single failed API call should not produce a full-page error if the rest of the page content loaded successfully. GitHub demonstrates this — if the README fails to render in a repository, only the README section shows an error; the file tree, branch selector, and metadata remain fully functional.
+
+5. **Design 404 pages as brand moments, not dead ends.** A 404 page is one of the most-visited error pages on any site. It is also an opportunity to express brand personality while helping the user recover. Every 404 must include: a clear statement that the page was not found, a search bar or navigation to help the user find what they wanted, links to popular or recent content, and a way to report the broken link. GitHub's 404 page with the Octocat in a parallax star field is iconic — it is memorable, on-brand, and includes a search bar and link to the homepage. A 404 that simply says "Not Found" in the browser's default font is a missed opportunity and a UX failure.
+
+6. **Design degraded states for partial system failure.** Real applications rarely fail completely — they degrade. One microservice goes down while others remain healthy. The user's connection is slow but not gone. The CDN serves stale content. Degraded states require three design decisions: What cached or stale data can be shown? What functionality is reduced? How is the degradation communicated? Slack handles degraded state exceptionally: when the WebSocket connection drops, the app shows all cached messages with a yellow banner ("Connecting..."), queues new messages for sending when the connection returns, and timestamps stale data so users know it may not reflect the latest state.
+
+7. **Make empty states educational.** The best empty states teach the user something about the product. Notion's empty page shows "Press '/' for commands" — simultaneously an empty state and a tutorial. Slack's empty channel says "This is the very beginning of the #channel-name channel" followed by the channel's purpose and a prompt to send the first message. Figma's empty canvas shows keyboard shortcuts for creating shapes. The empty state is free real estate for reducing the learning curve.
+
+8. **Provide constructive error messages with specific remediation.** Vague errors cause support tickets. Specific errors enable self-service recovery. Compare:
+
+   | Vague (causes support ticket) | Constructive (enables recovery)                                                                              |
+   | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
+   | "Upload failed"               | "Upload failed: file exceeds 10MB limit. Compress your image or choose a smaller file."                      |
+   | "Permission denied"           | "You don't have access to this project. Ask @jordan (project owner) to invite you."                          |
+   | "Invalid input"               | "Email must include an @ symbol. Example: name@company.com"                                                  |
+   | "Server error"                | "We're experiencing issues. Your work is saved locally. We'll auto-save to the server when things are back." |
+
+## Details
+
+### Empty State Anatomy
+
+A well-designed empty state contains up to five elements, layered by importance:
+
+**Illustration or icon** (optional but powerful). A custom illustration communicates brand personality and softens the experience. Dropbox uses unique illustrations for every empty folder state — each one reinforces the brand while making the empty state feel intentional rather than broken. The illustration should be relevant to the content type: an empty inbox shows a mailbox, an empty project list shows a rocket, an empty search shows a magnifying glass. Avoid generic clip art — if the illustration could appear on any product, it is not adding value.
+
+**Headline** (required). A short, human sentence that names the state. "No notifications yet" is better than "Empty" or "0 items." The headline should be specific to the content: "No projects yet" not "Nothing here."
+
+**Description** (required). One to two sentences explaining why this state exists and what the user can do about it. For first-use empty: "Create your first project to start collaborating with your team." For no-results: "Try broadening your search or removing some filters."
+
+**Primary action** (required for first-use). A single, prominent button that advances the user to the next step. "Create project," "Import data," "Invite teammates." This button should be the most visually prominent element after the illustration. For no-results empty, the primary action might be "Clear filters" or "Search for something else."
+
+**Secondary guidance** (optional). Links to documentation, example templates, or video tutorials. GitHub's empty repository page includes secondary links to GitHub's getting-started guides. This layer serves users who are not ready for the primary action but want to learn more.
+
+### Error Recovery Patterns
+
+**Inline retry.** For transient failures (network timeout, rate limit), show a retry button within the failed component. The retry should use exponential backoff (1s, 2s, 4s) and show attempt count after the first retry: "Retrying... (attempt 2 of 3)." After max retries, switch to a manual retry with explanation: "We tried 3 times. Check your connection and try again."
+
+**Optimistic rollback.** When an optimistic update fails (the UI showed success before the server confirmed), the rollback must be visible and non-destructive. Do not silently remove the optimistic content — mark it with an error indicator and a retry button. Slack does this: a message that fails to send stays in the chat with a red warning icon and "Not delivered — Click to retry." The user's content is never lost.
+
+**Graceful degradation chain.** When a primary data source fails, fall through alternatives: live data (primary) to cached data with staleness indicator (secondary) to static fallback content (tertiary) to error state with recovery action (last resort). A weather app that loses its API connection should show yesterday's forecast with "Last updated 18 hours ago," not a blank screen.
+
+**Session recovery.** When an authenticated session expires mid-task, do not redirect to login and lose the user's work. Show an inline authentication prompt ("Your session expired. Enter your password to continue.") that preserves the current page state. After re-authentication, the user should be exactly where they were, with all form data and scroll position intact. Linear handles this well — an expired session shows a modal login overlay without navigating away from the current view.
+
+### Zero-Data Design
+
+Zero-data states deserve special attention because they represent the user's very first moment with your product. Principles for zero-data design:
+
+**Show example content, not empty containers.** A project management tool should show a sample project with realistic tasks, not empty columns. Trello's onboarding creates a "Welcome Board" with pre-populated cards that teach the interaction model. The example content serves dual purpose: it demonstrates the product's value and teaches the UI patterns.
+
+**Use progressive disclosure.** Do not show every empty section simultaneously. A new dashboard with six empty widgets is overwhelming. Show one section with a CTA, and reveal additional sections as the user creates content. Notion's approach: a new workspace has one empty page with a friendly prompt — not a grid of empty databases, boards, and calendars.
+
+**Communicate time investment.** If setting up the first item takes significant effort, tell the user: "Creating your first project takes about 5 minutes." This sets expectations and reduces abandonment. Vercel's onboarding tells you "Import a project in 30 seconds" — framing the empty state as a quick action rather than a daunting task.
+
+### 404 and System Error Pages
+
+The best 404 pages share these characteristics:
+
+**Brand consistency.** The 404 page should look like it belongs to the same product, with the same navigation, color palette, and typography. A user who encounters a 404 should never wonder if they accidentally left the site.
+
+**Helpful navigation.** Include the site's main navigation, a search bar, and links to popular content. The user arrived at this page for a reason — help them find what they were looking for. If you can infer intent from the URL (e.g., `/blog/old-post-title`), suggest similar content.
+
+**Personality without frustration.** Humor is appropriate on a 404 page only if it does not obscure the recovery path. GitHub's Octocat illustration is charming without making the user feel mocked. Avoid jokes that belittle the user ("Oops, you broke the internet!") — the user did nothing wrong.
+
+**Tracking and alerting.** Every 404 hit should be logged with the referrer URL. If a specific 404 spikes in traffic, it means a link changed or broke — the error page should be a signal to fix the source, not just a destination for lost users.
+
+### Anti-Patterns
+
+1. **The Blank Abyss.** A data-dependent view that renders as a completely blank page when no data exists — no heading, no explanation, no action. The user cannot tell if the page is loading, broken, or intentionally empty. This is the most common empty state anti-pattern and the easiest to fix: every view that can have zero data items must have an explicit empty state with at least a headline and a CTA.
+
+2. **The Blame-Shifting Error.** Error messages that imply the user did something wrong when the system failed. "You entered an invalid request" for a server error. "Please try again later" with no explanation of what went wrong. Error messages must be honest about fault: if the server failed, say "We're having trouble" not "Your request was invalid." Users are more forgiving of system failures than of being blamed for them.
+
+3. **The Generic Catch-All.** Using one error message for every failure type: "Something went wrong. Please try again." This message provides zero diagnostic information, generates support tickets, and trains users to distrust your error messages because they are never specific enough to act on. Map each error code to a specific, actionable message. A 401 is not the same as a 500 is not the same as a timeout — do not display them identically.
+
+4. **The Disappeared Content.** When an optimistic action fails, the UI silently removes the content the user just created. A message that "sent" then vanishes. A to-do that was "added" then disappears on refresh. Failed optimistic updates must be visible — show the failed item with an error state and a retry action, never silently delete it.
+
+5. **The Crying Mascot.** An error page dominated by a large sad-face illustration or crying mascot character with a tiny, barely visible recovery link. The illustration-to-action ratio is inverted: 80% decoration, 20% utility. Error pages should prioritize the recovery path. The illustration is supporting material, not the main content.
+
+### Real-World Examples
+
+**GitHub's Empty Repository State.** When a user creates a new repository with no README, GitHub's empty state is a masterclass in onboarding design. The page shows the repository URL with copy buttons (HTTPS and SSH), then presents three complete code blocks: "create a new repository on the command line," "push an existing repository," and "import code from another repository." Each option is a complete, copy-pasteable workflow. The empty state eliminates the gap between "I created a repository" and "I have code in my repository" by providing every possible path forward, verbatim.
+
+**GitHub's 404 Octocat Page.** GitHub's 404 features the Octocat floating through space with a parallax starfield that responds to mouse movement. It is visually memorable and immediately recognizable as a GitHub page. Below the illustration: "This is not the web page you are looking for" with a link to the homepage and a search form. The page reinforces brand identity while providing every recovery path a lost user needs.
+
+**Slack's Empty Channel State.** When a user opens a newly created channel, Slack shows: the channel name with a decorative header, "This is the very beginning of the #channel-name channel," the channel purpose (if set during creation), the date the channel was created, and a prompt to write the first message. For direct message conversations, the empty state shows the other person's profile info, title, and timezone — contextual information that makes the empty state useful even before any messages are sent.
+
+**Airbnb's No-Results Search.** When a search returns zero listings, Airbnb shows "No exact matches" as a headline, then provides three recovery paths: "Try changing your dates" (with suggested flexible date ranges), "Remove some filters" (with a list of active filters, each with a remove button), and "Explore nearby destinations" (with a grid of alternative locations with photos and prices). The no-results state is more interactive than many product pages — it aggressively guides the user toward a successful search rather than abandoning them at a dead end.
+
+**Dropbox's Empty Folder Illustration.** Each empty folder in Dropbox shows a unique brand illustration relevant to the folder context. A shared folder shows people collaborating. A new personal folder shows an open box. The "Starred" view when empty shows a telescope with "Nothing starred yet — star files and folders so they're easy to find." Each illustration is on-brand, each message is specific to the empty state type, and each includes a clear next action.
+
+**Apple's Error Recovery Patterns.** iOS handles system-level errors with a consistent pattern: a simple icon, a brief explanation, and one or two actions. When an app cannot connect to the App Store: "Cannot Connect to App Store" with a "Retry" button. When cellular data is disabled for an app: "Cellular Data Is Turned Off" with a direct link to Settings. The error messages are never technical ("Error -1009") and always include the most direct path to resolution.
+
+## Source
+
+- Norman, D. — _The Design of Everyday Things_ (2013), feedback and error recovery
+- Krug, S. — _Don't Make Me Think_ (2014), first-time user experience
+- Yablonski, J. — _Laws of UX_ (2020), aesthetic-usability effect on empty states
+- Material Design — Empty states guidelines, https://m3.material.io/foundations/content/empty-states
+- Nielsen Norman Group — "The Power of Empty States" (2019)
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/design-empty-error-states/skill.yaml

@@ -0,0 +1,35 @@
+name: design-empty-error-states
+version: "1.0.0"
+description: Empty and error state design — empty states as onboarding, error states as recovery, 404 pages, zero-data states, degraded states, constructive error messages
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-state-design
+  - design-loading-patterns
+  - design-feedback-patterns
+stack_signals: []
+keywords:
+  - empty-state
+  - error-state
+  - "404"
+  - zero-data
+  - degraded-state
+  - onboarding
+  - error-recovery
+  - constructive-error
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-feedback-patterns/SKILL.md

@@ -0,0 +1,156 @@
+# Feedback Patterns
+
+> System response design — immediate vs delayed feedback, optimistic updates, progress indicators, confirmation patterns, undo vs confirm, toast/snackbar/banner
+
+## When to Use
+
+- Designing user action responses — what the system communicates after a click, submit, or gesture
+- Choosing between optimistic and pessimistic update strategies for data mutations
+- Implementing notification and messaging patterns (toast, snackbar, banner, inline, modal)
+- Deciding between destructive action confirmation (undo vs confirm dialog)
+- Building progress indicators for multi-step or long-running operations
+- Auditing an interface for feedback gaps — actions that produce no visible system response
+- Designing error recovery flows that guide users back to a working state
+- Evaluating feedback timing — is the response too fast (missed), too slow (frustrating), or poorly timed (interruptive)?
+
+## Instructions
+
+1. **Every user action must produce visible feedback within 100ms.** This is Jakob Nielsen's foundational threshold: actions with feedback under 100ms feel instantaneous. Between 100ms and 1 second, the user notices a delay but maintains flow. Over 1 second, the user's attention breaks and they need a progress indicator. Over 10 seconds, they need percentage completion or a time estimate. No action should ever produce zero feedback — a silent button click is a broken interface. Even if the backend operation takes seconds, acknowledge the click immediately with a visual state change (button press, spinner start, text update).
+
+2. **Choose optimistic or pessimistic updates based on operation reversibility and failure rate.** The decision matrix:
+
+   | Condition                            | Strategy      | Example                                  |
+   | ------------------------------------ | ------------- | ---------------------------------------- |
+   | Reversible + low failure rate (<5%)  | Optimistic    | Slack message send, GitHub star          |
+   | Reversible + high failure rate (>5%) | Pessimistic   | File upload (network-dependent)          |
+   | Irreversible + any failure rate      | Pessimistic   | Payment processing, account deletion     |
+   | Irreversible + critical impact       | Confirm first | Stripe charge, data export, user removal |
+
+   Optimistic updates show the success state immediately and roll back on failure. Slack displays your message in the channel instantly — if the server rejects it, the message shows a red warning icon with "Not delivered. Click to retry." The rollback is visible, actionable, and non-destructive. GitHub's star is optimistic: the star fills and the count increments on click, before the server confirms. If the server fails, the star unfills and the count reverts.
+
+3. **Use the toast/snackbar/banner taxonomy correctly.** These three feedback containers serve different purposes and should not be used interchangeably:
+   - **Toast (ephemeral, non-blocking, auto-dismissing).** For confirmations of low-stakes completed actions: "Settings saved," "Link copied." Auto-dismiss after 4-6 seconds. Position: top-right or bottom-center. No required action. Material Design snackbar spec: 4 seconds for single-line, 10 seconds for two-line. Never use toasts for errors — errors need to persist until addressed.
+   - **Snackbar (ephemeral with action, non-blocking).** For completed actions that offer an undo opportunity: "Conversation archived. Undo." Auto-dismiss after 6-10 seconds. Must include one action (typically "Undo" or "View"). Gmail's snackbar after archiving is the canonical example: "Conversation archived" with an "Undo" link that persists for approximately 8 seconds.
+   - **Banner (persistent, page-level, blocking or non-blocking).** For system-wide status that affects the user's session: offline state, pending migration, subscription expiring, maintenance window. Does not auto-dismiss — requires user action (dismiss, acknowledge, or resolve). Slack's yellow offline banner and GitHub's blue deployment notice bar are banners. Position: top of viewport, full width.
+
+4. **Implement undo instead of confirmation for reversible destructive actions.** Confirmation dialogs ("Are you sure?") are failure patterns — users click "Yes" reflexively without reading. Research by Aza Raskin (Mozilla) showed that confirmation dialogs prevent less than 5% of unintended destructive actions because users develop muscle memory for the confirm button. Undo is superior: let the action happen immediately, show a snackbar with an undo option, and give the user 6-10 seconds to reverse it. Gmail pioneered this with "Undo Send" (originally a 5-second window, now configurable to 30 seconds). The action feels fast (no dialog interruption) and the safety net is always visible.
+
+5. **Reserve confirmation dialogs for truly irreversible, high-consequence actions.** The threshold: if the action cannot be undone AND the consequences are significant (data loss, financial transaction, permanent account change), use a confirmation dialog. Stripe uses a confirmation dialog for refunds — the dialog names the specific amount and customer, requires explicit confirmation, and cannot be undone. GitHub uses a typed-confirmation pattern for repository deletion: you must type the repository name to confirm, preventing both accidental clicks and confirmation-dialog muscle memory.
+
+6. **Design progress indicators based on operation characteristics.** The decision procedure:
+   - **Determinate operations** (known total, known progress): use a progress bar with percentage. File uploads, multi-step wizards, bulk operations. Show the actual percentage, estimated time remaining, and current step. Vercel's build progress shows: step name ("Installing dependencies"), elapsed time, and a progress bar.
+   - **Indeterminate operations** (unknown duration): use a spinner or indeterminate progress bar. API calls, search operations, server-side processing. Do NOT show a fake progress bar that fills linearly then stalls at 90% — users will notice and trust is destroyed. Use an honest spinner or a pulsing bar.
+   - **Long operations (>10 seconds):** add a descriptive status message that updates as the operation progresses. Vercel's deployment flow: "Analyzing source" then "Building" then "Deploying to edge" then "Assigning domain" — each step update reassures the user that progress is happening.
+
+7. **Stack feedback by urgency with a clear visual hierarchy.** When multiple feedback messages compete for attention, use a priority system:
+   - **Critical (errors requiring action):** Inline at the source of the error, red, persistent, with recovery action. Highest priority — displayed immediately, displaces other feedback.
+   - **Warning (potential issues):** Banner or inline, amber/yellow, persistent until dismissed or resolved.
+   - **Success (action completed):** Toast or snackbar, green, auto-dismissing. Medium priority — queued behind active errors.
+   - **Informational (status update):** Toast or subtle inline update, neutral color, auto-dismissing. Lowest priority — suppressed if higher-priority feedback is active.
+
+   Never show a success toast while an error banner is active — the mixed signals confuse users about system state.
+
+8. **Place feedback at the point of action whenever possible.** Inline feedback (next to the button that was clicked, below the field that has an error) is always more effective than remote feedback (a toast in the corner, a banner at the top of the page). The user's attention is already at the point of action — inline feedback requires zero eye movement. Stripe's form validation is entirely inline: error messages appear directly below the offending field, the field border turns red, and the error text describes exactly what is wrong ("Your card number is incomplete"). No toast, no banner, no modal — the feedback is exactly where the user is looking.
+
+## Details
+
+### Optimistic Update Architecture
+
+Optimistic updates require three components working together:
+
+**Immediate state mutation.** On user action, update the local UI state before the server responds. This means the UI must have a local state layer (React state, Zustand, Vuex, etc.) that can be modified independently of server state. When the user clicks "like," set `isLiked = true` and `likeCount += 1` in local state immediately.
+
+**Background server request.** Simultaneously, send the mutation to the server. The request runs in the background while the user sees the success state.
+
+**Rollback on failure.** If the server returns an error, revert the local state to its pre-mutation value AND show the user what happened. This is where most implementations fail — they revert silently, and the user does not understand why their action "undid itself." The correct pattern: revert the state, show a toast/inline error explaining the failure ("Could not save. Check your connection."), and offer a retry action. Slack implements this precisely: if a message send fails, the message stays visible but gets a red warning icon and "Not delivered — Click to retry."
+
+**Conflict resolution.** When the server returns success but with modified data (e.g., the server sanitized the input), the local state must reconcile. Pattern: on server success response, overwrite local state with server state. This handles cases where the server modifies timestamps, normalizes text, assigns IDs, or applies business logic that changes the data from what the client optimistically displayed.
+
+### Toast Positioning and Stacking
+
+Toast positioning affects discoverability and readability. The conventions by platform:
+
+- **Material Design:** Bottom-center, stacked upward if multiple. Max 1 visible at a time — new toasts replace existing ones.
+- **Apple HIG:** Top-center (iOS notifications), brief, single-line.
+- **Web convention:** Top-right (most common in web apps — Vercel, Linear, Stripe dashboard) or bottom-left (Gmail). Stack downward (top-right) or upward (bottom-left).
+
+**Stacking rules.** Never show more than 3 toasts simultaneously — beyond 3, users stop reading them. When a new toast arrives while 3 are visible, dismiss the oldest. Group identical toasts: if 5 "Item saved" toasts fire in rapid succession, show one toast with a count: "5 items saved." Vercel groups deployment status updates into a single notification that updates its content rather than spawning new toasts.
+
+### The Undo Window
+
+The undo window duration directly impacts user behavior:
+
+- **3-5 seconds:** Sufficient for "I immediately regretted that" reversals. Too short for the user to read the undo message, process it, and decide. Appropriate for trivial actions (marking as read, dismissing a notification).
+- **6-10 seconds:** The optimal range for most destructive actions. Long enough to read, decide, and act. Gmail uses 5-30 seconds (configurable). Slack uses approximately 10 seconds for message deletion undo.
+- **10-30 seconds:** For high-consequence actions where the user might need to verify before committing. Email recall (Gmail's "Undo Send" at 30 seconds), bulk operations, export jobs.
+
+During the undo window, the server-side action should be deferred (not executed until the window expires) or logged for rollback. Gmail's "Undo Send" actually delays sending the email — it does not recall an already-sent email. This is important: the undo must be reliable, which means deferring is safer than rolling back.
+
+### Feedback Timing Precision
+
+The psychological breakpoints for feedback timing, validated across decades of HCI research:
+
+- **0-100ms:** Perceived as instantaneous. The user feels direct control, as if manipulating a physical object. This is the target for all local state changes: toggling, selecting, typing.
+- **100-300ms:** Perceived as "fast but noticeable." The user notices a slight delay but flow is not broken. Appropriate for client-server round trips on fast connections. Show a micro-interaction (button press state) to bridge this gap.
+- **300ms-1s:** Perceived as a deliberate system action. The user knows the system is working. A spinner or progress indicator should appear at the 300ms mark — not before (premature spinners for fast operations create flicker) and not after (delayed spinners create anxiety).
+- **1-5s:** The user's attention wanders. Progress indicators are mandatory. Add a status message explaining what is happening. Vercel shows "Analyzing source code..." during this window.
+- **5-10s:** The user considers abandoning the task. Provide: progress percentage, estimated time remaining, and a cancel option. Long build processes should show streaming log output — watching text scroll reassures the user that the system is working.
+- **>10s:** The user will switch context. Send a notification when complete (email, browser notification, in-app badge). Allow the user to navigate away without losing progress.
+
+### Anti-Patterns
+
+1. **The Silent Click.** A button that performs an action but provides no visual feedback — no state change, no toast, no animation. The user clicks, nothing happens, they click again (potentially duplicating the action), and eventually something changes with no connection to their click. Fix: every clickable element must change its visual state on click within one frame (16ms). Even if the backend response takes seconds, acknowledge the click with a press state, spinner, or "Saving..." text.
+
+2. **Success Theater.** Showing a celebratory success state (checkmark animation, confetti, "All done!") before the backend has confirmed success. If the server then rejects the action, the user experienced a lie. Fix: if using optimistic updates, keep the success feedback proportional (subtle confirmation, not celebration) so that a rollback is not jarring. Reserve celebratory feedback for confirmed successes only.
+
+3. **The Error Novel.** Displaying error messages that are paragraphs long, filled with technical details, and buried in a modal dialog that blocks all other interaction. Users do not read long error messages — they click "OK" to dismiss them. Fix: error messages should be one sentence maximum, written in the user's language, with a single clear action. Put technical details behind a "Show details" toggle for debugging purposes.
+
+4. **Confirmation Dialog Addiction.** Using "Are you sure?" dialogs for every action: delete, archive, save, cancel, navigate away. Confirmation fatigue sets in after 2-3 dialogs and users click "Confirm" reflexively, defeating the purpose entirely. Fix: use undo for reversible actions, reserve confirmation for truly irreversible high-consequence actions (payment, permanent deletion, account changes), and never confirm non-destructive actions.
+
+5. **Feedback Channel Mismatch.** Showing a success toast at the top-right corner of the screen while the user's attention is on a form at the bottom-left. The feedback fires but the user never sees it because it is outside their attentional focus. Fix: place feedback at the point of action. If you must use a remote notification (toast/banner), also provide inline feedback at the action source — a subtle checkmark next to the button, a field border color change, or an inline success message.
+
+### Real-World Examples
+
+**Slack Optimistic Messaging.** When you send a message in Slack, it appears in the channel immediately with full formatting. The only hint that it has not been confirmed by the server is a subtle clock icon where the timestamp will appear. On server confirmation (typically under 200ms), the clock icon is replaced by the actual timestamp — most users never see the clock. On failure, the message stays visible but shows a red warning icon with "Not delivered — Click to retry." The message text is preserved, so the user does not need to retype anything. This is the gold standard for optimistic updates.
+
+**Vercel Deployment Progressive Feedback.** A Vercel deployment provides feedback at every stage: (1) "Queued" with a gray status (immediate acknowledgment), (2) "Building" with a yellow animated dot and streaming build log, (3) "Deploying" with a blue animated dot, (4) "Ready" with a green checkmark, preview URL, and deployment summary. Each stage transition includes the elapsed time. If a build fails, the error state shows the exact line of the build log where the failure occurred, with syntax highlighting. The feedback is progressive, informative, and actionable at every stage.
+
+**Stripe Payment Confirmation.** After a successful payment, Stripe shows: (1) an animated checkmark draw (300ms), (2) a confirmation message ("Payment successful"), (3) a receipt summary (amount, last 4 digits, date), and (4) clear next steps ("Return to [merchant]" button). On failure, Stripe shows: (1) the specific field with the error (card number, expiry, CVC), (2) a human-readable error message ("Your card was declined. Try a different payment method."), and (3) the form pre-filled with valid fields so the user only needs to fix the problem field. The feedback addresses both success and failure with equal design attention.
+
+**GitHub Typed Confirmation.** For repository deletion, GitHub requires the user to type the full repository name (e.g., "cwarner/my-project") into an input field before the "Delete this repository" button becomes enabled. This pattern prevents both accidental clicks and confirmation-dialog muscle memory — you cannot type a repository name reflexively. The input includes real-time validation: the button remains disabled until the typed text exactly matches the repository name. This is appropriate for irreversible, high-consequence actions.
+
+**Linear Optimistic Status Updates.** Changing an issue's status in Linear (e.g., "In Progress" to "Done") updates immediately in the local UI — the status icon changes, the issue moves to the correct column in board view, and any filter/sort recalculates. The server sync happens asynchronously. If the server rejects the change (rare), the issue reverts with a subtle error toast. Because Linear is a single-player tool in practice (your own issue statuses), the failure rate is extremely low, making optimistic updates the correct strategy.
+
+### Feedback Audit Checklist
+
+For any interactive element, verify these feedback requirements:
+
+1. **Click/tap acknowledgment under 100ms.** Does the element visually change state within one animation frame of being clicked? A button should show its press state, a toggle should begin its animation, a link should change color. If you click and nothing happens for 200ms, the feedback is broken.
+2. **Operation progress for actions >1 second.** If the operation takes more than 1 second, is there a progress indicator? A spinner, a skeleton, a progress bar, or at minimum a "Loading..." text. Silent waits over 1 second feel like broken pages.
+3. **Success confirmation that names the action.** After a successful operation, does the feedback name what happened? "Saved" is acceptable. "Settings updated successfully" is better. No feedback at all after a successful save is a critical gap.
+4. **Error feedback that is actionable.** When an error occurs, does the message tell the user what to do? "Error" is useless. "Could not save. Try again." is minimal. "Your card number is incomplete — enter all 16 digits." is correct.
+5. **No competing feedback channels.** Is the system showing a success toast while an error banner is active? Are two different feedback mechanisms (toast + inline) saying different things? Conflicting feedback is worse than no feedback.
+
+## Source
+
+- Nielsen, J. — "Response Times: The 3 Important Limits" (1993), feedback timing thresholds
+- Raskin, A. — "Undoing the Undo" (2010), research on confirmation dialog ineffectiveness
+- Material Design — Communication patterns, https://m3.material.io/foundations/interaction/states
+- Gmail — Undo Send implementation and timing research
+- Slack Engineering — "Real-Time Messaging Architecture" (2017), optimistic update patterns
+
+## 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.