Design System

Content fundamentals#

• Capital Letters. Sentence case for headings, buttons, links and labels. The page title (post-h1), the mono label, meta and link-mono styles are set uppercase by CSS.
• Buttons and links. Always carries an descriptive accessible name, explaining their action or destination. In isolation, the purpose or context should be understood alone.
• Errors. Explain what is wrong and how to fix it, for example: "Enter an email address, such as name@example.com."
• Internalization. Everything (except this page :P) is written in three languages: Spanish, my native language, English, my second language I like to thing, and Italian, which is a language that I am still learning but I included to force myself to write in this language to exercise.
• Icons. Icons are lucide, only one emoji on the footer which is hidden from assistive technologies.
• Numbers and dates. Dates are short and localised ("Sep 23, 2026"), reading time is "7 min read", counters are two digits ("01", "07").

Accessibility rules#

• Target WCAG 2.2 AA. Text is 4.5:1 on its ground (3:1 from 24px, or 18.66px bold); borders, focus rings and icons that carry meaning are 3:1. Each token's note names the grounds it was measured on.
• Use the native element first: dialog, details, button, a, label. ARIA only where the tag runs out.
• Every control is at least 44px (min-block-size: 2.75rem) and reachable and operable by keyboard. An icon-only control has a name.
• Colour is never the only signal: links are underlined, the selected language has a bar and a check, an invalid field has text.
• Numbers drawn by CSS counters are spoken through the / alt-text slot (content: counter(post) '. ' / ...).
• Put SkipLink first on every page, and send focus to the page h1 after a route change.

Iconography#

I use icons provided by Lucide library. They use 16px beside text, 20px for social links, 24px inside the 56px icon button. They are decorative (aria-hidden="true") next to text; a button that is only an icon carries its name in text hidden from sight.

Button#

Actions

The hard-shadowed action: a 3px border edge, radius, shadow-sm and 700 weight. On hover it sinks 2px into its shadow (shadow-pressed, duration-press).

• Use primary (accent fill, accent-foreground text) for the one action a view exists for, quiet (card) for the rest, and danger (destructive) only for an action that cannot be undone. Say what it does: "Erase account".
• Verb first, sentence case. Never two primary buttons in one view.
• If the button is only a visual icon you can use sr-only to hide the accessible name of the button or an aria-label, then it should go along with a tooltip explaining the purpose for sighted users. The icon should have a size="icon" (a 56px square).
• Targets are at least 44px (min-block-size: 2.75rem). Focus is the focus-halo shadow. Under prefers-reduced-motion the button does not move.
• A disabled button drops to 50% opacity and keeps its edge.

Related components: Link and button

Link#

Actions

They are always underlined, because colour alone never marks a link.

• brut (default): 700 weight, a 3px foreground underline at a 4px offset.
• nav: a 3px accent underline. The current page sets current and becomes a filled secondary pill with no underline, and gets aria-current="page".
• muted: footer-size text in muted-foreground with a 2px accent underline that appears on hover and focus. Hover darkens the text to foreground.
• Link text should make sense out of context: "Read more about Everything Is A List", not "click here".
• An icon after the text is decorative, which means it should go to an aria-hidden="true".
• Focus is the focus-halo; the link also lifts to z-raised so the ring is not clipped.

Related components: Link and button

Slab#

Surfaces

Just for clarification: slab is a container component. It uses a 3px border edge, radius and a hard shadow on card. It is used on cards, the table of contents, the language listbox, demo frames and tables are all slabs.

• shadow (4px) for a slab, shadow-sm (3px) for a control.
• Choose padding with pad: sm (space-3) for a compact card, md (space-6) by default, lg (space-10) for a feature panel, or none.
• Give it a landmark or heading when it holds content (<article> with an aria-labelledby).
• Do not nest a slab inside a slab. Use border 1px or a Rule inside.

Related components: Interactive Card

Rule#

Surfaces

A 3px border line. It ends a header, closes a page intro and separates a heading from a long list.

• It is a separator, so it is purely decorative aria-hidden="true".

Label#

Text

A mono micro-label: 0.8125rem, 700, 0.08em tracking, capitals, in accent-text. It names a region or a value.

• Type the text in sentence case and let CSS set the capitals to prevent the screen reader to announce letters and announce words.
• Use it for eyebrows, the listbox heading and counts: "Published posts". Keep it to two or three words.
• accent-text on background, muted and secondary is 9.70:1 or better (AAA), so it stays readable at 13px. accent alone is 5.68:1 there, which is too thin for small capitals. Do not put the label on accent or on a photo.

Underline#

Text

The highlighter: a marker band behind ink text, 0.42em thick and pulled up into the letters.

• Use it on one phrase per page, such as the hero greeting.
• The text is always ink (14.24:1 on marker).

Heading#

Text

Page headings at six levels. Every level is 700 and tightly tracked (post-h1 to post-h6).

• post-h1: set in capitals, once per page, clamped from 2.1rem to 3.9rem with 1.02 leading. Not for sentences longer than a line or two.
• post-h2: sentence case with a 3px border underline
• post-h3 to post-h6: sentence case with an accent rail on the inline start that thins from 5px to 1px as the level drops

Blockquote#

Text

A pull quote: Georgia italic at 1rem with 1.75 leading and a 2px accent rule on the inline start. It is the only serif on the site.

• Use the HTML tag blockquote and a cite for the source.

InlineCode#

Text

The contents list on this page is the live example.

Inline code: 0.875em mono at 600, a 12% accent tint, a 2px edge in accent at 30% and radius-code.

• Wrap every attribute, element, property and token name in a sentence: aria-describedby, showModal(), --accent.
• Use CodeBlock for more than a line.

Kbd#

Text

A key cap for a keyboard instruction: light, 700 weight, a faint lilac edge and a short inner shadow so it reads as a key.

• One Kbd per key: Shift then Tab, never one cap for a chord. Use the key's name as it is printed ("Esc", "Enter", "Tab").
• Ink on the key's near-white face is 16:1 or better.

Code Block#

Text

<dialog id="demo" aria-labelledby="demo-title">
  <h2 id="demo-title">A modal dialog</h2>
  <button type="button" command="close" commandfor="demo">
    Close dialog
  </button>
</dialog>

A multi-line code sample: ink ground, paper text, 1rem mono at weight 500 and 1.6 leading, radius and a faint accent edge.

Syntax colors, all on ink (#16161A):

• Plain text and punctuation: paper or #FFF9F5, 17.29:1 or better.
• Comments: #FFFFFF in italic, 18.04:1.
• Attribute names and numbers: #F4D58D, 12.67:1.
• Functions and types: #B3DFE0, 12.50:1.
• Tags and keywords: #FFCBBD, 12.48:1.
• Strings and class names: #DDD2ED, 12.47:1.
• Invalid code: #FFC8DC, 12.50:1.

• Pass the code as a string. Long lines scroll inside the block, which takes focus (tabindex="0") so a keyboard user can scroll it.
• The copy button is an icon-only button: its name comes from copyLabel ("Copy code").
• Keep it under about 20 lines.

Chip#

Content

A pill with a 1px edge in the text colour, 0.875rem at 700. It is either a link or a plain tag.

• Link (it has an href): accent-text on a 10% accent tint, with its 1px edge in the same colour. Hover deepens the tint to 20%. The text is accent-text, not accent or lilac-dark: on the 20% hover tint over wash, accent falls to 4.31:1 and lilac-dark to 5.91:1, both under the 7:1 AAA asks of 14px text. accent-text (lilac-deep) holds 7.35:1 there, 8.47:1 at rest, and 8.52:1 and 9.92:1 over paper.
• A link that opens a new page (target="_blank") draws the external-link icon after its text, 16px and aria-hidden, and announces "opens in a new tab" through a hidden text. Give it rel="noopener noreferrer". A link that stays in the tab has no icon.
• Tag (no href): foreground text on the muted fill with a muted-foreground edge and no hover.

Chip List#

Content

A wrapping list of Chips with a space-2 gap, built as a real ul so a screen reader announces the count.

• Pass label ("Topics") so the list has a name. Pass items with external: true for links that open a new page. An item without an href is a plain tag, and a list may mix both.
• Use it for a post's topics or a talk's tags.

Post Item#

Content

One entry in the blog index, set inside PostList (an ol whose entries are numbered by a CSS counter). Meta line, linked title, description, then a "Read more" link.

• The meta line is meta in accent: the date, a square dot, the reading time. Pass the date already formatted for the locale. dateTime is the machine-readable one.
• The number sits in the left gutter (01, 02) and is spoken as "1." through CSS alt text. Do not draw it as a pseudo-element on the list item or as text.
• The title is a card-title (1.5rem, 2.25rem from md), underlined 3px on hover. The description is muted-foreground.
• The "Read more" link is link-brut in mono capitals. Give it the post's title in an aria-label so repeated links have distinct names.
• Entries are separated by a 2px border line, with space-10 (space-12 from md) above and below each.

Hotspot#

Content

Variant

LinkDialog

• Design System

  The tokens and components of this site

  Read more

• Blog

  Posts on accessible components

  Read more

• Experience

  Where I have worked

  Read more

• Speaking

  Talks I have given

  Read more

Markers over an image that open a card about the thing they point at. There are two variants: the expanded card is a link that contains only a short name and description and leads the user to the product details page and a non-modal dialog that holds information organized in a more structured and complex way.

Link variant

The card is just one <a>. The marker is a button.

Keyboard interaction

• Tab moves from marker to marker. A marker that takes focus opens its card by itself (WCAG 1.4.13), and focus stays on the marker.
• Tab again moves focus into the card's link while the card stays open. Shift+Tab goes back to the marker, and the card is still open.
• Tab from the link closes the card and goes on to the next marker, which opens its own card. Only one card is open at a time.
• Enter or Space on the marker never closes an open card. Enter on the link redirects the user to a different location.
• Escape closes the card from the marker or from inside it and returns focus to the marker. The card stays closed until the pointer or the focus comes back, or the user interacts with it again by pressing Enter or Space.

Screen reader interaction

• The list of markers is announced with its name and its count ("Pages in this image"), because it is a ul with an aria-label.
• On a marker: "Expand to read more about Blog, button, expanded". The name says that pressing it shows more, and the browser adds expanded or collapsed itself from popovertarget.
• In the card: "Blog, Posts on accessible components, Read more, link".

Pointer or touch interaction

• Hovering a marker opens its card. Leaving closes it after 150ms, a wait the pointer can cross, so the card can be hovered.
• On touch a tap on the marker opens the card, a tap on another marker switches to that card, a tap on the card follows the link and a tap outside closes it.

Semantic structure

• The markers are in the lis of a ul named for what it holds ("Products in this image").
• The marker is a button named by triggerLabel, with popovertarget pointing at the card and popovertargetaction="show".
• The card is an a with popover="auto", so the whole card is the link. The browser gives it the top layer, light dismiss, Escape and the return of focus.
• It holds three p: the name, the description and a last line ("Read more") that says what following the link gives.

Dialog variant

The card is a non-modal dialog opened by a press and it would need a focus management. The marker is a button and the card is a dialog tag.

Keyboard interaction

• Enter or Space on a marker opens its card, and focus moves to the card's heading.
• Tab goes to the close button, then to the link if there is one. Shift+Tab goes to the previous interactive element. If it is the first interactive element, it goes to the marker because since it is not a modal dialog element there is no need to have a focus trap.
• Tab if there is one, the focus goes to the next interactive eleent inside the non-modal dialog. If not, the focus leaves the card and goes to the next marker in the ul
• Escape closes the card from anywhere inside it and returns focus to the marker. The close button does the same with Enter or Space.
• Opening one card closes the other.

Screen reader interaction

• On a marker: "View details for Design System, button, collapsed", and expanded once the card is open.
• On opening, focus is on the heading so it is going to be announced by the screen reader. The card is named by that heading (aria-labelledby), so it is announced as a dialog called "Design System".
• Then, in reading order: the detail line, the close button, the paragraph, the list with its count, and the link by its name ("Go to Design System"). The close button is named "Close".

Pointer or touch interaction

• A press or a tap on the marker toggles the card, and a press or a tap outside closes it (light dismiss).
• A tall card scrolls inside its own height, so it never covers the marker.

Semantic structure

• The markers are in the lis of a ul named for what it holds. Each marker is a button named by triggerLabel, with popovertarget pointing at the card.
• The card is a dialog with popover="auto", named by its heading. The browser handles the top layer, light dismiss, Escape, the return of focus and the expanded state of the marker. The close button is popovertarget with popovertargetaction="hide", so it needs no script.
• Inside it is a section that holds a header (the heading and the detail on one side, the close button on the other, laid out with flex so nothing is positioned by hand), then the paragraph, the list and an optional link.
• The heading is tabindex="-1" and takes the focus on open using javascript.

Both variants

• A card is a popover tied to its marker by anchor positioning. It goes below the marker in the upper half of the image and above it in the lower half, or on the other side when that has more room.
• It is at most as tall as the room on its side, less its margins, and scrolls inside when it needs more, so it never covers the marker.
• Position is a percent of the image, to the centre of the marker. prefers-reduced-motion stops the pulse. With six or more markers, add a "View all" link below the image.

TextField#

Forms

A text field associated with a label, optional hint, a 2px input edge, radius and the focus-halo on focus.

• Always a visible label. Mark a required field with required; the asterisk is destructive and hidden from assistive technology because the required attribute is already set on the input.
• hint and error are linked through aria-describedby. Explain the fix in the error: "Enter an email address, such as name@example.com.", not "Invalid".
• An invalid field turns its edge destructive and sets aria-invalid. The error text should be always visible until the user addresses it.
• Minimum height 44px. The edge is input, at least 3:1 against background.

Related components: Form Fields

Dialog#

Surfaces

This is a modal dialog built using the native dialog tag and using its native methods showModal() to open it and close() to close it.

• title: the accessible name of the dialog comes from the aria-labelledby attribute and receives focus on open. Focus returns to the control that opened it on close.
• showModal() method: native method of the dialog tag to open it. It makes the page behind inert, and a backdrop.
• variant="drawer" slides in from position left or right.
• There should always be an exit mechanism such as a button to "Close dialog".

Keyboard interaction

• Enter or Space on the button opens the dialog. Focus moves to the title.
• Tab moves forward through the controls inside the dialog in reading order: the close button first, then the content. From the last control it wraps to the first interactive element inside the dialog.
• Shift+Tab moves back. From the close button, or from the title, if it is on the first interactive element inside the dialog the focus will be placed on the last interactive element.
• Escape closes the dialog, and focus returns to the control that opened it.
• Enter or Space on the close button returns the focus to the opener.
• The page behind is inert and Tab key never reaches it.

Focus trap

The dialog tag has a native focus trap BUT it considers the interactive UI widgets of the browser part of the focus flow. In my opinion, this is a blocker for keyboard or screen reader users because if a dialog contains 3 interactive elements, they will have to also navigates through the UI interactive elements making their experience worse. In order to avoid this, I implemented a custom focus trap.

Tooltip#

Surfaces

A visual hint for interactive elements that are only an icon. It has a 1px white edge and an arrow. It contains the name of the control and it only will be visible when on hover or on focus. The text should not be put twice to avoid redundancy announcement in screen readers.

• It shows on hover and keyboard focus and closes on Escape.
• The tooltip itself has aria-hidden="true" because the control should already have an accessible name.

Table of Contents#

Navigation

The contents list on this page is the live example.

A navigation landmark listing a page's headings, numbered by CSS counters (1., 1.1.) in order to organize the content of the page.

• aside is a sticky Slab (18rem, z-fixed) beside long posts and only visible on wide screens.
• Nest at most three levels. Deeper levels get smaller and quieter (muted-foreground).

Skip to Main Content#

Navigation

The first focusable element on every page. It is hidden until it takes focus. When pressed, it jumps from the header to the main content.

• It is an <a> placed as the first thing in the tab order and points at #main-content (main has id="main-content" and tabindex="-1").
• It appears only on focus, at z-skip-link, with the focus-halo.

Language Switcher#

Navigation

The language control is a button that control a listbox to change the language of the page.

• The trigger announces the current language and what to do to change it ("The current language is English. Click to change language"). It has and aria-haspopup="listbox" to associate it with its listbox and aria-expanded, and is at least 44px.
• Options are role="option" with aria-selected. The selected one has an accent bar on its inline start, a secondary ground and a check.
• Each option shows the name in its own language. Set lang on the page when it changes.
• The listbox heading is a Label: "Select language". Escape closes it and returns focus to the trigger.

Keyboard interaction

• Enter, Space or ArrowDown on the trigger opens the menu, and focus goes to the selected language.
• ArrowDown and ArrowUp move between the options and wrap from the last to the first and back. Home and End go to the first and the last interactive elements.
• Enter or Space on an option chooses it: the menu closes, focus returns to the trigger and the trigger shows the new language.
• Escape closes the menu and returns focus to the trigger.
• Shift+Tab from the first option closes the menu and returns focus to the trigger. Tab from the last option closes it and goes on to the next control in the focus flow of the page.
• Hovering an option moves focus to it, and a press outside the menu closes it.

Screen reader interaction

• Opening is announced politely, in a live region: "Language menu opened. 3 options available." Choosing a language is announced the same way: "Language changed to Español".

Site Header#

Navigation

The site header on desktop view has the main navigation and the language switcher. On mobile view, the main navigation will be grouped in a expandable menu and the language switcher will be visible too unchanged.

• My name is the home link and it is plain text.
• wide shows the nav links and compact, below the lg breakpoint, swaps them for an icon-only menu button, named "Open menu", that opens a modal dialog under the header.
• Place SkipLink before it.

Compact header and its menu

The compact header is the name, the LanguageSwitcher and the menu button in one row. The example opens the same menu the site opens, under its own header and at its width.

• Enter or Space on the menu button opens the dialog and moves focus to its close button. The button has aria-haspopup="dialog" and aria-expanded.
• The menu is a modal dialog named "Mobile navigation": a close button, then the links as a numbered list (01 Home to 05 Design System), each in large type with an arrow and named "Go to Blog". The current page has a tint and aria-current="page".
• Tab and Shift+Tab cycle through the close button and the links without leaving the dialog. Escape, the close button or a press outside closes it, and focus returns to the menu button.
• Choosing a link closes the menu. The page behind is inert and does not scroll while the menu is open.

Semantic structure

• The header is a native header element. SkipLink is its first child, an a to #main-content, so the keyboard reaches it first.
• The name is an a to the home page. It is a link, not a heading or an image.
• The wide navigation is a nav named "Main navigation" that holds a links. The current page has aria-current="page". Below lg it is display: none, so it leaves the accessibility tree instead of staying as a hidden duplicate of the menu.
• The language switcher is a button with aria-haspopup="listbox" and aria-expanded. Its options are buttons with role="option" and aria-selected.
• The compact menu button is a button with aria-haspopup="dialog" and aria-expanded. The menu is a native dialog named by an h2, hidden from sight, through aria-labelledby: "Mobile navigation".
• Inside the dialog are a nav and an ol with role="list" of a links, each named "Go to Blog". The numbers are aria-hidden, so the name is read once.

Site Footer#

Navigation

The site footer contains a brief description of my role, a resume of the page, social links and a webring link are placed here.

• Text is small in muted-foreground; links are muted, with the accent underline on hover and focus. Social links are icon-only and each carries its name ("LinkedIn", "GitHub") for screen readers.
• Columns collapse to one on a phone (breakpoint-sm). Padding is space-12 above and space-8 below.
• The closing line reads "© 2026 Mica. Made with sweat and tears for everyone", followed by a hidden icon from assistive technology.

Semantic structure

• The footer is a footer element and it is placed inmediately after the main element.
• Every column has its own heading like an h3 for the name and an h4 for "Navigation" and "Get in touch". The webring has an h2.
• The email is an a with mailto:. The social links are icon-only a with target="_blank" and rel="noopener noreferrer", named with aria-label ("Go to my Github's profile"), and the icon is aria-hidden. The webring links use rel="external".
• The VAT number is plain text. Next to it is a button type="button" named "Copy VAT number", and the confirmation goes in a hidden span with role="status", so it is announced without moving focus.
• The icon is aria-hidden, and the closing note is a p.

Icon#

Iconography

The icon set comes from lucide-react: a 24px grid, a 2px stroke, round caps and joins, currentColor.

• Icons next to text are decorative: aria-hidden="true", and the text carries the name. An icon alone sits in a button whose name is its visible or screen-reader text.
• Size them to the text: 16px beside 14-16px text, 20px for footer social links, 24px inside the 56px icon button.
• Colour follows the text (currentColor), or accent for icons in the language switcher. Never a second hue.

Link and button#

Built with: a href · button type

A link takes the user somewhere. A button does something in the current page.

The live example is in the post.

Read the post: Link or Button

Related components: Button, Link

Disclosure#

Built with: details · summary · ::details-content

An expandable and collapsible section with no JavaScript and no WAI-ARIA.

Read the post: Learn how to build a disclosure component using the native HTML details tag

Interactive Card#

Built with: article · a · button

Read the post: Learn how to build a semantic, accessible and interactive Card UI using HTML and CSS

Related components: Slab

Form Fields#

Built with: label · fieldset and legend · select · input · textarea

The post is still in progress.

Related components: TextField

Select#

Built with: select · option and optgroup · label

The native html `select` tag.

The post is still in progress.

Combobox with a Tree Popup#

Built with: input role=combobox · role=tree · role=treeitem

A product search whose suggestions each carry a second level of related suggestions.

The post is still in progress.

Pagination#

Built with: nav · a · aria-current · aria-setsize and aria-posinset

The post is still in progress.

Progress, meter and steps#

Built with: progress · meter

Avoid implementing a soup of divs to built progress indicators because we have their HTML semantics equivalents!!.

The post is still in progress.

Quantity spinbutton#

Built with: input type=number · role=spinbutton · aria-valuetext

Do NOT follow the APG pattern. Just follow my solution because it works on all browsers and screen readers..

Read the post: Accessible and Functional Quantity Spinbutton Pattern