@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/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/claude-code/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.

package/dist/agents/skills/claude-code/design-feedback-patterns/skill.yaml

@@ -0,0 +1,35 @@
+name: design-feedback-patterns
+version: "1.0.0"
+description: System response design — immediate vs delayed feedback, optimistic updates, progress indicators, confirmation patterns, undo vs confirm, toast/snackbar/banner
+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-micro-interactions
+  - design-affordances
+stack_signals: []
+keywords:
+  - feedback
+  - optimistic-updates
+  - progress-indicators
+  - confirmation
+  - undo
+  - toast
+  - snackbar
+  - banner
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-fluent-design/SKILL.md

@@ -0,0 +1,241 @@
+# Fluent Design System (Fluent 2)
+
+> Microsoft's cross-platform design system covering the five foundational elements (light, depth, motion, material, scale), Acrylic and Mica materials, reveal highlight interactions, connected animations, responsive container strategies, and the Fluent 2 token theming architecture.
+
+## When to Use
+
+- Building Windows apps (WinUI 3, WPF with Fluent theme) where Acrylic, Mica, and reveal highlight are platform expectations
+- Developing Microsoft 365 integrations (Teams tabs, Outlook add-ins, SharePoint web parts) that must match Fluent 2 visual language
+- Implementing a React-based UI using `@fluentui/react-components` (Fluent UI React v9) with Griffel CSS-in-JS and token theming
+- Creating responsive layouts for apps that span desktop (1920px), tablet (1024px), and compact (320px) using Fluent's breakpoint and container strategy
+- Migrating from Fluent 1 (Fabric) to Fluent 2 where the token system, component API, and material model have fundamentally changed
+
+## Instructions
+
+Fluent Design is organized around five foundational elements: **Light** (illumination that reveals interactive surfaces), **Depth** (layering that establishes hierarchy), **Motion** (animation that connects user actions to outcomes), **Material** (translucent surfaces that establish context), and **Scale** (adaptive layouts from 320px mobile to 3840px Surface Hub). Unlike Material Design's single-seed generative approach, Fluent uses a brand-token injection model: you provide a brand ramp (16 shades of your brand color), and the system maps those shades to 160+ semantic alias tokens.
+
+**Key architectural distinction:** Fluent 2 separates "global tokens" (platform-level primitives like `colorNeutralBackground1`), "alias tokens" (semantic mappings like `colorBrandBackground`), and "component tokens" (per-component overrides). The alias layer is where theming happens. Swapping the alias-to-global mapping changes the entire application's appearance.
+
+**Fluent is context-aware.** The same `Dialog` component renders with Acrylic material on Windows 11 (where the compositor supports real-time blur), falls back to a solid color with subtle noise texture on web (where backdrop-filter has performance implications), and uses Mica on Windows 11 desktop app backgrounds. Material selection is not a design choice -- it is a platform capability negotiation.
+
+## Details
+
+### The Five Foundational Elements
+
+**Light** in Fluent manifests as reveal highlight -- a lighting effect that follows the cursor and illuminates interactive surface boundaries. On hover, a radial gradient (diameter ~120px, falloff from 12% white at center to 0% at edge) follows the pointer, making borders and clickable regions glow. This effect answers the question "what can I interact with?" without requiring explicit affordances.
+
+**Reveal highlight implementation (CSS approximation):**
+
+```css
+.fluent-reveal {
+  position: relative;
+  overflow: hidden;
+}
+.fluent-reveal::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: radial-gradient(
+    circle 120px at var(--mouse-x) var(--mouse-y),
+    rgba(255, 255, 255, 0.12) 0%,
+    rgba(255, 255, 255, 0.04) 40%,
+    transparent 100%
+  );
+  pointer-events: none;
+}
+```
+
+The JavaScript component tracks `mousemove` events and updates `--mouse-x` / `--mouse-y` CSS custom properties. On Windows 11 with WinUI 3, this is handled natively by the compositor at 60fps with no JavaScript overhead.
+
+**Depth** uses three explicit layers: Base (z=0, app content), Raised (z=8, cards and commanding surfaces), and Overlay (z=32, dialogs, flyouts, teaching tips). Each layer has a corresponding shadow token:
+
+```
+shadow2:    0 1px 2px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Raised)
+shadow4:    0 2px 4px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Commanding)
+shadow8:    0 4px 8px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Cards)
+shadow16:   0 8px 16px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)    (Flyouts)
+shadow28:   0 14px 28px rgba(0,0,0,0.24), 0 0 8px rgba(0,0,0,0.20)   (Dialogs)
+shadow64:   0 32px 64px rgba(0,0,0,0.24), 0 0 8px rgba(0,0,0,0.20)   (Full overlays)
+```
+
+Each shadow uses a dual-layer technique: a larger spread for the ambient term and a tighter spread for the key light.
+
+**Motion** uses four duration tiers and two easing families:
+
+```
+Duration:
+  ultraFast:   50ms     (checkbox check, toggle snap)
+  fast:        100ms    (button press feedback)
+  normal:      200ms    (panel slide, card expand)
+  slow:        300ms    (page transition, dialog enter)
+  slower:      500ms    (connected animation, full-screen morph)
+
+Easing:
+  accelerate:  cubic-bezier(0.9, 0.1, 1.0, 0.2)     (element exiting)
+  decelerate:  cubic-bezier(0.1, 0.9, 0.2, 1.0)     (element entering)
+  linear:      cubic-bezier(0, 0, 1, 1)               (progress bars, spinners)
+```
+
+**Scale** defines four responsive tiers with specific adaptation rules:
+
+```
+Small:    320px - 479px    Single column, stacked nav, bottom sheet
+Medium:   480px - 1023px   Flexible column, rail nav, side panel
+Large:    1024px - 1365px  Multi-column, sidebar nav, inline panel
+XLarge:   1366px+          Extended layout, expanded sidebar, canvas
+```
+
+### Acrylic and Mica Materials
+
+**Acrylic** is a translucent material that blurs the content directly behind it. It comes in two variants:
+
+- **Background Acrylic:** Blurs content from behind the application window (the desktop, other windows). Used for navigation panes and sidebars. Tint: 80% opacity of the surface color with a Gaussian blur at 30px radius and a noise texture at 2% opacity.
+- **In-app Acrylic:** Blurs content within the application (the content area beneath a flyout or command bar). Used for command bars, context menus, and flyouts. Tint: 70% opacity, blur: 20px, noise: 2%.
+
+**Acrylic recipe (CSS for web approximation):**
+
+```css
+.acrylic-background {
+  background-color: rgba(255, 255, 255, 0.8); /* tint layer */
+  backdrop-filter: blur(30px) saturate(125%); /* blur + saturation boost */
+}
+.acrylic-background::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: url('noise.png'); /* 2% noise texture */
+  opacity: 0.02;
+  pointer-events: none;
+}
+```
+
+**Mica** is a material unique to Windows 11 that samples the user's desktop wallpaper and creates a subtle, static tint for the app's title bar and background. Unlike Acrylic, Mica does not blur in real-time -- it samples once and applies a static color derived from the wallpaper. This makes it dramatically cheaper to render.
+
+**Mica properties:**
+
+```
+Base Mica:       Wallpaper sample at 80% luminance, no blur, very subtle tint
+Mica Alt:        Wallpaper sample at 70% luminance, slightly more opaque
+Fallback (web):  Solid colorNeutralBackground1 (#FFFFFF light / #292929 dark)
+```
+
+**Material selection decision procedure:**
+
+1. Is this a window/title bar background? -> **Mica**
+2. Is this a navigation pane behind content? -> **Background Acrylic**
+3. Is this a flyout/menu overlaying content? -> **In-app Acrylic**
+4. Is the platform unable to composite blur? -> **Solid fallback with noise texture**
+5. Has the user enabled "Transparency effects: Off"? -> **Solid fallback, no blur, no noise**
+
+### Connected Animations
+
+Connected animations create visual continuity between views by morphing a shared element from its position in the source view to its position in the destination view.
+
+**The three-phase model:**
+
+1. **Prepare** (0ms): Snapshot the source element's bounds, corner radius, and opacity.
+2. **Animate** (300ms, `decelerate` easing): Interpolate position, size, corner radius, and opacity from source to destination.
+3. **Complete** (0ms): Hand off rendering to the destination element.
+
+**Concrete example -- file explorer thumbnail (80x80, radius 4px, at position 120,340) morphing to full image preview (1200x800, radius 0px, at 0,0):** All properties -- position, size, corner radius -- interpolate over 300ms with `decelerate` easing. On web, implement using the FLIP technique (First-Last-Invert-Play): snapshot source bounds, position destination, calculate the inverse transform, then animate from inverted to natural position.
+
+### Responsive Containers and Layout
+
+Fluent 2 uses container-based responsive design rather than viewport-based. A `Card` adapts to its container width, not the window width. This means the same Card component works in a full-width layout, a split-view panel, and a Teams tab without media query overrides.
+
+**Container query breakpoints:** Use `container-type: inline-size` on parent elements. Compact (<300px): stack vertically, center actions. Standard (300-599px): row layout with trailing actions. Extended (600px+): grid with metadata column. This replaces viewport media queries entirely.
+
+**Fluent's 4px grid:** All spacing values are multiples of 4px: `XXS: 2px` (icon-to-text), `XS: 4px` (compact padding), `S: 8px` (standard gap), `M: 12px` (card padding), `L: 16px` (section gap), `XL: 20px` (panel margin), `XXL: 24px` (page margin).
+
+### Token Theming Architecture
+
+Fluent 2 tokens follow a three-tier hierarchy: **Global -> Alias -> Component**.
+
+**Brand ramp injection:** You supply 16 shades (shade10 through shade160) spanning L*=5 (darkest) to L*=98 (lightest). Example for a blue brand: shade10 `#020305`, shade40 `#1B2E54`, shade80 `#4F72B8` (primary), shade120 `#B1CCF2`, shade160 `#FAFCFF`.
+
+```
+
+The alias layer maps these brand shades to semantic roles:
+
+```
+
+colorBrandBackground: brand[80] (primary buttons)
+colorBrandBackgroundHover: brand[70] (primary hover)
+colorBrandBackgroundPressed: brand[40] (primary pressed)
+colorBrandForeground1: brand[80] (links, active text)
+colorBrandStroke1: brand[80] (focus rings)
+
+```
+
+**Neutral palette (auto-generated):** Fluent generates 28 neutral shades from the brand hue with reduced chroma:
+
+```
+
+colorNeutralBackground1: #FFFFFF (light) / #292929 (dark)
+colorNeutralBackground2: #FAFAFA / #1F1F1F
+colorNeutralBackground3: #F5F5F5 / #141414
+colorNeutralForeground1: #242424 / #FFFFFF
+colorNeutralForeground2: #424242 / #D6D6D6
+colorNeutralForeground3: #616161 / #ADADAD
+colorNeutralStroke1: #D1D1D1 / #404040
+colorNeutralStroke2: #E0E0E0 / #333333
+
+````
+
+**Theme application in Fluent UI React v9:**
+
+```jsx
+import { FluentProvider, webLightTheme, createLightTheme } from '@fluentui/react-components';
+
+const customTheme = createLightTheme(myBrand);
+
+function App() {
+  return (
+    <FluentProvider theme={customTheme}>
+      <MyApplication />
+    </FluentProvider>
+  );
+}
+````
+
+### Anti-Patterns
+
+**Using Acrylic material everywhere.** Acrylic triggers real-time compositor blur which is expensive. Applying Acrylic to scrollable content areas, list items, or the main canvas causes frame drops, especially on integrated GPUs. Acrylic is reserved for commanding surfaces (nav pane, command bar, flyout) -- surfaces that overlay content. Use Mica for window backgrounds and solid colors for content areas.
+
+**Ignoring the transparency effects system setting.** Windows allows users to disable transparency effects (Settings > Personalization > Colors > Transparency effects: Off). When disabled, Acrylic and Mica must fall back to solid colors. If your CSS relies on `backdrop-filter` without a solid fallback, users with transparency off see a fully transparent (invisible) surface. Always provide `background-color` as a base layer beneath `backdrop-filter`.
+
+**Applying reveal highlight to non-interactive elements.** Reveal highlight signals interactivity. Placing it on static text blocks, images, or decorative elements teaches users that the light effect is meaningless, destroying its value as an affordance signal. Only apply reveal to elements that respond to click or tap: buttons, list items, cards with actions, navigation items.
+
+**Using viewport media queries instead of container queries.** A Fluent Card in a Teams side panel at 400px width should render in its compact layout, but a viewport media query at 1920px window width would give it the extended layout. Container queries ensure components adapt to their actual available space, not the window size. This is especially critical in embedded contexts (Teams tabs, SharePoint web parts, Outlook add-ins) where the viewport is not the component's container.
+
+**Flat brand ramp with insufficient contrast spread.** A brand ramp where shade10 through shade160 spans only L*=20 to L*=70 (instead of L*=5 to L*=98) produces alias tokens that fail WCAG AA contrast. `colorBrandForeground1` (brand[80]) on `colorNeutralBackground1` (#FFFFFF) must achieve 4.5:1 contrast. If brand[80] is too light (L\*>55), all branded text becomes illegible. Test the brand ramp extremes against both light and dark neutral backgrounds before deployment.
+
+### Real-World Examples
+
+**Microsoft Teams** is the canonical Fluent 2 implementation. The sidebar uses Background Acrylic (30px blur of the desktop). The chat pane uses `colorNeutralBackground1` (solid). Hover over a message reveals a command bar with In-app Acrylic. The compose box sits at `shadow4` elevation. When switching between chats, message avatars use connected animations -- the avatar morphs from the chat list position to the message header position over 300ms with decelerate easing.
+
+**Windows 11 File Explorer** demonstrates Mica on the title bar and navigation pane header, with the file list on a solid `colorNeutralBackground1`. Folder thumbnails use connected animations when transitioning to the preview pane. Reveal highlight illuminates folder items on hover, with the light effect flowing across adjacent items as the cursor moves through the list.
+
+**Visual Studio Code (Fluent theme)** shows the token theming system at scale: 160+ alias tokens are remapped to match VS Code's syntax highlighting and panel structure. The brand ramp uses VS Code's signature blue (`#007ACC` at brand[80]), generating all interactive states from hover (`brand[70]`: `#0066B8`) to pressed (`brand[40]`: `#003F73`) automatically from the 16-shade ramp.
+
+**Microsoft Loop** uses container-responsive layouts throughout. A Loop component embedded in a Teams message at 280px width renders in compact mode (stacked, minimal chrome). The same component in a full Loop page at 900px renders in extended mode (multi-column, full toolbar). Container queries drive all layout shifts, making the components truly portable across Microsoft 365 hosts.
+
+## Source
+
+Microsoft Fluent 2 Design System (fluent2.microsoft.design, 2024). Fluent UI React v9 documentation (react.fluentui.dev). Windows App SDK design guidelines. MSDN documentation on Acrylic, Mica, and connected animations. WinUI 3 Gallery app source code.
+
+## 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/claude-code/design-fluent-design/skill.yaml

@@ -0,0 +1,35 @@
+name: design-fluent-design
+version: '1.0.0'
+description: Microsoft Fluent 2 design system covering light/depth/motion/material/scale, acrylic material, reveal highlight, connected animations, responsive containers, and token theming
+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-motion-principles
+  - design-token-architecture
+stack_signals: []
+keywords:
+  - fluent-design
+  - Microsoft
+  - acrylic
+  - reveal-highlight
+  - connected-animations
+  - responsive-containers
+  - Windows
+  - Teams
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []