Make an Open Design design system from a website: measure the rendered site, write DESIGN.md and tokens.css from one set of measurements, and check the result against the site before saving it.
Request: the rest of the user's message (if there is none, ask the user: "Which website should the design system come from?")
How to talk to the user. Many people using Open Design don't write code, so:
- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
- Keep the machinery out of replies: no tool names, no ids like
od:prototype:poster-hero, no internal files (.artifact.json,.comments.json,config.json), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first. - Explain a print term the first time it comes up, in one short clause, and not again.
- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
| Instead of | Say |
|---|---|
| artifact, entry, registered | your design, saved |
| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
| surface, skill, template, recipe | kind of design, starting layout, or nothing |
| workspace, output directory | your folder, your Open Design folder |
| bleed | print edge ("a few millimetres extra that the printer trims off") |
| trim size | final size |
| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
| export | save as PDF, save as an image |
| inline preview, MCP App | the preview above |
1. Ask only what's missing
Three things decide the run. Take each from the request when it says so, and ask only about the ones it leaves open, in one message:
- The address (and, optionally, up to 3 more pages on the same site, such as a pricing or product page).
- Light, dark or both. Default to light if the user doesn't care.
- Their own brand, or a reference? For a reference site the design system is named "-inspired" and no logos or images are copied.
If the request already answers all three ("make a dark design system from https://example.com, it's our brand"), ask nothing and go straight on.
2. Measure the site
Call extract_open_design_design_system with url, extraUrls if there are any, and theme.
ok: you get adraft(contract tokens, a[data-theme="dark"]set only if the site has a dark theme),sourcessaying which element each value came from, theunmeasuredtokens, and the screenshot. Look at the screenshot and the role crops in the evidence bundle before writing anything.partial(no browser installed): only candidate colours and fonts from the page source. Tell the user, show the candidates, and ask them to confirm the brand colour and font, or to install Chrome for a full measurement.blocked: show the user the screenshot and the reason. Ask for the site's CSS, a screenshot of the page they mean, or another public page. Don't retry the same page.- An invalid-args error (a private address, an extra page on another site): tell the user what was refused and why.
If the user asked for dark and the result notes that no dark theme was found, say so. Don't invent dark values.
3. Write both files from the draft
Call create_open_design_design_system with a name (for a reference site, "-inspired") and a brief describing the site in a sentence. Don't pass sourceUrl: you have better measurements already. It returns the suggestedEntryPath, the id and the token contract.
Write DESIGN.md at suggestedEntryPath and tokens.css beside it, both from the same draft:
tokens.css: start fromdraftCss. Keep every measured value exactly as measured. For anunmeasuredtoken, leave it out so the contract fallback applies, or derive it from measured ones (acolor-mix()of--accentfor a missing hover); never make one up, and don't fill two steps with the same value.- Sanity-check each role against the screenshot first. If a measured value plainly can't be that role (text that would be unreadable on
--bg, a hairline as a spacing step), drop it and say so; don't write prose to explain it away. DESIGN.md: the values it names (primary colour, surface, text, the font families, the type scale) must be the same values astokens.css. Write the prose (atmosphere, layout, components, voice, do and don't) from the screenshots. For a reference site, say near the top that it is inspired by the site and name it.- Marks: for the user's own brand, copy the files in the result's
marksinto anassets/folder besideDESIGN.mdand mention them there. For a reference site, copy none.
4. Review it side by side
Write a review page next to the design system as review.html, and register it with register_open_design_artifact. One page, two columns:
- Left, "The site": the desktop screenshot from the evidence bundle (an
<img>with a relative path to it), cropped withobject-fit: coverto the top 900px. - Right, "The design system": a sample page that uses only the new
tokens.css(<link rel="stylesheet">to it, or its:rootblock inlined): a hero with a heading and a primary and secondary button, a card with text, and a form row with a label, an input and a button.
Call check_open_design_artifact on it. Compare the two columns yourself (colours, font, button shape, density), fix anything that's clearly off, then show the user the review and ask whether it matches.
Apply what the user says ("the buttons are rounder on the site" → raise the radius tokens) in both files, rebuild the review and check again. Stop after two rounds of fixes: save then, and list anything still open.
5. Save
Call set_active_design_system with the returned id if the user wants to design with it now (offer it). Tell the user the design system's id and where its files are, and that the measurements are kept in the evidence bundle.
