SKILL.md
Design Rationale
A design rationale document captures the "why" behind design decisions.the context, constraints, alternatives considered, and reasoning that led to a particular solution. While designs themselves show what was built, rationale documents preserve institutional knowledge about why it was built that way.
When to Use
- When making significant UX decisions that affect user experience
- Before design reviews to prepare stakeholder discussions
- When multiple valid approaches exist and the choice needs justification
- To onboard new team members to existing design decisions
- When revisiting past decisions to understand original reasoning
- During design system evolution to document pattern choices
When NOT to Use
- The decision is architectural or a technology selection -> use
develop-adr(Nygard format) - You need stakeholder alignment on the overall solution direction -> use
develop-solution-brief - You are documenting exploration findings rather than a decision -> use
develop-spike-summary - The decision is trivially reversible and low-stakes: a rationale document adds ceremony; record the reasoning in the PR or ticket instead