@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/design-token-architecture/SKILL.md

@@ -0,0 +1,218 @@
+# Token Architecture
+
+> Token taxonomy covering primitive, semantic, and component tokens with naming conventions, aliasing chains, theme switching, and the token-to-code pipeline.
+
+## When to Use
+
+- Establishing a design token structure for a new design system
+- Migrating from hardcoded values (hex colors, pixel sizes) to a token-based architecture
+- Adding theme support (light/dark, brand variants, high-contrast) to an existing system
+- Resolving naming conflicts where the same token name means different things in different contexts
+- Building the pipeline that transforms design tokens into platform-specific code (CSS, iOS, Android)
+
+## Instructions
+
+Design tokens are the atomic values of a design system -- colors, spacing, typography, elevation, motion -- stored as platform-agnostic data. A well-architected token system has exactly three tiers, each with a distinct purpose and naming convention. Every visual value in your codebase should resolve to a token; any hardcoded value is a system escape.
+
+**The three-tier model:**
+
+1. **Primitive tokens** (also called "global" or "reference" tokens): Raw values with no semantic meaning. `color.blue.500: #2563EB`. They answer "what values exist?"
+2. **Semantic tokens** (also called "alias" or "decision" tokens): Purpose-driven aliases that reference primitives. `color.background.brand: {color.blue.500}`. They answer "what is this value for?"
+3. **Component tokens**: Scoped to a specific component, referencing semantic tokens. `button.background.primary: {color.background.brand}`. They answer "how does this component use the system?"
+
+Components consume component tokens. Component tokens alias semantic tokens. Semantic tokens alias primitives. This chain is the backbone of theme switching: swap the semantic-to-primitive mapping and every component updates.
+
+## Details
+
+### Primitive Token Layer
+
+Primitives define the complete palette of available values. They are exhaustive (every possible value is listed), value-based (named after what they are, not what they do), and stable (they rarely change after initial definition).
+
+**Color primitives** follow a numeric scale. Stripe uses 50-950 in 11 steps per hue:
+
+```
+color.blue.50:   #EFF6FF
+color.blue.100:  #DBEAFE
+color.blue.200:  #BFDBFE
+color.blue.300:  #93C5FD
+color.blue.400:  #60A5FA
+color.blue.500:  #3B82F6
+color.blue.600:  #2563EB
+color.blue.700:  #1D4ED8
+color.blue.800:  #1E40AF
+color.blue.900:  #1E3A8A
+color.blue.950:  #172554
+```
+
+**Spacing primitives** use a geometric or linear scale. Material Design 3 uses a 4px baseline:
+
+```
+spacing.0:    0px
+spacing.1:    4px
+spacing.2:    8px
+spacing.3:    12px
+spacing.4:    16px
+spacing.6:    24px
+spacing.8:    32px
+spacing.10:   40px
+spacing.12:   48px
+spacing.16:   64px
+```
+
+**Typography primitives** define the raw font properties:
+
+```
+font.family.sans:       "Inter", system-ui, sans-serif
+font.family.mono:       "JetBrains Mono", monospace
+font.weight.regular:    400
+font.weight.medium:     500
+font.weight.semibold:   600
+font.weight.bold:       700
+font.size.xs:           12px
+font.size.sm:           14px
+font.size.md:           16px
+font.size.lg:           18px
+font.size.xl:           20px
+font.size.2xl:          24px
+```
+
+Stripe uses `sohne-var` as their brand font primitive -- a single variable font token that enables weight and width modulation through font-variation-settings rather than multiple font-family tokens.
+
+### Semantic Token Layer
+
+Semantic tokens encode design decisions. They reference primitives but carry purpose in their names. The naming convention follows the CTI (Category-Type-Item) format, optionally extended with state and scale modifiers.
+
+**CTI format:** `{category}.{type}.{item}.{state?}.{scale?}`
+
+```
+color.background.default:         {color.neutral.50}      /* page background */
+color.background.subtle:          {color.neutral.100}     /* card background */
+color.background.brand:           {color.blue.600}        /* primary action */
+color.background.brand.hover:     {color.blue.700}        /* primary hover */
+color.background.danger:          {color.red.600}         /* destructive action */
+color.background.danger.hover:    {color.red.700}         /* destructive hover */
+color.text.default:               {color.neutral.900}     /* body text */
+color.text.subtle:                {color.neutral.500}     /* secondary text */
+color.text.on-brand:              {color.white}           /* text on brand bg */
+color.border.default:             {color.neutral.200}     /* standard border */
+color.border.focus:               {color.blue.500}        /* focus ring */
+```
+
+**Theme switching** works by remapping semantic tokens to different primitives:
+
+```
+/* Light theme */
+color.background.default: {color.neutral.50}
+color.text.default:       {color.neutral.900}
+
+/* Dark theme */
+color.background.default: {color.neutral.900}
+color.text.default:       {color.neutral.50}
+```
+
+GitHub Primer's token system uses this exact pattern. Their `--color-canvas-default` resolves to `#ffffff` in light mode and `#0d1117` in dark mode. They support 6 themes (light, light high contrast, light colorblind, dark, dark high contrast, dark dimmed) by maintaining 6 semantic-to-primitive mappings.
+
+### Component Token Layer
+
+Component tokens scope semantic decisions to individual components. They are optional for small systems (under 20 components) but essential for large ones.
+
+```
+button.color.background.primary:          {color.background.brand}
+button.color.background.primary.hover:    {color.background.brand.hover}
+button.color.background.primary.active:   {color.background.brand.active}
+button.color.background.secondary:        {color.background.subtle}
+button.color.text.primary:                {color.text.on-brand}
+button.color.text.secondary:              {color.text.default}
+button.spacing.padding.sm:                {spacing.2} {spacing.3}
+button.spacing.padding.md:                {spacing.2} {spacing.4}
+button.spacing.padding.lg:                {spacing.3} {spacing.6}
+button.border.radius:                     {border.radius.md}
+```
+
+Material Design 3 maps every component to semantic tokens. Their `FilledButton` uses `md.sys.color.primary` for background and `md.sys.color.on-primary` for text, creating a fully traceable chain from component surface to primitive value.
+
+### Token-to-Code Pipeline
+
+Tokens are authored in a format (JSON, YAML, or DTCG) and transformed into platform outputs.
+
+**DTCG (Design Tokens Community Group) format** is the emerging W3C standard:
+
+```json
+{
+  "color": {
+    "brand": {
+      "$type": "color",
+      "$value": "#2563EB",
+      "$description": "Primary brand color"
+    }
+  }
+}
+```
+
+**Transformation pipeline** (using Style Dictionary, Cobalt UI, or Tokens Studio):
+
+```
+tokens.json -> Style Dictionary -> CSS custom properties
+                                -> iOS Swift UIColor extensions
+                                -> Android XML resources
+                                -> Figma variables (via Tokens Studio)
+```
+
+IBM Carbon's token pipeline generates CSS custom properties, SCSS variables, and JavaScript objects from a single JSON source. Their `@carbon/colors` package exposes `$blue-60: #0f62fe` as SCSS and `--cds-blue-60: #0f62fe` as CSS.
+
+### Aliasing Chains and Debugging
+
+A token aliasing chain traces the resolution path: `component -> semantic -> primitive -> raw value`.
+
+```
+button.color.background.primary
+  -> color.background.brand
+    -> color.blue.600
+      -> #2563EB
+```
+
+**Maximum chain depth: 3 hops.** More than 3 levels of aliasing creates debugging pain. If tracing a button's color requires traversing 5 files, the architecture is over-layered.
+
+Salesforce Lightning provides a token resolution inspector in their developer tools that shows the full chain for any element, from component token to resolved CSS value.
+
+### Anti-Patterns
+
+**Semantic names that are actually descriptive.** Naming a token `color.background.blue` defeats the purpose of the semantic layer. "Blue" is a description of the value, not its purpose. When brand color changes from blue to purple, `color.background.blue` becomes a lie. Use `color.background.brand` instead.
+
+**Skipping the semantic layer.** Component tokens that directly reference primitives (`button.background: {color.blue.600}`) bypass the theme-switching mechanism. Every component token must go through a semantic token. Direct primitive references in components mean theme changes require updating every component token file.
+
+**Token explosion through over-specification.** Creating a unique token for every possible state combination: `button.primary.small.hover.disabled.background`. This produces thousands of tokens. Instead, compose from orthogonal dimensions: `button.background.primary.hover` + `button.size.sm.padding`. Shopify Polaris keeps their token count under 400 by using composable dimensions rather than combinatorial tokens.
+
+**Inconsistent scale naming.** Mixing `sm/md/lg` with `small/medium/large` with `1/2/3` across different token categories. Pick one scale convention and use it everywhere. GitHub Primer uses numeric scales for colors (0-9) and t-shirt sizes (sm, md, lg) for spacing -- but this split is intentional and documented, not accidental.
+
+**Orphaned primitives.** Primitive tokens that no semantic token references. If `color.orange.300` exists but nothing uses it, it adds cognitive load without value. Audit primitive usage quarterly. IBM Carbon's automated tooling flags primitives with zero semantic references.
+
+### Real-World Examples
+
+**Stripe** operates a 3-tier system where primitive tokens include their brand typeface `sohne-var` as a font primitive. Their semantic layer maps `--color-primary` through 6 themes including a high-contrast accessibility mode. Component tokens are generated per-component, keeping each component's token file under 30 lines.
+
+**Material Design 3** introduced dynamic color tokens that generate an entire theme from a single seed color using the HCT (Hue, Chroma, Tone) color space. A seed of `#6750A4` generates 5 tonal palettes (Primary, Secondary, Tertiary, Neutral, Neutral Variant), each with 13 tones (0, 10, 20...100), producing 65 primitive tokens that map to 29 semantic color roles.
+
+**GitHub Primer** maintains one of the most sophisticated token aliasing systems in production. Their `primer/primitives` package defines 6 complete theme mappings. Token values are authored in JSON, transformed via a custom build pipeline, and output as CSS custom properties and JavaScript objects. Their `color-contrast` checks run against every theme variant during CI.
+
+**Apple** uses platform-specific token sets: `systemBackground` resolves to `#FFFFFF` on iOS light, `#000000` on iOS dark, `#ECECEC` on macOS light, and `#1E1E1E` on macOS dark. The semantic name is identical across platforms, but the primitive mapping differs per platform and appearance combination.
+
+## Source
+
+W3C Design Tokens Community Group, _Design Tokens Format Module_ (Editor's Draft, 2024). Jina Anne, "Design Tokens for Dummies" (2019). Nathan Curtis, "Naming Tokens in Design Systems" (2020). Salesforce Lightning Design System documentation on token architecture.
+
+## 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-token-architecture/skill.yaml

@@ -0,0 +1,37 @@
+name: design-token-architecture
+version: '1.0.0'
+description: Token taxonomy covering primitive, semantic, and component tokens with naming conventions, aliasing, and theme switching
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-palette-construction
+  - design-type-scale
+  - design-atomic-design
+  - css-design-tokens
+stack_signals: []
+keywords:
+  - design-tokens
+  - primitive-tokens
+  - semantic-tokens
+  - component-tokens
+  - CTI
+  - aliasing
+  - theme-switching
+  - DTCG
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-transitions-timing/SKILL.md

@@ -0,0 +1,183 @@
+# Transitions & Timing
+
+> Temporal design — enter/exit asymmetry, stagger patterns, easing functions (ease-out for enter, ease-in for exit), duration by element size, interruptibility
+
+## When to Use
+
+- Implementing CSS transitions or animations for component state changes (show/hide, expand/collapse, enable/disable)
+- Deciding on enter and exit animation durations and easing for modals, drawers, tooltips, or dropdowns
+- Building stagger animations for lists, grids, or sequential content reveals
+- Designing interruptible animations where user input during a transition must be handled gracefully
+- Calibrating animation timing to element size (small icon vs. full-screen overlay)
+- Defining transition tokens for a design system that multiple teams will consume
+- Debugging transitions that feel "off" — too slow, too fast, or mechanically wrong
+- Any implementation requiring temporal coordination between two or more animated elements
+
+## Instructions
+
+1. **Apply enter/exit asymmetry as a default rule.** Enter transitions should be slightly longer than exit transitions. Rationale: entering elements bring new information the user needs to perceive and process, so they deserve more time. Exiting elements are being dismissed — the user has already decided they are done with that content, so the exit should be quick to confirm the dismissal. The concrete ratio is approximately 1.5:1 — if an enter is 300ms, the exit should be 200ms. Material Design 3 specifies this explicitly: a dialog enters at 400ms with `emphasized-decelerate` easing and exits at 200ms with `emphasized-accelerate` easing. A dropdown menu enters at 250ms and exits at 150ms. This asymmetry feels natural because it matches human attention patterns: we focus when something new appears, but we disengage quickly when something leaves.
+
+2. **Use ease-out (deceleration) for entering elements and ease-in (acceleration) for exiting elements.** This maps to physical intuition: an object arriving decelerates as it reaches its destination (a ball rolling to a stop); an object departing accelerates away from its resting position (a ball being thrown). The CSS mapping:
+   - **Enter:** `transition-timing-function: cubic-bezier(0.0, 0.0, 0.2, 1.0)` — starts fast, ends slow. Material Design's `emphasized-decelerate`.
+   - **Exit:** `transition-timing-function: cubic-bezier(0.4, 0.0, 1, 1)` — starts slow, ends fast. Material Design's `emphasized-accelerate`.
+   - **Move between positions:** `transition-timing-function: cubic-bezier(0.4, 0.0, 0.2, 1.0)` — accelerates then decelerates. Material Design's `standard` easing.
+     Reversing this (ease-in for enter, ease-out for exit) creates an uncanny feeling: elements hesitate before appearing and linger after being dismissed, as if the interface is reluctant to respond.
+
+3. **Scale duration to element size and travel distance.** Small elements that animate in place (toggle, checkbox, icon swap) need 100-150ms. Medium elements with moderate travel (card appearing, panel expanding, dropdown opening) need 200-350ms. Large elements with significant travel or surface area (modal entrance, page transition, drawer slide) need 300-500ms. The formula: `base_duration + (travel_distance_px * 0.8)ms`, clamped between 100ms and 500ms. For a dropdown menu appearing 200px below its trigger: `150 + (200 * 0.8) = 310ms`, rounded to the nearest token value of 300ms. Material Design scales by component category:
+   - Small: switches, checkboxes, radio buttons — 100ms
+   - Medium: cards, chips, text fields — 250ms
+   - Large: sheets, dialogs, navigation — 300-400ms
+   - Extra large: full-screen transitions — 400-500ms
+
+4. **Design stagger patterns with intention, not uniform delay.** Stagger — the time offset between consecutive element animations — creates a ripple effect that guides the eye. But uniform stagger (every item delayed by the same amount) creates a linear progression that feels mechanical. Better stagger patterns:
+   - **Decelerating stagger:** First items have shorter delays, later items have longer delays. Creates a "settling" effect. Delays: 0ms, 30ms, 70ms, 120ms, 180ms. The formula: `delay = index^1.5 * 15ms`.
+   - **Attention-first stagger:** The most important element animates first with no delay. Secondary elements stagger after. If a dialog has a title, body, and actions, the title enters immediately (0ms delay), body enters at +60ms, and actions enter at +120ms.
+   - **Spatial stagger:** Elements closest to the trigger point animate first. A dropdown opening from a button: items nearest the button appear first, items farthest appear last. This creates a "flow from source" effect that maintains spatial logic.
+     Linear's issue list uses decelerating stagger — the first few items appear rapidly, then the pace slows, giving the eye time to catch up. Total stagger sequence stays under 400ms regardless of list length; after 8-10 items, remaining items appear simultaneously.
+
+5. **Cap total stagger sequence duration.** A list of 50 items with 50ms stagger each would take 2,500ms to complete — unacceptable. Set a maximum total stagger duration of 300-400ms. For lists longer than ~8 items, apply stagger to the first 6-8 items, then reveal all remaining items simultaneously at the final stagger step. The user perceives the stagger effect from the first few items and their brain fills in the pattern for the rest. Implementation: `const delay = Math.min(index * staggerInterval, maxStaggerDelay)`.
+
+6. **Make all transitions interruptible by default.** If a user triggers a new action while an animation is in progress, the animation must not block that action. Three interruptibility strategies:
+   - **Jump to end:** The current animation instantly completes (jumps to final state), then the new animation begins. Simplest to implement. Use for short animations (under 200ms) where the jump is imperceptible.
+   - **Reverse from current position:** The animation reverses direction from its current progress point. Use for toggle-like interactions (open/close a dropdown). CSS transitions do this automatically when the triggering property changes mid-transition — the browser calculates a reversed curve from the current interpolated value.
+   - **Blend:** The current animation's target is updated and the motion curve recalculates from the current position to the new target. Spring animations do this naturally — you can change the target position of a spring mid-flight and it smoothly redirects. Framer Motion's `animate` prop handles this: updating the target value while a spring is active produces a smooth course correction without jarring stops or restarts.
+
+   The anti-pattern: queuing animations. If a user rapidly toggles a dropdown 5 times, they should not watch 5 sequential open/close animations play out. The final state should resolve within one animation cycle of the last input.
+
+7. **Use `will-change` and compositor-only properties for jank-free transitions.** Transitions that animate `transform` and `opacity` run on the compositor thread and never cause layout or paint jank. Transitions that animate `width`, `height`, `top`, `left`, `margin`, `padding`, `border-width`, or `box-shadow` trigger layout recalculation per frame and will drop frames on mid-range devices. Decision procedure:
+   - **Position change:** Use `transform: translateX/Y()` not `left/top`
+   - **Size change:** Use `transform: scale()` not `width/height` where possible. When actual dimensional change is needed (content reflow), animate `max-height` with `overflow: hidden` as a compromise.
+   - **Visibility change:** Use `opacity` with `visibility: hidden` (at opacity 0) for proper accessibility — `opacity: 0` alone leaves the element focusable and clickable.
+   - **Color change:** Animate `background-color` and `color` directly — these trigger paint but not layout, and paint is fast for small elements.
+     Apply `will-change: transform, opacity` to elements that will animate, but remove it after the animation completes to free GPU memory. Do not apply `will-change` to more than 5-10 elements simultaneously.
+
+8. **Define transition tokens as a system contract.** Transition tokens encode duration, easing, and delay as named values that all teams consume. A complete token system:
+
+   ```css
+   :root {
+     /* Durations */
+     --transition-instant: 0ms;
+     --transition-fast: 100ms;
+     --transition-normal: 200ms;
+     --transition-moderate: 300ms;
+     --transition-slow: 400ms;
+     --transition-deliberate: 500ms;
+
+     /* Easing */
+     --ease-enter: cubic-bezier(0, 0, 0.2, 1);
+     --ease-exit: cubic-bezier(0.4, 0, 1, 1);
+     --ease-move: cubic-bezier(0.4, 0, 0.2, 1);
+     --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+     /* Composed transitions */
+     --transition-enter-normal: var(--transition-normal) var(--ease-enter);
+     --transition-exit-fast: var(--transition-fast) var(--ease-exit);
+     --transition-move-moderate: var(--transition-moderate) var(--ease-move);
+   }
+   ```
+
+   Teams should never write raw `transition: 237ms cubic-bezier(0.68, -0.55, 0.27, 1.55)`. They should write `transition: opacity var(--transition-enter-normal), transform var(--transition-enter-normal)`. This ensures temporal coherence — all elements in the system share the same timing vocabulary.
+
+## Details
+
+### Enter/Exit Asymmetry: The Full Decision Table
+
+| Component       | Enter Duration | Enter Easing          | Exit Duration | Exit Easing           | Notes                                |
+| --------------- | -------------- | --------------------- | ------------- | --------------------- | ------------------------------------ |
+| Tooltip         | 150ms          | ease-out              | 75ms          | ease-in               | Instant feel. Exit is half of enter. |
+| Dropdown menu   | 250ms          | emphasized-decelerate | 150ms         | emphasized-accelerate | Items stagger 30ms on enter only.    |
+| Modal dialog    | 400ms          | emphasized-decelerate | 200ms         | emphasized-accelerate | Scrim fades independently (300ms).   |
+| Side drawer     | 350ms          | emphasized-decelerate | 250ms         | emphasized-accelerate | Slides from edge; scrim fades 300ms. |
+| Bottom sheet    | 400ms          | spring (damping 0.85) | 200ms         | ease-in               | Spring overshoot on enter only.      |
+| Toast/snackbar  | 250ms          | ease-out              | 200ms         | ease-in               | Enters from bottom, exits to bottom. |
+| Page transition | 300ms          | standard              | 200ms         | accelerate            | Outgoing fades; incoming slides.     |
+| Popover         | 200ms          | ease-out              | 100ms         | ease-in               | Scale from 95% to 100% on enter.     |
+
+The pattern: exits are 50-60% of enter duration. Exits never have spring or overshoot easing. Exits never stagger — all exiting elements leave simultaneously for a clean, decisive dismissal.
+
+### Stagger Mathematics
+
+**Linear stagger:** `delay(i) = i * interval`. Interval of 50ms for 10 items = 500ms total. Simple but monotonous.
+
+**Decelerating stagger:** `delay(i) = (i^exponent) * baseInterval`. With exponent 1.4 and base 20ms:
+
+- Item 0: 0ms
+- Item 1: 20ms
+- Item 2: 53ms
+- Item 3: 94ms
+- Item 4: 141ms
+- Item 5: 194ms
+
+Total: 194ms for 6 items. The visual effect: a burst of items followed by a settling rhythm. This matches human perception — the first few items establish the pattern, then the brain predicts the rest.
+
+**Capped stagger:** `delay(i) = Math.min(i * interval, maxDelay)`. With interval 40ms and max 280ms: items 0-7 stagger normally (0ms to 280ms), items 8+ all appear at 280ms. Prevents long lists from feeling like a progress bar.
+
+**Reverse stagger for exits:** When dismissing a staggered list, reverse the order — last item disappears first, first item disappears last. This creates a "gathering" effect that mirrors the "spreading" effect of the entrance. Apple's Launchpad app grid uses reverse stagger on close: apps in the bottom-right corner disappear first, cascading up-left until the top-left app disappears last.
+
+### Interruptibility in Practice
+
+**CSS Transition Reversal.** When a CSS property changes mid-transition, the browser automatically reverses the transition from the current interpolated value. But the reversal timing is calculated based on how far the transition has progressed, not the original duration. If a 300ms ease-out transition is 200ms in (67% complete), and the property reverts, the browser calculates a reversed 200ms transition (proportional to remaining visual change). This produces natural-feeling interruptions without any JavaScript.
+
+**Spring Interruption (Framer Motion/React Spring).** Spring animations are inherently interruptible. When the target value changes, the spring redirects from its current position and velocity toward the new target. This produces smooth direction changes without any visual discontinuity. The spring does not stop-and-restart; it curves toward the new target. This is why spring animations feel more responsive than duration-based animations in interactive contexts — they handle interruption gracefully by default.
+
+**JavaScript-Driven Interruption.** For imperative animations (GSAP, anime.js, Web Animations API), implement a cancellation pattern: before starting a new animation, call `currentAnimation.cancel()` or `currentAnimation.finish()`, read the element's current computed style, and start the new animation from those computed values. Never animate from a hard-coded initial value when interrupting — always animate from the element's current visual state.
+
+### Duration Perception and the Kriz Threshold
+
+Research by Miller (1968) and Card, Moran, and Newell (1983) established three perceptual thresholds for interface response:
+
+- **100ms:** The limit of "instantaneous." Feedback within 100ms feels like direct manipulation. Under this threshold, no transition is needed — instant state change is appropriate.
+- **300ms:** The limit of "connected." The user still perceives the animation as a direct response to their action. Most UI transitions should complete within this window.
+- **1000ms:** The limit of "flow." Beyond 1 second, the user's attention shifts and they begin thinking about whether the system is working. Animations longer than 1 second need progress indicators or are simply too long.
+
+Practical implication: feedback animations (button press, toggle, hover) must complete within 100-200ms. Navigational transitions (page change, panel slide) must complete within 200-400ms. No user-initiated animation should exceed 500ms. The only acceptable animations above 500ms are system-initiated sequences (loading states, data refresh animations) where the duration matches actual processing time.
+
+### Anti-Patterns
+
+1. **Symmetric Enter/Exit.** Using identical duration and easing for enter and exit transitions. A modal that takes 400ms to appear and 400ms to disappear feels sluggish on close — the user has already mentally moved on, but the interface is still animating. The fix: cut exit duration to 50-60% of enter duration and use accelerate easing on exit. Material Design is explicit: "Exit transitions should be faster than enter transitions because the user no longer needs to focus on the leaving element."
+
+2. **Infinite Stagger.** Applying stagger delay to every item in a long list without capping. A 100-item list with 50ms stagger takes 5 seconds to fully render. By item 30, the user has already scrolled past the animation and sees items popping in late, which looks like a loading bug rather than a design choice. Fix: cap stagger to the first 6-8 visible items (300-400ms total), and render remaining items instantly.
+
+3. **Blocking Transitions.** Disabling pointer events or keyboard input during a transition, forcing the user to wait for the animation to complete. A drawer that takes 350ms to open and prevents all interaction until fully open adds 350ms of dead time to every navigation action. Across 20 navigation events per session, that is 7 seconds of staring at an animation. Fix: enable interaction on the destination surface as soon as it becomes visually accessible — typically at 40-60% of the transition progress. Linear's command palette is interactable before its entrance animation completes.
+
+4. **Duration Guessing.** Choosing arbitrary duration values (137ms, 283ms, 421ms) based on "what feels right" without using a token scale. These magic numbers drift across components and create temporal incoherence — no two animations in the system share the same timing personality. Fix: define a duration scale (100, 150, 200, 250, 300, 400, 500ms) and snap every animation to the nearest step. Consistent durations create a unified temporal feel.
+
+5. **Easing-Property Mismatch.** Using `ease-in-out` on enter/exit transitions where asymmetric easing is correct, or using `ease-out` on exit transitions where `ease-in` is correct. This creates subtle but perceptible wrongness — elements hesitate when they should depart swiftly, or decelerate when they should accelerate away. Fix: create a decision table (see above) and enforce it through token usage. If the token system only provides `--ease-enter` and `--ease-exit`, developers cannot accidentally use the wrong curve.
+
+### Real-World Examples
+
+**Material Design 3 Container Transform.** When a card expands into a full-screen detail view, MD3 uses a precisely choreographed transition: the card's border-radius animates from 12px to 0px over 300ms (`emphasized`), its bounds expand to the viewport using `transform: scale()` to avoid layout animation, and the card's content crossfades to the detail content during the middle 60% of the transition (fade out from 100ms-180ms, fade in from 180ms-280ms). The scrim behind the expanding card fades in over the first 150ms. The entire transition is interruptible — swiping down during the expansion reverses the animation from its current state using spring physics.
+
+**Linear's Keyboard Navigation Transitions.** When navigating Linear's issue list with arrow keys, the selection highlight moves between items with a 120ms `ease-out` transition on `transform: translateY()`. The transition is fast enough to keep pace with rapid keyboard input — pressing the down arrow 5 times in quick succession moves the highlight smoothly through 5 items without queuing. This works because each new keystroke interrupts the current transition (CSS automatic reversal), and 120ms is short enough that the interruption is visually clean. The issue detail panel on the right updates with a 200ms crossfade, slightly trailing the selection change, which reinforces the cause-and-effect relationship.
+
+**Vercel's Deploy Detail Cascade.** Vercel's deployment detail page uses a cascade entrance: the header (deployment URL, status badge) enters first (0ms delay, 200ms duration), the build log section enters second (80ms delay, 200ms duration), and the function/edge list enters third (140ms delay, 200ms duration). Total cascade: 340ms from first to last. Each section uses `ease-out` for its entrance and a slight upward slide (8px `translateY` to 0). The stagger creates a top-to-bottom reading flow that matches the natural scan direction. On exit (navigating away), all sections fade out simultaneously in 150ms with no stagger — the exit is decisive.
+
+**Apple's Sheet Presentation Spring.** iOS's sheet presentation (the card that slides up from the bottom for modal content) uses a spring animation with `mass: 1, stiffness: 300, damping: 0.85`. The sheet slides up with one subtle overshoot (approximately 3% past its resting position) then settles. The dismissal is not a spring — it uses a `250ms ease-in` slide downward, matching the exit asymmetry principle. During the spring entrance, the sheet is already interactive — the user can tap buttons inside the sheet before the spring has fully settled. If the user grabs the sheet's drag handle during the entrance animation, the spring redirects to follow the user's finger, making the transition feel like a physical object being caught mid-flight.
+
+## Source
+
+- Material Design 3 — Motion and transitions documentation, https://m3.material.io/styles/motion
+- CSS Specification — `transition` shorthand and `transition-timing-function`, https://www.w3.org/TR/css-transitions-1/
+- Card, S., Moran, T., Newell, A. — _The Psychology of Human-Computer Interaction_ (1983), response time thresholds
+- Miller, R. — "Response time in man-computer conversational transactions" (1968), perceptual limits
+- Apple Human Interface Guidelines — Sheet presentation and spring animation parameters
+- Web Animations API — https://www.w3.org/TR/web-animations-1/
+- Framer Motion — Spring physics and interruptible animation documentation
+- GSAP — Timeline sequencing and interruption patterns
+- Nielsen, J. — "Response Times: The 3 Important Limits" (1993, updated from 1968 research)
+
+## 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-transitions-timing/skill.yaml

@@ -0,0 +1,35 @@
+name: design-transitions-timing
+version: "1.0.0"
+description: Temporal design — enter/exit asymmetry, stagger patterns, easing functions (ease-out for enter, ease-in for exit), duration by element size, interruptibility
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-motion-principles
+  - design-micro-interactions
+stack_signals: []
+keywords:
+  - transitions
+  - timing
+  - easing
+  - stagger
+  - enter-exit
+  - asymmetry
+  - interruptibility
+  - duration
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,157 @@
+# Type Scale
+
+> Mathematical type scales — modular, major third, perfect fourth, golden ratio, custom scales, and when each is appropriate
+
+## When to Use
+
+- Establishing font sizes for a new design system or component library
+- Auditing an existing system that has accumulated arbitrary font sizes
+- Choosing heading sizes that create clear visual hierarchy without guesswork
+- Adapting a type scale for different contexts (marketing site vs data dashboard)
+- Translating a designer's type ramp into a developer token system
+
+## Instructions
+
+1. **Start with a base size.** The base size is the body text size — the most frequently read text in your interface. For web, the standard is **16px** (1rem). Do not change this without strong justification; browsers default to 16px, accessibility tools assume it, and the entire rem system depends on it.
+
+2. **Choose a ratio based on content density.** A type scale multiplies the base size by a ratio at each step. The ratio determines how dramatically sizes increase between levels:
+
+   | Ratio | Name             | Factor     | Use Case                              |
+   | ----- | ---------------- | ---------- | ------------------------------------- |
+   | 1.067 | Minor second     | Tight      | Data-dense dashboards, admin panels   |
+   | 1.125 | Major second     | Compact    | Documentation, technical interfaces   |
+   | 1.200 | Minor third      | Moderate   | General-purpose web applications      |
+   | 1.250 | Major third      | Balanced   | Content sites, blogs, marketing       |
+   | 1.333 | Perfect fourth   | Expressive | Editorial, storytelling               |
+   | 1.414 | Augmented fourth | Dramatic   | Landing pages, single-message layouts |
+   | 1.500 | Perfect fifth    | Bold       | Hero sections, splash screens         |
+   | 1.618 | Golden ratio     | Extreme    | High-impact single headlines only     |
+
+   **Decision procedure**: Count the distinct hierarchy levels visible on your densest page. If you need 6+ levels to remain distinguishable, use a tighter ratio (1.125-1.200). If you need only 3-4 levels, use a wider ratio (1.250-1.414).
+
+3. **Generate the scale.** From a 16px base with a major third ratio (1.250):
+
+   | Step | Calculation   | Value | Rounded | Token Name |
+   | ---- | ------------- | ----- | ------- | ---------- |
+   | -2   | 16 / 1.250^2  | 10.24 | 10px    | text-xs    |
+   | -1   | 16 / 1.250    | 12.80 | 13px    | text-sm    |
+   | 0    | 16 \* 1.000   | 16.00 | 16px    | text-base  |
+   | +1   | 16 \* 1.250   | 20.00 | 20px    | text-lg    |
+   | +2   | 16 \* 1.250^2 | 25.00 | 25px    | text-xl    |
+   | +3   | 16 \* 1.250^3 | 31.25 | 31px    | text-2xl   |
+   | +4   | 16 \* 1.250^4 | 39.06 | 39px    | text-3xl   |
+   | +5   | 16 \* 1.250^5 | 48.83 | 49px    | text-4xl   |
+
+   Round to whole pixels for simplicity. The mathematical relationship matters more than exact precision — it creates **visual rhythm** that the eye perceives as coherent.
+
+4. **Map scale steps to semantic roles.** Do not expose raw step numbers to consumers. Map each step to a purpose:
+   - **body** (step 0): paragraphs, descriptions, form labels
+   - **body-small** (step -1): captions, footnotes, metadata
+   - **heading-3** (step +1 or +2): subsection headings
+   - **heading-2** (step +2 or +3): section headings
+   - **heading-1** (step +3 or +4): page titles
+   - **display** (step +4 or +5): hero headlines, marketing
+
+5. **Constrain the total number of sizes.** A well-functioning type scale has **6-10 distinct sizes**. Fewer than 6 limits hierarchy expression. More than 10 creates decision paralysis — designers pick arbitrary sizes when the options are too numerous.
+
+6. **Validate the scale against real content.** Set actual UI text (not "Lorem ipsum") at each scale step. Check:
+   - Is each step visually distinguishable from its neighbors?
+   - Are the smallest sizes still readable (minimum 11px on screen, 14px on mobile)?
+   - Are the largest sizes not overwhelming their containers?
+   - Does the scale produce reasonable line lengths when combined with your layout grid?
+
+## Details
+
+### How Real Design Systems Build Scales
+
+**Material Design 3 Type Scale**
+Material Design 3 defines 15 named styles across 5 roles, using a custom scale built on Roboto Flex:
+
+| Role     | Size | Small | Medium | Large |
+| -------- | ---- | ----- | ------ | ----- |
+| Display  | -    | 36px  | 45px   | 57px  |
+| Headline | -    | 24px  | 28px   | 32px  |
+| Title    | -    | 14px  | 16px   | 22px  |
+| Body     | -    | 12px  | 14px   | 16px  |
+| Label    | -    | 11px  | 12px   | 14px  |
+
+This is not a strict mathematical scale — it is a **custom scale** tuned to Material's specific hierarchy needs. The ratios between adjacent sizes vary by role. This is valid when you have the design expertise to tune by eye, but a mathematical scale provides better defaults for most teams.
+
+**Tailwind CSS Type Scale**
+Tailwind uses a roughly major-second progression with manual adjustments:
+
+- `text-xs`: 12px, `text-sm`: 14px, `text-base`: 16px, `text-lg`: 18px
+- `text-xl`: 20px, `text-2xl`: 24px, `text-3xl`: 30px, `text-4xl`: 36px
+- `text-5xl`: 48px, `text-6xl`: 60px, `text-7xl`: 72px, `text-8xl`: 96px, `text-9xl`: 128px
+
+The ratios tighten at small sizes (14/12 = 1.167) and widen at large sizes (128/96 = 1.333). This is deliberate — small size differences need less separation to be distinguishable, while large sizes need more dramatic jumps.
+
+**Stripe's Constrained Scale**
+Stripe's dashboard uses a deliberately minimal type scale:
+
+- Body: 14px (weight 400) and 16px (weight 300-400)
+- Headings: 20px, 24px, 28px (all weight 300)
+- Display hero: 56px (weight 300, letter-spacing -1.4px)
+- Only 6-7 distinct sizes total — extreme constraint creates extreme consistency
+
+**Vercel's Minimal Scale**
+Vercel limits their primary scale to approximately 5 core sizes:
+
+- 14px (small/meta), 16px (body), 20px (subheading), 24px (heading), 32px (page title)
+- This restriction forces hierarchy through weight, color, and spacing rather than size alone
+
+### Custom Scales and When to Break the Math
+
+Mathematical scales are starting points, not laws. Legitimate reasons to deviate:
+
+- **Rounding for the pixel grid**: 31.25px rounds to 32px — this is fine and expected
+- **Accessibility minimums**: if the scale produces a size below 11px, clamp it to 11px
+- **Specific use cases**: a data table might need 13px that does not exist in your scale — add it as a named exception, not a new scale step
+- **Responsive adaptation**: mobile scales often use a tighter ratio than desktop (1.125 mobile vs 1.250 desktop) to prevent headings from dominating small screens
+
+### Anti-Patterns
+
+1. **Too many sizes.** When a system accumulates 15+ font sizes (11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 28, 32, 36, 48...), every pixel difference becomes a choice that designers and developers make inconsistently. Audit your CSS: if `font-size` has more than 10 unique values, your scale is broken. Collapse to a mathematical scale and map existing values to the nearest step.
+
+2. **Arbitrary sizes with no mathematical relationship.** A scale of 14px, 17px, 19px, 23px has no governing ratio — each jump is different (1.214, 1.118, 1.211). The eye perceives this inconsistency as visual noise. Run your sizes through the formula `ratio = size_n / size_n-1` — if the ratios vary by more than 0.05, you do not have a scale, you have a list.
+
+3. **One ratio for all contexts.** The golden ratio (1.618) produces a stunning headline but by step +4, your largest heading is 111px from a 16px base. Data dashboards using a perfect fifth (1.500) will have headings that overpower their content. Match the ratio to content density: tight for dense UI, wide for sparse marketing.
+
+4. **Ignoring the base size.** Teams that change the base from 16px to 14px "to fit more content" cascade problems throughout the system — rem calculations break, browser zoom behavior changes, and body text drops below comfortable reading size. If text feels too large, the problem is usually line-length or spacing, not font size.
+
+### Real-World Examples
+
+**Building a SaaS Dashboard Scale (Major Second, 1.125)**
+Starting from 16px: 11px, 13px, 14px, 16px, 18px, 20px, 23px, 25px. Eight sizes. The tight ratio keeps headings from overwhelming dense data tables. Heading-1 at 25px is only 1.56x the body size — appropriate for a screen that may have 4 data tables visible simultaneously.
+
+**Building a Marketing Landing Page Scale (Perfect Fourth, 1.333)**
+Starting from 16px: 12px, 16px, 21px, 28px, 38px, 50px, 67px. Seven sizes. The dramatic ratio creates clear separation between the hero headline (67px), section headings (38px), and body text (16px). Each level is unmistakable at a glance — essential when the user is scanning, not reading.
+
+**Migrating from Ad-Hoc to Systematic**
+A real-world audit might find these font sizes in production CSS: 10, 11, 12, 13, 14, 15, 16, 18, 20, 22, 24, 28, 32, 40, 48, 64. That is 16 sizes. Collapse to a minor-third scale (1.200) from 16px base: 11, 13, 16, 19, 23, 28, 33, 40. Map each existing size to its nearest scale value. Document exceptions. The result: 8 sizes replacing 16, with mathematical coherence.
+
+## Source
+
+- Bringhurst, Robert. _The Elements of Typographic Style_, version 4.0 — on proportional systems
+- Brown, Tim. "More Meaningful Typography" — A List Apart, modular scale theory
+- type-scale.com — interactive scale generator by Jeremy Church
+- Material Design 3 Type System — https://m3.material.io/styles/typography/type-scale-tokens
+- Tailwind CSS font-size documentation — https://tailwindcss.com/docs/font-size
+
+## Process
+
+1. **Evaluate** — Audit the current font sizes in the project. Count unique values. Determine if a mathematical relationship exists. Assess content density to choose an appropriate ratio.
+2. **Apply** — Generate a scale from the chosen base and ratio. Map steps to semantic token names. Replace arbitrary sizes with the nearest scale value.
+3. **Verify** — Confirm that each scale step is visually distinguishable, no size falls below readability minimums, and the total size count is between 6 and 10.
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides type scale theory and calculation methods to guide font-size token creation. Use these principles when defining `--font-size-*` custom properties, Tailwind `fontSize` config, or any design token system. Cross-reference with `design-responsive-type` for viewport-adaptive scaling.
+
+## Success Criteria
+
+- Font sizes follow a consistent mathematical ratio (variation < 0.05 between steps)
+- Total unique font sizes in the system are between 6 and 10
+- Every font size maps to a named semantic token (no raw pixel values in components)
+- The smallest size is at least 11px on desktop and 14px on mobile
+- The chosen ratio matches the content density (tight for data, wide for marketing)