UI primitives with clean ownership.

Wensity UI primitives are foundational React controls for forms, selection, feedback, navigation, and layout. They live under /primitives so search engines, users, and the command palette all resolve each primitive to one canonical detail route.

Use this guide when you want Button, Input, Toggle, Dialog, Breadcrumb, Table, or any other primitive as source in your app. For larger composed UI, keep using the Components guide.

What primitives are

Foundation layer

Primitives are the small controls and layout pieces that larger Wensity components depend on.

Same source model

A primitive installs as a local .tsx file through the same Wensity registry contract as components.

Canonical catalog

The public catalog is /primitives, and each detail page uses /primitives/<slug>.

Owned in your repo

After install, the primitive is application code. Your formatter, linter, and git diff own the change.

Canonical routes

Primitive detail pages should be linked as /primitives/<slug>. Do not link primitive details through /components/<slug>, because the primitive route owns the canonical metadata, Open Graph URL, sitemap entry, and structured data.

One primitive, one public detail route

Use /primitives/button for the Button primitive, /primitives/input for the Input primitive, and /docs/primitives for the install workflow. Keep /components focused on composed product UI.

Install with CLI

Run wensity init once in your project, then add a primitive by slug.

terminal

$npx wensity init

terminal

$npx wensity add button

The CLI reads wensity.json, writes source into your configured components path, adds helper files when needed, rewrites internal imports to your aliases, and installs declared package dependencies.

app/page.tsx

1import { Button } from "@/components/wensity/button";
2
3export default function Page() {
4return (
5  <main className="grid min-h-screen place-items-center">
6    <Button>Continue</Button>
7  </main>
8);
9}

shadcn registry

Free primitives can also be installed through the public shadcn registry namespace.

terminal

$npx shadcn@latest add @wensity/button

Use the Wensity CLI when you want the full Wensity config flow. Use shadcn when you already run a shadcn registry workflow and only need a quick free primitive add.

Manual source

The Code tab on each primitive detail page includes the install command, dependencies, full source, and usage snippet. Manual source is best for review. The CLI is better for repeatable team installs because it follows wensity.json and keeps helper paths consistent.

Theming

Primitives read the same Tailwind v4 tokens as Wensity components. Set the surface, border, foreground, muted foreground, and chili brand tokens once in your global CSS. Every primitive will inherit the same visual system.

Theme primitives and components together

Do not maintain a second primitive theme. Use the shared Wensity tokens from the Theming guide so Button, Input, Dialog, and larger components stay visually aligned.