DeesseJS UI

The official component registry for DeesseJS.com. Real components, live preview, source shown verbatim.

View live site →     Browse source →

---

What's in this repo

Path	Role	Notes
apps/web/	Showcase site	Next.js 16, deployed at ui.deessejs.com
packages/registry/	Component library	Real .tsx components, each with index.tsx + meta.ts
packages/ui/	shadcn primitives	Base UI (not Radix) + Tailwind v4 tokens
learnings/	Design research	The anti-slop thesis behind the design system

Why this registry

• Real components, not wrappers. Each component lives as a real .tsx file. The registry ships actual code you can copy.
• Source shown verbatim. The "Code" tab on every detail page is the real file content, extracted via fs.readFileSync — not generated stubs.
• Live preview, not screenshots. Each component renders in the page, so you see what it actually does, not a mock.
• Themable by tokens. Every color, every gap follows the design system. No raw palette utilities escape into the registry.
• Designed for AI agents. Components are real, discoverable, and copyable — no abstractions to fight through.

Install

Any developer can copy a component into their own shadcn project:

# GitHub registry (no setup, reads from this public repo)
npx shadcn@latest add deessejs/ui/ds-button

# URL (works against the deployed showcase site)
npx shadcn@latest add https://ui.deessejs.com/r/ds-button.json

# Namespace (one-time setup, then any item by short name)
npx shadcn@latest registry add @deessejs=https://ui.deessejs.com/r/{name}.json
npx shadcn@latest add @deessejs/ds-button

All three commands land the same ds-button.tsx in the consumer's components/ui/, with peer dependencies installed automatically.

Available components

Component	Type	Description
ds-button	registry:ui	Button primitive — Base UI on shadcn base-nova tokens, with variant and size styles.
ds-icon-button	registry:ui	Icon-only button — sm / md / lg size variants, requires aria-label.
ds-colored-badge	registry:ui	Inline badge with semantic color variants. Self-contained — no Base UI dependency.

Each item declares its npm peer dependencies in registry.json. Browse the catalog at https://ui.deessejs.com or the full index at /r/registry.json. See Adding a component to publish your own.

Adding a component

1. Create packages/registry/src/components/<id>/ with two files:
   • index.tsx — exports the component plus a Demo function
   • meta.ts — ComponentMeta { id, name, description, category, variants? }
2. Register in apps/web/lib/registry/:
   • Import the component and Demo in index.ts
   • Add the fs.readFileSync source in sources.ts
   • Append to COMPONENT_REGISTRY
3. Run npm run typecheck to confirm the build still passes.
4. Push. The registry re-deploys with the new component on the next Vercel build.

Tip

The Demo export renders the component in the preview tab. Keep it self-contained — no external state, no providers.

Project structure

.
├── apps/
│   └── web/                Next.js 16 showcase site (serves /r/* registry JSON)
│       ├── scripts/build-registry.mjs   Emits items to public/r/
│       └── public/r/                    Generated registry JSON (committed)
├── packages/
│   ├── registry/           @workspace/registry — the deessejs component library
│   │   └── src/components/  One folder per component (index.tsx + meta.ts)
│   ├── ui/                 @workspace/ui — shadcn primitives (Base UI)
│   ├── eslint-config/      Shared ESLint config
│   └── typescript-config/  Shared TypeScript configs
├── registry/
│   └── base-nova/          Hand-curated consumer-facing sources (ships to users)
│       └── ds-button/      One folder per distributable item
├── registry.json           Catalog at repo root (read by the GitHub registry CLI)
├── docs/
│   ├── product/            This README lives here
│   ├── learnings/          Design research (anti-slop thesis)
│   └── plans/              Implementation plans
├── .github/workflows/ci.yml         Registry validate + lint + typecheck + build
├── turbo.json              Monorepo task graph
└── package.json            Workspaces: apps/*, packages/*

Architecture notes

• shadcn on Base UI, not Radix. We import from @workspace/ui/components/* which uses @base-ui/react/* primitives. All shadcn components (Tabs, Breadcrumb, Empty, etc.) follow this.
• Source extraction via fs.readFileSync. The Code tab pulls content from packages/registry/src/**/*.tsx at module load. Earlier attempts with ?raw imports failed in the Next.js + Turbopack + workspaces context.
• Dual-theme syntax highlighting. Shiki emits --shiki-light and --shiki-dark CSS variables per token. globals.css switches based on the .dark class. Zero client JS for theme switching.
• Registry seam for the future DB. apps/web/lib/registry/index.ts is the single entry point. When components move to a database, only this file changes — pages don't.

Contributing

Open an issue to discuss larger changes. For typos, broken links, and small fixes, PRs are welcome.

To add a new component to the registry, follow registry/CONTRIBUTING.md — it covers file layout, registry.json schema, the build pipeline, and the local validation loop.

License

MIT. See the LICENSE file for details.

Support

• Issues: github.com/deessejs/ui/issues
• Discussions: github.com/deessejs/ui/discussions
• Email: support@deessejs.com