@gentleduck/ui

React component library, headless primitives, hooks, variants, and developer tooling for the Gentleduck design system.

MIT - Changelog - Contributing - Docs

---

Install

bunx @gentleduck/cli init
bunx @gentleduck/cli add button dialog calendar

Quick start

import { Button } from '@/components/ui/button'

export default function App() {
  return <Button variant="default">Quack</Button>
}

Workspace

Path	Package	Role
packages/registry-ui	@gentleduck/registry-ui	Styled Tailwind components
packages/duck-primitives	@gentleduck/primitives	Headless a11y-first primitives
packages/duck-variants	@gentleduck/variants	Type-safe cva() variant system
packages/duck-motion	@gentleduck/motion	Motion primitives + reduced motion
packages/duck-hooks	@gentleduck/hooks	React utility hooks
packages/duck-libs	@gentleduck/libs	cn() + small utilities
packages/duck-lazy	@gentleduck/lazy	Lazy-loading helpers
packages/duck-calendar	@gentleduck/calendar	Headless calendar engine
packages/duck-vim	@gentleduck/vim	Keyboard command engine
packages/duck-query	@gentleduck/query	Atom + query primitives
packages/duck-ttest	@gentleduck/ttest	Type-level testing utilities
packages/duck-gen	@gentleduck/gen	Codegen helpers
packages/duck-cli	@gentleduck/cli	Project scaffolding + add CLI
packages/duck-docs	@gentleduck/docs	Shared docs app kit
packages/duck-registry-build	@gentleduck/registry-build	Component registry build engine
packages/registers	@gentleduck/registers	Registry schema + types

Private docs-only: registry-blocks, registry-examples, registry-internals. WIP / deprecated lives under packages/wip/ and packages/deprecated/.

Apps

Path	Role
apps/duck	Docs site at gentleduck.org/duck-ui

Templates

Path	Stack
templates/acme	Next.js monorepo starter wired to the registry

Build

bun install
bunx turbo run build --filter='./packages/*'
bunx turbo run test --filter='./packages/*'
bunx turbo run check-types --filter='./packages/*'

Docs

• Site: gentleduck.org/duck-ui
• Component docs: apps/duck/content/docs/<package>/
• Sibling repos: @gentleduck/iam, @gentleduck/upload, @gentleduck/md

Contributing

PR checklist + style notes in CONTRIBUTING.md. Security: SECURITY.md. Behaviour: CODE_OF_CONDUCT.md.

License

MIT. See LICENSE.