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:
- Read ARCHITECTURE.md to understand the codebase layout.
- Read CONTRIBUTING.md for guidelines on code style, PR process, and conventions.
- Test your changes in
apps/dev — use ComponentsCheckPage.tsx to visually verify components.
- 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.
