The Designer’s Dev Setup: How I’d Build a Portfolio Website with Claude Code and VSCode in 2026

The personality of the result depends on the constraints written before the prompts begin.

Record concrete decision criteria in a `CLAUDE.md` file at the project root
- Unambiguous brand tokens covering color, type scale, spacing, radius, and shadows
- Reusable component rules for cards, hover states, and motion
Define unwanted patterns and page intent as clearly as desired outcomes
- Explicitly exclude defaults such as purple gradients or glassmorphism
- Describe the experience each page should create, such as “feel like a gallery”
Update `CLAUDE.md` before patching individual pieces of code when the result feels wrong
- Treat it as an evolving source of truth rather than a one-time brief

For a portfolio, comparing real screens is more effective than relying on text instructions alone.

Run the local server → capture a screenshot → compare it with a reference → revise → capture again
- Use a Dribbble image, competing site, or exported Figma frame as the visual baseline
- Correct spacing and proportion issues that are difficult to express through code descriptions
Work on navigation, hero, cards, and footer separately instead of cloning a full page
- Validate the design system with one component first
- Expand only after the constraints are working to reduce rework

Design can be rebuilt, but case studies and personal copy are expensive to recreate, so their home matters.

Use Markdown files in the project when you are comfortable working in VSCode
- Claude Code can read them directly, while content and code remain versioned together
- The writing environment can feel limited for long-form prose
Move to Obsidian when you want a better solo writing experience
- Keep the benefits of Markdown and Git while writing in a more comfortable interface
- Collaboration and external feedback remain somewhat awkward
Use Notion when collaboration and production tracking matter most
- Manage draft, image-preparation, and publishing states through database views
- Expect some cleanup when converting rich text into code-friendly Markdown

Real content and small-scale validation create a more durable result than a perfect first launch.

Follow the order `CLAUDE.md` → real content → one component → screenshot QA → early release
- Rough but authentic case studies are more valuable than polished placeholder pages
- Validate the constraints on a small component before increasing the scope
A structured system dramatically lowers the cost of future updates
- One change to a type scale or design token can propagate across every page
- The portfolio becomes a living asset instead of a rushed job-search project
As AI handles more execution, the designer’s decision trail becomes a more important artifact
- Chosen constraints and rejected patterns communicate taste and judgment
- Future portfolios may show the reasoning behind the work as much as the finished output

Get the week's signal by email, every Saturday.