Build your portfolio site the way I built this one.

Here are the sections most portfolios draw from, in any field. You do not need all of them. Each one says when it is worth including, so keep the ones that fit.

The sections above apply to almost everyone, but each field puts the weight in a different place. Use this table as a starting point, not a rule, and check it against the portfolios you admire in your own field.

The right set of sections depends on what you want the site to do. A few common starting points:

• Looking for your first role: hero, about, work and projects, education, skills, contact.
• Experienced and changing jobs: hero, experience, two or three strong projects or case studies, skills, contact.
• Switching into a new field: hero, about (explain the switch), projects in the new field, transferable experience, contact.
• Freelancing or looking for clients: hero (what you offer and to whom), selected work, process, testimonials if you have real ones, contact.

Fewer, stronger sections beat a long page of thin ones. You can always add more later, because updating it takes a few minutes once it is set up (step 5 shows how).

With a rough list of sections in mind, the next step is to gather the actual content and assets that will fill them.

Before you open an AI tool, it helps to be clear about what you are making and who it is for. A portfolio website is a small, focused site that shows your work, how you approach it, and how someone can reach you.

This guide works whatever your field: design, engineering, product, marketing, writing, research, or something else. It also works whether you are a student, changing careers, job hunting, or looking for freelance clients. By the end of this step you will have a rough list of sections, which is the starting point for step 2.

A job title and a list of employers say little about the quality of your work. Two people with the same title can have done very different things, and a resume rarely has room to show the work itself or explain the thinking behind it. A portfolio gives you that room.

• It shows the work itself. A designer can show screens and the sketches behind them, a developer can link to working projects and their code, and a writer can share published pieces. Reviewers can judge the work directly instead of taking a bullet point on trust.
• It shows how you think. A short write-up can walk a reader through a problem, the options you weighed, and why you chose one. That is what interviewers and clients try to uncover anyway.
• It gives people one link. Recruiters, hiring managers, and potential clients can see your background, work, resume, and contact details in one place instead of piecing them together from several sites.
• It demonstrates care. Choosing what to include, writing it clearly, and publishing it is itself a small project. A tidy, well-structured site signals that you pay attention to details.

A portfolio will not replace your resume or your network, and it does not guarantee interviews or clients. It is a supporting asset: something you can share with confidence when someone asks what you have done.

Whatever your field and whatever sections you choose, a reader should come away with clear answers to four questions:

1. What have you worked on? Show the work itself, whether that is designs, code, products, campaigns, writing, or research. Choose pieces that represent the work you want to do next.
2. How do you approach the work? Describe your process: how you understood the problem, the trade-offs you made, the evidence you used, and what you decided not to do. This is what sets you apart from someone with similar output.
3. What happened, and how do you know? Share real outcomes and the evidence behind them, such as a live link, a published piece, feedback someone agreed to let you quote, or results you are allowed to share. Include what did not go to plan. Honest reflection is more convincing than a perfect record.
4. Who are you, and how can people reach you? Say what you do, what you are looking for, and how you work with other people, and make it easy to get in touch.

This guide is based on the workflow behind adityagangwani.me, the site you are reading it on. It is a product manager’s portfolio, so its sections reflect that field. It is fine to look at it, or any portfolio you admire, to understand how it is structured. Notice the order of the sections, what question each one answers, and how much text sits on each page.

Then look at strong portfolios from people in your own field, ideally people a few steps ahead of where you are now. Each field has its own conventions: design portfolios lean on visuals, developer portfolios on working projects and code, and writing portfolios on published samples. Seeing several examples helps you tell a convention apart from one person’s style.

Do not copy the wording, the visual design, or any claims. Your portfolio only works if it describes your own experience in your own voice. A useful exercise is to write down, for each section of a site you like, one sentence on what it is trying to tell the reader. Then ask whether you need that section at all.

These four formats overlap, so it is easy to end up with a website that simply repeats your resume. The table shows what each one is best at.

In practice, your portfolio links to the other three: it hosts your case studies or project write-ups, offers your resume as a download, and links to your LinkedIn profile.

Create a folder on your computer called something like portfolio-content and a single text document inside it for your notes. Work through the list below. Rough notes are fine; you will refine them with the discovery prompt later in this step.

• Export your resume as a PDF with a clear filename, such as firstname-lastname-resume.pdf, so it looks tidy when someone downloads it. Remove your home address and anything else you would not want published on the open web.
• For your profile photo, use a square, high-resolution image with good light and a plain background. A square image is easiest to crop into a circle or card.
• Only use images and screenshots you own or have permission to use. Work from a past employer or client may be confidential; check before publishing, or create a simple diagram instead. Keep the original, full-size files; your coding tool can make smaller copies for the web.
• Check that every code repository you plan to link to is meant to be public, has a short description of what it is, and contains no passwords or keys. Open each live demo to make sure it still loads.
• Link to the published version of each writing sample where you can. If a piece is no longer online, keep a PDF copy, and only publish it if you have the right to.

Put all of these files in your portfolio-content folder so they are easy to find later.

Your notes are now the raw material. The next step is to shape them into a plan: what you will say, in what order, and how the site should feel. An AI chat assistant can help by interviewing you, the way a good career coach would.

Copy the discovery prompt at the top of this step into a new chat. The AI will first ask about your field and goals, then adapt its questions to them, asking a few at a time. Answer them using your notes, and paste in sections of your notes when that is quicker. The prompt tells the AI not to invent anything and not to write code yet, so the result is a plan built only from your real information.

When the AI delivers its plan, read it carefully before you accept it.

• Check every fact. Correct anything that is wrong or that the AI added on its own.
• Fill in each “[needs input]” gap, or remove that part of the outline.
• Pick one positioning statement, or combine the options into one you like.

Then save the final version as a document called portfolio-brief.md in your portfolio-content folder. The .md ending means Markdown, a plain text format that uses simple symbols such as # for headings. Any text editor can open it. In step 4 you copy this file into your project folder, and your AI coding tool reads it from there.

If you already have a coding agent such as Google Antigravity, you can run discovery inside it. This is the workflow behind this site:

Discovery interview

123

Second AI chat

12

AI tools are good at turning material into a website. They are not good at knowing your work. If you start with a vague request, you get a generic site full of guesses. If you start with real content, you get a site that sounds like you.

This step is about collecting that content before you build anything. Plan for an hour or two, spread over a couple of sittings. Of everything in this guide, it is the step I would least want you to skip.

A case study is a short story about one piece of work that shows how you approached it. The term is most common in design and product work, but the same structure works for a software project, a campaign, a series of articles, or a research study. You do not need a fancy format:

1. Context: the project, who it was for, and the situation, in two or three sentences.
2. Problem or brief: what was wrong, missing, or asked for, and for whom.
3. Your role: what you were responsible for, and who you worked with.
4. Process: how you approached it, such as research, sketches, drafts, prototypes, or experiments.
5. Decisions: the options you considered, what you chose, and why.
6. What you delivered: what was actually built, designed, published, or launched.
7. Outcome and evidence: what happened as a result, and how you know.
8. What you learned: what you would keep or do differently.

Use real outcomes. If you have numbers you are allowed to share, use them exactly. If you can only share an approximate figure, say that it is approximate and where it comes from (for example, “roughly a third fewer support tickets in the quarter after launch, based on the support team’s weekly reports”). If you have no number, use a qualitative result (“the client now uses the new logo across all its signage”). Evidence can also be a live link, a published piece, or a quote someone has agreed to let you use.

Plans and features change often, so treat the details below as a summary at the time of writing and check each tool’s official page before you sign up. Some tools offer a free tier with usage limits; others need a paid plan.

Google Antigravity (opens in a new tab) describes itself as an agentic development platform. It is available as an app, a command-line tool, and an IDE (a code editor), on macOS, Windows, and Linux. The Antigravity IDE (opens in a new tab) can work across the editor, the terminal, and a browser, which suits a build-and-preview workflow.

At the time of writing, the pricing page (opens in a new tab) lists a plan for individuals at no charge with basic weekly rate limits, meaning you can only use it so much each week. Google AI Pro and Ultra plans raise those limits. See the plans documentation (opens in a new tab) for current details, and the getting started guide (opens in a new tab) to install it.

Claude Code (opens in a new tab) is Anthropic’s AI coding assistant. You can use it in a terminal, through extensions for editors such as VS Code and JetBrains IDEs, in a desktop app, or on the web.

It requires a paid Claude plan (Pro, Max, Team, or Enterprise) or a Console account, which is Anthropic’s API platform. The free claude.ai plan does not include Claude Code, though you can still use free Claude chat for planning. Follow the setup guide (opens in a new tab) to install it and the quickstart (opens in a new tab) for your first session.

Claude Code (desktop app)

12

Many other tools can build a portfolio, including Cursor (opens in a new tab), GitHub Copilot (opens in a new tab), Replit (opens in a new tab), Bolt (opens in a new tab), Lovable (opens in a new tab), and v0 by Vercel (opens in a new tab). They differ in how they work and what they cost, so check each tool’s current plans and limits.

You now have a portfolio brief. You do not need to know how to code to turn it into a website, but you do need to give clear instructions, review what the tool produces, and ask for specific changes.

The build workflow in step 4 works with Google Antigravity, Claude Code, or another tool you prefer. No single tool is required.

An AI coding tool is an assistant that writes and edits code from instructions in plain English. You describe what you want, the tool writes the files, and you review the result. For a portfolio, that means the pages, the styling, and the small bits of behaviour such as a mobile menu or an image gallery.

The tool is fast, but it is not the author of your portfolio. It cannot know your work, and it can make mistakes. Your job is to supply accurate content, judge the result, and steer it.

AI tools come in two broad shapes. A coding agent works directly in a folder on your computer (or in a project the tool hosts for you): it creates and edits files, runs commands, and can often start a preview. A chat interface only replies with text, so you copy code into files yourself.

For building the site, use a coding agent. A chat interface is still useful for planning, which is why the discovery prompt in step 2 works in any chat AI.

Whichever tool you choose, the work follows the same loop. Expect to go around steps 4 to 6 of this loop many times.

The master prompt at the top of this step gives the agent everything it needs for a strong first version. Replace each part in square brackets with your own information before you send it. It works for any field.

The agent reads your brief from portfolio-brief.md in the project folder, so keep that file up to date: when your details change, edit the file and ask the agent to read it again. The prompt also keeps the brief out of your public repository.

The prompt asks for Next.js with TypeScript, a popular framework for building websites and a version of JavaScript that catches many mistakes before they reach your site. Sticking to one stack keeps the agent from picking something different each time, and the publishing steps cover it on both hosts: Vercel, or GitHub Pages as a static export.

The field notes part tells the agent how your field usually presents work, such as image-led case studies for designers or repository and demo links for developers. Keep the line that matches you, adapt it, or write your own, and delete the rest.

One of its rules keeps secrets out of your code, such as an API key (a password-like code that lets a program use a paid or private service). A typical portfolio does not need one.

Another rule names your host. Keep Vercel or GitHub Pages, whichever you plan to use. If you have not decided yet, the comparison in step 6, Choose your host, helps you pick; if you are still unsure, keep Vercel, which also runs sites that need server code.

The first version will rarely be right. The quality of your feedback decides how quickly it improves. “Make it better” forces the tool to guess, and it may change things you liked. Specific feedback says where the problem is, what you see, and what you want instead.

A few habits make this loop safer:

• Make small changes, one issue at a time. If something breaks, you will know which change caused it.
• Review what changed. Most coding agents show a diff, a view of exactly which lines were added or removed. Skim it, and check the preview, before accepting.
• Keep a copy before large changes. Before a big redesign, save a copy of the project folder, or once you have set up GitHub, make a commit. Step 5 explains commits.

Expect the first version to look clean but generic: AI tools tend to fall back on the same safe layouts, fonts, and colours. Show the agent sites you like instead of describing a style in words.

• Collect 2 or 3 references. Browse real sites on Refero (opens in a new tab), a large library of real product and website screenshots with a free plan, or on Awwwards (opens in a new tab) and Godly (opens in a new tab) for more striking web design. Take screenshots of the parts you like and attach them to the agent, saying what you like about each one: the spacing, the type, the colours, or the layout.
• Give the agent a style file. Refero Styles (opens in a new tab) turns real sites into a DESIGN.md file listing their colours, typography, spacing, and components, written for AI coding tools. Save one you like in your project folder and ask the agent to follow it.
• Add motion sparingly. React Bits (opens in a new tab) is a free, open source collection of animated React components, such as text effects and backgrounds, that work in a Next.js site. Pick one, for example for your hero heading, choose its TypeScript version, and ask the agent to add it and turn it off for visitors who prefer reduced motion. One or two effects feel polished; ten feel like a template.
• Use ready-made building blocks. shadcn/ui (opens in a new tab) provides well-built, accessible components such as buttons, menus, and dialogs that your agent can add to the project instead of writing its own.
• Keep the system small. One or two fonts, for example from Google Fonts (opens in a new tab), and one accent colour. A palette tool such as Coolors (opens in a new tab) helps you choose colours that work together.
• Use real images. A good photo of you and real screenshots of your work make a portfolio feel personal far more than stock photos or AI-generated images do.
• Be inspired, do not copy. Take the feel of a reference, not its brand. Never reuse another site’s logo, illustrations, photos, or text, and change the colours and fonts so your site looks like you.

Improve the visual design of my portfolio using the references I am giving you.

REFERENCES
[attach 2 or 3 screenshots, or name a DESIGN.md file in this project folder, and say what you like about each one, for example "the generous spacing" or "the bold serif headings"]

RULES
1. First describe the design direction you will take from the references: typography, colour, spacing, and layout. Wait for my approval.
2. Take the feel, not the brand. Do not copy logos, illustrations, photos, text, or exact layouts, and adapt the colours and fonts so the site looks like mine.
3. Do not change my text, links, or section order.
4. Keep it accessible: readable contrast, visible focus states, and no motion for visitors who prefer reduced motion.
5. Keep the stack as it is (Next.js and TypeScript), and ask before adding any dependency.
6. Afterwards, list the files you changed and what I should check in the preview.

Use these once the first version exists. Each one asks the agent to diagnose before changing anything, keep changes small, leave your existing content alone, and report what it changed.

Review the visual design of my portfolio before changing anything.

Focus on typography (sizes, line length, line height), spacing and alignment, visual hierarchy, colour and contrast, and consistency between sections.

What I have noticed: [describe what feels off, for example "the hero text feels cramped and the project cards look unrelated to the rest of the page"]

RULES
1. First list the five most important issues, ordered by impact, with the change you would make for each. Wait for my approval.
2. Do not change any text, links, or section order.
3. Do not add dependencies or heavy animation.
4. Keep changes small and consistent with the existing style.
5. Afterwards, list the files you changed and what I should check in the preview.

Check my portfolio for mobile and tablet problems at widths of 375px, 414px, and 768px.

Look for: horizontal scrolling, text or images that overflow, text that is too small to read, buttons or links that are too small to tap, and navigation that does not work on small screens.

Issues I have already seen: [describe them, including the page, section, and screen width]

RULES
1. Diagnose first. List each issue with the section and width where it happens, and the likely cause.
2. Fix with the smallest possible changes. Do not change the desktop layout unless it is needed for the fix.
3. Do not remove any content to make things fit.
4. Afterwards, list the files you changed and the widths I should re-check.

Help me present one piece of work as a project or case study page on my portfolio.

PROJECT NOTES
[paste your notes for this project]

VISUALS AND LINKS
[list the file names of images in the project folder, and any repository, demo, or published links for this project, or write "none"]

STRUCTURE
Context, Problem or brief, My role, Process, Decisions, What I delivered, Outcome and evidence, What I learned. Adjust the headings if a different order suits my field better, and tell me why.

RULES
1. Use only facts from my notes. Where something is missing, write "[needs input]" and ask me.
2. Do not invent metrics, quotes, clients, or results. Keep qualitative results qualitative.
3. Flag anything that may be confidential, such as client or internal names, unreleased work, private code, or revenue.
4. Keep each part short and easy to scan, with clear headings. Place visuals next to the part they explain, with alt text for each image.
5. Show me the written text for approval before you change any code.
6. Then build it using the site's existing design and components, make sure it reads well on mobile, and list the files you changed.

Audit my portfolio for accessibility and basic SEO. Report first; do not change anything yet.

CHECK
1. One main heading (h1) per page and a logical heading order.
2. Alt text on meaningful images; decorative images hidden from screen readers.
3. Descriptive link text (no "click here").
4. Every interactive element works with the keyboard and has a visible focus state.
5. Text colour contrast meets WCAG AA.
6. Form fields have labels.
7. Each page has a unique title and meta description, Open Graph tags for link previews, a favicon, and a language attribute.

RULES
1. List findings with severity (high, medium, low) and the file where each one is.
2. Wait for my confirmation before fixing.
3. Propose any new alt text, titles, or descriptions for my approval. Do not change other content or the visual design.
4. Do not add dependencies. List the files you changed when you are done.

Do a final quality check of my portfolio before I publish it. Report only; do not fix anything until I confirm.

CHECK
1. All internal links and section anchors work.
2. List every external link so I can open and confirm each one.
3. No placeholder text, sample content, "#" links, or leftover notes.
4. No invented metrics, projects, clients, testimonials, or claims compared with my brief.
5. My resume opens and my contact details are correct.
6. Layout works at 375px, 768px, and 1280px wide, and the site is usable with a keyboard.
7. No errors in the browser console.
8. The production build succeeds, if this project has a build command. Run it and show me the result.
9. No passwords, API keys, or other secrets in the code, and .gitignore covers dependencies, build output, and environment files.

Report the result as a checklist marked pass or fail. For each failure, propose the smallest fix.

For a bug in your local preview, use the prompt below. For build, deploy, or address problems, the Help desk has a way to find the cause and a table of common errors.

Something on my portfolio is broken. Help me fix it without breaking anything else.

WHAT I SEE
[describe the problem: which page or section, what you expected, what happens instead, and the steps to make it happen]

ERROR MESSAGE (if any)
[paste the exact error text]

RULES
1. Diagnose first. Investigate and explain the most likely cause before changing any code.
2. Propose the smallest safe fix and wait for my approval.
3. Do not rewrite, refactor, or reformat unrelated code. Do not remove features or content.
4. If you are not sure of the cause, say so and suggest how we can find out.
5. After the fix, explain how I can confirm it works, and check that the rest of the site still works.
6. List every file you changed.

If something breaks after you deploy, the Help desk has a fuller diagnostic prompt.

Public or private? If you are unsure, private is the safer default, unless you plan to host with GitHub Pages on a free GitHub account (see below).

• Public: anyone on the internet can read the repository, including every file and every past commit (see GitHub’s guide: About repositories (opens in a new tab)). If you go public, check the secrets section before your first push.
• Private: only you and people you invite can see it.

Your host affects this choice:

• GitHub Pages: needs a public repository on GitHub Free (see the host comparison).
• Vercel (Hobby plan): public or private both work when the repository belongs to your personal account. On Hobby, Vercel cannot deploy a private repository owned by a GitHub organization (see the Vercel Git docs (opens in a new tab)).

Choose the path that matches how comfortable you feel. If you built the site with an AI coding agent, path A is usually the easiest. If you would rather click buttons, use path B.

Many coding agents can run Git commands for you, inside your project folder. That is convenient, but you should still understand what is happening. Ask the agent to explain each command before it runs, and to stop before it pushes, so you can check nothing private is about to go online.

The prompt near the top of this step asks your agent to work exactly that way.

GitHub Desktop is GitHub’s free app for Windows and macOS that does the same job with buttons instead of commands. You add your project folder to the app, make a first commit, then choose Publish repository. The publish dialog has a Keep this code private checkbox; leave it ticked for a private repository. Labels may differ slightly between versions. Adding an existing project to GitHub using GitHub Desktop (opens in a new tab)

A terminal is a window where you type commands instead of clicking. Most code editors have one built in (look for a Terminal menu). Open it so that it is pointing at your project folder, the one that contains your site’s files. This path needs Git installed on your computer; if the first command below prints an error instead of a version number, use path A or B instead. Run these one at a time, in order.

git --version

git init

git add .

git config --global user.name "Your Name"

git config --global user.email "you@example.com"

git commit -m "Initial portfolio"

git branch -M main

git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO.git

git push -u origin main

On your repository’s page on GitHub you can choose Add file → Upload files, drag files in, and commit them. Browser uploads are limited to 25 MiB per file and up to 100 files at a time, and you will have to repeat the upload by hand every time you change something. Never upload the node_modules or .next folders (they are generated and huge) or any .env file (it may contain secrets). Official guide: Adding a file to a repository (opens in a new tab).

github.com

123

Once your site is live (step 7: Vercel or GitHub Pages), updating it is a loop: edit your files, commit, push. Your host notices the push and publishes the new version automatically. Vercel starts a new deployment; on GitHub Pages it can take up to 10 minutes for changes to appear. Your AI agent or GitHub Desktop can do the commit and push for you; on the command line it looks like this:

git status

git add .

git commit -m "Update projects section"

git push

A secret is anything that grants access or that you would not print on a public poster: an API key (a password-like code that lets a program use a paid or private service), passwords, access tokens, and private details such as your phone number or home address. A typical portfolio needs no secrets at all. If you add a contact form through a third-party service, it may give you a key that is designed to be public; follow that service’s own documentation on where to put it.

github.com: .gitignore

123

Your AI tool has built a portfolio that runs on your computer. Before anyone else can see it, the code needs a home online that a hosting service can read. That home is GitHub. This step explains the handful of terms you need, then gives you three main ways to get your project there, plus a browser-upload fallback.

If your project is already on GitHub (some AI tools create the repository for you), check the secrets section and the host comparison below, then move on to step 7 for Vercel or GitHub Pages.

Git is a tool that records the history of a folder of files. GitHub is a website that stores that history online, so it is backed up, shareable, and readable by hosting services such as Vercel and GitHub Pages. You will meet these words throughout the rest of the guide:

• You can undo a bad AI edit. AI tools sometimes change more than you asked. If you commit each working version, you can return to it quickly instead of trying to describe what used to be there.
• You get a history. Every commit shows what changed and when, which makes it much easier to work out when something broke.
• Your host publishes from it. Once you set up Vercel or GitHub Pages in step 7, every push to the branch your host publishes from (normally main) publishes a new version of the site.

• Sign-in fails, or the terminal asks for a password: read the sign-in note in path C.
• A key or .env file went up by mistake: revoke it first, then follow Keep secrets out of your repository.
• Something else: look up the symptom in the Help desk table, or undo a change that broke things.

With your code on GitHub and nothing private in it, you are ready to put it on the internet. A host is the service that takes your code from GitHub and serves it at a web address. This guide covers two that can publish straight from your repository at no cost: Vercel and GitHub Pages. Both suit a portfolio. The biggest difference is whether your site needs code that runs on a server.

Free plans come with conditions and usage limits, and both companies can change them, so check the official pages linked below before you rely on them.

Pick one. You only need one host, and you can follow just its panel in step 7.

• Choose Vercel if your site uses server features (for example Next.js API routes or form handling on the server), you want to keep the repository private, or you want the least configuration.
• Choose GitHub Pages if your site is plain HTML, CSS, and JavaScript or a static export, you are happy for the repository to be public, and you want everything in one place on GitHub. A contact form can still work there through a third-party form service that runs in the browser.
• Not sure? Ask your AI tool whether your project needs a server. The prompt above has it inspect the project and answer before changing anything.

Before you add the link to your resume, your profiles, or your applications, go through this list once on the live site. Tick each item as you confirm it. Nothing is saved, so if you reload the page the list starts fresh, which is handy when you run through it again after a big update.

If an item fails, fix it with your AI coding tool (the prompts in step 4 help), push the change, and check again on the deployed site. The Help desk covers common problems.

If you followed this guide from the start, you now have:

• A portfolio built from your real experience and projects, with an AI coding tool doing the coding.
• Your code stored on GitHub, with a history of every change you have made.
• A live site on Vercel or GitHub Pages that updates when you push a change.
• Optionally, your own custom domain with HTTPS.
• A repeatable workflow: describe a change, review it, push it, and check the live site.

That last point matters most. The portfolio is never really finished, and you now know how to keep improving it without starting over.

• Update it after each project. Add new work while the details, decisions, and results are still fresh.
• Review your links every few months. Once a quarter, click through your contact, resume, and project links to catch anything that has moved or expired.
• Renew your domain if you bought one. Turn on auto-renew at your registrar, or set a reminder before the renewal date. An expired domain takes your portfolio offline.

Find the symptom in the Help desk, then change one thing at a time:

• Build, Vercel, and live-site problems
• GitHub Pages problems
• Domain, DNS, and HTTPS problems
• Roll back to a working version