web-design makes Claude Code write DESIGN.md before it writes markup

Why a spec document comes before the first line of HTML

web-design is not a UI component library or a starter template. It is a SKILL, the format Claude Code uses for packaged instructions, and its entire premise is the ordering of work: spec first, code second. The argument behind it is a familiar one about consistency. When a page is generated directly from a prompt, spacing, colour and type drift between sections of the same site, and the drift is invisible until someone looks at two screens side by side. Routing the work through a written specification first gives the generator a single source of truth to follow and gives a human reviewer a document to argue with before any code exists. The audience is people who build pages with Claude Code and who have been disappointed by the consistency problem, and the second audience is people who want the design decisions recorded as text rather than as an implicit property of generated markup.

Phase A reads a PRD, a URL or a screenshot

The first phase is understanding, and it accepts several kinds of input: a PRD, a reference URL, a screenshot, keywords, or a brand name, in any combination. The README describes a graceful fallback chain, which means the skill keeps working when the input is sparse, for example when you give only a brand name and let it infer the rest. That is a reasonable design for a tool whose users arrive with wildly different levels of preparation. The same phase also handles the case where a reference URL is present, and that fact is not forgotten later: the code generation phase performs a diff audit when a reference URL exists, comparing what it built against the site you pointed at. The scripts directory supports this phase with a Playwright crawler for pulling information from a reference page and a static token extractor for pulling design tokens out of an existing codebase or page.

Phase B produces a nine section DESIGN.md you approve first

The second phase writes the deliverable that matters: a DESIGN.md containing a full nine section specification, covering colour, type, components, layout, motion, depth, do's and don'ts, responsive behaviour, and accessibility. Those nine headings are the whole point of the project, because they turn taste into a checklist that a generator can be held to and that a person can edit. The workflow requires your approval before it moves on, and once approved the spec lives in your project, where it can be edited by hand. That hand-edit step is what makes the tool different from a one-shot generation, since the file is deliberately a plain, readable, portable Markdown document. The repository demonstrates the pattern on itself: the landing page in docs/ has its own DESIGN.md, and the README says it was produced by the SKILL itself.

Phase C generates code against the spec, then audits what it produced

The third phase writes the web code, and the README states that it follows the spec strictly. Two audits sit on top of that generation. The first is a self-audit against a quality checklist with a score out of 100, and the checklist itself lives in the references/ directory alongside design systems, style seeds, a motion library and interaction patterns. The second is the diff audit, which only applies when you supplied a reference URL. The honest limitation of both is that they are self-assessed. The scoring is produced by the same system that produced the page, and there is no documented threshold at which a failing score stops the run. What the audits do give you is a place to look: a score and a diff are things a reviewer can disagree with, which is a better position than a page with no explanation attached.

Installing the skill into ~/.claude/skills and serving the demo page

Installation is a clone into your Claude Code skills directory. Claude Code then discovers the skill automatically at the start of the next session, which means there is no registration step and no plugin to enable.

git clone https://github.com/KAOPU-XiaoPu/web-design ~/.claude/skills/web-design

The repository also ships its own landing page under docs/, with index.html, styles.css and app.js, and the README gives a way to serve it locally with the Python standard library. You need the HTTP origin, because the page pulls in Google Fonts and an OGL ES module, and the README says that opening index.html directly with a file:// URL will not work.

cd web-design/docs
python3 -m http.server 8000
# open http://localhost:8000

The scripts and references directories are the parts you will touch first

The repository is small at the top level: SKILL.md, references/, scripts/, docs/, README.md and LICENSE. Everything except the landing page is instruction content for the model. SKILL.md holds the instructions themselves, references/ holds the design systems, style seeds, motion library, interaction patterns and the quality checklist the audit uses, and scripts/ holds the tooling the skill can run: a Playwright crawler, a static token extractor and an Unsplash image fetcher. Two things follow from that layout. First, the scripts are the only executable parts, so they are also where dependencies live, and the README does not document an install step for the Playwright crawler or for anything the image fetcher needs. Second, because the references are plain files in the repository, editing them is a supported way to change the behaviour of the skill without touching code.

MIT licensed, with a landing page built on borrowed motion work

The licence is MIT, and the README states it plainly: use it, fork it, ship it. There is no copyleft obligation, so a team can fold the skill into an internal toolchain without publishing changes. The README also credits the motion effects on the landing page, which derive from work by David Haz under the MIT licence, specifically the vue-bits project for GradientBlinds and RollingGallery and react-bits for DomeGallery. The structure of the DESIGN.md document itself draws inspiration from awesome-design-md, also under MIT. On maintenance, the picture is thin rather than busy: the project has a single release, v0.1.0 dated 2026-04-16 and described as the initial public release, and the last push was on 2026-06-24. The repository is not archived, so the project is not dead, but a version 0.1.0 with one tag tells you to expect the file format and the checklists to change.

Editorial conclusion

web-design fits teams and solo builders who want a written design specification before code exists, and who are willing to review a spec before it is turned into markup, since the approval step in Phase B is the part that makes the output consistent. It is the wrong tool if you have no Claude Code session, if you need a design system that already exists to be obeyed rather than rediscovered, or if you want a finished site with no human in the loop. Before adopting it, clone the repository into your skills directory, run it once against a real PRD and check that the generated DESIGN.md matches your existing conventions, and expect to edit that file by hand, since the README states the spec lives in your project and can be edited by hand. Maintenance is thin: the project has one release, v0.1.0 from 2026-04-16, and the last push was on 2026-06-24.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xiaopu-ai/web-design on GitHub