Building your first page

I would build and review the home page before creating the rest of the site. It gives you one working reference for navigation, spacing, type, and responsive behavior. The written requirements guide Claude, but the browser shows which decisions actually work.

Ask for Design Options First

Ask for several design options before choosing one, as the first result may lock you into a direction you have not compared.

Build me 3 design directions for the home page with the same content.
Make the layout, typography, and color choices clearly different.
Save them as home-v1.html, home-v2.html, home-v3.html.

Open all three in the browser and pick the one closest to your goal. If they look alike, ask Claude to explain what changed before generating another set.

Pick the option closest to your goal and use it as the starting point. It does not need to be final.

I like v2 the best. Let's use that as our starting point.
Rename it to index.html and move the other versions to _docs/archive/.

Review Your Selected Design

Open the selected index.html in a browser before changing it. Check the navigation, main heading, planned content, and overall structure against your requirements. Add anything missing in the next step. At this point you only need a usable reference, not a finished page.

The Iteration Loop

I use a short review loop:

1. Look at what Claude built: Open the file in your browser
2. Identify one thing to change: Not everything. One thing.
3. Tell Claude what's wrong: "The hero text is too small" not "fix the design"
4. Repeat

Be specific. Compare:

❌ "Make it better"
✅ "Make the hero heading larger, at least 48px"

❌ "I don't like the colors"
✅ "Change the background to dark blue (#0a1628) and the accent color to a warm orange (#ff6b35)"

❌ "Fix the layout"
✅ "Center the navigation links horizontally and add more space between them"

Change one visible problem at a time until the page is good enough to reuse. The number of rounds depends on the first result and how specific your feedback is.

Common First-Page Fixes

On a first page, I check spacing, text size, mobile layout, and contrast.

Spacing is usually the first thing that feels off:

Add more padding around the hero section. It feels cramped.
The footer needs more space above it.

For text that's too small or too light:

The body text is too small. Use 18px minimum.
Make headings bolder - use font-weight 700.

Always check a phone-sized screen:

Check the site on a phone-sized screen. The navigation is broken.
Make sure text doesn't overflow on narrow screens.

If the colors aren't quite working:

The contrast between text and background is too low.
Make the links more visible - they blend in too much.

Lock In Your Design Standards

Once the home page works, record its design decisions before building another page. Otherwise Claude may choose different spacing, navigation, or type on the next result.

Tell Claude to capture everything from your home page into a rules file:

Create .claude/rules/css.md from the decisions already present in
index.html and css/styles.css. Record the actual colors, type sizes,
spacing, header, footer, and responsive behavior. Do not invent values.
Treat the working home page as the reference for later pages.

Review the generated file before using it. A short rule can be enough:

# Design System Rules

- Use the header and footer from index.html as the reference.
- Keep shared styles in css/styles.css.
- Record only colors, sizes, spacing, and breakpoints found in the files.
- Compare each new page with index.html and correct visible drift.

Treat this file as the shared reference for later pages. Claude Code loads project rules as context, not as enforced configuration, so compare every new page with the working home page and correct any drift you see.

Why This Matters

Without a shared reference, one page may have five navigation links while the next adds a sixth or changes the header. After four pages, you can end up maintaining four versions of the same component.

The rules file gives Claude a reference for the shared parts. It does not remove the need to compare the rendered pages.

Extract Inline Styles (If Needed)

Claude may create the first options with CSS inside the HTML. If the chosen design will become the reference, move those styles into css/styles.css so later pages can reuse them.

If Claude does not propose that change, tell it:

Extract all the inline CSS from index.html into css/styles.css.
The HTML should only have class names, no style attributes or <style> tags.

Review the change, as the HTML should keep class names while the shared visual rules stay in one stylesheet.

Test Before Moving On

Before building more pages, verify your home page works. Ask Claude to do a full check:

Review index.html and css/styles.css for:
1. Responsive design - test at mobile (375px), tablet (768px), and desktop (1200px+)
2. HTML validation - any errors or missing elements
3. Accessibility - proper heading hierarchy, alt text, color contrast
4. Navigation - all links present and styled correctly

Fix any issues you find.

Ask Claude to inspect the HTML and CSS for likely problems, then test the page yourself at narrow, medium, and wide widths. If Claude Code has a browser integration configured, it can also open the page and exercise those viewports. Source review alone cannot confirm the rendered result.

What You Have Now

After these steps, the project may look like this:

my-portfolio/
  CLAUDE.md
  index.html
  css/
    styles.css
  .claude/
    rules/
      css.md
  _docs/
    plan.md
    requirements.md
    archive/
      home-v1.html
      home-v3.html

Open the home page at 375px, 768px, and desktop width. Once the content, navigation, and spacing hold up, use it as the reference for the next page.