Design principles

Tie-breakers when a decision could go either way. Not rules — priorities.

1. Quiet by default#

Typography weight does the work; heavy backgrounds and gradients don't. One accent color per surface. Borders are 1px and dim until something needs your attention.

2. Tokens before values#

Every visible decision (color, spacing, type, radius, motion) is a named token in @ship-it-ui/tokens. Components consume tokens, never raw hex or px. This is the single rule that lets us reskin the system in one variable change.

3. Accessible by default#

Every component asserts axe violations === 0 in unit tests. Behavior + ARIA + keyboard come from Radix primitives where applicable. If a component can't pass a11y, it doesn't ship.

4. Composition over configuration#

A few sharp primitives that compose well beat one giant component with thirty props. Prefer <Card><Card.Header /></Card> to <Card title=… subtitle=… actions=…/>.

5. Predictable APIs#

All components accept className, forward refs, and use asChild for polymorphism. Variant axes are typed via cva. Once you've used one component, you can guess how the next one works.

6. Honest performance#

Tree-shakeable ESM. No runtime CSS-in-JS. No global side effects beyond the explicit @ship-it-ui/ui/styles/globals.css import. Geist is self-hosted, not loaded from a CDN.

7. Glyphs, not emoji#

The icon vocabulary is typographic glyphs (◆ ◇ ○ ▤ ✦ …) rendered at text weight, monochromatic, always centered. Never tinted, never gradient. See Foundations / Iconography for the full set.