3.4 Layout and design system · AI Global Academy

Duration	~50 min in the lesson + ~25 min homework
Prerequisites	Checkpoint `lesson-3.3`; `docs/design.md` from 2.3.
Checkpoint	`lesson-3.4`

What you will have

Every page of the site sits inside the same frame: your colours and fonts, a header with navigation and a call-to-action button, and a footer. A hidden style-guide page at /styleguide shows every basic component and matches docs/design.md.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 2 — Tokens become the Tailwind theme

Prompt to Claude

Purpose: make the design tokens from docs/design.md the only colours, fonts,
sizes and radii the site can use.

Context: Tailwind CSS 4 with the theme in app/globals.css. The file still has
the scaffold's default variables, Geist fonts and a dark-mode block. Read the
Tailwind theme documentation for the installed version and the Next.js font
guide in node_modules/next/dist/docs before editing.

Done when:
- every colour, font family, type size, radius and any custom spacing value in
  docs/design.md exists as a theme variable in app/globals.css, with a name
  that follows the document's names (for example --color-brand);
- the scaffold's default colours and the dark-mode block are removed (the site
  has one light theme);
- the heading and body fonts from docs/design.md are loaded with next/font in
  app/layout.tsx and connected to the theme, replacing Geist;
- body text uses the body font, the text colour and the background colour from
  the document.

Constraints: no tailwind.config file. No colour or size values anywhere except
the theme block. If a token in the document is ambiguous or missing, stop and
ask me rather than inventing one. Before reporting, run the build and lint,
and give me a table: token name in design.md → theme variable → example class.

Part 3 — Container, header and footer

Prompt to Claude

Purpose: build the shared frame every page sits in.

Context: tokens are in app/globals.css. The sitemap and navigation labels are
in docs/content.md; business name and contact details are in docs/brief.md.
Routes for this site: / (landing), /privacy, /terms. Landing sections will get
ids later (benefits, how-it-works, faq, quote).

Done when:
- components/ contains Container, Header and Footer;
- app/layout.tsx renders Header, then the page inside a main element, then
  Footer, so they appear on every page;
- Header: business name linking to /, navigation links to the landing
  sections, and one CTA button labelled as in docs/content.md linking to
  /#quote. It stays usable when the window is narrow (full mobile menu comes
  in lesson 3.6; for now the links may simply hide on small screens while the
  CTA stays visible);
- Footer: business name, contact details, links to /privacy and /terms, and
  the current year;
- the business name, contact details and navigation labels live in one file,
  content/site.ts, and the components read them from there.

Constraints: only theme tokens, no hard-coded colours or sizes. Semantic HTML:
header, nav, main, footer. No new libraries. Links to pages that do not exist
yet are fine. Before reporting: run build and lint, open the home page in the
browser at desktop width and at 375px wide, take a screenshot of each, and
tell me what you see.

Part 4 — Basic components and the style guide

Prompt to Claude

Purpose: create the reusable basics and one page where I can review them all.

Context: tokens in app/globals.css; usage rules in docs/design.md; Container,
Header, Footer exist.

Done when:
- components/ contains Button (variants: primary, secondary; works as a link
  or as a button; has visible hover and keyboard-focus styles), Section
  (consistent vertical spacing, optional background variant, Container
  inside) and Heading (levels matching the type scale in docs/design.md);
- Header's CTA uses Button;
- a page at /styleguide shows: every colour token as a labelled swatch with
  its name and value; the type scale with each heading level and body text;
  the spacing and radius tokens; every Button variant in normal and disabled
  state; a Section in each background variant;
- /styleguide is not linked from anywhere and its metadata tells search
  engines not to index it;
- CLAUDE.md has a short "Frontend conventions" section: tokens live in the
  @theme block in app/globals.css and mirror docs/design.md; no hard-coded
  colours or sizes; components in components/; site text in content/; new
  basic components are added to /styleguide.

Constraints: only theme tokens. Keep component options minimal; add nothing
docs/design.md does not call for. Before reporting: build and lint, open
/styleguide, take a full-page screenshot, compare it line by line with
docs/design.md and list every difference you find, even small ones.

Do along

Work on your own project and pause the video where told.

Start from lesson-3.3 with the dev server running.
Pause after Part 2. Run the tokens prompt from Part 2. Review Claude's table against your own docs/design.md.
Pause after Part 3. Run the layout prompt from Part 3. Replace the section ids and CTA label only if your docs/content.md uses different ones.
Pause after Part 4. Run the components prompt from Part 4.
Open /styleguide next to docs/design.md and compare every token. Inspect at least one colour, one font size and one radius in developer tools.
Fix differences by briefing Claude with the exact element and values. Update docs/design.md first if the document is what should change.
Read the new "Frontend conventions" section in CLAUDE.md.
Save the checkpoint with the commands under "Recap and next". Wait for the deployment, then open your live domain and /styleguide on it.

Check your work

Open /, /styleguide and a made-up address such as /abc. Expected: the header and footer appear on all three.
On /styleguide, compare each swatch, font and size with docs/design.md. Expected: names and values match exactly.
Open app/globals.css. Expected: one @theme block containing your tokens; no dark-mode block; no tailwind.config file in the project.
Ask Claude: "Search components/ and app/ for hard-coded colour values and report any." Expected: none outside globals.css.
npm run build and npm run lint. Expected: both pass.

Common problems

Claude created tailwind.config.js → it followed the older Tailwind approach → "This project uses Tailwind 4; delete the config file and move those values into the @theme block in app/globals.css. Re-read the Tailwind theme documentation first."
A class such as bg-brand has no effect → the variable name does not follow the pattern (for example --brand instead of --color-brand) → ask Claude to check the variable names against the Tailwind theme namespaces.
The font did not change → the font is loaded but not connected to the theme, or body still names the old font → "The body still renders in the fallback font; trace it from layout.tsx to globals.css and fix it. Confirm with the computed font-family in the browser."
The page turns dark on your computer → the scaffold's dark-mode block is still there and your system is in dark mode → ask Claude to remove it.

Homework

About 25 minutes, after the lesson. No later lesson depends on it.

Read the frame as a customer. On the live site, read the header and footer word by word: business name, contact details, navigation labels, CTA label. Brief Claude to correct anything wrong in content/site.ts. Change values only; keep the routes and section ids. Deliverable: a list of what you corrected, and a commit without a tag if anything changed. Done when: every fact shown is one you would print on a business card.
Compare with a reference. Put /styleguide beside one reference site from lesson 2.3 and write three differences. Decide for each: keep or change. For a change, update the value in docs/design.md first, then have Claude fix the token, not the component. Do not rename tokens. Deliverable: three decisions in your notes. Commit without a tag. Done when: step 2 of "Check your work" still passes.
Outside opinion. Show the live home page and /styleguide to one person who knows the business and ask: "Does this look like us?" Deliverable: their answer in two lines in your notes. Done when: you have written what, if anything, you will change because of it.

Save your work

git add -A
git commit -m "Lesson 3.4: theme tokens, layout, basic components, style guide"
git tag lesson-3.4
git push
git push --tags