layout-canvas

Elevated surface container with background, radius, shadow, and padding. Use the data-canvas attribute on semantic elements or the layout-canvas wrapper element.

Attributes

Attribute Values Default Description
data-canvas (empty), flush, elevated (empty) Applies canvas surface styling. Value sets the variant.
data-variant flush, elevated - Variant for the <layout-canvas> element form.
data-layout-max narrow, content, wide, prose - Maximum inline size constraint.
data-layout-padding none, s, m, l, xl l Override default padding.
data-canvas-depth 1, 2 - Ghost card stacking effect (not available on flush).

How It Works

data-canvas is an attribute you add to any semantic element to give it an elevated surface — background, border-radius, box-shadow, and padding. The <layout-canvas> custom element is an alternative wrapper for when you need a non-semantic container.

Both forms share the same CSS and consume the same --canvas-* design tokens used by data-backdrop, so theme overrides apply to both systems.

Attribute Form (Preferred)

Add data-canvas directly to a semantic element. No wrapper needed.

<article data-canvas> <h2>My Article</h2> <p>Content with elevated surface styling.</p> </article>

Element Form

Use <layout-canvas> when you need a non-semantic wrapper around multiple children.

<layout-canvas> <header>Page Header</header> <main> <p>Main content area wrapped in a canvas surface.</p> </main> </layout-canvas>

Variants

Flush

No border radius or shadow. Edge-to-edge surface.

<section data-canvas="flush"> <h2>Flush Canvas</h2> <p>No border radius or shadow. Edge-to-edge surface.</p> </section>

Elevated

Larger radius and dramatic shadow for emphasis.

<section data-canvas="elevated"> <h2>Elevated Canvas</h2> <p>Larger radius and dramatic shadow for emphasis.</p> </section>

Width Constraints

Use data-layout-max to constrain the canvas width. It auto-centers with margin-inline: auto.

<article data-canvas data-layout-max="narrow"> <h2>Narrow Canvas</h2> <p>Constrained to 45rem max width, centered on the page.</p> </article> <article data-canvas data-layout-max="content"> <h2>Content Width</h2> <p>Constrained to 60rem max width.</p> </article>

Nested Canvases

Nested canvases automatically use --color-surface-raised for visual hierarchy.

<article data-canvas> <h2>Outer Canvas</h2> <p>Primary surface background.</p> <aside data-canvas> <h3>Nested Canvas</h3> <p>Automatically uses raised surface color for hierarchy.</p> </aside> </article>

Ghost Card Depth

Add stacked-paper shadows beneath the canvas for a layered effect. Not available on the flush variant.

<article data-canvas data-canvas-depth="1"> <h2>Single Ghost Card</h2> <p>One stacked paper shadow beneath the canvas.</p> </article> <article data-canvas data-canvas-depth="2"> <h2>Double Ghost Cards</h2> <p>Two stacked paper shadows for extra depth.</p> </article>

Multiple Canvases

Unlike data-backdrop which styles body-level regions implicitly, data-canvas works on any element — so you can have multiple independent canvases on the same page.

<section data-layout="grid" data-layout-min="20rem"> <article data-canvas> <h3>Canvas A</h3> <p>Independent canvas region.</p> </article> <aside data-canvas="elevated"> <h3>Canvas B</h3> <p>Elevated variant alongside.</p> </aside> </section>

Relationship to data-backdrop

data-canvas and data-backdrop are complementary:

  • data-backdrop styles body > main/header/footer/nav/aside implicitly
  • data-canvas is for explicit, per-element canvas surfaces
  • Both consume the same --canvas-* tokens
  • A page can use both simultaneously

Mobile Behavior

At <640px, all canvases automatically go flush — no border radius, no shadow, reduced padding. This matches data-backdrop mobile behavior.

Related