Astro Design System Starter
Token-first UI foundationDocs
Field 4

Layout

Primitive foundations

Primitive layout tokens define the raw responsive references for the layout system: viewport range, breakpoints, site padding limits and container limits. Semantic layout tokens and layout classes should consume these values instead of hardcoding local measurements.

Fluid viewport range

Reference viewport limits used when calculating responsive layout values.

Token
Value
Resolved value
Role
--fluid-viewport-min
20rem
320px
Minimum viewport reference used when deriving fluid layout values.
--fluid-viewport-max
120rem
1920px
Maximum viewport reference used when deriving fluid layout values.

Breakpoints

Viewport thresholds that define major layout changes.

Token
Value
Resolved value
Role
--breakpoint-medium
64rem
1024px
Tablet and medium layout reference. Media queries still use the literal value because CSS custom properties cannot be used in media conditions.
--breakpoint-small
48rem
768px
Mobile and small layout reference. Media queries still use the literal value because CSS custom properties cannot be used in media conditions.

Site padding limits

Minimum and maximum horizontal page padding before semantic fluid padding is calculated.

Token
Value
Resolved value
Role
--site-padding-inline-min
var(--size-16)
1rem / 16px
Minimum horizontal page padding from viewport edges.
--site-padding-inline-max
var(--size-40)
2.5rem / 40px
Maximum horizontal page padding from viewport edges.

Container limits

Raw max-width boundaries used by semantic container tokens.

Token
Value
Resolved value
Role
--container-main-max
var(--fluid-viewport-max)
120rem / 1920px
Maximum width for the main site container and composition grid canvas.
--container-small-max
50rem
800px
Maximum width for constrained reading or compact content areas.

Semantic variables

Semantic layout variables translate primitive viewport, padding and container values into reusable layout contracts. They are value contracts consumed by layout classes and data attributes, not the final public API by themselves.

Site padding

Semantic page padding used by layout classes and page-level composition.

Token
Value
Resolved value
Role
--site-padding-inline
clamp(var(--site-padding-inline-min), 0.5714rem + 2.1429vw, var(--site-padding-inline-max))
16-40px
Global horizontal page padding. Layout classes should use this token instead of local viewport padding values.

Containers

Semantic container width contracts consumed by layout container classes.

Token
Value
Resolved value
Role
--container-main
min(calc(100% - 2 * var(--site-padding-inline)), var(--container-main-max))
Available width minus page padding up to 1920px
Default content canvas width used by the main layout container and composition grid.
--container-small
min(calc(100% - 2 * var(--site-padding-inline)), var(--container-small-max))
Available width up to 800px
Constrained reading width for copy-heavy or compact content areas.
--container-full
100%
100%
Full available width for layouts that intentionally span their parent.

Composition grid

Semantic grid values for page composition and responsive column systems.

Token
Value
Resolved value
Role
--site-grid-columns
12 / 8 / 4
12 desktop, 8 tablet, 4 mobile
Responsive composition grid column count controlled by breakpoint media queries.
--site-grid-column-gap
clamp(var(--size-16), 0.9286rem + 0.3571vw, var(--size-20))
16-20px
Gap between composition grid columns.
--site-grid-column-width
calc((var(--container-main) - var(--site-grid-column-gap) * (var(--site-grid-columns) - 1)) / var(--site-grid-columns))
Calculated from container width, column count and grid gap
Derived width of one composition grid column.
--grid-auto-min-small
14rem
224px
Minimum item width for dense auto-fit grids.
--grid-auto-min-card
18rem
288px
Default minimum item width for card-like auto-fit grids.
--grid-auto-min-panel
24rem
384px
Minimum item width for larger panels in auto-fit grids.
--grid-auto-min-wide
32rem
512px
Minimum item width for wide editorial or feature panels in auto-fit grids.
--grid-breakout-edge-track
max(0rem, calc((100vw - var(--container-main)) / 2 - var(--site-grid-column-gap)))
Calculated edge tracks around the content grid
Creates edge tracks before and after the content grid for breakout layouts, accounting for the centered max-width container.

Grid system

The grid system defines site composition, explicit columns, auto-fit wrapping and breakout layouts. Use .l-grid as the structural class, then select the grid behavior with data attributes.

Grid visuals

The site grid uses responsive 12/8/4 columns. Breakout grids add edge tracks before and after the content columns for full-width media or composition.

Site grid: 12 content columns
Breakout grid: edge tracks + content columns

Grid attributes

Grid-specific attributes control grid mode, explicit columns, auto-fit minimum widths, gaps and child column spans.

Selector
Attribute
Values
Default
Value contracts
Usage
.l-grid
data-grid
site, columns, auto-fit, breakout
site
--site-grid-columns, --site-grid-column-gap, --grid-auto-min, --grid-breakout-edge-track
Controls the grid mode: site composition grid, explicit columns, auto-fit wrapping or breakout grid with edge tracks.
.l-grid
data-columns
site, 1, 2, 3, 4, 6, 12
site
--site-grid-columns
Controls explicit column presets. Use with data-grid="columns" for local repeated layouts or site for the responsive 12/8/4 grid.
.l-grid
data-min
small, card, panel, wide
card
--grid-auto-min-small, --grid-auto-min-card, --grid-auto-min-panel, --grid-auto-min-wide
Controls the minimum child width before auto-fit wraps to a new row.
.l-grid
data-gap
site, none, tiny, small, regular, medium, large, xlarge
site
--site-grid-column-gap, --gap-*
Controls grid gap. Use site for composition grids and global gap values for local grid groups.
.l-grid > *
data-grid-span
1-12, full, content, start, end
auto
grid-column
Controls child placement. Numeric spans are for column grids; content/full/start/end are for breakout grids.

Grid examples

Copyable patterns for the three most important grid modes: site composition, auto-fit card grids and breakout grids.

Site composition grid
<div class="l-grid" data-grid="site" data-gap="site">
  <article data-grid-span="4">...</article>
  <article data-grid-span="4">...</article>
  <article data-grid-span="4">...</article>
</div>
Auto-fit card grid
<div class="l-grid" data-grid="auto-fit" data-min="card" data-gap="medium">
  <article>...</article>
  <article>...</article>
  <article>...</article>
</div>
Breakout grid
<section class="l-section" data-padding="large">
  <div class="l-grid" data-grid="breakout">
    <div data-grid-span="content">Content aligned to the site grid.</div>
    <figure data-grid-span="full">Media can break out into edge tracks.</figure>
  </div>
</section>

Styles

Layout style classes are the public role-based interface for page composition. Classes define what a layout object is; attributes define its variant.

Layout classes

Base layout primitives for sections, containers, grids and grouped child flows.

Class
Role
Display
Default values
Value contracts
Usage
.l-section
Page section wrapper
block
width: 100%; padding-block: var(--section-padding-medium)
--section-padding-medium
Use as the outer wrapper for a major page section before placing a container or layout composition inside.
.l-container
Content width boundary
block
width: var(--container-main); margin-inline: auto
--container-main
Use to constrain section content to the main page canvas while preserving global page padding.
.l-grid
Responsive composition grid
grid
grid-template-columns: repeat(var(--site-grid-columns), minmax(0, 1fr)); gap: var(--site-grid-column-gap)
--site-grid-columns, --site-grid-column-gap
Use for column-based section composition when children need site grid, fixed columns, auto-fit wrapping or breakout behavior.
.l-stack
Vertical rhythm group
grid
gap: var(--gap-regular)
--gap-regular
Use for vertical groups of related children that need consistent spacing.
.l-cluster
Wrapping inline group
flex
flex-wrap: wrap; align-items: center; gap: var(--gap-regular)
--gap-regular
Use for wrapping horizontal groups such as actions, filters, compact links or metadata clusters.

Attributes

Layout attributes are the variant API for layout primitives. Use them to change section padding, container width, grid columns, gaps and alignment without creating additional utility classes.

Layout attributes

Variant controls for public layout classes. The class defines the role; the attribute defines the selected layout behavior.

Class
Attribute
Values
Default
Value contracts
Usage
.l-section
data-padding
none, small, medium, large, hero-top
medium
--section-padding-small, --section-padding-medium, --section-padding-large, --section-padding-hero-top
Controls vertical section padding. Use it on the section wrapper, not on inner content.
.l-container
data-container
main, small, full
main
--container-main, --container-small, --container-full
Controls the content width boundary for a layout container.
.l-stack
data-gap
none, tiny, small, regular, medium, large, xlarge
regular
--gap-*
Controls vertical rhythm between stacked children.
.l-stack
data-align
start, center, end, stretch
stretch
align-items
Controls cross-axis alignment for stacked children.
.l-cluster
data-gap
none, tiny, small, regular, medium, large, xlarge
regular
--gap-*
Controls spacing between wrapped inline children.
.l-cluster
data-align
start, center, end, stretch
center
align-items
Controls vertical alignment inside a wrapping inline group.
.l-cluster
data-justify
start, center, end, between
start
justify-content
Controls horizontal distribution inside a wrapping inline group.

Agentic Rules

Agentic layout rules describe how AI should compose sections, containers, grids and child-flow groups using classes, attributes and semantic layout variables.

Agentic layout rules

Operational rules for class-and-attribute layout composition.

Agentic Rule

Class defines role, attribute defines variant

Use layout classes for structural roles such as section, container, grid, stack and cluster. Use data attributes on those same elements to select padding, width, columns, gap or alignment variants.

Agentic Rule

Use section before container

Major page blocks should start with .l-section. Put .l-container inside it when content needs the main, small or full width contract. Do not replace this with one-off wrapper classes.

Agentic Rule

Use grid for composition, not for spacing only

Use .l-grid when children need site composition, explicit columns, auto-fit wrapping or breakout behavior. If the only need is vertical rhythm, use .l-stack instead.

Agentic Rule

Choose grid mode before grid details

First choose data-grid as site, columns, auto-fit or breakout. Then add data-columns, data-min, data-gap or child data-grid-span only when that mode needs it. Do not use data-columns as the grid mode.

Agentic Rule

Use stack for vertical rhythm

Use .l-stack for vertical groups of related children. Control the distance between children with data-gap instead of margins on individual children.

Agentic Rule

Use cluster for wrapping inline groups

Use .l-cluster for action rows, metadata, filters and small inline groups that should wrap. Control wrapping distance with data-gap and alignment with data-align or data-justify.

Agentic Rule

Promote only repeated layout patterns

Keep one-off component layout inside the component. Promote a local layout decision into global layout classes or attributes only when the same structural pattern repeats across sections or components.

Layout structure examples

Copyable markup patterns that show where classes and data attributes belong in semantic layout structure.

Section + container
<section class="l-section" data-padding="large">
  <div class="l-container" data-container="main">
    <div class="l-stack" data-gap="medium">
      <h2 class="heading-h2">System-first websites</h2>
      <p class="body-large">Reusable structure, controlled values and clear AI-readable contracts.</p>
    </div>
  </div>
</section>
Section + container + composition grid
<section class="l-section" data-padding="medium">
  <div class="l-container" data-container="main">
    <div class="l-grid" data-grid="site" data-gap="site">
      <article class="feature-card">...</article>
      <article class="feature-card">...</article>
      <article class="feature-card">...</article>
    </div>
  </div>
</section>
Stack + cluster inside a component area
<div class="l-stack" data-gap="regular">
  <h3 class="heading-h4">Design system audit</h3>
  <p class="body-regular">Use stack for vertical rhythm and cluster for wrapped inline actions.</p>

  <div class="l-cluster" data-gap="small" data-align="center" data-justify="start">
    <a class="button" href="/design-system">Open docs</a>
    <a class="button" href="/design-system/layout">View layout</a>
  </div>
</div>