Designing

The design language is small on purpose. Five principles, one token set, one prop surface. Everything else falls out of those.

Principles

Universal first. A component is not "done" until both the web and the native variant exist, share the same prop API, and satisfy the same accessibility contract. Platform-specific affordances live behind the component, not in front of it.

Semantic tokens, never raw values. Components reach for bg-primary, text-foreground, rounded-md — names that survive theme changes. Hex codes inside a component are a code-review red flag.

WCAG 2.1 AA is a release blocker, not a stretch goal. Contrast, focus indication, keyboard support, and touch-target sizing are merge-gating. The audit checklist on each component page is the spec.

Mobile first. Layouts are designed at 375 px first and scale up. The lg size on interactive primitives is 44 px tall so it satisfies the Apple HIG and Material touch-target rule by default.

Density follows generosity. When two spacing options are equally defensible, take the larger one. Cramped UIs feel cheap; the system optimises for clarity over fitting more.

Tokens

Color, spacing, radius, motion, and typography all live in @mihcm/tokens. The same names appear in CSS variables, Tailwind utilities, the NativeWind preset, and (soon) Figma. Designers and developers reference one vocabulary.

Layout follows the Grid system: mobile-first breakpoints, tokenized gutters, constrained containers, and 12-column recipes for complex desktop screens.

If a value isn't a token, it shouldn't be in a component.

Component states

Every interactive primitive accounts for nine states: default, hover, focus, active, disabled, loading, error, empty, success. A reviewer should be able to point at any state on any component and find the answer — in the code and in Figma.

States that look identical must still differ in their accessibility signal. A disabled button is not a busy button, even when the pixels match.

Voice and tone

Copy in components is sparse and direct. No exclamation marks in micro-copy. Verbs over nouns. "Save changes," not "Click here to save." Errors describe what to do next, not what went wrong.

Figma

A token-mirrored Figma library is on the way. Until then, designers can pull live primitives from the Storybook viewer — every variant has a permalink, and the rendered components match what's shipped in production.