Project Scaffold

Set up the file structure, design tokens, and base CSS. This is the foundation every other milestone builds on. Get the tokens right and the rest falls into place.

Create a portfolio website project with this structure:

  index.html
  assets/css/style.css
  assets/js/main.js

In style.css, set up CSS custom properties as a design system:

- Dark background (#0a0a0a), light text (#ffffff), secondary text (#b0b0b0)
- Font stacks: a monospace font for code/labels, system-ui for body text,
  and a bold display font for headings
- Spacing scale: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px
- Type scale: 0.75rem, 0.875rem, 1rem, 1.25rem, 1.5rem, 2rem, 3rem
- Border colors: subtle (#1a1a1a), default (#303030), strong (#505050)
- Transitions: fast (0.15s), base (0.2s), slow (0.3s)
- A full CSS reset (box-sizing, margin, padding)

In index.html, set up a minimal HTML5 document with lang="en",
viewport meta, and links to the stylesheet and script. Leave the
body empty for now. We will fill it in the next steps.

Do not add any content yet. This is only the scaffold.

VERIFY BEFORE CONTINUING

All three files exist at the correct paths
CSS custom properties are defined on :root
Spacing scale has at least 6 steps, type scale has at least 5
CSS reset applies box-sizing: border-box to all elements
HTML has lang="en" and the viewport meta tag

02

Global Layout

Build the header, footer, and responsive page shell. Nail the semantic landmarks here. This structure wraps everything that follows.

Build the global layout for this portfolio in index.html:

HEADER:
- Sticky header with my name/logo on the left
- Navigation links on the right: Work, About, Contact
- Use <header> and <nav> with aria-label="Main navigation"
- Mobile: collapse nav into a hamburger button that toggles
  a hidden menu. Use a <button> with aria-expanded and
  aria-controls. Toggle the nav visibility with a data attribute,
  not a CSS class.

MAIN:
- Wrap all content sections in <main id="main-content">
- Add a skip-to-content link as the first element in <body>:
  <a href="#main-content" class="skip-link">Skip to content</a>
- Leave <main> empty for now. We add sections next

FOOTER:
- Use <footer> with copyright year, social links (GitHub,
  LinkedIn, Twitter as icon links with aria-label), and a
  "back to top" anchor
- Style the footer with a top border and muted text

Use the CSS custom properties from style.css for all spacing,
colors, and typography. Use BEM naming for CSS classes.

VERIFY BEFORE CONTINUING

Page has <header>, <main>, <footer> landmarks
Skip link is the first focusable element
Nav uses aria-label and the hamburger has aria-expanded
Resize to mobile: hamburger appears and toggles the menu
All CSS uses custom properties, not hard-coded values

03

Hero Section

The first thing visitors see. Strong typographic hierarchy, a clear role statement, and a call-to-action. Keep it minimal. Whitespace is your friend.

Add a hero section as the first child of <main>:

- Wrap in <section class="hero">. No aria-label needed since
  the h1 labels it
- Large <h1> with my name (use placeholder "Jane Developer")
- Subtitle <p> with my role: "Full-Stack Developer"
- One-sentence tagline beneath: "I build fast, accessible
  web experiences with clean code and modern tools."
- Two CTAs: a primary <a> linking to #work ("View My Work")
  and a secondary <a> linking to #contact ("Get in Touch")
- Style the primary CTA as a solid button, secondary as an
  outlined/ghost button
- Use generous vertical padding so the hero fills at
  least 80vh on desktop
- Add a subtle CSS entrance animation (fade + translate up)
  using @keyframes, triggered on page load

Keep typography hierarchy clear: h1 is the largest element
on the page, subtitle is secondary color, tagline is body size.

VERIFY BEFORE CONTINUING

Page has exactly one <h1>
CTAs are <a> elements (they navigate to anchors)
Hero fills the viewport on first load
Animation respects prefers-reduced-motion

04

Projects Grid

The core content of any portfolio. Build project cards that show your work clearly with images, context, and tech stack.

Add a projects section after the hero:

- Use <section id="work" aria-labelledby="work-heading">
- <h2 id="work-heading"> as the section title: "Selected Work"
- Display 6 project cards using CSS Grid:
  - 2 columns on desktop (min 768px)
  - 1 column on mobile
- Each card is an <article class="project-card"> containing:
  - A thumbnail image (use placeholder dimensions 800x600,
    add width and height attributes, alt text describing the project)
  - <h3> with the project title
  - One-sentence description in a <p>
  - Tech stack as a list of small tags/pills (e.g. "React",
    "Node.js", "PostgreSQL")
  - An external link (<a> with target="_blank" rel="noopener
    noreferrer") to "View Project ↗"
- On hover, add a subtle scale transform or border highlight
- Use BEM naming: .project-card, .project-card__image,
  .project-card__title, .project-card__tags, etc.
- Use placeholder project names: "Dashboard Redesign",
  "E-commerce Platform", "Weather App", "Task Manager",
  "Blog Engine", "API Gateway"

VERIFY BEFORE CONTINUING

Section heading is <h2>, no levels skipped from the <h1>
Each card uses <article> with an <h3>
Images have width, height, and meaningful alt text
Grid collapses to single column on mobile
External links have rel="noopener noreferrer"

05

About Section

Give visitors context about who you are. Two-column layout with a photo and bio, plus a categorized skills list.

Add an about section after the projects grid:

- Use <section id="about" aria-labelledby="about-heading">
- <h2 id="about-heading">: "About Me"
- Two-column layout on desktop, stacked on mobile:

  LEFT COLUMN:
  - Professional photo placeholder (400x400) inside a
    <figure> with <figcaption> containing my name
  - Add width and height attributes to the image
  - Square aspect ratio, subtle border

  RIGHT COLUMN:
  - 2-3 paragraph bio using placeholder text about being
    a developer who cares about performance, accessibility,
    and clean architecture
  - Skills grouped by category using a <dl> (definition list):
    - Frontend: HTML, CSS, JavaScript, React, TypeScript
    - Backend: Node.js, Python, PostgreSQL, REST APIs
    - Tools: Git, Docker, Figma, VS Code
  - Each skill as a small tag/pill inside the <dd>
  - Optional: a "Download Resume" link styled as a
    secondary button

Use CSS Grid or Flexbox for the two-column layout.
Collapse to single column at 768px.

VERIFY BEFORE CONTINUING

Photo uses <figure> and <figcaption>
Skills use a <dl> with <dt> for categories and <dd> for items
Heading is <h2>, maintains hierarchy
Layout stacks correctly on mobile

06

Contact

A working contact form with proper validation and accessibility. This is where visitors convert, so make it frictionless.

Add a contact section after the about section:

- Use <section id="contact" aria-labelledby="contact-heading">
- <h2 id="contact-heading">: "Get in Touch"
- Two-column layout:

  LEFT COLUMN (Contact Form):
  - <form novalidate> (we do custom JS validation)
  - Fields: Name (text, required), Email (email, required),
    Message (textarea, required)
  - Every <input> and <textarea> must have a <label>
    associated via for/id
  - Add aria-describedby hints: "Your name as you'd like
    to be addressed", "We'll reply to this address",
    "Tell me about your project"
  - A submit <button type="submit">: "Send Message"
  - Add JS validation on submit:
    - Check required fields, validate email format
    - On error: set aria-invalid="true" on the field,
      show an error message linked via aria-describedby
    - On success: show a confirmation message in an
      aria-live="polite" region
  - Add a mailto: fallback link below the form:
    "Prefer email? [email protected]"

  RIGHT COLUMN (Social Links):
  - List of contact methods: Email, GitHub, LinkedIn, Twitter
  - Each as an <a> with the platform name and an arrow (↗)
  - Use target="_blank" rel="noopener noreferrer" for
    external links

Collapse to single column on mobile (form above, links below).

VERIFY BEFORE CONTINUING

Every input has an associated <label>
Form uses novalidate with custom JS validation
Error states use aria-invalid and aria-describedby
Success message uses an aria-live region
Tab through the form and confirm focus order is logical

07

Polish

Refine the entire site: animations, hover states, responsive fine-tuning, and a dark/light theme toggle. This pass turns a functional site into a polished one.

Refine the portfolio site with these improvements:

SMOOTH SCROLL:
- Add scroll-behavior: smooth to html
- Smooth anchor navigation for Work, About, Contact links

SCROLL ANIMATIONS:
- Add scroll-triggered fade-in animations for each section
  using IntersectionObserver
- Elements start with opacity: 0 and translateY(24px), then
  animate to visible when they enter the viewport
- Stagger project cards with a transition-delay
- Wrap all animations in a prefers-reduced-motion check.
  If reduced motion is preferred, skip all animations and
  show elements immediately

HOVER STATES:
- Review every interactive element (links, buttons, cards)
- Ensure all have visible hover and focus states
- Project cards: subtle translateY(-4px) on hover
- Navigation links: underline or color shift
- Buttons: brightness or background shift
- All transitions use the CSS custom property durations

THEME TOGGLE:
- Add a dark/light theme toggle <button> in the header
- Toggle a data-theme attribute on <html> between "dark"
  and "light"
- Define light theme overrides: swap background/text colors,
  adjust border colors
- Persist the choice in localStorage
- Respect prefers-color-scheme as the default

RESPONSIVE REVIEW:
- Test at 320px, 480px, 768px, 1024px, 1440px, 2560px
- Fix any overflow, text wrapping, or spacing issues
- Ensure touch targets are at least 44x44px on mobile

VERIFY BEFORE CONTINUING

Animations disable when prefers-reduced-motion: reduce is set
Theme toggle persists across page reloads
Every interactive element has a visible :focus-visible state
No horizontal overflow at any viewport width from 320px up
All transitions use custom property durations, not hard-coded values

08

Ship It

The final pass: SEO, performance, accessibility audit, and deployment. This is what separates a project from a product.

Finalize the portfolio for production:

SEO:
- Add complete <head> meta tags:
  - <title> matching the h1 content + "| Developer Portfolio"
  - meta description (150-160 characters about my work)
  - Open Graph: og:title, og:description, og:image (1200x630),
    og:url, og:type="website"
  - Twitter card: summary_large_image
  - Canonical URL
  - Favicon (link to a placeholder SVG)
  - theme-color matching the background
- Add JSON-LD structured data using the Person schema:
  name, jobTitle, url, sameAs (social links), description
- Verify heading hierarchy: single h1, no skipped levels

PERFORMANCE:
- Add loading="lazy" to all images below the fold
- Add width and height attributes to every <img> to
  prevent layout shift (CLS)
- Add fetchpriority="high" to the hero image or LCP element
- Add <link rel="preconnect"> for any external font domains
- Minify the CSS (remove comments, compress whitespace)

ACCESSIBILITY AUDIT:
- Check color contrast meets WCAG AA (4.5:1 for text,
  3:1 for large text) in both dark and light themes
- Keyboard navigation: tab through the entire page and
  verify focus order is logical, nothing is trapped,
  skip link works
- Verify all images have meaningful alt text (or alt=""
  for decorative images)
- Run through a screen reader checklist: headings announce
  correctly, landmarks are named, form labels read properly

DEPLOYMENT:
- Add a netlify.toml or vercel.json with:
  - Custom 404 page
  - Security headers (X-Frame-Options, X-Content-Type-Options,
    Referrer-Policy, Permissions-Policy)
  - Cache-Control for static assets (1 year for CSS/JS/images)
- Create a simple README.md with project name, screenshot
  placeholder, and deploy instructions

VERIFY BEFORE CONTINUING

Heading hierarchy: one <h1>, no skipped levels across the page
All below-fold images have loading="lazy"
JSON-LD is valid (paste into Google's Rich Results Test)
Tab through the entire page, focus should never get trapped or lost
Lighthouse scores: Performance >90, Accessibility >95, SEO >95

Portfolio Site

MILESTONES

Project Scaffold

Global Layout

Hero Section

Projects Grid

About Section

Contact

Polish

Ship It

MILESTONES

Project Scaffold

Global Layout

Hero Section

Projects Grid

About Section

Contact

Polish

Ship It

Level up the skills behind this pack

Modern CSS

Components

Design Tokens

Performance

Accessibility

SEO