# Neo design system

## Status and ownership

- Status: early preview
- Token source: `/neo/tokens.json`
- Component catalog: `/neo/catalog.json`
- Canonical platform: standards-based Web (HTML, CSS, JavaScript)
- Maintained adapter: React
- Themes: dark and light

## Principles

1. **The Web is the reference** — Native semantics and browser behavior define each component. Framework adapters preserve that contract.
2. **Material serves hierarchy** — Glass is used where changing color or imagery should remain visible through structure. It is not a decorative effect applied everywhere.
3. **Source stays owned** — Consumers copy readable source into their project. There is no required Neo runtime.
4. **Requirements travel with code** — Each manifest includes use guidance, accessibility requirements, files, dependencies, and supported targets.
5. **Atmosphere never reduces utility** — Text contrast, keyboard behavior, reduced motion, and a non-blur fallback remain mandatory.
6. **Color is optional** — Neo is monochrome by default. A configurable accent is reserved for selection, progress, and primary data emphasis; danger and success colors appear only when they carry meaning.

## Architecture

Neo has four portable layers:

1. DTCG-compatible design tokens describe semantic light and dark roles.
2. One shared CSS file defines the visual vocabulary and progressive glass material.
3. Canonical Web snippets and small JavaScript behavior modules define semantics.
4. Thin framework adapters map framework state and events onto the same markup and class contract.

The machine catalog links to a manifest for every component. A manifest identifies the canonical Web files, optional behavior module, React adapter, dependencies, and behavioral contract. This format is intentionally simple JSON and is not tied to a package manager or framework CLI.

The public documentation and static component catalog live at `https://neo.voorhees.dev`. MCP clients can discover the same evolving library through `https://mcp.neo.voorhees.dev/mcp`; the MCP server is an optional transport rather than a replacement for the inspectable manifests.

## Accent configuration

Neo works without a brand color. To opt in, override the semantic accent pair after the shared stylesheet. Choose values that maintain at least 4.5:1 contrast in their theme; `--neo-on-accent` is used for marks or text placed on the accent.

```css
:root {
  --neo-accent: #9b87f5;
  --neo-on-accent: #111111;
}

.light {
  --neo-accent: #6548c7;
  --neo-on-accent: #ffffff;
}
```

The explorer palette control adjusts arbitrary custom colors toward white or black until they meet this contrast floor. Accent overrides intentionally do not recolor glass, borders, primary buttons, or semantic danger/success states.

## Component inventory

Neo currently publishes 40 components across eight functional groups:

- **Surfaces:** Glass surface, Accordion
- **Controls:** Button, Icon button, Slider, Text field, Textarea, Select, Checkbox, Radio group, Segmented control, Search field, Switch
- **Navigation:** Tabs, Breadcrumb, Pagination
- **Overlays:** Dialog, Drawer, Dropdown menu, Tooltip
- **Feedback:** Alert, Progress, Toast, Spinner, Skeleton, Empty state
- **Data display:** Avatar, Badge, Table
- **Data visualization:** Stat, Sparkline, Line chart, Bar chart, Donut chart, Gauge, Heatmap, Data legend
- **Utilities:** Key hint, Separator, Code block

Every catalog entry includes its canonical Web file, maintained React adapter, shared styles, dependencies, use guidance, required behavior, and known misuses.

## Accessibility baseline

- Native elements are preferred whenever they express the interaction.
- Interactive targets are at least 44px.
- Focus is visible in both themes.
- Meaning is never encoded by color alone.
- Motion is suppressed with `prefers-reduced-motion`.

## Motion and feedback

Neo uses motion to confirm state, not decorate it. Interactive controls share three duration tokens: 120ms for press feedback, 180ms for state changes, and 260ms for overlays or larger spatial changes. Hover movement is limited to one pixel, press states compress slightly, and non-interactive surfaces remain still.

Menus, dialogs, drawers, and toasts enter from their physical origin with short opacity and position changes. Continuous controls such as sliders update without a trailing animation while their thumb provides immediate press feedback. All motion has a `prefers-reduced-motion` equivalent, and no state is communicated by motion alone.
- Glass falls back to an opaque readable surface when backdrop filtering is unavailable.

## Adding another framework

Start from the component's Web markup and contract. Preserve element semantics, class names, keyboard behavior, state names, and output values. The adapter owns framework state only; the shared stylesheet continues to own visual presentation.