Skip to content

Design spec

View as Markdown

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

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

1. Foundations

1.1 Color — neutrals (shared by every product)

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 use 112 on the 512 canvas (≈ 22%).
  • Padding rhythm: card body 18px · header 16px 18px · KPI 14px 16px · input 9px 12px · button 9px 15px. Vertical stack gap inside a card body is 14px; tab gap 18px.

1.5 Motion

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

Token Value Use
--nx-ease cubic-bezier(.22,.68,.16,1) All kit transitions + the mark draw-on
  • Mark draw-on (.nx-mark.is-playing): the n strokes in over 0.6s, then the accent x follows (0.5s delay). Triggered when the mark scrolls into view.
  • Reduced motion: @media (prefers-reduced-motion: reduce) disables all mark animation and shows the final state. Honor this everywhere.

1.6 Elevation & borders

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:

  1. Channel vars (--nx-*-rgb, e.g. --nx-accent-600-rgb: 37 99 235) — the source of truth. Space-separated RGB so they work with / <alpha>.
  2. rgb() aliases (--nx-accent-600, --nx-accent, …) — convenience, derived from the channels. Declared on both :root and every [data-nx-product] so each themed subtree recomputes its aliases from its own channels.
<!-- 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: dark applies automatically unless data-theme="light" is set. NxThemeToggle flips the attribute.
  • How it works: the dark block overrides the neutral channel vars on :root; because the rgb() aliases derive from those channels, every component recolours with no per-component dark CSS. The mark’s n flips to light for free (it reads --nx-ink).
  • Accent tints are derived, not hand-picked: in dark, --nx-accent-50/100 become a color-mix() of the product accent into the dark surface, and --nx-accent-700 (text-on-tint) becomes a lightened accent — so every product, including any future one, dark-themes with zero extra values. --nx-accent (signature 600) stays vivid; --nx-on-accent stays white.
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 380
x: M424 156 L244 380
viewBox 0 0 512 512 · stroke-width 60 · round caps + joins
  • n = family constant, painted in --nx-mark-stroke (default --nx-ink, flips to paper on dark).
  • x = per-product accent (--nx-accent). The parent nx variant paints the x with a blue→violet→teal spectrum gradient.
  • Differentiation is accent + wordmark only — there is no per-product glyph.

3.1 NxMark (React) — props

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

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

3.2 Standalone SVG assets

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

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

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

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

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


4. The lockup

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

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

4.1 FileNX — the former lockup exception (resolved)

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-100 glow (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.

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

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

Primitives

NxDivider — .nx-divider

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

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

Icon button — .nx-iconbtn

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 dataviz skill for the ramps).

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


IA & actions

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

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

Icons instead of text arrows

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

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

Guided AI assistance

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).

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

6. Accessibility

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

7. Do / Don’t

Do

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

Don’t

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

8. certNX is standalone

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

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

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


9. Where things live

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

0.16.0 — hostNX (2026-11-17)

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-density attribute + density-scoped role tokens (compact/comfortable).
  • Primitives: .nx-empty, .nx-spinner, .nx-sr-only.
  • A11y behaviors: useFocusTrap, useBodyScrollLock, roving-tabindex menu/tabs, live-region alerts, a hoverable + dismissible tooltip, and forced-colors + reduced-motion coverage.
  • RTL: logical-property sweep across the kit.
  • Showcase: a dev-only axe self-audit (see breaking change 4 for known, by-design findings).

Breaking changes (adopt-time)

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

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

Notes:

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

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

P0.5 — DocLinq re-skin primitive gap-fill (2026-07-14)

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

Added:

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

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

Audited, found NOT needed despite being called “likely missing” in the task brief (i.e. the brief’s a-priori guess didn’t survive contact with real usage — flagging so the next audit doesn’t re-add these speculatively):

  • .nx-btn--md/--lg — DocLinq never passes an explicit Button size other than "sm" (already covered by the existing .nx-btn--sm).
  • .nx-btn--success/--warning — DocLinq’s only Button color values are "primary" and "danger" (and the untinted default), both already covered.
  • Avatar size modifiers — DocLinq’s one real Avatar usage renders at exactly 32px (h-8 w-8), i.e. the existing default .nx-avatar (--nx-avatar-md). No second size is used, so none was added.

Considered, deliberately deferred (not a kit.css concern):

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

0.8.0 — coproNX (2026-09-05)

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

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

0.6.0 — SkyONEx + account/upload patterns (2026-08-14)

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

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

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

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

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

Known limitation (not a kit change): NxModal does not portal. Mounted inside an element that creates a stacking context — e.g. a z-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:

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

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

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

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

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

Workspace identity and navigation help

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

Mobile identity and appearance placement

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

suiteNX display name (2026-10-19)

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

Conversation primitives (2026-11-16)

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

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