Portfolio Site
A portfolio site has one job: a stranger with your link and ninety seconds decides whether to email you. Everything on the page either helps that decision or delays it. Most portfolios delay it, because they are organized around the owner's history instead of the visitor's question, which is always the same question: can this person do the thing I need done?
The answer to that question is not a skills grid. It is three or four pieces of work, each shown as a small case study: what the problem was, what you did about it, what happened because of it. One project explained beats nine projects thumbnailed. If you're switching careers or returning to work and the honest answer is "I don't have client work yet," case-study your practice projects the same way. The problem-action-result structure is doing the persuading, not the client's logo.
The technical decision baked into this spec is that your projects live as data, separate from the layout. When you finish something new, you add one entry to one file and the site updates. Portfolios die when adding a project means re-opening the code, so the spec makes adding a project the easiest operation on the site.
Prerequisites
- A GitHub account and a Vercel account (free tiers are fine).
- Your three or four best projects written up rough: what problem, what you did, what resulted. The agent builds the site; it cannot know your work.
# Project: Portfolio site for [your name]
Build a personal portfolio: a home page, one page per project, and a
short about page. Optimized for a visitor deciding in under two minutes
whether to contact me.
## Stack
- Next.js (App Router) on Vercel. Static generation; there is no server
state anywhere on this site.
- Plain CSS or Tailwind. No component library, no animation library.
- No CMS. Content lives in the repo (see data shape below).
## Data shape (build this first)
All projects live in `content/projects/`, one markdown file each, with
frontmatter:
- `title`: [project name]
- `slug`: [url-safe-name]
- `summary`: one sentence for the home page card
- `role`: [what I actually did; "built the whole thing" is fine]
- `year`: [YYYY]
- `links`: list of `{label, url}` (live site, repo, write-up)
- `featured`: true/false; featured ones appear on the home page
The body of each file is the case study in three sections:
**The problem**, **What I did**, **What came of it**.
Adding a project must require exactly one new file and zero code changes.
## Pages
### Home (`/`)
1. Name, one-line description of what I do: [e.g., "I build internal
tools for small teams"]. No "welcome to my portfolio."
2. Featured projects as cards: title, summary, one image, link to the
project page. Maximum four.
3. Contact block: email as a visible `mailto` link, plus [GitHub /
LinkedIn / other]. No contact form; forms need spam handling and a
backend, and an email link needs neither.
### Project pages (`/work/[slug]`)
Rendered from the markdown files. Images referenced from the file,
stored in the repo, compressed, with real `alt` text.
### About (`/about`)
[2-3 short paragraphs: background, what kind of work you want, one
human detail.] Pull the text from `content/about.md`.
## Constraints
- Every page readable on a 375px-wide phone screen with no horizontal
scroll.
- Real page titles and meta descriptions per page; the home page title
is "[Your name] — [what you do]".
- Total JavaScript shipped to the browser stays small: no analytics
script, no chat widget, no cookie banner (nothing here sets cookies).
- Lighthouse performance and accessibility both 90+ on the home page.
## Explicitly out of scope
- Blog. If I want one later it is a separate effort.
- Dark mode toggle, page transitions, scroll animations.
- Testimonials carousel. If I have quotes they go as plain text on
project pages.
## Done means
- `git clone`, install, run: site works locally with the sample content.
- I add a new markdown file to `content/projects/` and the project
appears on the site with no other edits.
- All links resolve; the mailto link opens with my address.Adaptation notes:
- Designer or photographer: the case-study structure holds, but the image handling becomes the hard requirement. Add a constraint that project pages use responsive images and that no single page ships more than a couple of megabytes.
- Actively job hunting: add a
/resumeroute serving a PDF stored in the repo, and put the link in the nav. Recruiters ask for the PDF anyway; hand it to them before they ask. - If you genuinely have one project, build the site anyway with one case study. A single deep write-up reads as focus. Three placeholder cards read as padding.
- The mistake: spending the week on the site and an hour on the case studies. The site is a picture frame. Visitors hire the work, and the work is described in the markdown files you were supposed to write first.