Layout, Grid & Z-Index

The structural rules of any page: container width, grid columns, spacing scale, radius scale, breakpoints, and the z-index ladder. All of these are tokens you can compose; this page documents how they fit together.

Container

Max page width with side gutters. Centered horizontally.

1440px viewport

1200px container · token --container-max

Token	Value	Use
--container-max	1200px	Outer page max-width. Center with `margin: 0 auto`.
--container-pad	24px	Side gutter at desktop sizes. Drops to 16px on mobile.

12-column grid

CSS Grid with 12 equal columns + 16px gutter. Compose layouts via grid-column: span N.

12 (full width)

4 (sidebar)

6 (split half)

4 (3-col cards)

3 (4-col stat row)

Spacing scale

8 steps, 4px base. Use these tokens — never hardcode numbers like padding: 13px.

--space-xxs

2pxhairlines, micro-gaps inside chips

--space-xs

4pxtight gaps (icon+text inside a button)

--space-sm

8pxdefault flex gap, button padding-y

--space-md

12pxcard content padding, form-field gap

--space-lg

16pxsection gap, grid gutter

--space-xl

20pxcard padding-x

--space-2xl

24pxpage padding, modal padding

--space-3xl

32pxsection break, between unrelated cards

Radius scale

7 steps. Each component has a recommended radius — see the rightmost column.

--radius-xs
4px
checkboxes

--radius-sm
6px
small chips

--radius-md
8px
inputs, secondary btns

--radius-lg
10px
tab pills, dense cards

--radius-lg2
12px
primary CTAs, cards

--radius-lg3
14px
large feature cards

--radius-xl
16px
dialogs, hero surfaces

--radius-pill
9999px
avatars, full-pill btns

Breakpoints

Mobile-first. Use min-width queries; let things stack until they need to spread.

Token	Value	Layout behavior	Examples
--bp-sm	480px	Phones rotate to landscape; small split-pane appears.	2-col grid possible, side-by-side button rows.
--bp-md	768px	Tablets in portrait; sidebar nav can appear collapsed.	4-col stat row, 2-col forms.
--bp-lg	1024px	Desktop layout — full sidebar, full grid.	12-col grid, 3-col card grids.
Below `--bp-sm` (under 480px) is the default — everything stacks single-column with 16px page padding.

Pattern: mobile-first CSS

.layout {
  /* default: stack */
  display: flex;
  flex-direction: column;
  gap: var(--space-lg);
}

@media (min-width: 768px) {  /* --bp-md */
  .layout { flex-direction: row; }
}

Z-index ladder

Six tiers, well-spaced. Don't invent ad-hoc numbers — pick the right tier for the surface.

tier 1 · base

--z-base: 0

tier 2 · sticky

--z-sticky: 50

tier 3 · header

--z-header: 100

tier 4 · dropdown / popover / tooltip

--z-overlay: 200

tier 5 · modal / drawer

--z-modal: 1000

tier 6 · toast

--z-toast: 9000

Token	Value	Used for	Why
--z-base	0	Page content, default	Sets the floor
--z-sticky	50	Sticky table headers, sub-nav	Floats above scroll content
--z-header	100	Page top-bar, side-rail	Above sticky elements
--z-overlay	200	Dropdowns, popovers, tooltips	Above header
--z-modal	1000	Dialogs, drawers, sheet overlays	Big jump — modal blocks the world
--z-toast	9000	Toasts, system banners	Above modals (you must see a fill confirmation even mid-modal)

The 50/100/200/1000/9000 spacing is intentional — each tier has plenty of room for sub-tiers within itself (e.g. nested popovers can use 201, 202 without colliding with modal). Never invent ad-hoc numbers like z-index: 7 — pick a tier.

Implementation notes

Tokens currently in `tokens.css`

✅ --space-* (8 steps)
✅ --radius-* (7 steps + pill)
✅ --container-max, --container-pad, --header-h
✅ --bp-sm, --bp-md, --bp-lg
⏳ z-index tokens — proposed in this doc, not yet in tokens.css. Coming in v0.3.0.
⏳ Grid mixin / class — proposed; will ship as .fam-grid-12 with column-span utility classes.

Don't

❌ Don't hardcode padding: 13px — it'll never line up with the rest of the system. Use the closest --space-* token.
❌ Don't use 4-column grids on mobile — stack first, spread when there's room.
❌ Don't pick z-index numbers ad-hoc — use the tier token.
❌ Don't override --container-max per-page — if a page needs full width, use a full-bleed wrapper outside the container.