Espalier Guides

Start with the platform contract

Install Espalier with Lit, place an <esp-root> around the application, and import only the components the application uses. The component references in this documentation describe each element's properties, attributes, events, slots, CSS parts, and theme properties from the repository's generated Custom Elements Manifest.

Design-system foundations

Espalier's guides cover perceptual OKLCH color, APCA contrast, fluid typography, modular spacing, intrinsic layout, container queries, forms, icons, fonts, theming, and the public token hierarchy. Prefer those shared primitives over one-off application values so component composition remains coherent. The intent attribute carries an element's status meaning, and theme-defined context zones re-tint a whole subtree coherently; prefer them to manually overriding several unrelated color tokens.

Working with forms

Use <esp-form> as the native form wrapper, place each control in an <esp-form-item> for its label and validation message, and give submitted controls a name directly or through the form item's field-name. Espalier's form-associated controls participate in browser submission, reset, validity, and accessibility behavior through ElementInternals.

Keep layout separate from the form contract by composing fields in an <esp-box>, CSS grid, or application-owned layout. Add use-fetch only when the form should intercept submission and emit Espalier's typed submission events instead of using ordinary browser navigation.

Accessible automation

Controls expose browser-native roles, names, values, and events. Automation should locate controls by role or label and activate them through real pointer or keyboard input. Shadow-root selectors and synthetic host .click() calls are outside the supported consumer contract.

The complete authored guides, interactive examples, and nested topic pages remain available on the independent Espalier Guides site.