Introducing DtBox: The Surface and Spacing Primitive

TLDR #

• New component DtBox handles surface styling: padding, surface, border, shadow, borderRadius, sizing, simple positioning, overflow, and scrollbar.
• Completes the primitive triad: DtBox (container) + DtText (typography) + DtStack (layout).
• Replaces manual composition of CSS utility classes like class="d-bgc-primary d-bc-default d-baw-100 d-bar-200 d-p-200 d-bs-sm".
• All prop values are token-constrained and validated — invalid values produce console warnings, not silent failures.
• Component docs • Storybook

The Primitive Triad #

Dialtone's UI primitives now cover three distinct concerns:

• DtBox: what the container is: surface color, border, padding, shadow, sizing, positioning
• DtText: what the content looks like: font family, size, weight, color
• DtStack: how children are arranged: flex direction, gap, alignment

Demo #

Each primitive owns its domain. In the example below, DtBox provides the visual container (surface, border, shadow, padding). DtStack arranges the children vertically with consistent gap. DtText renders the typography.

<dt-box padding="300" surface="primary" border-width="100" border-radius="400" shadow="card">
  <dt-stack gap="100">
    <dt-text as="h3" kind="headline" size="md">Card title</dt-text>
    <dt-text kind="body" size="sm">Supporting text that describes the card content.</dt-text>
  </dt-stack>
</dt-box>

Why DtBox Over CSS Utilities? #

Building a custom container previously might look like this:

<div class="d-bgc-primary d-bc-default d-baw-100 d-bar-200 d-p-200 d-bs-sm">
  Content
</div>

Six CSS utility classes from six different naming conventions (d-bgc-*, d-bc-*, d-baw-*, d-bar-*, d-p-*, d-bs-*). Each requires knowing the prefix, the token scale, and the exact naming pattern. A wrong prefix (e.g., d-bg-primary instead of d-bgc-primary) silently fails.

With DtBox:

<dt-box padding="200" surface="primary" border-width="100" border-radius="200" shadow="small">
  Content
</dt-box>

The prop names are self-documenting. The values are validated: pass surface="foo" and you get a console warning instead of silent failure. IDE autocomplete works. The Dialtone MCP server also returns the full prop API in one search, making DtBox easier for AI-assisted development tools to work with.

Prop Tiers #

Scrollbar Integration #

The scrollbar prop integrates the v-dt-scrollbar directive as a first-class feature.

<dt-box padding="100" border-width="100" border-radius="300" scrollbar="always" block-size="200" inline-size="200">
  <dt-stack gap="100" as="ul">
    <dt-text as="li" kind="body" :size="200" v-for="i in 20" :key="i">Item {{ i }}</dt-text>
  </dt-stack>
</dt-box>

Composing With the Triad #

Here's a more realistic composition showing how the three primitives of DtBox, DtStack, and DtText work together while each handling exactly one concern:

<dt-box
  as="aside"
  padding="200"
  surface="primary"
  border-width="100"
  border-radius="400"
>
  <dt-stack gap="200">
    <dt-stack direction="row" justify="space-between" align="baseline">
      <dt-text as="h2" kind="headline" :size="400">Title</dt-text>
      <dt-button size="200">Action</dt-button>
    </dt-stack>
    <dt-stack direction="row" gap="200">
      <dt-box class="d-fl1" padding="200" surface="secondary" border-width="100" border-color="subtle" border-radius="300">
        <dt-text as="p" kind="body" :size="200" tone="muted">Box 1</dt-text>
      </dt-box>
      <dt-box class="d-fl1" padding="200" surface="secondary" border-width="100" border-color="subtle" border-radius="300">
        <dt-text as="p" kind="body" :size="200" tone="muted">Box 2</dt-text>
      </dt-box>
      <dt-box class="d-fl1" padding="200" surface="secondary" border-width="100" border-color="subtle" border-radius="300">
        <dt-text as="p" kind="body" :size="200" tone="muted">Box 3</dt-text>
      </dt-box>
    </dt-stack>
  </dt-stack>
</dt-box>

• DtStack handles the arrangement of elements.
• DtBox provides the card surface (as="aside" for semantics, padding, border, radius).
• Nested DtBox instances provide the secondary surfaces.
• DtText handles all typography.
• class="d-fl1" is the utility escape hatch for flex-grow, a property DtBox intentionally doesn't provide.

What DtBox Does NOT Do #

• Layout: No direction, gap, justify, or align. Use DtStack.
• Typography: No font, size, tone, or weight. Use DtText.
• Flex child: No flexGrow, flexShrink, or alignSelf. Use CSS Utility classes.
• Complex positioning: No responsive, calc, arbitrary, or CSS-wide reset offsets. Use CSS Utility classes.

These boundaries are intentional as DtBox is a container primitive, not a general-purpose styled element. The class attribute remains the escape hatch for anything outside its prop surface.

See the full component documentation for all prop values, demos, and usage guidance.