Headless

20 channels · 15 utilities · 2 variants

Three things a consumer meets before it meets a component: how its own props merge with ours, how to take the library with no Tailwind pipeline at all, and which classes a later migration must not flatten. Everything below is measured in this browser or read off the real build artifact — one claim is transcribed, and says so.

Pass-through (pt)

One prop on the root, seven slots, four rules. The contract is decided once in modules/nk-lib/src/ui/pt.ts — so no component re-litigates it — and a consumer types its object with Pt or NkDialogPt. mergePt itself is deliberately not exported: only components merge.

NkDialog pt

0/11 on

Switch overrides on, then open the dialog. Every figure under Measured off the live dialog is read from the rendered element — this page claims nothing it has not measured in your browser.

className — appended through tailwind-mergedecision #1
other keys — replaced outrightdecision #2
protected keys — dropped silentlydecision #3
What the consumer wrote
tsx
<NkDialog open={open} onOpenChange={setOpen}>
{/* no overrides enabled — switch one on above */}
</NkDialog>
Measured off the live dialog

Nothing measured yet. Open the dialog once and the readings fill in; the first open with no overrides enabled is kept as the baseline that unchanged is measured against.

NkDialogSlot

7 slots

Which element each slot actually addresses — not transcribed, but read from the DOM after data-pt-slot was delivered through pt itself. Two of these rows, heading and footer, are rendered by sibling components; they are reached anyway, which is the whole argument for declaring pt on the root instead of on seven parts.

Open the dialog above to populate the map. Each row is a query for [data-pt-slot="…"] — a slot that reached no element would say so in place of a tag name.

ALWAYS_PROTECTED

class, every slot

The two slots are not equally good evidence, and the difference is worth knowing. viewport is a plain <div> that the merged object is spread onto directly, so ALWAYS_PROTECTED is the only thing between that key and the DOM. panel is react-aria's Modal, which runs its props through filterDOMProps; that filter passes data-* and drops unknown names, so it would have stopped class as well. The panel row is true and over-determined — the viewport row is the one that isolates the guard.

Correct
Enabling viewport: { class: 'hidden' } or panel: { class: 'bg-destructive' } changes nothing: both class attributes read unchanged against the baseline, and the panel keeps its measured background.
Regressed
Without the entry, React 19 maps class straight to setAttribute('class', …), which replaces the merged string outright — the component's entire base class list is gone, with a dev-only “Invalid DOM property” warning as the only signal.

PROTECTED.overlay

WCAG 2.1.2

Two neighbours stay reachable on purpose. isDismissable is not protected — it governs POINTER dismissal only, and NkAlertDialog sets it false deliberately. Switch it on above, click the scrim, and the dialog stays open while Escape still closes it. close.disabled is reachable by design too: with Escape guaranteed, disabling the close button mid-flight (a save that must not be abandoned halfway) is a legitimate need rather than a trap.

The match is case-insensitive, which is the half an exact guard gets wrong. Enable panel: { ROLE: 'none' } and panel: { 'data-Probe': 'landed' } together: panel role attr stays (absent) while panel data-probe reads landed. One merge, a mis-cased protected name blocked and an unprotected one through. React logs one dev-only warning for the second — “React does not recognize the data-Probeprop” — which is React itself confirming the key reached the element and was lowercased on the way in. Expected, and only while that chip is on.

Correct
With overlay: { isKeyboardDismissDisabled: true } enabled, open the dialog and press Esc. It closes, and Last close reads Escape (keyboard). Escape is the guaranteed exit from every modal the library ships, and no styling API can take it away.
Regressed
Unprotected, that single key produces a focus-trapped dialog with no keyboard exit at all — a WCAG 2.1.2 keyboard trap, reachable through a prop whose documented purpose is styling.

mergePt

Decision #4 · transcribed

The one rule here that cannot be proven from outside the library: mergePt always returns a fresh object, on the merged path and the no-op path alike, so a component merging several slots out of one own literal never gets the same object back twice. The function is not exported, so there is nothing a consumer can measure — transcribed from modules/nk-lib/src/ui/pt.ts:136-147, and therefore able to drift.

The same file states the limit of everything above, and it is the line to remember: protection cannot reach styling. A consumer who wins the cascade fight has removed a base class's effect as surely as deleting it, so essential behaviour belongs in a typed prop — never in a class a slot can reach.

The compiled distribution

What “headless” actually means here. tokens.css and motion.css are SOURCE sheets built out of Tailwind v4 at-rules — a dead end for a consumer with no Tailwind, who would import a file of at-rules nothing in their pipeline understands and see unstyled components with no error anywhere. The build therefore emits a plain stylesheet, and a manifest of what the consumer must still supply for it to render.

@nkapp/lib/tokens.json

manifest

Derived at build time, never hand-written: the channels are read back out of the emitted CSS as unresolved, fallback-less var() reads inside the mapping layer. A hand-kept list would drift silently, and the failure it drifts into is invisible — an undeclared channel makes oklch(var(--x)) an invalid colour, the browser drops the declaration, and the surface renders transparent.

read fromnode_modules/@nkapp/lib/dist/tokens.json
symlink lands on/workspace/modules/nk-lib/dist/tokens.json
size757 B · 0.7 KiB
gzip263 B · 0.3 KiB

@nkapp/lib/nk-lib.css

stylesheet

Tailwind's base layer, every utility the library's own components use, every custom utility and the semantic token MAPPING. A consumer with no build step imports this one file and gets the library's styles; what is NOT baked in is the channel values, which is what keeps re-theming possible with nothing but the custom properties listed below — no build step, no bundler, no Tailwind.

read fromnode_modules/@nkapp/lib/dist/nk-lib.css
symlink lands on/workspace/modules/nk-lib/dist/nk-lib.css
size176,570 B · 172.4 KiB
gzip21,693 B · 21.2 KiB

channels

20 demanded

The two-part token model, audited. @nkapp/lib ships the mapping (--color-card: oklch(var(--card))); the app supplies the channel triplet. These are the properties the artifact says this app must declare, checked against what this document declares right now.

Reading this document's stylesheet…

utilities

15 promised

Every row paints a real specimen with the class beside an identical control that does not carry it, and diffs the two computed styles. A utility the manifest promises and the stylesheet does not emit would change nothing — and build-css.mjs safelists every one of them for that reason, since Tailwind otherwise emits an @utility only where some scanned file happens to use it.

utilitymeasured difference
nk-elevate-1measuring…
nk-elevate-2measuring…
nk-factmeasuring…
nk-labelmeasuring…
z-basemeasuring…
z-blockingthis page has no literal class for it — the bench is behind the library
z-drawermeasuring…
z-headermeasuring…
z-popovermeasuring…
z-raisedmeasuring…
z-scrimmeasuring…
z-shellthis page has no literal class for it — the bench is behind the library
z-stickymeasuring…
z-toastmeasuring…
z-tooltipmeasuring…

The two specimens differ visibly only where the utility is typographic or carries a surface. The z-* ladder paints nothing at all, and its whole evidence is the z-index value in the third column — which is why this is measured rather than eyeballed. Counted off the readings above, 0/15 of them change nothing a reader could see.

variants

2 registered

A @custom-variant is not a property with a value — it is a selector transform, so the evidence that it registered is that rules selecting its attribute exist in the compiled document. These two are what every overlay in the library animates with, the dialog above included.

variantrules in this document
entering:counting…
exiting:counting…

Structural indicators

The record a Panda migration must not flatten: declarations that look like colour and are the affordance, kept as a public export rather than as prose, because the next pass over this styling will be automatic and an automatic pass cannot tell them apart.

STRUCTURAL_INDICATORS

15 entries

These are the classes a tidy-up deletes and an accessibility audit then fails on — a removed focus ring whose replacement indicator IS the focus:border-primary/30 pair, a checkbox whose only checked affordance is a background colour, a thumb whose travel IS the on/off signal.

file:linematchwhy removing it is a regression
ui/NkSearchFilter.tsx:71focus:border-primary/30outline-none removes the native focus ring; focus:border-primary/30 + focus:bg-card/90 ARE the replacement indicator, and they are COLOUR ONLY — a consumer re-skinning this field to their own palette removes the only way to see where the keyboard is. It cannot be made expressible without adding a ring to a shipped control, which is a visual change to every call site and belongs in its own deliberate pass; it cannot be protected (see the header). So it is recorded.
ui/NkCheckbox.tsx:61group-data-[selected]:bg-primarygroup-data-[selected]:bg-primary/border-primary is the only checked affordance the BOX itself has; without it the box renders invisible (`:52-57` records that shipping). Colour only — the glyph's scale is the expressible half, recorded separately below.
ui/NkCheckbox.tsx:70selected && 'scale-100'the check glyph's presence is a `scale` transform, not a mount/unmount, so the checked state survives any colour re-skin: a consumer who repaints the box cannot remove the glyph appearing. This is what makes the colour entry above a degradation rather than a total loss.
ui/NkCheckbox.tsx:71!selected && 'scale-0'the other half of the same transform. Recorded separately because the two are on separate lines and a refactor that keeps one and drops the other leaves a glyph that is always visible.
ui/NkSwitch.tsx:56group-data-[selected]:bg-primarygroup-data-[selected]:bg-primary is one of only two on/off signals, and the colour one; `:50-54` records that the previous `not-selected:` spelling never matched and the off-track rendered fully transparent. The travel below is the half that survives a re-skin.
ui/NkSwitch.tsx:66translate-x-0 group-data-[selected]:translate-x-5translate-x-0 → translate-x-5 IS the thumb travel, i.e. the affordance itself, and a transform is not reachable by a colour override — so the on/off state remains perceivable in any palette. Under reduced motion the travel collapses to 1ms rather than disappearing (`motion.css`), so the END POSITION still differs; the indicator is the position, not the movement.
ui/NkOtpInput.tsx:728text-transparent caret-transparenttext-transparent/caret-transparent keep the real input focusable while invisible; display:none breaks autofill and screen readers (the comment states the alternative explicitly). This is a CONCEALMENT rather than an indicator, so there is no second carrier to fall back on: a consumer who restores a text colour here double-renders the code, once in the real input and once in the cells. Recorded as untouchable.
ui/NkTable.tsx:388focus-visible:ring-2a ring is a box-shadow: re-theming `ring-primary/60` changes the ring's COLOUR, never its existence, so the indicator survives any palette. `ring-inset` is load-bearing geometry rather than taste — the table clips, so an outset ring would be cut off. `NkTable.tsx:51` records the defect this replaced: a `<tr>` carrying a focus-visible class but no tabIndex, i.e. a ring nothing could reach.
ui/NkTable.tsx:473data-[focus-visible]:ring-2the same ring on the ROW, which is the element a keyboard user actually lands on. Recorded as its own site because the three are three separate class strings and a refactor can drop one of them.
ui/NkTable.tsx:516data-[focus-visible]:ring-2the same ring on the CELL, reached by cell-navigation mode. Recorded separately for the same reason as the row: three class strings, three ways to lose it.
ui/NkDataTable.tsx:396focus-visible:ring-2the drag-reorder header's focus ring, inset for the same clipping reason as NkTable's. Reachable only when `reorderable`, which is why it is written as a conditional rather than a base class.
ui/NkCloseButton.tsx:97focus-visible:ring-2 focus-visible:ring-ringa box-shadow, so the indicator survives a re-skin. The absence of a ring OFFSET is the part worth recording: `:56-58` explains the offset would be clipped by the overlay edge, so "adding the missing offset" is a plausible-looking change that silently removes the indicator on exactly the surface this button exists for.
ui/NkDropdownMenu.tsx:124data-[focused]:bg-primary/10the menu item's ONLY focus indicator, and it is colour only (`outline-none` is on the line above). It satisfies WCAG 2.4.7 today — something visible does change — but a consumer who re-skins `bg-primary/10` to their own hover colour can flatten focused and unfocused into the same pixels. Same class of site as NkSearchFilter:71, same verdict, and found only because this record was re-derived from the source rather than copied from the inventory.
ui/NkNumberPicker.tsx:155focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-insetWAS a 2.4.7 failure: `focus:outline-none` stood alone and the field had no focus indicator at all (measured in a browser: `outline: none`, `box-shadow: none` on a focused input). The ring added in this pass is inset, because the enclosing Group is `overflow-hidden` and clips an outset one — the same geometry NkCloseButton records.
ui/NkLogin.tsx:154focus-visible:ring-2 focus-visible:ring-ringWAS a 2.4.7 failure: `outline-none` on a text button whose only affordance was `hover:underline`, which a keyboard user never triggers. The ring added in this pass carries an offset (nothing clips here) and `focus-visible:underline` beside it, so the indicator is not a ring alone under forced colours.
ui/NkSwitch.tsx:56 · ui/NkSwitch.tsx:66
ui/NkCheckbox.tsx:61 · ui/NkCheckbox.tsx:70 · ui/NkCheckbox.tsx:71

The switch does signal twice — the thumb travels AND the track turns primary — which is why its entry says “one of only two”. The checkbox does not: its tick is text-primary-foreground, a near-white, so deleting the fill as “colour” leaves a white tick on a transparent box. The state is still announced; it is simply no longer visible.

The record is data, not behaviour, and it is deliberately not a lint rule: an automatic pass cannot tell focus:border-primary/30 — the only focus indicator an input has once outline-none removed the native one — from a decorative border. That is a decision, and the list is what makes it an explicit one.