@craftzbay/ui

A refined-minimal Tailwind v4 + React design system. Production-grade primitives — Button through DataGrid — plus composed patterns (authentication, app shell, settings, etc.).

• Showcase: components.runestonetechnologies.com
• Components: components.runestonetechnologies.com#components
• Templates: components.runestonetechnologies.com#templates

Aesthetic direction: Linear / Vercel / Stripe Dashboard / Notion / Raycast. Neutral-dominant, one accent, hairline borders, generous whitespace, fast quiet motion. See docs/PHILOSOPHY.md.

Install

pnpm add @craftzbay/ui

import { Button, Dialog, Toast } from '@craftzbay/ui';
import '@craftzbay/ui/styles.css';

export function App() {
  return <Button variant="primary">Save</Button>;
}

Peer dependencies: react@>=18, react-dom@>=18.

Local development

This package lives in the craftzbay-ui monorepo (packages/ui). The showcase site is a separate workspace (apps/site) that consumes this package's source directly. From the repo root:

pnpm install
pnpm dev           # showcase site (apps/site) — edits to this package hot-reload
pnpm build:lib     # build this library → packages/ui/dist-lib/

Inside packages/ui itself, pnpm build produces the distributable bundle and pnpm test runs the component tests.

Tech stack

• Tailwind CSS v4 — tokens defined in @theme in src/styles/globals.css
• React 18 + TypeScript 5.7
• Radix UI primitives for accessibility-correct overlays
• class-variance-authority + cn() (clsx + tailwind-merge)
• Lucide icons (16 / 20px, 1.5 stroke)
• Geist sans + Geist Mono monospace

Project structure

src/
├── styles/
│   └── globals.css           # @theme tokens, semantic vars, base layer
├── lib/
│   ├── utils.ts              # cn() + uid()
│   └── cva.ts
├── components/
│   ├── ui/                   # primitives — 40 components
│   └── patterns/             # composed layouts
├── hooks/
│   ├── use-toast.ts
│   └── use-media-query.ts
└── icons/                    # curated Lucide re-exports
docs/
├── PHILOSOPHY.md             # the 6 refined-minimal principles
├── VOICE.md                  # content + tone of voice
└── ACCESSIBILITY.md          # WCAG checklist + contrast ratios

Component index

Inputs

• Input — text / email / password / number / search with prefix, suffix, error
• Textarea — auto-resize multi-line input
• Select — single-choice menu (Radix)
• MultiSelect — chip-based multi-choice picker
• Combobox — searchable single-select, sync or async
• Checkbox — including indeterminate
• RadioGroup — mutually-exclusive choices
• Switch — instant-apply binary toggle
• Slider — single + range
• DatePicker — single + range
• Form primitives — react-hook-form bindings

Buttons

• Button — primary · secondary · outline · ghost · destructive · link
• IconButton — square icon-only variant
• Pagination — numbered + jumps + page-size

Feedback

• Alert — inline banner, dismissible
• Toast + useToast hook
• Spinner — accent / neutral / on-accent tones
• Progress — linear + circular, determinate + indeterminate
• Skeleton — text, avatar, card variants
• EmptyState
• ErrorState — 404 / 500 / generic

Navigation

• TopNav + TopNavLink
• Sidebar + SidebarSection + SidebarItem + SidebarGroup
• Breadcrumbs — with overflow ellipsis
• Tabs — underline + pills variants
• Stepper — horizontal + vertical

Layout

• Card + CardHeader/Title/Description/Content/Footer
• Separator
• ScrollArea — Radix-backed styled scroll
• Accordion — single + multiple

Overlays

• Dialog + ConfirmationDialog
• Sheet — left / right / top / bottom
• Popover
• Tooltip — 500ms delay default
• DropdownMenu — submenus, separators, kbd
• ContextMenu — right-click menu
• CommandPalette — ⌘K palette

Data display

• Table + TableSortHeader
• DataGrid — column visibility, filter, sortable
• Badge — subtle + outline, 6 tones
• Avatar + AvatarGroup

Typography

• Kbd — keyboard shortcut indicator

Blocks (page templates)

Whole-page compositions — dashboard, settings, auth, pricing, data table, record detail, onboarding, first-run — are not shipped as importable components. They live in the showcase as copy-paste blocks: complete pages assembled from the primitives above, with the full source on the page. Read it, copy it, adapt it — no opaque <Dashboard /> import. Browse them under Templates in the showcase.

Documentation

• docs/PHILOSOPHY.md — the six principles + forbidden list
• docs/VOICE.md — tone of voice, button labels, error copy formula
• docs/ACCESSIBILITY.md — WCAG AA contrast table, keyboard map

Contributing

1. Read docs/PHILOSOPHY.md first — the forbidden list is non-negotiable.
2. Components reference semantic tokens (bg-card, text-accent), never raw palette steps (bg-indigo-500).
3. Every interactive element ships with: default, hover, focus-visible, active, disabled, loading, and (where applicable) error / success states.
4. Forward refs correctly; set displayName.
5. Run pnpm typecheck && pnpm test before opening a PR.