Skip to content
loseta

Getting started

Theming

Components read semantic CSS custom properties. Override tokens to change the look without editing component CSS. Geometry and spacing come from a style; seeStyles.

Layers

The generated index.css declares the layer order. Keep it before your own layers so component styles can be overridden deliberately.

css
@layer loseta.tokens, loseta.reset, loseta.base, loseta.components, loseta.style, loseta.utilities;

Token convention

Most tokens come in pairs: a surface and the foreground that sits on it. The surface token has no suffix; its text and icon color adds -foreground.

css
:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

A component that sets background-color: var(--primary) pairs it withcolor: var(--primary-foreground).

Color roles

  • --background / --foreground — page surface and primary text.
  • --card / --card-foreground — cards and alerts.
  • --popover / --popover-foreground — dialogs, popovers, menus and tooltips.
  • --primary / --primary-foreground — primary actions and checked controls.
  • --secondary / --secondary-foreground — secondary actions and badges.
  • --muted / --muted-foreground — subdued surfaces, descriptions and secondary text.
  • --accent / --accent-foreground — highlighted and focused menu items.
  • --destructive — destructive actions, invalid borders and invalid text.
  • --border — separators, outlines and outline-variant borders.
  • --input — form-control borders and subtle control fills in the dark scheme.
  • --ring — focus border and focus shadow.

--chart-*, --sidebar-* and --scrollbar-* are consumed by the chart, sidebar and scroll area components. The families stay stable across styles.

Radius

--radius is the base value; the scale multiplies it. Styles may cap the radius of small controls so they stay visually consistent.

  • --radius-sm: 0.6 × --radius.
  • --radius-md: 0.8 × --radius.
  • --radius-lg: --radius.
  • --radius-xl: 1.4 × --radius.
  • --radius-2xl to --radius-4xl: 1.8 × to2.6 × --radius.
  • --radius-full: fully rounded.

Adding tokens

Define a new color as a light-dark() pair under :root, then use it from the files you own.

css
:root {
  --warning: light-dark(oklch(0.84 0.16 84), oklch(0.41 0.11 46));
  --warning-foreground: light-dark(oklch(0.28 0.07 46), oklch(0.99 0.02 95));
}

Color scheme

Without a forced scheme, components follow prefers-color-scheme. The token file sets color-scheme: light dark, so native controls follow the OS too. No JavaScript is required.

Add .dark or .light to force a scheme. The classes work on<html> or on any container, so a section can use a different scheme from the page.

html
<html class="dark">...</html>

<section class="light">
  <p>This section stays light when the page is dark.</p>
</section>

A forced scheme is still a color-scheme change, not a separate palette: custom tokens should be defined with light-dark() so they respond to both the OS and the override classes.

Data-URI tokens are the one exception: light-dark() only accepts colors, so icon URLs switch through .dark / .light and aprefers-color-scheme query instead.

Styles

Nova is the default style. A style changes geometry, spacing, control sizes, radii and the type scale; it does not change tokens or markup. Styleslists every shipped style and how to switch.

Direction

Direction is a native HTML concern, not a component. Set dir="rtl" on<html> or on any container. The reset and every component use logical properties, so margins, padding, borders and placement follow the nearest direction without extra classes.

html
<html lang="ar" dir="rtl">...</html>

<section dir="rtl">
  <p>This section flows right to left.</p>
</section>

The placement attributes data-side="inline-start|inline-end" follow the container direction. The one physical exception is the context menu position, which uses --context-x and --context-y because it follows the pointer.

No direction item. shadcn's Direction maps to the nativedir attribute. There is nothing to install and no JavaScript provider.

Public style contract

Components expose variants, sizes and states through data attributes and ARIA. The most common hooks are:

  • data-variant and data-size for visual variants.
  • data-orientation, data-spacing and data-fitfor layout-specific presentation. data-align="start|end" places messages and standalone bubbles.
  • data-slot="title|description|action|header|footer|avatar|content|media|actions|trigger|reactions|reaction|icon|shortcut|indicator|fallback|badge|ellipsis|text|label|status|body|source|progress|progress-label|choices|item|error|skip|jump|handle|addon|empty|clear|plot|legend|legend-item|swatch|tooltip|brand|close"for parts.
  • :focus-within for the input-group focus ring.
  • aria-invalid="true" for invalid controls.
  • aria-busy="true" for an attachment or trace that is still working.
  • aria-selected="true" for tabs, options, calendar cells and selectable rows.
  • aria-multiselectable="true" for a multiple listbox.
  • aria-checked="true" for checkable menu items.
  • aria-pressed="true" for toggle buttons and message reactions.
  • aria-current="page" for the active breadcrumb or pagination item.
  • aria-current="date" for today in a calendar.
  • aria-current="step" for the active questionnaire step.
  • aria-valuenow, aria-valuemin and aria-valuemax for resizable separators.
  • data-highlighted for the highlighted menu or listbox item.
  • :disabled and aria-disabled="true" for disabled states.
  • [open] on <details> and inert for accordion state.
  • :indeterminate for progress without a value.
No prefixes. Classes and tokens are intentionally unprefixed to match shadcn/ui and the source nomenclature. Use one design system per project to avoid collisions.

loseta is MIT licensed. Built with native CSS, no runtime. Inspired byshadcn/ui.