YoltraYoltra
TSPyDS
Docs

Quick Start

The Yoltra Design System (@yoltra/ds) is the token set, semantic light/dark themes, and React components behind this site, its docs, and the examples. It is plain React (18 or 19), server-first, and themed entirely through a single data-theme attribute.

#Install

bash
npm install @yoltra/ds

#Add the styles

DS 0.2.0 ships styles as files. Two sheets are always required — the design tokens and the base layer — and each component's styles are opt-in, so an app carries CSS for what it renders and nothing else:

ts
import "@yoltra/ds/styles/tokens.css"; // the --yl-* custom properties (both themes)
import "@yoltra/ds/styles/base.css";   // the 10px root, .yl-root, .yl-container
import "@yoltra/ds/styles/button.css"; // one per component you render
import "@yoltra/ds/styles/callout.css";

Prototyping, or building a docs site where the trade-off isn't worth making? Import everything in one line:

ts
import "@yoltra/ds/styles/all.css";

The full model — the 10px root, per-component vs. bundle, and inlining the variables for a server render — is covered in Styling & Theming.

#Use a component

Primitives are server-safe: they render in a React Server Component with no provider, because every color resolves through a CSS variable.

tsx
import { Button, Callout, Stack } from "@yoltra/ds";

export function Example() {
  return (
    <Stack gap={4}>
      <Callout kind="info">Fine-grained, event-sourced state for React.</Callout>
      <Button onClick={() => console.log("hi")}>Get started</Button>
    </Stack>
  );
}

Interactive components — the theme controller, Tabs, CodeBlock, and the whole overlay tier — live behind the @yoltra/ds/client entry, which ships a real "use client" directive:

tsx
import { Dialog } from "@yoltra/ds/client";

#Theming is one attribute

Set data-theme on the document root and every color follows:

html
<html data-theme="dark"> … </html>

Each color is a custom property redefined under [data-theme="dark"], so switching themes is a single attribute write — no React re-render. Use the built-in ThemeProvider / useTheme, call applyTheme("dark") directly, or — as this site does — drive data-theme from your own store.

#What's next