Section
import "@taprootio/espalier/section";
<esp-section>
A full-bleed page band with a centered content well — the natural host for a theme zone.
esp-section paints the local --esp-color-background edge to edge
and centers its content in a capped well. It carries no card identity:
no raised surface, no border radius, no shadow. Give it a context
(see theme overview) and
the band renders the zone's complete token table with nothing to
neutralize:
Inside esp-page kind="site" sections stack full-width and their
wells share the page's --esp-page-well-max-width, so section
content, the header, and the footer all align on one column. Outside
a page the well defaults to the same width and the band fills
whatever container it is given.
The vertical rhythm defaults to the theme's fluid --esp-size-section
step. For edge-to-edge content (a full-bleed hero image) clear both
the well cap and the inline breathing room —
--esp-section-max-width: none; --esp-section-padding-inline: 0; —
and drop --esp-section-padding-block too when the media should
meet the band's edges; the band's zone behavior is unaffected.
A section may also tint one raster alpha mask behind its content.
The component owns clipping, no-repeat mask behavior, stacking, and
interaction isolation; consumers opt in with the decoration
attribute and supply only the image, semantic tint, position, size, and
opacity:
Without decoration the section renders no decorative layer at all, and
the --esp-section-decoration-* hooks have no effect. The attribute is
what keeps an undecorated band free of painted planes: accessibility
auditors such as axe-core and Lighthouse do not model mask-image, so a
tinted plane hidden only by a mask is read as the background behind every
word in the section. Set it together with the image, never on its own. A
decorated band is audited as though the tint covered it everywhere, so
text that passes an audit also reads where it crosses the mark.
CSS image values are trusted stylesheet input. Products that accept image references from documents or users must enforce their own asset ownership and URL policy before mapping a value to this hook.
Slots
<esp-section> has a slot:
Default
The section's content, centered in the well.
Attributes
<esp-section> has the following attributes:
decoration
decoration has a default value of false.
Whether the section paints its decorative mask plane. Set it whenever
--esp-section-decoration-image names an image; without it the
section renders no decorative layer and the decoration hooks are
inert.
surface-layer
surface-layer has a default value of undefined.
Declares the painted surface depth. Fields use the next local layer, capped at layer 4.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-section> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
CSS Parts
<esp-section> has the following CSS parts:
section
The full-bleed band.
well
The centered content well.
CSS Properties
<esp-section> has the following CSS properties:
--esp-section-background
The band's background. Defaults to the local --esp-color-background, which inside a context zone is the zone's canvas.
--esp-section-max-width
The content well's cap. Defaults to var(--esp-page-well-max-width, 72rem); none lets content span the band.
--esp-section-padding-block
Vertical rhythm above and below the well. Defaults to var(--esp-size-section).
--esp-section-padding-inline
Horizontal breathing room inside the band at narrow viewports. Defaults to var(--esp-size-medium).
--esp-section-decoration-image
Raster alpha mask painted behind the well when decoration is set. Defaults to none.
--esp-section-decoration-color
Semantic tint applied through the mask. Defaults to the local --esp-color-headings.
--esp-section-decoration-position
Mask position, including responsive or bleeding values. Defaults to center.
--esp-section-decoration-size
Mask size. Defaults to contain.
--esp-section-decoration-opacity
Decoration opacity from 0 through 1. Defaults to 1.
--esp-field-background
Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at var(--esp-color-layer-4), or var(--esp-color-layer-2) without a declared surface. An explicit override wins.
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).