# Nerio

Nerio is an open-source, source-first design system for modern digital products. It is universal and domain-agnostic: suitable for SaaS applications, consumer products, marketplaces, dashboards, internal tools, content platforms, creator tools, productivity products, and data-rich workflows.

Nerio has two product layers: Nerio Core and Nerio Pro.

Nerio Core is the open-source foundation: tokens, themes, primitive and base UI components, public docs, public registry, CLI, and public MCP/component discovery.

Nerio Pro is the paid advanced layer: complex product components, templates, premium themes, Figma assets, advanced registry items, and Pro MCP/AI tooling.

Core = building blocks. Pro = product-ready solutions.

The canonical Core UI implementation and review standard is `docs/core-ui-best-practices.md`. Apply
its four-owner model: the maintainer owns visual-language values and character, Core owns reusable
technical primitive contracts, consumers own application policy and composition, and Pro owns
reusable product-ready workflows. Before adding a prop, variant, size, state, slot, event, or
imperative handle, prefer existing composition, semantic/component tokens, consumer `className` or
source ownership, and meaningful slots in that order. Admit public API only for a stable,
domain-agnostic semantic or behavioral need with multiple independent use cases, preserved
accessibility and entrypoint boundaries, and justified maintenance cost. Classify styling decisions
as system rules, family rules, or reasoned component exceptions.

The maintainer-approved Nerio 1.0 visual language is documented in
`docs/visual-language-1-0.md`, with recurring inconsistencies grouped by system cause in
`docs/audits/visual-language-1-0.md`. It is the implementation-ready art-direction contract for
color and surfaces, typography, geometry and spacing, interaction states, motion, iconography, and
signature details. It does not introduce a new runtime axis or silently change public APIs.

Public documentation lives under `/docs`, and `/templates` embeds the app-local universal workspace
demo. The demo proves composition but is not a released Core template or Pro distribution surface.
Legacy `/docs/compositions/*` aliases
redirect to unindexed `/docs/blocks/*` stress-test routes and are not part of public Core discovery.

Data Display and Feedback follow one neutral-first hierarchy. Card is a generic raised white or
black surface with a soft shadow and no default border; secondary grouping and TableContainer use
flat muted surfaces. Table keeps native semantics and consumer-owned behavior while selected or
current rows combine a neutral fill with a logical-edge indicator. Avatar fallbacks use fixed
light/dark fills and overlap borders so translucent seams do not appear in groups. Alert is a flat
muted inline surface whose semantic tone is carried by its icon and complete message text. Toast is
an inverted dark glass surface with blur in every mode, neutral white copy, glass-aware controls,
and restrained semantic status icons. Stat trend text is neutral by default because Core does not
infer direction or meaning from an arbitrary string.

Navigation, Layout, and Overlays use one focus, selection, and motion language. Current navigation
stays neutral unless a compact indicator is needed; segmented Tabs use a soft selected-surface
shadow, and hover feedback resolves through shared motion tokens. Tooltip, Popover, Dropdown Menu,
Command, Dialog, and Sheet use the approved inverted dark-glass surface with white hierarchy and
blur; compact popups use smaller radii than Dialog and Sheet. Modal backdrops blur, Dialog settles
with restrained scale and opacity, and Sheet preserves the physical direction of its side. Dialog
and Sheet close controls are secondary icon Buttons, while their action footers align to the inline
end. Sidebar and Command remain low-level primitives without routing, persistence, or product search
policy.

Use `COMPONENTS.md` and `data/component-catalog.json` as the source of truth for Core/Pro component tiering.

Core `0.1.0-alpha.1` is published under the npm `alpha` tag with a signed tag and GitHub prerelease; npm `latest` intentionally remains on `0.1.0-alpha.0`. Alpha APIs may still change before 1.0. The approved Core scope is implemented with evidence-based statuses: all non-deprecated Core components are stable Core, and IconButton remains a deprecated compatibility wrapper. Pro components remain outside Core. Command Primitive owns the accessible query field, local or consumer-filtered leaf results, sound flat or grouped collections, active option, disabled navigation, selection events, and empty/loading presentation. Keyword and stable-value text affect matching only; selection writes the visible label to the controlled or uncontrolled query and form value while `onSelect` emits the stable value. CommandItem leading content owns its accessibility semantics, while decorative Nerio Icons hide themselves. Command does not own fetching, ranking, routing, global shortcuts, recent/history storage, analytics, permissions, or a complete command palette. Sidebar Primitive owns layout, physical side, controlled or uncontrolled collapse state, regions, and accessible toggles; it does not own routes, navigation data, menus, permissions, persistence, or AppShell behavior. Compose Sheet explicitly for mobile and render one interactive navigation tree per viewport. Sheet is a stable Base UI modal side-panel primitive with explicit left/right/top/bottom sides, sm/md/lg sizes, neutral SheetClose composition, a safe-area-aware default close, shared enter/exit motion contracts, compound slots, and no app navigation or settings behavior. Dialog keeps its icon close control localizable through `closeLabel` while preserving the default accessible name. RadioGroup supports concise data-driven `options` and compositional `RadioGroupItem` children; use composition for richer option content. A Core component should not move to `stable-core` until its API, accessibility, tokens, registry metadata, docs, CLI fixture, MCP metadata, and validation checks are aligned.

Use primitive tokens only for raw values. Use semantic tokens such as `--n-color-surface-default`, `--n-color-text-primary`, `--n-color-action-primary`, `--n-color-border-default`, `--n-font-sans`, and `--n-font-mono` in product code. Components should prefer component tokens for local contracts such as `--n-button-background-primary`, `--n-input-border`, `--n-dialog-width-md`, `--n-overlay-background`, and `--n-table-cell-padding-x`.

Nerio is neutral-first and compact: use white or black primary surfaces, cool blue-gray grouping fills, whitespace between major blocks, restrained internal spacing, regular 12-14px UI typography, large concentric radii, and borderless controls by default. Adaptive controls, hover and pressed states, neutral selected surfaces, subdued borders, and grid lines use cool near-black alpha primitives in light mode and white alpha primitives in dark mode so the same semantic layer composes naturally over different surfaces. Canvas, primary surfaces, text, actions, semantic status colors, chart series, and contrast-critical roles remain opaque. Reserve the brand color for primary actions, focus, and compact justified selection indicators. Transient overlays use the inverted black-glass token family with white text, blur, and restrained elevation; placeholders may provide the compact visual prompt only when an explicit accessible name remains present.

System UI is the default Core font stack and the cross-platform system mono stack is the default technical font. Geist is the documentation brand only. Core provides System, Geist, Inter, IBM Plex, Manrope, Source Sans 3, and Space Grotesk scoped token recipes; non-system families remain consumer-loaded, no font files are bundled, and components must consume font tokens rather than hard-coded families.

Nerio separates theme, mode, and density. Theme is selected with `data-theme="purple"`, `data-theme="blue"`, `data-theme="green"`, `data-theme="orange"`, `data-theme="red"`, `data-theme="neutral"`, or a custom product theme. Mode is selected with `data-mode="system"`, `data-mode="light"`, or `data-mode="dark"`. Density is selected with `data-density="comfortable"` or `data-density="compact"`.

Primitive tokens are immutable raw values across theme, mode, and density selectors. Runtime selectors remap semantic and component contracts instead. The docs header exposes System, Light, and Dark through one compact icon menu, follows OS preference changes while System is selected, and restores appearance before hydration.

Default runtime attributes: `data-theme="purple" data-mode="system" data-density="comfortable"`.

Do not create or use combined theme names such as `purple-light`, `purple-dark`, `neutral-light`, `neutral-dark`, `blue-light`, `blue-dark`, `red-light`, or `red-dark`. Do not create vertical-specific Core preset names such as `fintech-blue`; use generic brand color names.

Font, radius, motion, spacing, shadow/elevation, and contrast are token-customizable in v1, but they are not separate runtime axes. Do not introduce `data-font`, `data-radius`, `data-motion`, `data-contrast`, or `data-scale` unless a later architecture decision explicitly promotes them. Typography presets are CSS token recipes, not runtime attributes; customize typography with `--n-font-sans`, `--n-font-mono`, `--n-font-sans-system`, and scoped product overrides.

Brand color is a restrained accent. Use it for primary actions, selection, active states, focus, links, small progress signals, the primary chart series, and brand moments. Do not use brand color for broad page backgrounds, routine icons, card backgrounds, standard borders, or secondary actions.

The Nerio 1.0 foundation uses pure white light foundations, pure black dark foundations, cool
alpha-neutral adaptive layers, generous role-based radii, compact 14px typography, and tokenized
motion. Use opaque neutrals for contrast-critical or overlap-isolated geometry such as Avatar
boundaries. Use semantic surface and border aliases instead of consuming alpha primitives directly.
The implementation reference is `/docs/foundations/visual-language`.

Core motion remains CSS-first. Install `motion` and use the optional client-only
`@nerio-ui/adapters/motion` entrypoint only for coordinated presence, interruption, layout
continuity, gestures, or product-level sequencing. `NerioMotionConfig` follows the user's reduced
motion preference; the preferred loading path is strict `LazyMotion` plus `m` and
`domAnimation`, with `domMax` reserved for layout, pan, or drag. Unrelated adapters and
`@nerio-ui/ui` resolve no Motion runtime.

Prefer composition, explicit slots, semantic HTML, visible focus states, and accessible labels. Use Nerio's icon adapter for Lucide or custom SVG React components.

Card anatomy is `Card`, optional `CardVisual`, `CardHeader`, `CardTitle`, `CardDescription`, optional `CardAction`, `CardContent`, and `CardFooter`. `CardVisual` accepts generic visual content and only supports `inset` or `bleed` placement. `CardAction` is for surface Cards only; linked Cards must not contain interactive descendants.

Package entrypoints: import static Core components and utilities from `@nerio-ui/ui`, interactive components from `@nerio-ui/ui/client`, styles from `@nerio-ui/ui/styles.css`, and icons or icon types from `@nerio-ui/adapters/icons`. The adapter package has no aggregating root export; optional integrations use `@nerio-ui/adapters/table`, `@nerio-ui/adapters/charts`, `@nerio-ui/adapters/forms`, or `@nerio-ui/adapters/schema` with the matching peer installed. Core packages ship TypeScript source, so Next.js consumers list the Nerio packages they use in `transpilePackages`. SidebarHeader, SidebarContent, SidebarFooter, SidebarInset, and Icon are server-safe; SidebarProvider, Sidebar, SidebarTrigger, SidebarRail, and useSidebar import from the client entrypoint. SidebarContent forwards an HTMLDivElement ref, SidebarInset preserves stable div or main refs, and SidebarRail is centered within its bounded hit area. Example: `import { Settings } from "@nerio-ui/adapters/icons"; import { Alert, Breadcrumbs, Card, Icon, List, Pagination, SidebarContent, SidebarInset, Table } from "@nerio-ui/ui"; import { Button, Select, Dialog, Sheet, Sidebar, SidebarProvider, SidebarTrigger, ToastProvider } from "@nerio-ui/ui/client"; import "@nerio-ui/ui/styles.css";`. Use Button's `link` variant with a native anchor render target for text-level navigation. Source-installed registry components keep local paths such as `@/components/nerio/components/button`.

Registry usage: `nerio init` creates `nerio.json`, `nerio list` lists component names, titles, and categories, `nerio info <component>` shows registry metadata, `nerio doctor` validates configuration and registry metadata, and `nerio add <component>` installs the selected source item plus registry dependencies. Use `nerio add input --dry-run` to preview files before writing. Registries may be local filesystem paths or HTTP URLs. Existing changed files are not overwritten unless `--overwrite` is explicitly provided.

`IconButton` remains installable as a deprecated compatibility alias until the next major release. New code must use `Button` icon-only mode: `<Button icon={Settings} aria-label="Workspace settings" />`.

Icon owns decorative or meaningful ARIA semantics and keeps every SVG non-focusable. Custom SVG components implement generic `IconSvgProps`; use `lucideAbsoluteStrokeWidth` only for Lucide fixed-stroke behavior. The older `absoluteStrokeWidth` Icon prop is a deprecated alpha alias. Item and ItemGroup compose refs already attached to `render` elements with forwarded refs. Pagination preserves `data-current` for static current pages without `href` or `onSelect`. TableContainer creates a focusable region only for `focusable={true}` plus a non-empty runtime `aria-label` or `aria-labelledby`; Table row states apply only to `tbody`, and `aria-current="false"` remains neutral.

The read-only MCP server uses the official Model Context Protocol stdio transport. Its tools are `list_components`, `get_component`, and `get_component_usage`; all responses come from the same Nerio registry metadata used by the CLI. `get_component_usage` returns usage, dependencies, registry dependencies, install files, Base UI primitives, slots, variants, states, required tokens, and accessibility guidance.

Registry `requiredTokens` should expose public customization points, preferably component aliases rather than internal implementation details. Registry `requiredTokens` and public component reference token chips must point to real `--n-*` CSS variables in `@nerio-ui/tokens`; `pnpm validate:docs` checks this contract.

Progress is a server-safe Core component for completion of one task that takes time. It requires exactly one accessible name through a visible `label`, `aria-label`, or `aria-labelledby`; finite values are clamped within normalized `min` and `max` range values, while indeterminate Progress omits `aria-valuenow`. Use `valueText` for localized text such as "3 of 5 records imported". Progress is read-only, not a slider, and not a Meter for static scores, capacity, battery, or health values. Use Alert, Badge, or Toast for task outcomes.

Toast has separate static presentation and managed stack forms. Static Toast is presentation-only; managed actions and icon-only dismissal use Button variants. The managed viewport is bottom-centered. Collapsed cards scale and step upward behind the frontmost toast, then expand upward while preserving reading order. Use `ToastProvider`, `ToastViewport`, and `useToastManager` for transient application feedback. Duplicate IDs update in place, `timeout={0}` creates an intentionally persistent toast, low priority is polite, and high priority is reserved for urgent failures. Managed timers preserve remaining duration during hover, keyboard focus, or window blur. The viewport inherits document direction on the first interactive render, follows root `dir` changes, and resolves `inline-start` and `inline-end` for LTR or RTL; an explicit `direction` prop wins immediately. A unified enter, expand, swipe, and dismissal coordinate system preserves offsets in all four physical directions, including reduced motion. The viewport also supports safe areas, compact density, F6 keyboard entry, localized labels, and a dismiss button. Use one provider per stack; use `createToastManager` only for an intentionally independent provider. Toast is not a notification inbox, persistent history, or background-job manager.

Input is a server-safe thin native control for `text`, `email`, `password`, `search`, `tel`, `url`, and `number` values. Use `size="sm" | "md" | "lg"`, use `htmlSize` for the native HTML size attribute, and compose labels, descriptions, and messages through `Field`. Input does not own validation, visual prefix/suffix content, search results, password visibility, parsing, or date workflows. Use InputGroup for a shared Input surface with explicit `InputGroupAddon placement="start" | "end"`; addons do not provide the input's accessible name, and interactive addons remain independently accessible. SearchInput, PasswordInput, Calendar, and a basic single-date DatePicker are future Core candidates; date ranges, date-time and preset workflows, global/entity/advanced search, CommandPalette, and FilterBar belong to Pro.

Nerio Core uses Tailwind CSS v4-first component authoring while `--n-*` variables remain the canonical visual value layer. Package consumers import `@nerio-ui/tokens/tailwind.css` and explicitly register `@nerio-ui/ui/src` with Tailwind `@source`; source-installed TSX is detected from the consumer project. Nerio packages do not inject Tailwind Preflight. All Core components use this contract; residual CSS is limited to named keyframes plus scoped Nerio-class box sizing and native-control font inheritance for consumers without Preflight.

AI agents should select the smallest component set that matches the workflow, avoid unnecessary domain-specific assumptions in Core, use Pro for advanced product workflows, keep examples universal unless the task explicitly asks for a vertical, and never introduce shadcn/ui, Radix UI, Headless UI, Ariakit, or overlapping primitive libraries.