Nim UI

"I don't understand what I can't create".

Open-source component ecosystem by nimjs for teams that want more than a UI library: design tokens, typed component registry, CLI scaffolding, system-first docs, and release discipline in one production-ready monorepo.

Nim UI is inspired by the developer experience standards of modern component systems, but it is designed as an independent OSS product with explicit package boundaries, contributor-safe public APIs, and maintainable release mechanics.

Why Nim UI

• Build and document UI primitives from the same system source of truth.
• Keep tokens, docs, CLI, and components aligned through typed metadata.
• Scale from a starter kit to an organization-owned design system foundation.
• Give contributors clear package boundaries and maintainers clear release rules.
• Stay portable: no private infrastructure assumptions, no vendor-locked repo architecture.

What You Get

• @nim-ui/tokens Design tokens, semantic themes, and CSS variables.
• @nim-ui/registry Typed component manifests shared by CLI and docs.
• @nim-ui/ui React component package with explicit public exports.
• @nim-ui/utils Shared helpers such as cn() and small DOM-safe utilities.
• @nim-ui/cli Registry-driven scaffolding foundation for init and add.
• @nim-ui/docs Next.js App Router docs and demo app.
• OSS baseline Changesets, CI/CD, governance, security policy, CODEOWNERS, templates, and Dependabot.

Architecture

apps/
  docs/                  Next.js docs and demo application
packages/
  cli/                   Registry-aware CLI foundation
  eslint-config/         Shared ESLint flat configs
  registry/              Typed component manifests
  tokens/                Design tokens and semantic theme mappings
  tsconfig/              Shared strict TypeScript presets
  ui/                    React component package
  utils/                 Shared utility helpers
tooling/                 Repo-level setup and support files
.changeset/              Versioning and release notes
.github/                 CI/CD workflows and contribution automation

System Flow

Nim UI is structured as a system, not a gallery of unrelated packages.

1. Tokens are defined in @nim-ui/tokens.
2. Tokens map to semantic CSS variables consumed by UI components.
3. Components are described in @nim-ui/registry.
4. The CLI reads the registry to scaffold component files.
5. Docs read the same registry metadata to explain tokens, dependencies, and usage.

That pipeline keeps implementation, documentation, and scaffolding aligned as the ecosystem grows.

Design Tokens And Theming

The theme layer is built around semantic CSS variables such as:

• --background
• --foreground
• --card
• --border
• --primary
• --primary-foreground
• --accent
• --ring
• --destructive

The current baseline ships with a light theme and a CSS variable architecture ready for dark-theme expansion. UI code should consume semantic variables, not raw color literals.

Relevant sources:

• packages/tokens/src/colors.ts
• packages/tokens/src/themes/light.ts
• packages/tokens/src/css/variables.css

Component Registry

The registry package is the ecosystem contract between implementation, docs, and CLI.

Each component manifest declares:

• component name
• source files
• system dependencies
• semantic tokens
• category
• description

Example:

{
  "name": "button",
  "files": ["button.tsx"],
  "dependencies": ["utils", "tokens"],
  "tokens": ["primary", "primary-foreground", "ring", "radius"],
  "category": "ui",
  "description": "Primary action trigger"
}

This gives maintainers one place to evolve component metadata without teaching docs and CLI different models.

CLI Foundation

The CLI is intentionally small but production-oriented.

Current capabilities:

• init
• add <component>
• nim-ui.config.ts resolution with sensible defaults
• registry-driven template lookup
• basic dependency reporting
• friendly validation and error messages

Default config:

export default {
  componentsDir: "src/components/ui",
  tokens: true,
};

The current design is ready for future registry fetches, adapters, and canary channels without rewriting package boundaries.

Docs Experience

The docs app is a product surface, not a sidecar demo.

It includes:

• landing page
• getting started docs
• installation guide
• theming guide
• components index
• dedicated component pages
• demo/code blocks
• registry-backed metadata for tokens and dependencies

Each component page exports typed metadata so the docs system can grow toward auto-generated sections without losing author control.

Public API Discipline

Nim UI follows explicit exports by default.

• No export * from package roots.
• No accidental deep internal exports.
• Subpath exports are intentional and tree-shaking friendly.
• Public API changes should be additive unless explicitly approved otherwise.

This helps maintainers keep package contracts stable as the ecosystem grows.

Getting Started

Requirements:

• Node.js 20.11+
• pnpm 9.15.4

Install dependencies:

pnpm install

Start the docs app in development:

pnpm dev

Useful workspace commands:

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm changeset

Development Workflows

Add A New Component

1. Create packages/ui/src/components/<component>/.
2. Export the component explicitly from packages/ui/src/index.ts.
3. Add a subpath export in packages/ui/package.json if needed.
4. Add a registry manifest in packages/registry/components/.
5. Add or update docs content in apps/docs/content/components/.
6. Add tests when behavior or accessibility are non-trivial.
7. Add a changeset for user-facing package changes.

Validate The Repo

pnpm turbo run lint typecheck test build

This is the same baseline validated by the main CI workflow.

Release Flow

Releases are managed with Changesets.

1. Contributors add a changeset for user-facing package changes.
2. Changes land on main.
3. The release workflow creates or updates a release PR.
4. Merging the release PR versions packages and publishes to npm.

Before the very first publish, make sure the npm scope exists and provide an automation token as NPM_TOKEN. npm trusted publishing can take over after the packages already exist on npm and each package has a trusted publisher configured.

Why this model works well for OSS:

• release intent is reviewed in git
• breaking changes stay explicit
• maintainers avoid ad hoc local publishing
• multi-package versioning stays understandable to contributors

Canary Releases

Canary publishing is not enabled by default, but the repository is ready for it through Changesets pre mode.

Recommended canary flow:

pnpm changeset pre enter canary
pnpm version-packages
pnpm release --tag canary
pnpm changeset pre exit

CI And Deployment

GitHub Actions cover:

• repository validation
• docs build validation
• release automation
• dependency review
• CodeQL analysis

The docs app is Vercel-friendly by default. The repository validates docs builds in CI without hard-coupling deployment to a provider-specific preview setup.

Open-Source Governance

Nim UI is structured for public maintenance from the start.

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md
• GOVERNANCE.md

These files are part of the product surface. They define how contributors work in the repo, how maintainers make decisions, and how releases stay safe.

Who This Repo Is For

• teams building an OSS or internal design system foundation
• maintainers who want docs, tokens, and release flow designed up front
• contributors who prefer explicit architecture over hidden repo conventions
• product organizations that need a scalable component ecosystem, not just components

Roadmap Direction

Near-term evolution paths that fit the current architecture:

• richer registry metadata for layouts, forms, and patterns
• remote registry distribution for CLI consumers
• more generated docs sections from typed component metadata
• canary release automation
• broader component coverage with stable public export discipline

Contributing

Start with CONTRIBUTING.md. For architectural or cross-package changes, also read GOVERNANCE.md before opening large pull requests.

License

MIT