Design doc
Write a design doc, design spec, or feature documentation that engineers will actually read and use. Use when the user needs to document a design decision, write a feature spec, prepare for design hand-off, or capture decisions for a postmortem-ready record.From its SKILL.md
npx -y skills add rafa-js/product-designer --skill design-docAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.9 KB, as published. Nobody here has run it
Design Doc
Docs are how design ships when you're not in the room. Keep them short enough to read, complete enough to build from.
Inputs to confirm
- What's being documented: a feature, a system change, a design decision, a hand-off package.
- Audience: engineers (most common), PMs, leadership, future maintainers.
- Stage: design in progress (living doc), pre-implementation (hand-off), post-ship (record).
- Existing artifacts: link to Figma file, research notes, related tickets.
Method
Template (one screen of structure, even if the content runs longer)
# [Feature name]
## TL;DR
[3 sentences max. What's changing, who it's for, why now.]
## Problem
[The user pain or business goal, with evidence — link to research, support tickets, or data.]
## Goals & non-goals
**Goals**
- ...
**Non-goals** (explicit out-of-scope)
- ...
## Solution overview
[One hero screen or short paragraph + a sentence each on the major moves.]
## Flows
[Link to the interaction flow diagram or embed a small one.]
## States
Empty / loading / error / edge cases — explicit list.
## Open questions
[Listed so engineers know what's still in flux.]
## Decisions log
[What we considered, what we picked, what we rejected, why. Living section.]
## Hand-off
- Figma file: [link]
- Engineering ticket: [link]
- PM ticket: [link]
- Owner: [name]
## Definition of done
[Specific shippable criteria.]
See references/07-deliverables/design-documentation.md for full guidance.
What goes in the doc vs. the file
- Doc: intent, decisions, tradeoffs, open questions, edge cases.
- Figma file: screens, components, redlines (only when needed), per-artboard interaction notes.
Don't duplicate. Cross-link.
What gets cut
- Lengthy persona descriptions if you already have a personas doc — link to it.
- Marketing-style framing for an internal doc.
- "Comprehensive" sections that nobody will read.
- Decision rationale you can't articulate — if you can't say why, the decision isn't ready.
Review pattern
- Async first: post the doc, allow 48 hours for comments, then meet only on unresolved items.
- Comment threads beat doc edits — discussion preserved.
- Resolve every comment before marking the doc reviewed.
- Definition of "reviewed": doc read, comments resolved, link added to engineering ticket.
Maintenance
- Update the decisions log as decisions are made.
- Mark sections
[outdated]rather than silently deleting — readers benefit from knowing what changed. - Archive when the feature ships; keep a permalink for postmortems.
Output formats
When writing a doc for the user:
- For features: use the full template above.
- For a single decision (RFC-style): TL;DR · Context · Options considered · Decision · Consequences.
- For hand-off only: short TL;DR · Flows · States · Definition of done · Asset links. Skip the rationale; assume it's elsewhere.
When to recommend a different artifact
- A design choice debated across multiple stakeholders → recommend an RFC (one decision, options, recommendation) rather than a feature doc.
- A pre-mortem or risk assessment → recommend a separate risk doc rather than padding the feature doc.
- A retrospective → recommend a postmortem doc template; don't backfill into the design doc.
Anti-patterns
- 40 pages no one reads past page 3.
- Beautiful design docs in tools engineers don't open.
- Pixel-perfect details documented; states/edge cases skipped.
- Decisions documented after the fact — engineers don't know why and deviate.
- Status updates inside the design doc instead of in the ticket.