I wanted to experiment with bringing AI into my design process and document the experience to share it with other designers and developers. I used Claude as a working partner to draft layouts, write code, and run the GitHub publish flow for this portfolio.
AI-assisted design and development
Every case study in this portfolio is about a product I designed and handed off to an engineering team. This one is different, because I'm also responsible for the code, the repo, and the deployment.
I brought Claude into my workflow to write code at scale. Because I can read and edit HTML, CSS, and JavaScript myself, I review every change before it ships, so ownership of the outcome stays with me.
Iterating with AI is easy. Staying consistent isn't.
Getting Claude to produce a working page is the easy part. The problem is what comes after the first draft. In each iteration I had to keep the visual system consistent across six pages built in separate sessions, catch copy that drifted from my actual voice, and ship changes from my local files to the live site without breaking anything.
On top of that, I had to keep the design system in the repo synced with the one in Figma. Every token or component change in the code meant going back to Figma to mirror it, and that back-and-forth got slower as the portfolio grew.
Describe, review, fix, ship
Every change went through the same steps. I described the goal and constraints, reviewed what Claude produced and fixed what needed fixing. Only then was it done.
Prompting like writing a user story
For prompting, I started using a loose version of the Ask, Requirements, Context, Examples framework. It ended up looking a lot like a user story with acceptance criteria, something I'd been doing for years when handing off designs to engineering teams. I'd state the ask plainly, list what had to stay consistent, name the existing pattern to match, and give one or more examples.
Teaching Claude my standards
I also built two Claude skills to guide the work. The first, a portfolio skill, holds how I want each case study structured (outcome first, decisions over tasks, an honest reflection at the end). The second captures my writing voice from copy I wrote myself, and it grew every time I caught Claude drifting from it. After seeing too many drafts built on a claim-colon-list structure, I added a rule to avoid that pattern.
Prototyping fast, testing in dev tools
I used the browser's dev tools constantly. I inspected elements, looked up the actual CSS class names so I could ask for specific changes, and nudged a padding or line-height value live to see what felt right before asking for the change in the file. I also checked accessibility in light and dark mode, and the mobile breakpoints, by hand.
Testing spacing and color adjustments live in dev tools before committing to a value in the stylesheet.
Taking the wheel in VS Code
Some changes were faster and more precise to make directly in VS Code. I kept the repo open alongside the Claude sessions, so I could see and edit directly instead of describing a one-line change and waiting for it to come back. I also kept a few small code blocks on hand for dropping in a new image or moving a pull-quote. Claude handled the larger structural work and the audits. I handled the small fixes I could solve faster myself.
A direct edit to a token value in VS Code, faster than a round trip through conversation for a one-line fix.
One private repo, one public one
I split the site into two repositories. A dev repo (private) handles day-to-day iteration, with a full commit history plus two reference files, session-context.md logging decisions session to session and design.md documenting the system. A live repo (public) only ever receives clean releases.
The dev repo for iteration, the live repo for deliberate, versioned releases.
The split also kept things safe. The dev repo's history let me trace changes and experiment freely, and nothing covered by an NDA could reach a public commit. Every push to the live repo was already reviewed and versioned.
Easy there, Claude!
Not every session went that smoothly. Left with a loosely scoped request, Claude tends to generate something new (a fresh class where an existing token would already do, a component variant nobody asked for). The results reminded me of when I was a junior graphic designer, wanting to show off every trick I knew, when the better move was to use only what's needed. Less is more. Tightening the Ask and Requirements steps helped, but wasn't enough. After a few iterations, I improved the results by adding design.md as a reference, so Claude would check every existing token and pattern there instead of drifting session to session.
Letting the code become the source of truth
I started the design system in Figma, the way I would in my usual design workflow, but this time connecting it to Claude through MCP. I'd given Claude a few reference sites and some instructions to generate the design system from scratch. The results weren't bad, but going from Figma to CSS meant every change needed a back-and-forth between the two to keep them in sync. That got slow and tedious. Partway through, I stopped going back to Figma for corrections. It was faster to test a change live in dev tools and edit the token or component's CSS directly.
For this new workflow, I needed a way to document the design system and keep it up to date. I used Claude Design, asked it to generate a design system from the repository, and it built one in minutes. The result was solid. The problem was I didn't know how to connect it back to Claude, so I ran into the same issue again. The fix was generating design.md from that design system. Now every token and pattern is listed there and Claude uses it as a reference, so I don't have to re-explain the system each session.
Auditing the CSS instead of guessing what was safe to delete
By the time the site had six pages and five stylesheets and was ready to publish, I asked Claude to audit the repository for dead CSS.
The audit found that 151 of 281 classes in the site's CSS were unused, more than half. Some were near-duplicates of other classes. Others were leftovers from components I'd tried and dropped, or styles a token had since replaced. The audit let me leave the CSS lighter and easier to maintain.
The categorized audit report: dead code approved for deletion, intentionally retired code kept for reference, and a small set held back for a future decision.
A live, versioned, bilingual portfolio I can keep iterating on
The site is live on a custom domain, built and maintained through the workflow described above. Every change I make goes through the review-and-publish loop, and every release is versioned on GitHub.
- It's fully responsive, bilingual, and supports light and dark modes.
- A full CSS audit removed 151 dead classes and cut the largest stylesheet by roughly a third.
-
A new dev-to-live publish flow with tagged releases, plus
session-context.mdanddesign.mdtracking decisions on the dev side, means every version of the site is documented.
What this project taught me
Adding AI to my workflow meant every design decision and code change had to go through my review and approval. My role shifted from maker to something closer to an editor and director.
Dev tools became a fast prototyping tool. Testing changes live and adjusting style values directly was faster and more precise than describing a change and waiting for Claude to get it right.
The design system built in Claude Design and the design.md file became the main reference for Claude. Figma started fading out of my workflow. I stopped using it as the source of truth, but I imagine I'll keep using it to explore new design concepts more freely, or to generate new assets.
Setting up a design system's foundation used to take me hours, from grid values to every color variable and token hierarchy. With AI, that groundwork took minutes and gave me a solid starting point.
If I started over, I'd set up design.md in the first session. Most of those 151 dead classes came from sessions where Claude had nothing to check against, so it kept inventing instead of reusing.
My next step would be exploring a real component library, something like Storybook, instead of design.md. I'd like to see if I can keep the same design consistency and improve execution speed, but with a more robust, documented component system.