Design system

The four

Variant against state

The distinction decides which form a class takes, and it is the one most often got wrong. A variant is chosen when the screen is built and does not change. A badge is a success badge; it will not become a danger badge. A state is true now and false later — a field is in error until it is corrected, a menu is open until it closes. Variants read as part of the component's name; states read as something happening to it.

Sizes

Shapes

.button-circle squares the box itself, so .icon-only is not needed beside it. A circle can only ever be icon-only — a label inside one is an ellipse. Both shapes still need an aria-label: the icon is the only thing naming the action, and it names nothing to a screen reader.

Colours

Expressive

Plan tiers

Status tones

Solid

Solid reads as a claim where the tint reads as background, so it is for the one status on a row that has to be seen before the row is. One per row. Two, and the row is a set of coloured pills with no order — which is what a badge exists to avoid. Warning takes near-black text rather than white: white on #F0B100 measures 1.91:1.

Sizes

The two larger sizes drop the uppercase. At 10px you recognise the badge without reading it; at 14px caps is shouting, and a status is a word you read. Title Case in the markup, one word where possible — Active, not Currently Active; the row it sits in supplies the context.

Tones

Sizes

Leading icon

Removable

Sizes

With a track

Stretched

Sizes

Icon only

Every segment still needs an aria-label. Without the word, the icon is the only thing naming the option, and it names nothing to a screen reader.

Carrying a badge

Stretched

Disabled

Horizontal

Running to the edge of a padded card

The plain divider is width:100%, which resolves against the content box — so inside a padded card it stops short by exactly the padding. .pai-divider-bleed reaches past it. The card says how far by setting --divider-bleed to its own padding.

Vertical

With a label

Select

The menu is .dropdown-menu-style at the field's width. Opening it belongs to the screen: toggle .is-closed and .is-open.

What it holds

an <img>

MSinitials

a Phosphor icon

In that order of preference: a picture if there is one, initials if there is a name, the icon if there is neither — a seat nobody has taken, an invite not yet accepted. The ring is drawn over the picture rather than under it, so a pale photograph still has an edge against a white row.

Identity colours

These carry no meaning. They tell one person from another and nothing else — an indigo avatar is not an indigo kind of person. The semantic tones the rest of the system uses are deliberately absent: an avatar is never in a state, there is no dangerous person, and a red circle beside a name reads as an accusation.

Pick deterministically from something stable — hash the user id, not the display name, or the circle changes colour when somebody corrects their surname. Same person, same colour, every screen. For an icon or initials only; a picture brings its own colour. Every ink clears 4.5:1 on its own tint, because initials are text.

Sizes

.pai-avatar-small

.pai-avatar

.pai-avatar-large

Stacked

+3 .pai-avatar-stack

+8 .pai-avatar-small

The counter sits on top of the last face, always — it is the end of the stack, and a number half-hidden behind a picture is a number nobody can read. It is .pai-avatar-more and not an avatar: nobody is called +3, and giving it a person's shape claims there is a person to press.

The four states

With a divider that reaches the edge

A padded card sets --divider-bleed to its own padding, and the divider runs corner to corner. See Dividers.

Two rules that still hold

• Put .is-interactive on a real button, link or label. It supplies cursor, hover and a focus ring — it cannot make a div focusable, and a div you can click is unreachable by keyboard.
• Do not nest a card in a card. The inner one claims to be a separate thing you can act on, and it is not. Nesting a surface in a surface is a different question — white on white needs the raised step.

The eight

Each one already existed somewhere in the system. This names what the components were doing separately rather than adding a ninth way of doing it.

Selected

A near-black ring with a hairline of the surface colour under it, so the ring never touches the card's own edge. It replaces the resting shadow — two edges on one card reads as a border that changed its mind. Add .is-selected to .pai-surface-card or .pai-surface-raised. Known: this is identical to :focus-visible today — see coverage-gaps.md.

Stacked

Card and raised are both white with a shadow, and the difference is what they sit on. A card sits on the page and needs only enough lift to separate from grey. Raised sits on another white surface — a panel inside a modal — and needs more, because white on white has nothing but the shadow to say there are two planes.

Why eight, not the obvious seven

A side panel is not its own surface. It is the modal surface anchored to an edge — same background, same elevation, same layer, different geometry. Naming it would mean two things to keep in step for no difference a reader can see.

Two are easy to leave out and both earn a place. Sunken is the only surface that goes the other way; it is not a darker card, because nothing is meant to look like it is sitting on it — it is meant to look cut in. And scrim is a surface even though nothing rests on it: it is what makes the thing above it legible as above.

The layer scale

The layer is the part this system was missing, and the corpus shows why: it carries z-index values of 0, 1, 2, 20, 30, 60, 99, 500, 999, 9999 and 2147483000 — which is what happens when every screen picks its own.

The gaps are deliberate, so something new can slot between two layers without renumbering everything above it. Modal sits above scrim by number rather than by DOM order, so a modal rendered before its own scrim still lands on top. Tooltip is highest because a tooltip can be triggered from inside a toast, and a toast can appear over a modal.

Counts

One to four, because that is what the screens draw. Across all three canonical screens and every design, the counts in use are repeat(3,1fr) eight times, 1fr 1fr five, repeat(4,1fr) four. There is no twelve-column grid anywhere in the corpus, so none is published — twelve would mean every screen dividing by three to get back to the four it wanted.

Spanning

As many as fit

For a set whose length is not known when the screen is drawn — a deck of thumbnails, a list of brand kits — where a fixed count either leaves a hole at the end or squeezes to fit.

Gutter

What it collapses at, and why those numbers

900px and 600px are the only two widths the corpus has ever branched on. They are not invented device sizes: 900 is where the analytics modal drops its two columns to one, and 600 is where the create flow does. A grid that collapses where the screens around it already do disappears; one with breakpoints of its own fights them.

Three and four halve to two at 900 before going to one at 600, so a four-up does not jump straight to a single column and double the page height. A grid that must not collapse sets --cols inline, which beats every rule above it — no opt-out class is published because nothing needs one yet.

Every column is minmax(0, 1fr) rather than 1fr. That is a fix for a bug the corpus has: a plain 1fr will not shrink below its content, so one long unbroken string — a file name, a URL — pushes the whole grid wider than its container instead of ellipsing.

Default

.pai-ticker

Small, and faster

.pai-ticker-small · --ticker-duration: 22s

How the loop is seamless

The track holds its contents twice and travels exactly −50%. At the end of the run the second copy sits precisely where the first began, so the jump back to zero lands on an identical frame and cannot be seen. Duplicate the items or the loop visibly snaps — it is the one part of this that is not optional. Mark the copies data-ticker-clone aria-hidden="true": they are scaffolding, and a screen reader should hear the list once.

The edges are a mask-image rather than a gradient laid over the top, so the strip works on whatever surface it is dropped onto — a white overlay would only disappear against white. The logos sit grey and half-lit because they are somebody else's, used as evidence, and nine at full strength out-shout the screen they are evidence for.

Under prefers-reduced-motion it stops and becomes a scrollable row, and the duplicate copies are hidden — with no loop they are just a list printed twice. An endless sideways crawl is the exact thing that setting exists for.

Column chart

One colour for every bar. Bars are already separated by position and share one scale, so a colour per bar encodes nothing and invents a category. Colour one differently only to mark it out — the one being compared against, the one that failed.

Slide 7 was viewed by nobody. It keeps a hairline through .is-empty rather than rendering at zero height — a bar with no height reads as a gap in the data, and this one says measured, and it was nothing.

Donut and legend

pathLength="1" on each arc is what lets --value be a fraction: it tells the browser to treat the circumference as one unit, so the same markup works at any radius and nothing computes 2πr. --at is where an arc starts — the sum of the arcs before it.

Distinct colours, never shades of one. A ramp reads as an order — low to high, worst to best — and Direct link, Email and LinkedIn are not steps of anything. Two tints of one hue meeting on a curve also read as one arc with a shadow on it: hue survives a 14px stroke, lightness does not. The same goes for the key, whose swatch is 10px — a reader can name a hue at that size but cannot place a tint on a scale.

What it does not do

The chart draws what it is given and computes nothing. Scale, ticks and rounding are the caller's — whether zero belongs on the axis and whether to round to a nice number are judgements about data the component cannot see, so a component that guessed would be guessing.

Picture alone

It takes its width from whatever holds it and works out its own height, so there are no size classes. The one with no picture shows the sunken grey rather than white — a slide that has not loaded should read as a well waiting for one, not as a blank slide.

With a name under it

Palantir — Q1 Investor Shared workspace · 2 days ago Cost of a Data Breach Security · last week Building a Brand Like Patagonia Drafts · 3 weeks ago

On its side

Palantir — Q1 Investor Shared workspace · 2 days ago Cost of a Data Breach Security · last week

The picture takes its own radius back here, because it is surrounded by card rather than clipped by it. In the grid the card owns the corners and the picture is cut to them, so it has none of its own — a second curve inside the card’s reads as two edges.

Why the ratio is not negotiable

A presentation slide is 16:9 and every deck in assets/decks/ renders at 16:9, so a thumbnail at any other ratio is either letterboxing a slide or cropping one. The dashboard’s handoff drew 366.5 × 202 — 1.81:1, four pixels short, enough to letterbox every cover on the shelf.

display:block is load-bearing. aspect-ratio does nothing to an inline box, so as a bare <span> a thumbnail is sized by its content and the ratio is silently ignored. That is how the dashboard’s first covers came out at 1.32:1.

The picture is object-fit: cover, so a source that is not quite 16:9 is cropped rather than squashed. A crop loses an edge; a squash makes everything on the slide wrong.

Resting

The submit stays disabled until there is something to start. The strip centres while nothing is set, because there is nothing on the right to balance against.

Focused, with a brand kit applied

A board update on Q3 — revenue, the two misses, and what we are doing about them.

Upload files, or links 5 Slides Standard Model Create Presentation

.is-focused · .pai-prompt-brand.is-set

A kit applied takes the card's tint with it, through --prompt-tint, so the whole card reads as belonging to that brand. The kit here is assets/brand-kits/airbnb — one of four, chosen to be four different problems rather than four logos.

Fills

Thin

At 2px the ramp still reads, because it is pinned to the track — a gradient squeezed into the fill itself would be a single flat colour at this height.

Indeterminate

A bar on its own does not say what is progressing. Name the work and the units beside it — Generating 12 of 20 slides, not a bar and a number.

Skeleton

Shimmer

Reach for the skeleton when there is nothing to read, and the shimmer when there is. A screen that hides what it already has while refreshing it reads as a screen that lost it.

Rewriting

Reading a deck's copy while it is being rewritten means reading something about to be wrong — so this one hides it, and that is the difference from the shimmer. What survives is identity: shape, colour, count, position, all where they were. It says this is still your deck while saying not these words. It carries no sweep and is not a loading indicator on its own — it belongs beside a timeline or a spinner that already says what is happening.

Above the target

Below the target

Beside the target

Tones

Pill

A <time> inside any tooltip is set in tabular numerals. The first one ticks — watch the width. Proportional digits re-measure every second and the bubble twitches for as long as it is on screen.

With a header

Sizes

Medium is what a bare .pai-search already renders as — the class exists so the size can be stated rather than assumed. Large is for a field that is the reason you came to the screen; medium for one that filters something already in front of you.

With results

Default

Interactive rows