AGENTS.md — @openstatus/ui #

Three directories under src/components/, three different contracts. Getting the wrong one is the most common mistake here.

blocks/README.md documents the composition API and REGISTRY.md the publish flow. This file is only the rules those two assume you already know.

Do not customize src/components/ui/ #

These 41 files are shadcn's, and the registry ships zero of them. Blocks instead declare registryDependencies: ["button", "tooltip", …], which resolve to the consumer's own shadcn components at install time.

So a block that depends on a local tweak to button.tsx renders correctly in this repo and incorrectly for everyone who installs it — with no error anywhere. Patching also means the next shadcn add either clobbers the change or silently skips the upgrade.

When a primitive isn't enough, in order of preference: pass className, compose a wrapper in blocks/ or custom/, or add a variant to the block that needs it.

Editing a ui/ file is a last resort, and only for a defect stock shadcn has too. input-group.tsx is the precedent — FormControl's Slot injected a data-slot that clobbered the group's own, breaking the focus ring. It carries a comment saying why the prop order matters. Do the same, or don't touch them.

blocks/ is a published registry, not internal code #

Anything you add here ends up on openstatus.dev/r and gets installed into codebases that are not this one.

• Register it. A new file needs an entry in registry.json with its registryDependencies. Forget that and it works in the monorepo and 404s for consumers — nothing in CI catches it.
• No app imports. No next/link, no next-intl, no @openstatus/db, no tRPC. Every direct dependency becomes a mandatory install for consumers, and most of them aren't even on Next.js. Routing, markdown and translation come in through slot props (renderEvent, renderMessage, asChild) and the StatusBlocksI18nProvider context.
• Imports must exist in a stock shadcn install. pnpm registry:build rewrites @openstatus/ui/* to @/*, so @openstatus/ui/components/ui/button becomes @/components/ui/button on the consumer's machine. Importing a primitive we have but they don't produces a build error there, not here.
• New color tokens go in registry.json cssVars. That is how --success, --warning and --info reach consumers; a token used only in globals.css is undefined for them.
• Defaults must render unconfigured. Slots are optional, i18n falls back to English. The registry preview has no wiring.

Border radius #

globals.css defines the scale as ratios of the themed --radius, anchored so the 0.625rem default keeps shadcn's pixel values: xs 0.2 (2px), rounded 0.4 (4px), sm 0.6 (6px), md 0.8 (8px), lg 1.0 (10px, the base), xl 1.4 (14px). Stock shadcn subtracts fixed pixels instead (calc(var(--radius) - 4px)), which collapses whole steps to 0 on the status page, where a theme can set --radius to 0.25rem or 0.

Never hard-code a radius, and prefer rounded-lg over the equivalent rounded-(--radius). rounded-full is only for a chip that wraps a glyph (StatusIcon); a coloured status marker takes rounded-lg so it matches the bar it describes.

In blocks/, bare rounded is off-limits: its 0.4 ratio comes from our globals.css, and a consumer's stock Tailwind resolves it to a fixed 0.25rem. lg/md/sm are safe — shadcn defines those keys too.

The ratios deliberately stay out of registry.json cssVars. --success and friends are tokens a consumer lacks; --radius-sm is one they already have, and overwriting it would reshape every button and card in their app because they installed a status block. Installed blocks follow the host's scale — see REGISTRY.md for the snippet consumers can opt into.

Generated output #

dist/ and public/r/ are build artifacts of pnpm registry:build (which apps/web's build runs). Both are gitignored. Never edit them, and never fix a registry bug by editing dist/ — change src/ and rebuild.

Imports #

Exports are path-based, with no barrel: @openstatus/ui/components/ui/button, @openstatus/ui/components/blocks/status-bar, @openstatus/ui/hooks/use-media-query. Import the exact file.

Shared UI belongs here, not forked into an app — see docs/adr/0003-shared-ui-comes-from-openstatus-ui.md.