Div

<Div /> is the DS's canonical styling primitive — the equivalent of MUI's Box or Chakra's Box. A single <div> (or any other element via actLike / as / asChild) with a flat, token-aware CSS shorthand prop surface plus responsive show/hide, opt-in motion presets, a centered shortcut, full HTML pass-through, and pseudo-state className hooks.

Reach for <Div> whenever you'd otherwise write <div className="flex items-center p-4 bg-bg-paper">…</div> — it reads better and resolves theme tokens (primary.main, md, …) into CSS variables for free.

Anatomy

import { Div } from 'apx-ds';

<Div p={4} bg="primary.50" fg="primary.contrast" radius="md">
  A token-aware box.
</Div>

<Div display="flex" gap={12} alignItems="center">
  <Div flex={1}>Left</Div>
  <Div flex={2}>Right</Div>
</Div>

<Div hideOn="md">Mobile-only content</Div>
<Div displayOn="lg">Desktop-only content</Div>

<Div centered h={200}>
  <Spinner />
</Div>

<Div actLike="button" type="button" onClick={open} onHover="bg-primary-100" onFocusVisible="ring-2 ring-primary-500">
  Click me
</Div>

<Div animation="fadeIn">Fades in on mount</Div>

import { Div } from 'apx-ds';

<Div p={4} bg="primary.50" fg="primary.contrast" radius="md">
  A token-aware box.
</Div>

<Div display="flex" gap={12} alignItems="center">
  <Div flex={1}>Left</Div>
  <Div flex={2}>Right</Div>
</Div>

<Div hideOn="md">Mobile-only content</Div>
<Div displayOn="lg">Desktop-only content</Div>

<Div centered h={200}>
  <Spinner />
</Div>

<Div actLike="button" type="button" onClick={open} onHover="bg-primary-100" onFocusVisible="ring-2 ring-primary-500">
  Click me
</Div>

<Div animation="fadeIn">Fades in on mount</Div>

Prop surface

Styling shorthand

Every value flows through the engine's sxToStyle resolver — palette / radius / shadow / spacing token strings (e.g. bg="primary.main", radius="md") become var(--sds-…), plain CSS values pass through untouched. Scalars only in v1 (no { base, sm, md } shape on these props — use hideOn / displayOn / className for responsive layout).

Responsive show / hide

Both use Tailwind's mobile-first "from breakpoint upward" semantics, so each emits a single utility class that the JIT scanner picks up at build time.

Animation

The pressScale preset is not exposed here — it's a whileTap interaction that belongs on a trigger element (<Button>) instead.

Scroll reveal

Without animateOnView the animation runs on mount — so everything below the fold finishes animating before the user ever scrolls to it, and a long page reads as static. animateOnView moves the trigger to the viewport:

<Div animation="riseIn" animateOnView>
  Reveals as it enters
</Div>

<Div animation="fadeIn" animateOnView={{ once: false, amount: 0.5 }}>
  Re-reveals every time, once half-visible
</Div>

<Div animation="riseIn" animateOnView>
  Reveals as it enters
</Div>

<Div animation="fadeIn" animateOnView={{ once: false, amount: 0.5 }}>
  Re-reveals every time, once half-visible
</Div>

Stagger

A stagger parent cascades its animated descendants. The children need no extra props — having an animation is the opt-in:

<Div stagger={0.08} staggerDelay={0.1} animateOnView>
  {features.map((f) => (
    <Div key={f.id} animation="riseIn">
      <FeatureCard {...f} />
    </Div>
  ))}
</Div>

<Div stagger={0.08} staggerDelay={0.1} animateOnView>
  {features.map((f) => (
    <Div key={f.id} animation="riseIn">
      <FeatureCard {...f} />
    </Div>
  ))}
</Div>

This works through ordinary wrapper markup — the cascade travels by React context, not by DOM adjacency, so grid wrappers and layout <div>s in between don't break it. Groups also nest: an inner stagger both inherits its start from the outer group and sequences its own children.

The mechanism matters if you write custom children: a stagger participant declares Motion variants and deliberately omits initial / animate, because an explicit animate prop outranks the inherited variant label and would silently detach the child from the parent's timeline — making stagger look like it does nothing.

Reduced motion

Every path above is gated on useReducedMotion(). When it's on, <Div> renders a plain element with no motion props at all — which is the only safe answer for a scroll reveal, since a viewport trigger that never fires would otherwise leave content pinned at opacity: 0. A stagger parent also stops publishing its orchestration context, so its children fall back to plain elements too.

Shortcuts

// the verbose className recipe…
<Div className="absolute inset-0 pointer-events-none bg-[radial-gradient(80%_80%_at_0%_50%,var(--sds-palette-primary-subtle)_0%,transparent_70%)]" aria-hidden />

// …becomes a single composed shortcut.
<Div decorative gradient={{ position: 'left' }} />

// the verbose className recipe…
<Div className="absolute inset-0 pointer-events-none bg-[radial-gradient(80%_80%_at_0%_50%,var(--sds-palette-primary-subtle)_0%,transparent_70%)]" aria-hidden />

// …becomes a single composed shortcut.
<Div decorative gradient={{ position: 'left' }} />

Polymorphism

Pseudo-state className hooks

Each prop accepts a Tailwind className string. Every whitespace-separated token is automatically prefixed with the corresponding state variant via the engine's prefixClasses helper.

onFocus is intentionally absent because it would collide with React's native focus event handler. Use onFocusVisible (the a11y-correct choice for focus rings) or compose focus:* classes via the standard className prop.

HTML pass-through

id, role, aria-*, data-*, every event handler, plus the common element-specific attributes (href, type, target, rel, download, src, alt, name, value, htmlFor, disabled, checked) flow to the rendered element untouched. Use actLike to swap the element type and the matching attributes "just work":

<Div actLike="a" href="/docs" target="_blank" rel="noreferrer">Open docs</Div>
<Div actLike="button" type="submit" disabled={isSubmitting}>Save</Div>

<Div actLike="a" href="/docs" target="_blank" rel="noreferrer">Open docs</Div>
<Div actLike="button" type="submit" disabled={isSubmitting}>Save</Div>

Style resolution order

Lowest → highest priority:

1. centered defaults (display: flex; align-items: center; justify-content: center;)
2. decorative defaults (position: absolute; inset: 0; pointer-events: none;)
3. gradient (background-image: …)
4. sx (theme-aware object)
5. Curated style shorthand props (p={4}, bg="primary.50", display="grid", …)
6. Consumer style prop (escape hatch)

Classes layer the same way:

1. Recipe (hideOn / displayOn)
2. theme.components.Div.styleOverrides.root (theme override)
3. Consumer className
4. Pseudo-state hooks (hover: / focus-visible: / …)

tailwind-merge handles utility-class conflict resolution (last wins).

Examples

Accessibility

• <Div> is a layout primitive — no implicit role, no implicit ARIA, no focus management of its own.
• When you swap the element with actLike (e.g. actLike="button"), the rendered intrinsic element carries its own semantics. Pair with type="button" and let the native element handle keyboard activation; no extra role is needed.
• hideOn / displayOn use display: none, which removes the node from the accessibility tree at the matching breakpoint — that's almost always what you want for purely decorative or duplicate content. For content you want to keep announced but hide visually, prefer a Tailwind utility like sr-only via className.

RTL

• No RTL-specific code. The aliases mx / my / px / py map to logical properties (marginInline, paddingBlock, …) so they flip automatically under dir="rtl".
• Pseudo-state classes (hover:, focus-visible:, …) are direction-agnostic.

Theming

• <Div> reads from theme.components.Div.styleOverrides.root and theme.components.Div.defaultProps via the standard useThemedClasses hook.
• Consumer className always wins via tailwind-merge.

Bundle

• Static cost: a single forwardRef component + two small pure helpers (extractStyleProps, buildPseudoClassName) + the existing engine sxToStyle / cv / prefixClasses / motionPresets.
• Motion runtime is only pulled in when animation is set on at least one render — and even then useReducedMotion() short-circuits to a plain element.

Do / Don't

• Do reach for <Div> instead of <div className="…"> when you'd otherwise inline more than one or two Tailwind utilities.
• Do use <Div centered> for the centered-spinner / centered-empty-state pattern.
• Do prefer <Div actLike="button"> over <Div role="button" tabIndex={0}> — the real element gets you keyboard activation + focus for free.
• Don't use <Div> as a substitute for a real DS component when one exists (<Button>, <Card>, <Stack>, <Field>, …). Those carry richer semantics, recipes, and a11y.
• Don't pass responsive objects to the inline-style shorthand props — they expect scalars in v1. For responsive layout, reach for hideOn / displayOn / className.
• Don't combine as / actLike with asChild — pick one. A dev warning fires in development if both are set.