What a useful design.md should explain
A design.md file gives an agent the visual and interaction rules it cannot safely infer from a screenshot. It should explain the product’s typography, color roles, spacing, component conventions, and boundaries, then point to the implementation that supports those decisions. Its value comes from specific, current guidance rather than its filename.
TDP’s design.md and component-library walkthrough uses a public repository to inspect existing tokens and generate an initial document. The important second step is review: correct inaccurate rules and connect the document to deeper component metadata. A file containing a palette and font names will not explain which action belongs in a destructive confirmation dialog.
Use this guide when your agent produces plausible UI that does not follow your product. If the product itself has no agreed visual rules, first decide a small baseline with your designer and engineer. Automatically describing an inconsistent interface can preserve the inconsistency instead of resolving it.
Step 1. Choose a screen that represents the product
Pick a frequently used screen with text, actions, and inputs. Record its purpose and the decisions a person makes there. A settings screen is a useful sample because it exposes typography, spacing, validation, and component states together. Include an error state; a pristine mockup hides many of the rules a tool will need.
Step 2. Extract the rules that already exist
Inspect the implementation and design file together. List the actual token names, font families, spacing values, and component imports. Mark disagreements for a decision. Do not quietly turn an inconsistent implementation into a new system: your first document should distinguish approved rules from unresolved work.
Step 3. Write the design.md specification
Use semantic roles so readers understand when a value applies. The following is a starter example, not a universal prescription. Replace the paths and values with verified ones from your product.
# Product design rules
## Product
A workspace for teams reviewing customer requests.
Prioritize scanning, clear status, and explicit next actions.
## Sources
Tokens: src/styles/tokens.css
Components: src/components/ui/
## Typography
Body: 16px / 1.5, regular. Labels: 14px / 1.4, medium.
Use the product font; do not introduce another family.
## Components
Use the shared Button and Field components.
Destructive actions need confirmation and a clear consequence.
## Constraints
Use semantic tokens. Preserve visible keyboard focus.
Do not communicate errors through color alone.
## Open decisions
Confirm compact table spacing with the product team.
Step 4. Make the file discoverable
Save it beside the product source and point to it from the context entry point your agent supports. Ask the agent to name the files it read before editing. A file called design.md is not automatically loaded by every tool. Use your tool’s documented context mechanism and verify the result.
Step 5. Run a small acceptance check
Ask for one settings form using the documented components. Compare the output with your reference: token usage, spacing, text hierarchy, validation, and focus. If the tool invents a button, check whether the component path and allowed variants were explicit. Add the missing rule only after confirming it is correct.
Worked example: turn a vague instruction into a usable rule
Suppose the initial file says “use our brand purple and keep the interface clean.” The agent still has to invent which purple, where it belongs, what a secondary action looks like, and how errors differ from brand accents. Replace subjective adjectives with a role, a source, and a boundary.
| Vague instruction | More useful replacement |
|---|---|
| Use purple | Use the existing action-primary token for the principal action in a decision group |
| Keep spacing consistent | Use the layout tokens exported by the theme; compare with the settings-form example |
| Use our buttons | Import Button from the public UI package; consult its contract for variants |
| Make it accessible | Preserve the component’s label, keyboard behavior, and visible focus; review the complete form |
The stronger version gives the agent something it can inspect. It also gives a reviewer a concrete way to disagree. If the specified import does not exist, that is a documentation defect to fix before the next task.
Keep the entry document thin, with depth one link away
TDP’s component-library article makes a useful distinction: system rules belong in the entry document, while the full component contract belongs near the component. Repeating every prop in design.md creates another copy that can become stale.
DESIGN.md
Product-specific visual principles
Token source and supported themes
Typography and layout roles
Component index
Button → implementation, contract, stories
Field → implementation, contract, stories
Open decisions and ownership
A component index should contain actual paths, not a list of aspirational components. If a pattern is planned but not implemented, label it that way. Keep current instructions separate from historical alternatives so an agent does not resurrect an abandoned design.
Test discovery as well as the generated screen
Run a task in a fresh session using the host’s documented repository-instruction mechanism. Ask the agent to name the design references it consulted before editing. This tests whether the document is discoverable without depending on the context from the session that created it.
Use a deliberately small task, such as adding a notification preference to an existing settings form. Compare the new row with adjacent fields: label style, control size, description spacing, focus treatment, and validation behavior. Then inspect the diff for new token values or duplicate controls.
If the output is wrong, classify the cause. Was the rule absent, ambiguous, contradictory, or ignored? Adding more text only helps the first three, and each needs a different edit. An ignored rule may require a better entry point or a stronger review check.
Maintenance and common mistakes
Update design.md when the team approves a system change, not whenever an agent happens to generate something different. A generated screen is a proposal until reviewed. Keep a short record of what changed and which implementation now demonstrates it.
Avoid treating a tool-specific format as a universal standard. Some tools have a prescribed design-file structure; others simply read Markdown through repository instructions. Follow the actual host documentation, and preserve useful native token formats rather than converting everything solely for appearance.
An effective review asks three questions: Can a new teammate locate the source? Can they apply the rule to a real screen? Can they tell what is unresolved? If all three answers are yes, the document is doing useful work.
For the next layer, use the component-contract guide and the product-context guide.
Completion checklist
- The brief describes the current product and audience.
- Token and component paths resolve to real files.
- Examples explain both values and intended use.
- Unknowns remain visible instead of becoming invented rules.
- A teammate can reproduce the test without extra verbal context.
Common questions
Should I put every component specification in design.md?
Keep shared principles in the entry document and link to detailed component specifications. Repeating every prop in two places creates maintenance work and conflicting answers.
How often should I update it?
Update it when an approved design rule changes. Include the documentation change in the same review as the implementation whenever possible.
Sources and TDP resources
- TDP’s design.md article explains the original workflow and examples.
- TDP product-context-builder skill helps organize repository context.