Build a portfolio site and design system that agents cannot drift from

Designer Blair Metcalf directed Claude Code through 175 changes in two weeks to build a portfolio on its own design system, with screenshot tests and doc-auditing agents that found 46 stale claims.

Done withClaude Code· Nov 3, 2026

What they did

Metcalf replaced a PHP portfolio from 2014 to 2023 with a design system and a site on top, built by directing Claude Code over two weeks. The agent got a private folder of 152 files: a resume, the old site, project notes and 104 images of past presentations, plus a voice guide it turned into writing rules. It asked questions four at a time with a recommended answer each, and showed three candidate looks as screenshots before any component existed. Colours, type and motion were given names by job, with the build failing on a raw colour value. Every component lives in Storybook with light and dark examples, which agents can query through Storybook's MCP server. A decision log of taste calls is read at the start of every session.

How it went

The site has case studies, a presentation, private pages, a small phone app and a public Storybook. Screenshot tests in both themes fail if more than 1% of pixels move; that caught a list that stopped folding after one link was removed. All 554 checks take about four minutes, so a script runs only the affected ones, 32 checks in 31 seconds for that change. The automated drift check passed, but three agents comparing about 255 doc claims to the code found 46 that did not match, including pages never pictured in dark mode and 36 pixel buttons under the 44 pixel tap rule.

Worth knowing

Not every rule is enforced: nothing checks that components use the named springs for motion, so that holds only through review. Reading the docs against the code with separate agents found problems the automated checks missed entirely. A UX designer and a content designer also reviewed the site by hand.

Try it

With Claude Code· 5 parts to fill in

Before writing any code, read everything in [my materials folder]. Ask me questions to fill the gaps, at most four at a time, each with your recommended answer first. Then show me three candidate looks for [my site] as screenshots and wait for me to pick one. While building, name every colour, size, shadow and motion by its job with a light and a dark value, and never write a raw value in a component. Show every component in [Storybook or my component catalog] in both themes with real copy, and add screenshot tests that fail when [1%] of pixels change. Log my taste decisions in [decisions.md] and read it at the start of each session. Before saying a change is done, compare what I asked for with what you built and list the gaps.

Square brackets are the parts to fill in. The prompt is ours; the story is theirs.

Where they said it

Related