# Crossroads UI

> A token-driven, accessible React component system. Every component is
> WCAG AA and RTL-ready, and light/dark, rounded/flat and LTR/RTL all
> resolve from one set of CSS custom properties without a rebuild.

Package: @tsviser/crossroads-ui — 93 ready components in 13 groups.
Generated: 2026-09-15

## Machine-readable manifests

- [Component manifest](https://crossroadsui.com/ai/component.manifest.json): every component, its props, examples, usage rules and accessibility notes.
- [Template manifest](https://crossroadsui.com/ai/template.manifest.json): 4 source-owned page and section compositions.
- [Token manifest](https://crossroadsui.com/ai/tokens.manifest.json): 536 design tokens grouped by concern.
- [Recipes](https://crossroadsui.com/ai/recipes.manifest.json): prompt to on-system code pairs.
- [Gaps](https://crossroadsui.com/ai/gaps.manifest.json): what the library does not have, what to do instead, and how to report a new gap.
- [Storybook](https://crossroadsui.com/storybook/): every ready Storybook-visible component rendered, with a live code sandbox.

## Rules for generating Crossroads UI code

1. Generate package imports from `@tsviser/crossroads-ui` only for repository examples or consumers with explicitly approved future access. The package is not currently published or authorized for client installation. Do not invent component names — check the component manifest's `exports`. A symbol belongs to the governed candidate contract only when its status is not `planned`, `importPath` is non-null, and it appears in `exports`; planned entries are roadmap metadata, never legal imports.
2. Compound components are exported flat and as namespaces: `<Select.Root>`/`<Select.Option>` and `SelectRoot`/`SelectOption` both exist.
3. Never hardcode colors, spacing, radii or motion. Use the `--cr-*` custom properties from the token manifest, and only names it declares.
4. Use logical CSS properties (`inline-start`, `block-end`) so RTL keeps working.
5. Keep visible labels, keyboard access, focus-visible styles and reduced-motion support intact.
6. Wrap an app in `CrossroadsProvider`; components that render in a portal also need a portal root.
7. Icons come only from `Icon`. No second component library and no icon package imported directly; no copied component source.
8. When the component you need does not exist: read the absence list first and do what it says. If it is not listed, stop — say what is missing, use the nearest listed alternative or ask, and file a change request. Never build a substitute silently.
9. Before you call the work done, run the bundle's `crossroads-check` on your source. A finding is a fix, not an exception.

## Flagship components

### Button
Contained, outlined, text, loading, and responsive action button.
Use for: Submit a form; Confirm or cancel in a dialog; Primary call to action on a page.
Exports: Button.

### TextField
Single-line text input with labels, descriptions, errors, and leading or trailing icons.
Use for: Collect a name or email; Search input; Field with helper text and validation errors.
Exports: TextField, TextFieldControl.

### Select
Native select wrapper with field states.
Use for: Choose one option from a known list; Settings dropdown; Filter control.
Exports: Select, SelectControl, SelectOption, SelectRoot.

### Autocomplete
Text input with suggested options and keyboard navigation.
Use for: Pick from a long list; Assign a person to a task; Type-ahead search.
Exports: Autocomplete.

### Table
Responsive semantic table with density controls.
Use for: List records with sorting; Admin data view; Dense reporting screen.
Exports: Table, TableBody, TableCaption, TableCell, TableEmpty, TableFooter, TableHead, TableHeaderCell, TableLoading, TablePagination, TableRow, TableSelectionCell, TableSortButton.

### Stat
Metric block for dashboards and summaries.
Use for: Dashboard KPI; Summary figure with trend; Metric tile above a chart.
Exports: Stat.

### VisualCard
Media-forward card for visual content, posters, uploads, and feature previews.
Use for: Marketing feature card; Content tile with media; Product listing.
Exports: VisualCard.

### Card
Bounded content container for repeated display items.
Use for: Group related content; Settings section; Summary panel.
Exports: Card, CardActionArea, CardActions, CardContent, CardHeader, CardMedia.

### SelectableCard
Card-shaped selectable option for button, radio, and checkbox flows.
Use for: Plan or tier picker; Choose one of several options visually; Onboarding choice.
Exports: SelectableCard, SelectableCardGroup.

### ActionCard
Reusable icon-bearing navigation card for indexes and action lists.
Use for: Navigate to a section; Launch a task from a dashboard; Quick action tile.
Exports: ActionCard.

### Panel
Semantic in-page section with title, description, body, actions, footer, collapse, and loading composition.
Use for: Settings section; Dashboard content region; Form section with actions.
Exports: Panel, PanelRoot, PanelHeader, PanelTitle, PanelDescription, PanelBody, PanelFooter, PanelSeparator.

### AppBar
Top application bar for product navigation and actions.
Use for: Application top bar; Page header with actions; Brand plus account menu.
Exports: AppBar.

### NavigationDrawer
Collapsible sidebar navigation with icon rail and responsive behavior.
Use for: Primary app navigation; Collapsible sidebar; Mobile navigation panel.
Exports: NavigationDrawer, NavigationDrawerBody, NavigationDrawerDivider, NavigationDrawerFooter, NavigationDrawerHeader, NavigationDrawerItem, NavigationDrawerNav, NavigationDrawerRoot, NavigationDrawerToggle.

### Tabs
Keyboard-friendly tablist and tab panel navigation.
Use for: Switch between views in one page; Settings sections; Detail page panels.
Exports: Tabs, TabsList, TabsPanel, TabsRoot, TabsTab.

### Stepper
Progressive multi-step workflow indicator.
Use for: Multi-step onboarding; Checkout flow; Progress through a wizard.
Exports: Stepper, StepperRoot, StepperStep.

### Dialog
Modal dialog with focus restoration and escape handling.
Use for: Confirm a destructive action; Focused form in an overlay; Detail view without leaving the page.
Exports: Dialog.

### Drawer
Edge-attached modal panel with logical placement.
Use for: Side panel for details; Filters panel; Edit form beside the list.
Exports: Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerDescription, DrawerDivider, DrawerFooter, DrawerHeader, DrawerRoot, DrawerTitle, DrawerTrigger.

### Snackbar
Temporary non-blocking notification with optional action.
Use for: Confirm an action succeeded; Non-blocking error notice; Undo affordance.
Exports: Snackbar.

### Progress
Linear and circular progress indicators for determinate and indeterminate work.
Use for: File upload progress; Multi-step completion; Indeterminate loading.
Exports: Progress.

### Skeleton
Placeholder loading state for content that is not ready yet.
Use for: Placeholder while data loads; Perceived performance on lists; Card loading state.
Exports: Skeleton.

### EmptyState
Centered empty content message with optional action.
Use for: No results after filtering; First-run experience; Cleared inbox.
Exports: EmptyState.

### Accordion
Multi-section disclosure with keyboard navigation.
Use for: FAQ section; Progressive disclosure in dense settings; Grouped detail panels.
Exports: Accordion, AccordionContent, AccordionItem, AccordionRoot, AccordionTrigger.

### Toast
App-wide queued notifications with imperative show, update, dismiss, and promise flows.
Use for: Queue application notifications; Track async work; Offer a non-blocking recovery action.
Exports: Toast, ToastProvider, useToast.

### SegmentedControl
Single-choice segmented controller with keyboard support.
Use for: Switch between two or three modes; View toggle; Compact filter.
Exports: SegmentedControl, SegmentedControlOption, SegmentedControlRoot.

## Example prompts this system answers

- Build a notification-settings section: email and push toggles, a digest frequency select, and a save button. (recipe: `notification-settings`)
- Show a table of team members with their status. (recipe: `members-table`)
- Show a friendly empty state when there are no projects yet. (recipe: `empty-state`)
- Show placeholder rows while the list is loading. (recipe: `loading-placeholder`)
- Confirm to the user that their settings were saved, with an undo. (recipe: `save-confirmation`)

## Source-owned templates

- Sign in: Centered authentication card with email and password, inline error, and a route to account recovery. (template: `sign-in`)
- Pricing plans: Three-tier plan selection with a billing-period toggle and a highlighted recommended plan. (template: `pricing-plans`)
- Error page: Full-page not-found and server-error states with a way back and a support route. (template: `error-page`)

## What the library does not have

Read this before building anything the component manifest does not cover. If it is listed, do what the row says. If it is not listed and not in the manifest, stop and file a change request — never build a substitute silently.

- **Date and time pickers** (deferred): `TextField` passes native input attributes through: `type="date"`, `"time"` or `"datetime-local"` gives a localized, accessible native picker inside the library's field styling. A range is two fields. A time zone or a custom calendar is a change request; do not build a calendar.
- **Charts** (deferred): `Stat` for a single value (format it yourself, `value` is a ReactNode); `Table` for a series a reader must inspect. Anything drawn is a change request.
- **Data grid** (deferred): `Table` for static data, with `Pagination` below it. Sorting, virtualisation, selection or editing is a change request.
- **Rich text editor** (declined): Product code: wrap Tiptap yourself and style it with `--cr-*` tokens. `TextArea` for plain multi-line text.
- **Watermark** (declined): Product CSS: a positioned, non-interactive layer using `--cr-*` tokens.
- **QR code** (declined): Generate the SVG in product code and place it as an image; it is content, not a control.
- **Countdown** (declined): `Stat` with a value you tick and format with Intl.
- **Avatar group** (planned): An `Inline` of `Avatar`s. Overlap and a “+N” overflow are a change request.
- **Password field** (planned): `TextField` with `type="password"`. A show/hide toggle is the planned addition; do not attach one by hand.
- **PIN / one-time-code input** (planned): One `TextField` with `inputMode="numeric"`, `maxLength={6}` and `autoComplete="one-time-code"`. Six boxes is the planned component.
- **Tags input** (planned): `Select` for a closed set; `Chip`s in an `Inline` to show what is chosen. Free-text tag entry is a change request.
- **Form orchestration** (planned): A `Stack` of `Field`s, and the actions in an `Inline` with `role="group"`. Validation state lives in your own code and reaches the fields through their props.
- **Context menu** (planned): `Menu` opened from an `IconButton`. A right-click menu is a change request.
- **Command palette** (planned): A `Dialog` containing a `SearchField` and a `List`.
- **Carousel** (planned): A horizontally scrolling `Box` with `overflow-x: auto` and scroll snapping in CSS. Do not write slide logic.
- **Hover card** (planned): `Tooltip` for a short text; `Popover` for rich content.
- **Menubar** (planned): An `AppBar` holding `Menu`s.
- **Anchor navigation / table of contents** (planned): A `NavList` of `Link`s to the page's headings.
- **Affix / back to top** (planned): `position: sticky` on a `Box`; a `Button` that scrolls to the top.
- **Tour** (planned): One `Popover` per step; the sequencing is product code.
- **Transfer list** (planned): Two `List`s of `Checkbox` rows with `Button`s between them.
- **Loading overlay** (planned): `Backdrop` with a `Spinner` or `Progress` inside it; `Skeleton` where the shape of the content is known.
- **Meter** (planned): `Progress` for a determinate value. Threshold colours are a change request.
- **Keyboard key** (planned): `CodeText` inside a native `<kbd>`.
- **Code block** (planned): `CodeText` inline; a block is a native `<pre>` styled with `--cr-*` tokens.
- **Indicator (anchored badge)** (planned): `Badge` placed beside the element. Anchoring over a corner is a change request.
- **Image** (planned): A native `<img>` with `alt`; inside a `Card`, use `CardMedia`. Fallback chains and lazy loading are a change request.
- **Scroll area** (planned): `overflow: auto` on a `Box`.
- **Virtual list** (planned): `Table` or `List` with `Pagination`. Virtualisation and infinite scroll are a change request.
- **Aspect ratio** (planned): The `aspect-ratio` CSS property on a `Box`.

Registered but not usable yet — do not import these:

MultiSelect (in-progress), ToggleButton (planned), ImageList (planned), PageShell (in-progress), SpeedDial (planned), Toolbar (planned), ActionBar (planned), AsyncSection (in-progress), Hero (in-progress), PageHeader (in-progress), FormLayout (in-progress), FormActions (in-progress), ConfirmDialog (in-progress), CssBaseline (planned), InitColorSchemeScript (planned), NoSsr (planned), Calendar (planned), RangeCalendar (planned), DateField (planned), TimeField (planned), DatePicker (planned), DateRangePicker (planned), DataGrid (planned), Charts (planned), TreeView (planned), Masonry (planned), Timeline (planned)

## Never import

@mui/, @radix-ui/, @chakra-ui/, @mantine/, @headlessui/, @ariakit/, @base-ui/, @heroui/, @nextui-org/, antd, react-aria-components, react-bootstrap, lucide-react, @phosphor-icons/, @material-symbols-svg/, react-icons, @heroicons/, @tabler/icons-react, @fortawesome/ — a second component library or a directly imported icon pack bypasses the tokens, the focus ring, RTL and the provider's icon choice. Icons come from `Icon`.

## Reporting a gap

Open a change request: https://github.com/crossroads-hq/crossroads-ui/issues/new?template=change-request.yml. Say what the product needed, which component came nearest and where it fell short. That is how a row above gets added.