Skip to content

Spacing & Layout ​

The 4pt grid, density modes, and the layout primitives every page is built from.


The 4pt grid ​

Every spatial value is a multiple of 4px (0.25rem). This is not arbitrary:

  • 4 divides evenly into 8, 12, 16, 20, 24 — the sizes UI actually needs
  • It matches iOS and Android baseline grids, so the design translates to mobile
  • Icon sets are drawn on 16/20/24px grids, which align to it
  • It removes the "is this 13px or 14px?" decision entirely

Full token list: Design Tokens.

Choosing a value ​

2px   hairline separation, icon optical nudges
4px   icon ↔ label
8px   related items in a group (button icon + text)
12px  form label ↔ input, button padding-x
16px  DEFAULT — items in a list, grid gutters
20px  card padding
24px  between distinct groups inside a card
32px  between cards
48px  between page sections
64px+ hero / empty-state padding

Rule of thumb: the gap between related things must be smaller than the gap to unrelated things. Most spacing bugs are a violation of proximity, not a wrong value.

❌ Ambiguous — is the label for the field above or below?
   [Label]           16px
   [Input]           16px
   [Label]           16px
   [Input]

✅ Grouped
   [Label]            8px
   [Input]           24px
   [Label]            8px
   [Input]

Density modes ​

Space tokens are multiplied by a density factor set on <html>.

scss
@layer tokens {
  :root { --av-density: 1; }
  [data-av-density="compact"]   { --av-density: 0.8; }
  [data-av-density="spacious"]  { --av-density: 1.25; }

  :root {
    --av-space-1: calc(0.25rem  * var(--av-density));
    --av-space-2: calc(0.5rem   * var(--av-density));
    --av-space-3: calc(0.75rem  * var(--av-density));
    --av-space-4: calc(1rem     * var(--av-density));
    --av-space-5: calc(1.25rem  * var(--av-density));
    --av-space-6: calc(1.5rem   * var(--av-density));
    --av-space-8: calc(2rem     * var(--av-density));
    /* … */
  }
}

What density does and does not affect ​

AffectedNot affected
Padding and marginFont sizes
Gaps in flex/gridBorder widths
Table row heightIcon sizes
Control heightsRadii
Sidebar item heightLine heights

Font size is deliberately excluded. Scaling type with density breaks the modular scale and the contrast/legibility guarantees. Users who need bigger text use browser zoom, which AdminVora fully supports.

Component-level density ​

Override for one region without changing the global mode:

html
<div class="av-table-wrap" data-av-density="compact">
scss
[data-av-density="compact"] .av-table {
  --av-table-cell-padding-y: var(--av-space-2);
}

Measurements per mode ​

ElementCompactComfortableSpacious
Table row height36px48px60px
Button height (md)32px38px44px
Input height34px40px46px
Card padding16px20px25px
Sidebar item height34px42px50px
Topbar height52px64px72px
Page padding20px24px32px

Important — in compact mode, touch targets can fall below the 44px WCAG 2.5.8 minimum. The shell therefore forces comfortable below the lg breakpoint:

scss
@media (max-width: 991.98px) and (pointer: coarse) {
  :root { --av-density: 1 !important; }
}

The shell grid ​

scss
// src/scss/layout/_shell.scss
.av-shell {
  display: grid;
  grid-template-columns: auto 1fr;
  grid-template-rows: 100dvh;
  grid-template-areas: 'sidebar main';
}

.av-sidebar { grid-area: sidebar; }
.av-main    {
  grid-area: main;
  display: grid;
  grid-template-rows: auto 1fr auto;
  grid-template-areas: 'topbar' 'content' 'footer';
  min-inline-size: 0;                 /* critical: allows children to shrink below content size */
  overflow: hidden;
}

.av-topbar  { grid-area: topbar; }
.av-content { grid-area: content; overflow-y: auto; overscroll-behavior: contain; }
.av-footer  { grid-area: footer; }

100dvh (dynamic viewport height) rather than 100vh — on mobile Safari, 100vh includes the collapsing browser chrome, which produces a scroll jump as the toolbar hides.

min-inline-size: 0 on .av-main is the single most important line in the file. Without it, a wide table forces the whole grid to expand and the sidebar gets pushed off-screen.

Layout mode variants ​

scss
[data-av-layout="horizontal"] .av-shell {
  grid-template-columns: 1fr;
  grid-template-areas: 'main';
  .av-sidebar { display: none; }
}

[data-av-layout="detached"] .av-shell {
  padding: var(--av-space-4);
  gap: var(--av-space-4);
  background: var(--av-surface-sunken);
  .av-sidebar, .av-main { border-radius: var(--av-radius-xl); overflow: hidden; }
}

Full reference: Layout Modes.


Content width ​

scss
.av-content > .container-fluid { padding-inline: var(--av-content-padding); }

:root { --av-content-padding: var(--av-space-6); }
@media (max-width: 575.98px) { :root { --av-content-padding: var(--av-space-4); } }

[data-av-width="boxed"] .av-content > .container-fluid {
  max-inline-size: var(--av-content-max, 1400px);
  margin-inline: auto;
}
data-av-widthBehaviour
fluid (default)Content fills the available width
boxedCapped at 1400px and centred

On ultra-wide monitors, fluid produces unreadable 200-character table rows. boxed is the better default for content-heavy applications; fluid is better for data grids.


Layout primitives ​

Six composable classes cover ~90% of layout needs without writing custom CSS.

Stack — vertical rhythm ​

scss
.av-stack-4 > * + * { margin-block-start: var(--av-space-4); }
html
<div class="av-stack-4">
  <section>…</section>
  <section>…</section>
</div>

One class, and the gap is in its name. There is no --sm/--lg/--xl family and no --av-stack-gap property to override, because a size-per-modifier utility is how a six-class layer becomes a twenty-class one — at which point it is a grid system, and the reason this product does not ship a grid system is that a customer should not have to learn one before moving a section.

It is > * + * rather than flex + gap deliberately: a flex container changes how its children size themselves, and this utility is applied to page sections that were laid out as block elements. Spacing them without also making them flex items is the whole point.

Cluster — horizontal group that wraps ​

scss
.av-cluster {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: var(--av-cluster-gap, var(--av-space-3));
}
.av-cluster--between { justify-content: space-between; }
.av-cluster--end     { justify-content: flex-end; }

The workhorse for toolbars, tag lists, and button groups. It wraps correctly at any width without a media query.

scss
.av-sidebar-layout {
  display: flex;
  flex-wrap: wrap;
  gap: var(--av-space-6);

  > :first-child { flex: 1 1 var(--av-side-width, 280px); }
  > :last-child  { flex: 999 1 var(--av-main-min, 50%); }
}

Stacks automatically when the main column would drop below 50% — no breakpoint required. This is the Every Layout sidebar pattern, and it beats media queries because it responds to the container, not the viewport.

Switcher — N columns that become 1 ​

scss
.av-switcher {
  display: flex;
  flex-wrap: wrap;
  gap: var(--av-space-4);

  > * {
    flex-grow: 1;
    flex-basis: calc((var(--av-switch-at, 40rem) - 100%) * 999);
  }
}

Three cards side by side above 40rem, stacked below — with zero media queries.

Grid — responsive auto-fit ​

scss
.av-grid {
  display: grid;
  gap: var(--av-grid-gap, var(--av-space-4));
  grid-template-columns: repeat(auto-fit, minmax(min(var(--av-grid-min, 260px), 100%), 1fr));
}

min(…, 100%) prevents overflow on narrow screens — the classic auto-fit bug.

Center — constrained and padded ​

scss
.av-center {
  box-sizing: content-box;
  max-inline-size: var(--av-center-max, 60ch);
  margin-inline: auto;
  padding-inline: var(--av-space-4);
}

The grid ​

There is no 12-column grid in this build — no row, no col-md-6, no g-3, no offset or ordering classes. .av-grid is CSS Grid with a short list of modifiers, and the gap comes from the space scale rather than a gutter class:

html
<div class="av-grid av-grid--stats">
  <div class="av-card">…</div>
  <div class="av-card">…</div>
</div>
ModifierColumns
.av-grid--statsrepeat(auto-fit, minmax(220px, 1fr)) — KPI tiles
.av-grid--leadWith --stats, on a row of four: 1.6fr repeat(3, minmax(0, 1fr)) from 1400px, so the first tile leads
.av-grid--cardsrepeat(auto-fit, minmax(280px, 1fr)) — card collections
.av-grid--main2fr 1fr — content with an aside
.av-grid--half3fr 2fr — two unequal panels

--main and --half collapse to one column at the narrow breakpoint; the auto-fit pair never need a media query at all, which is the reason to prefer them.

Exact column ratios are a modifier, not a span class. A 7/5 split is a new --modifier in utilities/_grid.scss, not col-7+col-5 in the markup — which keeps the ratio in the stylesheet where lint:css can see it, and out of the markup where nothing can.

One rule in that file is not cosmetic and is worth knowing before you write your own grid:

scss
.av-grid > * { min-inline-size: 0; }

A grid item's automatic minimum size is its content's min-content width, so any cell that can hold a table grows past the viewport instead of scrolling inside itself. This exact omission on a different container pushed 27px of a page out through the side, found by tests/pages.mjs rather than by looking.


Breakpoints ​

NameMin-widthTarget
xs0Phones
sm576pxLarge phones
md768pxTablets
lg992pxSidebar becomes persistent
xl1200pxDesktops
xxl1400pxLarge desktops
xxxl1800pxUltra-wide (AdminVora addition)
scss
// Custom media queries via postcss-preset-env
@custom-media --av-sm (min-width: 576px);
@custom-media --av-lg (min-width: 992px);
@custom-media --av-touch (pointer: coarse);
@custom-media --av-hover (hover: hover) and (pointer: fine);
@custom-media --av-motion-ok (prefers-reduced-motion: no-preference);

@media (--av-lg) { .av-sidebar { position: sticky; } }
@media (--av-hover) { .av-card:hover { box-shadow: var(--av-shadow-md); } }

Guarding hover effects with (hover: hover) prevents sticky hover states on touch devices — a persistent, easily-avoided annoyance.


Container queries ​

Components respond to their container. Use these instead of media queries inside components.

scss
.av-card {
  container-type: inline-size;
  container-name: card;
}

.av-stat-card {
  @container card (max-width: 240px) {
    --av-stat-card-value-size: var(--av-font-size-2xl);
    .av-stat-card__spark { display: none; }
  }
}

Registered container names:

NameDeclared on
card.av-card
panel.av-panel, .av-drawer__body
content.av-content
sidebar.av-sidebar
table.av-table-wrap

Sizing tokens ​

TokenValueUse
--av-size-icon-xs … --av-size-icon-xl12 / 16 / 20 / 24 / 32pxIcons
--av-size-avatar-xs … --av-size-avatar-2xl24 / 32 / 40 / 48 / 64 / 96pxAvatars
--av-size-control-sm / md / lg32 / 38 / 44pxButtons, inputs
--av-size-touch-min44pxWCAG 2.5.8 minimum
--av-sidebar-width264pxExpanded sidebar
--av-sidebar-width-collapsed72pxIcon-only sidebar
--av-topbar-height64px
--av-drawer-width380pxUtility drawer

Touch-target expansion ​

Small icon buttons stay visually small while meeting the 44px hit-area requirement:

scss
.btn-icon.btn-sm {
  inline-size: 32px;
  block-size: 32px;
  position: relative;

  &::after {
    content: '';
    position: absolute;
    inset: calc((var(--av-size-touch-min) - 100%) / -2);
    /* invisible, but clickable */
  }
}

Scroll behaviour ​

scss
html { scroll-behavior: smooth; scroll-padding-block-start: calc(var(--av-topbar-height) + 1rem); }

@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }

.av-content {
  overflow-y: auto;
  overscroll-behavior: contain;      /* stops scroll chaining to the page behind */
  scrollbar-gutter: stable;          /* stops layout shift when a scrollbar appears */
}

scrollbar-gutter: stable eliminates the horizontal jump when navigating between a short and a long page — a small detail that makes the app feel solid.

Read next: Elevation & Depth.

Documentation for @creativeigniter/adminvora