Writing Your First Web Page with Claude Code

Building your first web page is the right first project. It is immediately visible — you can open it in a browser and see results. It uses three beginner-friendly technologies (HTML, CSS, JavaScript). And it gives you a foundation for every web project that follows.

This lesson walks the full cycle: project setup, first build, iteration, and preview. No prior web development experience required.

Set Up Your Project Folder

Every project starts with a dedicated folder. Keep things clean.

mkdir my-web-page
cd my-web-page
claude

You are now inside your project folder with a Claude session active. Everything Claude creates will appear in this folder.

Your First Prompt: Build the Page

Be specific about what you want. Here is a good starting prompt for a beginner landing page:

Build a landing page for a fictional coffee shop called "The Dark Roast."
Include:
- A navigation bar with links: Home, Menu, About, Contact
- A hero section with a large headline and a call-to-action button
- A "Why Choose Us" section with three feature cards
- A footer with copyright text
Use modern CSS: dark background (#1a1a2e), white text, gold accent (#f4a261).
No JavaScript yet — just HTML and CSS.

Claude will plan the file structure and begin creating files. Claude uses its Write tool to create new files — you'll see this labeled in the tool call output. You will see tool calls like:

● Running tool: Write(index.html)
● Running tool: Write(style.css)

When it finishes, you will have two files in your folder: index.html and style.css.

Preview in Your Browser

Opening the result is immediate — no server needed for a static HTML file.

macOS:

open index.html

Windows:

start index.html

Linux:

xdg-open index.html

Or drag the index.html file from your file manager into any browser window. The page loads locally via the file:// protocol.

What you see is Claude's first pass. It may not be perfect. That is expected. The iteration cycle is where the real work happens.

Iterating on the Design

Iteration is the core skill of working with Claude. You describe what is not right, Claude fixes it. Repeat until you are satisfied.

Here are real iteration prompts with what they accomplish:

Typography refinement:

The font is too small throughout. Increase the base font size to 18px, make the hero headline 56px, and use a Google Font — import "Space Grotesk" and use it everywhere.

Layout fix:

The three feature cards in the "Why Choose Us" section are stacking vertically. Make them display in a horizontal row on desktop using CSS Grid with three equal columns. They should stack on mobile (screen width below 768px).

Interaction addition:

Add a hamburger menu for mobile. When the screen is below 768px, the nav links should be hidden. Clicking the hamburger icon (☰) toggles them visible. Use JavaScript for the toggle. Keep it in a separate script.js file.

Color refinement:

The hero button is the same color as the background. Change the button to gold (#f4a261) with dark text (#1a1a2e), add a subtle hover effect that lightens the gold slightly.

Notice the pattern: each prompt is specific about what is wrong, where it is, and what it should be instead. Claude does not need to guess at your intent.

When Claude Asks a Clarifying Question

Sometimes Claude will ask rather than assume. Example:

Should I use Flexbox or CSS Grid for the feature cards layout?

This is Claude being responsible. It wants to use the approach that fits your preference or skill level. Answer directly:

Use CSS Grid.

Then Claude continues without further interruption. Clarifying questions from Claude mean it detected an ambiguity that would have led to a wrong assumption. Answer them rather than pushing Claude to just pick one.

Building the JavaScript Layer

Once your HTML and CSS look good, add interactivity:

Add a contact form at the bottom of the page with fields for:
- Name (text input, required)
- Email (email input, required)
- Message (textarea, required)
- Submit button

When submitted, show an alert that says "Thanks for your message! We'll be in touch." and clear the form.
Keep the JavaScript in script.js.

Claude will create or edit script.js and link it in index.html. Refresh the browser and test the form.

This three-layer pattern — HTML structure, CSS presentation, JavaScript behavior — is the foundation of all web development. You have now touched all three with Claude's guidance.

Reviewing What Claude Built

After Claude finishes a significant change, take time to read the code it generated. You do not need to understand every line immediately. Look for:

1. The overall structure — does the HTML have the sections you asked for?
2. The CSS patterns — what selectors is it using? Are class names descriptive?
3. Comments — Claude often adds inline comments explaining non-obvious choices

Ask Claude to explain anything you do not understand:

Explain what this CSS does: display: flex; justify-content: space-between; align-items: center;

Claude gives a clear explanation. Every question like this is a lesson you do not have to find in a tutorial.

Saving Your Work with Git

Once your page looks the way you want, save the state with git:

git init
git add .
git commit -m "Initial coffee shop landing page"

Ask Claude to do this if you prefer:

Initialize a git repository, add all files, and commit with the message "Initial coffee shop landing page."

Claude runs the commands and confirms. Your work is now versioned.

Common First-Project Mistakes

Prompt too broad: "Build me a website" produces a generic result. Specificity produces quality. Describe the exact sections, colors, content, and style you want.

Not iterating: The first result is a starting point, not a finished product. Use at least 3-5 iteration prompts before calling it done.

Not previewing between changes: If you let Claude make five changes before checking the browser, debugging is harder. Preview after each significant change.

Asking Claude to guess preferences: If you have a color preference, say it. "Use a dark background with blue accents" beats "use something that looks professional."

Lesson 43 Drill

Build a web page for something you actually care about. Options:

• Your personal portfolio (name, skills, projects)
• A landing page for a hobby (music, games, fitness)
• A simple tool page (a timer, a calculator, a random quote generator)

Spend 30 minutes on it. Target at least 5 iteration prompts after the initial build. By the end, you should have a page you could show someone with reasonable pride.

Bottom Line

Building a web page with Claude Code follows a four-step cycle: set up a project folder, prompt Claude to build the initial structure, preview in your browser, and iterate with specific refinement prompts. No prior web development knowledge is required to produce a professional-looking result. The skill you are building is not HTML — it is knowing how to describe what you want precisely enough that Claude can build it correctly.

Lesson 44 covers the concept that makes all of this work: how Claude understands the context of your project.