Styleguide

Overview

Rules

34: 24 have an automatic check, 6 have one for part of the rule (R-4, R-6, R-7, R-13, R-23 and R-29), 4 are checked by review only (R-9, R-16, R-21 and R-26)

Do and don’t

18 pairs; the Storybook draws each in both modes

Parts

34 parts, 8 marked Trial; Link has no part of its own: it is a base rule

Colour

5 colour sets in 2 modes; media and TV stay dark in both

Contrast

364 pairs measured, each at or above the floor for its use (Lc 30 to 75)

Type

3 faces, 8 rungs on the canvas, body 17px

Storybook

Every part in every state

Counted from the canon and the contrast measurements when this page was built.

Rules

Numbered as the canon numbers them; a number is never reused. Where this page and the canon disagree, the canon wins.

Signature and headlines

1. R-1 The redaction bar is drawn over closed in “The eye is closed.” and nowhere else: not in an H1, a Plate, an entry page, an empty state, a mock or a specimen. The bar stays a signature because it sits on one word in one sentence and nowhere else. pair 1 · ruled 22 October 2026
2. R-2 Every H1 on every surface is one ink at the context’s display weight: no accent word, no <em>, no second colour, no bar. A headline in one ink is read in one pass; an accent word pulls the eye to itself before the sentence. pair 2 · ruled 22 October 2026
3. R-3 No kicker, eyebrow, pill, badge or numbered label above a heading; a source or date is a meta line after it. The reader comes for the heading, and a label above it is read first while saying less. pair 3 · ruled 22 October 2026
4. R-4 One primary fill per page at natural width; a selected tab, row or nav item is text plus a rule, a selected segment is the raised surface tone on a 1px control edge, and no selected state is amber. A fill on a selected item would blur which control is the one to press next. partly by review, pair 10 · changed 25 October 2026

Containers and layout

1. R-5 No card: a bordered or filled block is only Notice, Field, Sheet, Dialog, Confirm or Plate, and none sits inside another; the one other filled block is the television drawn on /tour's beat 05. Every edge is something to look past, so the few boxes that remain each mean one thing. pairs 7 and 8 · changed 29 October 2026
2. R-6 No grid of like boxes: never three or more equal containers in a row each with a glyph, a title and a sentence. A row of like boxes asks the reader to compare shapes before reading what is in them. partly by review, pair 7 · changed 25 October 2026
3. R-7 No stat tile and no hero number: a number sits inline at body size with its server time, or in a Plate with a source, and a round invented figure never ships. If a number is set large and alone, it looks like a boast with no time or source behind it. partly by review, pair 4 · ruled 22 October 2026
4. R-8 Flat on the ground: no shadow, glass, gradient, glow, halo, background pattern, side stripe or hover lift; radius 0 but the bar, the pill and the capsule. A shadow or a glow adds depth to a flat page and draws attention away from the words. pair 9 · ruled 22 October 2026
5. R-9 Content before controls: at 320 a row’s label shows twelve characters before its controls, or the controls move to the row’s detail. On a small screen the reader needs to know what a row is before what it does. by review only · ruled 22 October 2026
6. R-10 No carousel, marquee, auto-scroll, strip of customer quotes or wall of logos. Content that moves by itself or waits behind a swipe can be missed, and a strip of quotes or a wall of logos asks to be taken on trust. pair 15 · ruled 22 October 2026

Colour

1. R-11 No green for a live, ready, ok or up-to-date state anywhere: StatusChip, Plate and Notice lose their live and ok tones, the green role leaves the colour set, and the status palette is warn, alert and neutral. Colour is kept for what needs the reader, so a colour on a working state is noise they learn to skip. pair 5 · ruled 22 October 2026
2. R-12 No indicator of any colour for a thing that works: a working thing is silent, and a state shows only beside the Button or Link that acts on it. When a working thing says nothing, the reader looks only where there is something to do. pairs 5 and 6 · ruled 22 October 2026
3. R-13 Colour never travels alone, no percentage or bar is coloured unless an operation is running, and every colour is a semantic token. Some readers cannot tell colours apart, so a colour always comes with a word and marks only what is happening now. partly by review · ruled 22 October 2026
4. R-14 Body text is --ink-primary or --ink-secondary (Lc ≥ 75); --ink-tertiary carries labels and meta only; --ink-decorative is never text; grey never sits on a coloured ground. Body text uses the two strongest inks because they carry enough contrast for a long read. pair 11 · ruled 22 October 2026

Type and readability

1. R-15 Body is 17px, and nothing a user must read sits under 12px on desktop, 14px on touch or 24px on TV, scaled mocks and tour stages included; a device depiction on /tour is a picture and is held by its scale floor instead. Text under these sizes is hard to read, and the TV size is the largest because a TV is read from across the room. pair 11 · changed 29 October 2026
2. R-16 Prose runs at --measure and no line passes 75 characters; a hero sub-line is prose. Past about 75 characters the eye loses its place on the way back to the start of the next line. by review only, pair 11 · ruled 22 October 2026
3. R-17 Sentence case everywhere: no text-transform: uppercase, no all-caps string, and label tracking 0 (the TV label keeps 0.04em). Sentence case reads as words; capitals spaced wide are read letter by letter. pair 12 · changed 25 October 2026
4. R-18 Mono is for what you copy (codes, keys, references, times) and the Plate label; never nav, row values, footers, headings or prose. Mono marks what the reader copies, and anywhere else it makes plain words look like codes. pair 13 · ruled 22 October 2026
5. R-19 No italic, no bold display, no outlined or gradient text; emphasis in body is upright 600. Italic, outlined and gradient text is harder to read than upright text at a steady weight. pair 2 · ruled 22 October 2026
6. R-20 Three faces, each in its role, and nothing else: the platform face for running text, Atkinson Hyperlegible Next for headlines and the sign-off, Atkinson Hyperlegible Mono for codes and labels. Each face has one job, and the mono is drawn so that 0 and O, or 1 and l, can be told apart. changed 25 October 2026
7. R-21 One heading per section and it says the thing: no intro that restates it, no greeting, no formula (“The [X] for [Y]”, “Meet [name]”, “[Verb] your [noun]”, a question outside the ruled FAQ). Headings that say the thing let a reader skim a page by its headings alone. by review only · ruled 22 October 2026

Iconography

1. R-22 No emoji anywhere and no text glyph as an icon. Emoji and text glyphs are drawn by each device’s own font and look different from one device to the next. pair 14 · ruled 22 October 2026
2. R-23 Icons come only from the design system’s own glyph set, 16 or 20px in currentColor, in a row’s leading slot or an IconButton; never tinted, decorative, in a circle or tile, or above a heading. Icons from one drawn set at two sizes match each other, and an icon that only decorates adds nothing. partly by review, pair 14 · changed 25 October 2026
3. R-24 No stock, generated, 3D or isometric illustration; the pictures are the giraffe, the player’s own interface and footage, and on this page the Storybook’s Do and Don’t pairs. A stock or generated picture shows something that is not the product. changed 29 October 2026

Status and reassurance

1. R-25 The custody sentence appears once per surface in its ruled words; no stacked reassurance, no trust badge, no lock or shield glyph beside a form. A statement made once in its exact words is held to those words, and stacked reassurance around a form makes the reader wonder what is wrong. ruled 22 October 2026
2. R-26 One Notice visible per screen; the rest collapse to a count row. One notice gets read, and several at once get dismissed together. by review only · ruled 22 October 2026

Motion

1. R-27 One curve, three durations, the bar draw as the only signature: nothing pulses, blinks, bounces, floats, shimmers or loops, and nothing moves on scroll. Motion that repeats or follows the scroll competes with reading, and can make some readers unwell. pair 15 · ruled 22 October 2026

Copy, public and in-product

1. R-28 No em-dash and no en-dash pause in any UI string; a sentence ends, or a middle dot joins at most two short segments. A sentence that ends is easier to follow than two halves held together by a dash. pair 17 · ruled 22 October 2026
2. R-29 No forced contrast, no default triplet, no trailing participle clause. These patterns pad a sentence that a plain statement would say in fewer words. partly by review, pair 17 · ruled 22 October 2026
3. R-30 No marketing vocabulary: a word that sells the thing in place of saying what it does. The banned words are kept with the checks. Words that sell leave nothing to check. pair 17 · ruled 22 October 2026
4. R-31 A button is the verb and its object (“Add a source”, “Renew”), never “Get started for free”, “Learn more”, “Submit” or “OK”, and carries no arrow or chevron. A label that names the act and its object tells the reader what happens when they press it. pair 16 · ruled 22 October 2026
5. R-32 No exclamation mark, no greeting, no announced excitement and no cheerful apology; an error names what happened and what the reader can do. Cheerful words get in the way of a reader who wants to know what happened and what to do next. pair 18 · ruled 22 October 2026
6. R-33 Every state is written in its own words (empty, loading, error, disabled, zero-data), with no placeholder name and no filler text. Every state is something a reader will see, so each one says what is true at that moment. ruled 22 October 2026
7. R-34 No recurring saying as decoration: a ruled saying appears once, in its one home, and nowhere else; never as a label, strip, footer, meta line, plate source, placeholder or empty state. A line repeated on every page stops being read; said once, where it is explained, it keeps its meaning. changed 22 October 2026

Do and don’t

Each pair sets the plain form beside the pattern it replaces. The pictures are the Storybook’s drawings of each side, one in the dark mode and one in the light. The Storybook page draws the same pairs from the parts.

1. Sign-off DoThe bar is drawn over closed in “The eye is closed.” and nowhere else.
   
   Don’tA bar over a word in a headline hides a word the reader came for.
   
   R-1
2. Headline DoA headline is one ink at the display weight.
   
   Don’tAn accent word, an italic or a gradient.
   
   R-2 and R-19
3. Above the heading DoA source or a date is a meta line after the heading.
   
   Don’tA kicker, a pill or a number above it is a label the reader reads before the words.
   
   R-3
4. A number DoA number sits inline at body size with its time.
   
   Don’tA tile with the label on top sets a figure above the sentence it belongs to.
   
   R-7
5. A working state DoA working thing is silent.
   
   Don’tA green chip or a check announces what the reader never asked about.
   
   R-11 and R-12
6. A state with a verb DoA state shows beside the Button that acts on it.
   
   Don’tA chip with nothing to do is a status for its own sake.
   
   R-12
7. Claims DoClaims are prose in the measure.
   
   Don’tThree like boxes in a row make the reader compare boxes instead of reading.
   
   R-5 and R-6
8. Containers DoOne Notice with its action.
   
   Don’tA box in a box, or a coloured stripe down its side, adds edges and no meaning.
   
   R-5
9. Ground DoHairlines on the canvas.
   
   Don’tA shadow, glass, a glow or a lift on hover moves the eye off the words.
   
   R-8
10. Selected DoA selected segment is text plus a rule, and the page keeps one amber fill.
    
    Don’tA second one competes with the action.
    
    R-4
11. Body text DoBody text is 17px in the reading ink at the measure.
    
    Don’tSmall grey text on a long line is hard to read.
    
    R-14, R-15 and R-16
12. Case DoSentence case, no tracking.
    
    Don’tCapitals spaced wide are read letter by letter.
    
    R-17
13. Mono DoMono is for what the reader copies: a code, a key, a reference.
    
    Don’tA nav label or a footer in mono reads as a code.
    
    R-18
14. Icons DoA 16px glyph in a row’s leading slot.
    
    Don’tAn emoji, a glyph in a circle or a tile above a heading decorates and says nothing.
    
    R-22 and R-23
15. Motion DoThe bar draws once, then rests.
    
    Don’tA pulse, a marquee or a reveal on scroll moves while the reader is reading.
    
    R-10 and R-27
16. Buttons DoA button is the verb and its object, with no arrow.
    
    Don’t“Get started for free” says nothing the reader can act on.
    
    R-31
17. Sentences DoA sentence ends.
    
    Don’tA dash that joins two halves, a “not just” contrast and the marketing vocabulary are the tells of text nobody read twice.
    
    R-28, R-29 and R-30
18. Errors DoAn error names what happened and what the reader can do.
    
    Don’tA cheerful apology names neither.
    
    R-32

Brand and voice

• Readability comes first. Every design rule above removes something that stands between the reader and the words or the picture.
• One idea: the thing that is not there. One device: the redaction bar, the shape of the giraffe’s closed eyes. It is drawn once per view, over the word “closed” in the sign-off, and nowhere else.
• The players are dark, always. Light mode is for the reading pages.

Voice

Four traits: honesty, calibration, care without flattery and coherence.

• No unmeasured numbersA number a reader cannot trace to a source is a claim nobody can check.
• No claim that the source code is publicThe code is private, so a claim that anyone can read it would be untrue.
• No internal repo references in public copyA private file proves nothing to a reader who cannot open it.
• No internal-only routes from public copyInternal pages are working tools, and a visitor sent to one finds nothing written for them.
• Exits are named by number: exit 1, exit 2A name made of a number says nothing about where an exit is or what it runs on.
• No competitor comparisonAnother product’s choices are its own, so twiga’s pages say what twiga built.
• No superlatives without proofBecause one counter-example breaks a superlative, the copy says what twiga does instead.

Terms

twiga’s exits

Stream routing infrastructure

provider login

A person’s provider credentials

source

What a person adds to their account

playlist

The M3U field only

account

What a person signs in to; “vault” only where the wiki and the verifier explain how it works

Guide

The programme guide, in every label; “EPG” only where the wiki explains what it is

twiga relay

The server; never “twiga server” or “twiga backend”

twiga player

The player’s name in full; never “TwigaPlayer”

Parts

Each opens in the Storybook with its states drawn. A part still being tried is marked Trial.

Button

Any action on a page: one primary, the rest quieter.

Field

Text or a code that someone types, with its hint and error.

Select

A choice from a list too long to show at once.

Textarea

Text longer than a line, such as a note or feedback.

Toggle

A setting with two values that takes effect as it is flipped.

Checkbox

An option that is ticked or not, alone or in a group.

SegmentedControl

A choice from a few options that all stay in view.

IconButton

An action where a glyph says enough, such as close or copy.

Divider

A hairline between groups of content.

Notice

A message about this page that comes with something to do.

Dialog Trial

A question or form to answer before going on.

Confirm

The extra step before an action that cannot be undone.

Toast

A short note on a failure, or on something that happened off screen.

Skeleton

The shape of content on its way, when the layout is known.

EmptyState

A line that says what is missing, with a way on if there is one.

Sheet

A panel that rises from the bottom edge to hold a short task.

ListRow

One line of a list: a label, a value and its action.

Disclosure

Extra detail, kept behind a row until someone opens it.

ProgressLine

How much of a task is done, when that is known.

Keycap Trial

A key name that hints at a shortcut, shown on hover or focus.

Monogram Trial

The tile for a channel in a list, grid or guide.

NowChip Trial

The way back to now in the guide.

Capsule Trial

A glyph button over the picture, such as play.

Chip Trial

A small label on a row: a category, a quality tier or a state.

Menu Trial

A short list of choices that opens from a control.

Slider Trial

A value set along a line, such as volume.

PageHead

The top of a page: a way back, the title and the page actions.

CopyValue

A value to copy, such as a code or an address.

Plate

One fact, where it comes from and when it was checked.

Redaction

The sign-off, with the bar over its last word.

StatusChip

A state worth naming: a glyph, a word and a colour together.

Lockup

The twiga.tv wordmark, wherever the name stands as a logo.

Mark

The giraffe, on a hero and nowhere else.

Icon

A glyph that takes the colour of the text around it.

Rulings

Design rulings in plain words, newest first.