Appearance
Responsive Strategy
Admin panels are used on phones far more than their designers assume. This is the plan for making that work.
Philosophy
Not "mobile first" in the literal sense — an admin panel's primary device is a laptop, and pretending otherwise leads to desktop layouts that feel like scaled-up phone screens.
Instead: content-driven breakpoints with progressive disclosure. The interface reduces information density as space shrinks, in a defined order:
1920px Everything visible: sidebar, all columns, inline charts, side panels
1440px Side panels become drawers
1200px Low-priority table columns collapse into an expandable row
992px Sidebar becomes off-canvas; bottom nav appears
768px Multi-column forms become single column; split views show one pane
576px Tables become card lists; toolbars collapse into overflow menus
360px Minimum supported width — nothing may scroll horizontallyBreakpoints
| Name | Min-width | What changes |
|---|---|---|
xs | 0 | Base |
sm | 576 | Two-column grids appear |
md | 768 | Split views become two-pane; forms go multi-column |
lg | 992 | Sidebar becomes persistent; bottom nav disappears |
xl | 1200 | Full table columns; 4-column KPI rows |
xxl | 1400 | Side panels appear alongside content |
xxxl | 1800 | Boxed width caps content |
lg is the only breakpoint with structural significance. Everything else is content reflow.
Tables: the hard problem
A nine-column orders table cannot survive on a 375px screen. Two strategies ship, and which one a table uses is an author decision made with a modifier class.
1. Card transformation — .av-table--cards
Below 48rem the table stops being a grid and each row becomes a stacked card, with the column name supplied by an attribute on the cell.
html
<table class="av-table av-table--cards">
<thead>
<tr><th>Order</th><th>Person</th><th>Status</th><th>Total</th></tr>
</thead>
<tbody>
<tr>
<th scope="row" data-av-label="Order">#1042</th>
<td data-av-label="Person">Mark Ellis</td>
<td data-av-label="Status"><span class="av-badge av-badge--success">Paid</span></td>
<td data-av-label="Total" data-av-money="124000"></td>
</tr>
</tbody>
</table>The attribute is data-av-label, not data-label, and the label lives in an attribute rather than a duplicated hidden column for a specific reason: a hidden label column is read out by a screen reader on every row.
scss
@media (width < 48rem) {
.av-table--cards thead { display: none; }
.av-table--cards :is(tbody, tr, th, td) { display: block; }
.av-table--cards tbody tr {
margin-block-end: var(--av-space-3);
border: 1px solid var(--av-border-subtle);
border-radius: var(--av-radius-md);
background: var(--av-surface-raised);
}
.av-table--cards :is(tbody th, td) {
display: flex;
justify-content: space-between;
gap: var(--av-space-4);
text-align: end;
}
.av-table--cards :is(tbody th, td)::before {
content: attr(data-av-label);
color: var(--av-text-muted);
text-align: start;
}
/* A cell with no label would collapse its flex row and push the value to the
start edge, breaking the column of values down the card. */
.av-table--cards :is(tbody th, td):not([data-av-label])::before { content: ''; }
}
roleis deliberately not overridden, and that is worth stating because it looks like an omission. An earlier revision of this page claimed AdminVora swaps inrole="list"/role="listitem"below 576px. It does not, on purpose: changingdisplayon table elements already drops the implicit table semantics in most engines, so there is nothing left to override — and the label text restores exactly what the header row was providing. Adding a list role on top would announce a structure the markup does not otherwise behave like.
It is a plain @media query rather than @container. Container queries do ship in this product — .av-cart-list uses one — but a table's usable width tracks the viewport, and a container query here would need container-type: inline-size on a wrapper that also has to scroll.
2. Horizontal scroll — .av-table-wrap, with .av-table--sticky-col
Right when columns are genuinely comparable and truncation would destroy meaning — financial reports, timesheets, anything a reader scans across rather than down.
html
<div class="av-table-wrap" tabindex="0" role="region" aria-label="Orders, scrollable">
<table class="av-table av-table--sticky-col">…</table>
</div>scss
.av-table-wrap { overflow-x: auto; }
/* The identifying column stays put while the rest scrolls under it. */
.av-table--sticky-col :is(th, td):first-child {
position: sticky;
inset-inline-start: 0;
z-index: var(--av-z-sticky);
background: var(--av-surface-raised);
}
.av-table--sticky-col thead th:first-child { z-index: var(--av-z-topbar); }The corner cell is the whole difficulty. A sticky first column and a sticky header row overlap at the top-left cell, and whichever paints later wins. The header is raised one step so the corner belongs to it, which is the reading most people expect.
tabindex="0" and a named role="region" are both required: a scroll container with no focusable content inside it is unreachable by keyboard without them. That is the same rule .av-code follows.
There are no priority columns: a table does not hide or move cells by width. Below its natural width it scrolls inside .av-table-wrap, or collapses with .av-table--cards.
Forms
Two columns at most, collapsing to one below 768px. .av-field-row is the whole mechanism — there is no grid system to reach for.
html
<div class="av-field-row">
<div class="av-field">
<label class="av-field__label" for="first">First name</label>
<input class="av-input" id="first" name="first">
</div>
<div class="av-field">
<label class="av-field__label" for="last">Last name</label>
<input class="av-input" id="last" name="last">
</div>
</div>
<div class="av-field">
<label class="av-field__label" for="email">Email</label>
<input class="av-input" type="email" id="email" name="email">
</div>scss
.av-field-row {
display: grid;
grid-template-columns: 1fr 1fr;
gap: var(--av-space-4);
}
/* Without this, a long value inside a field pushes the row past the viewport:
a grid item's automatic minimum size is its content's min-content width. */
.av-field-row > * { min-inline-size: 0; }
@media (max-width: 767.98px) {
.av-field-row { grid-template-columns: 1fr; }
}Rules:
- Related short fields pair on a row (first/last, city/postcode); long fields — email, address, description — are always a plain
.av-field - Never three columns.
.av-field-rowis hard-coded to two, deliberately: scanning across three columns of inputs is error-prone, and making the count configurable is how a form ends up with five - Labels are always above inputs, never beside them — beside breaks at every width, in RTL, and on long translations
The rhythm rule has to name every block type in the stack, and this is where that was learned. .av-field + .av-field spaced a form and silently skipped every boundary involving a .av-field-row, because a row is not a field: row → field, field → row and row → row all measured 0px between pairs that got 16. It shipped on the checkout's shipping address, invisible to lint:css (the SCSS is valid) and to tests/visual.mjs (under its floor, and its baseline was recorded from the cramped markup). It is one :is(.av-field, .av-field-row) + :is(…) rule now, and it was found by measuring rather than by looking.
A sticky action bar for long forms does ship, as .av-form-actions--sticky.
Touch
| Requirement | How it is met |
|---|---|
| Comfortable targets | --av-size-touch-min under @media (pointer: coarse), on controls. The single writer is Target size; the short version is 24 CSS px, applied only where the pointer is coarse, and links keep their line height by decision |
| Spacing between targets | The --av-space-2 gap in button groups and table action cells |
| No hover-only interactions | Every :hover affordance also answers to :focus-visible — the rail's flyout label is the clearest case, and no-outline-none in lint:css enforces the general rule |
| No hover-dependent content | Tooltips supplement a label and never replace one; tests/pages.mjs fails on a control whose only name is a tooltip. Where a control is genuinely revealed by hover — the catalogue card's quick actions, the KPI spotlight — a @media (hover: none) block makes it simply present |
| Nothing stays hovered | :hover keeps matching after a tap until the next tap lands elsewhere, so a card that rises on hover stays risen with nothing raising it, and reads as selected. Every lift funnels through --av-lift / --av-lift-sm, and the token layer zeroes both under @media (hover: none) — one answer rather than twelve rules |
| Motion respects the reader | prefers-reduced-motion and the data-av-motion axis are one condition, in the runtime and in the stylesheet alike — see Reduced motion |
Colour-only hover states are deliberately left alone. They persist after a tap too, but that is how every website behaves on a touchscreen, a tint is self-evidently not a control, and neutralising 123 declarations to fight the platform would cost more than it buys.
npm run test:touch measures all of it — every control on every page, with a coarse pointer, and again with a fine one to prove the coarse rules are live.
There are no swipe actions. If you add a gesture, the same action must also exist in the row's overflow menu: a swipe-only action is invisible to keyboard users, screen-reader users and anyone on a desktop.
Images
html
<img src="/img/product-800.webp"
srcset="/img/product-400.webp 400w,
/img/product-800.webp 800w,
/img/product-1600.webp 1600w"
sizes="(max-width: 576px) 100vw,
(max-width: 992px) 50vw,
320px"
alt="Blue canvas backpack, front view"
width="800" height="600"
loading="lazy"
decoding="async">| Attribute | Why |
|---|---|
width + height | Reserves space → no CLS. Required even with srcset. |
loading="lazy" | Below-the-fold only. Never on the LCP image. |
decoding="async" | Does not block the main thread |
sizes | Without it the browser assumes 100vw and downloads the largest source |
scss
img, svg, video, canvas { max-inline-size: 100%; block-size: auto; }Preventing horizontal scroll
The most common responsive bug. These four rules prevent nearly all of it.
scss
/* 1. Constrain media */
img, svg, video, iframe, table, pre { max-inline-size: 100%; }
/* 2. Allow flex/grid children to shrink */
.av-main, .av-content, .av-card, .row > * { min-inline-size: 0; }
/* 3. Break long unbroken strings (URLs, tokens, emails) */
.av-truncate-url, td, .av-card__text { overflow-wrap: anywhere; }
/* 4. Never let a fixed width exceed the viewport */
.av-drawer__panel { inline-size: min(380px, 92vw); }
.av-modal { max-inline-size: min(600px, calc(100vw - 2rem)); }Automated detection:
js
// tests/e2e/responsive.spec.js
const WIDTHS = [320, 375, 414, 768, 1024, 1280, 1920];
for (const width of WIDTHS) {
test(`no horizontal scroll at ${width}px`, async ({ page }) => {
await page.setViewportSize({ width, height: 900 });
await page.goto('/dashboard');
const overflow = await page.evaluate(() =>
document.documentElement.scrollWidth - document.documentElement.clientWidth);
expect(overflow).toBeLessThanOrEqual(0);
// Report the offending element if it fails
if (overflow > 0) {
const culprits = await page.$$eval('*', (els, vw) => els
.filter((el) => el.getBoundingClientRect().right > vw + 1)
.map((el) => el.tagName + '.' + el.className), width);
console.log('Overflowing:', culprits);
}
});
}Viewport and safe areas
html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">viewport-fit=cover enables env(safe-area-inset-*) on notched devices. Without it the insets are always 0.
scss
.av-bottom-nav { padding-block-end: env(safe-area-inset-bottom); }
.av-topbar { padding-block-start: env(safe-area-inset-top); }
.av-drawer__panel {
padding-inline-end: env(safe-area-inset-right);
padding-inline-start: env(safe-area-inset-left);
}Warning — never add
user-scalable=noormaximum-scale=1. It blocks pinch zoom and is a WCAG 1.4.4 failure. iOS ignores it in recent versions; Android does not.
Testing matrix
| Device | Viewport | DPR | Notes |
|---|---|---|---|
| iPhone SE | 375×667 | 2 | Smallest common phone |
| iPhone 15 Pro | 393×852 | 3 | Notch + home indicator |
| Pixel 8 | 412×915 | 2.6 | Android reference |
| iPad Mini | 744×1133 | 2 | Portrait tablet |
| iPad Pro 11" | 834×1194 | 2 | Split-view target |
| Surface Pro | 912×1368 | 2 | Touch + keyboard |
| Laptop | 1366×768 | 1 | Still very common — short viewport |
| Desktop | 1920×1080 | 1 | Reference |
| Ultra-wide | 3440×1440 | 1 | Boxed-width validation |
| 320px | 320×568 | 1 | Absolute minimum |
js
// playwright.config.js
projects: [
{ name: 'mobile', use: { ...devices['iPhone 15'] } },
{ name: 'tablet', use: { ...devices['iPad Pro 11'] } },
{ name: 'desktop', use: { viewport: { width: 1440, height: 900 } } },
{ name: 'wide', use: { viewport: { width: 2560, height: 1440 } } }
]Checklist
- [ ] No horizontal scroll at 320px on any page
- [ ] Sidebar becomes off-canvas below 992px with a working backdrop and Esc
- [ ] Bottom nav appears below 992px with safe-area padding
- [ ] Tables use one of the three documented strategies
- [ ] Scrollable table regions have
tabindex="0"and arole/aria-label - [ ] Every touch target is ≥ 44×44px
- [ ] No hover-only functionality
- [ ] All images have
width,height, andsizes - [ ] LCP image is not
loading="lazy" - [ ]
viewport-fit=coverset; nouser-scalable=no - [ ] Long strings wrap (
overflow-wrap: anywhere) - [ ] Tested at 200% browser zoom — WCAG 1.4.4
Read next: Component Index.