Modern front-end development demands more than just getting things to work — it requires systems that scale, components that compose, and designs that adapt across products and teams. SonoJS is built to satisfy all three without forcing a rigid architecture on your app.

This guide walks through the practical path from a fresh project to a production UI: setup, tokens, layout, accessibility, and a checklist you can reuse on every release. Keep this page open while you scroll — the chapter rail on the side tracks where you are.

If you are evaluating component kits, focus on install ergonomics, token ownership, and direction support. Those three decide whether a library survives the second product, not the first demo.

The fastest way to start is with the SonoJS CLI. Run npx @sonojs/ui@latest init and follow the prompts for your framework, theme tokens, and TypeScript setup. The CLI writes a components map, CSS entry, and baseline dependencies so add commands land in the right folders.

After init, add only the primitives you need. Prefer small increments — button, then field, then dialog — so review stays readable. Each add installs registry dependencies recursively and runs npm for missing packages.

Pin versions when a major would break APIs. DayPicker-style ranges are a good example: declare the major your source expects so consumers do not silently upgrade into a broken UI.

Style with tokens like bg-primary and text-foreground. Because these map to CSS custom properties backed by oklch values, dark mode is zero-effort once the theme sheet is in place.

Keep brand color decisions in the theme file, not scattered across components. Heights, radius, and spacing should follow the control scale so docs previews and installed apps stay visually aligned.

When you need a one-off surface, derive it from existing tokens with color-mix rather than inventing a new hex. That keeps contrast tooling and theme switches honest.

Prefer logical layout utilities so grids and stacks adapt without physical left/right assumptions. Use ms/me, ps/pe, and start/end so RTL and LTR inherit direction from the document.

Keep control heights consistent across breakpoints. Responsive work should change width, stacking, and gutters — not shrink buttons below the default control height.

For sticky chrome like this chapter rail, make sure the reading column is tall enough that sticky has room to travel. Short demos make progress and active states flicker.

Interactive components ship with correct ARIA attributes, keyboard navigation, and focus management. Overlays handle focus trapping and restore focus on close.

Reading chrome should expose progress to assistive tech with a real progressbar role and live values. Chapter links need clear labels and visible focus rings.

Test with keyboard only once per release. If you cannot reach every control and see where focus is, the page is not ready — no matter how polished the visual design looks.

Before shipping: run typecheck, verify the production build, and test at 375px, 768px, and 1280px. Check light and dark modes and confirm focus rings stay visible on primary and muted surfaces.

Spot-check direction with both LTR and RTL providers. Directional icons should flip; brand marks and avatars should not. Sticky sidebars and progress bars must remain usable in both directions.

Finally, scroll this article end-to-end once. The chapter rail should settle on one active item at a time, the progress bar should climb smoothly, and nothing in the side chrome should jitter as sections pass the reading line.