The Designer’s Dev Setup: How I’d Build a Portfolio Website with Claude Code and VSCode in 2026
There’s a specific kind of dread that comes with building your own portfolio.
You know design. You have opinions about typography, whitespace, motion. You can critique someone else’s portfolio in thirty seconds flat. But when it’s your own work: your name, your case studies, your reputation on the page, suddenly everything feels harder. The blank canvas paralysis is real, and I’ve seen more talented designers avoid updating their portfolios for years because the bar they’ve set for themselves is impossibly high.
Here’s the thing that shifted for me recently: Claude Code has changed the math on what it costs (in time and cognitive energy) to actually build and iterate on a portfolio. Not just to ship a first version — but to keep it alive.
Let me walk you through the workflow I’d use if I were building mine from scratch today.
Start With a CLAUDE.md: Your Design System Lives Here
The biggest mistake I see designers make when jumping into Claude Code is treating it like a search bar. “Build me a portfolio website.” The output is technically functional and aesthetically… fine. Forgettable. The kind of thing that looks like it was made by an AI, because it was.
The antidote is what the community has started calling the CLAUDE.md-first approach. Before you write a single prompt about a hero section or a case study layout, you create a CLAUDE.md file at the root of your project. This is a plain text file — essentially a project brief and design system rolled into one — that Claude Code reads at the start of every session.
Think of it like the brief you’d give a developer. Except the developer is an AI that never forgets, never skips ahead, and will apply your constraints obsessively across every component it generates.
A strong CLAUDE.md for a portfolio should include:
Brand tokens — your exact hex colors, type scale, spacing units, border radius, and shadow definitions. Don’t write “use a clean sans-serif.” Write font-family: 'Instrument Serif', serif for display and font-family: 'DM Mono', monospace for body. Be specific enough that there’s only one correct interpretation.
Component conventions — how cards behave, how hover states feel, whether you prefer subtle motion or none at all. “Transitions: 200ms ease-out. No bounce. No slide-in from off-screen.”
What not to do — this is underrated. Listing explicit anti-patterns (“no purple gradients,” “no full-width hero images with overlay text,” “no glassmorphism”) is just as important as describing what you want. Claude will avoid these across the entire project.
Page intent — a short description of what each page is trying to accomplish, not just what it contains. “The work page should feel like a gallery, not a grid of thumbnails. Breathing room matters more than density.”
This file becomes your source of truth. You’ll edit it as you go — that’s expected. Treat it as a living document rather than a one-time setup. When something feels off after a generation, update the constraint in CLAUDE.md before re-running. You’re training the context, not just fixing a bug.
The Screenshot Loop: Design Feedback That Actually Works
Here’s a workflow detail that doesn’t get talked about enough. Claude Code can spin up a local server, take a screenshot, read the image directly, compare it against a reference, fix what’s off, and screenshot again: handling the whole cycle without you stepping in.
For a portfolio, where the visual output is the product, this is transformative. You set a reference screenshot (a Dribbble shot, a competitor’s site, a Figma frame you exported), and Claude iterates against it visually rather than just textually. The delta between “it looks roughly right” and “it matches my vision” collapses dramatically when there’s an actual visual feedback loop.
The reference cloning works better on sections than full pages. Breaking the design into header, body, and footer and handling each separately gives you a lot more control. I’d treat your portfolio the same way: tackle the nav, then the hero, then the case study card, then the footer — rather than asking Claude to generate everything at once.
Where Should Your Portfolio Content Live?
This is the question I actually get asked most often, and it’s worth spending real time on. The answer isn’t obvious, and it depends on your workflow more than any tool’s feature list.
Your content, case study write-ups, project descriptions, role timelines, the “about” text you’ve revised seventeen times, is the hardest part of a portfolio to maintain. The design can be rebuilt. The words take weeks. So the system you use to store and update them matters enormously.
Option 1: Markdown files in your project repo
This is my personal preference for designers who are comfortable in a code environment. Your content lives as .md files alongside your code. When you update a case study, you open the file, edit it, commit, and push. Claude Code can read and reference these files directly — you can ask it to “pull the intro paragraph from /content/case-studies/communication-app.md“ and it will. The content and the code stay in sync because they live in the same place.
The downside is that it’s not a great writing environment if you’re a prose-heavy writer. Markdown in VSCode is functional, not beautiful.
Option 2: Obsidian
Obsidian’s Markdown-native format integrates naturally with Git workflows — store your vault in a Git repository for version control, and you can query your notes programmatically. For a portfolio, this means you can write your case studies in a beautiful, linked note environment, and then export them as .md files that Claude Code can read directly. No format conversion, no copy-paste friction.
For anyone who writes in one tool and publishes in another, Obsidian’s native Markdown format eliminates the formatting friction that plagues Notion-to-external-platform workflows. This is real. If you’ve ever tried to copy a Notion page into a codebase, you know what I mean.
The tradeoff: Obsidian is a solo tool. If you collaborate with anyone on your portfolio content (a copywriter, a mentor giving feedback), the experience is clunky.
Option 3: Notion
Use Notion if you need content planning, editorial calendars, and project management alongside your writing. For a portfolio that’s actively being built: multiple case studies in different stages, a running list of things to add — Notion’s database views are genuinely useful. You can track each case study’s status (draft, needs images, published) in a kanban board.
The problem is export friction. Notion’s rich text doesn’t always convert cleanly to code-friendly formats. If you’re feeding content directly to Claude Code, you’ll find yourself doing manual cleanup more often than you’d like.
The recommendation: Start with Markdown files in your repo if you’re already working in VSCode. Graduate to an Obsidian vault if you find yourself writing long-form content and wanting a better writing experience. Use Notion only if you have collaborators or need to manage many projects simultaneously.
The Actual Build Order (Don’t Skip This)
Here’s the sequence that produces the best results, based on what I’ve seen work:
1. Write your CLAUDE.md first. Don’t touch code yet. Define your brand tokens, your aesthetic constraints, and your anti-patterns. This takes 30–60 minutes and saves hours of re-generation later.
2. Populate your content files. Write your case studies, your about blurb, your role history, even in rough draft form. Claude Code will use this as source material. A portfolio with real content and mediocre design beats a beautiful portfolio with placeholder text every time.
3. Build one component, test the design system. Before generating full pages, ask Claude to build a single case study card. Review it against your CLAUDE.md. Adjust the constraints. Then expand.
4. Use the screenshot loop for visual QA. Set your reference, run the loop, iterate. Trust the visual feedback more than the code review at this stage.
5. Ship early, iterate in public. Your portfolio is not a product launch. A live, imperfect portfolio with three real case studies is worth more than a perfect one that’s been in development for eight months.
What This Workflow Actually Changes
The deeper shift here isn’t about Claude Code being a faster way to write HTML. It’s about what happens when the cost of iteration drops low enough that you’ll actually do it.
Most designers update their portfolios once every few years, when they’re job hunting, when they feel enough accumulated guilt to force a weekend sprint. The reason isn’t laziness. It’s that the cost of updating felt too high relative to the payoff on any given week.
When your design system is encoded in a CLAUDE.md and your content is in Markdown files in a Git repo, the cost of updating a case study is fifteen minutes. The cost of tweaking your type scale across every page is a one-line edit and a re-run. That’s a different relationship with your portfolio entirely, and it’s the one that keeps it current enough to actually matter.
The bar for a portfolio worth sending hasn’t gotten lower. But the effort required to clear it has.
Forward-Looking Thought
I keep thinking about a question that doesn’t have a clean answer yet: as AI handles more of the execution, what does it mean for a portfolio to demonstrate your taste? If Claude Code built the UI, what exactly is the thing being evaluated?
My working answer is that the CLAUDE.md is the design artifact. The constraints you chose, the anti-patterns you named, the aesthetic precision you encoded — that’s judgment. That’s the thing that’s actually hard to replicate.
Which means the portfolio of the future might look less like a gallery of finished work and more like a record of the decisions you make along the way.
References
Tutorials Dojo — Claude Code: The Web Design Workflow That Actually Works (February 2026): https://tutorialsdojo.com/claude-code-the-web-design-workflow-that-actually-works/
MindStudio — How to Avoid AI Slop When Using Claude Design (The Design System Approach) (April 2026): https://www.mindstudio.ai/blog/claude-design-avoid-ai-slop-design-system
Design Systems Collective — From Prompt to Production: A Designer’s Step-by-Step Workflow with Claude Design + Claude Code (April 2026): https://www.designsystemscollective.com/from-prompt-to-production
Medium / Katherine Yeh — A Designer’s Guide to Claude Code (March 2026): https://medium.com/design-bootcamp/a-designers-guide-to-organizing-ai-skills-and-tools-in-claude-code
Tech-Insider — Obsidian vs Notion 2026 (April 2026): https://tech-insider.org/obsidian-vs-notion-2026/
DataCamp — Claude Code in VS Code: Setup, Features, and Workflow (2026): https://www.datacamp.com/tutorial/claude-code-in-vs-code
Abbas Ali / Substack — How to Build a Stunning Portfolio Website Using Claude Code (March 2026)