# NAMCHE UI

NAMCHE UI is the functional component layer for NAMCHE products and tools:
the full shadcn/ui component set, built on Base UI primitives, themed by
`@namche/design-tokens`. It is recognisably NAMCHE without the weight of the
brand layer — identity comes from the design system's own decisions, not
decoration.

## Install

```bash
pnpm dlx shadcn@latest init -b base -y
```

Register the registry in `components.json`:

```json
{ "registries": { "@namche": "https://ui.namche.ai/r/{name}.json" } }
```

Install the theme, then any component:

```bash
pnpm dlx shadcn@latest add @namche/theme
pnpm dlx shadcn@latest add @namche/button @namche/dialog @namche/table
```

Components land in `components/ui/` in the installing repo — they are meant
to be read and edited, not treated as an opaque package.

## Non-negotiable rules

An agent generating NAMCHE UI code must follow these. They are read off the
design system's own components, not invented, and every doc page under
`/docs/components` enforces them.

- **Tokens only.** Every colour, radius, and type value comes from
  `@namche/design-tokens` through the semantic Tailwind variables (`bg-primary`,
  `text-muted-foreground`, `rounded-card`, …) or, for chart/illustration work
  only, the OKEANOS/HELIOS bridge utilities (`text-okeanos-artemis`,
  `bg-helios-eos`, `var(--chart-1)`…`var(--chart-5)`). Never hardcode a hex
  value or invent a colour.
- **Composition uses the `render` prop, not `asChild`.** Base UI components
  take `render={<Button variant="outline">Open</Button>}`, not the Radix
  `asChild` pattern. Check each component's actual props before writing a
  trigger.
- **Namche Shadow Sans is headlines only**, weight 500 (or 700 for emphasis),
  never Regular — apply it with the `font-heading` utility. All running text
  is Geist Sans at 400. Buttons and meta labels are Namche Shadow Mono,
  uppercase.
- **The primary action is an ink pill, not a brand colour.** The default
  Button variant paints `--gaia-erebos` (near-black) with `--gaia-selene`
  (paper) text and an uppercase mono label. Every variant — including quiet
  ones like `outline` and `ghost` — names its own text colour explicitly,
  because the design tokens style bare `<a>` elements with an underline and
  ink colour; a variant that only inherits loses its label when rendered as a
  link through `render`.
- **One stroke, few shapes.** A 0.5px hairline is the only rule weight.
  Controls sit at radius 10, cards at radius 12, buttons are full pills.
- **No elevation, ever.** The system defines no box-shadow. Night surfaces lift
  by getting lighter (the tokens' `--night-*` steps), never by casting a shadow.
- **Both themes are real and canonical.** The tokens ship Night: Erebos ground,
  Selene ink, opt-in via `.dark` on the root. Every component must look
  correct in both — check light and dark before calling a change done.

## Fonts

Namche Shadow (Sans and Mono) loads from `cdn.namche.ai` by default —
declared automatically by `@namche/design-tokens`, nothing to wire up. For
an offline build, the same family ships as the npm package
`@namche/namche-shadow` instead. Geist is self-hosted through the `geist`
npm package via `next/font` in every case.

## Reference

Full page index follows. Each entry's Markdown is also served directly at
`/llms.mdx/docs/<path>/content.md`, e.g.
`/llms.mdx/docs/components/button/content.md`. `/llms-full.txt`
concatenates every page's Markdown into one document.

# Docs

- [NAMCHE UI](/docs): The functional component layer for NAMCHE products and tools.
- [Installation](/docs/installation): Add NAMCHE UI to a product or tool.
- [HTML & CSS](/docs/html-css): The zero-build lane — NAMCHE for server-rendered HTML, no React required.
- [Astro](/docs/astro): NAMCHE in an Astro site — CSS lane for content, React islands where needed.
- Components
  - [Components](/docs/components): Every component in the @namche registry, grouped by what it's for.

  - **Form**
  - [Button](/docs/components/button): The primary action control — an ink pill with an uppercase mono label.
  - [Button Group](/docs/components/button-group): Groups related buttons into one visually continuous control, merging borders and corner radii between them.
  - [Checkbox](/docs/components/checkbox): A binary control, built on Base UI's Checkbox primitive, for toggling a single option on or off.
  - [Combobox](/docs/components/combobox): A searchable, filterable select composed from Base UI's Combobox primitive and the input-group pieces.
  - [Command](/docs/components/command): A filterable command list, used inline or inside a dialog as a keyboard-driven command palette.
  - [Field](/docs/components/field): Layout primitives for composing labels, descriptions, and errors around form controls with consistent spacing.
  - [Input](/docs/components/input): A single-line text input styled to the design system's control conventions.
  - [Input Group](/docs/components/input-group): Wraps an input or textarea with prefix/suffix addons — icons, text, or buttons — inside one bordered control.
  - [Input OTP](/docs/components/input-otp): A segmented one-time-passcode input, built on the input-otp library, for confirming sensitive actions.
  - [Label](/docs/components/label): An accessible label bound to a form control, with automatic disabled-state styling via peer/group selectors.
  - [Radio Group](/docs/components/radio-group): A set of mutually exclusive options, such as a deployment region or rollout strategy.
  - [Select](/docs/components/select): A dropdown for choosing one value from a list, such as a GPU type or region.
  - [Slider](/docs/components/slider): A draggable control for picking a numeric value or range, such as autoscaling limits.
  - [Switch](/docs/components/switch): A binary on/off control, typically for notification or feature toggles.
  - [Textarea](/docs/components/textarea): A multi-line text input for longer freeform content, such as an incident note.
  - [Toggle](/docs/components/toggle): A two-state button that can be pressed or unpressed, for standalone options like pinning or auto-refresh.
  - [Toggle Group](/docs/components/toggle-group): A connected set of toggle buttons for a single choice, such as view density.
  - [Calendar](/docs/components/calendar): A date picker built on react-day-picker, styled to match the rest of the system's controls.

  - **Overlay**
  - [Alert Dialog](/docs/components/alert-dialog): A modal that interrupts the user to confirm a destructive or irreversible action.
  - [Dialog](/docs/components/dialog): A modal window layered over the page for a focused task, dismissible via overlay, Escape, or its own close button.
  - [Drawer](/docs/components/drawer): A vaul-style panel that swipes in from an edge of the viewport, built for touch and mobile layouts.
  - [Sheet](/docs/components/sheet): A panel that slides in from an edge of the viewport to show detail or a form alongside the page.
  - [Popover](/docs/components/popover): A click-triggered panel anchored to a control, for content that needs more room than a tooltip.
  - [Hover Card](/docs/components/hover-card): A preview card that opens on hover or focus, for showing detail about a link or reference without navigating.
  - [Tooltip](/docs/components/tooltip): A short label that appears on hover or focus to clarify an icon or truncated control.
  - [Context Menu](/docs/components/context-menu): A menu that opens at the pointer on right-click, scoped to the element it wraps.
  - [Dropdown Menu](/docs/components/dropdown-menu): A menu of actions or navigation anchored to a trigger, opened by click.
  - [Menubar](/docs/components/menubar): A row of always-visible menus for a dashboard's primary actions, like a desktop app's menu bar.

  - **Navigation**
  - [Breadcrumb](/docs/components/breadcrumb): A trail of links back up the workspace hierarchy, ending in the current page.
  - [Navigation Menu](/docs/components/navigation-menu): A top-level app menu with hoverable triggers that open a positioned dropdown panel.
  - [Pagination](/docs/components/pagination): Page-through controls for long tables, built from links styled as buttons.
  - [Sidebar](/docs/components/sidebar): A collapsible app-frame sidebar with groups, menus and a mobile sheet fallback.
  - [Tabs](/docs/components/tabs): Switches between panels of content sharing the same space.

  - **Data display**
  - [Avatar](/docs/components/avatar): A person's picture with an initials fallback, plus grouping and status-badge helpers.
  - [Badge](/docs/components/badge): A compact status pill for build state, plan tier, and other short labels.
  - [Card](/docs/components/card): A hairline-ringed surface for grouping related content, with header, action, and footer slots.
  - [Carousel](/docs/components/carousel): A swipeable, keyboard-navigable slide track built on Embla.
  - [Chart](/docs/components/chart): A themed wrapper around Recharts, driven by a ChartConfig and the --chart-1..5 tokens.
  - [Item](/docs/components/item): A flexible list-row primitive for feeds, menus, and settings rows.
  - [Kbd](/docs/components/kbd): A small key-cap label for documenting keyboard shortcuts.
  - [Table](/docs/components/table): A plain HTML table with hairline rows and the system's type scale.
  - [Aspect Ratio](/docs/components/aspect-ratio): Constrains a child to a fixed width-to-height ratio, for media and chart containers.

  - **Feedback**
  - [Alert](/docs/components/alert): An inline banner for status, warnings, and errors — card surface, hairline border.
  - [Empty](/docs/components/empty): A placeholder for a list or panel with nothing in it yet, with room for a call to action.
  - [Progress](/docs/components/progress): A determinate progress bar for rollouts, downloads, and other measurable operations.
  - [Skeleton](/docs/components/skeleton): A pulsing placeholder shape for content that is still loading.
  - [Sonner](/docs/components/sonner): Toast notifications, themed for NAMCHE and mapped to light/dark automatically.
  - [Spinner](/docs/components/spinner): An inline loading indicator for buttons and in-flight status text.

  - **Layout**
  - [Accordion](/docs/components/accordion): A set of collapsible panels, one at a time or several at once.
  - [Collapsible](/docs/components/collapsible): A single panel that toggles open and closed.
  - [Resizable](/docs/components/resizable): Panels that split a layout and resize by dragging the handle between them.
  - [Scroll Area](/docs/components/scroll-area): A scrollable region with a styled scrollbar instead of the browser's native one.
  - [Separator](/docs/components/separator): A thin rule that divides content, horizontally or vertically.