Design spec
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 singledata-nx-productattribute re-themes an entire subtree. - Alpha-aware. Colors are stored as
R G Bchannels, so any token composes with an opacity (rgb(var(--nx-accent-600-rgb) / .7)or Tailwindbg-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)
| 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 |
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.
| 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 |
The NX row is not a signature (0.7.0). 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. A generated
agent face 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
| 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
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 use112on the 512 canvas (≈ 22%). - Padding rhythm: card body
18px· header16px 18px· KPI14px 16px· input9px 12px· button9px 15px. Vertical stack gap inside a card body is14px; tab gap18px.
1.5 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): thenstrokes in over0.6s, then the accentxfollows (0.5sdelay). 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
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 live in tokens.css. Two layers:
- 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>. rgb()aliases (--nx-accent-600,--nx-accent, …) — convenience, derived from the channels. Declared on both:rootand every[data-nx-product]so each themed subtree recomputes its aliases from its own channels.
<!-- the whole theme switch — every nx-* class inside recolours --><div data-nx-product="check"> … </div> <!-- "ord" | "check" | "cert" | "file" | "firm" | "sky" | "copro" | "host" | "nx" --><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: darkapplies automatically unlessdata-theme="light"is set.NxThemeToggleflips the attribute. - How it works: the dark block overrides the neutral channel vars on
:root; because thergb()aliases derive from those channels, every component recolours with no per-component dark CSS. The mark’snflips to light for free (it reads--nx-ink). - Accent tints are derived, not hand-picked: in dark,
--nx-accent-50/100become acolor-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-accentstays white.
| 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 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 380x: M424 156 L244 380 viewBox 0 0 512 512 · stroke-width 60 · round caps + joinsn= family constant, painted in--nx-mark-stroke(default--nx-ink, flips to paper on dark).x= per-product accent (--nx-accent). The parentnxvariant paints thexwith 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 allicon.svgare 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 (inkFile+ emeraldNX,viewBox960), and everyaria-labelin 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.
<NxLockup product="check" size={20} /> // "Check" + blue nx mark- Prefix casing (as shipped,
PREFIXinreact.tsx):check·ord·cert·file·firm·SkyONEx·copro·host· (none fornx). .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 old62 126 392 284crop, which clipped the top of the n’s arch; 1.10em keeps the same glyph size.) size(px) sets the lockupfont-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)
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 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.
<NxThemeProvider product="ord"> … </NxThemeProvider>5.2 NxButton — .nx-btn
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.
<NxButton>Start job</NxButton><NxButton variant="ghost">Assign</NxButton>5.3 NxCard — .nx-card / .nx-card__body
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
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).
<NxProductHeader product="check" avatar="AC" />5.5 NxKpiTile — .nx-kpi
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.
<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.
<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
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.
<NxListRow icon="NK" title="Nordküste — window clean" sub="09:30 · A. Berger" pill="On site" />5.7 NxStatusPill — .nx-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
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.
<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
__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-100glow (no default outline).
<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
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.
<NxTabs items={["Today", "Activity", "Settings"]} activeIndex={0} />NxNavTabs — .nx-navtabs
The .nx-tabs look as page-section navigation (rule 1 of
Navigation within a section): 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.
<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
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
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
Custom dot, accent when checked, accent-100 focus glow, :has(input:disabled)
dims. React: NxRadio.
NxChoiceCard — .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
38×22 track, accent when on, --nx-on-accent knob. React: NxSwitch.
NxSelect — .nx-select
Styled native <select> with caret; focus = accent border + glow.
React: NxSelect.
NxTextarea — textarea.nx-field__input
The field input, min-height 88, vertical resize.
React: NxTextarea.
NxColorField — .nx-color
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
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
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 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
“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
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__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
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)
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
Solid (default) + --soft / --success / --warning / --danger, optional
__dot. React: NxBadge.
NxAlert — .nx-alert
--info/--success/--warning/--danger — tinted surface, coloured
left bar + icon, ink body text (never colour-alone). React: NxAlert.
NxProgress — .nx-progress
__bar — accent bar on an accent-100 track. React: NxProgress.
NxSkeleton — .nx-skeleton
Shimmer on --nx-surface-2, reduced-motion aware. React: NxSkeleton.
NxSpinner — .nx-spinner
Small rotating ring, currentColor border-top, spin animation, reduced-motion
aware — one of the primitives added in the DS-1 changelog.
React: NxSpinner.
NxTooltip — .nx-tooltip
__pop — CSS hover/focus tooltip; inverts per theme. React: NxTooltip.
Empty state — .nx-empty
Centered icon + title + copy + action for a list/table with no data yet — one of
the primitives added in the DS-1 changelog. React (0.9):
NxEmptyState — action is required: an empty state always names the next
step (IA & actions).
NxIntegrationCard — .nx-integration
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
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
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
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
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
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
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
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
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
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
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
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
(+ __sep / __current). React: NxBreadcrumb.
NxMenu — .nx-menu
__item (+ --active) / __sep — popover list with overlay shadow.
React: NxMenu.
NxProfileMenu — .nx-profilemenu
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
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
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
(+ --left), composed from the shared .nx-panel__head / __body / __foot.
React: NxDrawer.
NxModal — .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
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
okgets a note (.nx-command__note, warning tone forfailed/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 byChevronRight(.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-motionremoves the transitions. - Recent searches are kept per workspace in this browser only (
localStoragenx-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
1px hairline rule for separating stacked content within a panel.
React: NxDivider.
NxAvatar — .nx-avatar
Circular accent-filled initials badge. React: NxAvatar.
Agent faces — NxAgentFace, NxAgentLauncher, agentFace()
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. 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)andagentFaceSvg(name, seed, { shape, size, label })live in the platform-neutral entry@marcobeyer/nx-family/agent-face(no React, safe in route handlers).agentFaceSvgreturns a standalone SVG document; onlylabelis 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 unlesslabelis 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,labelas the accessible name andaria-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
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). Theme control: NxThemeToggle
(flips data-theme on <html>).
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
datavizskill for the ramps).
The showcase renders bar (single series), line + area (two series), a donut, and stat tiles against these tokens.
IA & actions
How a screen is put together, so every NX product feels like one family:
- One primary action per view, in the
NxPageHeader— the thing this page exists for. Everything else is secondary (≤ 2) or in a menu. - 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. - 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. - Every empty state names the next action (
NxEmptyState,actionrequired). - Speak the user’s words, not the data model’s: “Beitrag schreiben”, not “Maßnahme anlegen”.
- 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
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/ArrowLeftfor directional actions,ChevronRight/ChevronDownfor navigation or disclosure, andExternalLinkfor 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
currentColorand 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
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
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
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).
- 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 arole="tab"widget;NxTabs/NxSegmentedremain for switching views inside one page. - 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.
- 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.
- 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.
- 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 bestickyjust 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. - 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 (theNxAppShellnav look). Keyboard focus shows the kit’s focus outline. - Mobile: below
lgthe 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. - Breadcrumb + page title. Every page has one
h1title on the content gutter (NxPageHeader, or the shadcnBreadcrumb+ 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.5pxink 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-inkon 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 isaria-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/subfor 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 tightinside text (lockups); square elsewhere. - Keep the mark’s
nneutral and let only thexcarry 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)
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, NxSourceCoverage,
NxMoveNotice and NxSecretReveal 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 (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: 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); it points to the reading direction when closed (mirrored in RTL)
and down when open. CSS only, no API change. 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. Additive only — no breaking change.
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-densityattribute + 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, andforced-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:
NxTabsmarkup changed<span>→<button role="tab">. Any consumer CSS/markup keyed on.nx-tabs spanmust move to the class/role selector. Roving tabindex means the tablist is now one tab stop (was N stops).aria-controlsis now opt-in via a newpanelsprop (default off) — passpanelsand render matchingrole="tabpanel"elements. Id contract: tab${idBase}-${i}↔ panel${idBase}-panel-${i}.- 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-rootto offset the whole band. .nx-drawer--leftnow means inline-start (auto-flips under RTL). The API name is unchanged; the semantic is no longer “always screen-left.”- Contrast nudges are deferred (Task 10, partner-gated). The AA
color-contrastfixes 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 reportscolor-contrastviolations for these by design; don’t file them as DS-1 regressions.
Notes:
NxAlertlive-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-hships 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)
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) — HeroUIvariant="bordered"(dominant labeled-secondary-button variant in DocLinq, 24 call sites) andvariant="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-inktext,--nx-hairlineborder,--nx-state-hover/-activeoverlay) — 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’sCardHeaderalways wrapsCardTitle(+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 Buttonsizeother than"sm"(already covered by the existing.nx-btn--sm)..nx-btn--success/--warning— DocLinq’s only Buttoncolorvalues 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 needdisplay:inline-flex/gap/justify-content— properties.nx-btndoesn’t set today. Cross-repo precedent (PointNX’sHero.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-btnrule — so DocLinq’s re-skinned Button wrapper should add its owninline-flex items-center justify-center gap-*base classes, not kit.css. - One-off shape overrides reached via
classNamerather than a component prop — the nav-user Avatar’srounded-lg(square, not circular) and a handful ofSkeletonshapes (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 loadskit.cssunlayered (apps/main/src/app/[locale]/layout.tsximports 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 annx-*class that already sets that same property will silently lose. The reliable override for a one-off is an inlinestyle={{ 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-selectrenderValueis plain comma-joined text (neither call site supplies a customrenderValue), so the existing single-line.nx-selectstyling already covers it visually; the multi-select behavior itself is areact.tsx/ ARIA-listbox concern, out of scope for this CSS-only pass.
0.8.0 — coproNX (2026-09-05)
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)
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): 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 (
#334155on#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-50is the “current/selected” fill and--nx-surface-2is the neutral hover; at the same valueNxAppSwitcher’s current tile is indistinguishable from a hovered one.#E2E7EFkeeps--nx-slate-500body 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)
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)
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). 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 aslabels, 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.srcis 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 realloading|ready|errorladder off its own load/error events. The PDF<iframe>gets none — it fires no usable error event for content-level failures,onloadfires for error documents too, and a browser-rendered PDF has no meaningfulcontentDocumentto probe; any detection would be a heuristic that lies in both directions. So the download link is rendered beneath the frame wheneverdownloadHrefis given: worst case is an empty frame above a link that works. OmittingdownloadHref(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 bysrcand reset during render, never from an effect: ablob:or cached image can fireloadbefore React flushes passive effects, so an effect-based reset would overwritereadywithloadingand strand a perfectly good image atopacity:.45forever. - No
sandboxon the frame — Firefox’s pdf.js requiresallow-scripts allow-same-originto render, which grants back what a same-origin frame already has. The real control is the host app’s upload MIME allow-list plusX-Content-Type-Options: nosniffon 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 theNxModal/NxDrawerclose ”×”. A<button>with notypeis 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. (NxThemeTogglegot the same treatment for the same latent reason.) Purely additive — no consumer relied on the overlay chrome submitting anything.useFocusTrapmakes Escape terminal (e.stopPropagation()beforeonEscape). 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-indexed
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:
- Share fonts, semantic tokens, app purposes, names and appearance controls; verify real desktop/mobile screens and preference handoff.
- 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.
- 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.
- 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)
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) —variantisuser(the customer or the person chatting; right-aligned, accent fill),agent(an AI agent; white with hairline) orstaff(a human teammate; accent-50 tint, so a customer-facing human reply is never mistaken for the agent).agentandstafftake anavatarslot (32px, decorative — theauthorline carries the name; pair with the agent face from SkyONEx).metais a host-localized time,dateTimemakes it a<time>.footerholds citations or actions. Wrap bubbles in.nx-chat-thread.NxSourceChip(.nx-source-chip) — numbered citation:indexmatches the superscript in the answer,labelis the source name,detailthe location (“Zeile 12”). A link only withhref; passlinkComponentfor locale-aware routing.NxInboxList/NxInboxRow(.nx-inbox,.nx-inbox-row) — one row per conversation.statusisopen(agent answers),handoff(a human is needed or answering) orclosed;statusLabelis the host’s localized word (Offen / Übergeben / Erledigt).assigneenames who took it over;unreadadds a dot plus bold title and needsunreadLabelfor screen readers.actions(delete) sit outside the row link, never inside it.- Nav badge —
NxAppShellNavItem.badgeshows a count after the label (.nx-shell__navlink-badge);0,nullandfalserender nothing. GivebadgeLabel(“2 waiting”) so screen readers hear words instead of a bare number.