Style Guide

Fixing the values feels like it should make screens come out consistent, and it doesn't. Cut the palette to four colors and lock type to five sizes, and people still use the same values in incompatible ways.

At Pagedeck the shape of the problem was this. Noa settled on a single accent color and gave the value a name, and two months later the document list screen had four accent-colored buttons on it: new, share, sort, and filter. Everyone who built those screens had decided their own feature mattered, and nobody had used a wrong value. From the user's side it became a screen with no answer to the question of what to press first. Four things shouting at equal volume is the same as nothing being emphasized, which is the outcome the single accent color was supposed to prevent.

What was missing wasn't the value. It was the usage. The guide said what the accent color is and never said when it applies. A style guide fills that blank. It separates deciding the values from deciding the situations they belong in, and writes the second half down as sentences someone can be held to.

Rules paired with the situations they apply to. Five groups.

1. Color — for each color in the color palette, the set of colors you agreed to use, when it comes out. The accent color appears once per screen, red is reserved for actions that can't be undone, gray text is only for secondary explanation.
2. Type — where each step defined in typography belongs. Up to three heading levels on one screen, body text at 16 pixels, lines broken between roughly 45 and 75 characters.
3. Spacing — which relationships each step of the spacing scale applies to. Write down that items inside one group sit 8 apart and separate groups sit 24 apart and nobody picks a number again.
4. Words and voice — button labels start with a verb, error messages state the cause and the next action, the product doesn't address the reader by a title. Wording decides more of a screen's character than color does, and it's the group most often left out because it doesn't look like design work.
5. Accessibility floors — the minimum bar for accessibility. Contrast between text and background at 4.5 to 1 or better, and state never communicated by color alone without a word or shape alongside it.

Each rule gets a right example and a wrong example side by side. A sentence on its own gets interpreted. Put a screen with four accent buttons next to a screen with one under the rule about using accent once, and the follow-up questions stop arriving.

What doesn't go here is worth stating too. The actual values live in design tokens, one component's properties and states belong in a component spec, and repeated situations like confirmation flows belong in a pattern library. Write the same thing in two places and the day comes when only one of them gets updated.

The writer is a designer. At Pagedeck, Noa owns color, type, and spacing, and settles the voice rules together with whoever writes the interface copy, since a rule about wording that no writer agreed to won't survive its first exception.

Four audiences open it, each for a different reason.

1. A newly joined designer, checking what's already decided before drawing anything. Without the document their first mockup uses their own conventions and the review rolls all of it back.
2. Engineers, who pull values from tokens but come here when a judgment is required — which of two buttons on this screen gets the accent.
3. The people in front of customers. Sofia and Ravi write proposals and sales material against the same rules. When the material and the product don't match, the customer has met two companies.
4. Outside vendors. When contracted screens come back, this document is what they get checked against. A vendor given only mockups reproduces the mockups; a vendor given the rules produces screens that fit the ones you didn't send.

How it gets maintained falls to design system governance: who decides when someone asks for an exception, and what conditions justify changing the rule itself instead. Leave a rule in place that reality has outgrown and people stop opening the document at all.

Length has a ceiling as well. At 80 pages nobody reads to the end. Rather than adding rules, push the ones that can be enforced into the components themselves and keep only the judgment calls in prose.

"This screen has four accent buttons. The guide says one per screen."

The values are right and the usage left the rules.

"Red is for actions that can't be undone. Resetting a sort isn't that."

The meaning attached to a color has to hold, or users can't read risk from color at all.

"Let's take the exception here. But write down the condition and revisit it at the next review."

Recording a decision to break a rule so it doesn't quietly become the new default.

Fixing the four-accent-button screen at Pagedeck added one line to the guide: on any screen, the accent color goes to the single action the user should take now. Noa attached a right example and a wrong example, and Theo pushed the rule down into the components. Two or more accent buttons on one screen now raise a warning during development, and the same review comment stopped appearing after that.

The most common position is that tokens make this document unnecessary. Colors and spacing are already decided, so there seems to be nothing left to settle. But tokens report what exists; they say nothing about when to use it. One accent color can still appear four times on one screen, and at that point the benefit of narrowing the palette is gone. Skip the usage rules and the consistency you bought at the value level scatters again at the screen level. Tokens make inconsistency harder to introduce by accident; only usage rules make it harder to introduce on purpose.

The other misreading is that longer is better. Writing down everything looks like it should reduce follow-up questions. But as length grows, readership falls, and a rule nobody reads is the same as no rule. In a team with an 80-page document, the part that actually holds is usually the first five pages. Twenty lines of rules, with everything else enforced by the components, is what gets followed. The test of a rule isn't whether it's correct but whether anyone will remember it during a busy week.