Preview
Usage #
<dt-box> ... </dt-box>
DtBox complements DtText (typography) and DtStack (flex layout) to form Dialtone's primitive triad:
- DtBox: what the container is (
surface,border,padding,sizing) - DtText: what the content looks like (
font,size,color) - DtStack: how children are arranged (
direction,gap,alignment)
Guidance #
- Use DtBox in place of composing multiple surface utility classes (e.g.,
d-bgc-*,d-bc-*,d-bar*,d-bs-*,d-p-*). - Use the
asprop to render semantic HTML elements (section,nav,article,header, etc.) for accessibility. - DtBox is a passive container — it does not handle layout (use DtStack) or typography (use DtText).
- Compose DtBox + DtStack + DtText together for structured UI surface containers.
Do
- Use DtBox for card surfaces, info panels, content regions, and any container that needs surface styling.
- Compose with DtStack for layout:
<dt-box><dt-stack>...</dt-stack></dt-box>. - Use the
asprop for semantic HTML:<dt-box as="nav">,<dt-box as="section">. - Use
classfor one-off styling outside DtBox's prop surface (e.g.,class="d-ps-sticky").
Don’t
- Don't use DtBox for flex layout — use DtStack for direction, gap, alignment.
- Don't use DtBox for typography — use DtText for font, size, tone.
- Don't use utility classes for properties DtBox already handles (e.g., avoid
class="d-bgc-primary"whensurface="primary"exists). - Don't nest DtBox deeply when a dedicated component (DtCard, DtNotice) better fits the pattern.
Surface #
Background surface color mapped to --dt-color-surface-* tokens.
<dt-box surface="{surfaceColor}">...</dt-box>
Semantic surfaces #
<dt-box surface="{surfaceColor}">...</dt-box>
Padding #
Spacing token scale values for internal whitespace. The padding cascade resolves specific sides over axis shorthands over the all-sides shorthand.
<dt-box padding="{padding}">...</dt-box>
Directional padding #
Override specific sides. The cascade resolves: paddingBlockStart > paddingBlock > padding.
<dt-box padding="200" surface="moderate" border-radius="300">All sides: 200</dt-box> <dt-box padding="200" padding-inline="400" surface="moderate" border-radius="300">Inline override: 400</dt-box> <dt-box padding="200" padding-block-start="400" surface="moderate" border-radius="300">Block-start override: 400</dt-box>
Border #
Border width #
No visible border until a border-width is set. Uniform width applies to all sides.
<dt-box padding="200" surface="moderate" border-radius="300">No border</dt-box> <dt-box padding="200" surface="moderate" border-width="100" border-radius="300">100</dt-box> <dt-box padding="200" surface="moderate" border-width="200" border-radius="300">200</dt-box>
Directional border width #
Show borders on specific sides only.
<dt-box padding="200" surface="moderate" border-width-block-end="100">Bottom only</dt-box> <dt-box padding="200" surface="moderate" border-width-inline-start="200" border-color="critical">Start critical</dt-box> <dt-box padding="200" surface="moderate" border-width-block="100" border-width-inline="0">Block only</dt-box>
Border color #
Defaults to 'default' (--dt-color-border-default). Only visible when a border-width is set.
<dt-box padding="200" surface="moderate" border-width="100" border-radius="300">default</dt-box> <dt-box padding="200" surface="moderate" border-width="100" border-color="subtle" border-radius="300">subtle</dt-box> <dt-box padding="200" surface="moderate" border-width="100" border-color="critical" border-radius="300">critical</dt-box> <dt-box padding="200" surface="moderate" border-width="100" border-color="positive" border-radius="300">positive</dt-box>
Border radius #
<dt-box padding="200" surface="moderate" border-radius="0">0</dt-box> <dt-box padding="200" surface="moderate" border-radius="200">200</dt-box> <dt-box padding="200" surface="moderate" border-radius="400">400</dt-box> <dt-box padding="200" surface="moderate" border-radius="pill" inline-size="200" class="d-ta-center">pill</dt-box> <dt-box surface="moderate" border-radius="circle" inline-size="100" block-size="100" class="d-plc-center d-ta-center">circle</dt-box>
Shadow #
<dt-box padding="200" surface="moderate" border-radius="300" shadow="small">small</dt-box> <dt-box padding="200" surface="moderate" border-radius="300" shadow="medium">medium</dt-box> <dt-box padding="200" surface="moderate" border-radius="300" shadow="large">large</dt-box> <dt-box padding="200" surface="moderate" border-radius="300" shadow="card">card</dt-box>
Sizing #
Maps to Dialtone's layout token scale (--dt-layout-*). Supports both fixed values and percentage tokens.
<dt-box padding="200" surface="moderate" border-radius="300" inline-size="300">300 (192px)</dt-box> <dt-box padding="200" surface="moderate" border-radius="300" inline-size="500">500 (320px)</dt-box> <dt-box padding="200" surface="moderate" border-radius="300" inline-size="50p">50p</dt-box>
Overflow #
<dt-box surface="moderate" border-radius="300" overflow="hidden" inline-size="500" block-size="200" padding="200" > Tall content clipped by <dt-text kind="code" size="200">overflow="hidden"</dt-text>. Nemo rem ullam culpa ut laudantium repellat unde. Consequuntur cupiditate voluptatem velit rerum doloremque voluptatum commodi vitae vel inventore iusto ducimus iure? Ex fugit quae iste perferendis eaque! Alias in reiciendis suscipit facere incidunt repellendus! Voluptatibus iste nesciunt numquam consectetur suscipit unde atque tempora saepe est illum quaerat sit natus mollitia excepturi? Repellendus explicabo deserunt ipsam sint esse ab delectus beatae eligendi velit libero quasi culpa ut tenetur sunt corrupti iure suscipit magni fuga blanditiis nihil incidunt! Mollitia voluptas sed temporibus quasi. </dt-box>
Scrollbar #
Integrates the v-dt-scrollbar directive. An inner viewport wrapper is inserted automatically, solving the Custom Scrollbar's single-child constraint.
<dt-box padding="200" border-width="100" border-radius="300" scrollbar="always" block-size="300" > <dt-stack gap="100"> <dt-text v-for="i in 20" :key="i" kind="body" size="sm">Scrollable item {{ i }}</dt-text> </dt-stack> </dt-box>
Render as #
Use the as prop to render semantic HTML elements for accessibility.
<dt-box as="section" padding="200" surface="moderate" border-radius="300">as="section"</dt-box> <dt-box as="nav" padding="200" surface="moderate" border-radius="300">as="nav"</dt-box> <dt-box as="article" padding="200" surface="moderate" border-radius="300">as="article"</dt-box>
Examples #
Card #
<dt-box padding="300" surface="primary" border-width="100" border-radius="400" shadow="card" > <dt-stack gap="200"> <dt-text as="h3" kind="headline" size="md">Card title</dt-text> <dt-text kind="body" size="sm">Card body content with supporting text.</dt-text> </dt-stack> </dt-box>
Composed layout #
<dt-box 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" align="center" 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" align="center" 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" align="center" tone="muted">Box 3</dt-text> </dt-box> </dt-stack> </dt-stack> </dt-box>
Accessibility #
- Use the
asprop to render appropriate semantic elements —navfor navigation,sectionfor thematic content,articlefor self-contained content. - DtBox does not add any implicit ARIA role. The rendered element's native semantics determine how screen readers interpret it.
- When using
as="nav"oras="section", consider addingaria-labelto provide an accessible name for the landmark region. - The scrollbar integration preserves native keyboard scrolling behavior.
Vue API #
import { DtBox } from '@dialpad/dialtone-vue';Slots
Name
|
Type
|
|---|---|
default | Slot for main content |
Props
Name
|
Default
|
Type
|
|---|---|---|
as | 'div' |
"div"
|
"span"
|
"section"
|
"article"
|
"aside"
|
"main"
|
"header"
|
"footer"
|
"nav"
|
"ul"
|
"ol"
|
"li"
|
"fieldset"
|
"form"
|
"figure"
HTML element to render as. |
blockSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Block size (aka height). Maps to --dt-layout-* tokens. | |
borderColor | 'default' |
"transparent"
|
"subtle"
|
"default"
|
"moderate"
|
"bold"
|
"positive"
|
"positive-subtle"
|
"positive-strong"
|
"warning"
|
"warning-subtle"
|
"warning-strong"
|
"critical"
|
"critical-subtle"
|
"critical-strong"
|
"info"
|
"info-subtle"
|
"info-strong"
|
"focus"
|
"brand"
|
"brand-subtle"
|
"brand-strong"
Border color. Maps to --dt-color-border-* tokens.
Defaults to 'default'. Visible when any border-width prop is set. |
borderRadius |
"0"
|
"100"
|
"200"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"pill"
|
"circle"
Border radius. Maps to --dt-size-radius-* tokens. | |
borderWidth |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on all sides. Maps to --dt-size-border-* tokens. | |
borderWidthBlock |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the block axis (aka top/bottom).
Overrides | |
borderWidthBlockEnd |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the block-end side (aka bottom).
Overrides | |
borderWidthBlockStart |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the block-start side (aka top).
Overrides | |
borderWidthInline |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the inline axis (aka left/right).
Overrides | |
borderWidthInlineEnd |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the inline-end side (aka right).
Overrides | |
borderWidthInlineStart |
"0"
|
"50"
|
"100"
|
"150"
|
"200"
|
"300"
|
"400"
Border width on the inline-start side (aka left).
Overrides | |
inlineSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Inline size (aka width). Maps to --dt-layout-* tokens. | |
maxBlockSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Maximum block size. Maps to --dt-layout-* tokens. | |
maxInlineSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Maximum inline size. Maps to --dt-layout-* tokens. | |
minBlockSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Minimum block size. Maps to --dt-layout-* tokens. | |
minInlineSize |
"0"
|
"1px"
|
"2px"
|
"8px"
|
"25"
|
"20px"
|
"24px"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
|
"850"
|
"900"
|
"950"
|
"1000"
|
"1050"
|
"1100"
|
"1150"
|
"1200"
|
"1250"
|
"1300"
|
"1350"
|
"1400"
|
"1450"
|
"1500"
|
"1550"
|
"1600"
|
"10p"
|
"20p"
|
"25p"
|
"30p"
|
"33p"
|
"40p"
|
"50p"
|
"60p"
|
"66p"
|
"70p"
|
"75p"
|
"80p"
|
"90p"
|
"95p"
|
"100p"
Minimum inline size. Maps to --dt-layout-* tokens. | |
overflow |
"hidden"
|
"scroll"
|
"auto"
|
"clip"
|
"visible"
Overflow behavior. | |
padding |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on all sides. Accepts spacing token scale values. | |
paddingBlock |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the block axis (aka top/bottom).
Overrides | |
paddingBlockEnd |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the block-end side (aka bottom).
Overrides | |
paddingBlockStart |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the block-start side (aka top).
Overrides | |
paddingInline |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the inline axis (aka left/right).
Overrides | |
paddingInlineEnd |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the inline-end side (aka right).
Overrides | |
paddingInlineStart |
"0"
|
"1"
|
"25"
|
"50"
|
"75"
|
"100"
|
"125"
|
"150"
|
"175"
|
"200"
|
"250"
|
"300"
|
"350"
|
"400"
|
"450"
|
"500"
|
"525"
|
"550"
|
"600"
|
"650"
|
"700"
|
"750"
|
"800"
Padding on the inline-start side (aka left).
Overrides | |
scrollbar |
"leave"
|
"scroll"
|
"move"
|
"always"
Custom scrollbar via OverlayScrollbars. When set, an inner viewport
wrapper (.d-box__scrollbar-content) is inserted automatically. | |
scrollbarContentClass | '' | string|object|array Additional CSS classes applied to the scrollbar content wrapper element.
Only applies when scrollbar prop is set. |
shadow |
"small"
|
"medium"
|
"large"
|
"extra-large"
|
"card"
Box shadow. Maps to --dt-shadow-* tokens. | |
surface |
"primary"
|
"primary-opaque"
|
"secondary"
|
"secondary-opaque"
|
"moderate"
|
"moderate-opaque"
|
"bold"
|
"bold-opaque"
|
"strong"
|
"strong-opaque"
|
"contrast"
|
"contrast-opaque"
|
"backdrop"
|
"overlay"
|
"brand"
|
"brand-opaque"
|
"brand-subtle"
|
"brand-subtle-opaque"
|
"brand-strong"
|
"info"
|
"info-opaque"
|
"info-subtle"
|
"info-subtle-opaque"
|
"info-strong"
|
"positive"
|
"positive-opaque"
|
"positive-subtle"
|
"positive-subtle-opaque"
|
"positive-strong"
|
"warning"
|
"warning-opaque"
|
"warning-subtle"
|
"warning-subtle-opaque"
|
"warning-strong"
|
"critical"
|
"critical-opaque"
|
"critical-subtle"
|
"critical-subtle-opaque"
|
"critical-strong"
Background surface color. Maps to --dt-color-surface-* tokens. |
Classes #
Class
|
Applies to
|
Description
|
|---|