Motion

The motion layer ships in nk-lib as @nkapp/lib/motion.css: two react-aria lifecycle variants, a duration and easing scale, travel and scale floors, loop periods, nine named keyframes, and a reduced-motion policy. Every value on this page is read back from the live stylesheet, so it cannot go stale — including under reduced motion, where the duration scale collapses to 1ms and the loop periods deliberately do not.

Durations

Five steps for arriving, three for leaving. First as one shape you can read at a glance, then as a race so the order is felt rather than looked up.

The scale, to scale

8 steps

Bar length is the token's real duration against the longest step in the system. Nothing here animates — this is the shape of the scale, so the differences are legible before you replay anything.

--nk-duration-instant—
--nk-duration-fast—
--nk-duration-normal—
--nk-duration-slow—
--nk-duration-slower—
--nk-duration-exit-fast—
--nk-duration-exit-normal—
--nk-duration-exit-slow—
EnterExitRead from the stylesheet, printed in ms — the CSS minifier rewrites some of these to seconds, and a mixed-unit column cannot be compared.

Enter scale

5 steps

Five steps, released together. The ordinal marks the order they finish in — that order is the whole point of having a scale.

--nk-duration-instant—

Under the threshold where a change reads as a transition at all. Press feedback.

--nk-duration-fast—

A colour or border swap. The default for hover states.

--nk-duration-normal—

Something arriving: a menu, a popover, a panel.

--nk-duration-slow—

Something arriving that also travels or changes size.

--nk-duration-slower—

The longest step in the system. Past this it stops being motion and becomes waiting.

Exit scale

Paired with enter

An exit is deliberately faster than its matching enter. A dismissal should feel like it already happened; an entrance should feel placed. The muted bar is the enter it is paired with.

--nk-duration-exit-fast—
--nk-duration-fast—
--nk-duration-exit-normal—
--nk-duration-normal—
--nk-duration-exit-slow—
--nk-duration-slow—

Easing

Four curves, one duration. What changes between these rows is only the shape.

Easing curves

4 curves

Every bar below runs for exactly --nk-duration-slower, so the only thing that differs is the shape of the curve. The plot to the left of each row is drawn from the live value of that token, not from a copy of it.

--ease-enter

—

Leaves fast, lands soft. Everything that arrives on screen.

--ease-exit

—

Starts soft, accelerates away. Everything that leaves.

--ease-standard

—

The neutral curve. Colour, opacity, size changes in place.

--ease-emphasis

—

A longer settle. For the one element the eye should follow.

Travel and scale

How far something is allowed to move, and how small it is allowed to start.

Travel

≤ 8px

Every travel token is 8px or under. At this scale motion reads as the interface settling, not as things flying in from off-screen. The chips below rise from exactly their token's offset.

--nk-lift—

Hover and press nudge.

--nk-rise—

Popovers, menus, toasts.

--nk-shift—

Drawers and panel slides.

Scale floors

2 tokens

A dialog that scales from 0.97 reads as arriving. One that scales from 0.8 reads as a cartoon. The third square is not a token — it is what the floor exists to prevent.

--nk-scale-in—
--nk-scale-out—
not a token0.8

Periods

A fourth quantity, new to the scale: the cadence of an infinite loop. It is not a duration, it does not collapse like one, and the reason it does not is the most consequential decision in the motion layer.

Periods

3 tokens

A duration is how long a one-shot transition takes. A period is how long one cycle of an infinite loop takes. NkLoadingSpinner recorded the gap in a comment and then hard-coded 1.5spast it; these three are that comment turned into tokens, so the cadence of “the system is working” is one decision rather than nine.

--nk-period-pulse— · —

A beat you read as a heartbeat: dots, a caret, a halo.

--nk-period-sweep— · —

Something traversing the element once — a skeleton highlight, a radar hand. Slower, because the eye has to follow it across a distance.

--nk-period-wave— · —

One full excursion of a waveform bar. Between the two: many staggered bars read as sludge when slow and as jitter when fast.

All three run right now, each on one of the periods above.

Not a duration

No preference

Under prefers-reduced-motion every duration token collapses to 1ms. --nk-period-* is deliberately absent from that list: collapsing a loop period would not stop the loop, it would run it a thousand times a second.

--nk-period-pulse—
--nk-period-sweep—
--nk-period-wave—
three flashes per second3.00 Hz
a 1ms period1000 Hz

The axis stops at 3.5 Hz. The collapsed row is 333× past the flash limit and 286× past the end of this chart, which is why it is drawn as a number and not as an animation: a 1000 Hz opacity loop is a photosensitivity hazard, and rendering one to prove the point would be the one experiment this decision forbids.

Amplitude tokens — these DO collapse
--nk-stagger-step
—
--nk-blur-in
—
--nk-wave-floor
—

Every loop in the pass separates amplitude from luminance. The amplitude half is a token, so the reduced-motion block collapses it and the loop keeps its cadence on opacity alone — a loader that breathes while nothing moves.

Overlays

The transitions the variant registration brought to life. Stretch the playback, then open — or replay — each one; the exit is the half that used to be missing.

Playback

Overlay transitions run in the 120–240ms band by design: right for daily use, too fast to study. Stretch them, then open and close something and watch both halves.

NkDialog

enter + exit

Overlay and panel both animate. The panel adds zoom-in-95 on the way in and zoom-out-95 on the way out. Replay closes it and reopens it once the exit has finished.

NkModal

enter + exit

Same transition as NkDialog, prop-driven API instead of a compound one.

NkAlertDialog

enter + exit

role=alertdialog: the backdrop does not dismiss it, so the exit only plays from Cancel or Confirm.

NkDropdownMenu

token-driven

Renders through NkPopover, so its enter is --nk-duration-normal on --ease-enter and its exit is --nk-duration-exit-fast on --ease-exit. Escape closes it and still plays the exit.

NkSelect

token-driven

The listbox popover is the same NkPopover surface, so it inherits the same token pair. NkComboBox and NkMultiSelect share it too — see the Inputs page.

NkDrawer · NkBottomSheet

enter + exit

Both were hand-rolled portals that returned null while closed, so neither had an exit frame to animate. Both now mount through react-aria's ModalOverlay and play a real exit.

The sheet is token-driven (--nk-duration-slow in, --nk-duration-exit-slow out). The drawer still carries literal duration-300, and one more difference — see the tripwire below.

NkTooltip

No motion at all
Turn playback up first — nothing changes.
Correct
A tooltip should fade in and out like every other floating surface — it is the one overlay a pointer produces dozens of times a minute.
Regressed
NkTooltipContent declares no entering: or exiting: classes in either direction, so it appears and vanishes with no transition however far you stretch playback. It also still carries a raw z-50 instead of z-tooltip.

motion-reduce:animate-none

2 policies

Reproduce it: enable reduced motion in your OS, then open the drawer and the sheet from the specimen above. The sheet still fades; the drawer appears instantly.

Correct
Under reduce, an overlay keeps its ~100ms linear cross-fade. motion.css zeroes the travel and scale custom properties and caps the duration, which leaves exactly the opacity half of the keyframe. NkBottomSheet does this, and has a test asserting it never adds motion-reduce:animate-none.
Regressed
NkDrawer puts motion-reduce:animate-none on both its scrim and its panel. animate-none sets the animation shorthand to none, so there is no animation left for the duration cap to govern and the drawer pops instead of fading. Same library, same release, opposite answer.

Entrances

One component, one keyframe, six variants — and the property a mount animation has to have: if it never runs, the content is simply there.

NkEnter

6 variants · 1 keyframe

One component and one @keyframes nk-enter, parameterised by three custom properties. amicro ships seven files that differ in an x offset, a y offset and a starting scale; a variant union is the same call-site surface and makes the travel come from one place.

--nk-rise
—
--nk-shift
—
--nk-scale-in
—
variant="fade"

Sets no custom property at all — the keyframe fallbacks make it opacity-only.

variant="fade-up"

--nk-rise (6px). A thing settling into place.

variant="fade-down"

The same 6px, negated.

variant="slide-left"

--nk-shift (8px). Starts to the RIGHT and travels left — the name is the direction of travel.

variant="slide-right"

The same 8px, mirrored.

variant="scale"

--nk-scale-in (0.97). The same floor the dialogs use.

Staggered with delay, which rides on fill-mode: both. Without the backwards half of that, a delayed entrance shows the finished element for the length of the delay, snaps to opacity: 0 the instant the animation starts, and fades back — six blocks that flash in, blink out and arrive.

It fails open

Defeated

Both panels below have had their animation removed by an inline animation: none — the stand-in for every path where an entrance does not run: CSS blocked, a reset, a print stylesheet, an engine with no support, a crawler that applies CSS and runs no script. The opacity under each one is read off the painted element.

NkEnter · from-frame only

Three services will be rebuilt.

pg-fade-in · hidden by a class

Three services will be rebuilt.

Correct
@keyframes nk-enter declares only a from frame, so the implicit tois the element’s own style. The hiding lives inside the animation and nowhere else. NkEnter.test.tsx asserts this as a NEGATIVE test — no opacity-0, no invisible, no inline opacity, for all six variants.
The usual shape
A base class hides the element and an animation reveals it. Content that depends on an animation having run is content that can go missing — permanently, and silently. .pg-fade-in exists only in this app’s global.css so the defect can be rendered beside the fix; nothing in @nkapp/lib uses it.

Travel, two amplitudes

6 vs 40px

Identical duration, identical curve, identical component. The only difference is --nk-enter-y: the library’s --nk-riseon the left, amicro’s register on the right. The argument for ≤ 8px is not that the larger one looks bad in isolation — it is what a page of them does.

--nk-rise—
api-gateway
api-auth
api-runtime

the interface settling

40px40px
api-gateway
api-auth
api-runtime

things flying in from off-screen

Both amplitudes collapse to 0px under reduced motion — the right-hand one only because it is still an inline value on the same keyframe. A literal length written into a component would not.

Text

Four effects, and one decision that separates them: three never split the string, and the one that must split repairs every kind of damage it does. The last repair is the one you can check with your own hands.

NkTextShimmer · NkTextBlur

No split

A shimmer paints a gradient through the element’s own glyphs with background-clip: text; a blur is a property of the element. Neither touches the text node, so there is one copy in the DOM, one in the accessibility tree, one on the clipboard — and the line still wraps and hyphenates.

NkTextShimmer · a loop, on --nk-period-sweep
Reconciling services against the declared configuration
NkTextBlur · one shot, on --nk-duration-slower

Reconciling services against the declared configuration

--nk-period-sweep
—
--nk-blur-in
—

amicro renders the shimmer string TWICE and animates a mask over the top copy, and splits the blur into one element per character. Both duplicate or fragment the sentence for an effect that needs neither.

NkTextStagger

word · character

The one text effect that must split, and the only one that pays for it. The numbers under each line are the repair: textContent holds the sentence twice because of the hidden canonical copy, while the accessible text holds it once.

by="word" · the default

Reconciling services against the declared configuration

by="character" · ~7× the nodes

nkapp deploy -e production

--nk-stagger-step
—

The per-piece delay is calc(index * var(--nk-stagger-step)), so the rhythm is a token and the index is the only per-instance value — and the reduced-motion override of that token reaches every piece without the component knowing. Prefer the two effects on the left wherever either will do.

Select and copy

3 ways

All three lines below are the same sentence, split into pieces so each piece can animate. Select a line with the mouse — or click into it and use Shift+End — and the readout says exactly what your browser would put on the clipboard. Only one of the three gives you the sentence.

NkTextStagger · the library

Reconciling services against the declared configuration

Pieces are aria-hidden and select-none; the whole string is carried once in an sr-only sibling. A selection lands on that copy.

Anti-pattern · both halves selectable

Reconciling services against the declared configuration

The same markup with select-none removed. The hidden copy is still in the selection, so the clipboard gets the sentence twice.

Anti-pattern · separators replaced by a gap

Reconcilingservicesagainstthedeclaredconfiguration

The split drops the whitespace and a gap-xstands in for it. Typographic word spacing becomes a flex gap — immune to the type scale’s tracking — and each word becomes a flex item, so a copy comes back as a column of words rather than a sentence.

Your selection, right now

""

captured
0 chars
source
55 chars
verdict
nothing selected yet

Drag across one of the three lines above, or select it and press ⌘C / Ctrl+C.

Or verify the clipboard for real
pasted
0 chars
verdict
nothing selected yet

The readout on the left is the browser’s own serialisation of the selection, which is what a copy puts on the clipboard. This field is the end-to-end check, in case your platform disagrees.

NkTextTyping

No timer · no state

It animates a width in ch with steps() over overflow: hidden. The complete string is in the DOM from the first frame and is never touched — only how much of it is painted changes. The usual setInterval+slice holds a TRUNCATED string, so a crawler and a screen reader get half a sentence and a live region announces it one character at a time.

The whole string is there, all along
nkapp deploy -e production

textContent and the accessible text are the full command on the first frame and every frame after it. The two elements are the line and the caret.

Both constraints, deliberately
Resolving secrets from vault://nkapp/production and reconciling every declared service

One line. A width reveal cannot wrap — a second line would appear all at once — so whitespace-nowrap makes it explicit and max-w-full clips rather than pushing the page sideways. The clipped text is still complete in the DOM, so nothing is lost to assistive tech; visually it is, which is why this is for short strings.

Monospace. 1chis the advance width of “0”. Only in a monospaced face is every other glyph that width, and only then does each of the N steps land on a character boundary. The component applies font-mono itself.

NkTerminalLoader · the typewriter in a loader
nkapp plan -e production
No command · “a shell, waiting”

The honest rendering when the caller does not know what is running. An invented $ loading...is a fabricated claim about the system’s state.

background-clip: text

A recorded exception

specs/DESIGN.md §6 says: don’t use decorative gradients or background-clip: text gradient text as emphasis — emphasis comes from weight and Signal Blue. NkTextShimmer uses exactly that property, and the rule now carries the exception that says why that is allowed.

The distinction is emphasis versus mechanism, and the rule draws it itself now rather than leaving two documents to contradict each other. The ban’s own rationale is about emphasis; a loading shimmer is not emphasis — the travelling highlight is what says “working on it”, and there is nothing it is trying to make more important. The gradient runs between --color-muted-foreground and --color-foreground — two readable body colours, no hue, no brand — so the line is legible at every frame and nothing about it reads as decoration. The exception is written into the DESIGN.md§6 bullet and repeated in the component’s own header, so a reviewer finds the decision instead of an apparent breach. The rule was not weakened: decorative gradient text as emphasis is still banned.

One consequence of the technique is handled and worth knowing: in a forced-colours mode the user agent discards background images, which would leave transparent glyphs on a plain ground — an invisible line, not a plain one. forced-colors:text-foreground restores an opaque colour for exactly that case. The effect is lost; the sentence is not.

Loaders

Four new indicators, four different sentences. The accessible name is read off each rendered element, because that is the claim — not the figure.

Four sentences

Names from the DOM

Each row’s name column is read off the rendered element with aria-label, so it is the string that will be announced rather than one transcribed from the source. None of the four defaults to “Loading”.

  • NkTypingIndicator

    Something is composing a reply.

    Not “a request is in flight”. Three bobbing dots belong to a conversation, and Nanokit is an agent-native control plane where the operator is increasingly an agent. A spinner in a transcript says the UI is waiting; this says the agent is thinking.

  • NkTerminalLoader
    nkapp plan -e production

    This command is running.

    The only loader here that shows WHAT is running, which is why it takes a command. Nanokit is a command line; the Hub is a view onto what those commands did. Its default name is Running <command>, so the announcement carries the same information the pixels do.

  • NkRadarSweep

    Still looking. Nothing yet.

    A scan over a space, not a request in flight — the bridge re-running discoverProjects on a timer, infra resources querying provider APIs, teardown sweeping regions by tag, doctor walking an asset graph. The library had no way to say it.

  • NkWaveform

    A live stream, with a level to it.

    The only shape in the set that encodes INTENSITY rather than elapsed time. A spinner turns at the same rate whether a deploy is streaming 40 MiB of layers or sitting on a DNS timeout. Deliberately not wired to real amplitude data — a waveform driven by fake values is a chart that lies; NkSparkline is the component for data.

role=progressbar

not role=status

Both are defensible in isolation; only one is defensible in a library that already has a loader. NkLoadingSpinner has been a react-aria ProgressBar in indeterminate mode since its accessibility pass, with roughly 80 call sites across the apps.

Two loader vocabularies would mean a consumer writing getByRole('progressbar')for one of this library’s loaders and getByRole('status') for the next one, with nothing to tell them which is which.

The ARIA argument points the same way. role="status" is a LIVE REGION — it announces when its contents CHANGE. These loaders mount with their content already final and never change it, which is the documented case where a live region may announce nothing at all. role="progressbar" is a widget role with a name: it is read whenever the user reaches it, and it says what the element is.

A caller who wants a live region gets one by passing it — every loader spreads its rest props LAST over these attributes, so <NkWaveform role="status" /> is honoured. That is the escape hatch, and the asymmetry with pt’s protected keys is deliberate: nothing here is load-bearing enough to protect, and a consumer who names a role meant it.

role passed through as a rest prop

NkLoadingSpinner

5 variants

auto is the LEGACY rendering, named: sm and lg draw a spinning icon and md— the default size — draws no indicator at all. That asymmetry is pinned by the component’s own test file as deliberate, so auto reproduces it exactly and adding this prop changes nothing at eighty call sites until one asks it to.

size="sm"
size="md"
size="lg"

Switch to auto and read the middle column: direct children is 0. Any explicit variant draws at every size, which is the way out of the asymmetry for a call site that wants one — rather than a default change that silently restyles eighty places. label is here because sm renders no message, so it used to be nameable only by passing a message that was then not displayed.

NkSkeleton

The sharpest fix
variant · 4 shapes

card is the addition — the same block with panel chrome, for a placeholder standing in for a whole surface. The three original names are kept verbatim because 35 call sites spell them.

lines={3} · the last bar is short

Every multi-line text placeholder in the apps is hand-rolled as a stack of per-bar widths. lines is that, plus the detail nobody re-derives: the last line is short, so the block reads as text that ran out mid-line rather than as a barcode. Each bar sweeps one --nk-stagger-step behind the one above it, so the paragraph reads as one wave passing down it.

aria · hidden unless named

A skeleton is a picture of content that does not exist yet. Exposed, a loading table announces as a dozen empty groups, so it is aria-hidden by default and ONE labelled skeleton carries the region. The component previously had no ARIA at all, so the boxes were exposed as unlabelled generics.

Correct
A placeholder has to report that content is ARRIVING, and it has to do so for the user who most needs the interface legible. It now sweeps — left to right, reading direction, which is what makes it read as content filling in rather than as something sliding over it — and the sweep carries data-nk-sweep, so under reduced motion motion.css swaps the animation NAME to nk-breathe and the block pulses in place at the same period.
Regressed
It was 32 lines of animate-pulse bg-muted/40, and motion.css’s reduced-motion block force-stops .animate-pulse. So for a reduced-motion user every skeleton in every app was a STATIC GREY RECTANGLE — visually indistinguishable from a broken layout or a failed fetch. The one class of user who most needs the interface to report its state got the version that reported nothing, at roughly 35 call sites.

NkWaveform · bars

Odd is correct

A symmetric wave propagates from a centre bar, and an even count has no centre — the excursion then starts in the two middle bars at once, which reads as a seam down the middle rather than as a source. An even value is accepted rather than rejected (it is a cosmetic choice, not a correctness one) and degrades to that double-centre form.

size="sm"
size="md"
size="lg"

The per-bar delay is the bar’s distance from the centre, in --nk-stagger-step. amicro ships three files for this loader whose only difference is that formula — one of them computes Math.sin of an INDEX, so three of its seven offsets are negative and the animation starts part-way through on an unsorted sequence. It looks like a formula rather than a wave.

Reduced motion

What collapses when the operator asks for less movement, and what deliberately does not.

prefers-reduced-motion

No preference

This is an operating-system setting; the page cannot toggle it. Change it in your OS accessibility settings and this panel updates without a reload — the numbers below are read from the live stylesheet, not written here.

--nk-duration-normal
—
--nk-duration-exit-normal
—
--nk-lift
—
--nk-scale-in
—
--ease-enter
—
Collapses
  • Every duration token to 1ms.
  • Travel to 0px, scale floors to 1, easings to linear.
  • All transitions and animation delays to 1ms / 0ms.
  • animate-pulse, animate-ping, animate-bounce and anything whose class or style names shimmer stop outright.
  • The amplitude half of every loop — --nk-blur-in to 0px, --nk-stagger-step to 0ms, --nk-wave-floor to 1.
Survives
  • Overlays keep a ~100ms linear cross-fade. Content that pops into existence with no transition is its own kind of disorienting — the rule removes travel and spin, not continuity.
  • animate-spinis deliberately not killed. A spinner says “still working”: that is state, not decoration, and removing it costs information.
  • --nk-period-*, at any setting. A loop period collapsed to 1ms would run a thousand cycles a second — see Periods above.
  • Every loop carrying data-nk-sweep: rule 4 swaps its animation NAME to nk-breathe rather than stopping it, so the traverse becomes a breath at the same cadence.

State vs decoration

Live

Everything here moves right now. With reduce enabled some of it still does — that is the whole rule, rendered rather than described.

NkLoadingSpinner · both at once

Reconciling services

One component, three different answers. The ring keeps turning — animate-spinis exempted, because “still working” is state and removing it costs information. The label’s animate-pulse stops dead. The rail under it used to stop too — it was caught by the [style*='shimmer'] rule — and now carries data-nk-sweep, so it breathes instead of stopping.

NkSkeleton · a sweep, not a pulse

It used animate-pulse, which this rule force-stops — so a reduced-motion user got a static grey rectangle at every one of its ~35 call sites. It now sweeps and carries data-nk-sweep, so under reduce the highlight stops travelling and the block breathes at the same period. See the tripwire under Loaders.

Amplitude vs cadence

Rig off

Switch the rig on and compare the two columns. Nothing on the right MOVES — the dots stop bobbing, the radar hand parks, the bars stand at full height, the skeleton highlight stops travelling — and everything on the right is still running, at exactly the same cadence, carried by opacity alone. That is the least obvious decision in the pass, and it is one switch away rather than one paragraph away.

Simulated reduce

.pg-reduceis a bench rig, not a library feature. It redeclares the same amplitude tokens on a subtree and repeats the real block’s rules 1, 3, 4 and 5 verbatim — apps/playground/src/app/global.css.

As declared
nkapp up

Reconciling services

Rig off — identical to the left
nkapp up

Reconciling services

The two columns, measured — not the pixels, the properties the browser resolved
propertyleft columnright column

Switch the rig on and read the last two sweep rows together. The animation name changes — the traverse is swapped for a breath, which is rule 4 — and the animation duration does not change at all, because a period is not a duration and nothing in the policy collapses one. That one pair of rows is the least obvious decision in the whole pass, and it is the difference between a loader that stops reporting and a loader that reports without moving.

Tokens, as this page reads them
--nk-rise
—
--nk-wave-floor
—
--nk-stagger-step
—
--nk-period-pulse
—
--nk-period-sweep
—

Read from <html>, so these are the OS-level values — the rig is scoped to a panel and does not reach them. The top three collapse under the real preference; the two periods do not, at any setting.

What the rig cannot do
  • motion-safe: is a MEDIA variant. Under the real preference Tailwind emits no rule at all, so NkEnter, NkTextBlur and NkTextStagger get no animation whatsoever. Inside the rig their animation still runs, with zero travel, zero blur and zero stagger — a plain fade rather than nothing. Read the entrance family under the OS setting.
  • Rule 1’s transition-duration: 1mscannot reach an INLINE style, so the pointer family’s inline transitions are unaffected here. That gap is real under the OS preference too — which is exactly why that family is gated in JavaScript instead, and why it attaches no listener at all rather than tracking faster.

Scroll

Three components driven by where the reader is. All three are built around the same hazard: an effect that hides content and then depends on JavaScript to reveal it.

NkScrollReveal

3 states

Scroll the pane below and watch the state badges. The usual whileInView shape — render at opacity: 0, observe, animate to 1 — has five failure paths that all end in content that is NEVER SHOWN. So this one is revealed by default and the effect is what hides it, and the hiding state is set in a layout effect, before paint, only after confirming the element is both observable and currently outside the viewport.

idle
visible · no observer · the server-rendered state
armed
hidden · waiting · only ever set from inside the effect
shown
intersected · playing the entrance
once · the defaultdata-nk-reveal=—

Reveals once and disconnects the observer. Already on screen at mount, so it went idle → shown and was never hidden — arming an above-the-fold element would be a visible flash on every page load.

once={false} · re-arms on leavingdata-nk-reveal=—

Scroll this row out of the pane and back: it returns to armed and replays. Used sparingly — a section that re-animates every time the reader scrolls past it is the single most common way this effect turns from a flourish into a tic.

variant · shared with NkEnterdata-nk-reveal=—

The same six-value vocabulary and the same keyframe. slide-left starts to the RIGHT and travels left, which is what the name says.

no useInView hook, deliberatelydata-nk-reveal=—

A hook returning inView: booleanhas to pick a value for “not measured yet”, and both answers are wrong: false is the hidden-by-default defect, truemeans an element below the fold animates at mount and the effect never plays. The distinction between “not observed yet” and “observed, not intersecting” is the whole component.

an empty inline elementdata-nk-reveal=—
measured rect
—

A zero-size rect means the position could not be DETERMINED, which is not the same as “off screen” — and that difference is the sixth failure path, the one the library’s own test found rather than the five that were reasoned about. An element with no box can never intersect either, so arming it on the strength of a 0×0 rect hides it permanently: the observer is installed, it is never satisfied, and the content is gone. Treated as unmeasurable it falls through to shown — visible, like every other uncertain case here.

If you flip reduced motion while this page is open, check this pane. The preference is read ONCE, in the layout effect that runs at mount, and that effect does not re-run when the media query changes — so a row that armed before you flipped the setting stays armed and hidden until it next intersects, which is not what a reduced-motion reader should ever see. Reload with the preference already on and every row here reports idle at full opacity instead, which is the documented behaviour and the one that matters. Both states were measured in the browser rather than reasoned about; the window is narrow and self-clearing, but it is real.

One more caveat this pane makes visible: the mount-time measurement is against the WINDOW viewport, not against a scrolling ancestor. A row clipped by this pane but still inside the window’s rect is measured as on screen and goes straight to shown — which is why the rows below the fold here start shown rather than armed, and why re-mounting does not change that. It errs toward visible, which is the direction the whole component errs in; the observer still fires correctly afterwards, which is what the once={false} rows demonstrate.

NkScrollProgress

fixed={false}

The hairline at the top of the pane above is this component with fixed={false} and targetpointed at the pane, which is how it is shown here without hijacking the page’s own chrome. Its default is fixed to the top of the viewport on z-sticky— the ladder’s rung for this, not amicro’s zIndex: 9999, which outranks a modal scrim.

It is aria-hidden by default. A reading-progress bar restates information the user already has from the scrollbar, the gesture and the content, and exposing it as a live progressbar means an assistive technology announcing a value that changes continuously while the user scrolls — a stream of interruptions over the thing they are trying to read.

label present · the opt-in

Passing label makes it a real react-aria ProgressBarwith a value rounded to whole percent — for the case where it is NOT redundant: a multi-step form’s completion, a document the user is being asked to read to the end. Announcing 37.4182% is noise. This one tracks the document, so scroll the page and watch aria-valuenow… except it is read once, on mount: the number below is the value at the moment this panel was measured, not a live feed.

Nothing here is gated on reduced motion, deliberately. The bar is not an animation — it is a direct representation of a gesture the user is performing, like the scrollbar itself, and prefers-reduced-motionhas never meant “stop reflecting my input”. The only animation is the inter-sample smoothing, on --nk-duration-instant, which collapses on its own. A spring here — which is what the original uses — adds lag between the scrollbar and its own readout.

One sample per frame

rAF

A scroll listener that calls setState per event re-renders dozens of times per frame on a trackpad, and on a long document that is the whole of the jank a progress bar gets blamed for. The listener here stores nothing but a flag and schedules one requestAnimationFrame.

resize matters as much as scroll and is the half that is usually missed: rotating a phone or opening a devtools pane changes clientHeight, so the same scrollTop is now a different fraction. Without it the bar silently desynchronises.

The fill is a scaleX on origin-left, not a width: a width animation lays out and paints every frame, a transform composites. And a zero-height scroll range reads 0 rather than NaN — 0 / 0 in a transform drops the declaration and leaves the bar at its untransformed FULL width, i.e. a progress bar reading 100% on a page with no scrolling.

The colour is bg-primary and a consumer restyles it with className. amicro takes color = 'bg-blue-500'as a PROP — a prop whose type is “a Tailwind class name”, which cannot be typed, cannot be themed, and cannot be scanned: a caller passing a computed string gets no CSS at all.

NkStickyReveal

4 items

A narrative column beside a pinned visual that follows it. The active item comes from an IntersectionObserver with a centre-band rootMargin— “which item is in the middle of the viewport” — rather than from mapping scroll progress through index / count, which assumes every item occupies an equal share of the scroll range. Items have different amounts of text, so they do not, and that swap drifts further out of step with the prose the further down you read.

  1. Plan

    The delta between the local config and the remote state, rendered before anything is applied. Four sections: infrastructure, databases, services, and the deploy scope a deploy from this working copy would touch.

  2. Sync

    Project files reach the target over rsync or git, and the host is bootstrapped if Docker is missing. Change-proportional: only the services that actually changed since the last successful deploy from this working copy to this target.

  3. Reconcile

    The core engine resolves the dependency DAG and brings services to their declared state over an SSH tunnel to the remote Docker socket, healing and continuing rather than failing on the first error.

  4. Observe

    The bridge detects the new services and starts streaming stats. Telemetry gathers in parallel from several Docker engines, so one slow or offline environment does not block the others.

Below lg the visual is dropped, not shrunk. Stacking the panel above or below the text breaks the pattern rather than adapting it: a pinned visual that changes as you read is MEANINGLESS when it is not beside the thing you are reading, and a panel stacked at the end of the list is a picture of whichever item you happen to have scrolled past. On a narrow screen this renders as what it actually is underneath — an ordered list of titled sections. Narrow this window and the dimming of inactive items goes too: with no panel to point at, a dimmed paragraph is just harder to read.

The panels are aria-hidden and inert. Only one is visible at a time and which one is chosen by SCROLL POSITION, which is not a thing a screen-reader user has in the same way and not a thing a keyboard user can drive. They are also stacked on top of each other at opacity: 0, so a focusable element inside one would be a keyboard trap in invisible content — WCAG 2.1.2. Henceinert on every inactive panel, and hence the contract: a caller must not put anything in visual that title and description do not already say. The four panels here restate their own titles.

amicro’s markup is flex justify-between with two w-1/2 children and a 60vhsticky panel at EVERY width — on a 390px phone that is two 175px columns and prose at roughly 20 characters per line. This library’s hard rule is that every surface works at mobile widths with zero horizontal scroll, so the layout is single-column first and only becomes two columns at lg.

Adoption

An honest ledger of what the motion layer drives today.

motion.css

8/8 reached

What the motion layer actually drives today. A token that nothing consumes is a proposal, and this page says so rather than implying otherwise.

  • entering: / exiting: variantsIn use

    Registered in motion.css. Before that, seven components wrote these classes and Tailwind emitted nothing for them, so no overlay animated at all.

  • Duration + easing tokensPartial

    Consumed by NkPopover (and therefore NkSelect, NkComboBox, NkMultiSelect, NkDropdownMenu), NkBottomSheet, NkSplitPane, NkOtpInput, NkToggleGroup, NkUsageBar and — since this row last said otherwise — the whole dialog family: NkDialog.tsx:56,58,91,94 is token-driven and NkModal / NkAlertDialog import the same two strings from it. NkDrawer.tsx:87,88,115,116 is the one holdout, with literal duration-200 / duration-300.

  • Travel tokensIn use

    --nk-lift: NkOtpInput, NkCardHover. --nk-rise: NkDialog.tsx:90,93 (as --tw-enter-translate-y), enter-variant.ts — so NkEnter and NkScrollReveal — plus NkTextStagger, NkCardHover and @keyframes nk-cadence, which is where the typing indicator’s dots get their bob. --nk-shift: enter-variant.ts and NkMagneticButton, whose lean is capped at it.

  • Scale floorsIn use

    --nk-scale-in: NkDialog.tsx:89 (zoom-in-[var(--nk-scale-in)], not the old literal zoom-in-95), NkSteps.tsx:299, and enter-variant.ts’s scale variant. --nk-scale-out: NkDialog.tsx:92. There is exactly one scale floor and NkEnter declines amicro’s second one (zoom) rather than adding a second answer to a question the library already answered.

  • Loop periodsIn use

    All three are consumed on the day they were declared, which is the point of declaring them: --nk-period-pulse by NkTypingIndicator, the caret in NkTextTyping and NkTerminalLoader, and NkLoadingSpinner’s dots/pulse variants; --nk-period-sweep by NkTextShimmer, NkSkeleton, NkRadarSweep and the spinner’s rail; --nk-period-wave by NkWaveform and the spinner’s bars. The rail’s own comment used to say its 1.5s had no token.

  • Amplitude tokensIn use

    --nk-stagger-step: NkTextStagger, NkTextTyping (as its per-character cadence), NkTypingIndicator, NkWaveform, NkSkeleton’s lines, NkLoadingSpinner and useStagger. --nk-blur-in: NkTextBlur via @keyframes nk-blur-in. --nk-wave-floor: @keyframes nk-wave. Each one exists so the reduced-motion block has something to collapse — that is what makes a loop able to keep its cadence while losing its movement.

  • The keyframe layerIn use

    Nine named keyframes in motion.css, reached through Tailwind’s stock animate-[…] group rather than through a new @utility — so the manifest is unchanged at 20 channels, 15 utilities, 2 variants. Before this, NkLoadingSpinner rendered a <style> element containing @keyframes as a CHILD OF ITSELF, so a view with four spinners injected the same keyframe four times, on every render, into the document the browser was animating. apps/hub/src/components/ui/LoadingView.tsx still does the same thing through dangerouslySetInnerHTML.

  • Reduced-motion policyPartial

    The motion.css media block is global, so it reaches everything written as a class or a token. Two documented gaps remain, both by construction rather than by oversight: an INLINE transition is out of its reach (which is why the pointer family is gated in JavaScript instead), and one component opts out by hand — see the motion-reduce:animate-none tripwire.

Source: modules/nk-lib/src/motion.css. Imported by this app in src/app/global.css, after @import "tailwindcss" — the order matters, because the two custom variants have to be registered before Tailwind compiles the classes that use them.