@craftzbay/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 craftzbay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @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:** [design.runestonetechnologies.com](https://design.runestonetechnologies.com)
+- **Storybook:** [storybook.runestonetechnologies.com](https://storybook.runestonetechnologies.com)
+
+> **Aesthetic direction:** Linear / Vercel / Stripe Dashboard / Notion / Raycast.
+> Neutral-dominant, one accent, hairline borders, generous whitespace, fast quiet
+> motion. See [`docs/PHILOSOPHY.md`](./docs/PHILOSOPHY.md).
+
+## Install
+
+```bash
+pnpm add @craftzbay/ui
+```
+
+```tsx
+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
+
+```bash
+pnpm install
+pnpm dev           # Vite showcase at localhost:5173
+pnpm storybook     # Storybook at localhost:6006
+pnpm build:lib     # Build library → dist-lib/
+```
+
+## 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](./src/components/ui/Input.tsx) — text / email / password / number / search with prefix, suffix, error
+- [Textarea](./src/components/ui/Textarea.tsx) — auto-resize multi-line input
+- [Select](./src/components/ui/Select.tsx) — single-choice menu (Radix)
+- [MultiSelect](./src/components/ui/MultiSelect.tsx) — chip-based multi-choice picker
+- [Combobox](./src/components/ui/Combobox.tsx) — searchable single-select, sync or async
+- [Checkbox](./src/components/ui/Checkbox.tsx) — including indeterminate
+- [RadioGroup](./src/components/ui/RadioGroup.tsx) — mutually-exclusive choices
+- [Switch](./src/components/ui/Switch.tsx) — instant-apply binary toggle
+- [Slider](./src/components/ui/Slider.tsx) — single + range
+- [DatePicker](./src/components/ui/DatePicker.tsx) — single + range
+- [Form primitives](./src/components/ui/Form.tsx) — react-hook-form bindings
+
+### Buttons
+- [Button](./src/components/ui/Button.tsx) — primary · secondary · outline · ghost · destructive · link
+- [IconButton](./src/components/ui/IconButton.tsx) — square icon-only variant
+- [Pagination](./src/components/ui/Pagination.tsx) — numbered + jumps + page-size
+
+### Feedback
+- [Alert](./src/components/ui/Alert.tsx) — inline banner, dismissible
+- [Toast](./src/components/ui/Toast.tsx) + `useToast` hook
+- [Spinner](./src/components/ui/Spinner.tsx) — accent / neutral / on-accent tones
+- [Progress](./src/components/ui/Progress.tsx) — linear + circular, determinate + indeterminate
+- [Skeleton](./src/components/ui/Skeleton.tsx) — text, avatar, card variants
+- [EmptyState](./src/components/ui/EmptyState.tsx)
+- [ErrorState](./src/components/ui/ErrorState.tsx) — 404 / 500 / generic
+
+### Navigation
+- [TopNav](./src/components/ui/TopNav.tsx) + `TopNavLink`
+- [Sidebar](./src/components/ui/Sidebar.tsx) + `SidebarSection` + `SidebarItem` + `SidebarGroup`
+- [Breadcrumbs](./src/components/ui/Breadcrumbs.tsx) — with overflow ellipsis
+- [Tabs](./src/components/ui/Tabs.tsx) — underline + pills variants
+- [Stepper](./src/components/ui/Stepper.tsx) — horizontal + vertical
+
+### Layout
+- [Card](./src/components/ui/Card.tsx) + `CardHeader/Title/Description/Content/Footer`
+- [Separator](./src/components/ui/Separator.tsx)
+- [ScrollArea](./src/components/ui/ScrollArea.tsx) — Radix-backed styled scroll
+- [Accordion](./src/components/ui/Accordion.tsx) — single + multiple
+
+### Overlays
+- [Dialog](./src/components/ui/Dialog.tsx) + `ConfirmationDialog`
+- [Sheet](./src/components/ui/Sheet.tsx) — left / right / top / bottom
+- [Popover](./src/components/ui/Popover.tsx)
+- [Tooltip](./src/components/ui/Tooltip.tsx) — 500ms delay default
+- [DropdownMenu](./src/components/ui/DropdownMenu.tsx) — submenus, separators, kbd
+- [ContextMenu](./src/components/ui/ContextMenu.tsx) — right-click menu
+- [CommandPalette](./src/components/ui/CommandPalette.tsx) — ⌘K palette
+
+### Data display
+- [Table](./src/components/ui/Table.tsx) + `TableSortHeader`
+- [DataGrid](./src/components/ui/DataGrid.tsx) — column visibility, filter, sortable
+- [Badge](./src/components/ui/Badge.tsx) — subtle + outline, 6 tones
+- [Avatar](./src/components/ui/Avatar.tsx) + `AvatarGroup`
+
+### Typography
+- [Kbd](./src/components/ui/Kbd.tsx) — keyboard shortcut indicator
+
+## Patterns (composed layouts)
+
+- [Authentication](./src/components/patterns/Authentication.tsx) — sign-in, sign-up, forgot, magic-link
+- [AppShell + Dashboard](./src/components/patterns/AppShell.tsx) — sidebar + topnav shell, 4 stat cards + chart + activity table
+- [Settings](./src/components/patterns/Settings.tsx) — sub-nav + 5 sections
+- [DataTablePage](./src/components/patterns/DataTablePage.tsx) — filter / search / bulk actions / pagination
+- [RecordDetail](./src/components/patterns/RecordDetail.tsx) — header + tabs + side panel
+- [Onboarding](./src/components/patterns/Onboarding.tsx) — 4-step stepper flow
+- [Pricing](./src/components/patterns/Pricing.tsx) — 3-tier comparison
+- [FirstRunEmpty](./src/components/patterns/FirstRunEmpty.tsx) — hero + 3 next-step cards
+
+## Documentation
+
+- [`docs/PHILOSOPHY.md`](./docs/PHILOSOPHY.md) — the six principles + forbidden list
+- [`docs/VOICE.md`](./docs/VOICE.md) — tone of voice, button labels, error copy formula
+- [`docs/ACCESSIBILITY.md`](./docs/ACCESSIBILITY.md) — WCAG AA contrast table, keyboard map
+
+## Contributing
+
+1. Read [`docs/PHILOSOPHY.md`](./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 lint` before opening a PR.

package/dist-lib/components/patterns/AppShell.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export interface AppShellProps {
+    /** Page content. */
+    children: ReactNode;
+    /** Logo / wordmark for the TopNav. */
+    brand: ReactNode;
+}
+export declare function AppShell({ children, brand }: AppShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function Dashboard(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/Authentication.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+export interface AuthLayoutProps {
+    /** Brand mark shown above the title. */
+    brand?: ReactNode;
+    /** Page heading. */
+    title: ReactNode;
+    /** Secondary line under the title. */
+    subtitle?: ReactNode;
+    /** Form / content. */
+    children: ReactNode;
+    /** Footer slot — "Don't have an account? Sign up". */
+    footer?: ReactNode;
+}
+export declare function AuthLayout({ brand, title, subtitle, children, footer }: AuthLayoutProps): import("react/jsx-runtime").JSX.Element;
+export interface SignInFormProps {
+    onSubmit: (data: {
+        email: string;
+        password: string;
+    }) => void | Promise<void>;
+    loading?: boolean;
+    error?: ReactNode;
+    forgotHref?: string;
+}
+export declare function SignInForm({ onSubmit, loading, error, forgotHref }: SignInFormProps): import("react/jsx-runtime").JSX.Element;
+export interface SignUpFormProps {
+    onSubmit: (data: {
+        name: string;
+        email: string;
+        password: string;
+    }) => void | Promise<void>;
+    loading?: boolean;
+    error?: ReactNode;
+}
+export declare function SignUpForm({ onSubmit, loading, error }: SignUpFormProps): import("react/jsx-runtime").JSX.Element;
+export interface ForgotPasswordFormProps {
+    onSubmit: (email: string) => void | Promise<void>;
+    loading?: boolean;
+    error?: ReactNode;
+}
+export declare function ForgotPasswordForm({ onSubmit, loading, error }: ForgotPasswordFormProps): import("react/jsx-runtime").JSX.Element;
+export interface MagicLinkSentProps {
+    email: string;
+    onResend?: () => void;
+}
+export declare function MagicLinkSent({ email, onResend }: MagicLinkSentProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/DataTablePage.d.ts

@@ -0,0 +1 @@
+export declare function DataTablePage(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/FirstRunEmpty.d.ts

@@ -0,0 +1 @@
+export declare function FirstRunEmpty(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/Onboarding.d.ts

@@ -0,0 +1 @@
+export declare function Onboarding(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/Pricing.d.ts

@@ -0,0 +1 @@
+export declare function Pricing(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/RecordDetail.d.ts

@@ -0,0 +1 @@
+export declare function RecordDetail(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/patterns/Settings.d.ts

@@ -0,0 +1 @@
+export declare function SettingsPage(): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/ui/Accordion.d.ts

@@ -0,0 +1,21 @@
+import * as AccordionPrimitive from '@radix-ui/react-accordion';
+/**
+ * Accessible disclosure list. Supports single (`type="single"`) and multiple
+ * (`type="multiple"`) open behaviour — both come from Radix.
+ *
+ * @example FAQ
+ *   <Accordion type="single" collapsible>
+ *     <AccordionItem value="q1">
+ *       <AccordionTrigger>Can I cancel anytime?</AccordionTrigger>
+ *       <AccordionContent>Yes — usage stops at the end of the billing period.</AccordionContent>
+ *     </AccordionItem>
+ *     …
+ *   </Accordion>
+ *
+ * @do Use for FAQs, settings groups, and progressive-disclosure forms.
+ * @dont Nest accordions inside accordions — the focus order becomes opaque.
+ */
+export declare const Accordion: import('react').ForwardRefExoticComponent<(AccordionPrimitive.AccordionSingleProps | AccordionPrimitive.AccordionMultipleProps) & import('react').RefAttributes<HTMLDivElement>>;
+export declare const AccordionItem: import('react').ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionItemProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const AccordionTrigger: import('react').ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionTriggerProps & import('react').RefAttributes<HTMLButtonElement>, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
+export declare const AccordionContent: import('react').ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionContentProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist-lib/components/ui/Alert.d.ts

@@ -0,0 +1,35 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { VariantProps } from '../../lib/cva';
+declare const alert: (props?: ({
+    variant?: "default" | "success" | "warning" | "danger" | "info" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface AlertProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof alert> {
+    /** Heading. Renders bold above the description. */
+    title?: ReactNode;
+    /** Show a dismiss (×) button. */
+    dismissible?: boolean;
+    /** Called when the user dismisses. */
+    onDismiss?: () => void;
+    /** Override the variant's default icon. Pass `false` to suppress the icon. */
+    icon?: ReactNode | false;
+}
+/**
+ * Inline banner for static page-level or section-level state. For transient
+ * notifications use `Toast` instead.
+ *
+ * @example Inline error
+ *   <Alert variant="danger" title="Payment failed">
+ *     Your card was declined. Update your billing info to retry.
+ *   </Alert>
+ *
+ * @example Dismissible info
+ *   <Alert variant="info" dismissible onDismiss={dismiss}>
+ *     We're improving search — give us feedback at #search-feedback.
+ *   </Alert>
+ *
+ * @do Use the closest semantic variant — `info` for neutral facts,
+ *      `warning` for "watch out", `danger` for "this is broken".
+ * @dont Use Alert for one-time confirmations — that's Toast.
+ */
+export declare const Alert: import('react').ForwardRefExoticComponent<AlertProps & import('react').RefAttributes<HTMLDivElement>>;
+export {};

package/dist-lib/components/ui/Avatar.d.ts

@@ -0,0 +1,52 @@
+import { ComponentPropsWithoutRef, HTMLAttributes, ReactNode } from 'react';
+import { VariantProps } from '../../lib/cva';
+import * as AvatarPrimitive from '@radix-ui/react-avatar';
+declare const sizeMap: {
+    readonly xs: "size-5 text-[10px]";
+    readonly sm: "size-6 text-xs";
+    readonly md: "size-8 text-xs";
+    readonly lg: "size-10 text-sm";
+    readonly xl: "size-12 text-base";
+};
+declare const avatar: (props?: ({
+    size?: "md" | "xs" | "sm" | "lg" | "xl" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface AvatarProps extends ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>, VariantProps<typeof avatar> {
+    /** Image URL. If absent or fails to load, fallback initials are shown. */
+    src?: string;
+    /** Alt text for the image; falls back to fallback when there's no `src`. */
+    alt?: string;
+    /** Initials shown when image is missing or loading. Pass at most 2 characters. */
+    fallback?: string;
+    /** Status dot rendered on the bottom-right. */
+    status?: 'online' | 'busy' | 'away' | 'offline';
+}
+/**
+ * Avatar with image, initials fallback, and optional status dot.
+ *
+ * @example
+ *   <Avatar src={user.photo} alt={user.name} fallback={getInitials(user.name)} status="online" />
+ *
+ * @example AvatarGroup
+ *   <AvatarGroup max={3}>
+ *     {users.map(u => <Avatar key={u.id} src={u.photo} fallback={getInitials(u.name)} />)}
+ *   </AvatarGroup>
+ *
+ * @do Provide `alt` for image avatars and meaningful initials for the
+ *      fallback so screen readers announce something useful.
+ * @dont Use the status dot without a tooltip explaining what it means.
+ */
+export declare const Avatar: import('react').ForwardRefExoticComponent<AvatarProps & import('react').RefAttributes<HTMLSpanElement>>;
+export interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** Maximum visible avatars before showing a "+N" overflow chip. */
+    max?: number;
+    /** Avatar size applied to children + overflow. */
+    size?: keyof typeof sizeMap;
+    /** Children — Avatars. */
+    children: ReactNode;
+}
+/**
+ * Overlapping avatars with overflow indicator. Pass plain `<Avatar>` children.
+ */
+export declare const AvatarGroup: import('react').ForwardRefExoticComponent<AvatarGroupProps & import('react').RefAttributes<HTMLDivElement>>;
+export {};

package/dist-lib/components/ui/Badge.d.ts

@@ -0,0 +1,24 @@
+import { HTMLAttributes } from 'react';
+import { VariantProps } from '../../lib/cva';
+declare const badge: (props?: ({
+    variant?: "subtle" | "outline" | null | undefined;
+    tone?: "success" | "warning" | "danger" | "info" | "neutral" | "accent" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badge> {
+    /** Show a leading status dot in the same tone. */
+    dot?: boolean;
+}
+/**
+ * Status pill. Use `subtle` for high-volume contexts (table cells, lists);
+ * `outline` when the badge sits on a busy or coloured background.
+ *
+ * @example
+ *   <Badge tone="success" dot>Active</Badge>
+ *   <Badge tone="danger" variant="outline">Failed</Badge>
+ *
+ * @do Use badges to summarise state, not to label categories — for taxonomies
+ *      pick a tone palette and stick with it.
+ * @dont Use a badge as a button. Wrap it in a Button or use a Toggle.
+ */
+export declare const Badge: import('react').ForwardRefExoticComponent<BadgeProps & import('react').RefAttributes<HTMLSpanElement>>;
+export {};

package/dist-lib/components/ui/Breadcrumbs.d.ts

@@ -0,0 +1,31 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export interface BreadcrumbItem {
+    /** Visible label. */
+    label: ReactNode;
+    /** Optional URL. Last item is treated as current page even if href is set. */
+    href?: string;
+}
+export interface BreadcrumbsProps extends HTMLAttributes<HTMLElement> {
+    items: BreadcrumbItem[];
+    /** Collapse to first + ellipsis + last `n` when items.length exceeds this. */
+    maxItems?: number;
+    /** Custom link renderer (for next/link, react-router, etc.). */
+    renderLink?: (href: string, children: ReactNode) => ReactNode;
+}
+/**
+ * Breadcrumb trail. Collapses with an ellipsis when there are too many crumbs.
+ *
+ * @example
+ *   <Breadcrumbs items={[
+ *     { label: 'Projects', href: '/projects' },
+ *     { label: 'Nova', href: '/projects/nova' },
+ *     { label: 'Settings' },
+ *   ]} />
+ *
+ * @example With react-router
+ *   <Breadcrumbs items={trail} renderLink={(href, c) => <Link to={href}>{c}</Link>} />
+ *
+ * @do Always omit `href` on the last item — it represents the current page.
+ * @dont Use Breadcrumbs for flat navigation. Use TopNav links instead.
+ */
+export declare const Breadcrumbs: import('react').ForwardRefExoticComponent<BreadcrumbsProps & import('react').RefAttributes<HTMLElement>>;

package/dist-lib/components/ui/Button.d.ts

@@ -0,0 +1,50 @@
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+import { VariantProps } from '../../lib/cva';
+declare const button: (props?: ({
+    variant?: "link" | "outline" | "primary" | "secondary" | "ghost" | "destructive" | null | undefined;
+    size?: "icon" | "md" | "sm" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof button> {
+    /**
+     * Render as a different element via Radix Slot. Useful when wrapping a
+     * link: `<Button asChild><a href="…">…</a></Button>`.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Show a spinner in place of the leading icon and disable the button.
+     * Use for async actions where the user must wait.
+     * @default false
+     */
+    loading?: boolean;
+    /** Icon rendered before the label. Replaced by a spinner when loading. */
+    leadingIcon?: ReactNode;
+    /** Icon rendered after the label. Hidden while loading. */
+    trailingIcon?: ReactNode;
+}
+/**
+ * Primary interactive element. Variants:
+ *
+ * - `primary` — accent fill, the single most prominent action on a screen.
+ * - `secondary` — neutral fill, sits next to a primary or stands alone for
+ *   secondary actions.
+ * - `outline` — border only, transparent fill. Use when next to a primary.
+ * - `ghost` — no border, hover background. Use in dense toolbars and tables.
+ * - `destructive` — danger fill, reserved for irreversible actions.
+ * - `link` — text styled as a link.
+ *
+ * @example Two-button row
+ *   <div className="flex gap-2 justify-end">
+ *     <Button variant="outline">Cancel</Button>
+ *     <Button>Save changes</Button>
+ *   </div>
+ *
+ * @example Loading state
+ *   <Button loading leadingIcon={<Mail />}>Sending…</Button>
+ *
+ * @do Use one primary button per major surface. Verb-first labels.
+ * @dont Stack three primary buttons in a row — only the most important
+ *       action gets the primary variant.
+ */
+export declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
+export {};

package/dist-lib/components/ui/Card.d.ts

@@ -0,0 +1,37 @@
+import { HTMLAttributes } from 'react';
+import { VariantProps } from '../../lib/cva';
+declare const card: (props?: ({
+    variant?: "default" | "interactive" | null | undefined;
+    padding?: "none" | "md" | "sm" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface CardProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof card> {
+}
+/**
+ * Bounded surface used to group related content. Per the refined-minimal
+ * rules, cards on the page have a hairline border and no shadow.
+ *
+ * @example Header + content + footer
+ *   <Card>
+ *     <CardHeader>
+ *       <CardTitle>Storage</CardTitle>
+ *       <CardDescription>Usage across all projects.</CardDescription>
+ *     </CardHeader>
+ *     <CardContent>…</CardContent>
+ *     <CardFooter><Button>Upgrade</Button></CardFooter>
+ *   </Card>
+ *
+ * @example Clickable list row
+ *   <Card variant="interactive" onClick={open}>…</Card>
+ *
+ * @do Use the `border` style. If a card needs to "float" (modal, dropdown),
+ *      it isn't a Card — it's a Popover/Dialog.
+ * @dont Add `shadow-lg` to Cards. Shadows on inline surfaces violate the
+ *       refined-minimal direction.
+ */
+export declare const Card: import('react').ForwardRefExoticComponent<CardProps & import('react').RefAttributes<HTMLDivElement>>;
+export declare const CardHeader: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const CardTitle: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & import('react').RefAttributes<HTMLHeadingElement>>;
+export declare const CardDescription: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & import('react').RefAttributes<HTMLParagraphElement>>;
+export declare const CardContent: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const CardFooter: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import('react').RefAttributes<HTMLDivElement>>;
+export {};

package/dist-lib/components/ui/Checkbox.d.ts

@@ -0,0 +1,28 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+export interface CheckboxProps extends Omit<ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, 'asChild'> {
+    /** Visible label rendered to the right of the box. */
+    label?: ReactNode;
+    /** Secondary description rendered below the label. */
+    description?: ReactNode;
+    /** Validation error message. */
+    error?: ReactNode;
+    /** Hide the label visually while keeping it in the a11y tree. */
+    hideLabel?: boolean;
+}
+/**
+ * Checkbox with optional inline label + description. Pass `checked="indeterminate"`
+ * for the indeterminate state — Radix renders a `Minus` icon automatically.
+ *
+ * @example Single
+ *   <Checkbox label="I agree to the terms" checked={ok} onCheckedChange={setOk} />
+ *
+ * @example Tri-state header
+ *   <Checkbox aria-label="Select all"
+ *             checked={allSelected ? true : someSelected ? 'indeterminate' : false}
+ *             onCheckedChange={toggleAll} />
+ *
+ * @do Use indeterminate to summarise child rows in a table header.
+ * @dont Use a Checkbox for mutually exclusive choices — use RadioGroup.
+ */
+export declare const Checkbox: import('react').ForwardRefExoticComponent<CheckboxProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist-lib/components/ui/Combobox.d.ts

@@ -0,0 +1,58 @@
+import { ReactNode } from 'react';
+export interface ComboboxOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+export interface ComboboxProps {
+    /** Currently selected value (controlled). */
+    value: string | null;
+    /** Called when a value is picked or cleared. */
+    onChange: (value: string | null) => void;
+    /** Static options. Ignored if `loadOptions` is provided. */
+    options?: ComboboxOption[];
+    /**
+     * Async loader called with the current query each time it changes.
+     * Use for server-side search.
+     */
+    loadOptions?: (query: string) => Promise<ComboboxOption[]>;
+    /** Visible label above the field. */
+    label?: ReactNode;
+    /** Hint below the field. Hidden when `error` is set. */
+    helperText?: ReactNode;
+    /** Validation error. */
+    error?: ReactNode;
+    /** Placeholder shown when no value is selected. */
+    placeholder?: string;
+    /** Search placeholder inside the popover. */
+    searchPlaceholder?: string;
+    /** Empty state copy when nothing matches. */
+    emptyText?: string;
+    /** Allow clearing the selection with an inline ×. */
+    clearable?: boolean;
+    /** Disable the entire field. */
+    disabled?: boolean;
+    /** Field size, matches Input. */
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+}
+/**
+ * Single-select with typeahead. Use `options` for client-side filtering or
+ * `loadOptions` for server-side search.
+ *
+ * @example Client-side
+ *   <Combobox label="Country" options={countries} value={c} onChange={setC} />
+ *
+ * @example Server-side
+ *   <Combobox label="Assignee"
+ *             value={user}
+ *             onChange={setUser}
+ *             loadOptions={async (q) => api.searchUsers(q)} />
+ *
+ * @do Use Combobox over Select for >12 options or when the user is expected
+ *      to know what they want.
+ * @dont Re-query on every keystroke without debouncing — pass a debounced
+ *       `loadOptions` to avoid hammering the server.
+ */
+export declare const Combobox: import('react').ForwardRefExoticComponent<ComboboxProps & import('react').RefAttributes<HTMLDivElement>>;