Skip to content
Documentation

ADR-008: Border, Surface, and Overlay Discipline

Decision

One neutral border per visual stack. Floating overlays must escape local clipping and point back to their trigger. Storybook previews never invent a border the component does not own.

Key rules

  • One neutral perimeter border per local stack: border border-border. If the parent already has one, the child does not add another — prefer bg-muted/40 or spacing.
  • Extra or colored borders are allowed only for semantic state: focus ring, selection, destructive, drop target. Borders signal boundaries, not emphasis.
  • Anchored overlays (tooltip, popover, dropdown, combobox) must be portaled or positioned to escape any overflow: hidden ancestor. Test them inside cards, dialogs, and tables.
  • Every anchored overlay shows a caret pointing at its trigger; use the Radix UI or React Aria arrow primitive — do not hand-roll it. Full-screen dialogs and edge-anchored drawers are exempt.
  • Storybook preview wrappers frame a component with spacing, tone, or canvas width — never a CSS border the component does not actually own.

Why

Doubled and decorative borders are the second most common visual bug; one border per stack keeps surfaces legible. A caret and clip-escape are correctness requirements for anchored overlays, not decoration — without them the overlay floats unanchored or is clipped by a parent. A fake preview border misrepresents the component’s real visual footprint.

Applies when

You are adding a border to a card or container, building a floating overlay, or setting up a Storybook story canvas.

  • ADR-009 — icon role, placement & layout.
  • ADR-004 — interaction polish and motion.