Changelog

Popovers show more next to the button that opened them, like a set of filters or a hint with a link, without blocking the page. The Popover page walks you through building one on the popover attribute, from the Button with popovertarget that opens it, before any script loads, to the Escape that closes it without closing the Dialog behind it.

New

• The Popover is a non-modal role="dialog", named by its title, which the browser puts in the top layer and closes on Escape and on a press outside.
• Focus moves in when it opens and goes back to its trigger when it closes from inside, and close says why it closed, like escape or outside.
• Escape closes only the layer on top, so a Tooltip inside a Popover, and a Popover inside a Dialog, each close on their own.
• It opens beside its trigger, with the Tooltip's placement names, flips when there's no room and stays inside the screen, down to 320px wide and at 400% zoom.
• It comes with its own contract, live examples and a tested reference implementation.

Improved

• The Dialog, the Tooltip and the Button now link to the Popover, and the Button's Filters example sets aria-haspopup="dialog", while the Popover sets aria-expanded.

Radio groups let people pick one answer out of a few, and they're easy to get subtly wrong, like a question screen readers never read, or a red border that only sighted people notice. The Radio Group page walks you through building one the right way, from the legend that asks the question to the error message that says what to do.

New

• The Radio Group is built on native radios in a <fieldset>, named by its <legend>, so the browser handles the keyboard: one Tab stop per group, and arrow keys that move, check and wrap round.
• Its radios have the Input's heights, so a radio lines up with an input beside it, and their labels are part of what people press, so every radio is at least 24 × 24px.
• Its radios stack, one per line, apart from two short options, like "Yes" and "No", which can sit side by side with orientation="horizontal".
• Its invalid look comes from aria-invalid on the group, which takes the radiogroup role so screen readers can announce it, and its error message sits above the radios, where people read it before they choose again.
• It comes with its own contract, live examples and a tested reference implementation.

Checkbox groups let people pick any number of options from a short list, and most of what goes wrong with them is what holds the boxes together. The Checkbox Group page walks you through building one the right way, from a <fieldset> that its question names to a select-all box that turns mixed when some options are checked, and checks them all with one press.

New

• The Checkbox Group is a <fieldset> of Checkboxes, named by its <legend> and described by its hint and error message, so screen readers announce the question along with its options.
• Its value is a list, sent with one shared name, and its options run in a column by default, so they're quick to scan and fit on any screen.
• Its select-all box is worked out from the options every time they change, and checks every option, or clears them all, as the APG asks.
• Its checklist covers how forms use it too, like saying "Pick at least one" when people have to, and checking it in your own code, since HTML's required doesn't fit a group.
• It comes with its own contract, live examples and a tested reference implementation, built out of the Checkbox's.

Textareas are where people write more than a line, and they're often built as an input that's a few lines taller. The Textarea page walks you through building one the right way, from a height that fits what people are about to write to a limit that never cuts off what they paste.

New

• The Textarea has the Input's sizes, padding and states, so the two line up in a form, and a textarea of one row is exactly as tall as an input.
• Its height starts at rows and never goes below it. People resize it on the block axis, or it grows with its text, up to maxRows.
• Its count lets people type and paste past a limit, says by how much, and is announced to screen readers once they pause, rather than on every keystroke.
• Enter always starts a new line, and its checklist covers how forms use it too, like stating a limit in the hint and never making Enter send a message.
• It comes with its own contract, live examples and a tested reference implementation.

Checkboxes let people say yes or no to one thing, and the browser has had one built in for as long as there have been forms. Its box is hard to style, though, so many teams rebuild it, and that's where it goes wrong. The Checkbox page walks you through building one the right way, from a label that toggles the box to a "Select all" that screen readers announce as mixed.

New

• The Checkbox wraps its own label around the box, so the text names it and a press on the text toggles it, and the box sits in a hit area of at least 24 × 24px at every size.
• It takes the Button's and the Input's sizes, and shows checked, indeterminate, disabled, read-only and invalid with a look of their own, each read from the <input>, so what people see always matches what screen readers announce.
• Its checklist covers how forms use it too, like keeping labels positive, saying why a required box needs checking, and remembering that an unchecked box sends nothing.
• It comes with its own contract, live examples and a tested reference implementation, ready for the Checkbox Group that's next on our Roadmap.

Tooltips are small and everywhere, which is why they so often only work for a mouse. The Tooltip page walks you through building one that opens for the keyboard too, stays open while people read it and closes with Escape. The other overlays on our Roadmap, like the Popover and the Dialog, will follow its rules for the top layer and Escape.

New

• A tooltip either shows an icon-only button's own label, hidden from screen readers so they don't hear it twice, or describes its trigger with aria-describedby.
• It opens in the top layer and finds its place with CSS anchor positioning, flipping when there's no room, with a short script for browsers that don't have it yet. An arrow, on by default, points at its trigger from whichever side it opens on.
• Its checklist covers WCAG's rules for content on hover or focus, and the rules for the screens that use it, like never putting anything people need only in a tooltip, since a tap never opens one.
• It comes with its own contract, live examples and a tested reference implementation.

Cards group what people need to know about one thing, like a project or a product, and they're easy to build so that only a mouse can use them. The Card page walks you through building one the right way, from a heading that people can find it by to a link that covers the whole card without swallowing its text.

New

• A card that takes people somewhere has one link, in its heading, stretched over the card, so the link is named by the heading alone, and its actions, like Save, stay Buttons of their own.
• It has a header, a body, actions and a footer, with no borders between them, so a card reads as one block, and a separator adds a line only where a page needs one.
• Its heading comes first in the DOM, at the level you give it, while its image and eyebrow are shown above it, so people who move from heading to heading land at the start of the card.
• Its checklist covers how pages use it too, like putting cards in a list, describing their images and writing headings that say where the link goes.
• It comes with its own contract, live examples and a tested reference implementation.

Dialogs ask for someone's full attention, and most of what they do happens out of sight, in focus and in the accessibility tree, which is why they're so often broken for keyboard and screen reader users. The Dialog page walks you through building one the right way, from moving focus in when it opens to giving it back to the button that opened it when it closes.

New

• The Dialog is a native <dialog>, opened with showModal(), so the page behind it is inert and Tab never wanders off into it.
• It's named by its title and described by its description, and alert dialogs, for confirmations, have no close button and ignore a stray click outside.
• It asks, rather than closing itself. Escape, the close button, the backdrop and a <form method="dialog"> each fire close with the reason, so you can keep it open when people would lose what they've typed, and when a browser closes it anyway, close fires with closed, so your code can follow.
• It comes with its own contract, live examples and a tested reference implementation.

Switches turn a setting on or off, and they're so familiar that it's easy to forget what makes them work. The Switch page walks you through building one the right way, from a label that names the setting and never changes to a change that applies as soon as people flip it.

New

• The Switch is a native checkbox with the switch role, so Space, its label and its form work before any script loads, and screen readers announce it as on or off.
• On and off differ by more than colour, its track and thumb have 3:1 against what's next to them, and it takes the Input's sizes and states, read-only included, with a hit area of at least 24 × 24px.
• Its checklist covers how screens use it too, like applying a setting right away rather than waiting for a Save button, saying when the change is saved and moving the switch back if it fails.
• It comes with its own contract, live examples and a tested reference implementation.

Our MCP server gives your agents the standard as tools, but they still need to know when to reach for it, and its prompts only run when you start them. Our agent plugin brings the two together: skills that your agent picks up on its own whenever it builds or reviews a component, and the MCP server they read the standard from.

New

• Install it in VS Code, GitHub Copilot, Cursor, Codex, Claude Code and any other client that supports Agent Plugins, the open format for packaging skills and MCP servers.
• Its skills build a component in your framework, review one or how a screen uses it, reporting every rule by its ID, and move your CSS variables to token paths.
• Where your client doesn't connect MCP servers, the skills read the same contracts and pages from this site.

Inputs are where people tell you things, and they look so simple that they're often built in a hurry. The Input page walks you through building one the right way, from a label that doesn't disappear as people type to an error message that says how to fix what's wrong.

New

• The Input has the Button's sizes, so the two line up in a row, and slots for icons, prefixes and suffixes, and for buttons like Show password.
• Its border has 3:1 against the page, so people can always see where to type, and its invalid look comes from aria-invalid, so it always matches what screen readers announce.
• Its checklist covers how forms use it too, like giving every input a label and an autocomplete value, checking values when people leave an input rather than while they type, and never blocking paste.
• It comes with its own contract, live examples and a tested reference implementation.

A spinner is one of the simplest components there is, and still easy to get wrong. The Spinner page walks you through showing that something is busy, and making sure everyone hears what's loading and how it went, since the spinner itself stays silent.

New

• The Spinner takes its size and colour from the text around it, stays hidden from screen readers and stops turning when someone prefers reduced motion.
• Its checklist covers how screens use it too, like showing one spinner per wait, saying what's loading in a status message and leaving focus where it was.
• It walks you through every state of the wait it shows, from busy to done or failed, and what to say when it's taking longer than expected.
• It comes with its own contract, live examples, a tested reference implementation and a browser test that checks what screen readers and agents find while the page waits.

Improved

• The Button shows the Spinner while it's loading, so changing your spinner once changes it everywhere.

Agents do their best work with just what a task needs, but a component page holds far more than that: the Button's alone is about 35,000 tokens. Our MCP server, at https://mcp.opencomponents.dev/mcp, gives your agents the standard as tools instead, so they read a component's contract first, then only the sections and rules their task needs.

New

• Connect it to Claude, Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Grok, Hermes Agent or any other client that supports remote MCP servers. It's free, with no sign-in.
• Its tools read a contract, list the rules that apply to your task, read a page a section at a time in your framework, search the whole standard and return the reference implementation.
• Its prompts build a component, review one or how a screen uses it, reporting every rule by its ID, and move your CSS variables to token paths.

Contracts give agents every requirement for a component in one YAML file, so a field that's missing or misspelled leads them astray without a word. They now all follow one published JSON Schema, which catches those mistakes before anyone relies on the contract.

New

• Every contract names the schema on its first line, so editors that use the YAML language server check it as you type.
• The schema covers components and conventions alike, so you can validate the contracts you write for your own components too.
• We validate every contract on this site against it on every change, so the ones we publish always pass.

Most of our rules rest on WCAG, but some go further, and some are our own. Every checklist now has a Basis column that tells them apart, so you know when a rule is something WCAG asks for at level AA, and when it's a call we've made.

New

• Every rule in the Button and Design Tokens checklists names its basis: the WCAG 2.2 success criteria behind it and their level, HTML, WAI-ARIA or the APG, or Open Components for our own rules.
• Contracts include each rule's basis too, so your agents can tell the rules apart as well.

Improved

• button/focus-visible asks for an outline at least 2px thick, rather than exactly 2px, and the Button page says what we recommend for the details you can change and still meet the standard, like the ring's offset or the opacity of the state layers.

Fixed

• button/keep-focus now covers a button that can be disabled while it has focus, like Next on the last page, which stays focusable. Before, it said a focused button is never natively disabled, which no Button could promise on its own.
• button/focus-not-obscured now cites WCAG 2.4.12 as well as 2.4.11, since it asks that a focused button isn't covered at all.

Buttons are the most common interactive component in any interface, and also the one we most often get wrong. Our first component page walks you through building one the right way, and every component page after it will follow the same structure.

New

• It covers how a button looks, how it behaves for every person and every input, how developers work with it and how agents can read and verify it.
• Every example is live, and its code comes in React, Vue, Svelte, Angular, Solid, Astro and Vanilla.
• A checklist, a contract for agents and a tested reference implementation help you hold your own buttons to the standard.

Every component reads its colours, sizes and spacing from CSS variables, and their names are all that people, tools and agents have to go on. Our first Foundations page shows you how to name them, so that everyone reads them the same way.

New

• Token paths, like --color--primary, give every token a name that can only be read one way.
• Every component reads the same theme tokens, so a new brand or a dark mode never means editing every component.
• A Stylelint rule and a checklist let you and your agents check your tokens automatically.