DESIGN.md #

How openstatus UI should look, feel and be built. AGENTS.md says where code lives and what breaks; this file says what good looks like. Read both before touching anything a user sees. Rules are short on purpose: the reason is the rule, and the exception is in review.

Principles #

• Hierarchy over decoration. A page has one loud level and one quiet level. Authored content (a note, an update, a postmortem) is loud. State changes and system events are quiet. If everything is emphasized, nothing is.
• Quiet by default. Start from text-muted-foreground and lift only the word that matters to text-foreground. Borders, fills and color are earned.
• Compose, don't invent. A new screen is existing primitives in a new arrangement. A new primitive is a reviewed decision, not a side effect of a feature.
• Unseen details compound. Nobody notices a 160ms press or a dashed-underline hover on its own. Together they are why the product feels right.
• Learnable by repetition. The same shape on every incident, report and maintenance teaches the workflow without a tour. Consistency across pages beats a better idea on one page.

Components #

Where things live #

Layer	Path	Rule
shadcn primitives	packages/ui/src/components/ui/	Stock. Edited only as a documented last resort, see packages/ui/AGENTS.md.
Public blocks	packages/ui/src/components/blocks/	Published registry. Imports nothing from an app; apps import them freely.
Shared custom	packages/ui/src/components/custom/	Ours, used by more than one app.
App kits	apps/*/src/components/content/, common/	Compound kits a whole app composes from.
Feature rows	apps/*/src/components/<feature>/	What a feature renders with the kits.

A repeated visual is a new part in a kit, never a copied class stack. A feature-specific row (an incident event, a report update) lives in the feature folder and imports the kit; it does not add exports to the kit.

Compound components #

One kit per concept, small export list, every part a plain element wrapper:

export function TimelineItem({ children, className, ...props }: React.ComponentProps<"li">) {
  return (
    <li data-slot="timeline-item" className={cn("relative grid …", className)} {...props}>
      {children}
    </li>
  );
}

• Props are React.ComponentProps<"tag"> plus the few the part owns. Spread the rest, merge className with cn, always set data-slot.
• Parent context is expressed in CSS, not props: in-data-[slot=timeline-card]:text-foreground lets an actor render muted in a row and bold in a card without a variant prop.
• State is expressed through attributes the browser already sets: aria-pressed:, data-[state=open]:, aria-invalid:, disabled:. Style the attribute, never a parallel boolean class.
• Keep the kit at the number of exports it needs. Timeline has eleven. If a feature needs a twelfth, first ask whether it is a row in the feature file.
• Children, not render props, for layout. Slot props (renderMessage, asChild) only where a block must stay free of app dependencies.

Variants #

• cva for the visual axes of a part, VariantProps for the type. Status variants are default | success | warning | destructive | info, pinned with satisfies Record<StatusVariant, string> so a missing one fails typecheck.
• className is for layout (margin, width, grid placement). It is not for restyling a part's colors or type; add a variant instead.
• Prefer a boolean switch (dot, plain) over a new variant when it only removes chrome.
• gap-* on flex and grid, never space-x-* / space-y-*. size-* when width equals height. truncate plus min-w-0 on the flex child.

Primitives #

When a shadcn primitive is not enough, in order: pass className, wrap it in a kit part, add a variant to the wrapper. Editing ui/ is a last resort with a comment saying why. Shared UI comes from @openstatus/ui; an app never forks a primitive (docs/adr/0003).

Hierarchy and layout #

• Two row kinds, one rail. A list of events has a compact sentence row (icon, muted sentence, time) and a card (avatar, header, body, optional footer, actions top-right). The rule for which: an authored message is a card, everything else is a row. The rail runs between every item, including card to card and composer to first item.
• Sentences, not labels. A row reads "Thibault marked Resolved", not "Status changed · Thibault". The actor and the lifted value carry the only emphasis.
• Composer first, newest first. On anything time-ordered the input sits on top and the latest item is directly below it. During an incident you want to know what just happened.
• Content left, properties right. Detail pages are a main column (header, composer, timeline, postmortem) and an aside of label/value properties. The aside is reference; it never competes with the timeline. A linked entity is one row with its actions behind a menu, not a card with a primary button.
• Section title plus count. Activity 10, Updates 3. The count is mono and muted.
• Spacing. Lists gap-4, cards px-4, inside a row gap-2.5, stacked compact rows pull up with a short rail. Pages cap at max-w-6xl. Padding is symmetric unless the asymmetry is explained in a comment.
• Empty states use the dashed EmptyStateContainer with a title and one sentence that says what to do next. Never a bare "No data".
• Inline editing. Title and summary are borderless inputs that show their edge on hover and focus. Save on blur or explicit action; never on every keystroke.
• Hover affordance is a dashed, muted underline (decoration-dashed decoration-muted-foreground/50 underline-offset-2). Not a color change, not a chevron, not a dot.

Color #

• Tokens only: background, foreground, muted, muted-foreground, border, ring, success, warning, info, destructive. They are OKLCH in packages/ui/src/globals.css. Never a raw palette class (text-emerald-600).
• Dark mode comes from the tokens. No dark: color overrides in components. Images in content pages get a .dark sibling file.
• Status color sits on the smallest element that can carry it: a StatusDot, the word in a sentence, the icon in a disc. Chrome stays neutral.
• Tinted chrome is one recipe: border-{token}/20 bg-{token}/10 text-{token}. Inside a sentence use StatusBadge plain (dot and mono text, no border). Bordered badges belong in cards and tables.
• Impact and status labels on the status page are colored text only.
• A new token goes into registry.json cssVars too, or it is undefined for everyone who installs a block.
• Contrast: 4.5:1 for text, 3:1 for icons, focus rings and borders that carry meaning. Muted text on a muted fill is the usual offender; check it in both themes.

Typography #

• Sans for prose, labels and buttons. Mono for values: ids, counts, dates, durations, statuses, anything a user might copy or compare.
• tabular-nums on any number that updates in place so columns do not jitter.
• No font sizes beyond the scale. Hierarchy comes from weight and color before size: font-medium text-foreground for the lifted word, size only for the page title.
• Relative time in the row (2d ago), absolute time with timezone in a hover card. Both from HoverCardTimestamp; never format a date inline.
• Wrapped sentences are allowed. Icons top-align (items-start) so a two-line row still reads.
• Sentence case everywhere. Brand is openstatus, lowercase, except at the start of a sentence. Click paths use >: Settings > Integrations.

Radius #

The scale is proportional to the themed --radius (xs 0.2, sm 0.6, md 0.8, lg 1.0, xl 1.4). Prefer rounded-lg. Never hard-code a pixel radius. rounded-full only wraps a glyph. The status page and the marketing site set --radius to 0, so a radius in a demo is dead code. Details in packages/ui/AGENTS.md.

Motion #

CSS transitions only. There is no animation library in this repo and none is planned.

• Ask first whether it should move. Something seen a hundred times a day (command menu, keyboard shortcuts, list navigation) does not animate. Hover and press get feedback, not motion. Modals, drawers and toasts get a standard transition. Only rare moments may delight.
• Durations. Press feedback 100–160ms. Tooltips 125–200ms. Dropdowns and selects 150–250ms. Modals and drawers 200–300ms. Nothing in the UI over 300ms.
• Easing. ease-out for anything entering or leaving. ease-in-out for movement on screen. ease for color and hover. Never ease-in.
• Transition named properties, never transition-all. Prefer transform and opacity; they do not trigger layout.
• Press feedback on pressables we own (kit parts, blocks, custom): active:scale-[0.97] with the press duration above, on press rather than release. The stock ui/button stays untouched; add it through a wrapper class, not by editing ui/.
• Never enter from scale(0). Start at 0.95 or higher with opacity.
• Popovers scale from their trigger (origin-(--radix-popover-content-transform-origin)). Modals stay centered.
• Second tooltip opens instantly. The delay guards the first hover only.
• motion-reduce: on every transition that moves or scales. Fades may stay.
• @starting-style for enter animations when support allows, the data-mounted pattern otherwise. No useEffect just to animate.

Interaction and accessibility #

• Native elements. A button acts, a link navigates. No div with role="button". Space and Enter both work on a button because it is one.
• Every icon-only control has a label: aria-label plus a tooltip that shows the same text and the shortcut if there is one. Decorative glyphs (StatusDot, rail icons) are aria-hidden.
• Focus is visible. Never remove the focus-visible ring; override it with the token ring if a layout needs it. Keep focus inside overlays and return it to the trigger on close. The shadcn primitives already do this; a custom popover must too.
• Overlays have a title. Dialog, Sheet, Drawer always get a title; sr-only when the design hides it.
• Forms. Every control has a connected label. Placeholder text is not a label. Validation sets aria-invalid on the control and data-invalid on the field. Errors read next to the field, not only in a toast.
• Keyboard. ⌘↵ submits a composer, Escape leaves it, a single letter toggles a mode (E for preview). Shortcuts ignore key repeat, ignore typing inside inputs, textareas and open overlays, and show in the tooltip.
• Targets. 24×24px minimum on desktop, 44×44px where touch is likely. Pad the hit area, not the icon.
• Loading. Skeleton for layouts, Spinner with disabled on a button. No isLoading prop on a primitive; compose it.
• Destructive actions confirm with a dialog that names the thing being removed. The last item in a required list cannot be deleted; hide the action rather than erroring.
• Toasts carry an error the user can act on. A failed background call is never silent.

Responsive and mobile #

• Mobile first. Breakpoints follow the content, not devices. sm: for two columns, md: for the full layout. A four-column grid steps through two.
• No horizontal page scroll at 320px. Tables overflow in their own scroller (overscroll-behavior: contain); pages never do.
• hover: styles apply only where hover exists. Tailwind v4 compiles hover: to (hover: hover); do not reintroduce ungated hover with raw CSS. Touch users get :active feedback instead.
• touch-action: manipulation on tappable elements removes the double-tap delay. -webkit-tap-highlight-color: transparent globally, then every tappable has its own :active state.
• Inputs are 16px on touch so iOS does not zoom. Never disable zoom.
• 100dvh for app shells, drawers and bottom-pinned UI; 100svh for heroes. Fixed bars pad with env(safe-area-inset-*) and the viewport meta sets viewport-fit=cover.
• Swap structure with useIsMobile only when CSS cannot: Dialog becomes Drawer, a row of actions becomes a menu. Everything else is a breakpoint.
• Gate on capability ((pointer: coarse), (hover: hover)), never on the user agent.
• Test on a phone, not only in the emulator. Sticky hover, the keyboard and safe areas do not reproduce.

HTML #

• Semantic first: ol for ordered timelines, time with dateTime for every timestamp, header/section/aside where the page has those parts, one h1, headings in order.
• Interactive inside interactive is a bug: no button in a link, no link in a button. A card that is clickable has one link, overlaid, and the rest is inert to the click.
• Images declare width and height or fill; no layout shift on load.
• color-scheme: light dark on the root; theme-color once per scheme.
• No manual z-index on overlays; the primitives own the stack.
• inert on background content while an overlay is open comes from the primitive. Do not reimplement focus trapping.

Worst cases #

Before calling a view done, render it with:

• a 255-character title, an email with no break opportunity, a one-letter name, a name with emoji
• no avatar, no author (legacy rows), no description
• 0, 1 and 1,000 items; a count of 1 that must not say "1 updates"
• 320px wide, the widest layout, 200% zoom
• both themes

Flex failures look like squished avatars (shrink-0), text that overflows instead of wrapping (min-w-0), actions pushed off-screen, badges on two lines, and a last row clipped mid-glyph.

Verify by looking #

An agent cannot judge rendering from a diff. For any visible change, scripts/screenshot.mjs (the screenshot skill) shoots the element, not the viewport, on desktop and mobile (light; dark on request) on the local dev server of the dashboard, the marketing site or the status page, logging in with a seeded session where needed. Selectors differ per app: [data-slot=timeline] and the other dashboard slots, main or a section on the marketing site, the block slots from packages/ui/src/components/blocks/ on the status page. Compare against the previous state. Feedback goes back the same way: a screenshot with the problem boxed and one sentence. Marketing and docs pages render every component on /kitchen-sink so drift is visible there first.