Once UI

The open-source, agentic design system for React

Documentation

Learn how to set up and build with Once UI at docs.once-ui.com.

Installation

npm install @once-ui-system/core

Upgrading

Coming from 1.8.x? See MIGRATING.md — a codemod does most of it, and the rest is six short steps.

Getting started

git clone https://github.com/once-ui-system/core.git
cd core
pnpm install
pnpm dev

This boots both apps in parallel via Turborepo:

• Docs → http://localhost:3000
• Dev sandbox → http://localhost:3001

Note: pnpm install automatically builds the core library via a postinstall hook, so no separate build step is needed after initial setup.

Project structure

This is a pnpm monorepo with Turborepo. See ARCHITECTURE.md for the full directory layout, conventions, and where to contribute.

core/
├── packages/core/     # @once-ui-system/core — the design system library
├── apps/dev/          # Next.js 16 sandbox for component development
└── apps/docs/         # Next.js 16 documentation site

Scripts

Command	Description
pnpm dev	Start all dev servers in parallel (docs → :3000, dev → :3001, core watch)
pnpm build	Build everything (library + apps)
pnpm test	Run all tests via Turbo
pnpm lint	Lint everything via Turbo
pnpm typecheck	Typecheck everything in parallel
pnpm format	Format all files
pnpm clean	Clean all build artifacts
pnpm start	Start all built apps (docs → :3000, dev → :3001)

Individual workspace commands:

Command	Description
pnpm dev:docs	Docs app only → http://localhost:3000
pnpm dev:dev	Dev sandbox only → http://localhost:3001
pnpm build:core	Build just the library
pnpm test:core	Run core tests only
pnpm lint:core	Lint core only
pnpm start:docs	Start built docs app only
pnpm start:dev	Start built dev app only

AI codegen harness

The library ships an AI codegen harness in packages/core/ai/ — a manifest, task bundles, component slices, and validation scripts. This powers the Freebuff integration and enables AI agents to generate Once UI code correctly. See AI Coding docs for details.

Authors

Built and maintained by Lorant One.

Community

Join the Design Engineers Club for help, support and discussion.

Found a bug? Report it here. Got a feature request? Submit it here.

Contributing

We welcome contributions! Before submitting a PR:

1. Read ARCHITECTURE.md to understand the codebase layout.
2. Read CONTRIBUTING.md for guidelines on code style, PR process, and conventions.
3. Test your changes in apps/dev — use ComponentsCheckPage.tsx to visually verify components.
4. Run pnpm test before submitting.

Where to start:

• Fix or add a component → packages/core/src/components/
• Fix a complex module (CodeBlock, etc.) → packages/core/src/modules/
• Update docs → apps/docs/src/content/once-ui/
• Change design tokens → packages/core/src/tokens/

Sponsors

Once UI is an indie project, kept going by the companies and people who use it.

Company sponsors

Founding and Ecosystem sponsors get their logo here.

Tier	Price	Where your logo runs
Founding	$2,000 / month	This README, the documentation site and once-ui.com/sponsors; named in every release; a standing line to the team
Ecosystem	$750 / month	This README and once-ui.com/sponsors; named in every release for the term
Supporter	$250 / month	once-ui.com/sponsors; named in the quarter's release notes

See once-ui.com/sponsors for the details, or get in touch through the form there.

Individual sponsors

Individuals can sponsor us through GitHub Sponsors or thanks.dev and get featured on our site.