Projects Beginner 15 min read · ~2 hours to build

Build a Portfolio Website with AI: Step-by-Step Guide for Vibe Coders

Your portfolio is the first thing every client, employer, and collaborator sees. In this guide, you'll build a professional, live portfolio website using AI tools — from zero to deployed URL in one session.

By The AI-Enabled Coder Published March 17, 2026 Tested with Cursor 0.47, Claude Sonnet 4, Vercel (free tier) — March 2026

What You'll Build

A complete, deployed portfolio website with: hero section with your name and role, projects grid, about section, contact form, mobile-responsive design, and live HTTPS URL. Stack: plain HTML + CSS + JavaScript. Hosting: Vercel (free). Time: 1–3 hours.

Before You Start

What You Need

  • Cursor (free) — cursor.com — the best AI code editor for this project
  • GitHub account (free) — github.com
  • Vercel account (free) — vercel.com
  • 30 minutes of focused time for the initial build, more for polish

Why Plain HTML, Not React?

You'll see portfolio tutorials that use React, Next.js, or other frameworks. Ignore them for your first portfolio. Plain HTML/CSS/JavaScript is:

  • Faster to build — no build process, no configuration
  • Faster to load — no JavaScript framework overhead
  • Easier to understand — you can read every file
  • Easier to deploy — just static files, works everywhere

You can always rebuild it in React later. Start simple and ship.

Content to Gather Before You Start

AI can build the structure instantly. The content only comes from you. Before opening Cursor, collect:

  • Your name and professional title (or the one you want to claim)
  • 2–4 sentences about yourself and your work
  • 2–5 projects to showcase (name, description, what you built, links if live)
  • Your email address and links (GitHub, LinkedIn, Twitter)
  • Color preferences or reference sites you like the look of

Step 1: Set Up Your Project

Create the Folder Structure

Open Cursor. Create a new folder called portfolio. Inside it, create this structure:

portfolio/
├── index.html       ← Main page
├── css/
│   └── styles.css   ← All styles
├── js/
│   └── main.js      ← All interactivity
└── images/          ← Your photos and project screenshots

In Cursor: File → Open Folder → select your portfolio folder. Now AI has full context of your project.

Initialize Git

# In Cursor's terminal (View → Terminal):
git init
git branch -M main

# Create .gitignore
echo ".DS_Store" > .gitignore
echo "*.log" >> .gitignore

Step 2: Build the HTML Structure

Your Prompt for the HTML Skeleton

Cursor / Claude Prompt

"Create index.html for my portfolio website. I am [YOUR NAME], a [YOUR ROLE, e.g., 'AI-enabled web developer' or 'vibe coder building real products']. Include these sections: (1) nav with my name/logo and links to About, Projects, Contact, (2) hero section with my name, role, and a call-to-action button, (3) projects grid (3 columns, cards with image, title, description, tags, live link), (4) about section with photo placeholder and my background, (5) contact section with email form, (6) footer with social links. Use semantic HTML5 — header, nav, main, section, footer. Add id attributes to each section for smooth scrolling."

What AI Will Generate (Key Sections)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Your Name] — AI-Enabled Developer</title>
  <meta name="description" content="[Your 1-sentence description]">
  <link rel="stylesheet" href="css/styles.css">
</head>
<body>

  <!-- Navigation -->
  <header class="nav-header">
    <nav class="nav-container">
      <a href="/" class="nav-logo">[Your Name]</a>
      <ul class="nav-links">
        <li><a href="#about">About</a></li>
        <li><a href="#projects">Projects</a></li>
        <li><a href="#contact">Contact</a></li>
      </ul>
      <button class="nav-toggle" aria-label="Toggle menu">☰</button>
    </nav>
  </header>

  <main>
    <!-- Hero -->
    <section id="hero" class="hero-section">
      <div class="hero-content">
        <h1>Hi, I'm <span class="highlight">[Your Name]</span></h1>
        <p class="hero-subtitle">[Your role — be specific and interesting]</p>
        <div class="hero-cta">
          <a href="#projects" class="btn btn-primary">See My Work</a>
          <a href="#contact" class="btn btn-secondary">Get In Touch</a>
        </div>
      </div>
    </section>

    <!-- Projects -->
    <section id="projects" class="projects-section">
      <div class="section-container">
        <h2>Projects</h2>
        <div class="projects-grid">
          <article class="project-card">
            <div class="project-image">
              <img src="images/project-1.png" alt="Project 1" loading="lazy">
            </div>
            <div class="project-info">
              <h3>[Project Name]</h3>
              <p>[What you built and why it's interesting]</p>
              <div class="project-tags">
                <span class="tag">Next.js</span>
                <span class="tag">Supabase</span>
                <span class="tag">AI</span>
              </div>
              <a href="https://yourproject.com" class="project-link" target="_blank">View Live →</a>
            </div>
          </article>
          <!-- Repeat for each project -->
        </div>
      </div>
    </section>

    <!-- About, Contact sections follow same pattern -->
  </main>

  <footer>
    <p>Built with AI tools. © 2026 [Your Name]</p>
  </footer>

  <script src="js/main.js"></script>
</body>
</html>

After AI generates this: Replace all the placeholder content with your real information. AI handles structure; your story is yours.

Step 3: Style with CSS

Cursor Prompt

"Write css/styles.css for my portfolio. Design goals: modern, minimal, professional. Dark mode with [YOUR COLOR, e.g., 'electric blue' or 'emerald green'] as the accent. Use CSS custom properties (variables) for colors. Include: base reset, typography (Inter or similar clean font from Google Fonts), responsive nav (hamburger menu on mobile), full-viewport hero with centered content, 3-column projects grid that collapses to 1 column on mobile, card hover effects with subtle shadow and lift, smooth section transitions. Target: looks as professional as a $5,000 agency portfolio."

Key CSS Patterns AI Will Generate

/* css/styles.css — Key patterns to understand */

/* CSS Custom Properties — your brand colors in one place */
:root {
  --color-bg: #0A0E1A;
  --color-surface: #141828;
  --color-accent: #6366F1;      /* Your main color — change this */
  --color-text: #E2E8F0;
  --color-text-muted: #94A3B8;
  --font-sans: 'Inter', sans-serif;
  --border-radius: 12px;
  --transition: 0.2s ease;
}

/* Projects grid — responsive */
.projects-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 2rem;
}

@media (max-width: 768px) {
  .projects-grid {
    grid-template-columns: 1fr;  /* Stack on mobile */
  }
}

/* Project card hover effect */
.project-card {
  background: var(--color-surface);
  border-radius: var(--border-radius);
  overflow: hidden;
  transition: transform var(--transition), box-shadow var(--transition);
}

.project-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
}

Iterate on the design: Open index.html directly in your browser (drag the file in). Ask AI for adjustments: "Make the hero section full viewport height" or "Add a gradient to the hero background" or "Make the nav sticky on scroll."

Step 4: Add Interactivity with JavaScript

Cursor Prompt

"Write js/main.js for my portfolio. Add: (1) smooth scrolling when nav links are clicked, (2) mobile hamburger menu toggle (add/remove 'nav-open' class on nav), (3) active nav link highlighting based on scroll position, (4) contact form — on submit, show a 'Message sent!' success message and clear the form (no backend needed — just fake success for now). Keep it under 80 lines, no external libraries."

// js/main.js — Simplified version of what AI generates

// Smooth scrolling for nav links
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
  anchor.addEventListener('click', function(e) {
    e.preventDefault()
    const target = document.querySelector(this.getAttribute('href'))
    if (target) {
      target.scrollIntoView({ behavior: 'smooth', block: 'start' })
    }
  })
})

// Mobile menu toggle
const navToggle = document.querySelector('.nav-toggle')
const navLinks = document.querySelector('.nav-links')

navToggle?.addEventListener('click', () => {
  navLinks.classList.toggle('nav-open')
  navToggle.textContent = navLinks.classList.contains('nav-open') ? '✕' : '☰'
})

// Contact form
const form = document.querySelector('#contact-form')
form?.addEventListener('submit', function(e) {
  e.preventDefault()
  const btn = form.querySelector('button[type="submit"]')
  btn.textContent = '✓ Message Sent!'
  btn.disabled = true
  form.reset()
  setTimeout(() => { btn.textContent = 'Send Message'; btn.disabled = false }, 3000)
})

Step 5: Polish and Personalize

Don't Skip the Content — It's 80% of the Impression

The #1 mistake on AI-built portfolios: placeholder content left in, or generic descriptions that don't say anything distinctive. Spend real time on:

  • Your hero tagline: Not "Full-Stack Developer." Try "I build production apps with AI tools — in a fraction of the traditional time."
  • Project descriptions: Not "An e-commerce site." Try "Built a full Stripe-integrated store in 4 days using Cursor and Claude. Handles 50+ SKUs with real inventory management."
  • About section: Your real story is your differentiation. If you came from a non-tech background, say it. That's interesting.

Quick Polish Prompts

Polish Prompts

"Add a subtle scroll animation — sections fade in when they enter the viewport using Intersection Observer. No libraries."

Polish Prompts

"Add a 'copy email' button in the contact section — clicking it copies my email address to clipboard and shows 'Copied!' for 2 seconds."

Polish Prompts

"Add a loading skeleton to the projects grid — gray animated placeholder cards that appear for 500ms before the real content shows."

Step 6: Deploy to Vercel (Free, 5 Minutes)

Push to GitHub First

# In Cursor's terminal:
git add .
git commit -m "Initial portfolio build"

# Create a new repo on github.com (name it: portfolio or yourname-portfolio)
# Then connect and push:
git remote add origin https://github.com/yourusername/portfolio.git
git push -u origin main

Deploy on Vercel

  1. Go to vercel.com and sign up with GitHub
  2. Click "New Project" → Import your portfolio repository
  3. Vercel detects it's a static site — no configuration needed
  4. Click "Deploy"
  5. In ~30 seconds: your portfolio is live at yourname-portfolio.vercel.app

HTTPS is automatic. Future pushes to main auto-deploy. You get preview deployments on branches. Free forever for static sites.

Custom Domain (Optional)

In Vercel → your project → Settings → Domains. Add your domain (yourname.dev or yourname.com). Domains cost $10–20/year. Vercel handles HTTPS automatically.

Common Problems and Fixes

"It looks fine on desktop but broken on mobile"

Fix Prompt

"My portfolio has these mobile issues: [describe exactly what you see — nav overlapping content, images too wide, text too small]. Here's the CSS: [paste relevant CSS]. Fix the mobile styles."

"The nav hamburger menu doesn't work"

Fix Prompt

"My mobile nav toggle doesn't show/hide the menu when clicked. Here's the HTML: [paste nav HTML]. Here's the JS: [paste toggle code]. Here's the CSS for .nav-links and .nav-open: [paste]. Debug and fix it."

"AI keeps regenerating the whole file"

When making small changes, be specific about what to change: "In the .project-card CSS block, add a border-left: 3px solid var(--color-accent). Don't change anything else." Vague prompts get sweeping regenerations.

What to Add Next

  • Blog section: "Add a /blog/ page that lists 3 articles with title, date, and excerpt cards." Writing about what you're building compounds into SEO and authority.
  • Contact form backend: Connect Formspree or EmailJS so form submissions actually reach your inbox.
  • Analytics: Add Plausible or Fathom (privacy-respecting) to see who visits.
  • Meta tags and Open Graph: So your link looks good when shared on Twitter/LinkedIn.

What to Learn Next

Frequently Asked Questions

Can I build a portfolio website with no coding experience?

Yes — this guide is designed for that exact situation. Using Cursor or Claude, you describe what you want in plain English and AI writes the code. You'll learn concepts as you go. Most beginners complete a working portfolio in 1–3 hours on their first attempt. The learning accelerates fast once you're working with real files.

What AI tool should I use to build my portfolio?

Cursor is the best choice — it's a full code editor with AI built in, you can see and edit the files directly, and it handles HTML/CSS/JS projects well. Claude (claude.ai) or ChatGPT work if you're comfortable copying code into files manually. For complete beginners, start with Cursor. It's free for the features you need here.

How long does it take to build a portfolio with AI?

A basic working portfolio (hero, projects, about, contact) takes 1–3 hours. A polished, custom-designed portfolio takes a full day. Deploying to Vercel takes 5 minutes. Budget a weekend to build something genuinely impressive — most of that time is content and design decisions, not waiting for AI to generate code.

Does my portfolio need to be built with React?

No. Plain HTML, CSS, and JavaScript is the better choice for a portfolio. It's simpler to build, loads faster, works everywhere without a build step, and is easier to understand when something goes wrong. Use React when you need component reuse, state management, or complex interactivity. A portfolio needs none of those things.