@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/design-responsive-type/SKILL.md

@@ -0,0 +1,270 @@
+# Responsive Type
+
+> Type across viewports — fluid typography with CSS clamp(), viewport-relative scaling, minimum readable sizes, and maintaining hierarchy across breakpoints
+
+## When to Use
+
+- Building a site that must look correct from 320px mobile to 2560px ultrawide monitors
+- Replacing a brittle system of 4+ media query breakpoints for font sizes
+- Implementing fluid typography that scales smoothly between minimum and maximum sizes
+- Ensuring body text never drops below readable minimums on small screens
+- Maintaining consistent typographic hierarchy ratios across all viewport widths
+
+## Instructions
+
+1. **Understand the core problem.** Fixed font sizes create two failure modes:
+   - **Too small on mobile**: 14px body text on a 320px screen with 16px padding leaves only 288px of content width — text is cramped and lines wrap excessively
+   - **Too small on desktop**: that same 14px body text on a 2560px ultrawide monitor is proportionally tiny, creating excessive line lengths and visual insignificance
+   - **The solution**: font sizes that scale proportionally with viewport width, bounded by minimum and maximum values
+
+2. **Use CSS `clamp()` for fluid typography.** The `clamp()` function accepts three values: minimum, preferred (fluid), and maximum:
+
+   ```css
+   /* Font scales from 16px (mobile) to 20px (desktop) */
+   font-size: clamp(1rem, 0.8rem + 0.5vw, 1.25rem);
+   ```
+
+   The preferred value (`0.8rem + 0.5vw`) creates a smooth scaling curve. The `rem` component provides a stable base; the `vw` component adds viewport-proportional growth. The clamp bounds prevent the font from going below 16px or above 20px.
+
+3. **Calculate the preferred value using the fluid type formula.** Given:
+   - `min-size`: the smallest font size (in px)
+   - `max-size`: the largest font size (in px)
+   - `min-vw`: the viewport width where min-size applies (typically 320px)
+   - `max-vw`: the viewport width where max-size applies (typically 1240px or 1440px)
+
+   The formula:
+
+   ```
+   preferred = min-size + (max-size - min-size) * ((100vw - min-vw) / (max-vw - min-vw))
+   ```
+
+   In CSS-friendly form (converting to rem + vw):
+
+   ```
+   slope = (max-size - min-size) / (max-vw - min-vw)
+   intercept = min-size - (slope * min-vw)
+   preferred = intercept(rem) + slope(vw)
+   ```
+
+   **Worked example — 16px to 20px between 320px and 1240px viewports:**
+
+   ```
+   slope = (20 - 16) / (1240 - 320) = 4 / 920 = 0.00435 = 0.435vw
+   intercept = 16 - (0.00435 * 320) = 16 - 1.391 = 14.609px = 0.913rem
+   Result: clamp(1rem, 0.913rem + 0.435vw, 1.25rem)
+   ```
+
+   You do not need to calculate this by hand — use Utopia.fyi or similar calculators. But understanding the math prevents blind copy-pasting of values you cannot debug.
+
+4. **Apply fluid scaling to your entire type scale.** Each step in your type scale gets its own clamp() with proportional min/max values:
+
+   | Token     | Mobile (320px) | Desktop (1240px) | CSS                                             |
+   | --------- | -------------- | ---------------- | ----------------------------------------------- |
+   | text-sm   | 14px           | 14px             | `0.875rem` (no scaling needed)                  |
+   | text-base | 16px           | 18px             | `clamp(1rem, 0.957rem + 0.217vw, 1.125rem)`     |
+   | text-lg   | 18px           | 22px             | `clamp(1.125rem, 1.038rem + 0.435vw, 1.375rem)` |
+   | text-xl   | 22px           | 28px             | `clamp(1.375rem, 1.245rem + 0.652vw, 1.75rem)`  |
+   | text-2xl  | 28px           | 40px             | `clamp(1.75rem, 1.489rem + 1.304vw, 2.5rem)`    |
+   | text-3xl  | 36px           | 56px             | `clamp(2.25rem, 1.815rem + 2.174vw, 3.5rem)`    |
+
+   **Key principle**: larger type scales more aggressively. Body text grows by 2px (16->18), but display text grows by 20px (36->56). This maintains the hierarchy ratio — if everything grew by the same absolute amount, headings would lose prominence on desktop.
+
+5. **Enforce minimum readable sizes.** These are non-negotiable floors:
+   - **Body text**: 16px minimum on all viewports (WCAG 1.4.4 requires 200% zoom support; starting below 16px makes zoomed text unwieldy)
+   - **Secondary text** (captions, labels): 12px minimum on desktop, 14px minimum on mobile (touch targets need larger text)
+   - **Interactive text** (buttons, links): 16px minimum on mobile (Apple HIG recommends 17px for iOS)
+   - **Code blocks**: 13px minimum (developers accept smaller code text, but below 13px monospace becomes illegible on standard DPI screens)
+   - If your fluid calculation produces a size below these minimums at any viewport, raise the minimum in the clamp()
+
+6. **Decide between fluid scaling and breakpoint scaling.** Both approaches are valid:
+
+   **Fluid scaling (clamp):**
+   - Pros: smooth transitions, no jarring size jumps, fewer values to maintain
+   - Cons: harder to debug (what size am I at 834px?), requires understanding the math
+   - Best for: marketing sites, editorial content, any page where smooth scaling enhances the experience
+
+   **Breakpoint scaling (media queries):**
+   - Pros: predictable — you know exactly what size at each breakpoint, easy to debug
+   - Cons: abrupt changes at breakpoints, more CSS to maintain, gaps between breakpoints
+   - Best for: complex applications with fixed layout breakpoints, design systems with strict size tokens
+
+   **Hybrid approach (recommended for most projects):**
+   - Use breakpoints for layout changes (grid columns, sidebar visibility)
+   - Use fluid scaling for typography within each layout
+   - This gives you smooth type scaling without the complexity of fully fluid layouts
+
+## Details
+
+### The Utopia Approach
+
+Utopia (utopia.fyi) is the most rigorous fluid type system in production use. Its methodology:
+
+1. Define a minimum viewport (320px) and maximum viewport (1240px)
+2. Define a base size at each extreme: 16px (mobile) and 20px (desktop)
+3. Define a scale ratio at each extreme: 1.2 (mobile) and 1.25 (desktop)
+4. Generate every type scale step as a fluid value between its mobile and desktop sizes
+
+**Utopia's key insight**: the type scale ratio itself can change between viewports. A tighter ratio on mobile (1.2 minor third) prevents headings from overwhelming small screens, while a wider ratio on desktop (1.25 major third) creates more dramatic hierarchy on large screens. This means the hierarchy does not just scale — it adapts.
+
+Example output from Utopia for a 5-step scale:
+
+```css
+:root {
+  --step--1: clamp(0.8333rem, 0.7981rem + 0.1757vw, 1rem); /* 13-16px */
+  --step-0: clamp(1rem, 0.9348rem + 0.3261vw, 1.25rem); /* 16-20px */
+  --step-1: clamp(1.2rem, 1.0893rem + 0.5536vw, 1.5625rem); /* 19-25px */
+  --step-2: clamp(1.44rem, 1.2631rem + 0.8844vw, 1.9531rem); /* 23-31px */
+  --step-3: clamp(1.728rem, 1.4583rem + 1.3484vw, 2.4414rem); /* 28-39px */
+  --step-4: clamp(2.0736rem, 1.6766rem + 1.985vw, 3.0518rem); /* 33-49px */
+}
+```
+
+### Material Design's Breakpoint Approach
+
+Material Design 3 uses discrete breakpoints rather than fluid scaling:
+
+| Window Class | Width Range | Body | Headline Large | Display Large |
+| ------------ | ----------- | ---- | -------------- | ------------- |
+| Compact      | 0-599px     | 14px | 28px           | 45px          |
+| Medium       | 600-839px   | 14px | 32px           | 52px          |
+| Expanded     | 840px+      | 16px | 32px           | 57px          |
+
+Material's reasoning: their component system uses fixed-width layout patterns (cards, rails, drawers), so typography tied to those fixed patterns is more predictable than fluid values. This is a valid engineering trade-off — fluid is not always better.
+
+### Tailwind CSS Responsive Typography
+
+Tailwind provides responsive font sizes through breakpoint prefixes:
+
+```html
+<h1 class="text-2xl md:text-4xl lg:text-5xl">Responsive Heading</h1>
+```
+
+This maps to:
+
+- Mobile (<768px): 24px
+- Tablet (768px+): 36px
+- Desktop (1024px+): 48px
+
+Tailwind does not include fluid typography by default, but it integrates well with clamp:
+
+```javascript
+// tailwind.config.js
+fontSize: {
+  'fluid-base': 'clamp(1rem, 0.913rem + 0.435vw, 1.25rem)',
+  'fluid-lg':   'clamp(1.25rem, 1.076rem + 0.87vw, 1.75rem)',
+  'fluid-xl':   'clamp(1.75rem, 1.315rem + 2.174vw, 3.5rem)',
+}
+```
+
+### Viewport Unit Limitations
+
+Pure viewport units (`vw`) have critical problems:
+
+- **On very small screens** (smartwatches, 200px viewports): `2vw` = 4px — microscopic and unreadable
+- **On very large screens** (4K monitors, 3840px viewports): `2vw` = 76.8px — comically oversized
+- **User zoom is defeated**: viewport units do not scale with browser zoom, violating WCAG 1.4.4 (Resize Text). Users who set their browser to 200% zoom get no benefit for vw-based text.
+- **Solution**: always combine `vw` with `rem` in the preferred value (`0.5rem + 1vw`), and always wrap in `clamp()` with rem-based min/max. The `rem` component ensures zoom still works.
+
+### Anti-Patterns
+
+1. **Pure vw units without clamp bounds.** `font-size: 3vw` produces 9.6px on a 320px phone (illegible) and 57.6px on a 1920px desktop (absurd). This is the most common fluid typography mistake. Every viewport-relative size must have minimum and maximum bounds via `clamp()`.
+
+2. **Too many breakpoint overrides.** A heading that changes size at 5 breakpoints (480px, 640px, 768px, 1024px, 1280px) is a maintenance burden and creates 5 jarring size transitions. Fluid typography with `clamp()` eliminates breakpoint overrides for font sizes entirely. If you must use breakpoints, limit to 2 (mobile and desktop).
+
+3. **Shrinking body text below 14px on any viewport.** Some responsive systems scale body text to 12px or 13px on mobile "to fit more content." This sacrifices readability — the primary purpose of text. If content does not fit at 16px, the layout needs adjustment, not the font size. Minimum body text is 16px on all viewports.
+
+4. **Non-proportional scaling that destroys hierarchy.** When headings scale from 48px to 24px (50% reduction) but body text stays fixed at 16px, the heading-to-body ratio drops from 3:1 to 1.5:1. At mobile sizes, the heading barely stands out. Fix: scale all text levels proportionally — if headings shrink 33%, body should shrink ~10-15% to maintain the ratio difference (just less aggressively).
+
+5. **Forgetting line-height needs to scale too.** A heading at 48px with `line-height: 1.1` (52.8px leading) works beautifully. That same heading scaled to 24px on mobile still has `line-height: 1.1` (26.4px leading), which is too tight for a smaller size that now wraps to more lines. Use fluid line-height: `line-height: clamp(1.1, 1.0 + 0.25vw, 1.3)` or set line-height per breakpoint.
+
+### Real-World Examples
+
+**Implementing Utopia for a Marketing Site**
+Requirements: hero headline 36-72px, subheadline 20-32px, body 16-20px, caption 14-16px.
+Viewport range: 320px to 1440px.
+
+```css
+:root {
+  --text-caption: clamp(0.875rem, 0.8315rem + 0.2174vw, 1rem);
+  --text-body: clamp(1rem, 0.913rem + 0.4348vw, 1.25rem);
+  --text-sub: clamp(1.25rem, 0.9891rem + 1.3043vw, 2rem);
+  --text-hero: clamp(2.25rem, 1.4674rem + 3.913vw, 4.5rem);
+}
+```
+
+Hierarchy ratios:
+
+- At 320px: hero/body = 36/16 = 2.25:1
+- At 1440px: hero/body = 72/20 = 3.6:1
+- The ratio widens on desktop — correct behavior, because large screens can support more dramatic hierarchy.
+
+**Converting a Breakpoint System to Fluid**
+Before (5 breakpoints):
+
+```css
+h1 {
+  font-size: 24px;
+}
+@media (min-width: 480px) {
+  h1 {
+    font-size: 28px;
+  }
+}
+@media (min-width: 640px) {
+  h1 {
+    font-size: 32px;
+  }
+}
+@media (min-width: 768px) {
+  h1 {
+    font-size: 36px;
+  }
+}
+@media (min-width: 1024px) {
+  h1 {
+    font-size: 42px;
+  }
+}
+@media (min-width: 1280px) {
+  h1 {
+    font-size: 48px;
+  }
+}
+```
+
+After (1 line):
+
+```css
+h1 {
+  font-size: clamp(1.5rem, 0.978rem + 2.609vw, 3rem);
+}
+```
+
+Same visual result (24px at 320px, 48px at 1280px), smooth transitions at every viewport in between, one declaration instead of six.
+
+## Source
+
+- Utopia — Fluid Type Scale Calculator (utopia.fyi)
+- CSS-Tricks — "Simplified Fluid Typography" by Chris Coyier
+- Modern Fluid Typography Using CSS Clamp — smashingmagazine.com
+- WCAG 2.1 Success Criterion 1.4.4 — Resize Text
+- Material Design 3 — Applying Typography (responsive type guidance)
+
+## Process
+
+1. **Evaluate** — Identify the current responsive type approach (fixed, breakpoint, or fluid). Check minimum sizes on the smallest target viewport. Calculate heading-to-body ratios at mobile and desktop to verify hierarchy is maintained.
+2. **Apply** — Define fluid type values using clamp() with the min/preferred/max formula. Ensure body text minimum is 16px. Scale headings more aggressively than body to maintain hierarchy ratios. Use Utopia or manual calculation.
+3. **Verify** — Test at 320px, 768px, 1024px, 1440px, and 2560px viewports. Confirm no text drops below minimum sizes. Verify hierarchy ratios are maintained across all widths. Check that browser zoom (200%) still increases text size (fails if using only vw units).
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides responsive typography expertise to guide font-size declarations across viewports. Use these principles when implementing CSS `clamp()` values, configuring Tailwind `fontSize` with fluid values, or auditing responsive type behavior. Cross-reference with `design-type-scale` for base scale ratios and `design-readability` for line-length interaction at different viewport sizes.
+
+## Success Criteria
+
+- All type sizes use either fluid (clamp) or breakpoint scaling — no fixed px values that ignore viewport
+- Body text is at least 16px at every viewport width including 320px
+- Heading-to-body size ratio is maintained within 20% across mobile and desktop viewports
+- No font size uses pure vw units without rem component and clamp bounds
+- Browser zoom at 200% increases all text sizes (no viewport-unit-only text)
+- Fluid type declarations use a consistent viewport range (e.g., 320px-1240px) across all tokens

package/dist/agents/skills/codex/design-responsive-type/skill.yaml

@@ -0,0 +1,34 @@
+name: design-responsive-type
+version: "1.0.0"
+description: Type across viewports — fluid typography (clamp), viewport scaling, minimum sizes, maintaining hierarchy
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-type-scale
+  - design-readability
+  - design-responsive-strategy
+stack_signals: []
+keywords:
+  - responsive type
+  - fluid typography
+  - clamp
+  - viewport units
+  - minimum font size
+  - scaling
+  - responsive font
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-state-design/SKILL.md

@@ -0,0 +1,152 @@
+# UI State Design
+
+> UI state inventory — empty, loading, partial, error, success, offline, disabled, read-only, and how each state communicates system status
+
+## When to Use
+
+- Designing a new component or view that fetches data, accepts input, or depends on network availability
+- Auditing an existing interface for missing state coverage — most production bugs live in unhandled states
+- Building a component library or design system that needs state documentation per component
+- Reviewing pull requests that add UI components without accounting for all possible states
+- Planning error handling strategy across an application
+- Designing offline-capable or progressive web applications
+- Implementing accessibility — screen readers must announce state changes correctly
+- Any time a user might encounter a condition other than "happy path with full data"
+
+## Instructions
+
+1. **Enumerate every possible state before writing any UI code.** For each component or view, walk through the complete state inventory: empty, loading, partial data, error, success, offline, disabled, and read-only. Write them down explicitly. Vercel's deployment dashboard handles nine distinct states for a single deployment card: queued, building, deploying, ready, error, canceled, stale, archived, and rolling back. Each has a unique visual treatment. Missing even one creates a jarring undefined-state flash.
+
+2. **Map each state to a visual treatment.** Every state needs three decisions: (a) what the user sees, (b) what action is available, and (c) what the screen reader announces. Use this matrix:
+
+   | State     | Visual Signal                 | Available Actions         | Announcement Pattern           |
+   | --------- | ----------------------------- | ------------------------- | ------------------------------ |
+   | Empty     | Illustration + prompt         | Primary CTA               | "No items. Create your first." |
+   | Loading   | Skeleton / spinner            | None or cancel            | "Loading content"              |
+   | Partial   | Real data + skeleton gaps     | Interact with loaded data | "Content partially loaded"     |
+   | Error     | Error message + retry         | Retry, go back, contact   | "Error: [message]. Retry?"     |
+   | Success   | Confirmation + next step      | Continue, dismiss         | "Success: [action] completed"  |
+   | Offline   | Cached data + offline badge   | Read-only, queue actions  | "You are offline"              |
+   | Disabled  | Reduced opacity + tooltip     | None (tooltip explains)   | "[Control] disabled: [reason]" |
+   | Read-only | Full data, no edit affordance | Copy, export              | "[Field] read-only"            |
+
+3. **Design empty states as onboarding opportunities, not dead ends.** An empty state is the first thing a new user sees. It must answer three questions: What is this page for? Why is it empty? What should I do? GitHub's empty repository page is the canonical example: it explains what a repository is, shows why it is empty ("You created this just now"), and provides exact commands to push code.
+
+4. **Distinguish between "no data yet" and "no results."** A search that returns nothing is fundamentally different from a fresh account with no data. "No results for 'xyzzy'" needs a suggestion to broaden the search. "No projects yet" needs a create button. Mixing these states confuses users about whether the system is broken or their query is wrong.
+
+5. **Use progressive state transitions, not binary flips.** Moving from loading to loaded should feel continuous. Skeleton screens that morph into real content (as used by Facebook, LinkedIn, and Slack) create continuity. A spinner that disappears and is replaced by fully-rendered content creates a perceptual discontinuity — the user must re-orient to a completely new visual layout.
+
+6. **Make error states actionable.** Every error state must include at least one action the user can take. "Something went wrong" with no button is a dead end. Stripe's payment error states always include: (a) what went wrong in plain language, (b) a specific suggestion ("Check your card number"), and (c) a retry mechanism. The error message itself becomes an affordance for recovery.
+
+7. **Communicate disabled reasons proactively.** A disabled button with no explanation is a puzzle. Always pair disabled states with a tooltip, helper text, or inline explanation that says why the control is disabled and what the user needs to do to enable it. Linear disables the "Create Issue" button when no project is selected and shows "Select a project first" as helper text — the disabled state teaches rather than blocks.
+
+8. **Design offline states as first-class experiences.** For applications that may lose connectivity, offline is not an error — it is a state. Show cached data with a subtle offline indicator (Slack uses a yellow banner: "You're not connected to the Internet"). Queue user actions for replay when connectivity returns. Never show a blank screen when cached data is available.
+
+## Details
+
+### The Nine-State Inventory
+
+**Empty state** is the most underdesigned state in production software. It appears in three variants: (1) first-use empty — the user has never created anything, (2) cleared empty — the user deleted all items, and (3) no-results empty — a filter or search returned nothing. Each variant needs different messaging. Notion's empty page shows a minimal prompt ("Press '/' for commands") that simultaneously teaches the interaction model. Airbnb's empty wishlist shows curated suggestions — the empty state itself becomes a discovery surface.
+
+**Loading state** must match the expected content layout. A spinner is appropriate only when the content layout is unpredictable (e.g., a search whose result format varies). When the layout is known — a profile page, a dashboard grid, a settings panel — use skeleton screens that mirror the actual content structure. Facebook pioneered this pattern: their skeleton screens match the exact dimensions of the post, avatar, and text block they will replace. This reduces perceived load time by 15-30% compared to spinners (research by Nielsen Norman Group).
+
+**Partial data state** occurs when some API calls resolve before others, when paginated data is still loading, or when a WebSocket connection delivers incremental updates. The decision is whether to show what you have or wait for everything. The rule: show partial data if the already-loaded content is independently useful. GitHub's pull request page loads the description and metadata first, then comments stream in below. The user can begin reading immediately. Conversely, a checkout page should not show partial data — displaying a total without all line items is misleading.
+
+**Error state** has two dimensions: severity (recoverable vs terminal) and scope (field-level vs page-level vs system-level). A field validation error is low severity, field scope — show it inline. A 500 server error is high severity, page scope — replace the page content with an error message and recovery options. A network timeout is medium severity, component scope — show a retry button on the affected component without disrupting the rest of the page. Vercel's build error pages display the full error log with syntax highlighting, a "Redeploy" button, and links to relevant documentation — turning a frustrating error into a debugging workflow.
+
+**Success state** is where most designers stop and most users get lost. A success message without a next step leaves the user asking "Now what?" After Stripe processes a payment, the success state shows: confirmation of what happened, a receipt summary, and clear next steps (view in dashboard, send receipt, return to store). The success state is a navigation waypoint, not a destination.
+
+**Offline state** requires a data freshness indicator. When showing cached data, communicate its age: "Last updated 5 minutes ago" (acceptable) vs "Last updated 3 days ago" (user should know this data may be stale). Service workers should cache the most recent successful response for every critical view. Slack shows full cached channel history offline with a "Connecting..." banner — users can read everything, they just cannot send.
+
+**Disabled state** must be visually distinct from read-only. Disabled means "this control exists but you cannot use it right now" — reduced opacity (typically 0.4-0.6) and a `not-allowed` cursor. Read-only means "this data is presented for viewing" — full opacity, no interactive affordances, but no suggestion that interaction is broken. A disabled input has a grayed label and a `not-allowed` cursor. A read-only input has a normal label, no border, and looks like static text with a subtle background.
+
+**Read-only state** is often conflated with disabled but serves a completely different purpose. Read-only says "you can see this but editing is not available to you" — common in shared documents, audit logs, or permission-restricted views. Google Docs' "Viewer" mode removes all editing UI and shows a clean reading experience. The user never wonders if something is broken because there are no disabled controls — the editing affordances simply do not exist.
+
+### State Transition Timing
+
+State transitions have timing requirements that affect perceived quality:
+
+- **Loading to content:** Under 100ms, show no loading state — the content appears instant. 100ms-1s, show a skeleton screen. Over 1s, show a skeleton with a progress indicator. Over 10s, show a skeleton with an estimated time remaining and a cancel option. These thresholds come from Jakob Nielsen's response time research (1993, validated repeatedly).
+- **Action to success:** Optimistic updates should render in under 50ms (one frame at 20fps). The success state should persist for at least 2 seconds before auto-dismissing — shorter than 2 seconds and users miss it. Slack's message send is optimistic: the message appears in the chat immediately (under 50ms), with a subtle "sending" indicator that resolves to a timestamp on server confirmation.
+- **Error appearance:** Error states should animate in, not pop. A 200-300ms ease-in transition gives the user time to notice the change. Instant error appearance (0ms) feels like the page "jumped" and users may not register what changed.
+
+### State Composition in Complex Views
+
+Real views compose multiple independent state machines. A dashboard might have: navigation (loaded), header stats (loading), main chart (error), and sidebar list (partial). Each component manages its own state independently. The critical rule: **one component's error must not block another component's content.** GitHub's repository page demonstrates this — if the README fails to render, the file tree, branch selector, and metadata still display. The README section shows its own error state in isolation.
+
+When multiple components are loading simultaneously, stagger skeleton appearances by 50-100ms to create a cascade effect rather than a simultaneous flash. This makes the loading feel progressive and intentional.
+
+### State Persistence Across Sessions
+
+Certain UI states must persist across browser sessions and page refreshes:
+
+- **Form drafts:** If a user has partially completed a form (issue creation, comment composition, settings changes), their input should survive page refresh and browser close. GitHub auto-saves issue draft content to `localStorage`. Linear persists draft issues across sessions.
+- **View preferences:** Column widths, sort order, filter selections, collapsed/expanded sidebar sections should persist per user. These are not "data" — they are UI state that users expect to remain stable. Store in `localStorage` for anonymous users, in user preferences for authenticated users.
+- **Dismissed notices:** If a user dismisses a banner or onboarding tooltip, it should stay dismissed. Store dismissed states by ID in `localStorage` or user preferences. Never show a dismissed notice again unless the content has materially changed.
+- **Navigation position:** If a user was on page 4 of a paginated list, returning to that view should restore page 4, not reset to page 1. For infinite scroll views, store the scroll position and loaded item count. Slack restores exact scroll position within channels.
+
+### Anti-Patterns
+
+1. **The Boolean Trap.** Modeling state as `isLoading: boolean` and `hasError: boolean` creates impossible combinations (`isLoading: true, hasError: true`). This leads to race conditions where the UI shows both a spinner and an error message simultaneously. Fix: use a discriminated union / state machine with mutually exclusive states: `{ status: 'idle' | 'loading' | 'error' | 'success', data?: T, error?: Error }`. Libraries like XState or Zag enforce this at the type level.
+
+2. **The Empty White Screen.** Showing a blank white page while data loads, with no skeleton, spinner, or indication that anything is happening. Users interpret a blank screen as a broken page and leave within 2-3 seconds. Every view must have a defined loading state — if you are unsure what to show, a centered spinner is better than nothing, and a skeleton screen is better than a spinner.
+
+3. **Error Messages Written for Developers.** Showing raw error strings like "TypeError: Cannot read property 'name' of undefined" or HTTP status codes like "Error 500" to end users. Error messages must be written in the user's language, describe what happened from their perspective, and offer a concrete recovery action. "We couldn't load your projects. Check your connection and try again." is always better than "FETCH_FAILED: Network Error."
+
+4. **Disabled Without Explanation.** A submit button that is grayed out with no tooltip, no helper text, and no indication of what the user must do to enable it. The user clicks repeatedly, nothing happens, frustration builds. Every disabled control must have an associated explanation visible on hover, focus, or as persistent helper text.
+
+5. **Optimistic Without Rollback.** Showing a success state optimistically (before server confirmation) without a plan for what happens when the server rejects the action. The user sees "Message sent," the server returns a 403, and the message silently disappears. Optimistic updates require a visible rollback: re-insert the failed item with an error indicator and a retry action.
+
+### Real-World Examples
+
+**Vercel Deployment States.** A single deployment card cycles through: Queued (gray dot, "Waiting..."), Building (animated yellow dot, build log streaming), Deploying (animated blue dot, "Deploying to edge"), Ready (green checkmark, preview URL), Error (red X, error summary with "View Logs" link), Canceled (gray slash, "Canceled by [user]"). Each state has a distinct color, icon, label, and available action. The transitions animate smoothly — the dot color morphs rather than swaps. This is a masterclass in state design for a single component.
+
+**Slack Message Lifecycle.** A message traverses: Composing (text in input, real-time character display), Sending (message appears in chat with subtle opacity reduction and clock icon), Sent (full opacity, timestamp replaces clock), Failed (red warning icon, "Not delivered — click to retry"), Edited (original content replaced, "(edited)" suffix), Deleted ("This message was deleted" placeholder). Every state is visually distinct and every failure state includes a recovery action.
+
+**GitHub Repository Empty State.** A new repository with no commits shows: a clear heading ("Quick setup"), the repository URL with a copy button, and two complete workflow paths ("...or create a new repository on the command line" and "...or push an existing repository"). It also shows import options for migrating from other platforms. The empty state anticipates every user's likely next action and provides the exact commands needed.
+
+**Linear Issue States.** Linear defines a strict state machine for issues: Backlog, Todo, In Progress, Done, Canceled. Each state has a unique icon shape and color. Transitions are constrained — you cannot move from Backlog directly to Done without passing through intermediate states (unless explicitly overridden). The state machine prevents impossible states and the visual system makes the current state instantly scannable in a list of hundreds of issues.
+
+**Stripe Payment Form Field States.** Each input field in Stripe's checkout form cycles through five visual states independently: Empty (gray border, placeholder visible), Focused (blue border, placeholder fades, label floats), Filled (gray border, value displayed, green checkmark if valid), Error (red border, error message below, red icon), and Disabled (light gray background, reduced opacity). The states are managed per-field, not per-form — the card number can be in an error state while the expiry is focused and the CVC is empty. This independent state management prevents a single validation error from disrupting the entire form experience.
+
+### State Documentation for Design Systems
+
+When building a component library, every component must have its states documented explicitly. The documentation format should include:
+
+**State matrix per component.** For each component, create a matrix listing every state and its visual specification:
+
+| Component | State    | Background   | Border | Text Color | Icon    | Opacity | Cursor      |
+| --------- | -------- | ------------ | ------ | ---------- | ------- | ------- | ----------- |
+| Button    | Default  | Primary blue | None   | White      | None    | 1.0     | pointer     |
+| Button    | Hover    | Blue-dark    | None   | White      | None    | 1.0     | pointer     |
+| Button    | Active   | Blue-darker  | None   | White      | None    | 1.0     | pointer     |
+| Button    | Disabled | Gray-200     | None   | Gray-500   | None    | 0.5     | not-allowed |
+| Button    | Loading  | Primary blue | None   | Hidden     | Spinner | 0.8     | wait        |
+
+**Transition definitions.** Document how each state transitions to the next: duration, easing curve, which properties animate. Material Design documents this for every component — their button spec includes exact animation values for each state transition (100ms ease-in for press, 200ms ease-out for release, 150ms for focus ring appearance).
+
+**Compound state rules.** Some states can coexist (focused + error, hover + disabled). Document which combinations are valid and how they resolve visually. A focused error field should show both the focus ring and the error border — typically by using the error color for the focus ring rather than the default blue.
+
+## Source
+
+- Norman, D. — _The Design of Everyday Things_ (2013), feedback and system state visibility
+- Nielsen, J. — "Response Times: The 3 Important Limits" (1993), timing thresholds for loading states
+- Material Design — States documentation, https://m3.material.io/foundations/interaction/states
+- Facebook Engineering — "Building Skeleton Screens" (2017), perceived performance research
+- Vercel Design System — Deployment state 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/codex/design-state-design/skill.yaml

@@ -0,0 +1,36 @@
+name: design-state-design
+version: "1.0.0"
+description: UI state inventory — empty, loading, partial, error, success, offline, disabled, read-only, and how each state communicates system status
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-feedback-patterns
+  - design-loading-patterns
+  - design-empty-error-states
+stack_signals: []
+keywords:
+  - state-design
+  - empty-state
+  - loading
+  - error
+  - success
+  - offline
+  - disabled
+  - read-only
+  - UI-states
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []