How I built my personal site with Claude Design, Claude Code, and Vercel

A friend who happens to be a product designer looked at productpedro.com last week and said “nice, did you use a template?” I told him no, I built it, step by step. Then he asked me to share the repo so he could use it as a base, because he did not know how to start one from scratch.

That question is why this post exists. I have been exactly where he is. I am not technical, and figuring out where to begin is kind of overwhelming. So here is the full path from blank screen to live site, the way I did it.

Start in Claude Design, with references

I am not a designer. I am good at copying. So I start in Claude Design by telling it what I am building, a site to show my projects, and a bit about who I am. I also add links and screenshots as reference, pointing out what I like and do not like about each one.

First I prompt for a basic design guide: my colors, a logo, the rules, the design tokens. A small brandbook. I do this for every project I start from scratch. I push it around until I reach something I like, knowing it is a base and it will keep changing. A tip: do not chase perfection here, it comes later.

Then I use that brandbook to build the first screens. Same move for a website or a mobile app. Here it was the homepage of Product Pedro, and it started brutalist.

I iterated into editorial minimalism, which is also my thing, in about a day. It could take more, it could take less, the project decides, so keep the pace up.

Installing Claude Code (the part nobody explains)

If you already do this, skip ahead. If not, here you go. The first time I did it I had no clue. Now it takes a minute.

• Install Claude Code by following the official setup docs. They tell you what you need (Node.js, mostly) and walk you through it. Heads up: Claude Design and Claude Code both run on a paid Claude plan.
• Open a terminal, make a folder for the project, and cd into it (cd moves your terminal into that folder). In my case: cd ~/Documents/productpedro-site. Then type claude and it starts.
• The first thing I create is a CLAUDE.md file. It holds the rules I want Claude Code to follow in every repo: plan before big changes, verify before it says “done,” keep things simple, use sub-agents. I did not write mine from zero. I started from a CLAUDE.md that Boris Cherny, who created Claude Code, shared on X, and kept the parts that made sense to me. I paste that base into every project. Here is mine:

# CLAUDE.md

Guide for Claude Code (claude.ai/code) when working in this repository.

## User context

- **[Your role]** (e.g. Product Manager, designer, founder). State your technical level: whether you write code directly or delegate implementation to Claude Code.
- Describe **how you validate work**: by observable behavior in the app, by reading the code, by reviewing tests, etc.
- Add any context that changes how Claude should work with you (timezone, stack, project constraints).

---

## Working Agreement

How Claude collaborates with you on this project. These rules apply to every interaction.

### 1. Aggressive plan-first

- **Enter plan mode automatically** if the task meets any of these criteria:
  - 3+ implementation steps
  - Touches 3+ files
  - Involves an architectural decision (new pattern, new dependency, structural change)
  - New feature (not a tweak to existing code)
- **Execute directly** if trivial: typo, rename, one-line change, string/copy change.
- The plan is presented and approved before touching code.

### 2. Subagent strategy

- **Exploration of 3+ search queries** → delegate to an `Explore` subagent to keep the main context clean.
- **Parallel research across independent areas** → launch multiple agents in a single message.
- **One tack per subagent** — each agent gets a specific focus with concrete paths and questions.

### 3. Mandatory verification before "done"

Every task closes with THREE fixed steps, in order:

1. **TypeScript check:** `npx tsc --noEmit 2>&1 | head -30` if TS code was touched. If there are errors, explain them and ask whether to fix them before calling it done.
2. **Behavior summary**, 2-3 bullets, about *what changed in the app* from the end user's point of view, NOT which files were touched or which functions were added.
3. **Manual test steps** in the app/simulator: a step-by-step list of what to tap, what to observe, and the expected result.

If it can't be verified (e.g. UI without a simulator open), say so explicitly instead of assuming success.

### 4. Autonomous bug fixing

- When a bug is reported: diagnose and fix without ping-pong.
- Point at logs, errors, and failing tests, then resolve them.
- If there are 2+ viable fixes with real trade-offs → present options with pros/cons and recommend one. Don't ask permission for every micro-decision.

---

## Core Principles

- **Simplicity first** — the minimal change that solves the problem. Don't add abstractions for hypothetical cases.
- **No laziness** — go to the root cause, not workarounds. Never use `--no-verify` or skip hooks.
- **Minimal impact** — don't touch what doesn't need touching. A bug fix doesn't need a refactor around it.
- **Demand elegance (balanced)** — for non-trivial changes, pause and ask "is there a more elegant way?". Skip this step for obvious fixes.

The handoff that did not work

Claude Design has a button to hand off straight to Claude Code. I tried it once. It did not work for me. My workaround: I take the brandbook MD file Claude Design wrote, share it with the Claude Code agent along with screenshots of my final design, and start building the screens.

I also use some frontend design skills, you can find them here. They are a must for atomic design and consistent naming, which keeps the code clean.

Polish until it holds the design

Now the landing runs locally with npm run dev. The base is there. The job is to polish it and make sure it keeps the design I like as I keep building. Two skills do most of this for me. I keep them short here, they get their own post.

First, Impeccable by Paul Bakaus. I run its critique and audit, and they write two files for the project, DESIGN.md and PRODUCT.md. Those become the design source of truth for that specific site, so the look stays consistent every time I touch the code.

Once the design is where I want it, I move to motion with Emil Kowalski’s skill. This is the last touch. I do not like animations that slow a site down, I like subtle, and subtle is exactly Emil’s style. After the animations are done, I move to the copy with Impeccable’s copywriting side.

Why the project cards are Bauhaus, not screenshots

Then the projects, the tedious part. I had already used a bit of Bauhaus as an accent, the P in my favicon and my personal logo. Filling the project cards, I tried the usual move: a real screenshot or photo of each one. For my client Florale I dropped in a real photo of one of their flower arrangements, and it broke the page. It clashed with the editorial minimal look.

So I asked what would happen if I drew each one in the style I already had, that Bauhaus accent. I made a small Bauhaus piece per project.

Loved it. Every card now lives under one design language, and the site reads as mine. There is no grand reason here, it is a design call I liked and it is mine.

No database. One MDX file.

I was not going to wire up a CMS for four projects that barely change. Too much. I want to edit content and have the site load fast. Drop the database and you drop complexity and weight.

So I asked Claude Code for options without a database, and to keep the project code separate from the project data. It came back with MDX, which I had never heard of. Content lives in MDX files (markdown with components mixed in), and code stays code. The bonus: that clean split makes the repo easy to turn into a template later.

Astro, not Next

A habit worth breaking: when you are not an expert, you reach for what you already know. My default is Next: it is SEO friendly, the documentation is everywhere, Claude Code handles it well, and most developers use it. None of that means I know it beats another framework for my case. It just means it is familiar.

So I asked the question instead of defaulting. Is Next the best pick for a site that has to be fast, small, and simple? I put that to Claude Code. It pointed me to Astro: for a personal content site, Astro is plenty. Lighter, faster, ships almost no JavaScript by default, and it reads MDX out of the box. I had never touched Astro. For a site like this it was the right call, and I liked it.

GitHub is the new resume

The template is where this pays off. For product people, GitHub has quietly become the network that vouches for you. Build useful things people clone and star, and that is your validation. They do not have to be complex.

My plan for productpedro.com is to turn it into a public template so anyone can fork it and ship their own. Including the designer friend who thought it already was one.

Vercel: free and fast

Last step, and you do not need to know git. I tell Claude Code to put the project on GitHub, it commits and pushes for me. Then I connect that repo to Vercel, done. Vercel is free for this, and you get a CDN out of the box, so the site loads fast everywhere with zero setup. Compare that to standing up something on Google Cloud or DigitalOcean, where now you babysit a server and wire your own CDN. For a personal site, that is effort you do not need to spend.

The catch with the free tier: instances go to sleep, so the first visitor after a quiet stretch waits a few extra seconds for the first load. The paid tier removes it. For a personal site I will live with it, it is free. Plenty of generous free tiers do the same thing, Supabase included.

So no, it is not a template. But you can start from mine.

The repo is on GitHub, fork it and make it yours. Want to get in touch? DM me on LinkedIn.