@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/design-naming-conventions/SKILL.md

@@ -0,0 +1,200 @@
+# Naming Conventions
+
+> Design system nomenclature for semantic and descriptive names, color naming, size naming, and maintaining consistent vocabulary across design and code.
+
+## When to Use
+
+- Establishing naming patterns for a new design system's tokens, components, or variants
+- Resolving naming inconsistencies between design files (Figma) and code (React/CSS)
+- Renaming tokens or components during a system refactor without breaking consumers
+- Debating whether a color should be called "blue-500" or "brand-primary" (the answer is both, at different layers)
+- Writing a naming convention guide for contributors to follow
+
+## Instructions
+
+Names are the primary interface of a design system. A developer reads a name and must immediately understand what the thing does, where it belongs, and how it relates to other things. Bad names create ambiguity that compounds across hundreds of components and thousands of tokens.
+
+**The naming decision procedure:**
+
+1. **Determine the layer.** Is this a primitive (named by what it IS), a semantic token (named by what it DOES), or a component (named by what it RENDERS)?
+2. **Apply the layer's convention.** Primitives use descriptive names. Semantic tokens use purpose names. Components use noun-based names.
+3. **Check for collisions.** Does this name conflict with or shadow an existing name in the system? Search the token and component registries.
+4. **Check for lies.** Will this name become inaccurate if the underlying value changes? If `color-blue-primary` is renamed when the brand shifts to purple, it was a bad name from the start.
+5. **Check for ambiguity.** Can two reasonable people disagree about what this name refers to? If yes, the name is too vague.
+
+## Details
+
+### Descriptive vs Semantic Naming
+
+The core distinction in design system naming is between descriptive names (what something IS) and semantic names (what something is FOR).
+
+**Descriptive names** state the literal value or appearance:
+
+```
+color.blue.500          /* describes the hue and lightness */
+font.size.16            /* describes the pixel value */
+spacing.8               /* describes the pixel value */
+border.radius.4         /* describes the pixel value */
+```
+
+**Semantic names** state the purpose or role:
+
+```
+color.background.brand       /* describes the role in the interface */
+font.size.body              /* describes where it is used */
+spacing.inline.md           /* describes the spatial relationship */
+border.radius.control       /* describes what it rounds */
+```
+
+Both are necessary. Primitives use descriptive names because their purpose is to catalog available values. Semantic tokens use purpose names because their purpose is to encode decisions. A system with only descriptive names cannot theme. A system with only semantic names cannot be audited for palette coverage.
+
+**IBM Carbon** maintains both layers explicitly. Their SCSS exposes `$blue-60: #0f62fe` (descriptive primitive) and `$interactive-01: $blue-60` (semantic alias). Developers use `$interactive-01`; the descriptive name exists only in the token definition file.
+
+### Color Naming
+
+Color naming is the most contentious area of design system nomenclature. The decision tree:
+
+**Primitive color names** use hue + numeric scale:
+
+```
+red.50, red.100, red.200 ... red.900, red.950
+blue.50, blue.100, blue.200 ... blue.900, blue.950
+neutral.50, neutral.100 ... neutral.950
+```
+
+The numeric scale represents lightness, not importance. 50 is lightest, 950 is darkest. This convention (used by Tailwind, Radix, Stripe, GitHub Primer) is the de facto standard. Avoid inventing custom scales (1-10, light/medium/dark) unless your system has a documented reason.
+
+**Semantic color names** use role-based categories:
+
+| Category       | Examples                                                          | Purpose         |
+| -------------- | ----------------------------------------------------------------- | --------------- |
+| `background.*` | `background.default`, `background.subtle`, `background.brand`     | Surface colors  |
+| `text.*`       | `text.default`, `text.subtle`, `text.disabled`, `text.on-brand`   | Text foreground |
+| `border.*`     | `border.default`, `border.focus`, `border.error`                  | Edge colors     |
+| `icon.*`       | `icon.default`, `icon.subtle`, `icon.brand`                       | Icon foreground |
+| `status.*`     | `status.success`, `status.warning`, `status.error`, `status.info` | Feedback colors |
+
+GitHub Primer uses `--color-fg-default` (foreground/text), `--color-canvas-default` (background), `--color-border-default`. The `fg`/`canvas`/`border` prefix groups by surface type, and `default`/`subtle`/`muted`/`emphasis` suffix indicates prominence.
+
+**What NOT to name colors:**
+
+- Avoid emotion words: `color.happy`, `color.calm`. These are subjective and culture-dependent.
+- Avoid use-case specifics at the semantic layer: `color.sidebar-background`. This belongs in component tokens.
+- Avoid compound descriptors: `color.light-blue-ish`. If it does not fit a hue name, define a new hue.
+
+### Size Naming
+
+Size naming must be consistent across all dimensions: component sizes, spacing, typography, and icon sizes.
+
+**T-shirt sizes** are the most common convention:
+
+```
+xs, sm, md, lg, xl, 2xl, 3xl
+```
+
+**Rules for t-shirt size scales:**
+
+- `md` is always the default. If a component has a `size` prop, omitting it should give `md`.
+- Never go below `xs` or above `3xl`. If you need more, your scale is too granular.
+- The scale must be arithmetic or geometric, not arbitrary. Atlassian uses: xs=24, sm=32, md=40, lg=48 (linear +8). Material uses: sm=36, md=40, lg=56 (non-linear, justified by touch target research).
+
+**Numeric scales** are used when t-shirt sizes are insufficient:
+
+```
+spacing.0, spacing.1, spacing.2, spacing.3, spacing.4, spacing.6, spacing.8
+```
+
+These reference a base unit. If `spacing.1 = 4px`, then `spacing.4 = 16px`. The convention: the number IS the multiplier, not the pixel value. Tailwind uses `p-4` = `16px` (4 \* 4px base). Material uses `dp` units directly.
+
+**Never mix conventions within a category.** If component sizes use t-shirt sizes, all components use t-shirt sizes. If spacing uses numeric scales, all spacing uses numeric scales. Shopify Polaris uses t-shirt sizes for components and numeric tokens for spacing -- this is a clean split across categories, not mixing within one.
+
+### Cross-Discipline Vocabulary
+
+Design systems span design tools (Figma), code (React/CSS), and documentation. Names must survive the translation across all three.
+
+**The vocabulary alignment checklist:**
+
+1. **Figma component name = Code component name.** If Figma calls it "Action Card" and code calls it `InteractiveCard`, contributors will use the wrong name in discussions. Shopify Polaris enforces 1:1 Figma-to-code naming: `Button/Primary/Medium` in Figma maps to `<Button variant="primary" size="medium">`.
+2. **Figma variant properties = Code props.** Figma's variant axis "Type: Primary | Secondary | Ghost" must map to the code prop `variant: 'primary' | 'secondary' | 'ghost'`, not `type` or `appearance` or `kind`.
+3. **Token names are identical in Figma and code.** If Figma uses `color/background/brand` and code uses `--color-bg-brand`, the abbreviation `bg` vs `background` creates confusion. Pick one and enforce it everywhere.
+
+**Vocabulary register (maintain in your documentation):**
+
+| Concept          | Accepted Term | Rejected Alternatives                 | Rationale                                                     |
+| ---------------- | ------------- | ------------------------------------- | ------------------------------------------------------------- |
+| Visual form      | `variant`     | `type`, `kind`, `appearance`, `style` | `type` conflicts with HTML `type`; `style` conflicts with CSS |
+| Prominence level | `emphasis`    | `priority`, `weight`, `level`         | Aligns with Material Design terminology                       |
+| Size             | `size`        | `dimension`, `scale`                  | Most universally understood                                   |
+| Disabled state   | `disabled`    | `inactive`, `locked`, `frozen`        | HTML native attribute name                                    |
+| Loading state    | `loading`     | `pending`, `busy`, `processing`       | Most common in design system literature                       |
+
+Atlassian maintains a public glossary of over 60 terms that all contributors must use. Their glossary explicitly lists rejected synonyms for each term.
+
+### Component Naming
+
+Component names should be nouns that describe what the component renders, not what it does.
+
+**Good names:** `Button`, `Card`, `Dialog`, `Avatar`, `Badge`, `Tooltip`, `DataTable`
+**Bad names:** `Clickable`, `Displayable`, `Openable`, `Toggleable`
+
+**Compound component naming** uses dot notation or directory nesting:
+
+```
+/* Dot notation (React) */
+Dialog.Header, Dialog.Body, Dialog.Footer
+
+/* Directory nesting (file system) */
+Dialog/
+  DialogHeader.tsx
+  DialogBody.tsx
+  DialogFooter.tsx
+  index.tsx        /* exports Dialog with sub-components attached */
+```
+
+**Prefix conventions for sub-components:**
+
+- Same-component children: `Dialog.Header` (parent name as namespace)
+- Shared utility components: `VisuallyHidden`, `Portal`, `FocusTrap` (descriptive, no namespace)
+- Layout components: `Stack`, `Inline`, `Grid`, `Box` (abstract spatial nouns)
+
+### Anti-Patterns
+
+**Abbreviation inconsistency.** Using `bg` in some tokens and `background` in others, `sm` in some contexts and `small` in others. Every abbreviation must be listed in the vocabulary register and used uniformly. GitHub Primer uses `fg` (foreground) consistently across 200+ tokens -- it appears abbreviated everywhere or nowhere.
+
+**Semantic names that encode visual properties.** Naming a token `color.text.bold` (a visual treatment) instead of `color.text.emphasis` (a semantic role). When the emphasis style changes from bold to a different color, the name `bold` becomes misleading. Semantic names must survive implementation changes.
+
+**Platform-specific naming in shared tokens.** Naming a token `ios-blue` or `android-elevation` in the shared token file. Platform-specific mappings belong in the transform layer, not the token definition. The token is `color.background.brand`; the iOS-specific hex value is a build artifact.
+
+**Verb-based component names.** `ShowDetails`, `ToggleMenu`, `LoadData`. Components are things (nouns), not actions (verbs). The action is what the component enables; the name is what it is. `ToggleMenu` should be `Menu` with an `open` state. `ShowDetails` should be `Disclosure` or `Accordion`.
+
+**Numbered variants without meaning.** `button-1`, `button-2`, `button-3` in Figma or `CardV2`, `NewCard`, `CardFinal` in code. These names carry no information about what differs between them. If the distinction is not worth naming, it is not worth having.
+
+### Real-World Examples
+
+**Salesforce Lightning** maintains a naming matrix that maps every concept to four representations: Figma layer name, CSS class, design token, and documentation label. Their `SLDS` prefix (`slds-button`, `slds-card`) acts as a namespace to avoid collisions with consumer code. Component variants use BEM-like modifiers: `slds-button_brand`, `slds-button_neutral`, `slds-button_destructive`.
+
+**IBM Carbon** uses a strict CTI (Category-Type-Item) convention across all tokens. Colors follow `$carbon--{category}-{usage}-{property}-{variant}`: `$carbon--interactive-01` (primary interactive color), `$carbon--ui-background` (page background), `$carbon--text-01` (primary text). The numbered suffix (01, 02, 03) indicates prominence hierarchy within a category.
+
+**Shopify Polaris** aligns Figma and code naming with a published 1:1 mapping table. Their component names are plain English nouns: `Button`, `Card`, `Modal`, `Banner`, `Badge`. Variant names are adjective-like: `primary`, `critical`, `warning`, `success`. Size names use t-shirt convention without exception: `slim`, `medium`, `large` (they use `slim` instead of `small` to avoid confusion with type sizes).
+
+**Material Design 3** prefixes all tokens with `md.sys.` (system-level) or `md.comp.` (component-level), creating an unambiguous namespace. Color roles use a `on-` prefix for foreground-on-surface pairs: `md.sys.color.primary` (surface) and `md.sys.color.on-primary` (content on that surface). This pairing convention eliminates guesswork about which text color goes on which background.
+
+## Source
+
+Nathan Curtis, "Naming Tokens in Design Systems" (2020). Jina Anne, "Design Tokens W3C Community Group" naming guidelines. Brad Frost, "Naming Design System Components" (2019). Ethan Marcotte, "Naming Things" (A List Apart, 2013). Salesforce Lightning Design System Naming Conventions documentation.
+
+## 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-naming-conventions/skill.yaml

@@ -0,0 +1,34 @@
+name: design-naming-conventions
+version: '1.0.0'
+description: Design system nomenclature for semantic and descriptive names, color naming, size naming, and cross-discipline vocabulary
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-token-architecture
+  - design-component-anatomy
+  - design-design-governance
+stack_signals: []
+keywords:
+  - naming
+  - semantic-names
+  - descriptive-names
+  - vocabulary
+  - nomenclature
+  - color-naming
+  - size-naming
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-navigation-ux/SKILL.md

@@ -0,0 +1,150 @@
+# Navigation UX
+
+> Wayfinding — navigation models (hub-spoke, hierarchy, flat, content-driven), persistent vs contextual nav, breadcrumbs, information scent
+
+## When to Use
+
+- Designing the navigation architecture for a new application or website
+- Restructuring navigation in an existing product that has grown organically and become disoriented
+- Choosing between sidebar, top bar, bottom tab, hamburger menu, or command palette navigation
+- Evaluating whether users can answer the three wayfinding questions: Where am I? Where can I go? How do I get back?
+- Building deep content hierarchies (documentation sites, e-commerce catalogs, admin dashboards)
+- Designing mobile navigation where screen real estate constrains persistent nav options
+- Adding search or command palette navigation to complement structural navigation
+- Diagnosing analytics that show high bounce rates, circular navigation paths, or users hitting the back button repeatedly
+
+## Instructions
+
+1. **Select a navigation model based on content architecture and user behavior.** There are four fundamental models, each suited to different information structures:
+
+   | Model              | Structure                         | Best For                                   | Example                  |
+   | ------------------ | --------------------------------- | ------------------------------------------ | ------------------------ |
+   | **Hub-and-Spoke**  | Central hub, independent sections | Mobile apps, task-focused tools            | iOS Settings, Uber       |
+   | **Hierarchy**      | Tree structure, parent-child      | Documentation, e-commerce, file systems    | GitHub repo, AWS Console |
+   | **Flat/Matrix**    | All sections equally accessible   | Dashboards, command palettes, social feeds | Linear, Notion sidebar   |
+   | **Content-Driven** | Navigation embedded in content    | Media, editorial, onboarding flows         | Medium, Netflix, Spotify |
+
+   Hub-and-spoke works when sections are independent — completing a task in one section does not require visiting another. Hierarchy works when content has natural parent-child relationships. Flat works when expert users need rapid access to any section. Content-driven works when the content itself suggests the next destination.
+
+2. **Ensure users can always answer three questions.** Miller and Remington's wayfinding research (2004) established that effective navigation answers: (a) Where am I? — the current location must be visually highlighted (active state in nav, breadcrumb, page title). (b) Where can I go? — available destinations must be visible or one interaction away. (c) How do I get back? — return paths must be obvious (back button, breadcrumb, persistent nav). If your navigation fails any of these three, users become disoriented. GitHub answers all three: the repository breadcrumb shows "where am I" (org/repo/path), the file tree shows "where can I go," and the breadcrumb links show "how do I get back."
+
+3. **Use persistent navigation for primary sections, contextual navigation for secondary.** Persistent navigation (always visible: sidebar, top bar, bottom tabs) should contain only the top 5-7 destinations that users visit frequently. Beyond 7, the navigation becomes a scanning task rather than a recognition task (Miller's Law). Secondary and tertiary destinations belong in contextual navigation: dropdown menus, command palettes, breadcrumb paths, or in-page links that appear only when relevant. Vercel's persistent nav has exactly 5 items: Overview, Deployments, Analytics, Logs, Settings. Everything else is contextual.
+
+4. **Implement breadcrumbs for hierarchies deeper than 2 levels.** Breadcrumbs solve the "where am I?" question for deep hierarchies and provide one-click access to any ancestor. Each breadcrumb segment must be a link. The current page should be the last item, not linked (to avoid the "clicking the current page" confusion). Separator characters (/ or >) between segments must not be clickable. GitHub's file navigation is the benchmark: `org / repo / src / components / Button.tsx` — each segment is clickable, the current file is displayed but not linked, and the hierarchy is instantly legible.
+
+5. **Design information scent that guides users toward their goal.** Information scent (Pirolli and Card, 1999) is the degree to which a navigation label predicts the content behind it. Strong scent: "Billing and Invoices" clearly leads to payment history. Weak scent: "Resources" could contain documentation, blog posts, templates, or downloads. The rules for strong information scent:
+   - Use specific nouns, not abstract categories ("Billing" not "Account," "API Keys" not "Settings")
+   - Include the most common search terms in navigation labels (what users type in search should appear in nav)
+   - Front-load distinguishing words ("Deployment Settings" not "Settings for Deployments")
+   - Test labels with a card sort: show users the label alone and ask where they expect it to lead
+
+6. **Choose the right navigation container for the platform and content depth.**
+   - **Top bar:** Best for 3-7 primary sections on desktop. Vercel, Stripe Dashboard, GitHub. Scales poorly beyond 7 items. Not suitable for deep hierarchies without a supplementary sidebar.
+   - **Sidebar:** Best for 5-20+ sections with hierarchy. AWS Console, VS Code, Notion. Supports nested groups, expandable sections, and scroll. Can be collapsed to icons for space recovery. Linear uses a collapsible sidebar with team/project hierarchy.
+   - **Bottom tabs (mobile):** Best for 3-5 primary sections on mobile. iOS tab bar standard. Instagram, Spotify, Airbnb. Must never exceed 5 tabs (Apple HIG). Icons must be paired with labels — icon-only bottom tabs fail user testing consistently.
+   - **Hamburger menu:** A concession to space constraints, not a navigation strategy. Hides all navigation behind a single icon. Research by NNGroup (2016) showed that visible navigation increases feature discovery by 25-50% compared to hamburger menus. Use only when persistent navigation genuinely cannot fit, and supplement with visible shortcuts to the most-used sections.
+   - **Command palette:** Flat-access overlay invoked by keyboard shortcut (Cmd+K / Ctrl+K). Linear, VS Code, Figma, Vercel, GitHub. Best as a supplement to structural navigation, not a replacement — it serves expert users who know what they want and can type it.
+
+7. **Maintain spatial consistency across navigation transitions.** When a user navigates from Page A to Page B via the sidebar, Page B should appear in the content area while the sidebar remains stable. The sidebar should not scroll, reorder, or collapse during navigation — the persistent frame must persist. Apple's iOS navigation controller maintains spatial consistency through push/pop animations: new content slides in from the right, back navigation slides from the left. This builds spatial memory — users develop a mental model of "forward is right, back is left." Violating spatial consistency (content appears from random directions, navigation items rearrange) destroys the user's spatial model and causes disorientation.
+
+8. **Provide multiple navigation paths to the same destination.** Expert users and novice users navigate differently. Novices browse (following hierarchical paths, reading labels). Experts search (command palette, URL manipulation, keyboard shortcuts). Both need to reach the same content. GitHub supports at least four paths to any file: (1) browse the file tree, (2) use the "Go to file" search (T shortcut), (3) modify the URL directly, (4) search with the site-wide search bar. Each path serves a different user expertise level and context.
+
+## Details
+
+### Navigation Model Deep Dives
+
+**Hub-and-Spoke** is the dominant mobile pattern. The "hub" is a home screen or dashboard. "Spokes" are independent feature areas. Users always return to the hub before navigating to a different spoke. iOS Settings is pure hub-and-spoke: tap a category (spoke), configure it, tap "Back" to return to the settings list (hub), then tap another category. The strength is simplicity — users never get lost because the hub is always one tap away. The weakness is inefficiency — moving between spokes requires a hub round-trip. Solutions: add cross-spoke shortcuts (deep links from one spoke to a related spoke) or promote the most common cross-spoke paths to the hub.
+
+**Hierarchy** reflects content with natural parent-child relationships: file systems, documentation, e-commerce catalogs. AWS Console is a deep hierarchy: Service > Resource Type > Resource > Configuration Tab > Specific Setting. Hierarchies need breadcrumbs (essential), collapsible tree views (helpful), and "jump to" search (essential for hierarchies deeper than 3 levels). The critical design decision is hierarchy width vs depth. Broad, shallow hierarchies (many items per level, few levels) support scanning. Deep, narrow hierarchies (few items per level, many levels) support drill-down. Research by Larson and Czerwinski (1998) found that broad hierarchies outperform deep ones for information retrieval — users complete tasks faster with 8x8 (64 items, 2 levels) than 2x2x2x2x2x2 (64 items, 6 levels).
+
+**Flat/Matrix navigation** gives all sections equal structural weight. There is no parent-child relationship — every section is a peer. Linear's sidebar lists Inbox, My Issues, Views, Teams, and Projects at the same level. The command palette (Cmd+K) provides flat access to everything. This model works when: (a) users have clear goals and know what they want, (b) sections are independent, and (c) the total section count is manageable (under 20). Beyond 20 flat items, users cannot scan the list efficiently and the model degrades.
+
+**Content-driven navigation** embeds navigation choices within the content itself — "related articles" links, "you might also like" recommendations, "next episode" auto-play. Netflix is almost entirely content-driven: rows of suggestions, each item linking to its detail page, which contains more suggestions. The structural navigation (home, search, my list) is minimal. Content-driven navigation works for exploration and discovery scenarios but fails for goal-directed tasks — if the user knows exactly what they want, embedded suggestions are noise.
+
+### Breadcrumb Design Specifications
+
+Breadcrumbs appear trivial but have specific design requirements:
+
+- **Position:** Top of the content area, below the global navigation bar, above the page title. Consistent across all pages.
+- **Separator:** "/" (file-path metaphor) or ">" (hierarchy metaphor). Choose one and use it consistently. Not clickable — only the segment text is clickable.
+- **Current page:** Displayed as the last segment. Not linked (prevents "click current page" confusion). Visually distinguished (bold weight or reduced opacity compared to ancestor links).
+- **Truncation:** For deep hierarchies (>5 levels), show first segment, ellipsis, last 2-3 segments: `Home / ... / Components / Button / Variants`. The ellipsis should be clickable, revealing a dropdown of hidden segments.
+- **Mobile:** Breadcrumbs often collapse to a single "Back to [parent]" link on mobile, since the full path does not fit. This is acceptable — the "back" affordance answers "how do I get back?" which is the highest-priority wayfinding question on mobile.
+
+### Command Palette Design
+
+The command palette (Cmd+K) has become a standard navigation supplement in developer and productivity tools. Design requirements:
+
+- **Invocation:** Keyboard shortcut (Cmd+K or Ctrl+K) and a visible search icon/button for discoverability. Linear shows a persistent search bar in the sidebar. VS Code shows a magnifying glass icon in the activity bar.
+- **Fuzzy matching:** Users do not type exact nav labels. "depl sett" should match "Deployment Settings." Use fuzzy search algorithms (Fuse.js, fzf-style matching) that tolerate typos and abbreviations.
+- **Result categories:** Group results by type: Pages, Actions, Settings, Recent. Vercel's command palette groups by: Navigation, Commands, Teams, Projects. Each group has a heading and results are ranked by relevance within groups.
+- **Recent/frequent prioritization:** Show recently visited pages and frequently used commands at the top before the user types anything. This makes the command palette useful as a "quick jump" tool, not just a search tool.
+- **Keyboard navigation:** Arrow keys to move between results, Enter to select, Escape to close. Tab to cycle between result categories. The entire interaction must be keyboard-only accessible — mouse is optional.
+
+### Spatial Memory and Animation Direction
+
+Users build spatial models of applications. After using an app for days, they develop a sense of "where things are" — settings feels like it is "to the right," notifications feel "above," profile feels "in the corner." Navigation animations should reinforce these spatial models:
+
+- **Horizontal push/pop:** Used for peer-to-peer or sequential navigation (pages at the same hierarchy level, wizard steps). Content slides left to go "forward," right to go "back." Apple's UINavigationController and Android's Fragment transactions use this.
+- **Vertical slide:** Used for hierarchy changes. Content slides up to go "deeper" (into a detail view), down to go "shallower" (back to a list). Bottom sheets slide up from below.
+- **Fade/crossfade:** Used for non-spatial transitions where direction is meaningless (tab switches, same-position content swaps). Vercel uses crossfade for switching between dashboard tabs — there is no spatial relationship between "Deployments" and "Analytics."
+- **Scale/zoom:** Used for focus changes. Zooming in (scaling up) to enter a detail view, zooming out (scaling down) to return to an overview. Figma uses scale transitions when zooming into a frame.
+
+### Anti-Patterns
+
+1. **The Junk Drawer.** A navigation item labeled "More," "Resources," "Other," or "Misc" that contains unrelated items that did not fit elsewhere. This is a failure of information architecture — the categories are wrong if items do not fit. Fix: restructure categories so every item has a natural home. If truly disparate items remain, consider whether they need to be in the navigation at all (maybe they belong in footer links, a help center, or a settings page).
+
+2. **Navigation Inconsistency Across Pages.** The sidebar has 6 items on the dashboard, 4 items on the settings page, and 8 items on the analytics page — the navigation itself changes depending on where you are. Users lose their spatial model. Fix: persistent navigation must be literally persistent — same items, same order, same position on every page. Contextual nav can change, but the persistent frame must not.
+
+3. **Deep Hamburger Hiding.** Hiding all navigation — including primary sections — behind a hamburger menu on desktop viewports where screen real estate is abundant. NNGroup's research (2016) found 25-50% lower feature discovery when navigation is hidden. The hamburger menu is a mobile compromise, not a desktop design choice. Fix: on desktop (>1024px), show primary navigation persistently. Use the hamburger only on mobile viewports where space genuinely requires it.
+
+4. **Breadcrumb-less Deep Hierarchies.** A documentation site or admin panel with 4+ hierarchy levels and no breadcrumbs. Users navigate in, lose track of their position, and resort to the browser back button (which may not correspond to the hierarchy path if they arrived via search or deep link). Fix: add breadcrumbs to every page deeper than level 2.
+
+5. **Icon-Only Navigation Without Labels.** A sidebar of 8 cryptic icons with no text labels, tooltips only on hover, and no visible way for a new user to learn what each icon means. Requires memorization of an arbitrary icon vocabulary. Fix: always pair icons with visible text labels. If space requires icon-only mode, add persistent tooltips on hover and ensure every icon follows established conventions (gear for settings, bell for notifications, house for home).
+
+### Real-World Examples
+
+**GitHub Repository Navigation.** GitHub's repository page is a masterclass in multi-model navigation. The top tab bar (Code, Issues, Pull Requests, Actions, etc.) is flat navigation — all sections are peers. Within Code, the file tree is hierarchical navigation with breadcrumbs. The "Go to file" shortcut (T key) is command palette navigation. The global search bar is search navigation. The breadcrumb path (org/repo/path) provides wayfinding. All four navigation models coexist, each serving a different user need: browsing (hierarchy), scanning (tabs), jumping (command palette), searching (search bar).
+
+**Linear's Keyboard-First Navigation.** Linear's navigation is designed for speed. The sidebar provides structural navigation (Teams, Projects, Views). The command palette (Cmd+K) provides flat access to everything — issues, projects, settings, actions. Keyboard shortcuts (G then I for "Go to Inbox," G then M for "Go to My Issues") provide direct access without any visual navigation interaction at all. The three layers serve three user expertise levels: sidebar for learning, command palette for intermediate, shortcuts for expert. The transition between layers is seamless — a user can use all three in a single session.
+
+**Apple iOS Navigation Hierarchy.** iOS establishes spatial navigation conventions that billions of users have internalized. Push (slide from right): navigate deeper. Pop (slide from left): navigate shallower. Modal (slide from bottom): temporary context (compose, alert, picker). Dismiss (slide to bottom): close temporary context. These four animations create a complete spatial vocabulary. Every native iOS app that follows these conventions benefits from the user's pre-existing spatial model. Apps that violate them (custom transitions that do not match the push/pop/modal/dismiss model) feel disorienting because they break the learned spatial language.
+
+**Airbnb's Content-Driven Navigation.** Airbnb's home page navigation is almost entirely content-driven. Category pills (Icons, Beach, Cabins, Pools) filter the content grid. The grid items themselves are the primary navigation — each listing card leads to a detail page. The detail page uses content-driven navigation: a "More places to stay" section at the bottom continues the browsing journey. Structural navigation (search bar, profile menu, saved, trips) is minimal and positioned to not compete with content browsing. The design optimizes for exploration — users who do not have a specific destination in mind should find one through content, not through navigation menus.
+
+### Navigation Testing Methodology
+
+Validate navigation design with these three tests:
+
+**First-click test.** Show users a screenshot of the interface and ask them to click where they would go to complete a specific task ("Find your billing history"). If more than 70% of users click the correct navigation item on their first attempt, the information scent is strong. Below 50% indicates a labeling or hierarchy problem. Tools: Optimal Workshop, UsabilityHub.
+
+**Tree test (reverse card sort).** Present the navigation hierarchy as a text-only tree (no visual design) and ask users to navigate to specific content. This isolates information architecture from visual design — if users cannot find content in the tree, no amount of visual polish will save the navigation. Target: 80%+ success rate for critical tasks. Run tree tests before any visual design work — fixing IA problems in code is 10x more expensive than fixing them in a tree test.
+
+**Back button audit.** Navigate through every major flow in the application and press the browser back button at each step. Does it return to the expected previous page? Does the previous page preserve its state (scroll position, filter selections, form data)? SPA frameworks often break back-button expectations by treating route changes as forward-only — verify that history management works correctly for every navigation path.
+
+**Navigation path analysis.** In production, track the actual navigation paths users take to reach key pages. If users consistently take 4 clicks to reach a page that should be 2 clicks away, the navigation structure has a depth problem. If users consistently use search to find pages that are in the navigation, the labels have an information scent problem. Google Analytics User Flow and Hotjar recordings both support this analysis.
+
+## Source
+
+- Pirolli, P. and Card, S. — "Information Foraging" (1999), information scent theory
+- Miller, C. and Remington, R. — "Modeling Information Navigation" (2004), wayfinding in digital spaces
+- Larson, K. and Czerwinski, M. — "Web Page Design: Implications of Memory, Structure and Scent for Information Retrieval" (1998), hierarchy breadth vs depth
+- Nielsen Norman Group — "Hamburger Menus and Hidden Navigation Hurt UX Metrics" (2016)
+- Apple Human Interface Guidelines — Navigation patterns, https://developer.apple.com/design/human-interface-guidelines/navigation
+- Material Design — Navigation patterns, https://m3.material.io/foundations/adaptive-design/large-screens
+
+## 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-navigation-ux/skill.yaml

@@ -0,0 +1,34 @@
+name: design-navigation-ux
+version: "1.0.0"
+description: Wayfinding — navigation models (hub-spoke, hierarchy, flat, content-driven), persistent vs contextual nav, breadcrumbs, information scent
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-affordances
+  - design-information-architecture
+stack_signals: []
+keywords:
+  - navigation
+  - wayfinding
+  - hub-spoke
+  - hierarchy
+  - flat-nav
+  - breadcrumbs
+  - information-scent
+  - spatial-memory
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-palette-construction/SKILL.md

@@ -0,0 +1,152 @@
+# Palette Construction
+
+> Building functional palettes — primary/secondary/accent selection, neutral scales, semantic colors, and tint/shade generation for production design systems
+
+## When to Use
+
+- Building a color system for a new product or design system from scratch
+- Extending an existing brand color into a full functional palette
+- Creating tint/shade scales for a component library
+- Defining semantic color tokens (success, warning, error, info)
+- Generating a neutral gray scale with intentional warm or cool undertone
+- Auditing a palette for missing functional roles (no accent, no semantic, incomplete neutral scale)
+- Migrating from ad-hoc color values to a systematic, tokenized palette
+- Building a palette that must support both light and dark modes
+
+## Instructions
+
+1. **Understand palette anatomy.** Every production palette has five functional categories. Missing any category forces ad-hoc color decisions that erode consistency:
+
+   | Category      | Role                                                                    | Typical Count           | Example (Stripe)                                                          |
+   | ------------- | ----------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
+   | **Primary**   | Brand identity, primary CTAs, key interactive elements                  | 1 color + 10-step scale | Purple `#533afd`                                                          |
+   | **Secondary** | Supporting brand elements, secondary buttons, active states             | 0-1 color + scale       | (Stripe uses navy `#061b31` structurally, not as a secondary brand color) |
+   | **Accent**    | Decorative highlights, illustrations, marketing flourishes              | 0-2 colors              | Ruby `#ea2261`, Magenta `#f96bee`                                         |
+   | **Neutral**   | Text, backgrounds, borders, dividers, shadows — the structural backbone | 1 scale of 10-13 steps  | Slate gray scale from near-white to near-black                            |
+   | **Semantic**  | Status communication (success, warning, error, info)                    | 4 colors + scales       | Green/amber/red/blue, each with 3-5 variants                              |
+
+2. **Generate tint/shade scales using perceptually uniform steps.** A 10-step scale from 50 (lightest) to 950 (darkest) is the industry standard. Do not interpolate linearly in RGB — the results are perceptually uneven. Use HSL lightness interpolation at minimum, or OKLCH/CIELAB for perceptual uniformity.
+
+   **Tailwind CSS's approach:** Tailwind generates its color scales (50, 100, 200, ... 900, 950) with perceptual uniformity as the goal. Each step represents an approximately equal perceived lightness shift. The 500 step is the "base" — the color as you would name it in conversation ("that's blue"). Steps below 500 are tints (mixed toward white), steps above are shades (mixed toward black).
+
+   **Practical generation procedure:**
+   - Start with your base color (e.g., Primary 500 = `#533afd`)
+   - Generate lightness stops: 50 (L:97%), 100 (L:93%), 200 (L:86%), 300 (L:76%), 400 (L:64%), 500 (L:50%), 600 (L:40%), 700 (L:32%), 800 (L:24%), 900 (L:17%), 950 (L:10%)
+   - Adjust saturation: tints (50-300) reduce saturation by 10-30% to avoid pastel fluorescence; shades (700-950) reduce saturation by 5-15% to avoid muddy darkness
+   - Verify each step has sufficient contrast against both white and black backgrounds for its intended use
+
+3. **Build the neutral scale with intentional undertone.** Pure gray (`hsl(0, 0%, X%)`) is emotionally sterile. Every respected design system tints its neutrals:
+   - **Tailwind Slate:** Blue undertone (hue ~215, S:15-25%) — cool, technical, modern
+   - **Tailwind Zinc:** Blue-violet undertone (hue ~240, S:3-8%) — nearly true neutral with slight cool bias
+   - **Tailwind Stone:** Warm undertone (hue ~25, S:5-10%) — earthy, editorial, organic
+   - **Stripe:** Slate-blue undertone matching their navy brand — creates chromatic unity between colored and "gray" elements
+
+   Decision procedure: match neutral undertone to your primary color's hue family. If primary is blue, use cool neutrals (Slate). If primary is orange or red, use warm neutrals (Stone). This creates subliminal harmony between the structural gray and the chromatic brand.
+
+4. **Define semantic colors independently from brand colors.** Semantic colors must be recognizable regardless of brand context. Never reuse your primary brand color as a semantic color — if your brand is green, your "success" green must be a different green (shifted in hue, saturation, or lightness) so users do not confuse brand elements with success states.
+
+   **Standard semantic mapping:**
+   - **Success:** Green (hue 120-160). Tailwind: `#22c55e` (green-500). Material: `#4caf50`.
+   - **Warning:** Amber/yellow (hue 35-50). Tailwind: `#f59e0b` (amber-500). Material: `#ff9800`.
+   - **Error/Destructive:** Red (hue 0-15). Tailwind: `#ef4444` (red-500). Material: `#f44336`.
+   - **Info:** Blue (hue 200-220). Tailwind: `#3b82f6` (blue-500). Material: `#2196f3`.
+
+   Each semantic color needs at least 3 variants: a strong variant (for filled backgrounds/badges), a subtle variant (for tinted backgrounds), and a text variant (for inline status text). Example for error: `error-500` for filled badges, `error-50` for background tints, `error-700` for text on light backgrounds.
+
+5. **Apply the 60-30-10 rule at the palette level.** This is a surface area budget, not a color count:
+   - **60% — Neutrals.** Backgrounds, text, borders, dividers. This is your neutral scale doing the structural work.
+   - **30% — Primary/Secondary.** Brand presence through headings, navigation, cards, section backgrounds.
+   - **10% — Accent + Semantic.** Buttons, links, badges, status indicators. The scarcity makes them visually powerful.
+
+   Stripe's implementation: approximately 60% white/light gray (neutral), 30% navy text and dark sections (primary structural), 10% purple for interactive elements and semantic colors for states. This distribution makes the purple CTAs unmissable precisely because they are rare.
+
+6. **Test the complete palette in a component matrix.** Before finalizing, render your palette across these components: button (primary, secondary, ghost, destructive), input (default, focused, error, disabled), card (default, elevated, selected), badge (success, warning, error, info), text (heading, body, secondary, disabled). If any component looks wrong, the palette has a gap.
+
+## Details
+
+### Material Design 3's HCT Color Space
+
+Material Design 3 introduced the HCT (Hue, Chroma, Tone) color space for palette generation. HCT separates three perceptually independent dimensions:
+
+- **Hue** (0-360): the color family
+- **Chroma** (0-~120): colorfulness (similar to saturation but perceptually uniform)
+- **Tone** (0-100): lightness from black (0) to white (100)
+
+From a single seed color, MD3 generates:
+
+- **Primary palette:** Seed hue, full chroma, tones 0-100
+- **Secondary palette:** Seed hue, chroma reduced by ~67%, same tones
+- **Tertiary palette:** Hue shifted +60 degrees, moderate chroma, same tones
+- **Neutral palette:** Seed hue, chroma reduced to ~4, same tones
+- **Neutral variant:** Seed hue, chroma reduced to ~8, same tones
+
+This algorithmic approach guarantees harmony because every palette shares a hue relationship with the seed. The tonal system maps directly to accessibility: Tone 40 on Tone 100 (white) guarantees 7:1+ contrast; Tone 80 on Tone 10 guarantees similar contrast in dark mode.
+
+### Palette Sizing: How Many Colors Are Enough?
+
+A common trap is building either too few colors (everything is a one-off) or too many (the palette is an unusable rainbow). Guidelines by product type:
+
+- **Marketing site / landing page:** 1 primary + 1 neutral scale + semantics = ~30 total values. Minimal UI, maximum brand impact.
+- **SaaS application / dashboard:** 1 primary + 1 secondary + 1 neutral scale + semantics = ~50-60 total values. Enough for complex UI without confusion.
+- **Design system / component library:** 1-2 primary + 1 neutral scale + semantics + 2-3 extended accent scales = ~80-100 total values. Covers all possible component states.
+- **Data visualization addition:** Add 6-8 categorical colors, each with 3 variants (strong, medium, subtle) = ~24 additional values.
+
+Stripe's public-facing palette contains approximately 60 total color values. Tailwind CSS ships approximately 220 (22 hues x 10 steps + black/white). Material Design 3 generates approximately 130 from a single seed.
+
+### Anti-Patterns
+
+1. **Too Many Primaries.** Having 3+ "brand colors" that all compete for attention. Symptoms: every page section uses a different bold color, and no single color owns the "primary action" role. Fix: one color is primary (owns buttons and links), at most one is secondary (owns navigation or section backgrounds), everything else is accent (illustrations only) or neutral. Spotify has one primary (green). Stripe has one primary (purple). Apple has zero chromatic primaries (achromatic).
+
+2. **Missing Neutral Scale.** Using only 2-3 grays (`#333`, `#666`, `#999`) instead of a full 10+ step scale. Symptoms: text hierarchy feels flat, borders blend into backgrounds, disabled states are indistinguishable from secondary text. Fix: generate a full 10-step neutral scale with intentional undertone. Even a simple project needs at least 7 neutral steps: background, surface, border, disabled, tertiary text, secondary text, primary text.
+
+3. **Semantic Ambiguity.** Using the same green for both "success" and "go/proceed" — or worse, using the brand green as the success color. Symptoms: users cannot tell if a green badge means "success" or is just brand decoration. Fix: semantic colors must be visually distinct from brand colors. If your brand is green, shift your success green to a different hue (more teal or more lime) or use a different lightness level.
+
+4. **Tint/Shade Scale Gaps.** Having a base color and a light variant but nothing in between. Symptoms: hover states use opacity hacks (`rgba(primary, 0.1)`) instead of real palette steps, dark mode has no intermediate surface colors. Fix: generate the full 10-step scale for every primary and semantic color. The intermediate steps (200-400, 600-800) are what make a palette feel production-ready.
+
+5. **RGB Interpolation.** Generating tints and shades by linearly interpolating in RGB color space. Symptoms: midpoint colors look muddy or desaturated (the "brown muddle" when mixing blue and orange). Fix: interpolate in HSL at minimum, OKLCH or CIELAB for best perceptual results. Modern tools (Figma, the `oklch()` CSS function) support perceptually uniform interpolation natively.
+
+### Real-World Examples
+
+**Tailwind CSS — The Reference Scale.** Tailwind's color system provides 22 named color families, each with 11 stops (50-950). The scales are designed for perceptual uniformity: stepping from gray-200 to gray-300 looks like the same lightness jump as gray-600 to gray-700. Each 100-step represents approximately 7-10% lightness change in OKLCH space. The 500 stop is always the "name-worthy" shade — the color you would call "blue" or "red" in conversation. This makes the system predictable: if you need a lighter version, go down the scale; darker, go up.
+
+**Stripe — Functional Minimalism.** Stripe's palette demonstrates that a world-class design system does not need many colors. The functional palette: purple `#533afd` (primary), navy `#061b31` (structural text), a slate-blue neutral scale (backgrounds, borders, secondary text), and standard semantics (red error, green success, amber warning, blue info). Decorative colors (ruby `#ea2261`, magenta `#f96bee`, cyan, green gradients) exist only in marketing illustrations and the homepage gradient — they never appear in the product dashboard. This discipline keeps the product interface clean while the marketing surface feels vibrant.
+
+**Material Design 3 — Algorithmic Generation.** MD3 proves that a full production palette can be generated algorithmically from a single color. Input: one hex value (e.g., `#6750A4`). Output: 5 tonal palettes (primary, secondary, tertiary, neutral, neutral-variant) x 13 tones each = 65 color values, plus semantic colors. Every generated color is guaranteed to meet contrast requirements when used at its designated tone pairing (e.g., "on-primary" text at Tone 100 on primary container at Tone 90). This eliminates manual contrast checking for standard component combinations.
+
+## Source
+
+- Material Design 3 Color System — https://m3.material.io/styles/color/the-color-system
+- Tailwind CSS Color Palette — https://tailwindcss.com/docs/colors
+- RefactoringUI — "Building Your Color Palette" chapter
+- OKLCH Color Space — https://oklch.com/ — perceptually uniform space for palette generation
+
+## Process
+
+1. Select your primary brand color and determine the harmony type (from design-color-harmony). Generate the full 10-step tint/shade scale.
+2. Build the neutral scale with undertone matching the primary hue. Add semantic colors (success, warning, error, info) with 3+ variants each.
+3. Test the complete palette in a component matrix (button, input, card, badge, text). Verify 60-30-10 distribution in a representative layout.
+4. Document every color value with its functional role, contrast relationships, and usage guidelines.
+
+## 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.
+- **Pairs with:** design-color-harmony (harmony type determines how many chromatic scales to generate), design-color-accessibility (palette must pass colorblind simulation), design-dark-mode-color (palette must have dark mode variants), design-token-architecture (palette values become design tokens).
+- **Sequencing:** Use after design-color-harmony and design-color-psychology have established direction. This skill produces the concrete palette values that all other skills reference.
+
+## Success Criteria
+
+- The palette has all five functional categories: primary, secondary (optional), accent (optional), neutral, and semantic.
+- Every chromatic color has a full 10-step tint/shade scale (50-950), not just a base value.
+- The neutral scale has an intentional undertone matching the primary hue family.
+- Semantic colors are visually distinct from brand colors — no ambiguity between "brand" and "status."
+- The 60-30-10 distribution is observable in representative layouts.
+- Every palette step has documented contrast ratios against white, black, and the palette's own background colors.
+- The palette renders correctly across the component matrix (button, input, card, badge, text).
+- Tint/shade generation uses perceptually uniform interpolation (HSL minimum, OKLCH preferred), not RGB.
+- The palette supports both light and dark modes through tone-based mapping (not simple inversion).
+- Total palette size is appropriate for the product type (30-60 for marketing sites, 50-80 for SaaS, 80-100 for design systems).
+- No opacity hacks (rgba with alpha) are needed for standard states — the scale provides real values for hover, pressed, and disabled states.
+- Palette documentation includes functional role for every color (not just hex values without context).
+- The palette has been tested in a component matrix across all standard component types.
+- Intermediate scale steps (200-400, 600-800) exist and serve distinct functional purposes.

package/dist/agents/skills/codex/design-palette-construction/skill.yaml

@@ -0,0 +1,37 @@
+name: design-palette-construction
+version: "1.0.0"
+description: Building functional palettes — primary/secondary/accent, neutral scales, semantic colors, tint/shade generation
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-color-harmony
+  - design-color-accessibility
+  - design-dark-mode-color
+  - design-token-architecture
+stack_signals: []
+keywords:
+  - palette
+  - primary color
+  - secondary color
+  - accent
+  - neutral scale
+  - semantic colors
+  - tint
+  - shade
+  - color system
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []