The measure of a design system is how little you have to do to get the right result. With Optimistic, the shortest path, install and import, is already the correct one.

Own the code, not a black box

Optimistic installs like a set of source files you own, not an opaque dependency you fight. You add the components you need, they land in your codebase, and you can read and change every line. Nothing is hidden behind a version bump you cannot inspect.

That ownership matters the first time you need a component to do something its author did not anticipate. You are editing real, legible code, not overriding a library from the outside.

Install once

npx optimistic-ui add button card table

Import and use

import { Button } from "@/optimistic-ui"

Ship with defaults

<Button>Get started</Button> // accessible, on-brand

Three steps from nothing to a shipped screen. The defaults are accessible and on-brand out of the box.

Style with tokens, not values

Once the components are in, resist the urge to reach for a raw hex or pixel. Style with the semantic tokens: surface, accent, danger, the spacing scale. A screen built this way re-themes for free and survives a rebrand without edits.

This is the single habit that separates a product that ages well from one that drifts. The components make it the easy habit, because the tokens are already wired underneath them.

Keep the skin, or replace itThe behaviour is headless underneath: focus, keyboard, and accessibility are solved in the core. Keep the default skin and you move fast. Replace it for a second brand and the behaviour still holds. You never trade one for the other.

Compose upward

Real product UI is not single components; it is compositions. A pricing card is a Card plus a Button plus tokens. A data view is a Table with cell renderers. Build your product-specific pieces by composing the primitives, and keep those compositions in your own layer.

When you do, upgrades stay clean: the primitives improve underneath, and your compositions inherit the improvement without a rewrite.

Upgrade without fear

Owning the code does not mean freezing it. When a component improves upstream, you pull the change into files you can read and diff, so an upgrade is a review rather than a leap of faith. You see exactly what moved before it ships.

Because your product-specific pieces are compositions on top of the primitives, they rarely need to change when the primitives do. The improvement lands underneath them and they inherit it for free.

The right thing should be the least work. Everything else is just discipline you should not need.On adoption