Foundations
KinetixUI has one set of design foundations — tokens for color, type, space, shape, elevation and
motion — defined once in tokens/ and compiled by Style Dictionary to CSS, TypeScript, SwiftUI, Compose
and Flutter. The components on every platform read those tokens; they don't restate values.
This page covers the foundations that shape layout. Color and type live on Tokens and Theming; Dark mode, RTL and Accessibility have their own pages.
The 8-unit grid#
KinetixUI uses an 8-unit base spatial grid with an optional 4-unit half-step for compact and fine-grained interface needs.
Space is measured in units, not pixels, because KinetixUI is multi-platform: a unit is a CSS pixel on the web, a point on iOS, a dp on Android and a logical pixel in Flutter. Every value on the scale is a multiple of 4. A multiple of 8 is a base step; any other multiple of 4 is a half-step.
The token number is the value divided by 4 (--spacing-4 is 16), the same numbering Tailwind uses, so a
utility like p-4 and the token --spacing-4 agree. Steps 1–8 are for component internals — padding,
gaps, control sizing. Steps 10–32 (40–128) are the layout scale: section spacing, containers, page gutters.
What the grid governs — and what it doesn't#
The grid governs spacing, padding, margins, gaps, layout, control sizing and touch layout. It does not govern:
- Typography. Type is sized for readability, hierarchy and each platform's text scaling (Dynamic Type, Android font scale, Flutter's text scaler), not for a multiple of 8. See Tokens.
- Hairlines and optical nudges. A 1px border or a 2px offset isn't a spacing decision.
- The
.5steps. Tailwind's0.5,1.5,2.5and3.5(2, 6, 10 and 14px) are the optical gap between an icon and its label and similar fine alignment. They are used deliberately and are not policed.
Keeping it on the grid#
pnpm check:grid runs in CI. It checks that every spacing token is a multiple of 4, and that the component
library does not gain a new arbitrary pixel value (p-[13px], gap-[22px]) that is off the grid. Three
exist today, all 18px — the checkbox and radio boxes and the button icon — because the design source
specifies them; they are listed by name in the script, with the reason. It is a guardrail against new drift,
not a rewrite: the components already sit on the grid the large majority of the time.
Radius#
Radius follows the same philosophy: multiples of 4, with full for pills and circles. Components take their
radius from these tokens rather than inventing one.
Role aliases#
Sizes tell you how round; roles tell you what is round. A role alias is a token that points at a size step, so a theme can reshape one kind of thing — every field, say, or every card — without disturbing the rest:
The mapping is measured from how the components use radius today (every component named above uses a class of
that size). On the web each alias is a live reference — --radius-control: var(--radius-md) — so overriding a
step carries through to its roles, and the Tailwind preset has matching rounded-field, rounded-control,
rounded-container and rounded-surface utilities. On SwiftUI, Compose and Flutter the same names are on
KinetixRadius.
The aliases are additive: components still use the size steps, and move to the roles one at a time. A
component can use more than one size (a menu's container is control, its items are field-sized), so a role
names the component's outer shape.
Why not rename the sizes? The public names sm (4) and md (8) predate the grid and are used across the
library and consuming apps. Renaming to xs 4 / sm 8 / md 12 / lg 16 / xl 24 would shift every name by one
step — a breaking visual change on every platform. Roles give the same benefit without breaking anything. The
one addition to the steps is xxl (24), the missing step on the grid. (Tailwind's rounded-2xl is a separate,
older value — 20px — and is not xxl.)
Elevation#
Elevation is the shadow that separates a surface from what's behind it. The table shows the levels as the
components use them today, measured from the source. The level names are documentation for now — the
values themselves are the --shadow-* tokens — and each platform draws shadow with its own mechanism, so
values need not be identical everywhere.
Motion#
Two duration and easing scales, shared by every platform. Native ports expose them as KinetixDuration and
KinetixEasing.
What each tier is for. instant is press and toggle feedback — the tier a control reaches for when it
has to answer the pointer. fast is a small state change: a chevron, a tab, a menu opening. base is a
fade or a progress stroke. slow is a large surface arriving, and slower exists for looping animation,
which is almost always the wrong answer. The easings carry direction rather than taste: enter decelerates
because a surface that is arriving should settle, exit accelerates because one that is leaving should get
out of the way, and emphasized is reserved for the rare transition that should be noticed.
When not to use motion. Nothing decorative that runs on its own, nothing that delays an interaction,
nothing that animates layout unless moving is the point (Tour's spotlight travelling between targets is
the exception that proves it). Prefer opacity and transform; naming the properties that actually change
beats transition-all, which quietly animates layout too.
Core is quieter than IoT, deliberately. A button or a menu should feel immediate and then get out of the
way. @kinetixui/iot uses motion to carry state that genuinely has stages — requested, pending, confirmed —
and that is a different job, documented in IoT.
Reduced motion. @kinetixui/ui ships no CSS of its own, so the guarantee lives in the Tailwind preset
consumers already extend: under prefers-reduced-motion: reduce it shortens every duration to 0.01ms
rather than removing motion. That distinction is the safety property. A shortened transition still arrives
at the same end state, so a checked box is still checked, a switch thumb is still moved and an IoT control
still reads confirmed rather than requested — the interpolation goes, the information does not. It is also
why the rule is not animation: none: Radix unmounts an overlay when its exit animation fires
animationend, and an animation that never runs never fires it, which would strand the overlay in the tree
for exactly the people who asked for less motion. Components that need more than this floor still say so at
their own call site with motion-reduce:, as the IoT package does where a pulse carries meaning.
Loops are the one case the floor cannot handle, because it turns an infinite animation into a single frozen
frame. So a loop states its own reduced form with motion-reduce:animate-none, and what that form is depends
on what the loop was saying: a Spinner rests as a ring that keeps its role="status" and name, a Skeleton
rests at full opacity, a Marquee stays still. A source check refuses a loop that does not say so.
Registry consumers. The preset above is not part of npx @kinetixui/cli add. A component copied that way
carries its own motion-reduce: classes, so its loops stop, but the global floor, tailwindcss-animate and
the custom keyframes come only from the @kinetixui/ui preset. Without it animate-in and the token
utilities are unknown classes, so those animations do not run at all, and a bare transition-* keeps
Tailwind's default timing. pnpm check:registry-motion checks the loops and the delivered token stylesheet;
it does not, and the registry cannot, promise that reduced motion shortens every transition.
Where each platform stands#
Four different things get called "supported", so they are kept apart. Defined: the value exists in the token source. Generated: it reaches the platform's own code. Consumed: a component reads it. Verified: a check shows reduced motion changes the behaviour.
| Platform | Defined and generated | Consumed by | Reduced motion |
|---|---|---|---|
| React | CSS variables, Tailwind utilities | every component with a transition | Global floor in the preset; loops state their own form. Verified in a real browser for Accordion, Collapsible, Switch, Spinner and Skeleton. |
| Angular | CSS variables | styles.css | Handled per component, with no global floor. The spinner slows to three seconds rather than stopping. |
| SwiftUI | KinetixDuration, KinetixEasing | disclosure and Switch; loops use their own periods | Reads Reduce Motion for disclosure, Switch, the four loops and the Sheet, Sidebar and Toaster slide. Tests cover the resolver only, since that package cannot render a view. |
| Compose | KinetixDuration, KinetixEasing | disclosure and Switch; loops use their own periods | Reads the system animator scale for the same set, except the slides. Tested through Robolectric composition, which asserts what the component exposes and not the motion itself. |
| Flutter | KinetixDuration, KinetixEasing | disclosure and Switch; loops use their own periods | Reads MediaQuery.disableAnimations for the same set. Widget tests sample rendered values over time. |
The native overlays other than the SwiftUI slides, and the native progress and focus-ring transitions, are
not covered by this statement. SwiftUI's Dialog only fades, and a fade is the accepted replacement for a
slide, so nothing was changed there.
Motion roles#
A role is a duration and easing pairing with a named job. The table is read from
tokens/contracts/motion.json, and pnpm check:motion-tokens holds it to the token source and to the
component files each role names: a role is proven only when it repeats on at least two platforms and a
check stands behind it, observed when the pairing repeats in source without a check of its own, and
proposed when it is a direction, not yet something any component does. Everything that is not a role
reads the tokens individually.
Angular's Switch runs on base rather than instant, which the contract records as a deviation rather than
hiding. Spring, stagger, delay and distance are deliberately not tokens yet: no component uses a spring, the
only stagger is the typing indicator, delays reuse a duration tier, and travel distance reuses the spacing
scale. MOTION.md says when each would be added.
On every platform#
The spatial and shape scales reach each platform from the same source:
| Platform | Where the tokens live |
|---|---|
| Web | CSS custom properties (--spacing-n, --radius-name) in globals.css; typed in @kinetixui/tokens |
| SwiftUI | KinetixSpacing, KinetixRadius, KinetixDuration, KinetixEasing (generated KinetixMotion.swift) |
| Jetpack Compose | the same enums in KinetixMotion.kt, plus spacing_n / radius_name in dimens.xml |
| Flutter | the same classes in kinetix_motion.dart |
Existing native components still contain literal numbers (with a // spacing/4 comment); moving them onto the
generated constants is incremental work, done component by component so nothing shifts visually.
See Supported platforms for what each platform covers today.