nsdev/ui

Own every pixel of your design system.

nsdev/ui is a component library built on Base UI and styled with Tailwind CSS. Base UI supplies the behavior and accessibility; this project supplies the look, with a small set of theme tokens you can change.

Live site: ui.nsdev.me

What is in it

Section	What you find there
Doc	Introduction, theming, typography and a changelog.
Components	The primitives: buttons, fields, dialogs, menus, text effects and more. Each page has a live demo with its source underneath, and notes on the thinking, the interface design, the interaction and the accessibility.
Blocks	Sections of a page built from components, such as a navigation menu. Each is previewed in a Desktop, Tablet or Mobile frame, with its code and the components it needs.
Pages	Full page templates built from blocks. Not built yet.
Dashboard	Full application screens. Not built yet.

Nothing is shown twice by hand. The code on every page is read from the real source file when the site is built, so what you read is what renders.

Tech stack

• Next.js 16 (App Router), fully static, pre-rendered at build time
• React 19 and TypeScript
• Base UI (@base-ui/react) for the unstyled primitives
• Tailwind CSS v4, configured in CSS (the tokens live in an @theme block in src/app/globals.css)
• Shiki for syntax highlighting, run on the server
• lucide-react for icons

There is no backend and no database.

Getting started

You need Node.js 20.9 or newer.

npm install
npm run dev

Then open http://localhost:3000.

Command	What it does
npm run dev	Starts the development server.
npm run build	Builds the site for production.
npm run start	Serves the production build.
npm run lint	Runs ESLint.

Project structure

content/
  components/<slug>/     meta.ts + demo.tsx for each component
  blocks/<slug>/         meta.ts + demo.tsx for each block
public/assets/images/    logos, avatars and pictures used by the demos
src/
  app/                   the pages (docs, components, blocks, previews)
  components/            the site itself: header, menus, code panels, viewers
  components/ui/         the library: one file per component
  lib/                   shared helpers (class names, styles, menus, scramble effect)
design.md                the design tokens: colors, type, radius, overlays

Adding a component

1. Write the component in src/components/ui/<slug>.tsx.
2. Create content/components/<slug>/meta.ts and demo.tsx.
3. Add the page in src/app/components/<slug>/page.tsx, using ComponentPage.
4. List its meta in content/components/index.ts.

The menu and the index are generated from that list, A to Z, in the group named by the component's meta.group.

Adding a block

1. Create content/blocks/<slug>/meta.ts and demo.tsx.
2. Import both in content/blocks/index.ts and add { meta, Component: Demo } to the list.

The page, its menu entry, its preview frame and its Prerequisites list are generated. The list is read from the block's own imports, so it always matches the code. A block's section in the menu is set in content/blocks/groups.ts.

Design

Colors, typography, radius and the shared rules for overlays are documented in design.md. Use the Tailwind utilities generated from the theme (bg-bg, text-accent, border-border, rounded-md) and avoid raw values, so one token change restyles everything.

Contributing

Work goes through branches and pull requests.

• Never commit directly to main. Cut a branch named type/short-description, where the type is feat, docs, fix or chore.
• One concern per commit, with a short imperative message ("Add Button states").
• Open a pull request and squash-merge it.
• A change to the library (a component, a block or a token) adds an entry to the changelog in the same branch.

Project notes for contributors and AI assistants are in CLAUDE.md and AGENTS.md.

Distribution

How to consume the library, as an npm package or by copying files (a registry in the style of shadcn/ui), has not been decided yet. For now the components are meant to be read and copied from the site.

Deployment

The site is hosted on Vercel and deploys automatically on every push to main. ui.nsdev.me is a CNAME on Cloudflare pointing at Vercel (DNS only, not proxied).

Author

Built by Njoh Simplice Junior.