Grid Identity System

A three-tier system where semantic HTML elements automatically register their grid areas. Pure separation of concerns: HTML declares structure, CSS assigns layout. See also full documentation.

Zen Garden Architecture

This system implements the CSS Zen Garden principle: the same semantic HTML transforms through pure CSS. No wrapper elements, no layout components - just <header>, <nav>, <main>, <aside>, <footer>.

Layout Template Tokens

Grid templates are stored as CSS custom properties, making them reusable and easy to customize.

:root {
  --tpl-stack:
    "body-header" auto
    "body-nav" auto
    "body-main" 1fr
    "body-footer" auto
    / 1fr;

  --tpl-sidebar-left:
    "body-header body-header" auto
    "body-nav    body-main"   1fr
    "body-footer body-footer" auto
    / var(--_sidebar-width) 1fr;

  --tpl-holy-grail:
    "body-header body-header body-header" auto
    "body-nav    body-main   body-aside"  1fr
    "body-footer body-footer body-footer" auto
    / var(--_sidebar-width) 1fr var(--_sidebar-width);
}

Grid Identity Layer

Semantic elements auto-register their grid areas based on DOM position. No classes needed.

/* Semantic elements auto-register */
body[data-layout] > header { grid-area: body-header; }
body[data-layout] > nav    { grid-area: body-nav; }
body[data-layout] > main   { grid-area: body-main; }
body[data-layout] > aside  { grid-area: body-aside; }
body[data-layout] > footer { grid-area: body-footer; }

Body Sidebar Left Layout

Two-column layout with navigation on the left. Apply data-layout="body-sidebar-left" to the body.

body-sidebar-left

Header

Main Content Area

<body data-layout="body-sidebar-left">
  <header>Header</header>
  <nav>Navigation links</nav>
  <main>Main Content Area</main>
  <footer>Footer</footer>
</body>

Body Holy Grail Layout

Classic three-column layout with nav, main, and aside.

body-holy-grail

Header

Main Content

<body data-layout="body-holy-grail">
  <header>Header</header>
  <nav>Navigation</nav>
  <main>Main Content</main>
  <aside>Sidebar content</aside>
  <footer>Footer</footer>
</body>

Content-Aware Layouts (:has() Powered)

The layout automatically adapts when elements are present or absent. CSS reads HTML structure and responds accordingly.

Holy Grail without Aside

When <aside> is absent, the layout adapts to two columns automatically.

:has() adaptation - no aside

Header

Main Content (aside absent - layout adapts!)

<body data-layout="body-holy-grail">
  <header>Header</header>
  <nav>Navigation</nav>
  <main>Main Content</main>
  <!-- No aside - layout adapts automatically via :has() -->
  <footer>Footer</footer>
</body>

/* CSS :has() rule */
body[data-layout="body-holy-grail"]:not(:has(> aside)) {
  grid-template:
    "body-header body-header" auto
    "body-nav    body-main"   1fr
    "body-footer body-footer" auto
    / var(--_sidebar-width) 1fr;
}

Body Dashboard Layout

Admin panel style with sticky header and sidebar navigation.

body-dashboard

Dashboard Header

Dashboard Content

<body data-layout="body-dashboard">
  <header>Dashboard Header</header>
  <nav>
    <a href="#">Overview</a>
    <a href="#">Users</a>
    ...
  </nav>
  <main>Dashboard Content</main>
</body>

Body Article Layout

Centered content layout optimized for reading. Content is constrained to a readable width.

body-article

Site Header

Article Title

This is article content that is centered on the page with a maximum width for optimal readability. Long lines of text are harder to read because the eye has difficulty tracking from the end of one line to the beginning of the next.

The content is constrained to approximately 65 characters per line (65ch), which is the recommended measure for comfortable reading.

<body data-layout="body-article">
  <header>Site Header</header>
  <main>
    <article>
      <h1>Article Title</h1>
      <p>Article content...</p>
    </article>
  </main>
  <footer>Footer</footer>
</body>

Layout Utilities

Additional data attributes for fine-tuning layouts.

Sticky Header

<header data-layout-sticky>Stays at top when scrolling</header>

/* CSS */
body[data-layout] > header[data-layout-sticky] {
  position: sticky;
  top: 0;
  z-index: var(--z-sticky, 100);
}

Sticky Sidebar

<nav data-layout-sticky>Sticky navigation</nav>

/* CSS */
body[data-layout] > nav[data-layout-sticky] {
  position: sticky;
  top: 0;
  align-self: start;
  max-height: 100dvh;
  overflow-y: auto;
}

Sidebar States

<!-- Collapsed sidebar -->
<body data-layout="body-sidebar-left" data-sidebar="collapsed">

<!-- Hidden sidebar -->
<body data-layout="body-sidebar-left" data-sidebar="hidden">

/* CSS */
body[data-layout][data-sidebar="collapsed"] {
  --_sidebar-width: var(--_sidebar-collapsed); /* 64px */
}

body[data-layout][data-sidebar="hidden"] > nav {
  display: none;
}

Full-Bleed Elements

<!-- Element spans all columns -->
<div data-layout-bleed>Full-width banner</div>

/* CSS */
body[data-layout] > [data-layout-bleed] {
  grid-column: 1 / -1;
}

Before vs After

Compare the old wrapper-based approach with the new semantic approach.

Before (Wrapper Elements)

<layout-sidebar data-layout-gap="m">
  <layout-stack>
    <nav>...</nav>
  </layout-stack>
  <layout-stack>
    <main>...</main>
  </layout-stack>
</layout-sidebar>

After (Grid Identity)

<body data-layout="body-sidebar-left" data-layout-gap="m">
  <header>Site Header</header>
  <nav>Navigation</nav>
  <main>Content</main>
  <footer>Footer</footer>
</body>

Available Body Layouts

Layout	Template Token	Description
`body-stack`	`--tpl-stack`	Single column, mobile-first
`body-sidebar-left`	`--tpl-sidebar-left`	Two-column with left nav
`body-sidebar-right`	`--tpl-sidebar-right`	Two-column with right sidebar
`body-holy-grail`	`--tpl-holy-grail`	Three-column classic layout
`body-app-shell`	`--tpl-app-shell`	Vertical nav bar
`body-dashboard`	`--tpl-dashboard`	Admin panel style
`body-article`	`--tpl-article`	Centered reading layout
`body-landing`	`--tpl-landing`	Marketing page sections

Component Regions

data-layout="regions" creates a header / content / footer grid on any element. Semantic children auto-place to named areas.

data-layout="regions"

Performance

Optimized for speed.

Accessibility

WCAG 2.1 AA compliant.

Theming

Full design token control.

<div data-layout="grid" data-layout-min="12rem">
  <article data-layout="regions" data-layout-gap="s">
    <header>Performance</header>
    <section><p>Optimized for speed.</p></section>
    <footer>Core feature</footer>
  </article>
  <!-- repeat for each card -->
</div>

Media Object

data-layout="media" places a figure and content side by side. The most common component pattern on the web.

data-layout="media"

Alice Brown

Deployed v2.1.0 to production. All health checks passing.

Carlos Martinez (reversed)

Merged PR #247: Container query support for media layout.

<div data-layout="media" data-layout-gap="m">
  <img src="avatar.jpg" alt="" width="48" height="48">
  <div>
    <strong>Alice Brown</strong>
    <p>Deployed v2.1.0 to production.</p>
  </div>
</div>

<!-- Reversed -->
<div data-layout="media" data-layout-reverse>...</div>

Key Principles

HTML declares structure - Use semantic elements (header, nav, main, aside, footer)
CSS assigns layout - Grid identity rules map elements to areas automatically
JS handles behavior - Only for interactive state changes (sidebar toggle, etc.)
:has() enables adaptation - Layouts respond to content presence without JS
Tokens enable customization - Override --_sidebar-width or template tokens as needed