Layout

Espalier provides layout primitives that handle page-level structure and component-level alignment consistently. The core principle is that layout is the responsibility of the parent, not the child: structural components orchestrate where content lives; content components remain unaware of their position in the page.

Page layout with esp-page

esp-page is the primary page scaffolding component. It provides three named layout kinds:

<esp-page kind="narrow">
  <esp-header slot="header">...</esp-header>
  <!-- main content -->
</esp-page>

On viewports wider than a kind's cap, use align (start, center, or end) to place the content surface within the page and turn the surplus width into a styleable canvas. See Page Alignment, Canvas, and Surface.

Use header-position="sticky" when the header should stick after it reaches the viewport top, or header-position="fixed" when the header should remain pinned and the page should reserve header-height space for main content and drawers:

<esp-page header-position="fixed">
  <esp-header slot="header" scroll-behavior="compact elevate">
    ...
  </esp-header>
</esp-page>

CSS Grid and Flexbox

Espalier uses a strict division of labor between layout engines:

• CSS Grid — for two-dimensional page scaffolding: header/content/sidebar structures, named grid areas, multi-column placements.
• Flexbox — for one-dimensional content alignment within components: toolbars, button groups, icon-label pairs, row content.

When composing with Espalier components, follow the same division in your own layout code. If you find yourself reaching for a grid inside a flex container to place items in two dimensions, reconsider whether a grid container belongs at that level instead.

Responsiveness without breakpoints

Espalier components prefer intrinsic layout over media query breakpoints. Components adapt to the space they actually occupy using:

• Container Queries — layout changes triggered by the component's container width, not the viewport width.
• Intrinsic sizing — auto-fit, minmax(), and fr units let grid and flex layouts reflow naturally.
• Fluid type and spacing — the --esp-type-* and --esp-size-* tokens scale continuously, removing the most common need for breakpoint-driven style changes.

Viewport @media queries are reserved for genuinely viewport-level decisions like toggling a mobile navigation drawer or responding to prefers-color-scheme.

Layout guides

• Macro Structures — building page shells with esp-page and named slots.
• Page Alignment, Canvas, and Surface — aligning the content surface, styling the canvas gutters, and lining up header content on wide viewports.
• Micro Alignment — Flexbox patterns for component internals.
• Container Queries — context-aware component responsiveness.