Design Principles
The eight constraints every Cynosure component and theme is measured against.
Design principles
Section titled “Design principles”Cynosure’s constraints are deliberate. These are the rules every component and every theme is measured against.
Tiny by default
Section titled “Tiny by default”Tree-shakeable ESM. Per-component entry points. Per-component CSS files.
sideEffects: false except for bare CSS imports. Consumers pay only for
what they import.
Props-only styling
Section titled “Props-only styling”Consumers should never need to write CSS to use Cynosure. Every visual concern is a prop, a variant, or a token override.
Raw HTML in one place
Section titled “Raw HTML in one place”Only the eleven layout primitives (Box, Stack, Inline, Flex, Grid,
Center, Spacer, Divider, AspectRatio, Container, Section) touch
intrinsic JSX elements directly. Form controls are the single necessary
exception — browser behaviour depends on the native element.
Accessibility is not optional
Section titled “Accessibility is not optional”WCAG 2.2 AA is the floor. Keyboard complete, focus visible, reduced-motion honoured, RTL safe. Every component has an axe-passing story.
Themes are data
Section titled “Themes are data”All design decisions live in W3C DTCG JSON tokens. CSS custom properties
are generated. Consumers swap themes with a single prop or a
data-theme attribute.
Controlled + uncontrolled both work
Section titled “Controlled + uncontrolled both work”Every stateful component accepts value / defaultValue / onChange (or
domain-appropriate names) and uses useControllableState internally.
asChild is the composition escape hatch
Section titled “asChild is the composition escape hatch”Every component that renders a single root element supports asChild.
Compose by passing your own element; we merge props via Slot.
Self-documenting
Section titled “Self-documenting”Every component ships with MDX docs, interactive Storybook, JSDoc on props, and an auto-generated API reference.
Architecture reference
Section titled “Architecture reference”The full architecture (styling pipeline, standard component anatomy,
perf budgets) lives in
docs/specs/ARCHITECTURE.md.