Layout Module

Navigation: uCss > Source > Modules > Layout

Modules: Config | Base | Layout | Theming | Typography | Patterns | Utilities

Context-Aware Layouts. The structural backbone of uCss β€” Section, Grid, Flex, and the Container Query helper. Powered by container queries, fluid spacing, and implicit grids, so your components look right on a 4K screen or squeezed into a 300px sidebar.


πŸ“‘ Contents


🌟 Overview

The Layout Module provides four pieces that cover virtually every layout need:

  1. Query (.cq) β€” the generic container-query context helper.
  2. Section (.s | [data-layout="section"]) β€” the page shell: full-bleed backgrounds, fluid vertical padding, and an implicit 3-tier system (Section > Container > Content).
  3. Grid (.g | [data-display="grid"]) β€” the 2D engine: auto-fit columns, explicit presets, subgrid, item placement, and recipes (masonry, carousels, dense).
  4. Flex (.f | [data-display="flex"]) β€” the 1D engine: navbars, media objects, stacks, and item control.

Top Features

  1. Container-Query Native: grids and flex containers respond to their parent container, not the viewport.
  2. Zero-Config Auto-Fit: .g computes columns from --g-min (β‰ˆ 256–320px default). No media queries.
  3. Fluid Spacing: gaps (--g-g, --f-g, --s-g) use clamp() β€” they breathe on desktop, tighten on mobile.
  4. Implicit 3-Tier Sections: section.s > div gives you a full-bleed section with a centered, constrained container.
  5. Subgrid: .sg / .sgc align grandchildren to the parent grid tracks.

🀯 Philosophy

Viewport vs Container

  • Viewport Thinking (Old): "I am on a phone, so this card is full width."
  • Container Thinking (New): "I have less than 480px of space, so this card is full width."

Container queries decouple the component from the page β€” a "mobile layout" card works inside a desktop sidebar with no code duplication.

Implicit vs Explicit

  • Explicit: you define every row and column (good for art direction).
  • Implicit: you define constraints (--g-min, gap) and let the browser generate rows/columns (good for application UI).

uCss defaults to Implicit, with explicit overrides (.g-3) when needed.

The Death of Media Queries

Media queries are global state; container queries are local state. Layout responds to the space it is given, which reduces media-query usage dramatically.


πŸš€ Getting Started

The "Clicked" Moment

  1. Create a grid: <ul class="g">.
  2. Add 5 items.
  3. Resize the window: 5 β†’ 4 β†’ 3 β†’ 2 β†’ 1 columns automatically.
  4. Override the floor: style="--g-min: 100px" β€” items pack tighter. You control the constraint, not the count.

Rollout in One Minute

<link rel="stylesheet" href="https://ucss.unqa.dev/latest/lib/layout.min.css">
<section class="s">
  <div>
    <h2 class="tl">Section Title</h2>
    <ul class="g">
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </ul>
  </div>
</section>

Done. The div is the implicit container (centered, 80rem max); the ul.g auto-fits.


πŸ’‘ How to Use It (Perfect Scenarios)

Each scenario shows an Emmet abbreviation β†’ expanded HTML β†’ which pieces it uses. Detail lives in the submodule READMEs: Grid, Flex, Section.

1. Universal Page Shell

Emmet: section.s>div

<section class="s"><div>…</div></section>

Full-bleed section + implicit centered container.

2. Section with a Card Grid

Emmet: section.s>div>(header>(h2+p)+ul.g>li.clk*3>article.crd>(h3+p)+div>a.btn)

<section class="s">
  <div>
    <header><h2>SEO</h2><p>Lede</p></header>
    <ul class="g">
      <li class="clk"><article class="crd"><h3>…</h3><p>…</p></article></li>
      <li class="clk"><article class="crd"><h3>…</h3><p>…</p></article></li>
      <li class="clk"><article class="crd"><h3>…</h3><p>…</p></article></li>
    </ul>
    <div><a class="btn">Key CTA</a></div>
  </div>
</section>

3. Split Hero

Emmet: section.s.split>div>(div>(h2+p+p+div>a.btn)+figure>img)

<section class="s split">
  <div>
    <div>
      <h2>SEO</h2>
      <p>Title / UVP</p>
      <p>Content…</p>
      <div><a class="btn">Key CTA</a></div>
    </div>
    <figure><img src="…" alt="…"></figure>
  </div>
</section>

4. Stats Row

Emmet: section.s>div>(header>h2+ul.g.g-3>li*3>(strong+span))

<section class="s"><div>
  <header><h2>SEO</h2></header>
  <ul class="g g-3"><li><strong>1M+</strong><span>Users</span></li> Γ—3</ul>
</div></section>

5. Sidebar Page

Emmet: div.g.sr>(main+aside)

<div class="g sr">
  <main>…content…</main>
  <aside>…sidebar…</aside>
</div>

6. Navbar (Flex)

Emmet: nav.f.row.ai-c>(div.logo+div.f>a*3)

<nav class="f row ai-c">
  <div class="logo">Logo</div>
  <div class="f"><a href="#">Home</a><a href="#">About</a><a href="#">Contact</a></div>
</nav>

7. Media Object (Flex)

Emmet: div.f.ai-c>(figure>img+div>(h3+p))

<div class="f ai-c">
  <figure><img src="…" alt="…"></figure>
  <div><h3>Title</h3><p>Body…</p></div>
</div>

πŸ“¦ Installation & Stats

Bundle Stats

layout.css is the aggregator β€” it imports Query, Section, Flex, and Grid.

File Full (Raw) Clean Min Gzip Brotli
layout.css (Aggregator) 100.3 KB 82.3 KB 68.6 KB 15.3 KB 12.1 KB
grid.css 56.3 KB 47.1 KB 39.1 KB 8.3 KB 6.5 KB
flex.css 21.1 KB 17.5 KB 14.5 KB 3.7 KB 3.0 KB
section.css 21.9 KB 17.1 KB 14.5 KB 4.2 KB 3.5 KB
query.css 0.8 KB 0.6 KB 0.5 KB 0.4 KB 0.3 KB

Stats reflect the last verified build from dist/latest. Run npm run build:latest to regenerate.

Module Full Source Minified (Prod)
Layout layout.css layout.min.css
Grid grid.css grid.min.css
Flex flex.css flex.min.css
Section section.css section.min.css

HTML Snippets

<link rel="preconnect" href="https://ucss.unqa.dev">
<link rel="stylesheet" href="https://ucss.unqa.dev/latest/lib/layout.min.css">

πŸ“‚ Files Reference

Path Description
query.css Container-query helper (.cq / .cquery) + opt-out (.un / .nq / .noquery).
section/ README β€” .s, .sc, .scc, width modifiers, recipes (split/lock/hero), spacing vars.
section/base.css Section shell (.s) β€” background, fluid padding, modifiers.
section/container.css Container (.sc / direct div) β€” max-width, centering, width modifiers.
section/content.css Content blocks (.scc) β€” gaps, measure presets (.ct-*, .ch-*).
section/recipes.css Split / lock / mono / slab / hero recipes.
flex/ README β€” .f, direction, wrap, item controls.
flex/base.css Container (.f) β€” default gap, responsive behavior.
flex/direction.css .col / .row / reverse.
flex/wrap.css .wrap / .nowrap.
flex/item/ README β€” .fxg-*, .fxs-*, .fxb-*, .o-*.
grid/ README β€” .g, columns, subgrid, item placement, recipes.
grid/base.css Grid engine (.g) β€” auto-fit, tracks, gaps, container queries.
grid/columns.css Column presets (.g-1…12, ratios, sidebars).
grid/subgrid.css Subgrid (.sg / .sgc).
grid/item/ README β€” placement spans and variable API.
grid/recipes/ README β€” masonry, scroll/carousel, dense.

🧠 Deep Dive

1. The Logic of Container Queries

The layout module establishes container contexts so children can respond to the space they are given:

  • Grid β€” a non-grid ancestor that directly contains a .g becomes the container (container: gp / inline-size).
  • Flex β€” a .cq / .cquery ancestor of a .f becomes the container (container: fp / inline-size).
  • Section β€” every container (.sc) is itself a named container: container: sc / inline-size.

Breakpoints (container-query widths):

Suffix Container width
--sm < 30rem (480px)
--smd < 60rem
--md 30rem – 60rem (480–960px)
--mdl > 30rem
--lg > 60rem (960px+)

An extra-small behavior (≀ 20rem / 320px) tightens grid minimums.

2. Section Architecture (.s)

The Section uses a "Smart Wrapper" technique:

  • The shell spans 100% width and carries the background + fluid padding-block (---3xg, β‰ˆ 7–8rem).
  • A direct child div becomes the Container: max-width: 80rem (--sc-maw), margin-inline: auto, and container: sc / inline-size.
  • Its children become Content blocks that flow vertically with responsive gaps.

The universal pattern is section.s > div.

3. Implicit Auto-Fit Grids (.g)

The core formula:

grid-template-columns: repeat(var(--g-cols, auto-fit), minmax(var(--g-min), var(--g-max, 1fr)))
  • auto-fit β€” as many columns as fit.
  • minmax β€” each column at least --g-min wide (default ---3xc, β‰ˆ 256–320px).
  • 1fr β€” share leftover space equally.

4. The Flex System (.f)

Flex handles flow. .f is display: flex with a fluid default gap (--f-g, β‰ˆ 0.875–1rem). Direction defaults to row; .col / .row / responsive variants switch it.

5. Variable API (Advanced)

"Configuration over Implementation." Every layout piece is driven by variables with responsive variants (--sm, --md, --lg).

  • Grid: --g-cols, --g-min, --g-max, --g-g, --g-rg, --g-cg, --gta, --gtr, --gtc.
  • Grid item: --gc, --gr, --ga, --as, --js, --o (aliases --gi-col, --gi-row, …).
  • Flex: --f-g, --f-rg, --f-cg, --f-ai, --f-ac, --f-jc.
  • Flex item: --fxg, --fxs, --fxb, --o.
  • Section: --s-pb, --s-pi, --s-g, --s-ai; --sc-maw, --sc-rg, --sc-cg; --scc-rg, --scc-cg.

πŸ“ Reference: Content Map

1. Section (.s / .sc / .scc)

Structure

Class / Attribute Tier Role
.s / [data-layout="section"] 1 shell β€” full width, background, fluid padding, flex-column
.sc / [data-layout="container"] / direct div 2 container β€” max-width: 80rem, centered, container: sc
.scc / [data-layout="content"] / direct content child 3 content block β€” responsive gaps, optional measure

Container Widths

Class Max width
.sc (default) 80rem (1280px)
.sc--xs / .c-xs 64rem
.sc--s / .c-s 70rem
.sc--m / .c-m 80rem
.sc--l / .c-l 85rem
.sc--xl / .c-xl 90rem
.sc--xxl / .sc--2xl / .c-2xl 100rem
.sc--xxxl / .sc--3xl / .c-3xl 120rem
.sc--f / .c-f 100%
.sc--a4 / .a4 Β· .sc--a4x / .a4x 210mm Β· 297mm
.mq--xs / --sm / --md / --lg 23 / 33 / 66 / 88rem
.cq--xs / --sm / --md / --lg 20 / 30 / 60 / 80rem

Content Measures

Class Max width
.scc--xxs / .ct-2xs 20rem
.scc--xs / .ct-xs 24rem
.scc--s / .ct-s 32rem
.scc--m / .ct-m 40rem (reading)
.scc--l / .ct-l 48rem
.scc--xl / .ct-xl 56rem
.scc--2xl / .scc--xxl / .c-xs 64rem
.scc--3xl / .scc--xxxl / .c-s 70rem
.scc--ch-xs / --ch-s / --ch-m / --ch-l 24 / 40 / 64 / 80ch

Recipes

Recipe Effect
.split / .horizon / .ledger / .spread side-by-side split (50/50 or β…“/β…”), stacks < 33rem
.lock / .sticker / .feat / .ancd 2-column grid β‰₯ 66rem, sticky first column
.mo / .mono / .kickin / .focus / .thesis narrow centered (max 64rem)
.plinth / .slab / .frieze / .hand left-aligned reading column (56rem; 48rem for .frieze/.hand/.thesis)
.hero / .heroism / .heroin reduced top padding; .heroin reserves header height

Shell Modifiers

Class Effect
.fh / .fs / .fvh full-height (min-height 100svh on viewports ≀ 64rem tall)
.fw / .fs / .fvw full width
.fsz full-bleed (zero inline padding)

Variables

Variable Default Controls
--s-bg none section background
--s-pb / --s-pbs / --s-pbe ---3xg (β‰ˆ 7–8rem) padding-block
--s-pi / --s-pis / --s-pie --p5f (clamp(1.5rem, 5%, 4rem)) padding-inline
--s-g / --s-rg / --s-cg ---xg (β‰ˆ 5–6rem) gap
--s-d / --s-fxd / --s-fxw / --s-ai flex / column / nowrap / center flex context
--sc-maw --c-m (80rem) container max-width
--sc-rg / --sc-cg ---xe / ---2xe (3–3.5 / 3.5–4rem) container gaps
--scc-rg / --scc-cg ---s / ---xe (1–1.25 / 3–3.5rem) content gaps
--scc-maw auto content max-width (use .scc--*)

2. Grid (.g)

Base

Class Effect
.g auto-fit grid (min --g-min, gap --g-g)
.dense / .g-d grid-auto-flow: dense
.inline / .g-i display: inline-grid

Column Presets

Class Desktop Tablet Mobile
.g-1 1 1 1
.g-2 2 1 1
.g-3 3 2 1
.g-4 4 2 1
.g-5 5 3 1
.g-6 6 4 2
.g-8 8 4 2
.g-9 9 6 3
.g-12 12 6 3
.g-2-1 / .g-1-2 β…”+β…“ / β…“+β…” 1 1
.g-3-1 / .g-1-3 ΒΎ+ΒΌ / ΒΌ+ΒΎ 1 1
.g-2-3 / .g-3-2 β…–+β…— / β…—+β…– 1 1
.sr / .sl sidebar right / left stacks stacks

Responsive suffixes: .g-3--lg, .g-2--md, .g-1--sm, --smd, --mdl.

Subgrid

Class Effect
.sg / .sgr / .subgrid / .subrow grid-template-rows: subgrid
.sgc / .subcol grid-template-columns: subgrid

Item Placement

Class Effect
.gc-1 … .gc-12 grid-column: span N
.gr-1 … .gr-5 grid-row: span N
.gc-f / .gr-f full: 1 / -1

All accept --sm, --smd, --md, --mdl, --lg.

Recipes

Class Effect
.g-ms / .g-gl / .grid-lanes masonry (multi-column fallback, native upgrade)
.slr, .scr-1…4 exact-fit scroll (1–4 items)
.crs-1…4, .ctrs peeking carousel + native scroll buttons
[data-recipe~="masonry|gallery|grid-lanes|lanes|slider|scroll|scroll-N|carousel|carousel-N"] attribute API

Variables

Variable Default Controls
--g-cols auto-fit column behavior
--g-min ---3xc (β‰ˆ 256–320px) minimum item width
--g-max 1fr maximum track size
--g-g / --g-rg / --g-cg ---e (2.5–3rem) gap
--gta / --gtr / --gtc β€” grid-template areas / rows / columns
--gac / --gar / --gaf β€” auto columns / rows / flow
--gc / --gr / --ga auto item column / row / area (aliases --gi-col / --gi-row)

3. Flex (.f)

Base

Class Effect
.f flex container (default row) + fluid gap --f-g
.row / .fxr flex-direction: row
.col / .fxc flex-direction: column
.rv / .reverse reverse current direction
.wrap / .fxw flex-wrap: wrap
.nowrap / .fxnw flex-wrap: nowrap

Responsive: .col--md, .row--lg, .wrap--sm, .rv--lg, etc.

Item Controls

Class Alias Variable Effect
.fxg-1 / .fxg-0 .grow-1 / .grow-0 --fxg flex-grow
.fxs-0 / .fxs-1 .shrink-0 / .shrink-1 --fxs flex-shrink
.fxb-auto .basis-auto --fxb flex-basis
.fxb-thd / .fxb-half / .fxb-full .basis-third / .basis-half / .basis-full --fxb 33.333% / 50% / 100%
.o-1 … .o-9 .first / .last --o order
.mi-a / .mb-a / .mi-as / .mi-ae β€” --fi-mi* auto margins

Variables

Variable Default Controls
--f-g / --f-rg / --f-cg ---xs (β‰ˆ 0.875–1rem) gap
--f-ai / --f-ac / --f-jc normal alignment (via shared utilities)
--fxg / --fxs / --fxb / --o 0 / 1 / auto / 0 item

4. Alignment & Gaps

Shared utilities (.ai-*, .jc-*, .ac-*, .as-*, .js-*) drive layout components through the alignment variables.

Class Property Value
.ai-c / .ai-s / .ai-e / .ai-st / .ai-b align-items center / start / end / stretch / baseline
.jc-c / .jc-s / .jc-e / .jc-sb / .jc-sa / .jc-se justify-content center / start / end / space-between / space-around / space-evenly
.ac-* align-content start / center / end / space-between / around / evenly / stretch
.as-* / .js-* align-self / justify-self start / center / end / stretch / baseline

Gaps come from the fluid spacing scale (---* tokens). Layout gaps are set per context:

Context Row / Column gap vars
Section --s-rg / --s-cg (default ---xg)
Container --sc-rg / --sc-cg (---xe / ---2xe)
Content --scc-rg / --scc-cg (---s / ---xe)
Grid --g-rg / --g-cg (---e)
Flex --f-rg / --f-cg (---xs)

πŸ’‘ Best Practices & Customization

Grid vs Flex: The Golden Rule

  • Grid (.g) β€” items are columns; you care about width and placement (2D): galleries, dashboards, card rows.
  • Flex (.f) β€” items are a stream; you care about flow and alignment (1D): navbars, media objects, button groups.

Real World Examples

The Dashboard Shell

<section class="s">
  <div>
    <ul class="g g-12">
      <li class="gc-3"><nav class="f col"><a href="#">…</a>Γ—4</nav></li>
      <li class="gc-9">
        <h1>Dashboard</h1>
        <ul class="g">…stats…</ul>
      </li>
    </ul>
  </div>
</section>

The Split Hero

<section class="s split">
  <div>
    <div>
      <h1 class="hl">Headline</h1>
      <p class="lede">Subhead</p>
      <div><a class="btn">CTA</a></div>
    </div>
    <figure><img src="hero.png" alt=""></figure>
  </div>
</section>

πŸ”§ For Developers

  • Subgrid: .sg / .sgc only work in browsers that support subgrid (modern Chrome, Firefox, Safari). No polyfill β€” it degrades to normal flow.
  • Customize:
    • --g-min: auto-fit floor (default β‰ˆ 256–320px).
    • --g-g / --f-g / --s-g: per-context gaps.
    • --sc-maw: container max-width (default 80rem).
  • Extend a grid preset:
.g-7 {
  --g-cols--lg: 7;
  --g-cols--md: 4;
  --g-cols--sm: 2;
}

Navigation: uCss > Source > Modules > Layout

Modules: Config | Base | Layout | Theming | Typography | Patterns | Utilities

Back to top

License: MPL-2.0 Copyright: © 2026 Shukhrat (Alive 🜁) ※ UNQA


πŸ—ΊοΈ Visual Map

src/lib/
β”œβ”€β”€ config/                  # 1. CONFIGURATION (The Brain)
β”‚   β”œβ”€β”€ root/                #    - Semantic Modules
β”‚   β”‚   β”œβ”€β”€ colors.css       #    - Palettes & Themes
β”‚   β”‚   β”œβ”€β”€ typography.css   #    - Fonts & Scales
β”‚   β”‚   β”œβ”€β”€ layout.css       #    - Layout Tokens (sections, grids, gaps)
β”‚   β”‚   └── patterns.css     #    - Component Vars
β”‚   β”œβ”€β”€ adapters/            #    - CMS Adapters
β”‚   β”‚   β”œβ”€β”€ blocksy.css      #    - Blocksy Theme
β”‚   β”‚   └── gutenberg.css    #    - WordPress Block Editor
β”‚   └── root.css             #    - Entry Point
β”‚
β”œβ”€β”€ base/                    # 2. BASE (The Foundation)
β”‚   β”œβ”€β”€ html/                #    - HTML Engine
β”‚   β”‚   β”œβ”€β”€ reset.css        #    - Normalization
β”‚   β”‚   β”œβ”€β”€ typography.css   #    - Text Defaults
β”‚   β”‚   β”œβ”€β”€ flow.css         #    - Smart Flow Engine
β”‚   β”‚   β”œβ”€β”€ lists.css        #    - List Styles
β”‚   β”‚   β”œβ”€β”€ forms.css        #    - Input Styling
β”‚   β”‚   └── helpers.css      #    - HTML Utilities
β”‚   └── html.css             #    - Entry Point
β”‚
β”œβ”€β”€ layout/                  # 3. LAYOUT (The Skeleton) <== YOU ARE HERE
β”‚   β”œβ”€β”€ query.css            #    - Container Query Helper (.cq / .cquery)
β”‚   β”œβ”€β”€ section/             #    - Section Engine
β”‚   β”‚   β”œβ”€β”€ base.css         #    - Section shell (.s)
β”‚   β”‚   β”œβ”€β”€ container.css    #    - Container (.sc) & width modifiers
β”‚   β”‚   β”œβ”€β”€ content.css      #    - Content blocks (.scc) & measures
β”‚   β”‚   └── recipes.css      #    - Split / Lock / Hero recipes
β”‚   β”œβ”€β”€ flex/                #    - Flex Engine
β”‚   β”‚   β”œβ”€β”€ base.css         #    - Container (.f)
β”‚   β”‚   β”œβ”€β”€ direction.css    #    - .col / .row / reverse
β”‚   β”‚   β”œβ”€β”€ wrap.css         #    - .wrap / .nowrap
β”‚   β”‚   └── item/            #    - Item controls (.fxg-* / .fxs-* / .fxb-* / .o-*)
β”‚   β”œβ”€β”€ grid/                #    - Grid Engine
β”‚   β”‚   β”œβ”€β”€ base.css         #    - Core (.g) & container queries
β”‚   β”‚   β”œβ”€β”€ columns.css      #    - Presets & asymmetric layouts
β”‚   β”‚   β”œβ”€β”€ subgrid.css      #    - .sg / .sgc
β”‚   β”‚   β”œβ”€β”€ item/            #    - Placement spans & variable API
β”‚   β”‚   └── recipes/         #    - Masonry, scroll/carousel, dense
β”‚   β”œβ”€β”€ section.css          #    - Aggregator
β”‚   β”œβ”€β”€ flex.css             #    - Aggregator
β”‚   β”œβ”€β”€ grid.css             #    - Aggregator
β”‚   └── layout.css           #    - Entry Point (imports all)
β”‚
β”œβ”€β”€ patterns/                # 4. PATTERNS (The Components)
β”‚   β”œβ”€β”€ button/
β”‚   β”œβ”€β”€ card/
β”‚   └── ...
β”‚
β”œβ”€β”€ theming/                 # 5. THEMING (The Skin)
β”‚   β”œβ”€β”€ set/
β”‚   └── ...
β”‚
β”œβ”€β”€ typography/              # 6. TYPOGRAPHY (The Voice)
β”‚   β”œβ”€β”€ title.css
β”‚   β”œβ”€β”€ text.css
β”‚   └── controls/
β”‚
└── utilities/               # 7. UTILITIES (The Tools)
    β”œβ”€β”€ display.css
    β”œβ”€β”€ position.css
    β”œβ”€β”€ size.css
    └── ...