The indie design system for Next.js apps

Documentation

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

Installation

npm install @once-ui-system/core

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. Individuals can sponsor us through GitHub Sponsors and get featured on our site.

Companies can partner with us through dedicated sponsor tiers — logo placement, recognition on ecosystem releases, and top-tier partnership options. See once-ui.com/support for tiers and benefits, or reach out through the site to talk it through.