Appearance
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 paddingRule 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
| Affected | Not affected |
|---|---|
| Padding and margin | Font sizes |
| Gaps in flex/grid | Border widths |
| Table row height | Icon sizes |
| Control heights | Radii |
| Sidebar item height | Line 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
| Element | Compact | Comfortable | Spacious |
|---|---|---|---|
| Table row height | 36px | 48px | 60px |
| Button height (md) | 32px | 38px | 44px |
| Input height | 34px | 40px | 46px |
| Card padding | 16px | 20px | 25px |
| Sidebar item height | 34px | 42px | 50px |
| Topbar height | 52px | 64px | 72px |
| Page padding | 20px | 24px | 32px |
Important — in
compactmode, touch targets can fall below the 44px WCAG 2.5.8 minimum. The shell therefore forcescomfortablebelow thelgbreakpoint: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-width | Behaviour |
|---|---|
fluid (default) | Content fills the available width |
boxed | Capped 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.
Sidebar — two columns, one fixed, that collapses
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>| Modifier | Columns |
|---|---|
.av-grid--stats | repeat(auto-fit, minmax(220px, 1fr)) — KPI tiles |
.av-grid--lead | With --stats, on a row of four: 1.6fr repeat(3, minmax(0, 1fr)) from 1400px, so the first tile leads |
.av-grid--cards | repeat(auto-fit, minmax(280px, 1fr)) — card collections |
.av-grid--main | 2fr 1fr — content with an aside |
.av-grid--half | 3fr 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
| Name | Min-width | Target |
|---|---|---|
xs | 0 | Phones |
sm | 576px | Large phones |
md | 768px | Tablets |
lg | 992px | Sidebar becomes persistent |
xl | 1200px | Desktops |
xxl | 1400px | Large desktops |
xxxl | 1800px | Ultra-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:
| Name | Declared on |
|---|---|
card | .av-card |
panel | .av-panel, .av-drawer__body |
content | .av-content |
sidebar | .av-sidebar |
table | .av-table-wrap |
Sizing tokens
| Token | Value | Use |
|---|---|---|
--av-size-icon-xs … --av-size-icon-xl | 12 / 16 / 20 / 24 / 32px | Icons |
--av-size-avatar-xs … --av-size-avatar-2xl | 24 / 32 / 40 / 48 / 64 / 96px | Avatars |
--av-size-control-sm / md / lg | 32 / 38 / 44px | Buttons, inputs |
--av-size-touch-min | 44px | WCAG 2.5.8 minimum |
--av-sidebar-width | 264px | Expanded sidebar |
--av-sidebar-width-collapsed | 72px | Icon-only sidebar |
--av-topbar-height | 64px | |
--av-drawer-width | 380px | Utility 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.