@harness-engineering/cli 1.23.2 → 1.24.0

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

@@ -0,0 +1,175 @@
+# Design Critique
+
+> Structured feedback — critique frameworks (like/wish/wonder, what/why/improve), separating subjective preference from objective assessment, avoiding "I don't like it"
+
+## When to Use
+
+- Reviewing a design proposal, mockup, or prototype before implementation begins
+- Providing feedback on a pull request that changes UI layout, typography, color, or interaction patterns
+- Running a formal design review session with multiple stakeholders
+- Evaluating a competitor's design to extract actionable insights for your own product
+- Coaching junior designers or engineers to give better design feedback
+- Receiving vague feedback like "it feels off" and needing to decompose it into addressable items
+- Deciding between two or more design directions that each have merit
+- Auditing your own work before presenting it — self-critique as quality gate
+- Preparing a design for handoff to engineering with pre-addressed concerns
+
+## Instructions
+
+1. **Separate observation from judgment before speaking.** Every piece of design feedback must begin with what you see, not what you feel:
+   - "The primary CTA button is 12px from the form's last field" is an observation.
+   - "The button feels too close" is a judgment.
+   - Start with the observation, then layer the judgment with reasoning. This prevents the most common critique failure: feedback that cannot be acted upon because nobody knows what it refers to.
+   - **Stripe example:** "The payment form looks cluttered" is useless. "The payment form has 14px spacing between field groups while the rest of the page uses 24px — this inconsistency creates visual tension" is actionable.
+
+2. **Apply the Like/Wish/Wonder framework for generative feedback.** Structure every critique response in three parts:
+   - **Like** — identify specific elements that work and explain why they work. "I like that the error messages appear inline below each field rather than in a banner — this preserves the user's scroll position and creates a direct spatial association between the error and its cause."
+   - **Wish** — express desired changes as wishes rather than demands. "I wish the success state included a clear next-step CTA — right now the confirmation message is a dead end."
+   - **Wonder** — pose open questions that expand the design space. "I wonder if the onboarding flow would benefit from progressive disclosure — showing all 8 fields at once might create form abandonment."
+   - This framework forces balanced feedback and prevents pile-on negativity.
+
+3. **Apply the What/Why/Improve framework for evaluative feedback.** When the goal is to assess quality rather than generate ideas:
+   - **What** — describe the specific element under review. "The navigation sidebar collapses to icons at 768px."
+   - **Why** — explain why this is effective or problematic with reference to a principle. "Icon-only navigation relies on recognition over recall, violating Nielsen's heuristic #6, because these custom icons have no established meaning."
+   - **Improve** — propose a concrete alternative. "Add persistent text labels below each icon, or use a tooltip that appears on hover with a 200ms delay."
+   - Every improve statement must be specific enough to implement without further clarification.
+
+4. **Classify feedback into three weight categories.** Not all feedback carries equal weight:
+   - **Objective** — references measurable criteria. "The contrast ratio between the body text (#767676) and white background is 4.48:1, which fails WCAG AA for normal text (requires 4.5:1)." Non-negotiable — must be fixed.
+   - **Subjective-informed** — applies established design principles. "The 8px margin between the headline and body text creates an ambiguous grouping per Gestalt proximity — increasing to 16px would clarify the hierarchy." Strong weight — should usually be accepted.
+   - **Subjective-preference** — expresses personal taste. "I prefer rounded buttons over square ones." Least weight — must be explicitly labeled as preference so it does not dominate the discussion.
+
+5. **Use the severity/confidence matrix to prioritize feedback.** Every critique item should be tagged:
+
+   | Severity   | Confidence | Example                                                              | Action                  |
+   | ---------- | ---------- | -------------------------------------------------------------------- | ----------------------- |
+   | Critical   | High       | "Submit button is invisible on mobile — tested iPhone 14, Safari 17" | Blocks approval         |
+   | Major      | High       | "Form has no error recovery — users must re-enter all fields"        | Must fix this iteration |
+   | Minor      | Medium     | "Icon weight could be 1.5px instead of 2px for consistency"          | Backlog for polish      |
+   | Suggestion | Low        | "Wonder if a tooltip would help here"                                | Consider in future      |
+
+   This matrix prevents a 90-minute review from being derailed by icon weight discussions while a checkout-blocking bug goes unmentioned.
+
+6. **Critique the design, not the designer.** Frame all feedback in terms of the artifact, never the person:
+   - Say "The layout does not account for text expansion in German localization" — not "You forgot about i18n."
+   - When receiving critique, practice the 24-hour rule: do not respond defensively in the moment. Write down every piece of feedback, sit with it for a day, then evaluate which items improve the design.
+   - Jony Ive's design review culture at Apple was famously ego-free — feedback was directed at the object on the table, never the person who made it.
+
+7. **Anchor critique in user goals, not aesthetic preference.** The ultimate test of a design is whether it helps the user accomplish their goal:
+   - User-goal-anchored: "The dashboard shows 12 metrics above the fold, but the user's primary task is checking deployment status — a single status indicator with drill-down would reduce cognitive load from 12 items to 1."
+   - Aesthetic preference disguised as critique: "The dashboard is too busy."
+   - Always ask: what is the user trying to do, and does this design make that task easier or harder?
+
+8. **Close every critique session with a prioritized action list.** Synthesize all feedback into a ranked list:
+   - **(1) Must-fix before ship** — blocks release if unresolved.
+   - **(2) Should-fix this iteration** — significant quality impact.
+   - **(3) Consider for future iteration** — nice-to-have improvements.
+   - Each item must reference the original feedback, the agreed-upon resolution, and the owner. Do not end a critique with "lots of good feedback, we will work through it" — that is how feedback gets lost.
+
+## Details
+
+### The Critique Ladder
+
+Design critique operates at five distinct levels of depth. Skilled reviewers consciously choose which level is appropriate:
+
+**Level 1: Visceral reaction** (0-3 seconds). First impression, gut feeling. "This feels premium" or "this feels dated" captures the immediate emotional response. Useful as a data point but never sufficient as feedback. Record it, but do not act on it until you can articulate why.
+
+**Level 2: Descriptive observation** (what exists). Catalog what you see without judgment. "The header uses a sans-serif font at 32px bold. The primary color is #2563EB. There are four navigation items. The hero image is full-bleed." This establishes a shared factual baseline before opinions enter the conversation.
+
+**Level 3: Analytical assessment** (how it works). Apply design principles to the observations. "The 32px heading with 16px body text creates a 2:1 type scale ratio — this is below the 2.5:1 minimum recommended for clear hierarchy. The four navigation items use identical visual weight, offering no signal about which is the current page." This is where the majority of useful critique lives.
+
+**Level 4: Interpretive evaluation** (why it matters). Connect the analysis to user outcomes. "The weak type hierarchy means users scanning the page cannot distinguish section headings from body text at a glance, increasing time-to-task by an estimated 2-4 seconds per page. For a dashboard viewed 20+ times daily, this compounds into meaningful friction."
+
+**Level 5: Strategic questioning** (what else is possible). Zoom out from the specific solution to question the problem framing. "The dashboard assumes users need to see all metrics simultaneously, but analytics show 80% of sessions focus on a single metric. Would a single-metric focus view with drill-down better serve the primary use case?" This level can redirect entire product directions.
+
+### Critique Session Facilitation
+
+A structured critique session follows this protocol:
+
+1. **Context setting** (2 min). The presenter shares: the user problem, the constraints (timeline, tech, brand), and what specific feedback they need. "I need feedback on the information hierarchy of this settings page. I am not looking for color feedback — that follows the existing system."
+2. **Silent review** (5-10 min). All participants review the design silently, writing their observations. This prevents anchoring bias — the first person to speak in an open discussion sets the frame for everyone else.
+3. **Round-robin likes** (5 min). Each participant shares one specific thing that works and why. This establishes a constructive tone and surfaces strengths that should be preserved.
+4. **Round-robin wishes and wonders** (15 min). Each participant shares their wishes and wonders, tagged with severity/confidence. The facilitator captures each item on a shared board.
+5. **Clustering and prioritization** (5 min). Group related feedback items. Vote on priority. Identify the 3-5 most impactful items.
+6. **Response** (5 min). The presenter reflects back what they heard and identifies which items they will address. No defensive explanations — just acknowledgment and intent.
+
+### Asynchronous Critique Protocol
+
+Not all critique happens in a room. Pull requests, Figma comments, and Slack threads require adapted techniques:
+
+**Written feedback format.** Every asynchronous critique comment should follow this template:
+
+1. Screenshot or link to the specific element
+2. Observation — what you see
+3. Assessment — why it matters, referencing a principle or user goal
+4. Suggestion — a concrete alternative
+5. Severity tag — critical / major / minor / suggestion
+
+This structure prevents the two failure modes of async critique: comments that are too vague to act on and comments that are so long nobody reads them.
+
+**Figma annotation conventions.** Pin comments to specific layers, not arbitrary canvas positions. Use color-coded labels: red for critical, orange for major, blue for minor, gray for suggestion. Resolve comments when addressed rather than leaving a thread of "fixed" replies.
+
+**Pull request design review.** When reviewing a PR that changes UI:
+
+- Open the preview/staging URL and test at three breakpoints (375px mobile, 768px tablet, 1440px desktop)
+- Test with browser zoom at 150% and 200%
+- Check dark mode if applicable
+- Screenshot each finding and annotate it
+- A PR design review that only looks at code diffs misses layout regressions, animation glitches, and responsive breakage
+
+### Critique Calibration
+
+Teams drift in critique quality over time. Calibrate regularly by reviewing the same design independently and comparing feedback:
+
+- If five reviewers all surface different critical issues, the team's shared standards are misaligned.
+- If five reviewers converge on the same three issues, the team has a healthy shared baseline.
+- **Calibration exercise:** Take a publicly available design (a SaaS landing page, a government form, a mobile app screen). Each team member writes five critique items using What/Why/Improve. Compare: which items overlap? Which are objective vs. preference? Where do severity ratings diverge? This 30-minute exercise, run quarterly, dramatically improves critique consistency.
+
+### Anti-Patterns
+
+1. **The Drive-By "I Don't Like It."** Feedback with no specificity, no reasoning, and no suggested alternative. "I don't like the spacing" tells the designer nothing about what spacing, why it is problematic, or what to change. The fix: require every "I don't like" to be followed by "specifically [element], because [reason], and I suggest [alternative]." If the reviewer cannot complete the sentence, the feedback is not ready to share.
+
+2. **The Pixel Police.** Focusing exclusively on implementation details (2px misalignment, slightly wrong shade of gray) while ignoring structural issues (navigation model is confusing, information hierarchy is inverted, user flow has a dead end). A review that spends 40 minutes on padding inconsistencies while the core user flow is broken has inverted its priorities. The fix: enforce critique levels — structure first, details second.
+
+3. **The Solution Stampede.** Jumping directly to solutions without understanding the problem. "Just add a sidebar" or "make it more like Notion" or "use tabs instead of a dropdown." Solution-first feedback skips the analytical step and assumes the reviewer's first instinct is correct. The fix: require feedback to follow the What/Why/Improve sequence — the "what" and "why" must be validated before any "improve."
+
+4. **The Frankenstein Review.** Multiple reviewers each contribute one change, none coordinated, resulting in an incoherent patchwork. Reviewer A wants more whitespace, B wants more density, C wants larger type, D wants smaller type. The designer implements all four and the result is worse than the original. The fix: the design owner synthesizes feedback into a coherent revision rather than applying each suggestion independently.
+
+5. **The Compliment Sandwich Trap.** Framing critical feedback between two hollow compliments: "The colors are nice. The entire navigation model is broken. But great font choice!" This trains people to ignore the compliments and softens the impact of the critique. The fix: give genuine, specific positive and critical feedback separately — do not manufacture fake positives as wrapping paper.
+
+6. **The Stakeholder Override.** A senior leader's personal preference overrides well-reasoned design decisions: "The CEO wants it blue." The fix: acknowledge the constraint but document the trade-off with measurable impact: "Changing from orange (#F97316) to blue (#2563EB) reduces the CTA's contrast against the blue navigation bar from 8.2:1 to 1.3:1."
+
+### Real-World Examples
+
+**Apple Design Reviews.** Apple's industrial design team under Jony Ive held daily critique sessions with physical prototypes. The protocol: place the object on the table, and everyone critiques the object — never the person who designed it. "The radius on this corner creates a shadow line that interrupts the continuous surface" is the level of specificity expected. This culture produced the unibody MacBook, the iPhone's edge-to-edge glass, and the AirPods case.
+
+**Google's Design Sprint Critique.** In Google Ventures' design sprint methodology, critique happens on Day 3 ("Decide"). The team silently reviews printed concepts on a wall, places dot-vote stickers on effective elements, and discusses the clusters. Silent voting eliminates groupthink. A concept with 15 dots clustered on its navigation but zero dots on its data visualization tells a clear story without discussion.
+
+**Stripe's Design Review Protocol.** Stripe runs formal reviews for any customer-facing change. Three explicit questions: (1) Does this design handle all edge cases in the state matrix? (2) Does it maintain consistency with the existing design language? (3) Does it degrade gracefully on slow connections and small screens? A "P0" finding (checkout button below the fold on iPhone SE) blocks release. A "P2" finding (reduce font weights from 4 to 2) is logged for the next iteration.
+
+**Airbnb's Design Language System Reviews.** Airbnb's DLS team runs weekly sessions where any team can bring a component variation. Critique is anchored against DLS principles: unified, iconic, conversational. "This card variant introduces a fifth corner radius (6px) when the system uses only 4px, 8px, 12px, and 16px" is grounded in system consistency. Components that pass review carry a "reviewed" badge in the component library.
+
+## Source
+
+- Feldman, E. — "Practical Handbook of Design Critique" (2019), structured critique methods
+- Stanford d.school — "I Like, I Wish, What If" framework for generative feedback
+- Liedtka, J. & Ogilvie, T. — _Designing for Growth_ (2011), critique in design thinking
+- Nielsen, J. — "10 Usability Heuristics for User Interface Design" (1994), criteria anchoring
+- Knapp, J. — _Sprint_ (2016), design sprint critique and dot-voting methodology
+- Connor, A. & Irizarry, A. — _Discussing Design_ (2015), improving critical conversations about design
+
+## 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-design-critique/skill.yaml

@@ -0,0 +1,32 @@
+name: design-design-critique
+version: "1.0.0"
+description: Structured feedback — critique frameworks (like/wish/wonder, what/why/improve), separating subjective preference from objective assessment
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-design-audit
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - critique
+  - feedback
+  - like-wish-wonder
+  - objective-assessment
+  - design-review
+  - structured-feedback
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,163 @@
+# Design Documentation
+
+> Documenting design decisions — design rationale, spec handoff, annotating designs, living documentation, decision logs, the DESIGN.md format
+
+## When to Use
+
+- Starting a new project or feature that involves non-trivial design decisions (layout, interaction model, component selection)
+- Handing off designs from a design phase to implementation — the spec must be unambiguous enough that a developer produces the correct result without guessing
+- Onboarding new team members who need to understand why the interface looks and behaves the way it does
+- Auditing an existing product where design decisions were made but never recorded, leading to inconsistency as team members reinvent rationale
+- Building or maintaining a design system where every component needs documented usage rules, constraints, and change history
+- Resolving recurring design debates — "Why don't we use tabs here?" should have a recorded answer, not a re-litigation
+- Preparing for a design review or critique where participants need context before the meeting, not during it
+- Any time a design decision is made that a future developer or designer might question or reverse without understanding the original reasoning
+
+## Instructions
+
+1. **Write a DESIGN.md at the root of every project or feature directory.** This file is the single canonical source for design rationale. It lives alongside the code it documents, versioned in git, reviewed in pull requests. The format follows a strict structure:
+
+   ```markdown
+   # Feature Name — Design Document
+
+   ## Overview
+
+   One paragraph: what this feature does and why it exists.
+
+   ## Decisions
+
+   ### D1: [Decision Title]
+
+   - **Status:** accepted | proposed | deprecated | superseded by D[n]
+   - **Date:** YYYY-MM-DD
+   - **Context:** What situation prompted this decision
+   - **Decision:** What was decided
+   - **Rationale:** Why this option was chosen over alternatives
+   - **Alternatives considered:** What else was evaluated
+   - **Consequences:** What this decision enables and constrains
+
+   ## Visual Spec
+
+   [Layout descriptions, spacing values, responsive behavior]
+
+   ## Component Inventory
+
+   [Which components are used, their states, their props]
+
+   ## Open Questions
+
+   [Unresolved items with owners and deadlines]
+   ```
+
+   Stripe maintains this format internally — every payment form, dashboard view, and API response page has a corresponding design document that records why specific layout, typography, and interaction choices were made.
+
+2. **Record the rationale, not just the outcome.** "We use a modal for deletion confirmation" is useless documentation. "We use a modal for deletion confirmation because user research showed 23% of users accidentally clicked delete on mobile, a confirmation toast was dismissed too quickly, and an inline confirmation displaced adjacent content causing misclicks" is documentation that prevents the next designer from replacing the modal with a toast. Every decision entry must answer: What was the context? What alternatives existed? Why was this one chosen?
+
+3. **Annotate designs at the point of ambiguity.** Not every pixel needs a note — only the ones where a developer might guess wrong. Annotate: spacing that differs from the base grid ("24px here, not 16px, because the visual weight of the icon needs more breathing room"), interactive behavior that is not obvious from a static mockup ("this panel slides from the right on desktop but overlays from the bottom on mobile"), conditional visibility ("this badge only appears when count > 0"), and truncation rules ("truncate at 2 lines with ellipsis, tooltip on hover shows full text"). Apple's Human Interface Guidelines annotate these exact ambiguity points in their component specs — every spacing override, every conditional behavior, every platform-specific variation.
+
+4. **Use a living documentation system, not static exports.** A Figma link in a wiki that nobody updates after launch is dead documentation. Living documentation is generated from or tightly coupled to the source of truth. Approaches that work:
+   - **Storybook** with embedded design notes per story — the documentation lives next to the rendered component
+   - **DESIGN.md in the feature directory** — reviewed in every PR that changes the feature
+   - **Design tokens as documentation** — the token file (`tokens.json`) is the spec; if the token says `spacing.modal.padding: 24px`, that is both the implementation and the documentation
+   - **Automated screenshot tests** — the test output is the visual spec; if it changes, the PR diff shows the before/after
+
+5. **Create a decision log for cross-cutting design choices.** Individual DESIGN.md files capture feature-level decisions. Cross-cutting decisions ("We use 8px grid system throughout," "Our primary action color is always blue, never green," "We never auto-play video") belong in a centralized decision log, typically at `docs/design-decisions.md` or within the design system documentation. Material Design's documentation functions as a massive decision log — every guideline ("FABs should contain at most one per screen") is a recorded decision with rationale.
+
+6. **Write spec handoff documents that eliminate ambiguity.** A spec handoff is complete when a developer can implement the design without asking a single clarifying question. The handoff must include: exact dimensions and spacing (in design tokens, not pixel values), all interactive states (hover, active, focus, disabled, loading, error), responsive breakpoints and what changes at each, content limits (max characters, truncation behavior, what happens with 1 item vs 1000), accessibility requirements (focus order, ARIA labels, keyboard shortcuts), and animation specs (duration, easing, trigger condition). Vercel's internal spec handoffs include a "Questions a Developer Will Ask" section that pre-answers implementation ambiguities.
+
+7. **Version your design decisions explicitly.** When a decision is superseded, do not delete the old entry — mark it as `superseded by D[n]` and link to the new decision. This creates an audit trail that explains why the interface evolved. GitHub's Primer design system maintains a changelog for every component that records not just what changed but why, including links to the user research or bug reports that motivated the change.
+
+8. **Conduct documentation reviews as part of design reviews.** Before any design is approved, its documentation must be reviewed for completeness. A design without documentation is an undocumented API — it works today, but nobody can maintain it tomorrow. Add "Documentation complete?" as a checkbox in your design review template.
+
+## Details
+
+### The DESIGN.md Format in Depth
+
+The DESIGN.md file serves three audiences simultaneously: designers reviewing the rationale, developers implementing the spec, and future maintainers understanding the constraints. Each section targets a specific audience:
+
+**Overview** is for everyone — one paragraph, no jargon, explains what exists and why. "The notification center displays real-time alerts, grouped by category, with bulk actions for mark-read and dismiss. It exists because user research (2024-Q3) showed users missed critical alerts buried in email notifications."
+
+**Decisions** is for future maintainers. Each decision follows the ADR (Architecture Decision Record) format adapted for design. The critical field is **Alternatives considered** — without it, future designers will propose the same rejected alternatives. Stripe's payment form DESIGN.md records that they considered inline validation (rejected: too aggressive for payment fields where users type slowly), post-submit validation (rejected: users must re-find errors), and field-exit validation (accepted: validates when user moves to next field, balances feedback speed with interruption).
+
+**Visual Spec** is for developers. It must use design tokens, not raw values. "The card has `spacing.card.padding` internal padding, `elevation.card.default` shadow, and `radius.card` border radius" is implementation-ready. "The card has 16px padding, a subtle shadow, and rounded corners" requires the developer to guess which token maps to "subtle" and "rounded."
+
+**Component Inventory** lists every component used in the feature, its variant, and its state coverage. A notification center inventory might read: "NotificationCard (variants: info, warning, error, success; states: unread, read, dismissed, loading), NotificationGroup (variants: collapsed, expanded; states: all-read, has-unread, empty), BulkActionBar (states: hidden, visible, processing)."
+
+**Open Questions** is a forcing function. Every unresolved ambiguity must be written down with an owner and a deadline. "Q: Should notifications older than 30 days auto-archive? Owner: @sarah. Deadline: 2024-11-15." If an open question has no owner and no deadline, it will never be resolved.
+
+### Annotation Best Practices
+
+Annotations should follow a consistent format across the team. A proven annotation structure:
+
+| Annotation Type     | Format                             | Example                                                 |
+| ------------------- | ---------------------------------- | ------------------------------------------------------- |
+| Spacing override    | `[spacing] value — reason`         | `[spacing] 24px — extra breathing room for icon weight` |
+| Conditional display | `[condition] rule`                 | `[condition] visible when notifications.length > 0`     |
+| Responsive change   | `[breakpoint] behavior`            | `[breakpoint] <768px: stack vertically, full-width`     |
+| Truncation          | `[truncation] rule`                | `[truncation] 2 lines, ellipsis, tooltip on hover`      |
+| Interaction         | `[interaction] trigger — behavior` | `[interaction] long press — reveal drag handle`         |
+| Accessibility       | `[a11y] requirement`               | `[a11y] aria-live="polite" for new notification count`  |
+
+Keep annotations terse. An annotation is a pointer to a decision, not an essay. If the rationale is complex, the annotation should reference the corresponding decision entry: `[spacing] 24px — see D4 in DESIGN.md`.
+
+### Living Documentation Strategies
+
+**Strategy 1: Code-adjacent documentation.** Place a `DESIGN.md` in the same directory as the feature code. When a developer opens the feature directory, the design rationale is right there. This is the approach used by many open-source design systems including Primer (GitHub) and Polaris (Shopify). The documentation is reviewed in the same PR as the code, ensuring they stay synchronized.
+
+**Strategy 2: Storybook as living spec.** Each Storybook story can include a "Design" tab (using the `@storybook/addon-designs` plugin) that embeds the Figma frame, plus a "Documentation" tab (using MDX) that contains usage guidelines, dos/don'ts, and decision rationale. The component, its visual spec, and its documentation coexist in the same tool. When the component changes, the Storybook story changes, and the documentation mismatch becomes immediately visible.
+
+**Strategy 3: Token-driven documentation.** When design tokens are the source of truth, the token file itself becomes the documentation. A token like `color.action.primary.default: #0066FF` with a description field `"Primary action color — used for all primary buttons, links, and interactive elements. Do not use for informational or status indicators."` is both implementation and documentation. Tools like Style Dictionary can generate documentation sites directly from token files.
+
+### Decision Log Maintenance
+
+Decision logs rot when they are append-only with no review cycle. Implement a quarterly review where each decision is re-evaluated:
+
+- **Still valid?** Keep it, add a "reviewed YYYY-MM-DD" note
+- **Outdated?** Mark as `deprecated` with the date and reason
+- **Wrong?** Mark as `superseded by D[n]`, write the new decision, and update the implementation
+
+### Anti-Patterns
+
+1. **The Screenshot Graveyard.** Dropping PNG screenshots into a wiki page with no context, no annotations, and no update mechanism. Within weeks, the screenshots diverge from the implemented UI. Within months, nobody knows if the screenshot represents the intended design or a legacy version. Screenshots without version numbers, dates, and associated decision entries are noise, not documentation. Use linked Figma frames or automated visual regression screenshots instead.
+
+2. **Tribal Knowledge Masquerading as Documentation.** "Ask Jordan, they know why we did it that way." This is not documentation — it is a single point of failure. When Jordan leaves, the rationale leaves with them. Every design decision that lives only in someone's head must be extracted and written into DESIGN.md. A good test: if every designer and developer on the team were replaced tomorrow, could the new team understand every design decision from the documentation alone?
+
+3. **The Specification Novel.** A 40-page spec document that describes every pixel in prose, updated by one person, read by nobody. Long-form spec documents have a half-life of about two sprints before they diverge from reality. Keep specs modular (one DESIGN.md per feature), terse (use tables and token references, not paragraphs), and reviewable (small enough to review in a PR diff). If a spec takes more than 10 minutes to read, it is too long.
+
+4. **Documenting What, Not Why.** "The button is blue" is not a design decision — it is a description. "The button is blue (color.action.primary) because blue tested 18% higher in task completion than green in our A/B test (2024-Q2), and aligns with our brand palette where blue signals interactivity and green signals success/completion" is a design decision. Documentation without rationale is just a less efficient way to read the CSS.
+
+5. **Post-Hoc Documentation.** Writing design documentation after the feature ships, reconstructing rationale from memory. By that point, the alternatives considered are forgotten, the trade-offs are rationalized, and the documentation reads like a justification rather than a decision record. Document decisions when they are made, in real time, as part of the design process — not as a cleanup task after launch.
+
+### Real-World Examples
+
+**Stripe's Component Documentation.** Every component in Stripe's internal design system includes: a usage description, a "When to use / When not to use" section, a props table with types and defaults, a state matrix showing all visual states, a "Design decisions" section recording why the component looks and behaves the way it does, and a changelog linking each visual change to the research or feedback that motivated it. This documentation is generated partially from code (props table, state matrix) and partially maintained by hand (rationale, usage guidance), striking a balance between automation and human insight.
+
+**GitHub Primer's ADR System.** Primer uses Architecture Decision Records for design system decisions. ADR-001 might record "Use CSS custom properties for theming" with full context on why CSS-in-JS was rejected (build complexity, runtime cost) and why Sass variables were superseded (no runtime theming). Each ADR is a markdown file in the repository, reviewed in PRs, and cross-referenced from component documentation. When a developer asks "Why don't we use styled-components?", the answer is a link, not a debate.
+
+**Apple's Human Interface Guidelines as Living Documentation.** The HIG is the gold standard for design documentation at scale. Every component has: a description of its purpose, platform-specific usage guidance (iOS vs macOS vs watchOS), a "Best practices" section that functions as a decision log ("Use action sheets instead of alerts when offering more than two choices"), specific measurements and spacing values, and accessibility requirements. The HIG is updated with every OS release, with change annotations marking what is new. It demonstrates that documentation can scale to thousands of components across multiple platforms without becoming unreadable.
+
+**Material Design's Documentation Structure.** Material Design 3 documents each component with: an overview, anatomy diagram (labeling every visual element), usage guidelines, specs (exact dimensions, spacing, elevation), states (with visual examples of each), accessibility notes, and implementation guidance per platform (Android, iOS, Web, Flutter). The documentation is generated from a single source and published to multiple formats. Every specification includes the design rationale — not just "the FAB is 56dp" but why 56dp is the minimum touch target that balances reachability and visual prominence.
+
+## Source
+
+- Keeling, M. — _Design It!_ (2017), documenting design decisions in software
+- Nygard, M. — "Documenting Architecture Decisions" (2011), the original ADR format
+- Apple — Human Interface Guidelines, https://developer.apple.com/design/human-interface-guidelines/
+- Material Design — Component documentation format, https://m3.material.io/components
+- GitHub Primer — ADR process, https://primer.style/
+
+## 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-design-documentation/skill.yaml

@@ -0,0 +1,33 @@
+name: design-design-documentation
+version: "1.0.0"
+description: Documenting design decisions — design rationale, spec handoff, annotating designs, living documentation, decision logs, the DESIGN.md format
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-design-governance
+  - design-brand-consistency
+stack_signals: []
+keywords:
+  - documentation
+  - design-rationale
+  - spec-handoff
+  - annotations
+  - decision-log
+  - DESIGN-md
+  - living-documentation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,187 @@
+# Design Governance
+
+> Living system maintenance covering contribution models, deprecation processes, versioning strategies, adoption metrics, and documentation standards for treating a design system as a product.
+
+## When to Use
+
+- Launching a design system and need a governance structure before the first external contribution
+- A design system has grown past 30 components and informal processes are breaking down
+- Teams are forking components instead of contributing back, creating drift
+- Planning a breaking change and need a deprecation strategy that does not strand consumers
+- Leadership asks "is the design system working?" and you have no metrics to answer
+
+## Instructions
+
+A design system without governance is a component library with an expiration date. Governance is the set of processes that keep a design system alive, coherent, and adopted as it scales across teams, products, and years. It answers five questions: Who can change the system? How do changes get approved? How do breaking changes propagate? How do we measure health? How do we document everything?
+
+**The governance maturity model:**
+
+1. **Ad hoc (1-10 components).** One team owns everything. Changes happen in PRs. Documentation is README files. This works for 6-12 months.
+2. **Defined (10-50 components).** Contribution guidelines exist. A review board approves additions. Versioning follows semver. Migration guides accompany breaking changes.
+3. **Managed (50-200 components).** Dedicated design system team. Formal RFC process. Automated adoption metrics. Deprecation timelines enforced. Multi-product support.
+4. **Optimized (200+ components).** Community-driven contributions. Automated visual regression. Self-service documentation. Design system as internal product with roadmap, OKRs, and user research.
+
+Most systems stall at level 1. The goal of this document is to help you reach level 2 early and level 3 within the first year.
+
+## Details
+
+### Contribution Models
+
+A contribution model defines who can propose, implement, and approve changes to the design system.
+
+**Centralized model:** A dedicated design system team owns all code. Product teams submit requests; the DS team prioritizes and implements. Used by Stripe (small, senior DS team controls all changes to the shared library).
+
+- Advantages: Consistency, quality control, single source of truth.
+- Disadvantages: Bottleneck. Product teams wait weeks for component additions. Resentment builds.
+
+**Federated model:** Product teams implement components and submit them to the system. The DS team reviews, provides feedback, and merges. Used by Atlassian (product teams contribute to `@atlaskit` packages through a structured RFC and review process).
+
+- Advantages: Scales with organization size. Product teams feel ownership.
+- Disadvantages: Quality variance. Contributions may not generalize well. Review burden on DS team.
+
+**Hybrid model (recommended):** The DS team owns core atoms and molecules. Product teams contribute organisms and patterns through a defined process. Used by Salesforce Lightning and IBM Carbon.
+
+**Salesforce Lightning's contribution workflow:**
+
+1. Contributor opens an RFC issue describing the component, its use cases, and proposed API.
+2. DS team triages within 5 business days: accept, request changes, or defer.
+3. Accepted RFCs enter a design review (Figma spec + accessibility checklist).
+4. Implementation follows the DS team's coding standards, submitted as a PR.
+5. DS team reviews code for token usage, accessibility, documentation, and test coverage.
+6. Merged components enter a 30-day beta period before stable release.
+
+**IBM Carbon's community contribution model** is fully open-source. External contributors submit components through GitHub PRs. Carbon's team maintains a "Component Status" board showing every component's lifecycle stage: proposed, draft, experimental, stable, deprecated. Each transition requires explicit approval from a Carbon maintainer.
+
+### Deprecation Process
+
+Deprecation is the most underinvested governance area. A component or token that is removed without a migration path breaks consumer trust permanently.
+
+**The deprecation lifecycle:**
+
+| Phase        | Duration           | Actions                                                                                                      |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **Announce** | Release N          | Add `@deprecated` JSDoc tag. Add console.warn in dev mode. Update docs with migration guide.                 |
+| **Warn**     | Release N+1 to N+2 | Console.warn in dev and production. Codemod published (if feasible). Adoption metrics track remaining usage. |
+| **Remove**   | Release N+3        | Component removed from package. Import fails with descriptive error message pointing to replacement.         |
+
+**Minimum deprecation window:** 3 minor releases or 6 months, whichever is longer. Atlassian enforces a 12-month deprecation window for any component with more than 10 consumer teams.
+
+**Deprecation artifacts (all required):**
+
+1. **Migration guide:** Step-by-step instructions showing old code, new code, and edge cases. Not "use ComponentB instead" but the exact prop mapping, slot changes, and behavior differences.
+2. **Codemod (when feasible):** An automated transform (using jscodeshift, ts-morph, or similar) that converts old usage to new. GitHub Primer publishes codemods for every component migration.
+3. **Adoption dashboard entry:** A live counter showing how many files/instances still use the deprecated component, per consuming team.
+
+**Salesforce Lightning deprecation example:** When `lightning-card` v1 was replaced by v2, Salesforce published a migration guide with 14 before/after code examples covering every prop and slot change. They provided a codemod that handled 80% of migrations automatically. The remaining 20% (custom slot content) received dedicated office hours from the DS team.
+
+### Versioning Strategy
+
+Design systems must version thoughtfully because their consumers are internal teams who cannot choose to skip a version.
+
+**Semantic versioning applied to design systems:**
+
+- **Major (X.0.0):** Breaking changes to component APIs, token removals, fundamental layout changes. Requires migration guide.
+- **Minor (0.X.0):** New components, new variants, new tokens. No existing API changes. Safe to upgrade without code changes.
+- **Patch (0.0.X):** Bug fixes, visual corrections, documentation updates. No API changes.
+
+**What counts as a breaking change in a design system:**
+
+- Removing a prop, token, or component
+- Renaming a prop, token, or component
+- Changing a prop's type (string to enum, optional to required)
+- Changing default values that affect layout (default size from `md` to `lg`)
+- Changing token values that affect contrast ratios (WCAG compliance boundary)
+
+**What does NOT count as breaking:**
+
+- Adding a new optional prop with a sensible default
+- Adding a new component
+- Adjusting visual properties that do not affect layout (changing a shadow's blur radius by 1px)
+- Adding a new token
+
+**Material Design's versioning approach:** M1 to M2 was a full rewrite (major). M2 to M3 introduced new components alongside old ones with a gradual migration path. Google maintains both M2 and M3 component libraries simultaneously, allowing product teams to migrate on their own timeline. This dual-support model costs engineering resources but prevents forced migration crises.
+
+**Multi-package versioning:** Large systems (Atlassian, IBM Carbon) version individual packages independently. `@atlaskit/button` at v16 while `@atlaskit/modal-dialog` is at v12. This allows granular upgrades but requires a compatibility matrix. Atlassian maintains a public "Supported Combinations" page listing which package versions are tested together.
+
+### Adoption Metrics
+
+"Is the design system working?" requires quantitative answers. Track these metrics:
+
+**Coverage metrics:**
+
+- **Component adoption rate:** Percentage of UI instances in product code that use DS components vs custom implementations. Target: >80% after 12 months. Salesforce measures this by scanning product repos for `lightning-*` imports vs raw HTML elements.
+- **Token adoption rate:** Percentage of color, spacing, and typography values that resolve to DS tokens vs hardcoded values. Target: >90%. IBM Carbon runs a Stylelint rule that flags any non-token CSS value.
+- **Page coverage:** Percentage of pages in the application that use at least one DS component. Target: 100%.
+
+**Health metrics:**
+
+- **Contribution velocity:** Number of community-contributed components merged per quarter. Atlassian targets 3-5 per quarter from outside the DS team.
+- **Issue resolution time:** Median time from bug report to fix release. Target: <2 weeks for accessibility issues, <4 weeks for feature requests.
+- **Deprecation compliance:** Percentage of deprecated components removed by the deadline. Target: 100%.
+
+**Satisfaction metrics:**
+
+- **Developer satisfaction (quarterly survey):** "How easy is it to build UIs with the design system?" on a 1-5 scale. Target: >4.0. Shopify Polaris runs this survey and publishes results internally.
+- **Designer satisfaction:** "How well does the Figma library match the code library?" Target: >4.0.
+- **Onboarding time:** Time for a new developer to ship their first feature using the DS. Target: <1 day with documentation, <3 days without.
+
+**Atlassian's adoption dashboard** is a live internal tool that shows per-product adoption rates, broken down by component. Product teams see their adoption percentage on a leaderboard. Teams below 70% adoption receive a quarterly nudge from the DS team with an offer of pairing sessions.
+
+### Documentation Standards
+
+Documentation is the design system's user interface. If the docs are bad, the system is bad -- regardless of code quality.
+
+**Required documentation per component:**
+
+1. **Overview:** One paragraph describing what the component is and when to use it. Not how it works internally, but what problem it solves for the consumer.
+2. **Interactive examples:** Live, editable code examples showing every variant, size, and state. Storybook or a custom playground. Not screenshots.
+3. **Props/API table:** Every prop with name, type, default, required/optional, and a one-sentence description. Auto-generated from TypeScript types.
+4. **Accessibility:** Which ARIA roles and properties the component uses. Keyboard interaction pattern. Screen reader announcement behavior. Tested with VoiceOver/NVDA/JAWS.
+5. **Design guidelines:** When to use this component vs alternatives. "Use Card for grouped content. Use Banner for page-level messages. Do not use Card as a button -- use ActionCard instead."
+6. **Migration notes (if applicable):** What changed from the previous version and how to upgrade.
+
+**Shopify Polaris documentation structure:** Every component page has four tabs: Examples (interactive), Props (auto-generated), Accessibility (manual), and Best Practices (design guidelines with Do/Don't image pairs). Their "Best Practices" tab averages 5-7 rules per component with visual examples of correct and incorrect usage.
+
+**Apple Human Interface Guidelines** serve as the canonical example of governance-level documentation. Each component has: purpose statement, platform availability matrix, configuration options with visual examples, and behavioral guidelines ("A toggle should take effect immediately without requiring a save action"). Apple updates the HIG in sync with every OS release.
+
+### Anti-Patterns
+
+**Governance by committee.** A review board of 12 people that meets monthly and takes 3 months to approve a new component. Governance should enable speed, not prevent it. Atlassian's solution: a 3-person rotating review panel with a 5-day SLA. Any 2 of 3 can approve. Deadlocks escalate to the DS lead.
+
+**Documentation as afterthought.** "We will document it after the component is stable." Stable components without documentation are invisible to consumers. Salesforce Lightning requires documentation to be part of the PR -- a component cannot merge without its doc page, examples, and accessibility section complete.
+
+**Silent deprecation.** Removing a component in a minor release without warning, migration guide, or codemod. This trains consumers not to upgrade, because upgrades are dangerous. Every removal MUST follow the deprecation lifecycle: announce, warn, remove.
+
+**Vanity metrics.** Tracking "number of components in the system" as a success metric. A system with 200 poorly designed components is worse than one with 40 excellent ones. Track adoption and satisfaction, not inventory size.
+
+**Forking tolerance.** Allowing product teams to fork DS components into their codebases "temporarily" without a plan to merge back. Every fork that lasts more than one sprint becomes permanent. IBM Carbon addresses this by requiring fork requests to include a "merge-back plan" with a deadline. Forks without merge-back plans are denied.
+
+### Real-World Examples
+
+**Salesforce Lightning Design System** is the gold standard for enterprise design system governance. They maintain a public contribution guide, a structured RFC process, a deprecation policy with 6-month minimums, automated adoption scanning across 100+ internal products, and a dedicated documentation team. Their "Component Blueprint" format is a template that every new component must follow before review begins.
+
+**IBM Carbon** operates as an open-source design system with governance that supports both IBM internal teams and external community contributors. Their GitHub repository has 3,500+ stars, 900+ contributors, and a maintainer team of 15. They use GitHub Projects for roadmap visibility, label-driven triage, and a "good first issue" program for onboarding new contributors. Every component has a lifecycle status badge on its documentation page.
+
+**Atlassian Design System** governs a multi-product design system serving Jira, Confluence, Trello, Bitbucket, and 10+ other products. Their "Design System Council" (3 designers + 3 engineers, rotating quarterly) reviews all component proposals. They publish adoption metrics per product, run quarterly developer satisfaction surveys, and maintain a "Design System Health" internal dashboard that surfaces components with low adoption, high bug counts, or missing accessibility coverage.
+
+**Apple Human Interface Guidelines** represent governance through documentation authority. Apple does not accept community contributions to their design system, but their governance model -- centralized ownership, exhaustive documentation updated in sync with platform releases, strict deprecation through SDK versioning -- has maintained consistency across 40 years of products. Their "Designed for iPad" and "Designed for iPhone" badges are adoption metrics: apps that do not follow HIG guidelines do not receive Apple's endorsement.
+
+## Source
+
+Brad Frost, "Design Systems are for People" (2019). Nathan Curtis, "The Design System Product" (2020). Jina Anne, "Design Tokens and Theming" (2019). Dan Mall, "Design System in 90 Days" (2022). Salesforce Lightning Design System Governance documentation. IBM Carbon Design System Contribution Guidelines. Atlassian Design System 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.