Slow down to speed up

Draw me a mountain by partiallyHere

—

"The cobbler wears the worst shoes" — 16th-century proverb

I've been putting off my portfolio for nearly seven years.

Not because I didn't have the work. Because I don't enjoy working on it. Portfolios for designers are a necessary evil. You spend your career building things for other people, and then at intervals you have to stop and produce evidence of that, in a format that feels nothing like the work itself.

I've been finding reasons to defer it since before my last full time gig.

What finally moved me was a combination of things I've been writing about elsewhere: Claude Code, Figma's MCP integration, and the particular kind of motivation that comes from having tools that make a thing feel tractable. I set up VS Code with the MCP connection to Figma, pointed it at a blank canvas, and started building.

I got it very wrong first and I realised it almost immediately. I built too fast, skipped the foundations, and spent the back half of a session unpicking what Claude Code had helpfully constructed for me at speed out of a poorly resolved design.

The components in the first iteration were styled with hardcoded values and inconsistency was rife. The structure didn't map to anything systematic that I'd actually want to maintain later. The potential for a whole new pocket of portfolio procrastination in the making. The time I'd saved building fast I spent rebuilding correctly. I slowed down to think and plan. And then I got really fast.

These are the highlights of how I built my portfolio website in a day.

Lay the groundwork before you start

There is an order of operations that makes this new form of building for the web work well. What follows is what I learned about the sequence, the constraints, and the places where the tooling isn't yet what it should be.

"Give me six hours to chop down a tree and I will spend the first four sharpening the axe" — Einstein (or Lincoln, depending on your search engine...)

Two things will save you significant effort when building for the web with AI, if you do them early. I'll try to cover both in more detail in future articles, but they're worth naming here for now.

The first is your CLAUDE.md file and .claude/ folder.

View post on Bluesky

This is where you define your project context, commands, and working conventions for Claude Code. If you start building without it, you may find yourself spending time re-explaining your naming conventions, your token structure, your component philosophy. Get it written early, and update it as the project evolves.

The second is having your user stories and requirements accessible to ClaudeCode from the start. I keep these as GitHub issues and access them using the gh CLI tool directly from the terminal. Working in branches tied to those issues gives you a clean history and makes Claude Code's context more coherent. It knows what it's supposed to be building and why.

Neither of these is glamorous setup work, but they both require a lot of thinking and planning up front, which will later pay back more than it costs.

dollspace.gay

Writing a good CLAUDE.md

GitHub CLI

Tokens before everything

I found that the single most important decision was establishing a token architecture (before coding a single component). I use the DTCG standard as my framework in three tiers: primitive, semantic, and app-level.

If you're unfamiliar with tokens, primitives are raw values with no opinion about usage: color-black-500, space-4, font-family-sans. Semantic tokens give those values meaning in context: color-text-primary references color-black-500; space-component-gap references space-4. App-level tokens handle what varies between themes or contexts, without touching the components themselves.

Making sure those tokens exist in the codebase before building components helped to avoid a lot of issues. When Claude Code generates styles based on my designs, it needed to reference real token names that existed in real files. If the token definitions don't exist yet, I saw hardcoded values scattered across my components, and unpicking that later is slow and fiddly.

Define the architecture in Figma. Implement it in code. Then build components. That order definitely mattered to me.

Tokens in Design Systems

Design Tokens Technical Reports 2025.10

Attacking both ends of the atomic scale

It's counter-intuitive, but useful to start building at the atomic level and the page template level at the same time.

Atoms give you the building blocks: buttons, inputs, labels, icons, type styles. Templates give you the real-world context: what does a product page actually need? What layout decisions matter? What spacing breaks?

Working only bottom-up, you end up with a library of components that have never been tested under real layout pressure. Working only top-down, you spend time sketching compositions with placeholders that don't reflect the real component behaviour.

Working both ends forces them to meet in the middle with fewer surprises. Templates reveal which atoms are missing. Atoms constrain what templates can promise.

Claude Code handles both directions well once the token layer is solid.

Atomic Design Methodology | Atomic Design by Brad Frost

Build with props and tokens

When building atomic components, I find two foundational elements matter most: rational props and token-based styling throughout.

Good props means thinking through the states, variants, and configuration options a component actually needs. You don't need to think about every possible variant upfront, but enough that the component is flexible without being unpredictable.

Good housekeeping is really important here. Naming layers, using auto-layouts with intention, and keeping architecture lean will translate to the browser better. Try to think beyond visible results on your canvas.

ClaudeCode can generate a reasonable prop interface from a well-described Figma component, though it needs guidance on naming conventions and which variants map to which states.

Good token-based styling means nothing hardcoded. Every colour, space, radius, and type style should reference a token. Claude Code will respect this if your CLAUDE.md makes it explicit. If not, you may find it occasionally making reasonable-looking choices that aren't in your system.

Props and variables | Developer Docs

Explore component properties

Passing Props to a Component – React

Learn to Love to Lint

Token discipline can break down without guard-rails and self-discipline.

Design Lint catches detached styles and hardcoded values that should be bound to variables. I run it before treating a component as done. It surfaces exactly the class of mistake that gets copied into code: styling that look correct but isn't in the design system.

In code, I used stylelint with the stylelint-declaration-use-variable plugin which flags hard-coded values for colour, spacing, and radius properties. Configure it to require CSS custom properties for those categories and it will fail the build if a component uses a raw value instead of a token reference.

One catches it before it reaches Claude Code, the other after. Neither is complicated to set up, and both are worth doing before you have a a lot of components to audit.

Home | Stylelint

Home

Where Figma MCP falls short

The Figma MCP integration is useful. It is not (yet) magic. The biggest limitation I found is responsive behaviour. Figma's responsive system, even with auto-layout, doesn't map cleanly to how breakpoints work in code. Explaining breakpoint behaviour to Claude Code often requires building out multiple component variants in Figma representing different viewport states, then describing the relationship between them in your prompt. It works, but it's less than idea and adds some overhead. This is actually true of a lot of browser behaviours, so careful declarations in the CLAUDE.md and user stories help to scaffold gaps.

The Dev Mode MCP experience also has room to improve.

You can copy a prompt from a Figma component to pass to Claude Code, which is helpful. But reading the component URL in Dev Mode could be better: navigating between components and layers to identify what to pass to the MCP is less smooth than it should be. Sometimes it struggles to identify the atomic components contained within a more complex composition.

This is a tooling maturity issue rather than a fundamental problem, and it will likely improve, but it's worth knowing before you start.

What the time saving actually looks like

With the setup done correctly, the token architecture in place, and components built cleanly from atoms upward, the acceleration is genuine and astounding.

Styled accessible components that respect the design system, built in the time it would previously take to scaffold one. Review, adjust, ship.

The caveat is that the setup investment is more front-loaded. The first few sessions are slower than working without AI assistance. You're building the foundations that make everything after faster. If you skip them, you don't avoid the cost. You defer it, and that compounds.

Building solid foundations means preparation to build fast.

—

Visit the site I built in 8 hours with this method → renderg.host