What you’ll make
A small DESIGN.md with rules you can try on one new screen.
Which button gets the plum?
An export screen that looks like Pocket Inventory
Say you ask Claude to make an export screen for Pocket Inventory. Your brand notes say ‘plum accent,’ so you get three plum buttons. Which one am I supposed to press to get my file? Here’s what I’d put in DESIGN.md before asking for another pass.
DESIGN.md excerpt
Give the main action its own treatment
- Filled plum goes on the action that finishes the task. On this screen, that’s ‘Download CSV.’
- ‘Cancel’ uses a neutral border. ‘Help with exports’ is an underlined text link.
Export screen trial
Check a real mistake and a narrow screen
- Put ‘Choose a file format’ under the Format field when someone skips it.
- At phone width, stack Download CSV above Cancel and keep the help link by Format.
Before you start
- Find two screens that look like your product today. Pull together the CSS or theme, logo files, font names and weights, and a few lines of copy you’d keep.
- Pick a small screen to try next, like a purchase confirmation. Look for one that needs some of the same buttons, headings, or messages.
Pick a screen and its sources
Choose a screen where Claude will need to make a real design choice. Gather one approved screen and the theme or component file if you have it.
Draft the rules in Claude
Copy the prompt below into Claude and attach the sources you picked. Tell Claude which source wins if two screenshots or files disagree, then send it.
Draft a small DESIGN.md from what I use today
Use the details I provide in this chat or in my attachments. Write a short DESIGN.md for my project using the source files or examples I provide. Include the few rules that matter for my trial screen. Say when each rule applies and point to the source for exact tokens or values. Include one example of the main action, a secondary action, and an error or focus state if supported by the sources. Flag conflicts and screenshot estimates. Ask before inventing any value or rule that changes the design.
Keep the rules that come from your project
Check the draft against your sources. Resolve any guesses and save the file as DESIGN.md beside the project it describes.
I give Claude Pocket Inventory’s settings screen and theme, then describe my CSV export screen.
My draft could say ‘Use filled plum for the action that finishes the task.’ The export example applies it to Download CSV and gives Cancel a neutral border.
Try one rule on the new screen
Sketch the screen or ask Claude to draft it using your saved file. If the main action still blends in, tighten that rule and try it again.
- Trace each exact value to an approved source.
- Check one decision on the new screen.
- Save DESIGN.md where you’ll find it on the next pass.
Optional: Give the rules another screen
Try the same file on a different screen that uses some of the same components. Add one approved example if the rules leave a choice open, then try again in a fresh chat.
Turn the screens I already have into design rules
Use your approved screens and source files to draft rules Claude can apply on another screen.
Help me write DESIGN.md for [project]. Here are the approved screens, theme and component files, logo assets, and copy examples: [files]. Use [source of truth] if the sources disagree, and follow [existing file format] if I provide one. If there’s a conflict I haven’t settled, show both values with their source and ask me which to use. Mark screenshot measurements as estimates. Draft the file with color roles tied to tokens or exact values, type sizes and line heights, spacing and narrow layout, and rules for [controls on my test screen]. For each control, say when to use it and how focus, disabled, and error states look where relevant. Include logo paths for light and dark surfaces and two real lines of copy. Add an open-questions list and point me to the source for each rule so I can verify it.
Use my DESIGN.md on one new screen
Once you approve the rules, attach the file and component sources to see which rules hold up on a new screen.
Use [approved DESIGN.md, components, and approved screen references] to make [small test screen] with [real copy and data]. Before building, list the rules you’ll use for actions, headings, forms, and the narrow layout. Flag choices the file leaves open. If the code or tool can’t produce a preview, give me a build spec I can use to make one. Show the result at [phone width] and [desktop width]. Compare action order, type, spacing, and one focus or error state with the approved screens. Give me a short table with the mismatch, the rule it used or guessed, and an exact DESIGN.md edit I can try on the second pass.
Optional worksheet: DESIGN.md worksheet
Fill this in as you go. Keep this page open while you work. Reloading it clears your answers.
Troubleshooting
Two approved screens use different values for the same role. Which one goes in the file?
Check the current theme first. Write down the value you want people to use. If one screen really needs a different value, name that screen and say when the exception applies.
The assistant follows the colors but the screens still feel unrelated. Where do I look?
Put the screens next to each other. Look at the heading sizes, how wide the text runs, the space between sections, and where the main button sits. Add an example with the actual spacing and sizes you want.