Brand your reading list.

By the end of this part you’ll open a page in your own project that shows your colours, your typefaces, your mascot and the sentences your app will say, all in one place. Behind it will be two files that record those decisions, and your agent will build every screen from them.

You have a plan that says what is on each screen. Here you decide how those screens look and sound, in four stages with a prompt each.

1. Start from something you like

Find one interface you like the look of. It can be a page template, or an app or website you enjoy using. Starting here is quicker than asking an agent to invent a look, because people recognise what they like long before they can describe it. You may combine two, such as the layout of one with the typefaces and spacing of another, as long as you know which part comes from where.

Then say what you like about your reference, in your own words. “It feels calm” is a real answer. Your agent’s job in this stage is to turn your answer into visible choices you can recognise: the roominess, the big confident headings, how little colour there is, the soft corners, the plain buttons. For typefaces, describe the feel you want, such as rounded, elegant or sturdy, and let your agent suggest one. It will start with typefaces already on people’s computers. If none of those gives the feel you’re after, it can use a free one from Google Fonts, which your page then fetches from Google each time it opens.

There is a line between borrowing and copying, and your project’s instructions tell your agent not to cross it. You are borrowing an approach: how much space is used, how large the headings are, how restrained the colour is. You are never borrowing an identity: someone’s logo, artwork, photography, name or exact look belongs to them. Your colours are your own. Say which you want, or ask for a few suggestions and pick.

The prompt asks your agent to agree a description with you and to write no files yet. Replace each part in square brackets with your own answer, and delete the bracketed sentence about combining two if you have one reference:

Work on epic 03, stage A only, then stop.

I want to decide how this app looks before we build it, and I want to start from something I already like rather than from nothing.

Here is my reference: [a link to a template or a product, or a description of one]. What I like about it is [what you like: the roominess, the big headings, how little colour it uses, the soft corners, the plain buttons]. [If you are combining two: I want the layout from the first one and the typefaces and spacing from the second.]

Tell me which visible choices are actually producing that, so I know what I am asking for. Then ask me anything you need to know about the colours.

I want to borrow the approach, not the identity. Do not copy anyone's logo, artwork, name or exact look. The colours will be mine: [the colours you want, or "suggest a few and I will pick"].

Don't write any files yet. Just agree the description with me.

Read what comes back and push on anything vague. If it says “clean and modern”, ask which visible choices make it so. You’re finished with this stage when you could describe your app’s look to another person in four or five sentences.

2. Write the decision down

At the moment your look exists only in this conversation, and a later conversation won’t see it. An agent with nothing written to go on has to invent a colour, a corner and a size each time it adds a button, and it invents slightly different ones each time. That is how an app ends up restyled twenty times with no look of its own. So this stage writes your decision into two files.

The first is a brand pack, at docs/brand/brand-pack.md. It is a document written for you: the app’s name, the colours and what each is for, the typefaces and sizes, the spacing, how the app speaks, the real sentences it will show and a description of the mascot. You should be able to read it and disagree with it.

The second holds the same values in the form the app is built from, at src/tokens.css. Each value gets a name that says what it is for, such as --accent for your main colour, and that named value is called a design token. Every screen refers to the name, so changing the value in that one file changes it everywhere. You won’t need to open this file.

When the brand pack arrives, you’ll judge three things in it.

Every colour has a job. Five swatches tell an agent nothing about where to put them. “The page behind everything, the surface a card sits on, body text, quieter supporting text, and one accent for the action worth taking” can be applied without guessing.

Text is readable, with a number to prove it. The difference in brightness between two colours is measured as a contrast ratio, from 1:1 for identical colours to 21:1 for black on white. You need two figures to judge it: ordinary text should reach 4.5:1 against whatever is behind it, and large headings 3:1. The prompt asks your agent to calculate each ratio and show it to you, because a bare “yes, that’s readable” tells you nothing. If a colour you wanted falls short, you should be told its number and offered the nearest colour that passes.

The wording sounds like you. What the app says when the list is empty, or when you leave the title blank, gives it more character than any colour. Our reference app’s empty list says “Every library starts with one book.” The prompt lists every sentence the app will need, so that none is made up on the spot later. Some are for moments you haven’t met yet, such as the list loading or a change that couldn’t be saved; Part 5 explains those. For now, every app sometimes has to say “I’m still working” and “that didn’t work, please try again”, and those are the moments when its tone matters most.

Send this in the same conversation as Stage A, because it writes down what that conversation agreed:

Work on epic 03, stage B only, then stop.

Write what we agreed into docs/brand/brand-pack.md, so we never have to have this conversation again. Put in it: the app name; the colours with their values and what each one is for, with the contrast numbers; the fonts and every size we will use; the spacing scale; the corner radii; the shadows; how the app speaks, with examples of what to do and what not to do; and the real wording the app will use, which is the empty state, the "nothing matched" message, the message when I leave the title blank, the message while the list is loading, the label the form's button shows while it is waiting, the message and the retry button for when the server fails or does not answer, the message for when a change gets no answer in time, the message when this browser refuses to save the list, the note for when the saved list cannot be read, the note for when the list is only kept until I refresh, the note for when the stand-in server has to run inside the page, the note for when a teaching switch is on, the label for loading example books, the filter labels, the remove and undo wording, and every button label. Then a description of the mascot.

Put the same values in src/tokens.css as CSS custom properties, and import that file first in src/styles.css. From now on, every colour, size, space, corner and shadow in this app comes from those tokens, and every message comes from the brand pack. When you build the app, keep its sentences together in one place in the code that the components read, so a sentence is changed once, the way src/tokens.css does it for values.

Work the contrast out properly and put the real numbers in. If a colour I asked for fails, tell me the number and suggest the nearest one that passes. Don't quietly use something else, and don't tell me it's fine without measuring it.

Then stop and let me read the brand pack.

Open docs/brand/brand-pack.md when it appears, and read the wording aloud. This is the one section where you are the only expert: nobody else knows whether those sentences sound like you. Have anything changed that doesn’t.

If the pack has no contrast numbers, say: “Calculate the contrast ratio of every text colour against its background and put the numbers in the brand pack.” If your agent quietly changed a colour you asked for, ask which colour it replaced, and what the original measured.

3. Have your agent draw the mascot

Start this stage in a new conversation, and don’t tell it your colours or describe your mascot. Everything it needs is in the two files you’ve just agreed.

Your agent draws the mascot itself, as an SVG: a drawing described in text, which lists shapes, their positions and their colours, and which your browser then draws. Writing text is what a coding agent does, which is why it can draw one. Because the colours come from your tokens, the mascot follows your palette if you ever change it. An image tool is the other way to get a mascot, and you may prefer one, but a generated picture can’t follow a change of palette.

The prompt asks for two or three moods the app can use later, such as waving, reading and celebrating, and for a short label saying what the mascot is doing, so that someone using a screen reader is told a character is there. It also asks for a temporary page where you can see every mood, and it keeps the mascot out of the app itself for now.

Work on epic 03, stage C only, then stop.

Draw the mascot from the brand pack yourself, as an SVG component in src/Mascot.jsx. Take every colour in it from src/tokens.css, so it follows the palette if we change it. Give it two or three moods the app can use later, and an aria-label that says what it is doing.

Keep it simple enough to read at a small size. Don't wire it into the app yet. Show me all of its moods on a temporary preview page and give me the address, and I'll tell you what to change. Delete that page once I'm happy with the mascot.

Open the address your agent gives you. You should see your mascot in each of its moods. Look at its colours: they are yours, and this conversation was never told them. It read them from your brand pack and your tokens, which is what it means for a decision to live in the project and not in a conversation.

Then say what to change, as many times as it takes. The drawing is text, so another version costs you nothing:

Make it [rounder / friendlier / less tall / happier / smaller-eyed].

Keep the mascot simple. A character built from a few shapes reads better at the small size it will appear in the app than a detailed one does. When you’re happy, tell your agent so, and it deletes the preview page. The mascot is placed in the app when you build, in Part 6.

If the mascot arrives in colours that aren’t yours, say: “Take every colour in the mascot from src/tokens.css.” If the agent asks what your colours are, point it at docs/brand/brand-pack.md.

4. Open your style-guide page

The last stage puts everything you’ve decided on one screen. Your agent builds a style-guide page: a second page in your project, at style-guide.html, showing your colours with their jobs, the type sizes, the spacing, the corners, the shadows, the buttons, a form field, a book card, the empty list, an error message, the mascot and samples of the wording.

Two instructions in the prompt are worth knowing about. The page must read its values from src/tokens.css as it loads, and not have them typed into it, so that it can never show an out-of-date colour. And nothing in your reading list links to it, so it can’t get in the app’s way; you reach it by its own address. Carry on in the conversation that drew the mascot.

Work on epic 03, stage D only, then stop.

Build me a small style-guide page inside the project, at style-guide.html, showing everything from the brand pack in one place: the colours with their values and what each is for, the type sizes, the spacing steps, the corners, the shadows, the buttons, a form field, one book card, the empty state, a validation message, the mascot and the wording samples.

Read the values out of src/tokens.css when the page loads instead of typing them into the page, so the guide can't drift from the app. If you find yourself typing a colour or a pixel value into that page, it belongs in the tokens instead.

Keep the style-guide page separate from the app so it cannot break the reading list, but have it share src/styles.css with the app for the styles of its buttons, fields and cards, so that later the app's screens can be compared with this page and match. Nothing in the app should link to it. Give me the address to open it, and check it on a phone width too.

Open the address your agent gives you.

Your app’s first screen, which took on your background colour and type at Stage B, may have changed a little more. It shares its stylesheet with the style guide, so it can pick up the styles written for the guide’s headings and buttons. That is expected.

Narrow your browser window to check the page at the width of a phone. Then read down the colours and ask whether each still has a job you can name. A colour with no job is one your agent will misuse later, and removing it now is free.

If the page doesn’t open, the app has probably stopped running. Say: “Start the app and give me the address of the style-guide page.”

When you change your mind later

Expect to. A palette that looked right as a row of swatches can feel too heavy once twenty book cards are on the page. When that happens, ask your agent to change the value in the brand pack and the tokens, and not on the one screen you happen to be looking at. The value changes once, and every screen follows, the style-guide page included.

You now have a look of your own, written down where every later conversation will find it. Next, in Part 5, you’ll see how your reading list works before you build it.

FAQ

Further reading

• Design Systems 101Nielsen Norman Group

  What a design system and a style guide are, and why larger teams write their decisions down. No code, and it explains the reasoning behind what you have just done by hand.

• Contrast and Color AccessibilityWebAIM

  A careful explanation of contrast ratios, the 4.5:1 and 3:1 thresholds and what the exceptions are. A few short colour values appear, always with an explanation beside them.