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.

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.