# NX Design System

The complete reference for the **NX product-family** design system: foundations
(color, type, space, motion), the token model, the mark, and every shared
component. This is the *spec*; `README.md` is the *install/usage* guide and the
source files (`tokens.css`, `kit.css`, `mark.tsx`, `react.tsx`) are the
implementation. When they disagree, the source files win — update this doc.

- **One mark, one accent switch.** The nx ligature + a neutral foundation are the
  family constant; each product differs only by its **accent hue** and **wordmark**.
- **Token-driven.** Every component reads `--nx-*` custom properties, so a single
  `data-nx-product` attribute re-themes an entire subtree.
- **Alpha-aware.** Colors are stored as `R G B` channels, so any token composes
  with an opacity (`rgb(var(--nx-accent-600-rgb) / .7)` or Tailwind `bg-nx-accent/70`).
- **Quiet & flat.** Hairline borders and soft accent-tint fills carry hierarchy —
  no drop shadows.
- **certNX is standalone.** It wears the mark + tokens but not the app component
  kit (see §8).

---

## 1. Foundations

### 1.1 Color — neutrals (shared by every product) {#color}

<!-- NX:PALETTE:NEUTRALS:START -->
| Token | Hex | `R G B` | Role |
|---|---|---|---|
| `--nx-ink` | `#0B0E14` | `11 14 20` | Primary text, the mark's `n`, focus ring |
| `--nx-slate-700` | `#334155` | `51 65 85` | Strong secondary text |
| `--nx-slate-500` | `#5B6774` | `91 103 116` | Muted text, labels, placeholders |
| `--nx-slate-300` | `#CBD5E1` | `203 213 225` | Disabled / faint |
| `--nx-hairline` | `#E6E8EC` | `230 232 236` | Borders, dividers |
| `--nx-paper` | `#F7F8FA` | `247 248 250` | App background; the mark's `n` on dark |
| `--nx-white` | `#FFFFFF` | `255 255 255` | Card / input surfaces |
<!-- NX:PALETTE:NEUTRALS:END -->

### 1.2 Color — per-product accent ramps (partner-approved 2026-07-03)

Each product overrides **only** the four accent channels; everything else stays
shared. The signature is the **600**.

<!-- NX:PALETTE:ACCENTS:START -->
| Product | `--nx-accent-50` | `--nx-accent-100` | `--nx-accent-600` (signature) | `--nx-accent-700` (deep) |
|---|---|---|---|---|
| **ordNX** — violet | `#F5F3FF` | `#EDE9FE` | `#7C3AED` | `#6D28D9` |
| **CheckNX** — blue (live) | `#EFF6FF` | `#DBEAFE` | `#2563EB` | `#1D4ED8` |
| **certNX** — azure *(standalone)* | `#DCE8FE` | `#C7DBFD` | `#2F6BEB` | `#1E3A8A` |
| **FileNX** — emerald | `#ECFDF5` | `#D1FAE5` | `#047857` | `#065F46` |
| **FirmNX** — ochre | `#FAF4E8` | `#E8D6B0` | `#7A5C1E` | `#4A3712` |
| **SkyONEx** — sky | `#F0F9FF` | `#E0F2FE` | `#0369A1` | `#075985` |
| **coproNX** — terracotta | `#FDF3EE` | `#F8DCCB` | `#9A3412` | `#7A2810` |
| **hostNX** — rose | `#FFF1F2` | `#FFE4E6` | `#BE123C` | `#881337` |
| **NX** — graphite *(the suite itself)* | `#E2E7EF` | `#CBD5E1` | `#334155` | `#0B0E14` |
<!-- NX:PALETTE:ACCENTS:END -->

**The `NX` row is not a signature** (0.7.0) {#suite-accent}. `data-nx-product="nx"` themes
the family's *own* surfaces — nx-account's single sign-in and the control plane behind it —
and those belong to no product. Wearing one product's accent there would misbrand the screen
every other product redirects to; leaving `data-nx-product` unset is not the alternative, since
that falls through to `:root`, which is ordNX's violet. So this ramp is deliberately **not a new
hue**: 600 is `--nx-slate-700`, 700 is `--nx-ink`, 100 is `--nx-slate-300` — the shared neutrals
promoted into the accent channels, no accent decision required. Identity comes from the mark
instead: `<NxMark variant="nx">` paints its `x` with the family spectrum, independent of
`--nx-accent`.

It is also the one ramp whose **600 is not theme-invariant**. A hue reads on both grounds; a
neutral does not — `#334155` on the dark page `#0B0E14` is ~1.7:1, a primary button you cannot
find. Under dark theme the suite ramp therefore inverts to a light graphite (`#CBD5E1`) with a
literal ink `--nx-on-accent`, the mirror of the dark-ink `--nx-on-accent` escape the retired pointNX teal took for
the opposite reason. The table above is the light-theme ramp.


**Semantic roles of the ramp** (how the kit uses each step):

| Step | Alias | Used for |
|---|---|---|
| 50 | `--nx-accent-50` | Section/tile fills (header, KPI), ghost-button hover |
| 100 | `--nx-accent-100` | Chips/pills bg, row-icon bg, focus-ring glow, hairlines on tinted areas |
| 600 | `--nx-accent` / `--nx-accent-600` | Primary buttons, the mark's `x`, active underline, links |
| 700 | `--nx-accent-700` | Text on tint (KPI number, pill/tab text), primary-button hover |

**Contrast:** accent-600 on white and accent-700 on the accent-50/100 tints all
meet WCAG AA for the sizes used. Never put accent-600 text on an accent-50 fill
for body copy — use 700.

**Agent faces reuse the ramps — no new hues** {#agent-face-palette}. A generated
[agent face](#agent-faces) paints its tile with a ramp's **100**, its head with the
**600** and its features white; an inverted face (30 %) swaps to a white head with
**700** features. The eight palettes are the rows of the table above plus teal, the ramp of
the retired pointNX kept for faces only (sky, ordNX violet, teal, FileNX emerald, FirmNX ochre, coproNX terracotta, CheckNX
blue, suite graphite; certNX's azure is left out as it sits too close to CheckNX blue).
A face's colour says nothing about a product: it is chosen by the agent's name, so
never pick a palette "to match" the hosting app. Adding a ramp here does not add it to
the faces; `AGENT_FACE_PALETTES` in `agent-face.ts` is the list, and changing it
changes existing faces, so treat it as frozen.

### 1.3 Typography {#typography}

| Token | Stack |
|---|---|
| `--nx-font-sans` | `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
| `--nx-font-mono` | `ui-monospace, "Cascadia Code", "SF Mono", "Segoe UI Mono", Menlo, Consolas, monospace` |

The wordmark and marketing surfaces target **Inter** where available (see the
lockup SVGs); the app kit uses the system sans for zero-latency rendering. The
mono layer is for "system"/technical labels (paths, codes, timestamps).

**Type scale in use** (rem @ 16px base):

| Name | Size | Weight | Tracking | Where |
|---|---|---|---|---|
| KPI number | `1.7rem` | 780 | `-0.03em` | `.nx-kpi__num` |
| Lockup word | `1em` (inherits) | 780 | `-0.02em` | `.nx-lockup__word` |
| Body / control | `0.875rem` | 620 | — | buttons, row titles |
| Input text | `0.84rem` | 400 | — | `.nx-field__input` |
| Tab | `0.82rem` | 640 (active) | — | `.nx-tabs` |
| KPI label / sub | `0.78rem` / `0.74rem` | 400 | — | labels, list subtext |
| Field label | `0.72rem` | 560 | — | `.nx-field__label` |
| Avatar / pill | `0.70rem` / `0.68rem` | 700 / 640 | — | avatar, `.nx-pill` |

*Note:* weights use non-standard steps (560/620/640/780). With variable fonts
they render as-is; with static fonts the browser rounds to the nearest cut
(500/600/700).

### 1.4 Space & radius {#space-radius}

> **Superseded by DS-1.** The literal px below predate the DS-1 scale/motion tokens (Task 0) — button/input padding now resolve through the density role tokens, and motion adds --nx-dur-*/--nx-ease-* alongside --nx-ease. See the DS-1 changelog; DS-2 reconciles the full tables.

- **Radius scale:** `8px` (row icon) · `10px` (button, input) · `12px` (KPI) ·
  `18px` (card) · `999px` (pill). App-icon tiles use `112` on the 512 canvas
  (≈ 22%).
- **Padding rhythm:** card body `18px` · header `16px 18px` · KPI `14px 16px` ·
  input `9px 12px` · button `9px 15px`. Vertical stack gap inside a card body is
  `14px`; tab gap `18px`.

### 1.5 Motion {#motion}

> **Superseded by DS-1** — see the note at the top of §1.4.

| Token | Value | Use |
|---|---|---|
| `--nx-ease` | `cubic-bezier(.22,.68,.16,1)` | All kit transitions + the mark draw-on |

- **Mark draw-on** (`.nx-mark.is-playing`): the `n` strokes in over `0.6s`, then
  the accent `x` follows (`0.5s` delay). Triggered when the mark scrolls into view.
- **Reduced motion:** `@media (prefers-reduced-motion: reduce)` disables all mark
  animation and shows the final state. Honor this everywhere.

### 1.6 Elevation & borders {#elevation}

No shadows. Depth comes from **1px `--nx-hairline` borders** and **accent-tint
fills** (50/100). Cards clip their content (`overflow:hidden`) so tinted headers
meet the rounded corner cleanly.

---

## 2. The token model {#tokens}

Tokens live in `tokens.css`. Two layers:

1. **Channel vars** (`--nx-*-rgb`, e.g. `--nx-accent-600-rgb: 37 99 235`) — the
   source of truth. Space-separated RGB so they work with `/ <alpha>`.
2. **`rgb()` aliases** (`--nx-accent-600`, `--nx-accent`, …) — convenience, derived
   from the channels. Declared on **both** `:root` and every `[data-nx-product]`
   so each themed subtree recomputes its aliases from its own channels.

```html
<!-- the whole theme switch — every nx-* class inside recolours -->
<div data-nx-product="check"> … </div>   <!-- "ord" | "check" | "cert" | "file" | "firm" | "sky" | "copro" | "host" | "nx" -->
```

```tsx
<NxThemeProvider product="check">{children}</NxThemeProvider>
```

**Runtime dark surfaces:** set `--nx-mark-stroke: var(--nx-paper)` on a dark
wrapper to flip the mark's `n` to paper/white (the accent `x` stays constant).

**Full alias list:** `--nx-ink`, `--nx-slate-700/500/300`, `--nx-hairline`,
`--nx-paper`, `--nx-white`, `--nx-accent-50/100/600/700`, `--nx-accent`
(= 600), `--nx-font-sans`, `--nx-font-mono`, `--nx-ease`, and the runtime
`--nx-mark-stroke`. See **Dark theme** and **Status, chart & overlay tokens**
(below) for the added `--nx-on-accent`, `--nx-surface-2`, `--nx-scrim`,
`--nx-shadow-overlay`, status (`--nx-success/warning/serious/danger`) and chart
(`--nx-chart-1…6`) tokens.

**Tailwind (optional):** `tailwind.nx.cjs` maps the channels to
`nx-ink`, `nx-paper`, `nx-white`, `nx-hairline`, `nx-slate-{300,500,700}`,
`nx-accent{,-50,-100,-600,-700}` and the two font families — all alpha-aware, all
reading the same vars (so `data-nx-product` re-themes utilities too).

---

## Dark theme

Dark is a first-class theme — one attribute re-themes every token, component,
chart, and the mark.

- **Switch:** set `data-theme="dark"` (or `"light"`) on `<html>` — an app toggle
  or an SSR cookie. `prefers-color-scheme: dark` applies automatically **unless**
  `data-theme="light"` is set. `NxThemeToggle` flips the attribute.
- **How it works:** the dark block overrides the neutral **channel** vars on
  `:root`; because the `rgb()` aliases derive from those channels, every component
  recolours with **no per-component dark CSS**. The mark's `n` flips to light for
  free (it reads `--nx-ink`).
- **Accent tints are derived, not hand-picked:** in dark, `--nx-accent-50/100`
  become a `color-mix()` of the product accent into the dark surface, and
  `--nx-accent-700` (text-on-tint) becomes a *lightened* accent — so every product,
  including any future one, dark-themes with zero extra values. `--nx-accent`
  (signature 600) stays vivid; `--nx-on-accent` stays white.

<!-- Not auto-generated by gen-palette.mjs; keep hexes in sync with tokens.css manually. -->
| Token | Light | Dark |
|---|---|---|
| `--nx-paper` (app bg) | `#F7F8FA` | `#0B0E14` |
| `--nx-white` (surface) | `#FFFFFF` | `#141922` |
| `--nx-surface-2` | `#F1F3F7` | `#1B212B` |
| `--nx-ink` (text) | `#0B0E14` | `#E7EAF0` |
| `--nx-slate-700` | `#334155` | `#C3C9D4` |
| `--nx-slate-500` | `#5B6774` | `#8B94A3` |
| `--nx-slate-300` | `#CBD5E1` | `#3A424E` |
| `--nx-hairline` | `#E6E8EC` | `#262D38` |

App surfaces are defined in **both** themes. The `#0B1220` "on-dark" strip in the
mark section is a fixed demo, independent of the app theme.

## Status, chart & overlay tokens

Fixed, product-independent tokens (not remapped by `data-nx-product`):

- **On-accent:** `--nx-on-accent` (`#FFFFFF`) — text/icons on an accent-600 fill
  (buttons, avatars, solid badges). Constant in both themes.
- **Status:** `--nx-success #0CA30C` · `--nx-warning #FAB219` · `--nx-serious
  #EC835A` · `--nx-danger #D03B3B` · `--nx-info` (= active accent). CVD-validated;
  always paired with an icon + label — never colour alone.
- **Overlays:** `--nx-scrim` (dimmer) + `--nx-shadow-overlay` — the **one**
  sanctioned elevation, for drawers/modals/menus only (flat components stay flat).
- **Second surface:** `--nx-surface-2` — table headers, menus, drawers, inset panels.
- **Charts:** `--nx-chart-1…6` — a CVD-validated categorical palette (the dataviz
  reference instance; the product accents are too hue-close to serve as series),
  with its own dark steps, plus `--nx-chart-grid` / `--nx-chart-axis`.

---

## 3. The mark — nx ligature {#the-mark}

The master device: a monoline `n` that flows into a crossing `x`. Path geometry is
the single source of truth (shared with the SVG assets):

```
n:  M92 380 L92 232 C92 140 178 128 244 156 L424 380
x:  M424 156 L244 380
    viewBox 0 0 512 512 · stroke-width 60 · round caps + joins
```

- **`n`** = family constant, painted in `--nx-mark-stroke` (default `--nx-ink`,
  flips to paper on dark).
- **`x`** = per-product accent (`--nx-accent`). The parent **`nx`** variant paints
  the `x` with a blue→violet→teal **spectrum gradient**.
- **Differentiation is accent + wordmark only** — there is no per-product glyph.

### 3.1 `NxMark` (React) — props

| Prop | Type | Default | Notes |
|---|---|---|---|
| `variant` | `"nx" \| "ord" \| "check" \| "cert" \| "file" \| "firm" \| "sky" \| "copro" \| "host"` | `"nx"` | `nx` = neutral parent (spectrum x); others colour the x |
| `animated` | `boolean` | `false` | Draw-on when scrolled into view; respects reduced-motion |
| `tight` | `boolean` | `false` | Crop viewBox to the stroked glyph bbox (`62 112 392 298`) for inline/lockup use; default is the square canvas |
| `title` | `string` | `"NX"` | Accessible label |

The `x` colour resolves to `var(--nx-accent, <variant signature>)`, so a
standalone `<NxMark variant="check" />` is blue even without a theme wrapper,
while inside `<NxThemeProvider>` the provider's accent wins.

### 3.2 Standalone SVG assets

Under `assets/<member>/` (`checknx` · `ordnx` · `certnx` · `filenx` ·
`firmnx` · `skyonex` · `copronx` · `hostnx` · `nx`):

| File | What | When |
|---|---|---|
| `symbol.svg` / `favicon.svg` | Adaptive — `n` flips white in dark mode via `prefers-color-scheme`; accent `x` constant | Default favicon / inline symbol on light-or-auto surfaces |
| `symbol-light.svg` | Forced ink `n` | Known-light backgrounds |
| `symbol-reversed.svg` | Forced white `n` | Known-dark backgrounds (no media query) |
| `symbol-mono.svg` | Single `currentColor` | Inherits text colour; one-colour contexts |
| `icon.svg` | Rounded Ink tile + white `n` + accent `x` | OS/app icon, avatar |
| `lockup.svg` / `lockup-reversed.svg` | Wordmark (prefix + accent `NX`), adaptive / dark | Horizontal logo *(not for parent `nx`)* |
| `png/…` | Raster 16/32/48/180/192/512/1024 (+`-dark`) + lockups | Where SVG isn't accepted |

> **PNG status:** exports exist for `checknx`/`ordnx`; `certnx`, `filenx`,
> `firmnx`, `skyonex`, `copronx`, `hostnx`, `nx`, and all `icon.svg` are **SVG-only** until re-exported through a
> renderer (follow-up — no SVG→PNG tool currently available).

> **FileNX assets were re-cut on 2026-08-02** (§4.1): the folder moved
> `assets/doclinq/` → `assets/filenx/`, both lockups now read "FileNX" in the
> family's two-tspan form (ink `File` + emerald `NX`, `viewBox` 960), and every
> `aria-label` in the set was updated from "DocLinQ".

**Clear space & min size:** keep at least the height of the `n`'s stem of clear
space around the mark; symbol legible from **16px**, wordmark from ~**80px** tall.

---

## 4. The lockup

Product labels render the **prefix as ink text + the ligature standing in for
"NX"** — e.g. `Check` + mark.

```tsx
<NxLockup product="check" size={20} />   // "Check" + blue nx mark
```

- Prefix casing (as shipped, `PREFIX` in `react.tsx`): `check` · `ord` ·
  `cert` · `file` · `firm` · `SkyONEx` · `copro` · `host` · *(none for `nx`)*.
- `.nx-lockup__word` — weight 780, tracking `-0.02em`, `--nx-ink`.
- The mark is `height: 1.10em`, `margin-left: .06em`, `NxMark tight`. (Was 1.05em with the old
  `62 126 392 284` crop, which clipped the top of the n's arch; 1.10em keeps the same glyph size.)
- `size` (px) sets the lockup `font-size`; the mark scales with it.
- Accessible name is the full product name; the inline SVG is `aria-hidden`.

### 4.1 FileNX — the former lockup exception (resolved) {#filenx-lockup}

**There is no longer an exception here.** `<NxLockup product="file" />` renders
`File` + ligature and is correct, exactly like `Check` / `Cert`.

*History, kept because it explains the assets.* When the product was called
**DocLinQ**, it was the one family member whose name didn't end in "NX", so the
ligature couldn't stand in for the trailing letters. Its lockup rendered the full
word in ink followed by the ligature as a **companion glyph**, and `NxLockup` was
deliberately unused for it. The 2026-07-22 rename to **FileNX** removed that
premise — the name ends in "NX" — and the 2026-08-02 rename pass finished the job:
the theme key became `file`, `PREFIX["file"] = "File"`, and
`assets/filenx/lockup.svg` / `lockup-reversed.svg` were re-cut to the family's
two-tspan convention (ink `File` + emerald `NX`) with the `viewBox` re-measured to
960 to match the narrower word.

FileNX's app still ships its own `Wordmark`
(`apps/filenx/apps/main/src/components/wordmark.tsx`), now by preference rather
than necessity: it renders the full word *and* the ligature, which reads stronger
in the app shell than the substitution form.

*(Related follow-up, kit-behaviour gate: if the family ever wants a generic
full-word lockup as a kit component, extend `NxLockup` to accept a word override
rather than the `${word}NX` template.)*

### 4.2 SkyONEx — companion-mark lockup {#skyonex-lockup}

SkyONEx is a family member whose established name does not end in a literal
`NX`. `<NxLockup product="sky" />` therefore renders the nx ligature first as a
companion mark, followed by `Sky` in Ink and `ONEx` in the sky accent. It keeps
the family mark and color grammar without changing or duplicating the product
name. Static assets in `assets/skyonex/` use the same composition.

---

## 5. Components

All class names mirror the React components and require `tokens.css` + `kit.css`.
Values below are the shipped defaults.

### 5.1 `NxThemeProvider`
Wraps a subtree, sets `data-nx-product` + `.nx-app` (applies `--nx-font-sans`,
`--nx-ink`, font-smoothing). The single re-theming switch.
```tsx
<NxThemeProvider product="ord"> … </NxThemeProvider>
```

### 5.2 `NxButton` — `.nx-btn` {#nx-button}
Base: `font-size .875rem`, weight 620, radius `10px`, padding `9px 15px`, `1px`
transparent border.

| Variant | Rest | Hover |
|---|---|---|
| `primary` (`.nx-btn--primary`) | bg `--nx-accent`, text white | bg `--nx-accent-700` |
| `ghost` (`.nx-btn--ghost`) | transparent, text `--nx-accent-700`, border `--nx-accent-100` | bg `--nx-accent-50` |
| `outline` (`.nx-btn--outline`, P0.5) | transparent, text `--nx-ink`, border `--nx-hairline` | bg `--nx-state-hover` |

`--outline` is the NEUTRAL secondary-action look (Cancel/Back/Retry/Download) — no
accent tint, unlike `--ghost`. It's a CSS-only class (apply directly via
`className="nx-btn nx-btn--outline"`, framework-agnostic like the rest of the kit);
the bundled `NxButton` component's `variant` union is unchanged (still
`"primary" | "ghost"`) since this pass didn't touch `react.tsx`. Active/press
(`background:var(--nx-state-active)`) lives in kit.css's DS-1 component-states block,
next to `--ghost`/`--danger`'s.

Focus: `:focus-visible` → `2.5px solid --nx-ink` outline, `2px` offset.
```tsx
<NxButton>Start job</NxButton>
<NxButton variant="ghost">Assign</NxButton>
```

### 5.3 `NxCard` — `.nx-card` / `.nx-card__body` {#nx-card}
Surface: white, `1px --nx-hairline` border, radius `18px`, clipped. Body: padding
`18px`, vertical flex, gap `14px`. The card is the standard container for a themed
panel (usually `NxProductHeader` + body).

**Sub-parts (P0.5, 2026-07-14 — DocLinq audit):** `.nx-card__header` (padding `18px`,
vertical flex, gap `6px` — consumers override `flex-direction`/alignment per instance,
e.g. a KPI card's row layout vs. a form card's centered column) wraps
`.nx-card__title` (`1rem`/700, tight leading, `-0.01em` tracking — same recipe as
`.nx-panel__title`) and an optional `.nx-card__description` (`.85rem`,
`--nx-slate-500`, normal leading). No `.nx-card__footer` — audited as unused across
DocLinq's real Card call sites, so YAGNI-cut; add it the same way if a future
consumer needs it.

### 5.4 `NxProductHeader` — `.nx-header` / `.nx-header__avatar` {#nx-product-header}
Tinted header bar: bg `--nx-accent-50`, bottom border `--nx-accent-100`, padding
`16px 18px`, space-between. Holds an `NxLockup` and an optional avatar
(`26×26` circle, bg `--nx-accent`, white `.7rem`/700 initials).
```tsx
<NxProductHeader product="check" avatar="AC" />
```

### 5.5 `NxKpiTile` — `.nx-kpi` {#nx-kpi-tile}
Tinted stat tile: bg `--nx-accent-50`, radius `12px`, padding `14px 16px`.
`__num` = `1.7rem`/780, tracking `-0.03em`, color `--nx-accent-700`; `__lbl` =
`.78rem`, `--nx-slate-500`.
```tsx
<NxKpiTile value="14" label="Jobs today" />
```

For an overview metric, use `variant="card"`: a flat neutral surface with a
hairline, clear tabular number and an optional small product-tinted icon. Its
visible label/value form a definition pair; `description` can supply a factual
period or unit. Never invent trend indicators without comparison data.

```tsx
<div className="nx-stat-grid">
  <NxKpiTile variant="card" value="14" label="Jobs today"
    icon={<CalendarDays size={18} />} description="Scheduled for today"
    href="/jobs" linkComponent={Link} />
</div>
```

`nx-stat-grid` fits as many columns as the available content width permits,
including inside a sidebar layout. Cards allow long labels and values to wrap
rather than truncate. Light/dark, product themes and RTL use the shared tokens.
`href` makes the whole card one keyboard-accessible link; `linkComponent` keeps
framework/locale routing. Icons are decorative, and slots must not contain
nested controls. Cards without `href` are static. Hover/focus only apply to
links. Hover tint requires a hover-capable fine primary pointer, so touch
scrolling does not leave a card highlighted; keyboard focus stays visible.
There are no card shadows or decorative charts. Existing compact tiles
keep their original markup and appearance.

### 5.6 `NxListRow` — `.nx-row` {#nx-list-row}
Row: flex, gap `12px`, padding `10px 0`, bottom `1px --nx-hairline` divider.
`__icon` = `30×30`, radius `8px`, bg `--nx-accent-100`, text `--nx-accent-700`,
700/`.78rem`. `__title` = `.875rem`/560, single-line ellipsis; `__sub` = `.74rem`,
`--nx-slate-500`. Optional trailing `NxStatusPill`.
```tsx
<NxListRow icon="NK" title="Nordküste — window clean" sub="09:30 · A. Berger" pill="On site" />
```

### 5.7 `NxStatusPill` — `.nx-pill` {#nx-status-pill}
Chip: `.68rem`/640, padding `4px 9px`, radius `999px`, bg `--nx-accent-100`, text
`--nx-accent-700`, no-wrap. For short states/counts.

### 5.7a `NxGettingStarted` — `.nx-getting-started` {#nx-getting-started}

Onboarding checklist composed as a titled card of full-row actions. Each task is
one semantic anchor or button—not a row containing a tiny trailing link—so its
complete 48px-high surface is clickable and keyboard focusable. Hover animates
the status marker and logical-direction arrow; reduced-motion disables both.
Completed tasks remain navigable and use a check plus struck label.

```tsx
<NxGettingStarted
  title="Get started"
  items={[
    { label: "Create your first agent", href: "/agents" },
    { label: "Add a widget or channel", href: "/widget", done: true },
    { label: "Upload a knowledge source", href: "/sources" },
  ]}
/>
```

### 5.8 `NxField` — `.nx-field` {#nx-field}
`__label` = `.72rem`/560, `--nx-slate-500`, `5px` below-gap. `__input` =
full-width, `1px --nx-hairline` border, radius `10px`, padding `9px 12px`,
`.84rem`, white bg; placeholder `--nx-slate-500`. **Focus:** border `--nx-accent`
+ `0 0 0 3px --nx-accent-100` glow (no default outline).
```tsx
<NxField label="Search jobs" placeholder="Type to filter…" />
<NxField label="Kürzel" hint="Erscheint in jedem Tracking-Link." error={slugError} />
```
`hint` and `error` (0.9) render `.nx-field__hint` / `.nx-field__error` under the
input and wire them with `aria-describedby`; `error` also sets `aria-invalid`.

Input adornments use `.nx-field__control`, a positioned wrapper, with
`.nx-field__adornment--leading` / `--trailing` slots. Apply the matching
`.nx-field__input--leading` / `--trailing` modifier to reserve logical inline
space in both LTR and RTL. Keep that padding in the kit layer: a Tailwind
padding utility cannot override the kit's unlayered input rule. Leading icons
are decorative and ignore pointers; trailing actions have an accessible label
and a 44px target. A custom clear action replaces the browser search-cancel UI.

Short forms default to a single column: label, control and help text, followed
by the next field. Use multiple columns for related compact fields only when
they make entry clearer. Align those field groups at the top so longer help
text does not shift neighbouring labels and controls down.

### 5.9 `NxTabs` — `.nx-tabs` {#nx-tabs}
Row of tabs: gap `18px`, `.82rem`, `--nx-slate-500`, bottom `1px --nx-hairline`,
`10px` bottom padding. Active (`__item--active`): color `--nx-accent-700`, weight
640, `2px` accent underline flush to the divider. `role="tablist"` + per-tab
`role="tab"` / `aria-selected`.
```tsx
<NxTabs items={["Today", "Activity", "Settings"]} activeIndex={0} />
```

#### `NxNavTabs` — `.nx-navtabs` {#nx-nav-tabs}
The `.nx-tabs` look as **page-section navigation** (rule 1 of
[Navigation within a section](#section-nav)): each tab is a link with its own URL and
`aria-current="page"`, not a `role="tab"` widget. Put it under the page title for 3–7 peer
views of one area. The row scrolls sideways on a phone, never the page. The caller decides
which tab is active.
```tsx
<NxNavTabs
  label="Agent sections"
  linkComponent={Link}
  items={[
    { href: "/agents", label: "Agents", active: true },
    { href: "/widget", label: "Website channel" },
  ]}
/>
```
`NxAppShellNavItem.activePaths` lists further paths that belong to a sidebar item, so the
sidebar keeps that area lit on a tab page with its own URL (the longest match wins).

---

## Extended components {#extended-components}

All dark-aware and token-driven; class names mirror the React components in
`react.tsx`. Framework-agnostic — the CSS classes work without React.

### Form controls

**Optional properties and filters:** domain-specific fields (such as business year)
belong to a configurable document/folder type, never to every form or list. Offer
an explicitly labelled property picker, then a correctly typed value control and
a labelled remove action. Common property keys can filter across compatible
types. Keep filter state in navigation URLs, reset pagination on changes, and
make active filters removable. Invalid/stale filters must never silently broaden
the result set. A custom type without a year must work throughout the workflow.

**Optional-field disclosure:** use a shared neutral NX button with a Lucide
chevron and `aria-expanded`. Use theme ink for its text; surface/accent background
tokens are not text colors. Check its collapsed and expanded states in both
themes, with a minimum 44px touch target.

#### `NxCheckbox` — `.nx-checkbox` {#nx-checkbox}
Custom box, accent when checked, accent-100 focus glow, `:has(input:disabled)`
dims. `indeterminate` (React prop; CSS `input:indeterminate`) shows a dash for a
mixed state — use it for a tree parent whose children are only partly selected.
Inherited selection in a tree is shown as a checked child with a hint naming the
parent ("Shared via …"), never as a separate per-row Allow/Exclude dropdown.
React: `NxCheckbox`.

#### `NxRadio` — `.nx-radio` {#nx-radio}
Custom dot, accent when checked, accent-100 focus glow, `:has(input:disabled)`
dims. React: `NxRadio`.

#### `NxChoiceCard` — `.nx-choice-card` {#nx-choice-card}
A radio choice drawn as a card: a title, an optional one-line hint and an optional
Lucide icon, the whole card is the hit target. Use it when each option needs a sentence
of explanation, for example "Where does the agent talk? Internal / External". Unselected:
hairline border on white. Selected: **2px accent-600 border on an accent-50 fill** (the
padding shrinks by 1px so the card never grows). Focus shows the standard ring; disabled
dims. Wrap the cards in `<fieldset class="nx-choice-group">` with a `<legend>`; the group
is a responsive grid. React: `NxChoiceCard` (radio input props plus `title`, `hint`,
`icon`). Two to four options; for more, or for short labels, use `NxRadio`.

#### `NxSwitch` — `.nx-switch` {#nx-switch}
38×22 track, accent when on, `--nx-on-accent` knob. React: `NxSwitch`.

#### `NxSelect` — `.nx-select` {#nx-select}
Styled native `<select>` with caret; focus = accent border + glow.
React: `NxSelect`.

#### `NxTextarea` — `textarea.nx-field__input` {#nx-textarea}
The field input, min-height 88, vertical resize.
React: `NxTextarea`.

#### `NxColorField` — `.nx-color` {#nx-color-field}
Native colour picker as a field-height swatch, a monospace hex input kept in
sync, and preset swatches (`NX_COLOR_PRESETS`: the light `--nx-chart-1…6`, so
a chosen colour matches the charts). Value is always `#rrggbb` (lower case) or
`""` when `clearable`; a half-typed hex never reaches `onChange`, and an invalid
one is reverted on blur. Presets carry `aria-pressed`. React: `NxColorField`.

#### `NxDateField` — `.nx-datefield` {#nx-date-field}
Date (and optionally time) entry written in the **UI's** locale. `<input
type="date">` is drawn in the *browser's* UI language instead, so a German page
in an English-US Chrome shows `mm/dd/yyyy` under a German label, and the native
picker carries none of the kit's tokens — neither is reachable from our side.
This field therefore renders the value itself: `Intl` decides the field order,
the separators, the first day of the week, the weekday names and the numerals,
and the popover is the kit's. The value crossing `onChange` is exactly what the
native input submitted (`YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with `withTime`),
and `name` emits a hidden input, so it is a drop-in replacement.

Typing is lenient — `3.11.`, `3/11/26`, `03112026`, `15` (that day of the month
on screen) and a pasted ISO date all land; a four-digit group is read as the
year wherever it sits. Anything else is simply not a date and the field reverts
on blur. The pattern (`tt.mm.jjjj`) is the placeholder and nothing more — it
comes on screen under the control only once what was typed has stopped parsing,
and screen readers get it either way through `aria-describedby`. A caption under
every date in a form is noise. `hideLabel` keeps the label for screen readers
and takes it off the screen, for one-line filter rows; `required` lands on the
visible input, because a hidden input is excluded from constraint validation.
The locale and the calendar's words are given **once per app**, not at every
field: mount `NxLocaleProvider` inside whatever already knows the active locale
and every field below it reads in that language (a field's own `locale` /
`labels` still win). For the same reason `NxField` with `type="date"`,
`"datetime-local"` or `"time"` renders these fields instead of a native input —
the submitted name and value are unchanged, so the form around it keeps
working, and an app fixes every date it has by mounting the provider. Leave
`value` out and the field holds its own, like the `defaultValue` input it
replaces.

`min` / `max` bound the field: days outside the window are struck through and
refuse the click but stay in the grid, so the arrow keys still cross them, and a
typed day outside it is not emitted — the caption turns into the window itself
(`01.01.2020 – 12.10.2026`, `≥ 01.01.2020`, `≤ 12.10.2026`), which needs no
translating.
The popover follows the APG date-picker dialog: arrows move a day,
Page a month (Shift a year), Home/End the ends of the week, Escape returns to
the input. React: `NxDateField`; the helpers (`nxFormatDate`, `nxParseDate`,
`nxDatePattern`, `nxFirstDayOfWeek`, `nxFormatTime`, `nxParseTime`,
`nxMonthGrid`, `nxDateOrder`) are exported for consumers that format dates
outside a field.

#### `NxTimeField` — `.nx-timefield` {#nx-time-field}
Clock entry for the hours that are not attached to a day — opening times, a
send time, the start and end of a shift. `<input type="time">` carries the same
defect as `<input type="date">`: it is drawn in the **browser's** language, so a
German page in an English-US Chrome asks for AM/PM. This field reads and writes
`HH:mm` and renders it the way the UI's locale writes a time. Typing is as
lenient as the date field's — `9`, `930`, `9:30`, `9.30`, `9 pm` and
Arabic-Indic digits all land, anything else reverts on blur. A time that belongs
to a date is not this field: use [`NxDateField`](#nx-date-field) with
`withTime`, so the two halves stay one value. React: `NxTimeField`, or `NxField` with
`type="time"`; `nxParseTime` and `nxFormatTime` are exported for consumers
outside a field. It takes its locale from `NxLocaleProvider` like the date
field does.

#### `NxDisclosure` — `.nx-disclosure` {#nx-disclosure}
"Mehr Optionen" over the form fields most people never need — native
`<details>`, works without JavaScript. Open it by default when a hidden field
already has a value: a value must never be invisible.

#### `NxFileUpload` — `.nx-upload` {#nx-file-upload}
Controlled single-file picker with a click/keyboard-accessible native input,
drag-and-drop target, visible format/size guidance, and a selected-file summary
with a labelled remove action. `accept` filters the picker but is never treated
as validation; consumers validate type and size again on the server. React:
`NxFileUpload`.

`NxFileDropzone` uses the same surface for multiple files and a separate folder
picker when the browser supports directory selection. Consumers own validation,
progress, retry and removal; the component does not upload or retain files.
Directory selection preserves each file's `webkitRelativePath`. Keep file and
folder selection available together, show accepted types and size limits, and
review the selected files before any upload or publication.

### Data

#### `NxTable` — `.nx-table` {#nx-table}
(+ `.nx-table__wrap` for a rounded bordered card) — uppercase muted
`th` on `--nx-surface-2`, hairline row rules, `tr:hover` → accent-50, `.num`
right-aligns with tabular figures. React: `NxTable`.

Column visibility uses the same NX outline button and menu styling as other
table actions. Label checkbox rows with human-readable column names, retain
search and multiple toggles without closing, and support keyboard focus,
Escape, Tab and RTL alignment. Do not style a column picker as an unrelated
combobox. Keep the trigger's touch target at least 44px.

#### `NxDocumentPreview` — `.nx-preview` {#nx-document-preview}
Inline viewer for an already-authorized document (0.5.0): `__frame`
(`<iframe>`, PDF), `__img` (`<img>`, raster, with a real
`data-nx-state="loading|ready|error"`), `__fallback` for anything else, and a
`__foot` carrying the bidi-isolated `__name` caption plus an optional
`__download` link. **Purely presentational** — every string arrives via
`labels` (no i18n inside), `src` is rendered as given and never fetched (so it
serves an app URL and a `blob:` URL alike), and there is no new dependency.
The PDF frame deliberately has **no loading or error state** (an `<iframe>`
gives no trustworthy signal); the download link beneath it is unconditional
instead. Pair with `NxModal size="wide"`. React: `NxDocumentPreview`.

### `NxGrantRow` — `.nx-grant-row` (allowlist entry, 0.13.0) {#nx-grant-row}

One entry of an allowlist: what an agent or assistant may read. Used by SkyONEx agent
allowlists ("Website-Concierge reads only …"); reuse it for any "X may access Y" list.

| Prop | Meaning |
|---|---|
| `source` | `drive` · `git` · `upload` · `obsidian` — picks the badge icon (Lucide geometry) |
| `sourceLabel` | Name shown in the badge and read out, e.g. "Google Drive" |
| `title` | File name or path |
| `detail` | Where it lives, e.g. the repo |
| `scopeLabel` | How far it reaches, e.g. "File" / "Folder, incl. new files" / "Whole source" |
| `types` | Worded file-type chips, e.g. "only .md" |
| `onRemove` + `removeLabel` | Labelled icon button (required label, names the entry) |

Rules: copy comes from the app (i18n), the row never guesses wording. Scope is always written
out — a folder grant silently covering future files is exactly what users must see. The
"reads every source" state of a legacy agent is an `NxAlert variant="warning"` above the list,
not a row.

### Status & feedback

#### `NxBadge` — `.nx-badge` {#nx-badge}
Solid (default) + `--soft` / `--success` / `--warning` / `--danger`, optional
`__dot`. React: `NxBadge`.

#### `NxAlert` — `.nx-alert` {#nx-alert}
`--info/--success/--warning/--danger` — tinted surface, coloured
left bar + icon, ink body text (never colour-alone). React: `NxAlert`.

#### `NxProgress` — `.nx-progress` {#nx-progress}
`__bar` — accent bar on an accent-100 track. React: `NxProgress`.

#### `NxSkeleton` — `.nx-skeleton` {#nx-skeleton}
Shimmer on `--nx-surface-2`, reduced-motion aware. React: `NxSkeleton`.

#### `NxSpinner` — `.nx-spinner` {#nx-spinner}
Small rotating ring, `currentColor` border-top, spin animation, reduced-motion
aware — one of the primitives added in the [DS-1 changelog](#ds-1-changelog).
React: `NxSpinner`.

#### `NxTooltip` — `.nx-tooltip` {#nx-tooltip}
`__pop` — CSS hover/focus tooltip; inverts per theme. React: `NxTooltip`.

#### Empty state — `.nx-empty` {#nx-empty-state}
Centered icon + title + copy + action for a list/table with no data yet — one of
the primitives added in the [DS-1 changelog](#ds-1-changelog). React (0.9):
`NxEmptyState` — `action` is **required**: an empty state always names the next
step ([IA & actions](#ia-actions)).

#### `NxIntegrationCard` — `.nx-integration` {#nx-integration-card}
A connected account or integration: logo, name, the connected account, a status
badge (connected / expired / disconnected / error — the badge says it, never
colour alone), optional error text and ONE action in `.nx-card__footer`
(Connect / Reconnect / Disconnect). Grid them on one "Accounts" page; link to
that page from wherever a missing connection blocks something.

#### `NxStatStrip` — `.nx-statstrip` {#nx-stat-strip}
One row of metrics for one source (a platform, a channel) plus where the numbers
come from (`source`: "synchronisiert vor 2 Std." / "manuell") — a number whose
origin is unknown is not shown. Optional trailing action ("Zahlen eintragen").

#### `NxHandoffStatus` — `.nx-handoff` {#nx-handoff-status}
A hand-off between two suite products (an ordNX deal sent to checkNX, a checkNX request filed in
FileNX): source → target as two small product marks (`.nx-suite-product`, a square in the fixed
`--nx-family-*` colour plus the name; products without a family token — file, aut, form, host —
use neutral slate), then the status chip and an optional link to the counterpart object.
`status` is `in-transit` (neutral) · `arrived` / `converted` (success tint) · `failed` (danger
tint); `statusLabel` is always visible text next to a Lucide icon, so the status never relies on
colour (WCAG 1.4.1). The arrow is Lucide `ArrowRight`, `aria-hidden`, mirrored in RTL;
`directionLabel` ("to" / "an") is read between the products instead. `link` goes through
`linkComponent` for locale routing; `detail` carries a time or the failure reason.
React: `NxHandoffStatus` (types `NxHandoffState`, `NxSuiteProduct`, `NxSuiteProductRef`).

#### `NxSourceCoverage` — `.nx-coverage` {#nx-source-coverage}
Which data sources answered, so a partial result is never shown as empty. One row per source:
name, state as text (`ok` · `pending` · `stale` "as of 14:05" · `timeout` · `failed`, the app
formats the time) with an aria-hidden Lucide icon, optional copy progress (`NxProgress` plus the
visible "3 of 10 copied") and a detail line. The list is a `role="status"` region named by
`label`. When a source failed or timed out and `alert` is given, an `NxAlert` sits above the
list — `warning` for a partial result, `danger` when no source answered — outside the status
region, so live regions do not nest. The sources that did answer stay listed.
React: `NxSourceCoverage` (types `NxSourceCoverageItem`, `NxSourceState`).

#### `NxMoveNotice` — `.nx-move-notice` {#nx-move-notice}
Shown once in the **target** product after an automatic move (the old app is deleted after the
move, so the notice cannot live there; it also works as a 301 landing page): old product struck
and neutral → new home in its family tint (leading bar and mark), a heading ("Your pointNX data is
now here"), one sentence about the data, an optional date and target link, and a dismiss icon
button (Lucide `X`, `dismissLabel` as its name). Dismiss hides the notice and calls `onDismiss`;
remembering that it was seen is the app's job. Flat surface, hairline, no shadow.
React: `NxMoveNotice`.

#### `NxSecretReveal` — `.nx-secret` {#nx-secret-reveal}
A freshly generated secret (device token, API key, pipeline secret) shown exactly once: label,
monospace value (`translate="no"`, wraps anywhere, `user-select: all`), a copy button and the
one-time hint ("only visible now, only the hash is stored" — passed in, the kit stays
language-neutral). Copy uses `navigator.clipboard.writeText`; when that is missing or refused the
value is selected instead and `copyFallbackLabel` is announced. Feedback goes through a status
region that is mounted empty. Optional regenerate (`regenerateLabel` + `onRegenerate`) and close
(`closeLabel` + `onClose`) actions. The value is only ever a text node — never a `title`, `value`
or `data-*` attribute — and leaves the DOM when the reveal is closed or unmounted.
React: `NxSecretReveal`.

### Navigation

#### `NxContextSwitcher` — `.nx-context` {#nx-context-switcher}
The working context of an area, always visible in `NxAppShell`'s `context` slot
(after the app switcher): a pill "● IPM Facility ▾" opening an `NxDropdownMenu`
with the options (colour dot, active checked), an optional "all" option and a
"manage" link. The host persists the choice (cookie/user setting) and every page
below **implies** it — filters, defaults of new items, KPIs. A URL parameter may
override it for a shared link. Use for one context per area (brand, workspace,
property), never as a second organisation switcher.

#### `NxPageHeader` — `.nx-pagehead` {#nx-page-header}
Title, optional description and breadcrumb, **one** `primaryAction` and at most
two `secondaryActions` (more → a menu; dev-warns). Every page has one; the
primary is the action this page exists for ("Beitrag schreiben").

#### `NxSegmented` — `.nx-seg` {#nx-segmented}
2–5 mutually exclusive views or filters ("Alle · Entwurf · Freigegeben"), radio
semantics (`role="radiogroup"`, arrow keys move, one always selected), optional
counts. Promoted from the inline `.nx-seg` of the showcase.

#### `NxLevelSwitch` — `.nx-level` {#nx-level-switch}
One row's access level, e.g. **Nein · Lesen · Bearbeiten** (suiteNX › AI assistants). Unlike
`NxSegmented` (view switching, buttons), it is a `<fieldset>` of native radio inputs: a radiogroup
with arrow keys for free, and it posts with a plain `<form>` without JavaScript. `label` is the
group's accessible name (visually hidden by default, `hideLabel={false}` shows it). The selected
option wears the row's own product accent through `product` (`data-nx-product`), on the accent-100
tint with accent-700 text. Disable an option (`disabled`, with a `title` saying why) when the level
is not available, never hide it: the person must see that it exists.

#### `NxAppTile` — `.nx-apptile` {#nx-app-tile}
A booked app on a start page: the product mark on its accent-50 tile, the name, a one-line purpose
and an optional status pill ("3 new orders"). The whole tile is one link. `add` renders the dashed
"More apps" tile with a Lucide `PackagePlus`, in neutrals, for booking or trying another app. Lay
tiles out in a grid; booked apps first, the add tile last.

#### `NxPlatformBadge` — `.nx-platform` {#nx-platform-badge}
Where a post goes and whether it is there: the platform's mark, grey on an
outline while `planned`, in the platform's own colour on its light tint once
`published`, dashed danger when `failed`. The accessible name and title say
platform + state; with `href` it links to the live post. Platform colours are
tokens (`--nx-brand-linkedin` … `--nx-brand-bluesky`) and colour only the mark,
never UI chrome. `NxPlatformIcon` renders the mark alone (e.g. as the logo of an
`NxIntegrationCard`).

#### `NxBreadcrumb` — `.nx-breadcrumb` {#nx-breadcrumb}
(+ `__sep` / `__current`). React: `NxBreadcrumb`.

#### `NxMenu` — `.nx-menu` {#nx-menu}
`__item` (+ `--active`) / `__sep` — popover list with overlay shadow.
React: `NxMenu`.

#### `NxProfileMenu` — `.nx-profilemenu` {#nx-profile-menu}
Avatar-first account menu composed from `NxAvatar` + `NxMenu`. It carries the
user's name/email in the panel and keeps profile, settings, and sign-out actions
out of the top-bar action cluster. `items[].icon`, `avatar`, and `chevron` accept
consumer-owned nodes, including Lucide icons, without adding an icon dependency
to the kit. Outside click and Escape close it; Escape and item activation restore
focus to the trigger. React: `NxProfileMenu`.

**Organisation switcher (ADR-0007).** Every product's profile menu is where a person
switches organisation (tenant) — once, for every product. Pass `organisations`
(`{ id, name, active?, available? }[]`, from the session's `nx_customers` claim),
`organisationHref` (the product's `/api/auth/oidc/switch?customer=…` route) and
`organisationLabels` (`heading`, `explain`, `active`, `noAccess`). With two or more
organisations the menu opens with an **Organisation** section: a heading
(`.nx-menu__heading`), one explanation line (`.nx-menu__note`), one link per
organisation — the active one marked, those that may not use this product
disabled with a hint (`.nx-menu__hint`) — then a separator and the product's own
items. `organisation` shows the active name in the panel header. Products that
compose their own items use `nxOrganisationItems(...)` for the same section.
`NxMenuItem` gained `href` (a link item), `hint`, `heading` and `note`.

#### `NxAppShell` — `.nx-shell` {#nx-app-shell}
Suite chrome (Phase 2 K1, 0.2.0): skip-link → sticky sidebar (`__sidebar`,
`__brand`, `__nav`, `__navlink`/`--active`) → sticky top bar (`__topbar`,
reuses `.nx-header`'s accent-tinted look) with `__topbar-start` (hamburger +
`NxAppSwitcher`) / `__topbar-center` (search slot) / `__topbar-end`
(themeToggle/localeSwitcher/user slots) → `#main-content` (`__content`).
Below 768px the sidebar hides and the hamburger opens the same nav via
`NxDrawer` (reused, not reimplemented) — unless the app owns mobile navigation
itself (`mobileNav="app"`, 0.6.0), which drops the hamburger AND the drawer so a
consumer's own bottom bar is not a second mobile nav; because the hidden sidebar
is out of the accessibility tree too, that opt-out hands the consumer the duty of
shipping a keyboard- and SR-reachable equivalent (see ADOPTION.md).
`contentClassName` (0.6.0) appends classes to `__content` for layout the shell
cannot know — e.g. bottom-bar clearance; both default to the previous markup
exactly. Framework-agnostic — `linkComponent` prop, no `next/*` import.
React: `NxAppShell`. See ADOPTION.md for the full prop table.

The desktop navigation scrolls within the space between the brand and bottom
utility controls. Long navigation must not paint over Help, language or
appearance, and keyboard focus must scroll every link into view. Mobile keeps
its enclosing drawer body as the scroll container.

The sidebar brand stacks the organisation name below the product wordmark.
Plain names wrap across the available width, including long unbroken names;
they have no vertical divider or ellipsis beside the product. A missing tenant
label keeps the existing wordmark-only heading.

#### `NxAppSwitcher` — `.nx-appswitcher` {#nx-app-switcher}
Top-bar product menu (Phase 2 K1, 0.2.0): icon trigger (`__trigger`,
`aria-haspopup="menu"`) and visible localized Apps label open a single-column
`__panel` of `__tile`/`--current` app rows (product mark, brand name, localized purpose
and current-app indicator, `role="menuitem"`). Descriptions come from the suite
manifest; brands are never translated. Escape/outside-click
close; focus-trap in and back out via the kit's `useFocusTrap`. Renders every
`apps` entry it's given — entitlement filtering is the consumer's job
(Phase 3), not this component's. React: `NxAppSwitcher`.

Optional `bookMore={{ href, label? }}` (also on `NxAppShell`) adds one
non-product row last (`__book-more`, `data-nx-switcher-entry="book-more"`): a
Lucide `PackagePlus` icon instead of a mark, a localized "Book more apps" default
label (en/de/fr/ar/es), never `aria-current`, reachable with the same arrow keys.
Consumers pass it only when the list was narrowed to the workspace's booked apps
(`resolveSuiteSwitcher` in `@nx-family/suite` decides), pointing at the Suite
products page.

### Overlays

Both below use `--nx-scrim` + `--nx-shadow-overlay`.

#### `NxDrawer` — `.nx-drawer` {#nx-drawer}
(+ `--left`), composed from the shared `.nx-panel__head` / `__body` / `__foot`.
React: `NxDrawer`.

#### `NxModal` — `.nx-modal` {#nx-modal}
`__card`, composed from the shared `.nx-panel__head` / `__body` / `__foot`.
`size="wide"` (0.5.0, optional) adds `__card--wide` → `width:min(920px,100%)`
for content the 460px form width cannot hold; the default is unchanged.
React: `NxModal`.

Initial focus on the non-interactive modal card supports reading order without
drawing a focus outline around the entire dialog. Keep the token hairline and
overlay shadow; interactive buttons, links and fields retain visible keyboard focus.

#### `NxCommand` / `NxGlobalSearch` — `.nx-command` {#nx-command}
`NxCommand` (K-31) is a modal combobox that owns a grouped listbox: `.nx-modal.nx-command-modal`
rendered in place (no portal, no cmdk), card `.nx-modal__card.nx-command`, a visually hidden
`h2` naming the dialog. Focus stays in the input; the active option is announced through
`aria-activedescendant`. The first option is active after every new result list, ArrowDown /
ArrowUp wrap, Enter follows the active option (not while an IME is composing), Escape closes
and returns focus to the opener (`useFocusTrap`), and the page behind does not scroll
(`useBodyScrollLock`). The request logic (debounce, stale guard, abort) is `useNxAsyncSearch`,
shared with `NxRelationPicker`. Result links use the host's `linkComponent` only for same-origin
destinations outside `/api/`; anything else is a plain anchor, and a non-http(s) destination is
not a link at all.

`NxGlobalSearch` puts it in the top bar: `.nx-command-trigger.nx-search-desktop` (a field-looking
button with the placeholder and a `Ctrl K` / `⌘K` hint) and `.nx-iconbtn.nx-search-mobile-trigger`
on phones. Ctrl/⌘+K opens it from anywhere (and refocuses the input when open); `/` opens it
outside inputs, textareas, selects and editable regions. It asks the product's own
`GET /api/suite/search` (same origin, `credentials: "same-origin"`, `cache: "no-store"`, 10 s) and
validates the answer against the C2 limits; an answer for another query or workspace is an error.
Results are one group per product, the host product first.

- **A failed or timed-out app is named as unavailable; No results appears only when every app
  answered.** Every product whose coverage is not `ok` gets a note (`.nx-command__note`, warning tone
  for `failed` / `timeout`), outside the listbox; the status then says some apps could not be searched.
- A request failure says sign in again (401), not available for this workspace (403) or could not be
  loaded (anything else), each with Try again. It is never shown as no results.
- Breadcrumb segments (`path`) are record data joined by `ChevronRight` (`.nx-command__sep`,
  `aria-hidden`), mirrored in RTL; titles and segments are isolated in `<bdi>`.
- Phones (< 768 px): the card fills the screen (`100dvh`, radius 0), the input is 16 px, every
  option, trigger and action is at least 44 px. `prefers-reduced-motion` removes the transitions.
- Recent searches are kept per workspace in this browser only (`localStorage`
  `nx-search-recent:v1:<workspace>`, at most 5), saved when a result is chosen, and can be cleared.
  Storage that throws is ignored.

React: `NxCommand`, `NxGlobalSearch`, `useNxAsyncSearch`, `nxSuiteSearchSource`,
`NxSearchRequestError`, `NX_SEARCH_COPY` (every `UI_LANGUAGES` entry). Contract:
`specs/features/nx-global-search/spec.md`.

### Primitives

#### `NxDivider` — `.nx-divider` {#nx-divider}
1px hairline rule for separating stacked content within a panel.
React: `NxDivider`.

#### `NxAvatar` — `.nx-avatar` {#nx-avatar}
Circular accent-filled initials badge. React: `NxAvatar`.

#### Agent faces — `NxAgentFace`, `NxAgentLauncher`, `agentFace()` {#agent-faces}
Every AI agent (SkyONEx agents, chat bots) gets a generated face instead of an
uploaded picture or an emoji. The face is **deterministic for `(name, seed)`**: a head
(circle, rounded square, dome, blob), a pair of eyes (dots, ovals, visor, smiling arcs),
a mouth (none, line, smile) and either an antenna or the NX **x** spark, in one of the
[agent-face palettes](#agent-face-palette). Products store only the integer `seed`;
"roll a new face" is `seed + 1`. The draw order is part of the contract (changing it
changes every stored face).

- `agentFace(name, seed)` and `agentFaceSvg(name, seed, { shape, size, label })` live in
  the platform-neutral entry `@marcobeyer/nx-family/agent-face` (no React, safe in route
  handlers). `agentFaceSvg` returns a standalone SVG document; only `label` is caller text
  and it is escaped.
- `NxAgentFace` (`@marcobeyer/nx-family/react`): `shape="square"` (16px radius at 64, for
  lists, cards and profiles) or `"round"` (chat bubbles, launchers). Decorative unless
  `label` is given; print the agent's name next to it rather than labelling twice.
- `NxAgentLauncher`: the round 56px chat launcher button, a hairline ring, the face
  inside, `label` as the accessible name and `aria-expanded`. The public web-widget embed
  mirrors this look in plain JS.

Sizes: 28 (nav rows), 40 (list rows), 56 (cards, launcher), 96–120 (agent profile).
Do not put a face inside another coloured tile or circle; it is its own tile.

#### Icon button — `.nx-iconbtn` {#nx-icon-button}
Square icon-only control for compact actions (close, more, toggle) — no
dedicated NxKit wrapper, apply the class directly.

Other primitives in this group: `.nx-btn--danger`, `.nx-btn--sm`, `.nx-btn--outline`
(P0.5) (Button modifiers — see [`NxButton`](#nx-button)). Theme control: `NxThemeToggle`
(flips `data-theme` on `<html>`).

---

## Charts {#charts}

Charts follow the data-viz method — **form → colour-by-job → validate → marks →
hover → a11y** — built as token-driven SVG.

- **Categorical palette:** `--nx-chart-1…6`, the CVD-validated dataviz reference set
  (worst adjacent ΔE ≥ 12 in light; the floor band in dark, so ≥ 4 series lean on
  direct labels / legend). Assign in **fixed order**; a 7th series folds into
  "Other" or small multiples — never a generated hue.
- **Marks:** thin (2px lines, ≥ 8px markers, 4px rounded bar data-ends), a 2px
  surface gap between adjacent/stacked fills, recessive grid (`--nx-chart-grid`) and
  axis (`--nx-chart-axis`), **selective** direct labels (never a number on every
  point), a legend whenever ≥ 2 series.
- **Text wears ink/slate, never the series colour.** Status colours are reserved
  (never "series 4"). **One y-axis only** — never dual-axis.
- **Dark:** the palette ships its own validated dark steps (auto via `data-theme`).
  Chrome classes: `.nx-chart`, `.nx-grid line`, `.nx-axis`, `.nx-legend`.
- **Magnitude/polarity:** sequential = one-hue light→dark ramp; diverging = two
  poles + a neutral gray midpoint (see the `dataviz` skill for the ramps).

The showcase renders bar (single series), line + area (two series), a donut, and
stat tiles against these tokens.

---

## IA & actions {#ia-actions}

How a screen is put together, so every NX product feels like one family:

1. **One primary action per view**, in the `NxPageHeader` — the thing this page
   exists for. Everything else is secondary (≤ 2) or in a menu.
2. **Context lives in the top bar and is sticky.** Choose it once
   (`NxContextSwitcher`); every page below implies it — filters, defaults of new
   items, KPIs — and shows it. A URL parameter may override it for shared links.
3. **Side sheets ask for at most 5 fields.** Everything else is implied from the
   page (the campaign you are on), from the context (the brand), defaulted (owner
   = me, status from dates, slug from name) or behind `NxDisclosure` "Mehr
   Optionen". A longer form is a page, not a drawer; a sequence is a stepper.
4. **Every empty state names the next action** (`NxEmptyState`, `action` required).
5. **Speak the user's words**, not the data model's: "Beitrag schreiben", not
   "Maßnahme anlegen".
6. **One place per setting.** Connections live on one Accounts page
   (`NxIntegrationCard`); anything blocked by a missing connection links there
   instead of carrying its own connect button.

### Icons instead of text arrows {#ui-icons}

All NX product interfaces use SVG icons for visual actions and navigation.
Do not use Unicode arrows such as `→`, `←`, `↗`, `›` or `»`, HTML entities,
ASCII substitutes such as `->`, or CSS-generated text as UI icons. Keep these
glyphs out of button/link labels, breadcrumbs, pagination and workflow connectors.

- Prefer **Lucide** through the app's existing icon component or package. Use
  `ArrowRight`/`ArrowLeft` for directional actions, `ChevronRight`/`ChevronDown`
  for navigation or disclosure, and `ExternalLink` for external destinations.
  Another established SVG icon is acceptable when Lucide does not fit; keep
  stroke weight, sizing and alignment consistent with the surrounding UI.
- Keep translated labels as text and render icons separately. Use `currentColor`
  and the existing component's icon sizing/spacing. Mirror directional icons
  appropriately in RTL layouts; external-link symbols keep their meaning.
- Decorative icons alongside a label use `aria-hidden="true"`. Icon-only
  controls need a translated accessible name and a visible focus indicator.
- Apply this rule to new and modified UI. Literal arrows in user content,
  code samples or explanatory notation may remain when they are content.

### Guided AI assistance {#guided-ai}

When AI is enabled, content and planning forms offer a visible **AI assist** entry
near the fields it supports. Start with the user's brief, ask concrete follow-up
questions for missing information, and present field suggestions with short
explanations. Show progress while generating. Users apply suggestions explicitly
to their unsaved form; keep their edits and reject stale suggestions. Saving,
approval and publishing remain separate, clearly named actions. Never fill
credentials, access rights, consent or lifecycle status through AI suggestions.

Long editors keep primary actions visible with a padded sticky action bar and
explain disabled actions in visible text. Keep publishing options reachable from
that bar with a control that opens them in place (a popover with the date and
platforms) — never a jump link dressed as a dropdown. Use optional brand-colour dots only for configured
colours; never render empty placeholder circles.

### Suite work in the header {#suite-work}

Every suite console provides the shared `NxSuiteWork` header controls for tasks
and notifications when its NX account connection is configured. Carry the
verified NX workspace identity when available. These controls open the central
work hub; source apps remain responsible for task records and permissions.
Only show counts when they come from an authorized source; absence of a count
does not mean the user has no work. Provide localized accessible labels.

### Navigation within a section {#section-nav}

The app sidebar (`NxAppShell`) chooses the **area**. Inside an area, pick one of two patterns
(the common convention: shadcn's examples, GitHub, Vercel, Stripe, Linear). Both live in
`@nx-family/ui` (`NavTabs`, `SectionNav`).

1. **Horizontal tabs for a few peer views of one area**: about 3–7 views of the same thing
   (ordNX Marketing: Overview · Posts · Calendar · Campaigns · Brands · Reports). Each tab is a
   link with its own URL (`aria-current="page"`), not a `role="tab"` widget; `NxTabs`/`NxSegmented`
   remain for switching views *inside* one page.
2. **About 7 tabs, then "More".** Places used less often go into one overflow tab that opens a
   menu. It looks like a tab (same type, underline slot, an SVG chevron), not a bordered button,
   and when one of its places is open it shows **that place's name**, underlined.
3. **A vertical in-page section nav for settings-like pages**: many independent sections of one
   page (Settings: General · Users · Marketing). It is a column **inside the page content, under
   the page title**, on the content gutter. Optional group headings.
4. **Never a second full-height sidebar.** No panel that runs from the top bar to the bottom of the
   viewport next to the app sidebar, with its own background and border. Two sidebars read as two
   apps.
5. **No nested scroll containers for navigation.** Section navs and tab rows never get their own
   vertical scroll area (`overflow-y`, a viewport-height box). They scroll with the page; a
   section nav shorter than the viewport may be `sticky` just below the app's sticky top bar
   (measured, not a guessed offset), otherwise it is not sticky. The only allowed scroll is a
   tab row's horizontal one on a narrow screen.
6. **Active state:** exactly one current item, marked with `aria-current="page"` and visible
   without colour alone: tabs get the 2px accent underline flush on the divider plus the
   accent-700 semibold label; section-nav items get the accent-50 tint with accent-700 semibold
   text (the `NxAppShell` nav look). Keyboard focus shows the kit's focus outline.
7. **Mobile:** below `lg` the section nav becomes a horizontally scrollable tab row with the same
   items (or a select for very many), directly under the page title; the active tab is scrolled
   into view. It is not a separate chip bar with its own styling, and tab rows do not
   hide behind the sticky top bar.
8. **Breadcrumb + page title.** Every page has one `h1` title on the content gutter
   (`NxPageHeader`, or the shadcn `Breadcrumb` + title of the post studio). A page below an area's
   tab (a campaign, a post) shows a breadcrumb above the title (Marketing › Campaigns › this
   one); on a phone the trail collapses to a back link to its parent with a chevron icon. Never a
   loose "← Back" link off the gutter. Section headings inside a settings page are one step
   smaller than the page title.

## 6. Accessibility

- **Focus:** interactive controls show a visible focus indicator — buttons use a
  `2.5px` ink outline (`:focus-visible`); inputs use the accent border + glow.
  Never remove focus styling without an equivalent.
- **Contrast:** use accent-**700** for text on accent-50/100 tints; accent-600 is
  for fills and large/graphic elements. Body text is `--nx-ink` on white/paper.
- **Motion:** all mark animation is gated behind `prefers-reduced-motion`.
- **Semantics:** tabs expose `role="tablist"/"tab"` + `aria-selected`; the lockup
  carries the full accessible name while its SVG is `aria-hidden`.
- **Profile actions:** account actions live behind one labelled avatar trigger;
  the menu follows roving-focus keyboard behavior and returns focus on close.
- **Uploads:** the drop target is also a labelled native file picker, so drag and
  drop is never the only interaction path.
- **Icon-only content** (row icons, avatars) is decorative shorthand — pair with a
  text `title`/`sub` for meaning.

---

## 7. Do / Don't

**Do**
- Theme with one `data-nx-product` / `NxThemeProvider`; let tokens cascade.
- Use accent tints (50/100) for surfaces and 600/700 for ink-on-tint + actions.
- Reach for `NxMark tight` inside text (lockups); square elsewhere.
- Keep the mark's `n` neutral and let only the `x` carry colour.

**Don't**
- Hard-code hex in components — always go through `--nx-*`.
- Add drop shadows or a second accent to a single product surface.
- Recolour the mark's `n`, add a per-product glyph, or outline the wordmark.
- Build certNX's certificate/portal surface from this kit (see §8).
- Merge the DRAFT staging PRs (checknx#78, ordnx#28) — they carry the superseded
  June assets; regenerate from `assets/` first.

---

## 8. certNX is standalone

`certNX` belongs to the family **by mark and tokens** — use `<NxMark variant="cert" />`,
the azure ramp, and `assets/certnx/` for badges/seals. But the shared app kit
(`NxProductHeader`, `NxKpiTile`, list rows, everyday-app surface) belongs to the
**everyday-app members** — ordNX, CheckNX, FileNX, FirmNX, coproNX, hostNX. Certification carries disclosure/trust obligations and gets a
more formal, document-grade surface, so certNX credentials and audit views should
**not** be built from these components. Same family, deliberate distance.

**Docs-site decision (DS-3):** certNX is the family's one **non-family-app, standalone azure
mark** — it gets no dedicated component/foundation entry and no standalone certNX docs page
in `docs-site/`; the caveat above (and the accent-ramp row in §1.2) is the complete, intentional
extent of its coverage here.

*(Open partner call: reconcile this family certNX mark vs the older
`templates/brand/assets/certnx.svg` in the `ipmnx-company` vault — which is
canonical? See that vault's `company/tasks.md`.)*

---

## 9. Where things live

```
packages/nx-family/
├── design.md              ← this file (the spec)
├── README.md              ← install + usage guide
├── FAMILY-PREVIEW.html    ← canonical family preview
├── index.html             ← living gallery: every brand + component (+ theme playground)
├── demo.html              ← kit verification page
├── tokens.css             ← foundations (source of truth for §1–§2)
├── kit.css                ← component styles (source of truth for §5)
├── tailwind.nx.cjs        ← optional Tailwind token map
├── mark.tsx               ← the mark (§3)
├── react.tsx              ← components (§4–§5)
├── dist/                  ← compiled react/mark + types (what consumers import)
├── registry.js            ← structured spec powering docs-site/ (keep in sync with §5)
└── assets/<member>/       ← standalone SVG (+ PNG) exports (§3.2)
```

## 0.16.0 — hostNX (2026-11-17) {#v0160-changelog}

Additive, no migration: the `host` product theme and mark variant join the family with a
`#BE123C` **rose** signature (`50 #FFF1F2` · `100 #FFE4E6` · `600 #BE123C` · `700 #881337`),
the regular prefix-plus-ligature `hostNX` lockup, the `--nx-family-host` tint for
`.nx-suite-product--host` / `.nx-move-notice--host`, and the complete SVG asset set under
`assets/hostnx/` (the standard `firmnx`/`copronx` composition). Until now hostNX had no
variant and the app switcher drew it with the neutral `nx` mark, which made its tile read as
suiteNX.

Rose was chosen to sit clear of every other signature: ordNX violet, CheckNX blue, certNX
azure, FileNX emerald, FirmNX ochre, SkyONEx sky, coproNX terracotta (an orange-brown, where
rose is a cool red) and the retired pointNX teal.

Contrast is measured with the WCAG relative-luminance formula, not assumed: white-on-`600`
is **6.3:1** (AA), `700`-on-`100` **8.0:1** and `700`-on-`50` **8.7:1** (both AAA), and
`--nx-slate-500` body text on the `50` tint is **5.3:1** — so hostNX needs **no** dark-ink
`--nx-on-accent` override. Like every product accent, the `600` is theme-invariant; dark
theme derives the 50/100/700 tints from it by the shared rule.

The `NxVariant` / `NxProduct` unions, the `ACCENT` and `PREFIX` maps, the
`[data-nx-product="host"]` ramp and the `@nx-family/suite` `NxVariant` land together —
`packages/suite/tests/registry.test.ts` reads the kit source and fails if either half ships
alone. `NxIntroProduct` and `NxSuiteProduct` no longer list `"host"` separately, since
`NxProduct` now contains it (same resulting type). formNX gets no variant. The package version
moves from `0.15.0` to **`0.16.0`**.

## 0.14.0 — suite fold components (2026-11-16)

New: [`NxHandoffStatus`](#nx-handoff-status), [`NxSourceCoverage`](#nx-source-coverage),
[`NxMoveNotice`](#nx-move-notice) and [`NxSecretReveal`](#nx-secret-reveal) for the suite
consolidation (issues #830–#833), plus the shared `.nx-suite-product` mark that tints a product by
its `--nx-family-*` colour. Existing tokens only, flat, light and dark. Additive only — no
breaking change.

## 0.13.0 — allowlist rows (2026-11-16)

- New `NxGrantRow` / `.nx-grant-row` ([[#nx-grant-row]]): source badge, path, written-out scope,
  file-type chips, labelled remove button. Additive; no existing class changed.

## Command search (2026-10-26)

New: [`NxCommand` and `NxGlobalSearch`](#nx-command) (K-31), the shared `useNxAsyncSearch` hook,
`nxSuiteSearchSource`, `NxSearchRequestError` and `NX_SEARCH_COPY`. `NxRelationPicker` now runs on
`useNxAsyncSearch`; its markup and behaviour are unchanged. Additive only; apps show the global
search only behind their `<product>.global-search` flag.

## 0.9.3 — navigation within a section (2026-10-10)

New rule set [Navigation within a section](#section-nav): tabs for a few peer views (about 7,
then "More"), an in-page section nav for settings, never a second full-height sidebar, no
nested scroll containers for navigation, active and mobile behaviour, breadcrumb + page title.
The components are `NavTabs` and `SectionNav` in `@nx-family/ui`. Docs only, no kit CSS or API
change.

## 0.9.2 — disclosure chevron (2026-10-10)

`NxDisclosure`'s marker is an SVG chevron (CSS mask, `currentColor`) instead of the text glyph
"▸" ([UI icons](#ui-icons)); it points to the reading direction when closed (mirrored in RTL)
and down when open. CSS only, no API change. [Guided AI](#guided-ai): publishing options open
in place from the action bar instead of a jump link.

## 0.9.1 — overlays and marks (2026-10-09)

Fixes: `NxDropdownMenu`'s open panel is placed at fixed viewport coordinates
from its trigger, so a scrolling ancestor (a tab bar with `overflow-x`, a
table wrapper) no longer clips it into a scroll strip. `NxPlatformBadge` uses
accurate brand marks and shows a published post in the platform's colour
(`--nx-brand-*` tokens); new `NxPlatformIcon`. `NxAppShell`: no rubber-band
overscroll on the page and none chained from the sidebar, so the sticky sidebar
and top bar stay put.

## 0.9 — IA & actions (2026-10-09)

New: `NxContextSwitcher` (+ `NxAppShell` `context` slot), `NxPageHeader`,
`NxSegmented`, `NxPlatformBadge`, `NxStatStrip`, `NxIntegrationCard`
(+ `.nx-card__footer`), `NxDisclosure`, `NxEmptyState`, `NxColorField`
(+ `NX_COLOR_PRESETS`); `NxField` renders `hint` / `error`. Registered the
existing `NxGettingStarted` and `NxDropdownMenu`. New section
[IA & actions](#ia-actions). Additive only — no breaking change.

## DS-1 changelog {#ds-1-changelog}

Foundations pass on top of §1–§9 above: scale tokens, interaction states, a
density mode, a11y hooks/behaviors, an RTL logical-property sweep, and a dev-only
axe self-audit in the showcase. **Full reference tables (values, usage matrices)
are deferred to DS-2** — this is a pointer to the new names plus the breaking
list below.

**New tokens** (pointer only — see `tokens.css` for values):
- Scale: `--nx-space-*`, `--nx-size-*`, `--nx-radius-*`, `--nx-border*`
- Focus/ring: `--nx-focus-outline-*`, `--nx-ring`, `--nx-ring-danger`
- Motion: `--nx-dur-*`, `--nx-ease-*`
- Layering: `--nx-z-*` (incl. `--nx-z-root`, see breaking change 2 below)
- Type: `--nx-fw-*`, `--nx-leading-*`
- Layout: `--nx-row-icon`
- Status: new dark overrides, plus `--nx-success-solid`, `--nx-danger-50`, `--nx-danger-100`
- State: `--nx-disabled-opacity`, `--nx-state-hover`, `--nx-state-active`, `--nx-press-y`, `--nx-selected-bg`

**New primitives & mechanisms:**
- **Density:** `data-nx-density` attribute + density-scoped role tokens
  (compact/comfortable).
- **Primitives:** `.nx-empty`, `.nx-spinner`, `.nx-sr-only`.
- **A11y behaviors:** `useFocusTrap`, `useBodyScrollLock`, roving-tabindex
  menu/tabs, live-region alerts, a hoverable + dismissible tooltip, and
  `forced-colors` + reduced-motion coverage.
- **RTL:** logical-property sweep across the kit.
- **Showcase:** a dev-only axe self-audit (see breaking change 4 for known,
  by-design findings).

### Breaking changes (adopt-time)

Flag for checknx / ordnx / pointnx / cosmethicals maintainers before bumping:

1. **`NxTabs`** markup changed `<span>` → `<button role="tab">`. Any consumer
   CSS/markup keyed on `.nx-tabs span` must move to the class/role selector.
   Roving tabindex means the tablist is now **one** tab stop (was N stops).
   `aria-controls` is now **opt-in** via a new `panels` prop (default off) —
   pass `panels` and render matching `role="tabpanel"` elements. Id contract:
   tab `${idBase}-${i}` ↔ panel `${idBase}-panel-${i}`.
2. **Z-index band** moved from ~100 to a documented **1000–1600** band. Host
   chrome (toasts, banners) still living in the old 100–999 range now renders
   **below** kit overlays — mitigate with `--nx-z-root` to offset the whole band.
3. **`.nx-drawer--left`** now means **inline-start** (auto-flips under RTL). The
   API name is unchanged; the semantic is no longer "always screen-left."
4. **Contrast nudges are deferred (Task 10, partner-gated).** The AA
   `color-contrast` fixes for `--nx-slate-500`, pointNX's `--nx-accent-700`, and
   white-on-light-accent tiles are **not** part of DS-1 — applying them repaints
   live products. Until they land, the showcase's axe self-audit reports
   `color-contrast` violations for these **by design**; don't file them as DS-1
   regressions.

**Notes:**
- **`NxAlert` live-region caveat:** a polite (`role="status"`) alert announces
  reliably only if the live region already exists in the DOM before its text
  changes. Render a persistent, empty alert container and inject text into it
  (mount-empty-then-populate) — don't mount the alert already carrying its
  final text.
- **Spec reconciliation:** the compact `--nx-menu-item-min-h` ships at **28px**
  (= `--nx-size-7`); the DS-1 planning spec's table said 30px. Both are ≥24px
  WCAG-safe — **28px is canonical**, the planning doc is superseded here.

**DS-added:** the emerald family member — then `doc`/DocLinQ, renamed to `file`/FileNX 2026-08-02.

### P0.5 — DocLinq re-skin primitive gap-fill (2026-07-14) {#p05-changelog}

Task P0.5 audited DocLinq's **actual** HeroUI component usage (`apps/main/src`,
`apps/website`) ahead of its Phase 2 nx-\* re-skin, to close only the primitive
gaps real call sites need (YAGNI — no speculative variants). CSS-only; `react.tsx`/
`mark.tsx` untouched.

**Added:**
- `.nx-btn--outline` (+ `:hover`/`:active`) — HeroUI `variant="bordered"` (dominant
  labeled-secondary-button variant in DocLinq, 24 call sites) and `variant="flat"`
  (3 call sites, all semantically-equivalent dialog Cancel buttons — consolidated
  onto the same class rather than adding a fourth near-duplicate neutral modifier).
  Neutral tone (`--nx-ink` text, `--nx-hairline` border, `--nx-state-hover`/
  `-active` overlay) — deliberately distinct from the accent-tinted `--ghost`,
  matching the "NEUTRAL controls use `--nx-state-*`" rule already documented for
  the DS-1 state model.
- `.nx-card__header` / `__title` / `__description` — DocLinq's `CardHeader` always
  wraps `CardTitle`(+`CardDescription`); ~19 real call sites across dashboard tiles
  and auth/settings forms.

**Audited, found already covered (no change):** icon-only buttons (real usage is
`variant="ghost"`/`"bordered"` + `isIconOnly` or icon-only sizing — maps onto the
existing `.nx-iconbtn`, per the brief's stated preference); the `[aria-busy]` +
`.nx-btn__label` + `.nx-spinner` loading contract (DocLinq's 4 auth submit buttons
already wire `aria-busy` by hand — the existing contract is an exact match); Badge
and Alert (each has exactly one real call site, neither passes a color/severity
prop — the existing `--soft/--success/--warning/--danger` sets already exceed
what's used); Input/Textarea/NumberInput/Select field states (`label`,
`description`, `isRequired`, `isInvalid`, `errorMessage`) — already fully carried
by `.nx-field__label/__hint/__error` + `[aria-invalid]`; Tabs/Checkbox/Radio
(default variant only); Progress/Switch/the design-system Tooltip (not used
anywhere in DocLinq today).

**Audited, found NOT needed despite being called "likely missing" in the task
brief** (i.e. the brief's a-priori guess didn't survive contact with real usage —
flagging so the next audit doesn't re-add these speculatively):
- `.nx-btn--md`/`--lg` — DocLinq never passes an explicit Button `size` other than
  `"sm"` (already covered by the existing `.nx-btn--sm`).
- `.nx-btn--success`/`--warning` — DocLinq's only Button `color` values are
  `"primary"` and `"danger"` (and the untinted default), both already covered.
- Avatar size modifiers — DocLinq's one real Avatar usage renders at exactly
  32px (`h-8 w-8`), i.e. the existing default `.nx-avatar` (`--nx-avatar-md`).
  No second size is used, so none was added.

**Considered, deliberately deferred (not a kit.css concern):**
- Button leading/trailing icons (`startContent`/`endContent`, ~4 real call sites)
  and full-width text-centering (submit buttons, 4 call sites) both need
  `display:inline-flex`/`gap`/`justify-content` — properties `.nx-btn` doesn't
  set today. Cross-repo precedent (PointNX's `Hero.tsx`: `className="nx-btn
  nx-btn--primary inline-flex h-12 min-h-11 gap-2 px-6 ..."`) shows the
  established convention is consumer-side Tailwind layout utilities alongside the
  kit's color/shape classes, not baking layout into the shared `.nx-btn` rule —
  so DocLinq's re-skinned Button *wrapper* should add its own `inline-flex
  items-center justify-center gap-*` base classes, not kit.css.
- One-off shape overrides reached via `className` rather than a component prop —
  the nav-user Avatar's `rounded-lg` (square, not circular) and a handful of
  `Skeleton` shapes (`rounded-full`/`rounded-none`) — are per-instance styling
  the same way arbitrary width/height already is, not a prop-level variant.
  Note for the re-skin: DocLinq's global CSS loads `kit.css` unlayered
  (`apps/main/src/app/[locale]/layout.tsx` imports it before
  `@workspace/ui/globals.css`'s `@import "tailwindcss"`), and per the CSS
  Cascade Layers spec unlayered rules beat *any* `@layer`-wrapped rule
  (Tailwind v4 utilities included) regardless of source order — so a Tailwind
  shape utility alongside an `nx-*` class that already sets that same property
  will silently lose. The reliable override for a one-off is an inline
  `style={{ borderRadius: "var(--nx-radius-full)" }}` (still 100% token-driven),
  not a new shared modifier for a single call site.
- A leading-icon affordance for `.nx-field__input` (one real call site: the
  search page's search icon + clear button) — needs a wrapper/slot structure
  with no existing kit precedent to match; flagged for whoever re-skins that
  screen rather than invented here.
- Select `selectionMode="multiple"` (approver/acknowledger pickers) — HeroUI's
  default multi-select `renderValue` is plain comma-joined text (neither call
  site supplies a custom `renderValue`), so the existing single-line
  `.nx-select` styling already covers it visually; the multi-select behavior
  itself is a `react.tsx` / ARIA-listbox concern, out of scope for this
  CSS-only pass.

### 0.8.0 — coproNX (2026-09-05) {#v080-changelog}

Additive, no migration: the `copro` product theme and mark variant join the
family with a `#9A3412` **terracotta** signature (`50 #FDF3EE` · `100 #F8DCCB` ·
`600 #9A3412` · `700 #7A2810`), the regular prefix-plus-ligature `coproNX`
lockup, and the complete SVG asset set under `assets/copronx/`.

Contrast is measured, not assumed: white-on-`600` is **7.3:1**, `700`-on-`100`
**7.5:1**, `700`-on-`50` **9.0:1** — all comfortably AA — so coproNX needs **no**
dark-ink `--nx-on-accent` override (no current member does; the retired pointNX was the only one).

The `NxVariant` / `NxProduct` unions, the `ACCENT` and `PREFIX` maps, the
`[data-nx-product="copro"]` ramp and the `@nx-family/suite` roster entry
(`NX_APP_COPRO_URL`) all land together — `packages/suite/tests/registry.test.ts`
reads the kit source and fails if either half ships alone. The package version
moves from `0.7.0` to **`0.8.0`**.

### 0.7.0 — the suite's own key (2026-09-11) {#v070-changelog}

Additive, no migration: no existing token, class, component or prop changes shape, so
`0.6.0` → **`0.7.0`** per the semver convention in `ADOPTION.md` (minor = new token). Every
existing consumer renders byte-for-byte what it rendered before — nothing outside
`[data-nx-product="nx"]` is touched.

Driven by **nx-account**, the one NX surface the kit had no answer for. It is the IdP every
product's OIDC flow redirects to plus the control plane behind it, and it is not a product:
there is no `nx` accent to theme it with, and the fallback for an unset `data-nx-product` is
`:root` — ordNX's violet. So the suite's login shipped in hand-rolled, dark-only CSS that
matched nothing, and adopting the kit would have meant choosing between misbranding it as
ordNX and inventing an eighth brand hue.

**Added — `data-nx-product="nx"`** ([the suite accent](#suite-accent)): the shared neutral
foundation promoted into the accent channels (600 = `--nx-slate-700`, 700 = `--nx-ink`,
100 = `--nx-slate-300`), so it needs no partner accent decision — it introduces no colour the
family had not already approved. `"nx"` joins `NxProduct` in `react.tsx`, which makes
`NxThemeProvider` / `NxAppShell` / `NxProductHeader` accept it; `NxVariant` (mark.tsx) already
had `"nx"`, and `NxLockup product="nx"` already renders mark-only (`PREFIX.nx` is `""`).

Two details that are the whole reason this is a token change and not an app-local override:

- **Its 600 inverts in dark theme** — the only accent in the kit that does. A neutral 600 has
  no hue to carry it onto a near-black ground (`#334155` on `#0B0E14` ≈ 1.7:1), so dark theme
  restates the 600 as a light graphite with a literal ink `--nx-on-accent`. Only those two
  declarations are restated; the 50/100/700 tints keep deriving from the 600, so selected
  rows, pills and KPI text re-resolve for free. The override is written as a **compound**
  `:root[data-theme="dark"][data-nx-product="nx"]` as well as the descendant form, because
  every real consumer puts both attributes on the same `<html>` element — a descendant
  combinator alone would have been dead code, which is the same reason the kit's existing
  derive rule leads with `:root[data-theme="dark"]`.
- **Its 50 is one step off `--nx-surface-2`**, not equal to it. `--nx-accent-50` is the
  "current/selected" fill and `--nx-surface-2` is the neutral hover; at the same value
  `NxAppSwitcher`'s current tile is indistinguishable from a hovered one. `#E2E7EF` keeps
  `--nx-slate-500` body text at 4.65:1 on it — the DS-1 Task 10 floor every accent-50 clears.

`tools/gen-palette.mjs` learned the key, and its block regex is now anchored at line start:
the theme-scoped `[data-theme="dark"] [data-nx-product="nx"]{…}` override restates only the
600 channel, and an unanchored match let that partial block overwrite the full light-theme one
and fail as `--nx-accent-50-rgb missing`. That guard also covers the next per-product dark
override, whoever adds one.

### 0.6.0 — SkyONEx + account/upload patterns (2026-08-14) {#v060-changelog}

Additive, no migration: the `sky` product theme and mark variant join the family
with a `#0369A1` signature, a companion-mark `SkyONEx` lockup, and the complete
SVG asset set under `assets/skyonex/`.

Two shared interaction patterns move out of the SkyONEx app and into the kit:
`NxProfileMenu` composes the existing avatar/menu primitives into compact suite
chrome and accepts consumer-owned Lucide icons; `NxFileUpload` provides one
controlled, keyboard-accessible picker/dropzone with guidance, selected-file
feedback, and removal. The package version moves from `0.5.0` to **`0.6.0`**.

### 0.5.0 — inline document preview (2026-08-04) {#v050-changelog}

Additive, no migration: nothing existing changes shape, so `0.4.0` → **`0.5.0`**
per the semver convention in `ADOPTION.md` (minor = new component/token/prop).
Driven by firmNX, whose every document affordance was a download — an operator
checking a scanned accusé had to leave the app for the OS downloads folder.

**Added — `NxDocumentPreview`** (`react.tsx`, `.nx-preview` in `kit.css`; see
[the component entry](#nx-document-preview)). Three deliberate constraints, all
of them the reason it can live in the shared kit at all:

- **No i18n, no fetching, no dependency.** Consumers disagree on i18n (firmNX
  has its own `useT()`, FileNX uses next-intl), so all six strings arrive as
  `labels`, already interpolated — a fragment the component concatenated with
  the filename would not survive translation into Arabic, and an accessible
  name assembled that way is exactly where that breaks. `src` is a plain
  string, never resolved: that is what lets one component render both a stored
  document and a not-yet-uploaded local file (`URL.createObjectURL`) whose
  revoke lifecycle stays with the caller that owns the `<input type="file">`.
- **Honest states.** `<img>` gets a real `loading|ready|error` ladder off its
  own load/error events. The PDF `<iframe>` gets **none** — it fires no usable
  error event for content-level failures, `onload` fires for error documents
  too, and a browser-rendered PDF has no meaningful `contentDocument` to probe;
  any detection would be a heuristic that lies in both directions. So the
  download link is rendered beneath the frame **whenever `downloadHref` is
  given**: worst case is an empty frame above a link that works. Omitting
  `downloadHref` (the pre-upload case, where the file is on the user's own
  disk) is legitimate but leaves no escape hatch, so a consumer that omits it
  must also pass error copy that does not say "download the file".
  The `<img>` state is keyed by `src` and reset **during render**, never from an
  effect: a `blob:` or cached image can fire `load` before React flushes passive
  effects, so an effect-based reset would overwrite `ready` with `loading` and
  strand a perfectly good image at `opacity:.45` forever.
- **No `sandbox` on the frame** — Firefox's pdf.js requires `allow-scripts
  allow-same-origin` to render, which grants back what a same-origin frame
  already has. The real control is the host app's upload MIME allow-list plus
  `X-Content-Type-Options: nosniff` on the byte route. Recorded as a named
  residual rather than a silently-broken feature in one browser family.

A11y/RTL: the `<iframe>` carries `title` (an untitled frame is a WCAG 4.1.2
failure — that is why `labels.pdfFrame` is required) and the `<img>` an `alt`;
the filename caption is `dir="ltr"` + `unicode-bidi:isolate`, since a filename
is inherently LTR data inside Arabic chrome. Dialog semantics, Escape, focus
trap and focus restoration are **not** reimplemented — compose with `NxModal`.

**Added — `NxModal` `size?: "default" | "wide"`.** `.nx-modal__card` is
`width:min(460px,100%)`, right for a form and unusable for a page of A4;
`--wide` is `width:min(920px,100%)`. `default` renders byte-identical markup to
0.4.0, so no consumer is forced to move.

**Fixed — overlays are now safe to compose INSIDE a `<form>`.** firmNX's
pre-upload preview is the first consumer to mount an `NxModal` inside a form
(previewing the file just picked in that form), which exposed two latent traps
that every consumer inherited:

- **`type="button"` on the `NxModal` / `NxDrawer` close "×".** A `<button>` with
  no `type` is a **submit** button owned by the nearest enclosing form, and
  these overlays render in place (no portal). So "dismiss this overlay" also
  submitted the form — in firmNX that meant uploading a document, or closing a
  fiscal obligation and archiving its accusé, from a click that meant nothing of
  the sort. `e.stopPropagation()` on the card cannot help: stopping propagation
  never cancels a default action. (`NxThemeToggle` got the same treatment for
  the same latent reason.) Purely additive — no consumer relied on the overlay
  chrome submitting anything.
- **`useFocusTrap` makes Escape terminal** (`e.stopPropagation()` before
  `onEscape`). The listener is bound to the trapped node, so with nested
  overlays one Escape bubbled through every ancestor trap and collapsed the
  whole stack — dismissing a preview also unmounted the form underneath it and
  discarded the operator's file selection. Innermost-dismisses-first is the
  correct semantic for nested traps and is a no-op for every single-level
  consumer.

**Known limitation (not a kit change): `NxModal` does not portal.** Mounted
inside an element that creates a stacking context — e.g. a `z-index`ed
`role="menu"` dropdown panel — its `z-index: var(--nx-z-modal)` is resolved
*inside* that context and the whole overlay, scrim included, can paint below a
sticky topbar at `--nx-z-sticky`. Nesting it in a menu panel is also invalid
ARIA. Consumers must mount overlays outside dropdown panels; firmNX's
`tests/unit/preview-placement.test.ts` guards this on its side.

**Not done (deliberate):** no Office/spreadsheet rendering and no server-side
conversion of any kind; no MIME→kind mapping in the kit (consumers need it
server-side and every file this package emits carries a `"use client"` banner);
no render test — this package has no test runner and firmNX's unit env is node
with no jsdom, so the component's guarantees are `tsc` + a cross-consumer
`turbo run typecheck` + manual browser verification, not a fake assertion.

---

Status: **review** — the mark + palettes are partner-approved (2026-07-03);
adopting this kit as the official in-app identity across the products is an open
partner gate (`company/tasks.md`, [ORG-14]).

## Task-based workspaces

Lead with the next useful action and its context. `NxActionQueue` and `NxNextActionRow` show why an item matters, its timing and one clear primary action. Reading or dismissing a notification never completes the underlying task. Keep unrelated actions in a secondary area and distinguish durable records from work awaiting action.

`NxRecordWorkspace` presents identity, relationship context, next actions and a chronological `NxTimeline`. Keep form help adjacent to the field. `NxRelationPicker` retains keyboard focus in its labelled combobox, announces pending/error/empty states and ignores outdated asynchronous results. Inline creation must use the same tenant authorization as ordinary creation.

Use `NxCaptureSheet` for short contextual capture and keep suggested changes in `NxSuggestionReview` until the person accepts them. `NxSaveFeedback` announces actual mutation state; success must follow persistence, never optimistic decoration alone.

Action areas use `NxResponsiveActionBar`, wrap on narrow screens, and keep targets at least 44px. Prefer actions in document flow. A fixed mobile navigation needs content padding and bottom safe-area allowance. Sticky form actions must reserve their own layout space, preserve visible error messages and avoid covering focused fields. Use existing tokens for warm white surfaces and product violet, readable text, restrained borders and generous spacing; communicate state through labels rather than unexplained circles.

## Evidence and revenue workspaces

`NxEvidenceCard` separates the claim (`title`, `children`), explicit
`statusLabel`, citation (`source.label`, `source.href`, optional
`source.publishedAt`) and qualification (`scope`). Only absolute HTTP(S)
citations become links; invalid citations retain their readable label. Dates
and status labels are consumer-owned translated text, never inferred proof of
a claim. Put an optional follow-up control in `action`.

`NxJourney` is a labelled navigation list of related work areas, not a progress
meter. Each step has `id`, a meaningful translated `label`, optional `value`
(including zero), `href`, and `current`; the current item uses `aria-current`.
Links accept local absolute routes, named hash anchors (letters followed by
letters, numbers, underscores or hyphens), or HTTP(S) URLs. Counts need meaningful
labels such as “Research sources”, rather than unexplained numbers. Do not
infer conversion, completion or a required order from the layout.

`NxNextAction` combines a `title`, contextual `children`, an optional decorative
consumer-supplied Lucide `icon`, and the consumer-owned `action`. All three are
exported from the React entry point and use neutral token surfaces, logical
properties, wrapping narrow-screen layouts, visible keyboard focus and 44px
control targets. They own no data fetching, state mutation, HTML injection or
translations.

### Versioned asset cards

`NxAssetCard` is a neutral, flat tile for library assets. It receives title,
preview, metadata and consumer-owned actions. It fetches no data and owns no
rights or approval decisions. Previews use `object-fit: contain`; logical sizing,
wrapping text, token colors, visible keyboard focus and 44px controls support
narrow layouts, dark theme and RTL. Show an explicit version and provenance in
metadata; never imply that a placeholder is a finished asset.

## Cross-product consistency and rollout (2026-10-15)

Application screens use the shared `--nx-font-sans` stack, semantic surface/text
colors, product SVG marks and header controls from the kit. Marketing pages may
keep their own typography. Product display names use a lowercase stem with `NX`
uppercase: ordNX, checkNX, fileNX, firmNX and coproNX. SkyONEx keeps
its established brand. Client IDs, domains, data keys and authenticator issuers
are independent contracts and must not change with display casing.

App selection shows the product name and a short localized purpose from its
manifest, and opens its declared application entry path. Services without an
application login do not appear as apps. Company names belong in the company
context; opaque internal customer IDs are never display names.

Appearance offers Light, Dark and Device through `NxAppearanceMenu`. The
`preferences` entry point owns validation, persistence and startup application.
When a person opens another app, the selector carries only validated theme and
preferred-language enums. Destination middleware consumes those parameters,
sets presentation cookies and redirects to the clean application URL before
its normal sign-in and tenant checks. API routes, authentication callbacks and
mutations retain their existing behavior. IPMNX subdomains share presentation
cookies; authentication cookies remain unchanged. Other domains synchronize
when opened from the app selector, including opening in a new tab. This does
not provide account-wide, cross-device synchronization.

Language controls list only shipped catalogs. The preferred language survives
an app that cannot translate it; that app uses English where available and
retains the preference for the next app. File table controls inherit the active
catalog, including pagination, column actions and empty states.

| Surface | Current translated UI |
| --- | --- |
| ordNX, checkNX | EN, DE, FR, AR, ES |
| firmNX, coproNX | EN, FR, AR |
| fileNX | EN, DE, FR, AR, DA, FI, NO, SV |
| SkyONEx | EN, FR, AR, Darija |
| Suite | EN |

Convergence proceeds in this order:

1. Share fonts, semantic tokens, app purposes, names and appearance controls;
   verify real desktop/mobile screens and preference handoff.
2. Translate missing EN/DE/FR/AR catalogs beginning with Suite, then
   firmNX, coproNX and SkyONEx. Ship a language only when its complete
   key set, ICU messages and RTL screens pass validation; preserve additional
   product languages.
3. Move remaining product-specific header/menu/table primitives onto the kit
   while preserving domain behavior and permissions. Use screenshot review at
   390px and desktop widths, in light/dark and Arabic, for each conversion.
4. Consider IPMNX app subdomains separately if operational benefits justify a
   reviewed DNS, redirect-URI and cookie migration. Presentation consistency
   does not require that migration.

Authenticated product shells show a short first-visit introduction, with the
canonical product purpose and three starting steps. Help reopens it in place.
The versioned dismissal flag contains only a fixed product key and is shared
between product surfaces on IPMNX subdomains; no identity or business record
is stored. The Suite customer hub enables this guidance. Auth's personal
security, AI connection lists, consent and action reviews have no product
introduction or Help control, keeping identity and permission flows focused.
`NxProductIntro` supplies the same localized, keyboard-accessible flow to
custom headers. Platform administration can opt out, and hostNX selects
its own introduction. (formNX did too until it was removed on 2026-11-17, #846; its intro
copy and the `form` member of `NxIntroProduct` / `NxSuiteProduct` went with it.)


## Shared mobile form and navigation contract (2026-10-18)

On touch devices or narrow viewports, editable native controls use at least
16px/1rem type, including consumer small-size adapters. Browser pinch zoom is
never disabled. `NxField` owns native attributes, refs, labels, descriptive
hints/errors and theme surfaces; app compatibility exports delegate to it.
A fixed `bg-white` is not a dark-mode input surface.

`NxAppShell` supplies the standard hamburger and role-filtered drawer. Search
can use the common phone opener with a kit modal, keeping the desktop field.
The canonical selector includes the suiteNX workspace hub independently of
paid product tiles; identity/security remains a separate destination. See
`specs/features/suite-mobile-consistency/spec.md` and the FileNX source audit
`docs/wiki/filenx-ui-audit.md` for implementation limits and browser verification.


### Workspace identity and navigation help

Product shells use `NxAppShell` with `organisationSwitcher` for the authenticated
workspace choices. The control sits below the product wordmark and inside mobile
navigation; it must not be hidden only inside a profile. Product hosts own the
validated options and switch action. Unavailable products remain disabled.
Help belongs in sidebar navigation, with one guide outside hidden containers and
focus restored to the mobile menu after a drawer-to-guide handoff. SkyONEx's
compatibility exports use the shared button/card/select/badge/dropdown controls;
editable instructions use NxTextarea and native constraints.


### Mobile identity and appearance placement

Product identity and the organisation selector belong inside the mobile drawer;
the phone header does not repeat the product logo. Appearance is in the drawer
footer using the host's existing preference handler, while its desktop header
slot is retained. App-owned mobile navigation must provide its own equivalent.
A shared boundary-only touch guard prevents vertical pull-down at the page edges
without taking over ordinary scrolling, history restoration, pinch or nested
scrolling. See specs/features/mobile-navigation-controls/spec.md.

### suiteNX display name (2026-10-19)

The customer hub is **suiteNX**. `NxLockup product="nx"` renders visible lowercase
`suite` followed by the existing neutral NX ligature; its accessible name is
`suiteNX`. Standalone `NxMark variant="nx"` remains the family device. Technical
`nx`/`nx-account` identifiers, client IDs and service addresses do not change.
Use `decorative` inside an already-labelled link; `label` overrides only its
accessible name. Account and Administration remain distinct identity surfaces.

## Conversation primitives (2026-11-16) {#nx-chat}

The SkyONEx inbox and the team chat share three primitives. Use them for any product that
shows a conversation; do not restyle a local bubble.

- **`NxChatBubble`** (`.nx-chat-bubble`) — `variant` is `user` (the customer or the person
  chatting; right-aligned, accent fill), `agent` (an AI agent; white with hairline) or `staff`
  (a human teammate; accent-50 tint, so a customer-facing human reply is never mistaken for the
  agent). `agent` and `staff` take an `avatar` slot (32px, decorative — the `author` line carries
  the name; pair with the agent face from SkyONEx). `meta` is a host-localized time, `dateTime`
  makes it a `<time>`. `footer` holds citations or actions. Wrap bubbles in `.nx-chat-thread`.
- **`NxSourceChip`** (`.nx-source-chip`) — numbered citation: `index` matches the superscript in
  the answer, `label` is the source name, `detail` the location ("Zeile 12"). A link only with
  `href`; pass `linkComponent` for locale-aware routing.
- **`NxInboxList` / `NxInboxRow`** (`.nx-inbox`, `.nx-inbox-row`) — one row per conversation.
  `status` is `open` (agent answers), `handoff` (a human is needed or answering) or `closed`;
  `statusLabel` is the host's localized word (Offen / Übergeben / Erledigt). `assignee` names who
  took it over; `unread` adds a dot plus bold title and needs `unreadLabel` for screen readers.
  `actions` (delete) sit outside the row link, never inside it.
- **Nav badge** — `NxAppShellNavItem.badge` shows a count after the label (`.nx-shell__navlink-badge`);
  `0`, `null` and `false` render nothing. Give `badgeLabel` ("2 waiting") so screen readers hear
  words instead of a bare number.
