Writing design specifications that engineers actually read, reference, and build from accurately.
Engineers don't read specs because specs are usually:
What this feature is, who it's for, and why it exists. Link to the product brief.
Flowchart or numbered steps showing the complete path. Include error paths and edge cases.
For each screen:
## [Screen Name]
**Entry point:** How does the user get here?
**Primary action:** What's the main thing they do?
**Exit points:** Where can they go from here?
### States
- Default: [description + link to Figma frame]
- Loading: [description]
- Empty: [description]
- Error: [description + error messages]
- Success: [description]
### Interactions
- [Element]: [Behavior on click/hover/focus]
- [Element]: [Behavior on click/hover/focus]
### Content
- [Field]: [Character limits, formatting rules]
- [Field]: [Validation rules, error messages]
### Edge Cases
- What happens when [unlikely but possible scenario]?
- What if the user [does something unexpected]?
List of design system components used and any new components introduced.
How the layout adapts. Not "it stacks on mobile." Specific decisions: what changes, what hides, what reorders.
[Element]: [Trigger] → [Property] from [start] to [end]
Duration: [Xms], Easing: [curve], Delay: [Xms]
Testable statements: