@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/design-design-audit/skill.yaml

@@ -0,0 +1,33 @@
+name: design-design-audit
+version: "1.0.0"
+description: Evaluating existing design — heuristic evaluation, consistency inventory, accessibility audit, competitive analysis, identifying design debt
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-design-critique
+  - design-design-governance
+  - design-consistency
+stack_signals: []
+keywords:
+  - audit
+  - heuristic-evaluation
+  - Nielsen
+  - consistency-inventory
+  - design-debt
+  - competitive-analysis
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/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/cursor/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/cursor/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/cursor/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: []