# Junco

> Junco is a free, open source (MIT) design system for React and Tailwind CSS v4: tokens, components, blocks, pages, motion and 3D. It can be used four ways, all reading the same tokens:

1. Semantic classes (like daisyUI): class="btn btn-primary". Pure CSS. Setup: @import "tailwindcss"; @import "@junco/tailwind";
2. Utilities (like Tailwind): bg-surface text-muted-foreground rounded-card. Same setup.
3. Copy-in components (like shadcn/ui): npx @junco/cli add button (or npx shadcn@latest add https://junco.madebytobi.com/r/button.json).
4. Installed components (like HeroUI): npm i junco, then import { Button } from "junco". Add @source "../node_modules/junco/dist"; to your CSS.

Tokens follow shadcn/ui names (--background, --foreground, --primary, --muted-foreground, --border, --ring, ...) plus Junco additions (--surface, --success, --warning, --success-text, --warning-text, --destructive-text, motion tokens). Dark mode: .dark or [data-theme="dark"] on <html>. Motion: data-motion="full|subtle|off", and prefers-reduced-motion always turns motion off.

## Components

- [Accordion](https://junco.madebytobi.com/docs/components/accordion): Stacked sections that expand and collapse. Good for FAQs and settings groups. `type="single"` opens one at a time (add `collapsible` to allow closing it); `type="multiple"` doesn't.
- [Avatar](https://junco.madebytobi.com/docs/components/avatar): A person or workspace picture that falls back to initials while loading or when the image fails.
- [Badge](https://junco.madebytobi.com/docs/components/badge): A short label for status or counts.
- [Breadcrumb](https://junco.madebytobi.com/docs/components/breadcrumb): Shows where a page sits in the hierarchy, with links back up. Collapses long trails with maxItems.
- [Button](https://junco.madebytobi.com/docs/components/button): Triggers an action. Variants solid, outline, soft, ghost and danger; isLoading shows a spinner and sets aria-busy.
- [Card](https://junco.madebytobi.com/docs/components/card): A bordered container for grouping related content, with header, title, description, action, content and footer parts.
- [Checkbox](https://junco.madebytobi.com/docs/components/checkbox): A checkbox. `checked` can be true, false or "indeterminate". Pair it with a <Label htmlFor>.
- [Command](https://junco.madebytobi.com/docs/components/command): A searchable list of actions, built on cmdk. Use it inline, or as a ⌘K palette with CommandDialog.
- [Dialog](https://junco.madebytobi.com/docs/components/dialog): Every dialog needs a DialogTitle. Hide it visually with `<DialogTitle isHidden>` when the design has no heading.
- [Dropdown Menu](https://junco.madebytobi.com/docs/components/dropdown-menu): Arrow keys move, Enter/Space select, typing jumps to an item, Esc closes and returns focus.
- [Empty State](https://junco.madebytobi.com/docs/components/empty-state): What to show when there is nothing to show: say why, and offer the next step.
- [Field](https://junco.madebytobi.com/docs/components/field): Label + control + help text + error, wired together.
- [Input](https://junco.madebytobi.com/docs/components/input): A single-line text field. Sizes sm, md and lg; isInvalid sets aria-invalid; picks up its label and errors from a Field.
- [Kbd](https://junco.madebytobi.com/docs/components/kbd): A keyboard key, e.g. `<Kbd>⌘</Kbd><Kbd>K</Kbd>`. Give symbols a `title` so they read clearly.
- [Label](https://junco.madebytobi.com/docs/components/label): A form label with an optional required marker.
- [Pagination](https://junco.madebytobi.com/docs/components/pagination): Numbered page links with previous/next. The current page has aria-current="page".
- [Popover](https://junco.madebytobi.com/docs/components/popover): Focus moves into the popover on open and back to the trigger on close. Esc and outside clicks close it.
- [Radio Group](https://junco.madebytobi.com/docs/components/radio-group): Arrow keys move between options; Tab leaves the group. Give the group an aria-label or aria-labelledby.
- [Select](https://junco.madebytobi.com/docs/components/select): A dropdown for picking one option from a list, with keyboard type-ahead and a check on the chosen item.
- [Separator](https://junco.madebytobi.com/docs/components/separator): A thin horizontal or vertical divider. Decorative by default.
- [Sheet](https://junco.madebytobi.com/docs/components/sheet): A panel that slides in from an edge. On phones (under 640px) side sheets become bottom sheets you can swipe down to close, unless `mobileSide="same"`.
- [Skeleton](https://junco.madebytobi.com/docs/components/skeleton): A placeholder block for content that is loading. Size it with className, e.g. `h-4 w-32`.
- [Spinner](https://junco.madebytobi.com/docs/components/spinner): A loading indicator. It keeps turning (slower) with motion off, since it carries meaning.
- [Stat](https://junco.madebytobi.com/docs/components/stat): A single number with its label and change. Direction is shown by icon, sign and screen reader text, never by color alone.
- [Switch](https://junco.madebytobi.com/docs/components/switch): An on/off toggle that applies immediately. For a choice submitted with a form, prefer Checkbox.
- [Tabs](https://junco.madebytobi.com/docs/components/tabs): Switches between views in the same space. Variants line (page sections) and segmented (small view switchers).
- [Textarea](https://junco.madebytobi.com/docs/components/textarea): A multi-line text field that can grow with its content (autoResize).
- [Toast](https://junco.madebytobi.com/docs/components/toast): Brief notifications from anywhere with toast(): success, error, warning, info, loading and promise, with actions and swipe to dismiss.
- [Tooltip](https://junco.madebytobi.com/docs/components/tooltip): Works without a TooltipProvider (it adds its own), but one shared provider is better.
- [Data Table](https://junco.madebytobi.com/docs/components/data-table): A full data table on TanStack Table: sorting, selection, search, column visibility, pagination, loading and empty states. Pass `manual` for server-side data.
- [Form](https://junco.madebytobi.com/docs/components/form): React Hook Form + Zod integration: FormField wires labels, help text and errors to any Junco control.
- [Theme Provider](https://junco.madebytobi.com/docs/components/theme-provider): Light, dark and system themes plus the data-motion switch, saved to localStorage, with a no-flash themeScript for SSR.
- [Theme Script](https://junco.madebytobi.com/docs/components/theme-script): An inline script for <head> that applies the saved theme before first paint, so server-rendered pages don't flash light then dark. Use it with the same options you pass to ThemeProvider.

## Optional

- [Full component reference](https://junco.madebytobi.com/llms-full.txt): props, variants and usage for every component
- [Registry index](https://junco.madebytobi.com/r/registry.json): shadcn-compatible registry