Key PayDesigner guide
A user manual for the books

You built Key Pay. These books keep it that way.

The three books carry the brand you made: the colors, the voice, the corridors, the card. They keep your work consistent as the team grows and as you design with AI tools. You will not need to read any of them cover to cover. This guide shows you what each book is, when to grab which one, and how to use them in your actual work.

The card you designed. Still the hero of every composition, including this one.
Sixty seconds

The three books

Each one has a different job. The file names appear here once, so you can recognise them in a folder; after this, the friendly names do the work.

The Design Book

DESIGN.md

How things look and behave in product: colors, type, spacing, components, the card, the image rules.

The Brand Book

BRAND.md

How Key Pay talks and feels: voice, the worst-day frame, the corridor personas, what Key Pay refuses to do.

The AI Brief

SKILL.md

A one-page intro you would hand any new collaborator: here is the project, here are the two reference books, here are the rules that matter most. Ask Penelope reads it once at the start of a chat and works to it for the rest. You upload it with the other books. You will not need to open it.

The visual catalog preview.html
Open it in a browser when you just need to look at a color, a type style, or a component. No book required.

The case, quietly

Why the books, and not just a long prompt

You could open Ask Penelope and type everything you know about Key Pay into the prompt. That works once.

The long prompt, every time

"Design a Key Pay screen. Warm sand background, purple primary, Raleway, card is the hero, balance is supporting, rate visible before the tap, never red for brand accents, no pure white surfaces, no em-dashes, none of the avoided words, status needs a label as well as a color, one primary action per screen, ...and the forty rules nobody can hold in their head while also designing."

The books, once per chat
  1. Upload the books at the start of the chat.
  2. Describe the screen you want in your own words.
  3. Cite a section when you want a specific pattern followed.
Same context every time, across every chat, across the whole team. Next week you write nothing again, slightly different.
The depth is already in the file: component variants, voice samples, the card spec, the image checks. Things you would never fit in a prompt anyway.
When a rule changes, the book updates once. The next chat uploads the new version. Everyone benefits.
You can cite the exact rule. "Per Design Book §10.13, this flow needs the permanent-action warning." The answer comes back formatted right.
The chat ends; the books remain. Tomorrow starts from the same baseline as today, instead of from scratch.
Disagreements get shorter. A citation settles in one message what re-explaining settles in five.

The books are the long prompt you would have written, lifted out so you do not have to write it again.

A decision aid

When to grab which book

Designing a wireframe?Design Book
Writing copy inside a wireframe?Brand Book
Working in Ask Penelope?+ AI Brief
Generating an image with AI?Design BookBrand Book+ AI Brief
Quick color or component lookup?Visual catalog
Reviewing AI output?Design Bookor Brand Book
Click by click

How to use the books in your tools

Figma

  1. Link the relevant book in the file, so anyone who opens it finds the source.
  2. Use section citations in frame titles where they help: "Cards (Design Book §10.20)".
  3. In comments, paste the citation instead of re-explaining the rule.
Comment · Order Card flow
Per the Design Book §10.13, this close-card modal needs the permanent-action warning, and the balance line: "Any remaining balance will be returned to your wallet."

Ask Penelope

  1. Start every Key Pay chat by uploading the books you need, plus the AI Brief.
  2. Describe the screen in your own words. The brand context is already loaded.
  3. Cite a section when you want a specific pattern, the way you would cite a page in a textbook.
Design Book Brand Book AI Brief
Per Design Book §11, design a card detail screen for a Premium tier card with two recent transactions visible.

Lark

  1. Share the book file directly when a teammate needs the canonical source.
  2. For one rule, send the citation in a message; the receiver reads the section, nothing gets re-uploaded.
  3. Change proposals travel here too; see Suggesting changes.
Design team · today
Per the Brand Book §5, we do not promise coverage that is not built. The "coming soon" line on this screen needs to go.

Browser

  1. Keep the visual catalog bookmarked, or drag the file into any browser tab.
  2. Open it to confirm a color, a type style, or a component at a glance.
  3. If the catalog and the Design Book ever disagree, the Design Book wins; flag the mismatch.
Raleway, every weightTitles 42 Medium · Body 20 Regular · Amounts in tabular numerals
Daily work

Recipes

Short, repeatable moves. The first set covers what you are doing right now; the second set is here so you know the same books cover the work that comes later.

Designing a wireframe for the Key Pay app
  1. Open the visual catalog in a tab, for colors and components at a glance.
  2. In Ask Penelope, upload the Design Book, the Brand Book, and the AI Brief.
  3. Describe the screen in your own words. Cite sections for specific patterns: the app structure lives in §7, the components in §10, the card in §11.
  4. Check the output against the two rules that matter most: the card is the hero, and every color and size is one of the named values.
  5. Anything off? Name the rule it breaks and ask for the fix. The citation does the arguing.
Design Book §7 · app structure Design Book §10 · components Design Book §11 · the card
Prompt pattern
I am designing a Key Pay wireframe. I have uploaded the three books; follow them.

Per Design Book §11, design a card detail screen for a Premium tier card with two recent transactions visible. The card is the hero; balance is supporting context.
Writing copy that sits inside a wireframe
  1. The Brand Book's voice section (§6) is the register; the specimens in §6.4 are the sound. Read three of them before you write.
  2. For destructive moments, the canonical openings live in the Design Book (§10.12 and §10.13): "This action is permanent..."
  3. Sweep your draft before it ships: no em-dashes, none of the thirteen avoided words, no "not X, it's Y" framing.
Brand Book §6.4 · voice specimens Design Book §10.13 · permanent actions
Prompt pattern
Per Brand Book §6 and the specimens in §6.4, write the empty-state line for the Cards tab. Factual and warm, no aspiration language, and run it against the voice rules before you show me.
Reviewing your own wireframe before sharing
  1. The Design Book's review checklist (§19) reads as a set of yes-or-no questions. Walk it before posting in Lark or pushing to Figma.
  2. Or hand the walk to Ask Penelope, with your wireframe attached.
  3. Fix what fails, re-check only what you changed, then share.
Prompt pattern
Walk the attached wireframe through the Design Book §19 review checklist. Answer each item yes or no, one line each, and list anything that needs fixing with the section that says so.

The same books cover this work when you get to it. These recipes get filled in then.

Campaign images with AI

The image rules live in Design Book §14: the constants every prompt carries (§14.1) and the twelve-question check you walk after generation (§14.7).

Social-post visuals

The same §14 contract applies. The Brand Book §6.5 carries the social copy register.

Landing-page sections

The marketing imagery lane is Design Book §13.1. The story arc is Brand Book §4; pick one corridor persona as the thread.

Press "/" anywhere

Quick Find

The search box in the top bar looks across the most-used rules in all three books. Type the way you would ask a teammate: "frozen card color", "closing a card wording", "can I use pure white". Each answer names its book and section, with the citation one click from your clipboard.

Try one of the common lookups:

If something is not findable, that is a gap in the index, and gaps are fixable: suggest the entry and it gets added.

The books are alive

Suggesting changes

When the brand evolves, the books evolve. When a rule needs sharpening, sharpen it. You made these decisions once; you are allowed to remake them.

1Write it

What you would change, why, and if you can, a worked example showing the before and the after.

2Send it

In Lark, or as a comment in the relevant Figma file. The change gets discussed in the open.

3It lands

The book updates once. The next Ask Penelope chat picks up the new version automatically.

Some rules pair across the two books. Color choices touch voice; voice choices touch component copy. If your change touches both the Design Book and the Brand Book, say so, and the pair gets updated together.

Short answers

Questions you might have

Why three files instead of one?
Different jobs. Easier to upload only the one you need for a given chat, and easier to update one without touching the others.
Do I have to read them all?
No. Treat them as reference books. Quick Find gets you to the right page; the books wait until you need them.
Why upload to Ask Penelope every time?
Each chat starts with no memory of previous chats. The books are how you give it memory.
Why the section numbers?
Like page numbers in a textbook. They let you, a teammate, or the AI cite the exact rule instead of paraphrasing it.
Can I break anything by getting it wrong?
No. The books are reference, the tools are forgiving, and the worst case is that an output needs a small fix.
Where do I find X?
Quick Find first. If it is not findable, file a change request and the index gets the entry.
A small doorway

For the technically curious

What is actually inside these files? Open if you want the longer answer.

What a .md file is

A plain-text file with light formatting marks. It opens in any text editor, reads cleanly as prose, and AI tools parse it natively. That double readability, human and machine, is the whole reason the books are written this way.

What "named colors and sizes" means

Every color, size, and spacing value in Key Pay has an agreed name, so everyone uses the same value: like Pantone numbers, but for code. The names and values live in design-tokens.json. If a value has no name, it does not ship; ask for it to be named, or use the nearest named value.

What the checker script does

validate.py is spell-check for the design system. It scans the books for typos, missing sections, and rule contradictions. The developer runs it; it occasionally matters to you when a change request is being reviewed.

What the AI Brief contains

The same instructions a senior designer would give a new collaborator on day one: read these two books, here are the rules that matter most, here is what to check before showing work.

The canonical files

DESIGN.md · BRAND.md · SKILL.md · design-tokens.json · preview.html · validate.py. The audit trail behind every decision (the receipts) lives in source-material-findings-register.md.