Skip to content
nessalabsPublic

About

Design System on top of Shadcn for AI components.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

136 Commits

Folders and files

Repository files navigation

Nessa UI

Nessa UI is the open design system for Nessa products. It builds on the shadcn/ui source model and provides two ways to adopt the same components:

  • install @nessalabs/ui as a conventional React package;
  • copy owned source into an application through the @nessa shadcn registry.

Storybook is the visual workshop and living component documentation.

The state atlas maps every public feature family, explains host ownership and cancellation boundaries, and links actual verification evidence.

Architecture contract

All future component, theming, packaging, registry, documentation, and tooling work is governed by the Nessa Design System Core Contract. Implementation plans sequence changes but cannot silently override that contract; amendments require explicit architecture review.

Workspace

apps/storybook    visual workshop, stories, and accessibility tests
packages/react    components, tokens, and package entrypoints
public/r          generated shadcn registry artifacts
registry.json     public registry catalog
docs/architecture permanent design-system contracts
skills            task-shaped guides for agents working in this repo

Start Storybook

The workspace requires Node.js 22.13 or newer and pnpm 11.9.0.

./start.sh

Then open http://localhost:6006.

start.sh verifies the repository's Node and pnpm versions, reconciles workspace dependencies against the frozen lockfile, and starts Storybook. Override its address with NESSA_STORYBOOK_HOST or NESSA_STORYBOOK_PORT.

Consume the package

The repository uses pnpm, while consumers can use their package manager of choice:

pnpm add @nessalabs/ui @fontsource-variable/geist @fontsource-variable/geist-mono
npm install @nessalabs/ui @fontsource-variable/geist @fontsource-variable/geist-mono
yarn add @nessalabs/ui @fontsource-variable/geist @fontsource-variable/geist-mono
bun add @nessalabs/ui @fontsource-variable/geist @fontsource-variable/geist-mono
import { Button } from "@nessalabs/ui"
import "@fontsource-variable/geist"
import "@fontsource-variable/geist-mono"
import "@nessalabs/ui/styles.css"

export function Example() {
  return <Button>Continue</Button>
}

The default stylesheet includes Nessa tokens and component utilities without resetting the host application. Import it before the application's stylesheet; Nessa's named cascade layer lets host Tailwind utilities remain authoritative. Nessa-owned applications can opt into Tailwind Preflight and global body defaults with @nessalabs/ui/app.css. A token-only entry is available at @nessalabs/ui/theme.css.

Package consumers customize the system by overriding semantic variables after the Nessa import. Registry consumers own the copied variables directly:

:root {
  --primary: oklch(0.45 0.2 260);
  --primary-foreground: oklch(0.985 0 0);
  --ring: oklch(0.55 0.17 260);
}

Consume the registry

Because this is a public GitHub registry, a project can install a component and its Nessa base directly from the repository in one command:

pnpm dlx shadcn@latest add nessalabs/nessa_ui/button

shadcn add also installs the shared files a component imports. Copying a component's file by hand does not: bring along every item in its registryDependencies too. Components that measure themselves — the charts, WindowDeck, the composers, SegmentedControl, Table and others — import @/lib/size-observer, and without it the copied file fails to resolve that import.

Generate static JSON artifacts for registry hosting or inspection:

pnpm build:registry

Commands

Command Purpose
./start.sh Verify the toolchain and start the Storybook workshop
pnpm storybook Start the visual workshop
pnpm build Build the React package and compiled theme CSS
pnpm build:storybook Produce the static Storybook site
pnpm build:registry Generate installable shadcn registry JSON
pnpm test Run Storybook render and accessibility checks in Chromium
pnpm typecheck Type-check every workspace package
pnpm validate Run the fast, read-only design-contract source gate
pnpm validate:full Run the complete review/CI artifact and contract gate

Validation details, focused commands, and performance guarantees live in validation/README.md.

Contributor setup, protected-main practices, and the explicitly authorized worktree workflow live in CONTRIBUTING.md. Agents must also follow AGENTS.md.

Naming

  • Brand: Nessa UI
  • npm: @nessalabs/ui
  • shadcn registry namespace: @nessa
  • repository: nessalabs/nessa_ui

License

MIT © 2026 nessalabs

About

Design System on top of Shadcn for AI components.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages