Skip to content

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 horizontally

Breakpoints ​

NameMin-widthWhat changes
xs0Base
sm576Two-column grids appear
md768Split views become two-pane; forms go multi-column
lg992Sidebar becomes persistent; bottom nav disappears
xl1200Full table columns; 4-column KPI rows
xxl1400Side panels appear alongside content
xxxl1800Boxed 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: ''; }
}

role is deliberately not overridden, and that is worth stating because it looks like an omission. An earlier revision of this page claimed AdminVora swaps in role="list" / role="listitem" below 576px. It does not, on purpose: changing display on 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-row is 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 ​

RequirementHow 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 targetsThe --av-space-2 gap in button groups and table action cells
No hover-only interactionsEvery :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 contentTooltips 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 readerprefers-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">
AttributeWhy
width + heightReserves 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
sizesWithout 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=no or maximum-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 ​

DeviceViewportDPRNotes
iPhone SE375×6672Smallest common phone
iPhone 15 Pro393×8523Notch + home indicator
Pixel 8412×9152.6Android reference
iPad Mini744×11332Portrait tablet
iPad Pro 11"834×11942Split-view target
Surface Pro912×13682Touch + keyboard
Laptop1366×7681Still very common — short viewport
Desktop1920×10801Reference
Ultra-wide3440×14401Boxed-width validation
320px320×5681Absolute 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 a role/aria-label
  • [ ] Every touch target is ≥ 44×44px
  • [ ] No hover-only functionality
  • [ ] All images have width, height, and sizes
  • [ ] LCP image is not loading="lazy"
  • [ ] viewport-fit=cover set; no user-scalable=no
  • [ ] Long strings wrap (overflow-wrap: anywhere)
  • [ ] Tested at 200% browser zoom — WCAG 1.4.4

Read next: Component Index.

Documentation for @creativeigniter/adminvora