A design system you can click

Both panels render identical markup. Nothing inside either one names a colour: every fill is var(--bg-surface), var(--accent), var(--danger-text). Only the data-theme attribute on the wrapper differs. Because [data-theme] matches any element rather than only body, a subtree can be pinned to one mode while the rest of the page follows the toggle in the header.

The gray ramp is finer-grained at the dark end — 850, 900, 925, 950, 975 — and coarser at the light end. Dark UIs build elevation by getting lighter, and the usable distance between “canvas” and “raised surface” is only a few RGB steps before two surfaces stop reading as distinct. Light mode has the whole range up to white, so it needs fewer stops. The four steps marked with a dot (--blue-450, --blue-750, --lime-350, --lime-450) are hand-tuned for one job each — a dark-mode link that clears AA on near-black, and pressed states one step past hover — rather than generated for scale symmetry.

Three deliberate exceptions, all of them contrast decisions rather than taste. Info is sky, not blue: blue is the light-mode action colour, so an info banner painted blue reads as interactive. --warning-fg is near-black in both modes — amber is too luminous to carry white text at any usable step, so it is the one family that breaks the white-on-fill pattern. And --danger-solid is red-700 rather than the more common red-600: white on red-600 measures 4.31:1 and misses AA for normal text, while one step darker clears it at 5.75:1. A destructive button is the last place to ship a near-miss.

The samples above are divs carrying the heading styles, not real h1–h6 elements. A documentation page that demonstrates a type scale with live headings ships a broken outline: eight h1s and headings out of order. The visual and the semantics are separable, so they are separated.

Truncation needs three properties together — display: -webkit-box, -webkit-box-orient: vertical and -webkit-line-clamp — plus overflow: hidden. It is still the only cross-browser way to clamp by line count, and it is safe here because the full string stays in the DOM: screen readers and page search both see all of it.

Two breakpoints, both min-width, both written as native nested @media blocks inside the rule they modify rather than in a slab at the bottom of the file. Everything between them is fluid: the container is max-width, the grid is 1fr columns, and the two type steps that need to scale do it with clamp() and no query at all.

Look at the two panels at the same time. In light mode the cards are separated from the canvas by shadow alone. On a near-black canvas that shadow is doing almost nothing — there is no light for it to remove — so dark mode carries depth two other ways: the surface steps lighter (--bg-surface to --bg-surface-raised) and --elevation-* adds a hairline via an inset-free 0 0 0 1px shadow layer. That is the whole difference between --elevation-* and --shadow-*: the shadow tokens are the raw ambient darkening, and the elevation tokens are the mode-aware recipe a component should actually reach for.

--radius-full is 999px rather than 50%. On a non-square element a percentage radius produces an ellipse that changes shape with the content; a large absolute value clamps to a true pill at any width and still renders a circle when the element is square.

The colour rule is narrow on purpose. An icon takes currentColor — whatever text colour surrounds it — unless the icon is the status: the tick in a success banner, the triangle on a flagged plate. A blue download arrow next to black text is decoration, and it costs the reader a moment deciding whether the colour means something.

Two implementation details make that work here. Stroke weight is set once in CSS from --icon-stroke rather than a stroke-width attribute per file, so the whole set can be re-weighted in one edit. And .ds-icon declares color: inherit — without it the universal selector in base.css assigns every svg its own colour and “inherits the surrounding text” stops being true.

Both demos run all their rows at once, because a duration is only legible next to another duration. The buttons are toggles, not one-shots — they carry aria-pressed, so the runners' position is a state a screen reader can read rather than an event it missed.

Reduced motion is handled once, at the token layer. Under prefers-reduced-motion: reduce, theme.css redefines all four duration tokens to 0.01ms. Every transition in the codebase already reads its duration from those tokens, so the whole site goes still without a single component knowing the preference exists — and a component that hard-codes 0.3s is the only way to opt back out. Doing it per component instead means every new transition is a fresh chance to forget.

Every panel above takes its z-index straight from the scale — z-index: var(--z-drawer) and nothing else — so the diagram is the scale rather than a drawing of it. The order encodes decisions that are obvious one at a time and contradictory under pressure: a toast has to clear a modal, because a save failure that renders behind the dialog that caused it is a bug the user cannot even report; a tooltip has to clear a toast, because a tooltip is attached to whatever the user is pointing at right now.

The reason to centralise is arithmetic. Stacking is only comparable inside a stacking context, and a component that picks z-index: 9999 to win a specific fight is unarguable: the next component picks 10000. Eight names and a single scale make the question “which layer is this?” instead of “what number beats the other number?”

Sizes are 32 / 40 / 48px. Medium is the default and needs no modifier. Small is a desktop-density control for table rows and toolbars — at 32px it is under the 44px pointer target touch needs, so it is the wrong default on a phone.

The loading state does not change the button's width. The label keeps its box and only turns color: transparent, so the intrinsic width is locked and the spinner is centred on top of it — a button that grows or shrinks the moment it is pressed drags every neighbouring control out from under the cursor. Keeping the text in flow also keeps it in the accessibility tree, so the button still announces its own name alongside aria-busy. Interaction is blocked with aria-disabled rather than the disabled attribute, which would drop the button out of the tab order mid-task and silently move the user's focus.

The tooltip is marked aria-hidden. It repeats the button's aria-label verbatim, so exposing both would have a screen reader read the name twice. Keeping the two strings identical is the rule: the moment the visible name and the spoken name disagree, voice-control users can no longer say what they can see. The tooltip opens on :focus-visible as well as hover — one that only answers the mouse leaves a keyboard user with an unlabelled row of glyphs.

One tab stop, not one per option. The group uses a roving tabindex: the checked option is the only focusable one, and the arrow keys move focus and selection together, as the radio-group pattern requires. Disabled options are skipped rather than parked on. Selection is styled from [aria-checked="true"] rather than a class, so what is painted and what a screen reader announces read from the same attribute and cannot drift apart.

Visited can only ever be a colour. Browsers block every other property on :visited to stop history sniffing, so the treatment is a single hue shift — the link colour muted toward --text-tertiary — and nothing else. Hover therefore strengthens the underline rather than shifting the colour, which leaves the colour channel free for visited to use. target="_blank" always carries rel="noopener noreferrer": without noopener the opened page gets a handle on this one through window.opener and can redirect it.

Counter without maxlength. A native max length silently swallows the 33rd keystroke, so the user finds out by noticing text missing. The counter here lets the value go over, turns red, and links a real error — the limit is explained rather than enforced in silence. The counter is not a live region: announcing it on every keystroke would drown out the typing.

Why auto-resize is worth the JS. A fixed three-row box turns a 200-word deviation note into a scrolling window inside a scrolling page — the writer cannot re-read the paragraph they just wrote. The field grows with the content up to max-height: 260px, and only then hands overflow back to a scrollbar, so the submit button never runs away down the screen.

Custom listbox, not a styled <select>. The native control renders its popup in the OS layer, so option padding, the selected tick, a disabled option's explanation and the dark-mode surface are all beyond CSS and differ on every platform. This is a button plus a real role="listbox", which means the keyboard model is ours to get right: ↑↓ HomeEnd move, first-letter typing jumps, Enter selects, Esc closes, and focus never leaves the trigger — the active option is pointed at with aria-activedescendant. The panel above it is a static rendering of the open state, marked aria-hidden so assistive tech is not offered a second, fake control. The trade is real: on a native select, a mobile OS gives you its own wheel picker for free.

Backspace arms, then removes. Deleting a selection the user cannot see their cursor in is a destructive keypress, so the first Backspace on an empty field marks the last chip and the second one removes it. Every removal — click or key — is announced through a polite live region, because a chip disappearing silently is invisible to anyone not watching that corner of the screen. Each chip's remove button is a real button in the tab order, so nothing here depends on knowing the Backspace trick.

The panel follows the query, not focus. Results stay open while the field has a value, so clicking into the list — or reading it on a screenshot — does not make it vanish. Esc clears the query and closes it in one press; ↑↓ walk the results and Enter takes the highlighted one. The matched substring is wrapped in <mark> repainted with --accent-muted, because the browser default is a fixed yellow that ignores the theme entirely.

The toggle is a button, and its name changes. It carries aria-pressed so its on/off nature is exposed, and the accessible name flips between "Show passphrase" and "Hide passphrase" — an icon-only control whose name never changes tells a screen-reader user nothing about what state they are in. Focus stays on the button after a press, so the toggle can be operated repeatedly without losing the caret. The masked value is set in --font-mono because proportional dots are almost impossible to count.

A fixed three months, and a real grid. February to April 2026 are rendered at build time from hard-coded values — never from new Date() — so the demo shows the same weekdays in a year's time as it does today, and month navigation is a panel swap rather than date arithmetic. The calendar is a role="grid" whose cells are the gridcells: ←→ move a day and cross the month boundary, ↑↓ move a week, Home/End jump to the start and end of the week, PageUp/PageDown change month, Enter selects and Esc closes and hands focus back to the trigger. Days outside the study window stay rendered, keep their place in the roving tab order and carry aria-disabled — moving onto one says so rather than skipping it silently.

The dropzone is the enhancement; the input is the control. A real <input type="file"> sits inside the zone, visually clipped but still focusable and still what a screen reader announces — its focus ring is forwarded to the visible "Choose file" label, since a clipped element's own ring is invisible. Drag handlers use a counter for dragenter/dragleave, because those events fire again for every child element the pointer crosses and a naive handler flickers. Progress here is a timer standing in for a real upload; the role="progressbar" and its aria-valuenow are wired the way they would be against a real one.

Indeterminate is a DOM property, not an attribute. There is no indeterminate markup to write — it can only be set as el.indeterminate = true, which is why the parent above is wired in script rather than in the template. Setting it is also what makes a screen reader announce the box as "mixed"; a dash painted with CSS alone announces as unchecked and quietly lies.

The card is a label, not a div. The whole surface is clickable because a <label> wraps a real <input type="radio">, and the card reacts through :has() rather than a JS-toggled class. That keeps arrow-key navigation, one tab stop for the group, the announced legend, and form submission — all of which a click-handler div throws away and then has to reimplement badly.

Still a native checkbox underneath. The control is <input type="checkbox" role="switch">, so it participates in the form, toggles with Space, and needs no key handling. The aria-checked attribute is written explicitly for the assistive tech that does not map the host-language state onto the switch role — which means it has to be re-set on every change, or it goes stale and starts announcing the opposite of what is on screen. That sync is the one line of script this component needs.

Two inputs, one rail. The range variant stacks two real <input type="range"> elements over a shared track, so each handle keeps its own tab stop, arrow keys, Home/End and announced value — none of which a div-with-two-draggable-handles gets for free. The track takes pointer-events: none and the thumbs take it back, otherwise the top input swallows every press and the lower handle can never be grabbed. Crossing is prevented on input, not change — by the time change fires, the range has already inverted on screen.

One switch in a form is not a contradiction. The notification toggle above applies on flip and says so in its helper text; everything else in the form is staged until Submit. That is the only shape in which the two controls can share a screen — if the switch needed the Submit button, it would have to be a checkbox. Note too that the two-column grid collapses to one column below 640px and the fieldsets always span the full width: a group of related controls that gets cut in half by a column boundary stops reading as a group.

Selected is not the same as focused. Focus is a 2px inset ring; selection is the accent underline plus a lift to --text-primary. Keeping them visually separate is what makes arrow-key navigation legible — the user can see focus travel ahead of the selection they are about to commit to.

Truncation is hiding, not deleting. The collapsed crumbs carry the real hidden attribute, so they leave the accessibility tree with the pixels instead of being read out as an invisible trail. The last crumb is a span, not a link — it is the page you are on — and carries aria-current="page". Individual crumbs also truncate at 20 characters, because a long study title should cost an ellipsis, not a second row.

Disabled prev and next are really disabled. They carry the disabled attribute rather than a grey class, so they are out of the tab order and cannot be activated by keyboard or script. The result count is a role="status" region: changing pages moves nothing on a screen reader's screen, so the new range has to be announced.

Scoped to its frame, and collapsed by container width. Nothing here is position: fixed — the bar is sticky inside its own scroll panel, and the demo shell carries isolation: isolate so --z-sticky resolves locally instead of racing this site's real header. The link row hides at a @container breakpoint rather than a media query, which is why the same component can show its desktop and mobile layout side by side on one screen.

Collapsed is a CSS clip, not a DOM removal. The label stays in the markup and is clipped to one pixel, so an icon-only rail still exposes "Cohorts" to a screen reader and keeps a native title tooltip for everyone else. Groups are real button elements with aria-expanded and aria-controls, so they work from the keyboard without a single key handler.

Status is a word, a shape, and a colour — in that order. Every step spells its state out in text ("Needs attention"), backs it with a distinct marker (tick, exclamation, number), and only then tints it. Drop the first two and the stepper stops working in greyscale, for the 8% of men with a colour vision deficiency, and for anyone listening rather than looking. The current step also carries aria-current="step".

Auto-dismiss is a decision, not a default. Info and success clear themselves in five seconds; a warning gets seven because there is more to read; an error never auto-dismisses — the one message a user cannot afford to miss is the one that should not vanish on a timer. A toast carrying an action gets nine seconds, because the user has to decide before they can act.

The timer pauses on hover and on focus. A toast that disappears mid-sentence, or that vanishes while someone is tabbing toward its Undo button, is the classic failure of this pattern. The countdown bar and the JavaScript timeout are paused by the same interaction, so what you see is the real remaining time rather than a decorative animation running next to an independent timer.

Two live regions, not one. aria-live cannot be changed per message once a region is registered, so the viewport holds a polite region and an assertive one. Errors go to the assertive region and interrupt; everything else queues politely behind whatever the screen reader is already saying. Both are role="region" with a label, and every dismiss button names the toast it closes rather than saying "Close".

role="alert" is not decoration. It makes the element an assertive live region: a screen reader abandons whatever it was saying to read it, and it moves the user's attention. That is right for the blocked export above, and wrong for the other three — an informational note announced this way interrupts the sentence someone was listening to. Over-applying role="alert" to every banner is one of the most common accessibility regressions in a design system, precisely because nothing looks broken on screen. Rule of thumb: no role for a message that was already on the page at load, role="status" for one that appears without blocking, and role="alert" only when the user must stop.

The dot is a second channel, not the only one. It is safe here because the word beside it already carries the meaning. A bare coloured dot with no text — the pattern that shows up on avatars and nav items — conveys status by hue alone and fails 1.4.1 Use of Color; if you need one, pair it with .sr-only text and a tooltip, and accept that sighted colourblind users still get nothing.

Removal has to be announced. The chip disappearing is visual feedback only; removing one here also writes "Assay: RNA-seq filter removed" into a polite live region, because a keyboard user whose focus target just left the DOM otherwise gets silence. Focus moves to the next chip rather than back to the top of the document.

Indeterminate means omitting aria-valuenow, not setting it to zero — zero is a real value and announces as "0 percent", which is a lie about a job that has started. Under prefers-reduced-motion the sliding segment is replaced by a static full-width wash in --accent-muted rather than the solid accent, so it still reads as busy without reading as finished.

The label is the component; the ring is decoration. The spinner is aria-hidden and the text beside it does the announcing — which is also why that text is mandatory rather than optional. Under prefers-reduced-motion the ring stops rotating entirely and holds as a static three-quarter arc, so a user who asked for no motion is left with the sentence, not with a silent frozen circle.

A screen reader must never read the boxes. Every bar is aria-hidden="true", the container carries aria-busy="true", and one .sr-only sentence says what is loading. Without that, assistive tech announces a dozen empty generics and the user has no idea the page is still working. The last line of a text skeleton is short on purpose — a block of equal-length bars reads as a table, not as prose. Note that the column headers above are not skeletons: those labels are known before the request resolves, so rendering them immediately gives the user something to read while the cells fill in.

Token gap: the shimmer highlight uses --bg-muted over a --bg-subtle base, and that pairing steps darker in light mode and lighter in dark. Both are visible, but the sweep is not the same gesture in both themes. A proper fix is a token that always steps one increment away from the surface in the mode's own elevation direction — it does not exist yet, and inventing a [data-theme] override in this file would have put a per-mode decision outside the theme layer.

The two differ in every part except the frame. The first-run state has a primary button because creating the first cohort is the thing the user came to do; the filtered state has only secondary buttons, because undoing a filter is a correction, not an achievement. The first-run copy explains what the object is; the filtered copy names the specific predicates that excluded everything, and says how many rows exist without them — which is the number that tells the user whether to widen the filter or fix the study. Same shell, opposite jobs.

Section level fails small; page level fails whole. A section error keeps the surrounding chrome alive so the user can still navigate away and still trusts the rest of the screen — which is why the copy says explicitly what was not affected. A page-level error owns the viewport, so it must offer at least one exit that is not "try again", because the retry may keep failing.

Empty and error share one shell. Both render .ds-blankslate; only the glyph tone, the copy, and the call to action differ. Keeping them one component is deliberate — it is what stops "no results" from drifting into looking like a crash, and a crash from being mistaken for "no results".

Built on the native <dialog> element. Calling showModal() hands the platform the four things a hand-rolled modal gets wrong: the top layer (so no ancestor's overflow or transform can clip or capture it), the focus trap, the inert background, and Escape. ::backdrop is painted with the --overlay token, so the scrim re-points with the theme like everything else. What is left to write by hand is overlay-click dismissal, the body scroll lock, and returning focus to the exact element that opened it — about thirty lines instead of three hundred.

Same shell as the modal, different geometry. A drawer is the same <dialog> plus showModal(), so it inherits the focus trap, Escape, the inert background and the scroll lock unchanged — only the panel's placement and its transform change. It sits at --z-drawer, one step below --z-modal, because a confirmation raised from inside a drawer has to land on top of it. Sides use physical margins rather than flex alignment: justify-content follows the writing direction and would quietly swap left and right in an RTL locale.

The flip is real, and the panel says so. Each popover prints the placement the collision pass actually resolved to. Open Prefers right at a normal window width and it reports left, because there is not enough room to its right; widen the window and it goes back to right. Scroll the page until a trigger sits near the bottom of the window and Prefers bottom-start resolves to top-start. The rule is deliberately conservative: flip only when the preferred side genuinely cannot hold the panel and the opposite side holds more of it, otherwise the panel appears to jump around at random. Cross-axis overflow is handled by shifting rather than flipping, and the whole thing re-runs on scroll and resize.

Popovers may contain focusable elements; tooltips may not. That is the line between the two patterns. This one holds a select, two checkboxes and two buttons, focus moves into it on open, and Escape closes it and returns focus to the trigger. Everything here uses the native Popover API, so light dismiss, Escape, and the top layer come from the platform; only the coordinates are computed in script.

Hover waits, focus does not. A 350 ms delay on hover stops a row of tooltips firing as the pointer sweeps across a toolbar; keyboard focus shows immediately, because a keyboard user has already committed to that control. Hiding has no delay in either case. Each tooltip is wired to its trigger with aria-describedby, so it is announced as a description rather than replacing the button's own label — the buttons above carry a real aria-label as well, and would still be usable if the tooltip never appeared. The arrow keeps pointing at the trigger even when the panel has been shifted back inside the viewport, and Escape dismisses it without moving the pointer, which WCAG 1.4.13 requires.

Keyboard model. Arrow keys move, Home and End jump to the ends, single letters type ahead to the next matching item, Escape closes and returns focus to the trigger, and Tab closes the menu rather than walking through it — a menu is one stop in the tab order, not eight. The disabled item uses aria-disabled rather than the disabled attribute, so it stays in the roving-focus order and a keyboard user learns the action exists and is unavailable, instead of it silently vanishing.

Focus opens on Cancel, never on the destructive button. A confirmation is often reached at speed, and the muscle memory that got the user here is a keypress away from firing again — Enter or Space on an autofocused Archive button would commit the exact action the dialog exists to slow down. Landing on Cancel makes the reflex safe and costs a deliberate Tab to proceed. The second dialog goes further: for something genuinely irreversible, typing the study identifier is what enables the destructive button, which turns a reflex into a transcription the user has to look at the screen to complete. Reserve that for actions with no recovery path at all; on anything routine it is theatre, and people learn to copy and paste through it.

Sort Reads (M) and watch the order. The comparator parses the value out of data-reads and subtracts; a string comparison would rank 103.2 above 12.7 above 9.4 and still look sorted, which is why this defect survives review so often. Run date sorts as a string on purpose — the row carries an ISO 2026-06-04, and a lexical sort of ISO dates is chronological, so the display format 04 Jun 2026 never has to be parsed.

Two details doing quiet work. The sticky header needs border-collapse: separate — under collapse the header's bottom border belongs to the collapsed grid, not the cell, so it is left behind the moment the row detaches. And the scroll container takes tabindex="0" with a name, because a region that only a mouse can scroll is unreachable content.

The stretched-link trade-off. The overlay that makes the whole card clickable also sits on top of the body copy, so that text can no longer be selected. Worth it for a summary card in a grid; not worth it where the card holds anything a user would copy — an ID, a dose, an address. There, keep the link on the title alone.

Selection carries a bar, not just a tint. The --accent-muted wash is a low-alpha fill and reads faintly on a busy background, so the selected row also gets a 2px inset bar and aria-current="true". Focus stays visually distinct from both — an inset outline, offset inward because the list clips its children.

Photo, initials, presence

Photo

Initials IM Ines Moreau

Online IM Ines Moreau, online

Away TO Tomas Oyelaran, away

Offline SK Sara Kwon, offline

With a name, and stacked

Paired with text Devi Raman Lab lead, Basel · Status: Online

Stacked group

• 
• IM Ines Moreau
• SK Sara Kwon
• +3 and 3 more reviewers

Why the fallback is not an afterthought. A photo is raster content — it does not re-point when [data-theme] flips, so it is the one element on the page that cannot be themed. Initials can be, which is why they are built from --accent-muted and --text-primary rather than a per-person tint. When the avatar sits beside its name, the image takes alt="" so the name is not announced twice.

The sparkline is context, not content. It is aria-hidden — a screen-reader user gets the value and the delta in text, which is the whole story — and it is painted in --text-tertiary rather than --accent, because the accent is reserved for things you can click and spending it on a decorative trend line devalues it everywhere else on the page. Both the value and the delta use tabular-nums, so a live tile does not jitter sideways when its last digit ticks over.

Single-open vs. multi-open is a content decision. Single-open suits panels that are alternatives — one site's protocol at a time — and keeps the group's height predictable so the page below does not jump. Multi-open suits panels that are reference material, where someone may reasonably want two open side by side; never close a panel the user opened deliberately. Collapsed panels use the hidden attribute rather than a height animation, which is what keeps their contents out of the tab order — a panel that animates to zero height still holds focusable controls. The value until-found keeps them reachable by find-in-page in browsers that support it, and degrades to a plain hidden in those that do not.