The Brief

Step 1: Yasmine's email

Every project starts with someone who needs something built. Here's yours.

Open materials/first-contact.md. This is an email from Yasmine Khelifi, a leather artisan in Tunis. Read it through.

Yasmine runs a workshop in the medina. Fifteen years of handcraft — bags, wallets, belts, custom pieces. Vegetable-tanned leather, traditional techniques from her grandmother. She sells through her workshop and two boutiques in Sidi Bou Said, but international customers who find her work while visiting Tunisia can't find her afterward. There's nothing online. She needs a portfolio website — large photos, a page about her process, a way for people to contact her. Not a shop. Her pieces are one-of-a-kind. People see the work, reach out, and talk.

Notice what she says about phones. "That's how most people will see it." A gallery owner in Paris, a private buyer in Milan — they'll find this site on a phone screen. If the layout breaks at that width, they'll close it before the first image loads. That requirement isn't a technical detail. It's about who her customers are and how they'll encounter her work.

Step 2: The planning pipeline

A real web development project follows a pipeline: requirements gathering, design, architecture, build, verification, deployment. This project practices the tail end — build, verify, and deploy. Everything upstream was done for you.

Think of it as a handoff. A senior developer took Yasmine's email and translated it into a full set of project materials: a requirements document, a design direction, a governance file with tickets. They left you a complete plan. Your job is to direct AI through the plan and verify the results.

This is deliberate. You'll create those upstream documents yourself starting in the next project. But first you need to see what good planning looks like — what a PRD contains, how design direction gets documented, how tickets break work into pieces. You work from it before you produce it.

The materials are in the materials/ folder. Four files, each with a specific role.

Step 3: The PRD

Open materials/prd.md. This is the Product Requirements Document — the file that translates what a client wants into what needs to be built.

A PRD is not a script to follow. It describes what needs to exist. Read through it and notice what it covers: the project overview (who Yasmine is, why the site exists), the goals (what the site must accomplish), the target audience (who will use it), the site structure (three pages, each with a defined purpose), the technical requirements (static HTML and CSS, semantic elements, responsive breakpoints, verification targets), and what's explicitly out of scope (no shop, no cart, no JavaScript framework).

The site structure is specific: index.html for the portfolio gallery, about.html for the process page, contact.html for the contact form. Three pages, three purposes.

The technical requirements call for semantic HTML throughout — <nav>, <main>, <section>, <article>, <footer>, <figure>, <figcaption>. These aren't interchangeable containers. Each one makes a claim about what the content is. A <section> creates a document landmark that screen readers announce and navigate to. A <div> does not. Every element choice affects how search engines read the page and how assistive technology presents it to people who depend on that structure.

The technical requirements also include verification targets — html-validate must report 0 errors, and Lighthouse scores must hit 90 or above across all four categories. These aren't suggestions. They're the bar the work has to clear.

Step 4: Design direction

Open materials/mockup-description.md. This is the design direction — it documents the visual identity of the site.

The color palette is drawn from Tunisian leather and medina architecture: saddle brown (#8B4513) for headings and borders, warm sand (#D2B48C) for section backgrounds, deep burgundy (#6B1C23) for buttons and accents, cream (#FDF5E6) for the page background, dark brown (#3E2723) for body text. The palette is restrained. The leather and the photography provide the visual richness — the site frames the work, it doesn't compete with it.

The layout approach is mobile-first. The base design targets 375px — a phone screen. Media queries expand the layout at 768px (tablet) and 1280px (desktop). Mobile-first means you design for the smallest screen first, then add complexity for larger screens. It's a choice, not a default. It reflects what Yasmine told you: phones are how most people will see this.

These are the kinds of pieces Yasmine makes. Structured bags with hand-saddle-stitching, solid brass hardware, vegetable-tanned leather with natural grain and warmth. The photos are the centerpiece of the site — minimum 600px wide on desktop, full width on mobile. The design direction says "no cropping, maintain original aspect ratios." The quality of the craft has to come through.

Step 5: CLAUDE.md and the tickets

Open materials/CLAUDE.md. This is the project governance file — the single document that tells Claude Code everything it needs to know about the project. When Claude Code starts a session, it reads this file automatically. What's in CLAUDE.md is the context AI works from. What's not in it, AI doesn't know.

Read through it. The file covers the client (who Yasmine is, what she does), what you're building (portfolio website, not a shop), the tech stack (static HTML/CSS, semantic elements, responsive breakpoints, Netlify), the color palette, the file structure, the verification targets, and the commit convention.

Then the tickets. T0 through T7, each with a clear scope and acceptance criteria. This is the work, broken into ordered pieces. Each ticket describes what to build and defines the specific conditions that make it done. "Acceptance criteria" means: if these things are true, the ticket is complete. If any of them isn't, the ticket isn't done yet.

Read through the ticket list:

• T0: Project Setup — Git repo, GitHub repo, backlog, issues, project board, web-optimized photos
• T1: Site Structure — HTML skeleton with semantic elements, shared navigation
• T2: Responsive CSS — mobile-first styles, color palette, Google Fonts, breakpoints
• T3: Portfolio Gallery — responsive image grid with figure/figcaption, descriptive alt text
• T4: Process Page — Yasmine's craft story with inline workshop images
• T5: Contact Form — Netlify Forms with three labeled fields
• T6: Final Verification — html-validate, Lighthouse, fix every finding
• T7: Deploy to Netlify — ship to a live URL

Eight tickets. That's the scope of the project. Each one moves the site forward, and together they take you from an empty folder to a deployed website.