# Xenon Design System (llms.txt)

> Xenon is a minimalistic, hairline-crisp UI kit for web (React DOM) and React Native (Expo), built from one shared token geometry and two renderers.

## Core Principles & Hard Design Rules
- **Pure Canvas**: No gradients. No shadows of any kind (CSS box-shadow, iOS shadow*, Android elevation). Depth comes solely from hairlines (1px borders) and tonal layering.
- **1px Hairline Precision**: All borders, separators, and dividers are strictly 1px (StyleSheet.hairlineWidth on native). Never use detached browser focus outlines (no outline-offset: 2px).
- **Fluid Spring Kinematics**: Zero instant/snappy transitions. All disclosures, active states, expansions, and dismissals use physics springs (springSoft / springSnappy) or cubic-bezier(0.2, 0, 0, 1).
- **No Emoji & Strict Iconography**: No emoji or raw ASCII/unicode characters for UI chrome (+, -, x, !, >). Icons are strictly Phosphor Thin (weight 200/thin).
- **Typographic Restraint**: Font weights are strictly 200, 300, or 400. Never 500 or above.
- **Don Norman Invariant**: Every component strictly embodies the 7 Norman principles: Affordances, Signifiers, Mapping, Feedback (<100ms), Conceptual Models, Architectural Constraints, and Discoverability.
- **Radius Scale**: Discrete radius stops R0 (0px), R1 (4px), R2 (8px), R3 (12px), R4 (16px), R5 (20px - default), R6 (9999px pill). Form inputs maintain architectural geometry (R1-R2 / 6-8px), pills are reserved for buttons and search bars.

## Agent Quickstart
Xenon's design rules are as binding as its components. Before writing UI, read the rules (AGENTS.md in the package, or /llms-full.txt which embeds the full guidelines).

```bash
# inside an existing React 19 app (Vite or Next.js App Router); if none exists:
#   npm create vite@latest my-app -- --template react-ts
npx @xenon-kit/cli init
```

`init` installs `@xenon-kit/web` and `@phosphor-icons/react`, imports `@xenon-kit/web/styles.css`, wraps the app in `XenonProvider`, and writes AGENTS.md + CLAUDE.md with the binding design rules.

Manual setup:
```bash
npm install @xenon-kit/web @phosphor-icons/react
```
```tsx
import "@xenon-kit/web/styles.css";
import { XenonProvider } from "@xenon-kit/web";

<XenonProvider defaultTheme="dark" defaultAccent="lime" defaultRadius={5}>{children}</XenonProvider>
```

## Agent Resources
- Rules (offline, version-locked): `node_modules/@xenon-kit/web/AGENTS.md` and `node_modules/@xenon-kit/web/docs/`
- Exact props: `node_modules/@xenon-kit/web/dist/index.d.ts`
- Full spec + guidelines: https://xenon.hi-ashwin.xyz/llms-full.txt
- Registry index: https://xenon.hi-ashwin.xyz/r
- Component detail (props, usage): https://xenon.hi-ashwin.xyz/r/<component>.json

## Component Registry (26 Components)

### Button (`button`)
- **Category**: Primitives
- **Description**: Signature pill-first action control with physics-based spring squash interaction (0.98 scale on press).
- **Accessibility**: Rendered as native button element with role='button', supports Space and Enter keys, manages disabled and aria-busy states.
- **Registry JSON**: https://xenon.design/r/button.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Button } from "@xenon-kit/web";

export function Example() {
  return (
    <Button variant="accent" size="md">
      Confirm Action
    </Button>
  );
}
```

### IconButton (`icon-button`)
- **Category**: Primitives
- **Description**: Concentric circular action button strictly optimized for Phosphor Thin icons with mandatory accessible labeling.
- **Accessibility**: Enforces non-empty ariaLabel prop, rendered with role='button' and accessible screen reader name.
- **Registry JSON**: https://xenon.design/r/icon-button.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { IconButton, Icon } from "@xenon-kit/web";
import { Gear } from "@phosphor-icons/react";

export function Example() {
  return (
    <IconButton ariaLabel="Settings" variant="subtle" size="md">
      <Icon size="sm">
        <Gear />
      </Icon>
    </IconButton>
  );
}
```

### ButtonGroup (`button-group`)
- **Category**: Primitives
- **Description**: Grouped capsule action bar where child buttons share outer bounds and internal 1px hairline dividers.
- **Accessibility**: Wraps buttons in a role='group' container with optional aria-label.
- **Registry JSON**: https://xenon.design/r/button-group.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { ButtonGroup, Button } from "@xenon-kit/web";

export function Example() {
  return (
    <ButtonGroup variant="outline" size="sm">
      <Button>Cut</Button>
      <Button>Copy</Button>
      <Button>Paste</Button>
    </ButtonGroup>
  );
}
```

### Surface (`surface`)
- **Category**: Primitives
- **Description**: Base structural container supporting concentric radius inheritance and Apple HIG Liquid Glass floating layers.
- **Accessibility**: Semantic generic container, transparent to screen readers.
- **Registry JSON**: https://xenon.design/r/surface.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Surface, Text } from "@xenon-kit/web";

export function Example() {
  return (
    <Surface variant="subtle" padding={24}>
      <Text>Concentric surface layer</Text>
    </Surface>
  );
}
```

### Typography (Text & Heading) (`typography`)
- **Category**: Primitives
- **Description**: Apple HIG calibrated Geist Sans typography system restricted strictly to light weights (200, 300, 400).
- **Accessibility**: Emits semantic h1-h6 headings and p/span elements with appropriate text hierarchy.
- **Registry JSON**: https://xenon.design/r/typography.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Heading, Text } from "@xenon-kit/web";

export function Example() {
  return (
    <>
      <Heading level={1} weight={200}>Minimalist Architecture</Heading>
      <Text styleKey="body" tone="muted" weight={300}>Geist typography with negative space.</Text>
    </>
  );
}
```

### Input (`input`)
- **Category**: Form Controls
- **Description**: Restrained architectural text field (6-8px radius, 12px optical padding) avoiding stadium pill shapes.
- **Accessibility**: Accessible input element supporting ARIA descriptions, errors, and clear triggers.
- **Registry JSON**: https://xenon.design/r/input.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Input } from "@xenon-kit/web";

export function Example() {
  return <Input placeholder="Project identifier..." size="md" clearable />;
}
```

### Field (`field`)
- **Category**: Form Controls
- **Description**: Persistent structural wrapper binding labels, helper annotations, and error callouts to input controls.
- **Accessibility**: Connects label and input via htmlFor/id, injects aria-describedby for errors and helper texts.
- **Registry JSON**: https://xenon.design/r/field.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Field, Input } from "@xenon-kit/web";

export function Example() {
  return (
    <Field label="Domain Name" helpText="Enter your custom subdomain">
      <Input placeholder="workspace.xenon.design" size="md" />
    </Field>
  );
}
```

### Textarea (`textarea`)
- **Category**: Form Controls
- **Description**: Architectural multi-line text input with smooth auto-expansion, character limit tracking, and hairline borders.
- **Accessibility**: Standard textarea element with full keyboard and screen reader accessibility.
- **Registry JSON**: https://xenon.design/r/textarea.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Textarea } from "@xenon-kit/web";

export function Example() {
  return <Textarea placeholder="Provide design specifications..." rows={4} maxLength={500} />;
}
```

### Checkbox (`checkbox`)
- **Category**: Form Controls
- **Description**: Restrained geometric square checkbox with crisp Phosphor Thin checkmark and indeterminate state support.
- **Accessibility**: Native role='checkbox', supports aria-checked='mixed', toggled via Space bar.
- **Registry JSON**: https://xenon.design/r/checkbox.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Checkbox } from "@xenon-kit/web";

export function Example() {
  return <Checkbox label="Accept terms and specifications" defaultChecked />;
}
```

### Switch (`switch`)
- **Category**: Form Controls
- **Description**: Apple HIG calibrated sliding toggle with physics spring release and native haptic click feedback.
- **Accessibility**: Role='switch', announces aria-checked state, operated with Space and Enter keys.
- **Registry JSON**: https://xenon.design/r/switch.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Switch } from "@xenon-kit/web";

export function Example() {
  return <Switch label="Liquid Glass Blur" defaultChecked />;
}
```

### Slider (`slider`)
- **Category**: Form Controls
- **Description**: Precision track slider with Apple spring thumb response, live value tooltip, and discrete stop ticks.
- **Accessibility**: Role='slider', exposes aria-valuemin, aria-valuemax, and aria-valuenow, controllable via arrow keys.
- **Registry JSON**: https://xenon.design/r/slider.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Slider } from "@xenon-kit/web";

export function Example() {
  return <Slider min={0} max={6} step={1} defaultValue={3} size="md" />;
}
```

### SegmentedControl (`segmented-control`)
- **Category**: Form Controls
- **Description**: Sliding pill segmented group with animated indicator and spring squash transition across items.
- **Accessibility**: Role='radiogroup' or 'tablist' with roving focus and arrow key navigation.
- **Registry JSON**: https://xenon.design/r/segmented-control.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { SegmentedControl } from "@xenon-kit/web";

export function Example() {
  return (
    <SegmentedControl
      options={[
        { value: "preview", label: "Preview" },
        { value: "code", label: "Code" },
      ]}
      defaultValue="preview"
      size="md"
    />
  );
}
```

### Navbar & GlassBar (`navbar`)
- **Category**: Navigation
- **Description**: Top navigation chrome featuring adaptive scroll elevation for Navbar and permanent Liquid Glass for GlassBar.
- **Accessibility**: Semantic <nav> element with role='navigation' and landmark identification.
- **Registry JSON**: https://xenon.design/r/navbar.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { GlassBar, Text } from "@xenon-kit/web";

export function Example() {
  return (
    <GlassBar bordered>
      <Text weight={400}>Xenon System</Text>
    </GlassBar>
  );
}
```

### Sidebar (`sidebar`)
- **Category**: Navigation
- **Description**: Background-less architectural sidebar navigation with collapsible rail mode, groups, and soft dividers.
- **Accessibility**: Semantic landmark <nav aria-label='Sidebar'> with accessible expandable groups.
- **Registry JSON**: https://xenon.design/r/sidebar.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Sidebar, SidebarGroup, SidebarItem, SidebarDivider } from "@xenon-kit/web";

export function Example() {
  return (
    <Sidebar variant="docked">
      <SidebarGroup label="Components">
        <SidebarItem active>Button</SidebarItem>
        <SidebarItem>Input</SidebarItem>
      </SidebarGroup>
      <SidebarDivider />
    </Sidebar>
  );
}
```

### Tabs (`tabs`)
- **Category**: Navigation
- **Description**: Accessible view switcher supporting pill capsule and sliding hairline underline modes with roving keyboard focus.
- **Accessibility**: Strict WAI-ARIA Tabs pattern (role='tablist', role='tab', role='tabpanel') with Home, End, and Arrow navigation.
- **Registry JSON**: https://xenon.design/r/tabs.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@xenon-kit/web";

export function Example() {
  return (
    <Tabs defaultValue="account" variant="pill">
      <TabsList>
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="security">Security</TabsTrigger>
      </TabsList>
      <TabsContent value="account">Account configuration</TabsContent>
    </Tabs>
  );
}
```

### Dialog (`dialog`)
- **Category**: Overlays
- **Description**: Centered modal surface with background scrim, focus restoration, focus trapping, and Apple spring dismissal.
- **Accessibility**: Role='dialog', aria-modal='true', trap focus inside dialog, dismisses on Escape key.
- **Registry JSON**: https://xenon.design/r/dialog.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Button } from "@xenon-kit/web";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="filled">Open Modal</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Confirmation</DialogTitle>
        </DialogHeader>
        <p>Proceed with the requested workspace deployment?</p>
      </DialogContent>
    </Dialog>
  );
}
```

### Sheet (`sheet`)
- **Category**: Overlays
- **Description**: Slide-over drawer on web and gesture-driven bottom sheet with tactile drag handle on React Native.
- **Accessibility**: Accessible drawer dialog with focus trapping and ESC dismissal.
- **Registry JSON**: https://xenon.design/r/sheet.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Sheet, SheetTrigger, SheetContent, Button } from "@xenon-kit/web";

export function Example() {
  return (
    <Sheet>
      <SheetTrigger asChild>
        <Button variant="outline">Open Sheet</Button>
      </SheetTrigger>
      <SheetContent side="right">
        <h3>Workspace Details</h3>
      </SheetContent>
    </Sheet>
  );
}
```

### DropdownMenu (`dropdown-menu`)
- **Category**: Overlays
- **Description**: Hairline contextual action menu with openOnHover option, keyboard navigation, groups, and shortcuts.
- **Accessibility**: Strict WAI-ARIA Menu pattern (role='menu', role='menuitem') with roving tabIndex.
- **Registry JSON**: https://xenon.design/r/dropdown-menu.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, Button } from "@xenon-kit/web";

export function Example() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">Options</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem shortcut="⌘S">Save</DropdownMenuItem>
        <DropdownMenuItem shortcut="⌘E">Export</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}
```

### Select (`select`)
- **Category**: Overlays
- **Description**: Architectural custom listbox on web and native picker sheet on Expo with dynamic radius matching global tokens.
- **Accessibility**: Role='combobox' / role='listbox' with ARIA expanded and active-descendant management.
- **Registry JSON**: https://xenon.design/r/select.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Select, SelectTrigger, SelectContent, SelectItem } from "@xenon-kit/web";

export function Example() {
  return (
    <Select defaultValue="pro" size="md">
      <SelectTrigger />
      <SelectContent>
        <SelectItem value="starter">Starter Plan</SelectItem>
        <SelectItem value="pro">Pro Architect</SelectItem>
      </SelectContent>
    </Select>
  );
}
```

### CommandPalette (`command-palette`)
- **Category**: Overlays
- **Description**: Global quick-launcher overlay triggered by ⌘K with keyboard arrow navigation and categorized action groups.
- **Accessibility**: ARIA combobox with full keyboard roving focus, live filtered search announcements.
- **Registry JSON**: https://xenon.design/r/command-palette.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { CommandPalette } from "@xenon-kit/web";

export function Example() {
  return (
    <CommandPalette
      open={isOpen}
      onOpenChange={setOpen}
      items={[
        { id: "1", label: "Button", group: "Primitives" },
        { id: "2", label: "Select", group: "Overlays" },
      ]}
    />
  );
}
```

### Badge (`badge`)
- **Category**: Feedback & Data Display
- **Description**: Compact status indicator with acid accent tones, subtle neutral styles, and optional live pulse dot.
- **Accessibility**: Screen-reader readable status tag, aria-hidden dot indicator.
- **Registry JSON**: https://xenon.design/r/badge.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Badge } from "@xenon-kit/web";

export function Example() {
  return <Badge tone="accent" variant="subtle" dot>Online</Badge>;
}
```

### Alert (`alert`)
- **Category**: Feedback & Data Display
- **Description**: Inline semantic status callout with Phosphor Thin icons, crisp 1px perimeter border, and restrained fill.
- **Accessibility**: Role='alert' or role='status' depending on severity tone.
- **Registry JSON**: https://xenon.design/r/alert.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Alert } from "@xenon-kit/web";

export function Example() {
  return <Alert tone="warning" variant="subtle" title="Token Deprecation">Use compiled motion tokens.</Alert>;
}
```

### Table & DataTable (`table`)
- **Category**: Feedback & Data Display
- **Description**: Outer-rounded hairline bordered table with tabular numbers, clean row highlighting, and horizontal containment.
- **Accessibility**: Full HTML table semantics (caption, thead, tbody, th with scope='col', td).
- **Registry JSON**: https://xenon.design/r/table.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Table, TableHeader, TableRow, TableHead, TableBody, TableCell } from "@xenon-kit/web";

export function Example() {
  return (
    <Table variant="bordered" fullWidth>
      <TableHeader>
        <TableRow>
          <TableHead>Prop</TableHead>
          <TableHead>Type</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell>variant</TableCell>
          <TableCell>string</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  );
}
```

### Accordion (`accordion`)
- **Category**: Feedback & Data Display
- **Description**: Apple-grade fluid grid disclosure (zero instant snappy jumps) with 280ms cubic-bezier transitions and spring caret rotation.
- **Accessibility**: Strict WAI-ARIA Accordion pattern with aria-expanded and aria-controls.
- **Registry JSON**: https://xenon.design/r/accordion.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@xenon-kit/web";

export function Example() {
  return (
    <Accordion type="single" variant="bordered">
      <AccordionItem value="item-1">
        <AccordionTrigger>What makes Xenon different?</AccordionTrigger>
        <AccordionContent>Xenon enforces mathematical concentric radii and zero shadows.</AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

### Avatar & AvatarGroup (`avatar`)
- **Category**: Feedback & Data Display
- **Description**: Circular avatar with graceful image loading, typographic initial fallbacks, and overlapping grouped clustering.
- **Accessibility**: Alt text fallback on image, aria-label describing user initials.
- **Registry JSON**: https://xenon.design/r/avatar.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { Avatar, AvatarGroup } from "@xenon-kit/web";

export function Example() {
  return (
    <AvatarGroup max={3}>
      <Avatar name="Dieter Rams" size="md" status="online" />
      <Avatar name="Jony Ive" size="md" />
    </AvatarGroup>
  );
}
```

### CodeBlock (`codeblock`)
- **Category**: Feedback & Data Display
- **Description**: Zero-dependency isomorphic syntax highlighted code block in Geist Mono with copy micro-action and line numbering.
- **Accessibility**: Accessible pre/code elements, copy button with aria-label.
- **Registry JSON**: https://xenon.design/r/codeblock.json
- **CLI Command**: `npx @xenon-kit/cli init`

```tsx
import { CodeBlock } from "@xenon-kit/web";

export function Example() {
  return <CodeBlock code="const xenon = true;" language="typescript" filename="index.ts" showLineNumbers copyable />;
}
```