Getting started
Accessibility
What you get for free from native elements, what the theme adds, and the few things you still have to do yourself.
Native semantics
Stock Bootstrap builds its interactive parts out of <div>s and bolts the semantics on with
ARIA and JavaScript. rb-bootstrap starts from the element that already has the right role. The role, the
name, the state and the keyboard handling come from the browser.
| Pattern | Element | What the browser provides |
|---|---|---|
| Collapse, accordion, dropdown | <details> / <summary> | Button role on the summary, expanded/collapsed state, Space and Enter, exclusive groups via name |
| Modal | <dialog> | Dialog role, Escape, top layer, ::backdrop; inert page and focus trap with command="show-modal" |
| Alert dismiss | <dialog open> + <form method="dialog"> | The close button is a real submit button; the alert leaves the tree when closed |
| Tabs, pills | Radio inputs + labels | Arrow-key selection, one tab stop for the whole list, checked state |
| Navbar toggle, button toggle | Checkbox + label | Space toggles, checked state announced |
| Offcanvas, popover, toast | Popover API | Top layer, light-dismiss and Escape (auto), autofocus honoured on open |
| Carousel | Scroll-snap track | Native scrolling, arrow keys when the track has focus, generated scroll buttons where supported |
| Form validation | :user-invalid / :user-valid | Constraint validation, native error bubbles, no premature red fields |
You still own the labels. Give every dialog an aria-labelledby, every icon-only button an
aria-label, and every form control a <label>. See
No JavaScript for the markup of each component.
Keyboard behaviour
Nothing here is scripted. These are the keys each component answers to.
| Component | Keys | Notes |
|---|---|---|
| Collapse, Accordion | Tab to the summary; Space or Enter toggles | An exclusive accordion closes the open item when another opens |
Dropdown (<details>) | Space or Enter opens; Tab walks the items; Space or Enter on the summary closes | No Escape. Use the popover variant for Escape and light-dismiss |
Dropdown (popover) | Enter opens; Tab walks the items; Escape closes | Focus returns to the invoking button |
| Tabs | Tab lands on the selected tab; Left/Right or Up/Down move selection and switch the pane | The radio group is one tab stop, matching the WAI-ARIA tabs pattern |
| Navbar toggler | Space toggles the menu | The hidden checkbox keeps focus; the label shows the ring |
| Modal | Escape closes; Tab cycles the controls | Focus is trapped and the page is inert only with command="show-modal" |
| Offcanvas | Escape closes | popover="manual" turns Escape off |
| Popover | Enter on the trigger opens; Escape closes | Put autofocus on the first control inside |
| Toast | Tab to the close button; Enter or Space | popover="manual", so Escape does not dismiss it |
| Tooltip | Shows on :focus-visible | Only focusable elements get tooltips. Keep the host a button, link or input |
| Carousel | Arrow keys scroll the track when it has focus; indicator links are tab stops | Add tabindex="0" to .carousel-inner if nothing inside it is focusable |
| Button toggle | Space toggles a checkbox; arrows move within a radio group | .btn-check is Bootstrap's own markup |
| Alert dismiss | Enter or Space on the close button | It is a submit button in a method="dialog" form |
Try the radio tabs. Tab into the list, then use the arrow keys.
HTML
<div class="tabs">
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item">
<input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-card" checked />
<label class="nav-link" for="a11y-tab-card">Card</label>
</li>
<li class="nav-item">
<input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-results" />
<label class="nav-link" for="a11y-tab-results">Results</label>
</li>
<li class="nav-item">
<input type="radio" class="nav-check" name="a11y-tabs" id="a11y-tab-tape" />
<label class="nav-link" for="a11y-tab-tape">Tale of the tape</label>
</li>
</ul>
<div class="tab-content pt-3">
<div class="tab-pane">Six matches. Main event: steel cage.</div>
<div class="tab-pane">Winner by pinfall at 14:22.</div>
<div class="tab-pane">Billed height 6'4". Billed weight 275 lb.</div>
</div>
</div>Focus rings
The focus ring is title-belt gold at 40 % opacity, 0.25 rem wide. It is defined once on the root and every
control reads it: buttons, inputs, selects, checks, the .focus-ring helper, and the hidden
radio and checkbox inputs that drive tabs and the navbar toggle (those forward the ring to their label).
:root {
--bs-focus-ring-width: 0.25rem;
--bs-focus-ring-opacity: 0.4;
--bs-focus-ring-color: rgba(184, 148, 31, 0.4); /* gold-700 */
}
[data-bs-theme="dark"] {
--bs-focus-ring-color: rgba(212, 175, 55, 0.4); /* gold-500 */
}
HTML
<button type="button" class="btn btn-primary">Tab to me</button>
<button type="button" class="btn btn-outline-secondary">Then me</button>
<input type="text" class="form-control w-auto" aria-label="Wrestler name" placeholder="Then the input" />
<button type="button" class="btn btn-link focus-ring focus-ring-navy">Navy ring via .focus-ring-navy</button>
Buttons use :focus-visible, so the ring appears for keyboard users and stays out of the way
of mouse clicks. .focus-ring-{color} exists for all eleven theme colors, including
.focus-ring-gold, .focus-ring-navy and .focus-ring-cream. See
Focus ring.
Reduced motion
Bootstrap already drops per-component transitions under prefers-reduced-motion: reduce
($enable-reduced-motion is on). The theme goes one step further and zeroes the shared
transition variables on the root, so anything you build with them stops moving too.
@media (prefers-reduced-motion: reduce) {
:root {
--bs-transition-base: none;
--bs-transition-fade: none;
--bs-transition-collapse: none;
}
}
Also covered: the collapse height animation, the toast auto-hide (it waits, then hides instantly), and smooth scrolling (scroll-behavior: smooth is only set under no-preference).
When you write your own transitions, use var(--bs-transition-base) or the
.transition-base / .transition-fade utilities and you inherit the behaviour. See
Components.
Color contrast
Gold is the brand, and gold is a trap. gold-700 text on the cream page background is about
2.5:1, well short of the 4.5:1 AA target. The theme is set up so the right pairing is the easy one:
- Gold text: use the emphasis variant.
.text-primary-emphasisis a darker gold (#6b5410, about 6:1 on cream). In dark mode it becomesgold-300on navy (about 10:1). - Gold backgrounds:
.btn-primary,.btn-gold,.text-bg-primary,.text-bg-warningand.badge.text-bg-goldall getnavy-900text, chosen by Bootstrap'scolor-contrast()at build time (about 5.9:1 ongold-700, 8:1 ongold-500). - Links:
navy-700on cream in light mode,gold-300on navy in dark. Links stay underlined, so the hover color (gold-700) never carries the meaning alone. - Secondary:
navy-300is a mid tone. Neither cream nor navy clears 4.5:1 on it, so Bootstrap falls back to white text for.btn-secondaryand.text-bg-secondary.
.text-primary — gold-700 on cream. Decorative only.
.text-primary-emphasis — passes AA. Use this for words.
Champion Challenger Program paper
HTML
<p class="text-primary mb-2">.text-primary — gold-700 on cream. Decorative only.</p>
<p class="text-primary-emphasis mb-2">.text-primary-emphasis — passes AA. Use this for words.</p>
<p class="mb-0"><span class="badge text-bg-gold">Champion</span> <span class="badge text-bg-navy">Challenger</span> <span class="badge text-bg-cream">Program paper</span></p>Full tables and the contrast rules are on Color.
Skip links
Every docs page starts with a skip link. It is visually hidden until it receives focus, using Bootstrap's
.visually-hidden-focusable. Press Tab once at the top of this page to see it.
HTML
<a class="visually-hidden-focusable" href="#a11y-skip-target">Skip to the results</a>
<p>Tab into this example and the link appears.</p>
<div id="a11y-skip-target" tabindex="-1" class="p-3 border rounded">Results table would start here.</div><body>
<a class="visually-hidden-focusable" href="#main">Skip to main content</a>
…
<main id="main">…</main>
</body>
Give the target tabindex="-1" when it is not a landmark, so focus actually lands there. See Visually hidden.
Autofocus inside popovers
The Popover API moves focus to the first autofocus element when a popover, offcanvas or modal
opens, and returns focus to the invoker when it closes. Without autofocus a keyboard user has
to Tab across the page to reach the overlay. Add it to the control you expect them to use first.
Search the roster
HTML
<button type="button" class="btn btn-outline-primary" popovertarget="a11y-pop">Find a wrestler</button>
<div class="popover fade" popover id="a11y-pop" data-bs-placement="bottom">
<div class="popover-arrow"></div>
<h3 class="popover-header">Search the roster</h3>
<div class="popover-body">
<label class="form-label" for="a11y-pop-name">Name</label>
<input type="search" class="form-control form-control-sm" id="a11y-pop-name" autofocus placeholder="Macho Man" />
</div>
</div>autofocus. Elements inside a closed popover are not rendered,
so they are skipped at load time and focused only when their popover opens. You can use
autofocus inside several overlays on one page.Checklist
- Headings h1–h3 use the display face. It is a condensed face; keep headings short and never go below 20 px.
- Every
<dialog>and offcanvas hasaria-labelledbyoraria-label. - Toasts carry
role="status"(orrole="alert"for urgent ones) so they are announced when shown. - Tooltip text is CSS-generated and hidden until hover or focus. Do not rely on it for essential information; put that in
aria-labelor visible text. - Do not put a
<details>dropdown inside another button. One interactive element per summary. - Test with the OS in dark mode and with reduced motion on. Both are automatic in this theme, and both change what users see.