Conformance matrix

Guarantees are inherited from native elements plus our focus handling. Proven by the walkthroughs below.

Typography

Heading one

Heading two

Heading three

Heading four

A paragraph. The measure is capped at --bf-content-width (64ch by default) so long text stays readable. Links like this one get a visible underline and offset.

“Barefoot: no boots, no baggage.”

• Unordered list item
• Another item

1. Ordered item
2. Another item

Ctrl + K for the kbd style, inline code next to it.

/* pre + code */
@layer tokens {
  --bf-primary: #1a1a1a;
}

Divider

A separator with a centered label: add data-divider to any element that can hold text (an <hr> can't — it's void). The label stays real content; the hairlines are decorative pseudo-elements.

Section two

Content continues below the divider, exactly where you'd expect it.

Prose

.bf-prose wraps long-form content and adds heading rhythm and section spacing. The element look — blockquote border, pre, table rows — comes from the base and component layers; the wrapper only imposes the pace. The measure is still capped at --bf-content-width (64ch) so lines stay readable.

Media & avatars

Responsive images scale down to their container (max-width: 100% + height: auto in the base layer). .bf-avatar is a circular image; [data-media] locks a ratio box (16:9 by default, data-ratio for others); .card[data-media] is a thumbnail card whose media bleeds to the top edge.

Avatars

Circular, sized from --bf-avatar-size (2.5rem); data-size="sm|lg" for other sizes. Always alt — an avatar is an image like any other.

Avatar group

Wrap avatars in .bf-avatar-group to overlap them; a surface ring keeps each face distinct. Purely visual — semantics and reading order are untouched.

Responsive images

The banner below is 2000px wide; it shrinks to its container and keeps its ratio.

Aspect-ratio embeds

[data-media] locks a ratio box on an img, video, iframe, or any element; the width follows the container and the height follows the ratio.

Thumbnail cards

.card[data-media] leads with media that bleeds to the card's top edge; the body below keeps the card padding.

Featured story

The media bleeds to the card's top edge; the body keeps the standard card padding.

Buttons

Forms

Stepper

A progress tracker for multi-step flows. Native

semantics; the current step gets aria-current="step". Completed steps are styled from the success token. Horizontal (default) and vertical (data-orientation="vertical") variants.

Horizontal

1. 1 Account
2. 2 Profile
3. 3 Confirm

Vertical

1. 1 Shipping
2. 2 Payment
3. 3 Review

Input groups

Wrap an input with a leading icon, currency, or unit in [data-input-group]. The affix shares the input's focus and validation states. Works with input, select, and textarea.

Date, number & email polish

Native pickers and spinners stay; Barefoot themes the surface and ensures validation states apply. Number inputs hide the spinner until hovered/focused; date inputs get a themed calendar button.

Dialog

Native <dialog>. Focus trap + Esc-to-close are built in. The triggers below use the Invoker Commands API (command/commandfor) where the engine supports it — fully declarative opening and closing; engines without it fall back to the same one native line of JS (showModal()). The Popover below is the fully JS-free alternative.

Popover (zero JS)

The Popover API: a button + popovertarget + a [popover] element. No JavaScript anywhere. In engines with anchor positioning each popover pins to its own trigger automatically — the invoker is the anchor (position-area does the placing, no inline styles needed). To pin a popover to something that isn't its invoker, give that element an anchor-name and point position-anchor at it.

The tooltip is a popover="hint": where the engine has interest invokers it appears on hover and focus and dismisses on hover-away; everywhere else popovertarget keeps click-to-show working, and engines without the hint state treat it as a plain popover. Same markup, three tiers of platform support, zero JS.

Dropdown (Popover-API menu)

A native popover menu via <button popovertarget>. Open with Enter, move with Tab, close with Esc.

Accordion (one-at-a-time)

All details share a name, so the browser allows only one open. For true tabs with arrow-key navigation, see the opt-in tabs below.

Tabs (opt-in JS)

WAI-ARIA tabs with roving tabindex and arrow-key navigation, driven by the opt-in js/tabs.js module (zero dependencies, size in the README table). Try ←/→, Home, End.

Carousel (scroll-snap)

Tab to the scroller, then scroll with the arrow keys. Pure CSS. Slides are sized in container units (60cqi = 60% of the carousel's own width) — they adapt to their container, not the viewport. Add data-autoplay (opt-in js/carousel.js) to auto-advance; controls below are wired by the same module. This one carries data-progress: the bar along its bottom edge is a scroll-driven animation (animation-timeline: scroll()), so it tracks your position with no JS.

Reveal (scroll-entry)

data-reveal fades and slides an element into place as it enters the viewport — a scroll-driven animation (animation-timeline: view()), not an IntersectionObserver, so scrolling back re-hides it. Direction variants: data-reveal="left|right|up|down|fade". Engines without scroll-driven animations show everything immediately; prefers-reduced-motion turns it off entirely.

Staggered reveal

data-reveal-group on a container staggers its children's reveal animations sequentially. js/reveal.js sets --bf-reveal-index on each child; without JS all children animate simultaneously.

Scroll-progress bar

data-progress on any scroll container draws a thin bar that fills as you scroll. Uses the ANONYMOUS scroll timeline pattern from the carousel. data-progress="top" pins it to the top; default is bottom.

Parallax

data-parallax on a decorative element makes it scroll at a different speed for a subtle depth effect. Pure CSS via animation-timeline: scroll(); @supports-gated, falls back to static position.

Navigation transitions

Importing view-transition.css opts every same-origin navigation into a root crossfade — MPA pages get SPA-feel transitions with zero JS (@view-transition { navigation: auto }). Shared elements morph when both pages give them the same view-transition-name: the first card below is named on both sides of the link. Engines without support navigate exactly as before.

Barefoot Chroma — One Color, Infinite Theme

Set --bf-primary once and every brand token — hover, subtle, border, focus — auto-generates via oklch(from var(--bf-primary) …) behind an @supports gate. Try the live builder: Barefoot Studio →

Change --bf-primary in Studio and these re-tint instantly — AA is checked at build time.

Icons — CSS-only

[data-icon] via mask: url() + currentColor, sized by --bf-icon-size. 0KB JS, inherits colour.

Command palette — zero JS

<dialog data-command> + <input type="search" list> + popover fallback. Opens with command/commandfor declaratively.

Data grid — resizable columns

table[data-grid] extends the sticky-header table: each <th> is resize: horizontal (drag the inline-end edge). Wrap in a scroll container; stacks at ≤40rem via container query.

Container queries

The same [data-grid] markup adapts to its container, not the viewport — wrap it in .bf-contain to make the container. Narrow box below (14rem) → 1 column; full-width → 3 columns. Zero media queries.

Responsive table

Add data-table="stack" and wrap the table in a query container (here .bf-contain, same as the grid above): below ~40rem (640px) rows stack as cards and the header row hides. Purely presentational — the <th> headers stay in the DOM, so screen readers still announce them.

Sticky header & column

Add data-table="sticky-head" or data-table="sticky-col" — they compose ("sticky-head sticky-col") — and wrap the table in a scroll container with a bounded height/width; that scroller is what the cells stick against. Give the wrapper tabindex="0" (plus a name) so keyboard users can scroll it — tables hold no focusable content of their own. Sticky cells carry an opaque surface so scrolled rows don't show through.

Sortable table (opt-in JS)

Add data-bf-sort to a table and put a real <button> inside each sortable <th>, then load js/table-sort.js. The module reorders <tbody> rows and maintains aria-sort; numeric columns (Points below) compare numerically, text compares locale-aware. No-JS first: without the module the buttons are inert and the table stays plain but valid.

Timeline

Add data-timeline to an ordered list: each entry gets a dot on a connecting spine. The chronology is the native reading order — screen readers hear a plain list.

1. v3.3 — growth batch

   Segmented control, datalist skin, timeline, empty state, toast stacking, sortable tables, Sunset theme.

2. v3.2 — deprecation wave

   The first run of the api.md policy: three surfaces announced, once-per-page notices.

3. v3.1 — platform primitives

   Scroll-driven animations, hint popovers, anchor positioning — all @supports-gated.

Empty state

A class, because there is no native element: .empty-state centers a decorative glyph (aria-hidden — the heading carries the meaning), a muted explanation, and the action out of the emptiness.

Cards & badges

Chips (removable tags)

An inline badge with a real <button> inside. Removal is opt-in JS (js/chips.js) — without the module nothing hides, the × just does nothing. Give each remove button an aria-label naming what it removes.

Breadcrumbs

A nav with a labeled list. The current page is plain text with aria-current="page", not a link.

Pagination

The current page is a <span aria-current="page">, never a link.

Navigation

A topbar <nav> landmark: a .bf-brand, a link list, and the current page marked with aria-current="page". The row wraps on narrow screens — nothing toggles, nothing hides. Pair with .bf-skip-link as the first element in <body>.

Hamburger (opt-in JS). Add a real toggle button and an id on the list, then load js/nav.js: below 40rem of nav width the list collapses behind the button (aria-expanded tracks it, Esc closes and restores focus). No-JS first — without the module the button never renders and the list always stays visible. Resize the window under 40rem to try it.

Layout

.bf-sidebar splits a fixed-ish aside (first child, --bf-sidebar-width = 16rem) from fluid content; when the row can't fit the aside plus at least 60% main it stacks to one column. .bf-sticky pins an element to --bf-sticky-top while its scrolling ancestor moves.

App shell layout

[data-layout="sidebar"] is a CSS Grid app shell: header, sidebar nav, main content, and footer in a named grid. Semantic elements (<header>, <nav>, <main>, <footer>) auto-map to their grid areas. The sidebar gets independent scroll via position: sticky + overflow-y: auto; main scrolls independently.

Grid variants

[data-grid="auto-fit"] flows as many columns as fit, each at least --bf-grid-min (14rem) — no container query needed, the tracks size against the row itself. data-gap="0|1…8" tunes the gap from the spacing scale.

Spacing utilities

The full token scale as layout-only helpers: .bf-mt-* / .bf-mb-* (block-start/end margins), .bf-p-* (all-sides padding), .bf-px-* / .bf-py-* (inline/block padding), each mapped to --bf-space-1…8.

Alerts & status tokens

Role-aware notices styled from the status tokens. Pick the ARIA role for the semantics — role="alert" for errors, aria-live="polite" for updates — and Barefoot paints it. Dismissible alerts pair a [data-alert-dismiss] button with the opt-in js/alert-dismiss.js module.

Field validation

:user-invalid / :user-valid fire only after a control is touched — nothing flashes before it. Touched textual fields also draw a shape cue at the inline end (check = valid, cross = invalid); the state hue stays on the border. Under forced-colors: active the invalid border goes dashed and focus regains a real outline. Pair with aria-invalid for script-driven forms and aria-describedby for the message.

Spinner

An indeterminate loading indicator, pure CSS: mark any element with data-spinner (data-size="sm|lg" for other sizes). The motion is decorative — it freezes under prefers-reduced-motion, so pair it with text that announces progress; role comes from your markup.

Skeleton

Pure-CSS loading placeholders. Add .skeleton to any element; the shimmer is decorative and static under prefers-reduced-motion. Always replace with real content — the placeholder is never announced.

Toast

A status notice pinned to the bottom edge, built on the Popover API — declarative, JS-free. Toasts are popover="manual": they don't light-dismiss, so an app opens them when work finishes and closes them on a timer or their Close button — exactly how several stay open at once. Use role="status" for non-urgent, role="alert" for urgent. Sibling toasts stack upward: each open one lifts above the open siblings after it (pure CSS; engines without the pieces used simply overlap, newest on top). Add data-duration for auto-dismiss (opt-in js/toast.js).

Adaptive components (v5.0)

Each component senses its container, not the viewport. The same markup renders stacked in a sidebar and full in the main column. Drag a box's right edge to see it morph — or set data-density="compact" on <html> to compress them all.

WCAG AA — native semantics are preserved, so keyboard and screen-reader behavior are unchanged (see the conformance table).

Table → card-stack

A data-table="adaptive" table card-stacks when its own width drops below --bf-adaptive-2. Cells carry data-label for the card captions.

Segmented density

A [data-segmented][data-adaptive] compresses its labels when narrow or under data-density="compact".

Form reflow

A form[data-form="adaptive"] collapses its .bf-row to one column when narrow, and reveals an error summary via :has(:user-invalid).

Card morph

A .card[data-card="adaptive"] lays out horizontally when wide, vertically when narrow.

Tabs — scroll-snap ↔ wrap

A [data-bf-tabs][data-adaptive] keeps a single scroll-snapping row when wide and wraps to multiple rows when narrow. No .bf-contain needed — the group self-containers.

Nav — drawer by container

A [data-nav="drawer"] collapses to an off-canvas drawer when its container is narrow (here a ~22rem slot) and stays an inline row in a wide slot. Reuses the same hamburger toggle.

Auto-wrap (no manual .bf-contain)

The table below is dropped straight into a plain <div> — no .bf-contain. The adaptive rule auto-establishes the container on its parent, so it still card-stacks when narrow.

Verify — the framework checks your laces

The dev-only js/verify.js checker audits Barefoot's own markup contracts — the ones axe can't know — and the badge in the corner shows the live result. Break a contract and it flips ✗, with the exact fix named in the console (docs/verify.md).

Try it: click Break, watch the badge, read the console, then Fix. The checker never mutates the DOM — the stage controls do, and the badge only reports.