Loui DS

A dark, minimal, functional React design system for internal tools, dashboards and apps. Design tokens, accessible components built on React Aria Components, and AI-ready documentation, in one package: loui-ds.

Live Storybook: https://xrazai.github.io/loUI/ · For AI agents: llms.txt, llms-full.txt, manifest.json, tokens.json

Status: pre-1.0, published on npm under the MIT license. All components are experimental; APIs can still change.

Highlights

• Accessible by default. WCAG 2.2 AA target, keyboard contracts, axe on every story.
• Tokens first. Every color, space, radius and duration is a --ds-* CSS variable built from DTCG JSON. No raw values in components.
• React 19, SSR-safe, CSS Modules in named cascade layers, no runtime styling library.
• i18n built in. English by default, pt-BR included, every string overridable through DSProvider.
• Made for agents too. A generated component manifest, token manifest and llms.txt keep AI tools exact.

Install

pnpm add loui-ds react react-dom

npm install loui-ds and yarn add loui-ds work too. To upgrade, run pnpm update loui-ds and read the release notes first: before 1.0 a minor version may break. Every release also attaches the package tarball, if you need to install a version by URL.

Requires React 19 and Node 24 or later for tooling.

Quick start

import 'loui-ds/styles.css';
import { Alert, Button, DSProvider } from 'loui-ds';

export function App() {
  return (
    <DSProvider locale="en-US">
      <Alert tone="warning" title="Low stock">
        3 rolls of linen are left. Reorder to avoid delays.
      </Alert>
      <Button variant="primary" onPress={() => console.log('created')}>
        Create order
      </Button>
    </DSProvider>
  );
}

More in Getting started: the stylesheet, DSProvider, fonts, theming and server-side rendering.

Documentation

For AI tools

Generated, always in sync with the source, committed under docs/ and shipped in dist/:

• docs/llms.txt and docs/llms-full.txt: index and full documentation.
• docs/manifest.json: every component, hook and utility with props, variants, messages, stories and usage notes.
• docs/tokens.json: every token with allowed text and surface pairings.
• docs/ai/content-rules.json: microcopy rules as data.
• docs/ai/components/: one Markdown page per component.

Quick start (Windows)

Double-click start.cmd in the repo root (or run it from a terminal). It installs pnpm and the dependencies if they are missing, starts Storybook and opens http://localhost:6006 in your browser. On any OS, pnpm install then pnpm start does the same.

Scripts

Contributing

Read AGENTS.md first: it is the single source of truth for conventions. Work comes from TODO.md; finished work is recorded in CHANGELOG.md. Components follow the component workflow. Commits follow Conventional Commits. Everything in this repository is written in English.

After adding or changing a component, regenerate the AI-facing documentation and commit it:

pnpm manifest:build

Project layout

src/
  components/<Name>/   component, CSS Module, messages, stories, tests, <Name>.md
  tokens/              DTCG JSON sources and generated output
  styles/              layered base CSS and fonts
  hooks/ utils/ i18n/  hooks, locale-aware utilities, message catalogs
  docs/                Storybook guide pages
  patterns/            domain patterns (second entry point)
docs/                  guides, ADRs, architecture notes, generated AI docs
schemas/               JSON Schemas for the manifests and content rules
scripts/               token and manifest tooling

License

MIT. The bundled Geist fonts are under the SIL Open Font License (src/styles/fonts/LICENSE.txt).