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 (details/summary)

A native <details data-menu>. 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 an element up into place as it enters the viewport — a scroll-driven animation (animation-timeline: view()), not an IntersectionObserver, so scrolling back re-hides it. Engines without scroll-driven animations show everything immediately; prefers-reduced-motion turns it off entirely.

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.

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.

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. 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).