Lesson 2.3 · 50 minDesign direction

What you will have

The student has docs/design.md, a small design system (colours, fonts, type scale, spacing, corner radius and usage rules), and a sample preview page, docs/design-previews/chosen.html, that uses only those values.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 3 — Demonstration: three directions as live previews

Purpose: Choose a visual direction for the site by comparing real pages, not
descriptions. Later sessions will build the whole site from the direction I pick.

Context: Read @docs/brief.md and @docs/content.md. Look at my references:
docs/references/ref-1.png (I like the large headings and the empty space),
docs/references/ref-2.png (I like the warm colours),
docs/references/ref-3.png (I like how simple the form looks).
Use them for direction only. Do not copy their logos, images, text or layout.

Done looks like: three standalone HTML files in docs/design-previews/ named
direction-a.html, direction-b.html, direction-c.html. Each shows the same
content: the hero, the benefits section, one FAQ item and the lead form, with
the real text from docs/content.md. The three must differ clearly in colour,
typeface and overall mood, not be three shades of one idea. Give each a
two-word name and tell me in one sentence who it would suit.

Constraints:
- At the top of each file, define every colour, font, font size, spacing step
  and corner radius once as a named CSS variable. Everything below uses only
  those variables.
- Fonts: propose only fonts you believe are published under a licence that
  allows commercial use on a website. For each, tell me the font name, the name
  of its licence and where I can read the licence myself. If you are not sure,
  say so. Tell me how each preview loads its fonts.
- No images from the internet. Where a photo would go, draw a plain block
  labelled "photo placeholder". For the logo, set the business name in text.
- Text must be readable: report the contrast ratio of body text and button
  text against their backgrounds for each direction.
- Keep [OWNER TO SUPPLY: ...] placeholders visible as they are.
- Each page must also look right at phone width.

I choose direction B. Two changes: use the heading font from direction A,
because B's headings feel too formal for a home service, and make the corners
less rounded. Save the result as docs/design-previews/chosen.html, built the
same way: all values as variables at the top. Report the contrast ratios again.

Part 4 — Demonstration: recording the tokens

Purpose: Record the chosen design so that any later session can build pages
that match it without seeing this conversation.

Context: docs/design-previews/chosen.html is the approved direction.

Done looks like: a file docs/design.md with these sections:
1. Direction: three sentences on the intended feel, and what was taken from
   each reference.
2. Colours: a table of token name, value, role, and where it is used; then
   the text/background pairs with their contrast ratios.
3. Typography: font families with the role of each; a licence record for each
   font (licence name, where it can be read, "checked by owner on: ___");
   the type scale as a table of name, size, weight and line height.
4. Spacing: the base step and the scale; section padding; maximum page width.
5. Corner radius, borders and shadows.
6. Usage rules: one primary button per screen area, how links look, form field
   states (normal, focus, error), what never to do.
7. Logo and imagery: what style of image fits; a table of every image the site
   needs with its source and licence, starting with placeholders.

Constraints: The values in docs/design.md must be exactly the variables in
chosen.html, with the same names. After writing the file, check chosen.html for
any colour, font size, spacing or radius value that is not one of the variables,
and list what you find, or state that there are none and how you checked.

Do along

Work on your own project. Pause the video where a step says so.

1. Pause after Part 1. Save a screenshot of each of your reference sites in docs/references/.
2. For each, write one sentence on what you like.
3. Pause when the main prompt appears in Part 3. Use it with your own sentences in the brackets. If you already have a brand colour or logo, add under Context: "Our brand colour is … and our logo file is at …; every direction must use them."
4. Open the three previews, wide and narrow.
5. Choose one, or combine, with the second prompt, giving reasons.
6. Pause after Part 4. Run the recording prompt to create docs/design.md, and do the two checks from Part 4.
7. Pause after the licence check in Part 5. Do it for each of your fonts and write the date in design.md; replace any font you cannot confirm.
8. Commit and push.

Check your work

1. docs/design.md has a Colours table. → Each colour has a name, a value and a role.
2. It has a Typography section. → Font families, a type scale, and a licence record with your check date for each font.
3. It has Spacing and radius sections. → A base step, a scale, radius values.
4. Open docs/design-previews/chosen.html in the editor. → All values are defined once at the top as named variables; three tokens picked from design.md appear there with the same names and values.
5. Ask Claude: "List any colour, size, spacing or radius value in chosen.html that is not one of the variables, and say how you checked." → None.
6. Open chosen.html in the browser, wide and narrow. → Readable in both; real copy; no images taken from elsewhere.

Common problems

• The three directions look almost the same. → The references are too similar or the request too weak. → Say: "Redo B and C so that each differs from A in colour family, typeface style and density."
• All previews show the same plain font. → The fonts did not load and the browser used a fallback. → Say: "The fonts in the previews are not loading. Find out why, fix it, and tell me how each font is loaded."
• Claude is vague about a font's licence. → It does not know. → Do not use that font; ask for an alternative and run the Part 5 check.
• Light grey text that is hard to read. → Contrast below the guideline. → Say: "Body text contrast must be at least 4.5 to 1. Adjust the text colour tokens and report the new ratios."
• design.md and chosen.html disagree. → One was edited after the other. → Say: "Make docs/design.md agree with chosen.html and list what you changed."

Homework

About 35 minutes, after the lesson. Nothing here is needed to start lesson 2.4. Do not change token names or values in these tasks.

1. Image inventory (~15 min). Go through docs/content.md section by section. For each landing-page section, add a row to the image table in section 7 of docs/design.md: what the image shows, where it will come from (one of the four sources from Part 5), its licence, and a date if you still have to take or commission it. Write "no image" for sections that need none. Commit without a tag. Done when: every landing-page section has a row or "no image", and no row lacks a source.
2. Read another site's tokens (~10 min). Open one of your reference sites. In your notes, write one line for each of the four groups from Part 2: how many colours you see and the role of each, how many fonts, whether spacing is tight or airy, how round the corners are. Add one sentence on how your chosen direction differs. Done when: four lines and one sentence are written.
3. Five-second test (~10 min). Show chosen.html on your screen to one person for five seconds, then hide it. Ask: what does this business do, and what would you click? Write down the answers next to your notes on the direction. Done when: both answers are written down, with a note on whether the button was the thing they named.

Save your work

git add -A
git commit -m "Lesson 2.3: design direction and tokens"
git push