Pointer

Five components and two hooks that answer the cursor, rewritten from amicro’s set. There is no motion library underneath any of them — the whole mechanism is CSS custom properties written imperatively to one node per frame. Four of the five are for marketing surfaces and say so in their own headers; the table below is those headers, and it comes before the effects on purpose.

Placement

The family's own verdicts on where each member may be used, and the specific cost behind each refusal.

Where these belong

Read first

Four of the five name the Hub as off-limits in their own headers, each for a specific stated cost rather than out of general caution. This table is those headers, and it is the first thing on the page on purpose.

  • NkCardHoverAnywhere, Hub included

    The one member of the family that is safe on a dense surface: 2px of travel, no listener, no state, no per-frame work, and nothing about it is pointer-position driven. It is a hover affordance, and a tile that answers the cursor is how a grid tells you its cells are reachable. It is also the only one on @nkapp/lib/isomorphic — no hook, no react-aria, so it can BE a React Server Component rather than merely be rendered by one.

  • NkMagneticButtonMarketing surfaces only

    A landing hero, a pricing call-to-action — a page with one or two primary actions where the cursor’s arrival is worth acknowledging. Not the Hub’s dense views. A toolbar of eight magnetic buttons is eight window listeners leaning in different directions, and a control that moves as you approach it is a worse target to hit — which matters when hitting it is the whole job. Rule of thumb: one per viewport.

  • NkTiltCardMarketing surfaces only

    A feature card, a testimonial, a screenshot. Not the Hub’s dense views, and never around a table. A grid of tilting cards is a grid of elements that are no longer axis-aligned with each other, which makes a scan comparison harder rather than easier; and a tilted plate mis-aims every hit target on it by a few pixels — a real cost for a row of controls and no cost at all for a paragraph.

  • NkSpotlightMarketing surfaces only

    Large feature panels — a pricing table, a hero card, a documentation tile. Not the Hub’s dense views. The glow is a repaint of the gradient layer on every frame the cursor moves: on a 400px card that is cheap and confined, and on a full-page container behind a long table it is a full-viewport repaint per frame. Scope it to a panel, never to a scroll region or a data grid.

  • NkCursorTrailOne per site, or not at all

    Never in the Hub, never on a data grid, never on any surface whose job is to be read or operated. It is the showiest thing in the library and the least discriminating: mounted once, it then decorates the cursor everywhere — including over a table the user is trying to scan and a form they are trying to fill. It conveys nothing, it cannot be made to convey anything, and its entire value is atmosphere.

The test every one of them passes

The effect is decoration and never state: it encodes nothing, it is never the only way to perceive anything, and removing it leaves a fully operable surface. That is the test for whether an effect like this may exist at all — and it is also why the reduced-motion answer is to remove it entirely rather than to make it faster.

The gate

Two media queries, read live, that decide whether any of this runs at all. The library's own hooks, called here rather than re-implemented.

Your browser, right now
prefers-reduced-motion: reduce
true
(hover: hover) and (pointer: fine)
false
usePointerEffectsEnabled()
false

One of the two halves fails, so the family is inert on this device and every specimen below is rendering its undecorated path — which is the point of the page as much as the effects are. NkCardHover is the exception: it has no listener and no JavaScript, so its colour affordances still work and only its travel is gone.

Both queries are required, because a pointer-driven decoration has two separate ways of being wrong and satisfying one does not satisfy the other. amicro ships a use-reduced-motion hook and its own components ignore it — the magnetic button, the tilt card, the spotlight and the cursor trail all animate regardless. A hook existing is not the same as a preference being honoured, which is why the gate here lives inside useMousePosition: a component cannot forget it, because forgetting means getting no samples.

The second query is deliberately not (any-pointer: fine), which is true on every touchscreen laptop and would keep the effects running on a tablet that happens to support a stylus. It is also read LIVE rather than once: fold a Surface’s keyboard away and Windows re-reports pointer: coarse under the page.

Hover and focus

The one member that belongs on a dense surface, and the four that answer the pointer's position.

NkCardHover

2 lifts

It moves. That is all. It carries no background, no border, no radius and no shadow, so it composes with NkCard, with a bare <a>, with a table row — and cannot disagree with any of them about what a card looks like. Had it owned a radius it would have had to own the fill and the hairline too, and it would then be a second card implementation to keep in step with the first.

lift="nudge"
--nk-lift · 2px
The default, and the right answer for a grid of tiles: at 2px the tile answers without the row appearing to shuffle.
lift="rise"
--nk-rise · 6px
For a single large feature card on a marketing page, where 2px would be invisible at that size.

The colour half of the affordance belongs to the CHILD. The wrapper sets Tailwind’s group class, so the card states what it wants — group-hover:border-primary/50 and its group-focus-within: twin, both written out above.

Reduced motion collapses --nk-lift and --nk-rise to 0px, so the lift becomes literally nothing — while every colour and border change the child wired through group-hover: keeps happening. The user asked for less movement, not for less information, and a hover affordance that disappeared entirely would take away the only hint that the tile is interactive. There is no JavaScript gate here because there is no JavaScript.

Touch does nothing, by construction: Tailwind v4 wraps hover: in @media (hover: hover), so the lift is never emitted for a device whose primary pointer cannot hover — which also means no sticky “stuck hovered” tile after a tap, the usual iOS failure.

It animates translate rather than transform, so it cannot clobber a transform a consumer or a child sets — and NkMagneticButton, which also writes translate, is the one to compose with deliberately rather than by accident.

NkMagneticButton

0 renders

Approach the button — from outside it, which is the part that usually does not work — and read the two factors. They are what the component writes per frame; everything else is one translate declaration set once at mount, and the browser compositing it.

Idle — hover the stage
--nk-magnet-fx
0
--nk-magnet-fy
0
resolved translate
—
will-change

The factors are unitless so the length arithmetic stays in CSS — calc(travel * factor). A frame therefore writes two short numeric strings rather than building two calc() expressions, and travel can be a token that resolves at use time. will-change is set only while a lean is in progress and removed on settle, so an idle page holds no promoted layer.

It is a wrapper, not a button. amicro’s renders its own <button> with a hard-coded rounded-full bg-neutral-900 h-11 px-6, so adopting it means maintaining a second button that knows nothing about NkButton’s six variants, four sizes, loading state, asChild slot or react-aria press handling — and drifts from all of them at the first change. This one contains your button.

The proximity radius works. Theirs measures hypot(cursor − centre) < 45pxfrom a handler bound to the button, which can only fire while the cursor is already ON it — so the “magnetic from a distance” behaviour its own knob describes never happens. Here the distance is measured from the element’s EDGE and the sampler is on the window, so range (default 48px) means what it reads as.

The travel is bounded by the token scale. Theirs multiplies an unbounded cursor distance ((cursor − centre) * 0.35), which on a wide button at the far corner is tens of pixels. The ceiling here is --nk-shift — 8px, the largest step in the travel scale — via min(1, length).

Nothing in this family overshoots. Two phases, two curves, shared with the tilt card and the spotlight so the three cannot drift: FOLLOW is --nk-duration-instant on --ease-standard, SETTLE is --nk-duration-slow on --ease-enter. A back-out curve is available and deliberately unused — an 8px lean that springs past zero reads as a toy on a product surface.

One thing to know

A non-none translate makes this span a containing block for position: fixed descendants, so a popover rendered INSIDE a magnetised control positions against the span rather than the viewport. Put the magnet around the trigger, not around the trigger and its overlay. That is also why the property is absent rather than zeroed when the effect is off — see the next section, which measures the difference rather than asserting it.

NkTiltCard

8° by default

The motion design is amicro’s and well judged: normalise the cursor to ±0.5 of the card’s own size, map that to rotateX/rotateY with the Y axis INVERTED — pointer below centre tips the bottom toward you, which is what a physical plate does — put the perspective on the parent, and lift the content off the plate with a translateZ.

maxTilt
depth
range
Deploy anywhere
One config file, five providers, one deterministic plan.
nkapp deploy -e production
maxTilt=8°

8°, not 15°. At 15° on a card-sized element the near edge noticeably foreshortens and text on the plate goes soft, and the surface reads as a toy rather than as a responsive object. Switch between them above and read the command line as you do — 8° is enough to be unmistakably three-dimensional and still legible.

depth is opt-in. amicro always renders a translateZ(40px) wrapper. It is a genuinely good effect with two costs worth choosing deliberately: a 3D-transformed subtree is rasterised before it is composited, so text on it can lose a little crispness, and preserve-3d flattens anything that needs its own stacking inside it.

range defaults to 0 — the tilt begins when the cursor arrives on the card, which is what a plate does. A small positive value makes it start tipping as the cursor approaches, which suits a single hero card and reads as fussy in a group.

perspective on the stage and the transform on the plate each make their element a containing block for position: fixed descendants, and depth adds preserve-3d, which flattens descendant stacking. A hand-positioned overlay rendered INSIDE the card positions against the card; react-aria’s overlays portal to the body and are unaffected. Tilt the content, not a control that opens one.

Unlike the magnet there is NO second guard from the token scale here: a rotation is measured in degrees and motion.css has no angle token to collapse — its travel tokens are all lengths. The JavaScript gate is therefore the only mechanism, which is exactly why it is pinned by a test rather than trusted.

NkSpotlight

Follows focus too

A soft light that follows the cursor across a surface — and, uniquely in this family, follows keyboard focus as well. Tab through the three plans below: the light moves to each one in turn, which is what makes the effect mean something to somebody who is not holding a mouse.

tint
intensity

The light is a token. amicro’s is rgba(255, 255, 255, 0.08) — a literal white that is invisible on a light ground and ignores the theme entirely. Here it is mixed from a semantic token with color-mix(in oklab, …), so the same translucent veil reads as the same neutral ink on both grounds. Switch the theme with the header toggle and watch it hold.

Above about 15 the gradient stops reading as light and starts reading as a coloured blob — try intensity=20 with tint=primary. A coloured glow behind body text also costs contrast, which is why foreground is the default: a spotlight is light, not brand.

focusin bubbles (unlike focus), so the component hears a descendant taking focus and moves the light to the centre of that element’s box, in the container’s coordinate space. focusout with an incoming related target still inside the panel is ignored — focus moving between two controls inside is not a reason to dim it. Switch followFocus off and tab through again: the panel goes inert for a keyboard.

The panel is overflow-hidden and isolate, which is what keeps the light inside its radius and out of its siblings — and which also CLIPS anything that needs to escape the box. A hand-positioned tooltip or absolute panel inside a spotlit surface will be cut off at its edge.

The glow is its own absolutely-positioned layer rather than a background-image on the container, and that is a performance decision rather than a structural one: repainting the container would repaint its content with it. The gradient is written once and only the two position properties are touched per frame.

NkCursorTrail

Off by default

It is off by default here, and that is itself the demonstration: the component mounts once and then decorates the cursor across the whole document — including over the measured readouts and the keyboard walk on this very page. There is no way to scope it, because there is no scope at which a cursor decoration makes sense.

count · clamped to 1…12
tint

One loop, no React state, no per-dot component. amicro calls setCoords on every mousemove, re-rendering the parent and all six TrailDot children, each of which then runs an effect to push the new coordinates into its springs — six components reconciled per pointer event. Here one requestAnimationFrame loop writes two custom properties per dot, and the loop stops itself once every dot has arrived, so a mounted trail costs nothing on a page nobody is moving over.

Frame-rate independence. A fixed per-frame lerp factor produces a visibly tighter trail at 120 Hz than at 60 Hz. The factor here is reconstructed from the elapsed time each frame — 1 − (1 − k) ^ (dt / 16.67) — so the trail has the same shape on every display.

The taper is floored. Theirs computes size × (1 − i/count) and the same for opacity, which on the default six dots makes the last one 1.3px across at 17% opacity — present in the DOM, invisible on screen. The ramps here stop at 35% size and 20% opacity, so every dot the component renders is a dot you can see.

It portals to document.body, because a position: fixed element is positioned against the nearest ancestor with a transform, filter or backdrop-filter rather than against the viewport — so a trail mounted inside an animated panel would silently land in the wrong place. It sits on z-tooltip, which is a stated compromise: the ladder has no rung for “the cursor”, and adding one belongs in tokens.css.

Reduced motion

The clearest case in the family: the component is motion, there is no non-moving version of it that means anything, and a slower trail is still a trail chasing the pointer. So it returns null — no portal, no dots, no listener, no loop. Returning null rather than rendering hidden markup also means no stray fixed-position node is left over the page.

Keyboard

Touch and keyboard are decided in this family, not omitted — and the decisions differ per component. Tab through the strip and read what each one did.

Walk it with the keyboard

0/5 walked

Put focus in the strip below — click the first control, or Tab into it — and walk it with Tab. Five stations, one focusable control in each, in order. Two respond to focus and three do nothing; the row for whichever station holds focus prints what was measured off the element that effect actually drives.

5 · NkCursorTrail — nothing to focus

Station 5 has no control, so Tab skips it entirely — which is why its row reports a count rather than a state. Every row below is measured at rest on load and again while its station holds focus, so none of them needs clicking and the two columns are directly comparable. The focused column reports what each property REACHED across the focused interval rather than its value at one instant: a single read at a chosen moment got this backwards three times before it was measured properly.

  • NkCardHoverresponds to focuslifts — every hover: rule has a focus-within: twin

    focus-within: is paired with every hover:rule, and a library test walks the class list and FAILS on an unpaired one — “has no focus-within twin, so tabbing to this tile does nothing”. The travel is 2px and axis-aligned, so lifting under a focus ring moves the ring by two pixels in a straight line rather than rotating it.

  • NkMagneticButtonno responseno lean — the factors stay at 0

    Deliberate. A focused button that drifted toward wherever the mouse happens to rest would move its own focus ring for no reason, and a focus-driven lean has no position to aim at. Both this and NkCardHover animate translate, so the two measured values above and below are directly comparable: focus moves one and not the other, and the difference is a decision rather than an oversight.

  • NkTiltCardno responseno rotation — identity transform

    A positive decision rather than an omission. Tilting on focus-within would rotate the plate under a focus ring the moment it appeared, moving the ring and everything it outlines — the one piece of UI that must stay exactly where the user put it. The difference from NkCardHover is the rotation, not the family.

  • NkSpotlightresponds to focusthe light moves to the focused control

    The one path in the family that does NOT require a fine pointer, because a keyboard user on a hybrid device is still a keyboard user. focusin centres the gradient on whichever descendant took focus, so tabbing through a spotlit pricing table lights each plan in turn instead of leaving the effect inert for anyone not using a mouse. Still gated on reduced motion.

  • NkCursorTrailno responsenot in the tab order at all

    Nothing, and nothing is the right answer: a trail that jumped to each focused element would be a second, competing focus indicator following the real one around. NkSpotlight is the component for lighting a focused control. There is no station control to focus here because the component renders no focusable node — the number above is that, counted.

One thing to read the table against: on a device with no hovering fine pointer the magnet and the tilt report none in BOTH columns because the family is switched off entirely, not because focus declined to move them — check The gate above. With a mouse attached they read 0px 0px and an identity matrix instead, which is the sharper comparison: the property is present, focus simply does not drive it, while NkCardHover beside them moves the same translate by 2px.

None of the five lean, tilt, light or trail is ever the only way to perceive anything. Every control inside keeps its own role, name, focus ring and activation; the wrappers add no tabIndex, no role and no handler. That is the test for whether an effect like this may exist at all — remove it and the surface is unchanged.

Reduced motion

The property is removed, not zeroed, and the difference is measurable rather than theoretical.

Absent is not zeroed

2 probes

Under reduced motion this family removes the transform property instead of setting it to zero. The reason is not tidiness: translate: 0 still creates a containing block for position: fixed descendants, so a switched-off decoration would go on changing the layout of anything inside it. Both probes below are identical position: fixed elements at top: 0; left: 0.

translate: 0px 0pxno translate
wrapper rect.top
—
probe INSIDE translate: 0
—
probe with no translate
—
verdict
measuring…

The first probe tracks the wrapper as you scroll; the second stays at 0. So NkMagneticButton renders no style attribute at all when the gate is closed, NkTiltCard drops its perspective and transform-style as well as its rotation, NkSpotlight does not render the glow element, and NkCursorTrail returns null — no portal, no dots, no listener, no loop. Not a slower effect: no effect.

NkTiltCard keeps its surface element in BOTH states, carrying only h-full w-full when the effect is off, so a preference flip mid-session changes a style rather than remounting the subtree — nothing inside loses focus, scroll position or component state.

The hooks

One sampler the whole family runs on, and the stagger helper that keeps a cascade on the token scale.

useMousePosition

3 counters

Move the pointer anywhere on this page and watch the three counters. A pointer listener is the cheapest thing in the world to add and one of the easiest ways to make a page janky, because the cost is not in the listener — it is in what the listener triggers.

Raw pointermove events
listener
window · passive · uncoalesced
events seen
—

The control. An implementation that calls setPosition per event does this much work, each time preceded by a synchronous getBoundingClientRect().

The mode the family uses
mode
onSample — the zero-render path
samples delivered
—
React renders
—

The hook keeps NO state and NEVER re-renders: it hands you the sample and you write it straight to the DOM. Its returned value is a frozen module constant, so destructuring it in render is safe and inert. Compare “samples delivered” against the events column — the difference is the per-frame coalescing, and a burst of coalesced pointer events between two frames collapses into one sample, which is the most a display can show anyway.

The stateful mode
mode
stateful — the returned value
x, y
0, 0
React renders
—

It exists for a consumer who genuinely needs the coordinates IN RENDER. Here it is one tiny component; put it above a table and every row reconciles once per frame for as long as the pointer moves, and that is how a “subtle” effect makes a page janky. Switch it off and the counter stops dead — the listener is removed, not merely idle.

The one unavoidable cost is a getBoundingClientRect() per frame when a target is given, which forces a style/layout flush if layout is dirty. It is once per frame rather than once per event, and it is read inside the animation frame where the browser is about to lay out regardless. These components animate only translate, transform and background-position, none of which dirty layout.

scope is the other half of the budget. 'target' — the default when a target is given — binds the listener to the element, so it fires only while the pointer is over it and costs nothing the rest of the time; NkTiltCard and NkSpotlight use it. 'window' is needed only for an effect that must react to the pointer being NEAR but not over the element (the magnet) or that has no element at all (the trail), and it is the more expensive of the two.

pointerleave, never pointerout, and on both scopes: pointerout bubbles, so on the window scope it would fire every time the pointer crossed from one element to any other and reset the effect mid-sweep. The resting sample is emitted IMMEDIATELY on leave rather than on the next frame, which is what makes the settle transition start at the moment the cursor actually left.

A touch sample is dropped explicitly (pointerType === 'touch') even though the fine-pointer gate makes one unlikely. A hybrid device can deliver one, and a tap-driven “hover” that sticks is the exact failure the gate exists to prevent.

useStagger

7 items

The from model — first, last, centeror an index to radiate from — is amicro’s, and it is the good part: a centre-out cascade is genuinely hard to get right by hand and reads completely differently from a left-to-right one. The unit is not theirs.

plan0ms
sync0ms
build0ms
push0ms
reconcile0ms
verify0ms
observe0ms

Every value above is a CSS time expression over a token. The return type is a string because calc(var(--nk-stagger-step, 45ms) * 3) cannot be reduced to a number without reading computed style off a live element — a layout read per item, which would defeat the point. The string drops straight into style={{ animationDelay: delays[i] }}.

It is a STYLE value, never a class name, so none of it goes near the Tailwind scanner and the rule against assembling a class from an interpolated value does not apply. Writing delay-[Nms] from a variable instead would compile to nothing, silently — which is the reason the hook exists in this shape.

Under prefers-reduced-motion the hook returns a literal 0ms for every item, which is NOT redundant with the token collapsing to 0ms on its own: a consumer who has not imported @nkapp/lib/motion.css would otherwise get the 45ms inline fallback and a live cascade, and a consumer feeding these values to a setTimeout ladder gets a number it can act on rather than a string it must resolve.

A stagger is a cascade of ONSETS rather than travel, so flattening it to simultaneous is the correct reduced-motion answer — every item simply appears together. That is a different collapse from the amplitude ones, and it is why the step is a token in the first place.

Source: modules/nk-lib/src/ui/NkCardHover.tsx, NkMagneticButton.tsx, NkTiltCard.tsx, NkSpotlight.tsx, NkCursorTrail.tsx, pointer-transitions.ts, and modules/nk-lib/src/hooks/useMousePosition.ts, useMotionPreference.ts, useStagger.ts. Four components and all three hooks are on @nkapp/lib/client; NkCardHover is on @nkapp/lib/isomorphic, and /client re-exports that entry as a superset — which is why the single @nkapp/lib/client import at the top of this page reaches all five. The bare @nkapp/lib barrel does not: it is the isomorphic half now, so of this family it carries NkCardHover and nothing else.