Styling Reference: CSS Custom Properties

Espalier exposes CSS custom properties at three different levels:

1. Theme outputs on <esp-root> such as --esp-color-text and --esp-size-padding.
2. Shared system hooks such as overlay and field tokens used across multiple components.
3. Component-level properties such as --esp-tooltip-max-width or --esp-progress-height.

This page is the canonical reference for those properties. For application-level guidance on when to use theme fields, component props, or variant, see Using Tokens & Variants Coherently.

Tokens prefixed with --_esp- are private implementation details. They are intentionally excluded from this reference and should not be used by applications or treated as stable public API.

Properties are organized into three groups:

1. Theme-level — computed by <esp-root> and inherited by every component in the tree.
2. Shared hooks — optional cross-component properties used by field-like controls and overlays.
3. Component-level — scoped to individual components for targeted overrides.

To customize a property, set it in your own CSS. Theme-level properties cascade naturally; component-level properties can be set on the component's tag or any ancestor:

/* Override dialog overlay opacity for a specific dialog */
.my-dialog {
  --esp-dialog-bg-opacity: 0.8;
}

When you want a system-wide change, prefer updating the light-theme or dark-theme passed to <esp-root> instead of overriding many emitted --esp-color-* or --esp-size-* outputs one by one.

General: Theme-Level Properties

These properties are computed and set by <esp-root> based on the active theme. They cascade to all descendant components and form the root styling contract for Espalier.

Scheme Indicator

Variant Colors

Geometric color-theory variants derived from the seed color by rotating the hue angle. Every variant is gamut-mapped to sRGB.

Semantic Colors

Derived from variant colors and lightness ramp positions. Text colors are enforced against APCA contrast targets to guarantee legibility.

Surfaces & Layers

Text & Headings

Links

Actions & Inputs

Borders & Shadows

Lightness Ramp

Raw lightness values (as percentages) for each ramp position. These control the perceptual brightness of the semantic color tokens above.

Type Scale

Fluid clamp() values that interpolate between a minimum and maximum viewport width. Seven steps from tiny to huge, using a modular ratio (default: Major Third, 1.25).

Spacing Scale

Fluid clamp() values for spacing. Seven individual steps plus six cross-step fluid pairs that interpolate between adjacent steps for more dramatic scaling.

Individual Steps

Cross-Step Fluid Pairs

These pair the minimum of a lower step with the maximum of the next higher step, producing a wider scaling range across viewport sizes.

Aliases

Font Families

Font Weights

Background Images

Optional decorative background images applied to page and box surfaces.

Shared Hooks

These properties are not specific to a single component, but they are still part of the styling surface used across Espalier.

Field Hooks

Field-like controls that inherit EspalierElementBase use these properties internally for consistent input behavior.

Overlay Hooks

These properties provide shared defaults for overlay components. esp-dialog and esp-lightbox fall back to them before falling back to root semantic colors.

Component-Level Properties

These properties are scoped to individual components. Set them on the component element or any ancestor to override the default styling.

esp-box

esp-button

esp-button-group

esp-page

esp-header

esp-header-button

esp-menu-item

esp-burger

esp-vertical-menu

esp-vertical-menu-group

esp-vertical-menu-item

esp-slider

esp-switch

esp-tab-group

esp-toaster

esp-tooltip

esp-progress

esp-checkbox

esp-radio-button

esp-dialog

esp-lightbox

esp-form-item

esp-details

esp-details-group

esp-info

esp-breadcrumbs

esp-breadcrumb

esp-image

esp-image-upload

esp-image-preview

esp-picker-menu

esp-color-picker

esp-grid

esp-repeater

esp-search

VS Code Integration

Espalier ships a CSS Custom Data file that gives VS Code autocomplete and hover documentation for every --esp-* property.

Setup

Add the following to your project's .vscode/settings.json:

{
  "css.customData": [
    "./node_modules/@taprootio/taproot-controls/espalier.css-data.json"
  ]
}

Once configured, VS Code will:

• Autocomplete --esp-* property names as you type in CSS, SCSS, and HTML style attributes.
• Show descriptions on hover, matching the documentation on this page.

This works with VS Code's built-in CSS Language Service — no additional extensions are required.

If you use the CSS Variable Autocomplete extension, it will also pick up the custom data file automatically.