Skip to content

Cards & Surfaces ​


Card ​

html
<div class="av-card">
  <div class="av-card__header">
    <div>
      <h2 class="av-card__title">Recent activity</h2>
      <p class="av-card__subtitle">Last 7 days</p>
    </div>
    <div class="av-dropdown">
      <button class="av-btn av-btn--ghost av-btn--icon av-btn--sm" type="button"
              data-av-dropdown-toggle aria-expanded="false" aria-haspopup="menu"
              aria-label="Card options">
        <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><circle cx="12" cy="5" r="1.4"/><circle cx="12" cy="12" r="1.4"/><circle cx="12" cy="19" r="1.4"/></svg>
      </button>
      <ul class="av-dropdown__menu" role="menu">…</ul>
    </div>
  </div>

  <div class="av-card__body">…</div>

  <div class="av-card__footer">
    <a href="/activity" class="av-btn av-btn--sm av-btn--ghost">View all</a>
  </div>
</div>
scss
@layer components {
  .av-card {
    --av-card-padding:      var(--av-space-5);
    --av-card-radius:       var(--av-radius-lg);
    --av-card-bg:          var(--av-surface-raised);
    --av-card-border:      1px solid var(--av-border-subtle);
    --av-card-shadow:      var(--av-shadow-sm);
    --av-card-header-border: 1px solid var(--av-border-subtle);

    background: var(--av-card-bg);
    border: var(--av-card-border);
    border-radius: var(--av-card-radius);
    box-shadow: var(--av-card-shadow);

    &__header {
      display: flex;
      align-items: flex-start;
      justify-content: space-between;
      gap: var(--av-space-3);
      padding: var(--av-card-padding);
      border-block-end: var(--av-card-header-border);
      background: transparent;
    }

    &__title {
      font-size: var(--av-font-size-base);
      font-weight: var(--av-font-weight-semibold);
      margin: 0;
    }

    &__subtitle {
      font-size: var(--av-font-size-sm);
      color: var(--av-text-muted);
      margin: var(--av-space-1) 0 0;
    }

    &__body   { padding: var(--av-card-padding); }
    &__footer {
      padding: var(--av-space-3) var(--av-card-padding);
      border-block-start: var(--av-card-header-border);
      background: transparent;
    }

    /* Modifiers */
    &--flush    { --av-card-border: 0; --av-card-shadow: none; }
    &--bordered { --av-card-shadow: none; --av-card-border: 1px solid var(--av-border-default); }
    &--compact  { --av-card-padding: var(--av-space-4); }
    &--elevated { --av-card-shadow: var(--av-shadow-md); }

    /* Full-bleed body — for tables and charts */
    &--flush-body .av-card__body { padding: 0; }
  }
}

contain: layout style used to be on this rule and was removed. It was set for the reflow win, with paint deliberately omitted so the hover shadow could still draw outside the box — but layout containment also makes the element a stacking context and an absolute containing block, so every dropdown opened inside a card had its z-index: var(--av-z-popover) scoped to that card and the next card painted straight over the open menu. Nothing was clipped and nothing measured wrong, which is why it read as an overflow bug and sent the first investigation somewhere there was nothing to find. Containment is a performance hint; a menu you cannot read is a broken control.

container-type: inline-size went with it. If you add it back for container queries, know that it establishes a containment context too and test every dropdown inside a card.

Rules ​

RuleReason
One <h2>–<h4> per card, matching the page's heading levelDocument outline
Cards do not nestNested cards are a hierarchy failure — use a section with a heading
Card header borders are optionalWhitespace usually reads better; use --av-card-header-border: 0
Tables and charts get --flush-bodyPadding around a full-width table wastes space
Never put layout margins inside a cardLayout owns spacing between cards

Stat card ​

html
<div class="av-stat-card">
  <div class="av-stat-card__head">
    <span class="av-stat-card__label">Revenue</span>
    <span class="av-stat-card__icon">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M12 3v18M16 7H10a3 3 0 0 0 0 6h4a3 3 0 0 1 0 6H8"/></svg>
    </span>
  </div>

  <div class="av-stat-card__value"
       data-av-countup="48250"
       data-av-countup-currency="EUR">€48,250</div>

  <div class="av-stat-card__foot">
    <span class="av-trend av-trend--up">
      <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/></svg>
      12.4%
    </span>
    <span>vs last month</span>
  </div>

</div>

There is no sparkline slot on the stat card. Earlier versions of this page showed an av-stat-card__spark element fed by data-av-chart-series; neither the class nor that attribute exists. The stat card carries a label, a value, an icon and a trend foot, and takes a top accent bar. To put a chart beside a number, use a card with a data-av-chart element in its body.

Colour comes from position, and a role overrides it. A row of stat cards is categorical, the way a chart is: four figures told apart by hue. Each card reads --av-tile-1 to --av-tile-4 by its place among its siblings (:nth-child(4n + k)), and those come from the preset's curated palette (series 2 to 4), so the row belongs to the theme in every preset. Tile 1 is always --av-color-primary.

How much colour a tile carries is the style's KPI recipe: five numbers on <html> (--av-kpi-fill, -edge, -chip, -glow, -bar) that say how much of the tile's colour fills it, tints its edge and its icon chip, how strong a glow it casts and whether it has the accent bar. Each UI style sets its own (Theme Presets); bold fills every tile outright. data-av-depth="plain" asks for the outline tile whatever the preset says, and av-stat-card--vivid fills the whole tile with its colour, deepened so white ink clears 4.5:1, when one figure deserves it.

A role says what the number means and wins over position: av-stat-card--danger on an overdue-receivables tile, av-stat-card--success on a figure that is good news by definition, or the same words on the icon (av-stat-card__icon--danger, matched with :has() so the bar and the icon cannot disagree). Do not use a role as decoration. "Orders" is not a warning, and the roles are fixed status hues that ignore the preset, which is how every dashboard once opened on a blue, amber and green strip whatever theme was chosen.

scss
.av-stat-card {
  --av-stat-card-value-size: var(--av-font-size-3xl);

  position: relative;
  display: flex;
  flex-direction: column;
  gap: var(--av-space-3);
  padding: var(--av-space-5);
  background: var(--av-surface-raised);
  border: 1px solid var(--av-border-subtle);
  border-radius: var(--av-radius-lg);
  overflow: hidden;
  container-type: inline-size;

  &__label {
    font-size: var(--av-font-size-sm);
    font-weight: var(--av-font-weight-medium);
    color: var(--av-text-muted);
  }

  &__icon {
    display: grid;
    place-items: center;
    inline-size: 40px;
    block-size: 40px;
    border-radius: var(--av-radius-md);
    background: var(--av-color-primary-subtle);
    color: var(--av-color-primary-text);

    &--success { background: var(--av-color-success-subtle); color: var(--av-color-success-text); }
    &--warning { background: var(--av-color-warning-subtle); color: var(--av-color-warning-text); }
    &--danger  { background: var(--av-color-danger-subtle);  color: var(--av-color-danger-text); }
  }

  &__value {
    font-size: var(--av-stat-card-value-size);
    font-weight: 650;
    line-height: var(--av-line-height-tight);
    letter-spacing: var(--av-tracking-tight);
    font-variant-numeric: tabular-nums;
  }

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

The hero tile ​

A row of equal tiles gives the eye nowhere to land. Mark the one figure the row is about with av-stat-card--hero, together with av-stat-card--vivid, on the first tile. It gets a display-size figure in the display face and a slow sheen that crosses it. Add av-grid--lead to a four-tile av-grid--stats row and the first tile takes a wider track from 1400px; below that width the row is an ordinary stats row.

html
<div class="av-grid av-grid--stats av-grid--lead">
  <div class="av-stat-card av-stat-card--vivid av-stat-card--hero">
    <div class="av-stat-card__head">
      <span class="av-stat-card__label">Revenue</span>
    </div>
    <div class="av-stat-card__value">€48,250</div>
    <div class="av-stat-card__foot">
      <span class="av-trend av-trend--up">
        <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/></svg>
        12.4%
      </span>
      <span>vs last month</span>
    </div>
  </div>

  <div class="av-stat-card">
    <div class="av-stat-card__head">
      <span class="av-stat-card__label">Active users</span>
    </div>
    <div class="av-stat-card__value">8,421</div>
    <div class="av-stat-card__foot">
      <span class="av-trend av-trend--up">
        <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/></svg>
        3.2%
      </span>
      <span>vs last month</span>
    </div>
  </div>

  <div class="av-stat-card">
    <div class="av-stat-card__head">
      <span class="av-stat-card__label">Orders</span>
    </div>
    <div class="av-stat-card__value">1,236</div>
    <div class="av-stat-card__foot">
      <span class="av-trend av-trend--down">
        <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 7l6 6 4-4 8 8"/><path d="M15 17h6v-6"/></svg>
        1.8%
      </span>
      <span>vs last month</span>
    </div>
  </div>

  <div class="av-stat-card">
    <div class="av-stat-card__head">
      <span class="av-stat-card__label">Conversion</span>
    </div>
    <div class="av-stat-card__value">3.42%</div>
    <div class="av-stat-card__foot">
      <span class="av-trend av-trend--up">
        <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/></svg>
        0.4pt
      </span>
      <span>vs last month</span>
    </div>
  </div>
</div>
  • One hero a row, first in the row. av-grid--lead lays out exactly four tiles (1.6fr repeat(3, minmax(0, 1fr))), so use it only on a row of four.
  • Keep av-stat-card--vivid on it. The fill and its ink come from the vivid tile, which is where the 4.5:1 contrast is measured; the hero modifier adds the figure size and the sheen.
  • Under 576px the row is two tiles wide and the hero's figure drops back to the ordinary size.
  • A style may redraw it. Luxe draws the hero in gold leaf with dark ink, and glass gives it an edge and a halo in the accent.

A sparkline in the tile ​

Put a chart in sparkline mode after the foot to draw the figure's own trend. .av-stat-card__spark reserves the height, so the tile does not grow when the chart arrives.

html
<div class="av-stat-card">
  <div class="av-stat-card__head">
    <span class="av-stat-card__label">Active users</span>
  </div>
  <div class="av-stat-card__value">8,421</div>
  <div class="av-stat-card__spark" data-av-chart
       data-av-chart-options='{ "type": "area", "height": 44, "legend": false, "sparkline": true, "colors": ["success"], "series": [{ "name": "Active users", "data": [26, 26, 33, 34, 34, 43, 44, 50, 54, 51] }] }'
       role="img"
       aria-label="Sparkline of active users, rising over the last ten periods."></div>
</div>

Spotlight and entrance ​

Every stat card lights up under the pointer, in its own colour; a vivid tile is lit with the highlight instead. You add no class and no hook: the runtime binds .av-stat-card the way it binds .av-spotlight and writes the pointer position into --av-spotlight-x and --av-spotlight-y. The light defaults to the tile's centre and is not drawn on a device that cannot hover. On the hero tile the sheen takes its place. The runtime does not watch for new content, so call AdminVora.init() after you insert tiles.

Stat cards rise in one after another when the page loads, each delayed by its place among its siblings. prefers-reduced-motion: reduce and data-av-motion="reduced" or "off" remove the entrance and the sheen.

Trend indicator ​

scss
.av-trend {
  display: inline-flex;
  align-items: center;
  gap: var(--av-space-1);
  font-size: var(--av-font-size-sm);
  font-weight: var(--av-font-weight-medium);

  &--up   { color: var(--av-color-success-text); }
  &--down { color: var(--av-color-danger-text); }
  &--flat { color: var(--av-text-muted); }
}

Important — "up" is not always good. Increased refunds, churn, or error rate should show --down colouring for an up arrow. Pair a direction modifier with a semantic one: av-trend--up av-trend--bad. Getting it wrong actively misleads people reading a dashboard.

The four rules are deliberately written separately rather than grouped into two selectors. Grouped, all four sit at 0-1-0 and source order decides a mixed pair — an element carrying --down --good matched the later rule and painted churn-is-falling in red, the exact reading the comment above it warned against. No page had used a mixed pair, so the documented behaviour had simply never been true. The semantic pair is last.

html
<span class="av-trend av-trend--up av-trend--bad">
  <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/></svg>
  8.2%
  <span class="av-visually-hidden">increase in refunds, which is unfavourable</span>
</span>

Hero band ​

The one expressive moment a dashboard is allowed: a greeting, the date and today's figures on a band of the preset's own primary, with the accent tinting one corner. The fill is the primary deepened to at most 42% lightness, so white ink clears 4.5:1 on every preset by construction. Use it once, at the top; everything below stays calm, which is what makes it read as the top of the page.

html
<section class="av-hero-band" aria-labelledby="heroTitle">
  <div class="av-hero-band__head">
    <div>
      <h2 class="av-hero-band__title" id="heroTitle">Good morning, Florin</h2>
      <p class="av-hero-band__text">Here is how the store is doing so far today.</p>
    </div>
    <span class="av-hero-band__date">Today</span>
  </div>
  <dl class="av-hero-band__stats">
    <div class="av-hero-band__stat">
      <dt class="av-hero-band__label">Orders today</dt>
      <dd class="av-hero-band__value">47</dd>
      <dd class="av-hero-band__delta">12% more than this time yesterday</dd>
    </div>
  </dl>
</section>

KPI card with target ​

The bar is driven by a custom property, not a fill element. --av-kpi-progress on the root sets the width, and av-kpi--ahead|--at-risk|--behind sets the colour. One element and one value, rather than a __bar wrapping a __bar-fill whose inline width has to be kept in step with the aria-valuenow beside it — two numbers describing one fact is two numbers that can disagree.

html
<div class="av-kpi av-kpi--ahead" style="--av-kpi-progress: 68%">
  <span class="av-kpi__label">Conversion rate</span>
  <p class="av-kpi__value">3.42%</p>
  <div class="av-kpi__bar" role="progressbar" aria-valuenow="68" aria-valuemin="0"
       aria-valuemax="100" aria-label="68% of monthly target"></div>
  <span class="av-kpi__target">68% of 5.0% target</span>
</div>

Media card ​

html
<article class="av-card av-card--media">
  <img class="av-card__media"
       src="/img/product-800.webp"
       srcset="/img/product-400.webp 400w, /img/product-800.webp 800w"
       sizes="(max-width: 576px) 100vw, 320px"
       alt="Blue canvas backpack, front view"
       width="800" height="450" loading="lazy" decoding="async">
  <div class="av-card__body">
    <h3 class="av-card__title"><a href="/products/42">Canvas backpack</a></h3>
    <p class="av-card__subtitle">Water-resistant 24L daypack with a padded laptop sleeve.</p>
  </div>
  <div class="av-card__footer">
    <span>€89.00</span>
    <span class="av-badge av-badge--success-soft">In stock</span>
  </div>
</article>

.av-card__media is a block-level image or a role="img" element with a background-image — the build uses the second form for the gradient covers on the UI-kit layout page. Give it explicit width/height so the card does not reflow when the image lands.

Link the title, not the card. Wrapping the whole card in an <a> swallows the price and the badge into the link's accessible name, which is then read as "Canvas backpack Water-resistant 24L daypack with a padded laptop sleeve €89.00 In stock, link".

There is no .stretched-link in this build. It is a Bootstrap utility, and earlier versions of this page recommended it. If you want the whole card clickable, put the anchor on the title and add a ::after covering the card from a rule you own — but weigh it first: a stretched link kills text selection inside the card and covers any secondary button in it.


Pricing card ​

html
<div class="av-pricing-card av-pricing-card--featured av-spotlight">
  <p class="av-pricing-card__name">Professional</p>
  <p class="av-pricing-card__price">€49<span class="av-pricing-card__period">/month</span></p>

  <ul class="av-pricing-card__features">
    <li>Unlimited projects</li>
    <li>25 team members</li>
    <li><span class="av-visually-hidden">Not included: </span>SSO</li>
  </ul>

  <a class="av-btn av-btn--primary av-btn--block av-pricing-card__cta" href="/signup?plan=pro">
    Start free trial
  </a>
</div>

The price is one element — €49 with the period nested inside it — rather than a currency, an amount and a period as three siblings. Splitting them means three baselines to align by hand, and a screen reader reads "euro 49 slash month" as three separate runs.

The visually-hidden "Not included:" text is essential — a grey X icon means nothing to a screen reader. Add av-btn--block rather than a width utility: the CTA is a button that fills its card, and there is no w-100 in this build.


Profile card ​

There is no .av-profile-card component. Build one from the card primitives — the cover is av-card__media and the rest is an ordinary body:

html
<div class="av-card av-card--interactive">
  <div class="av-card__media" role="img" aria-label="Jane Cooper's cover image"
       style="background-image: var(--av-gradient-brand); block-size: 96px"></div>
  <div class="av-card__body">
    <span class="av-avatar av-avatar--xl" aria-hidden="true">JC</span>
    <h3 class="av-card__title">Jane Cooper</h3>
    <p class="av-card__subtitle">Head of Operations</p>

    <dl class="av-detail-list">
      <dt>Projects</dt><dd>24</dd>
      <dt>Tasks</dt><dd>142</dd>
      <dt>Team</dt><dd>8</dd>
    </dl>
  </div>
  <div class="av-card__footer">
    <button class="av-btn av-btn--sm av-btn--primary" type="button">Message</button>
    <button class="av-btn av-btn--sm av-btn--outline" type="button">View profile</button>
  </div>
</div>

A <dl> is the correct element for label/value pairs; av-detail-list is the styled version this build ships, and it is also what the order-detail page uses.

av-card--interactive opts the card into the hover lift. It is opt-in on purpose: a static reporting card that rises under the pointer implies it can be clicked, and most cards cannot.


Glass panel ​

html
<div class="av-glass av-glass--strong">
  <h2>Sign in</h2>
  …
</div>

Rules and costs: Elevation & Depth.


Gradient-border card ​

html
<div class="av-card av-border-gradient"
     style="--av-bg-from: var(--av-color-primary); --av-bg-to: var(--av-violet-500)">
  …
</div>

Panel ​

A lighter-weight surface for grouping inside a card or a page section.

html
<section class="av-panel">
  <header>
    <h3 class="av-panel__title">Shipping address</h3>
    <button class="av-btn av-btn--sm av-btn--ghost">Edit</button>
  </header>
  <div>
    <address>
      Mark Ellis<br>12 Dame Street<br>Dublin 2, D02 XY45<br>Ireland
    </address>
  </div>
</section>
scss
.av-panel {
  background: var(--av-surface-sunken);
  border-radius: var(--av-radius-md);
  padding: var(--av-space-4);

  &__header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    margin-block-end: var(--av-space-3);
  }
  &__title {
    font-size: var(--av-font-size-sm);
    font-weight: var(--av-font-weight-semibold);
    color: var(--av-text-muted);
    text-transform: uppercase;
    letter-spacing: var(--av-tracking-wide);
    margin: 0;
  }
}

Card layouts ​

html
<!-- Fixed ratios -->
<div class="av-grid av-grid--stats">
  <div>…</div>
</div>

<!-- Auto-fit, no media queries -->
<div class="av-grid" style="--av-grid-min: 280px">
  <div class="av-card">…</div>
  <div class="av-card">…</div>
</div>

<!-- Two equal columns that stack on narrow screens -->
<div class="av-grid av-grid--half">
  <div class="av-card">
    <div class="av-card__body">…</div>
    <div class="av-card__footer">…</div>
  </div>
  <div class="av-card">…</div>
</div>

The layout classes this build ships are av-grid with --stats, --half and --main, plus av-stack-4. That is the whole set, and it is deliberately small: a named grid per real layout beats a column system whose class list has to be kept in step across four breakpoints. There is no av-switcher, and no row/col-*.

Grid and flex items that can hold a table need min-inline-size: 0 — .av-grid > * sets it. An item's automatic minimum size is its content's min-content width, so a wide table grows its track past the viewport instead of scrolling inside its own av-table-wrap.


States ​

html
<!-- Loading -->
<div class="av-card is-loading" aria-busy="true">
  <div class="av-card__body">
    <div class="av-skeleton" style="inline-size:40%;block-size:14px"></div>
    <div class="av-skeleton" style="inline-size:70%;block-size:28px"></div>
  </div>
</div>

<!-- Interactive (whole card is a link) -->
<a class="av-card av-card--interactive av-lift" href="/projects/42">…</a>

<!-- Selected -->
<div class="av-card av-card--interactive is-selected" aria-selected="true">…</div>

<!-- Disabled — see the note below: style this one yourself -->
<div class="av-card" aria-disabled="true">…</div>

is-selected ships in the stylesheet; a disabled card does not. Style [aria-disabled="true"] in your own layer, as in the rule below. aria-disabled is the part that matters either way — it is what a screen reader reads, and unlike disabled it keeps the element in the tab order so the user can still discover why it is unavailable.

scss
.av-card--interactive {
  display: block;
  text-decoration: none;
  color: inherit;
  cursor: pointer;

  &:focus-visible {
    outline: var(--av-focus-width) solid var(--av-focus-color);
    outline-offset: var(--av-focus-offset);
  }
}

.av-card.is-selected {
  border-color: var(--av-color-primary);
  box-shadow: 0 0 0 1px var(--av-color-primary);
}

.av-card[aria-disabled="true"] {
  opacity: .6;
  pointer-events: none;
  filter: grayscale(.4);
}

Accessibility checklist ​

  • [ ] Card titles use the correct heading level for the page outline
  • [ ] Interactive cards are <a> or <button>, or use .stretched-link
  • [ ] The whole card is never wrapped in <a> if it contains other meaningful content
  • [ ] Media has alt, width, height, and sizes
  • [ ] Decorative sparklines and cover images are aria-hidden / alt=""
  • [ ] Icons paired with text or a visually-hidden label
  • [ ] aria-busy during load
  • [ ] aria-selected / aria-disabled match the visual state
  • [ ] Hover lift is guarded by (hover: hover) and prefers-reduced-motion
  • [ ] Cards do not nest

Read next: Navigation.

Documentation for @creativeigniter/adminvora