Code block
Highlighted at build time, coloured by tokens, copyable with one click, and readable on paper.
// Contrast ratio between two colours (WCAG 2.x)
export function contrast(a, b) {
const [x, y] = [lum(a), lum(b)].sort((m, n) => m - n);
return (y + 0.05) / (x + 0.05); // 4.5 or more for text
} Use the theme switch in the site header to see the dark palette. Every syntax colour is at least 4.5:1 on its background in both themes.
When to use it
- Code someone will read closely or copy: a sample, a command, a config.
- More than a few words of it. A name or a value inside a sentence is inline
code.
Use something else when:
- It is a result to look at, not code to copy: a live example with its code underneath, as on these pages.
- It is a set of values to compare: a table.
How it works
- Fenced code in Markdown is highlighted by Shiki at build time using its
css-variablestheme, so the HTML carries variable names, not colours. - Those variables point at
color.code.*tokens, which change with the theme. - A small script adds the header with the language label and the copy button. Copying is said as well as shown.
- Code too wide for its box scrolls sideways inside it, with a hint underneath; only then is it a stop for the keyboard.
- In print, the copy button disappears, long lines wrap and keywords turn bold instead of coloured.
Accessibility
What it does for you
- A Copy button named for what it copies ("Copy js code"). It says "Copied" on the button and announces "Code copied", without moving focus.
- Code too wide for its box scrolls sideways inside it. It then becomes a region the keyboard can reach and scroll, named "Code, scrolls sideways", with a hint underneath.
- Code that fits its box is not a stop for the keyboard.
- Every syntax colour has at least 4.5:1 against the block, in light and dark.
- On paper long lines wrap, the button goes, and keywords are bold, not coloured.
What you need to do
- Say what the code is for in the sentence before it.
- Keep lines short where you can: scrolling sideways is work.
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves to Copy, then to the code if it scrolls. |
| Enter or Space | On Copy: copies the code. |
| Left and Right | On code that scrolls: scroll it. |
What a screen reader is told
- A button, "Copy js code"; then "Code copied".
- When it scrolls: a region, "Code, scrolls sideways".
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 1.4.3 Contrast (Minimum) | AA | Each syntax colour against the block’s background. |
| 2.1.1 Keyboard | A | Scrolling code can be reached and scrolled from the keyboard. |
| 2.5.3 Label in Name | A | The button’s name starts with its visible word, Copy. |
| 2.5.8 Target Size (Minimum) | AA | The button is 26px high. |
| 4.1.2 Name, Role, Value | A | A named button; a named region when the code scrolls. |
| 4.1.3 Status Messages | AA | The copy is announced without moving focus. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 7 of 7 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 5 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 7 checks made with the keyboard, on the example at the top of this page:
- Passed Copy is a button whose name starts with its visible word and says what it copies
- Passed Enter on Copy copies the code, says "Copied" on the button and announces it, and focus stays
- Passed The button’s word goes back to Copy
- Passed Code that fits its box is not a stop for the keyboard
- Passed Code too wide for its box is a region named "Code, scrolls sideways" that takes the focus, and Right scrolls it
- Passed Every syntax colour has at least 4.5:1 against the block, in light and dark
- Passed The Copy button is at least 24px high
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- How a screen reader reads the code itself, symbol by symbol, is the reader’s own business and has not been listened to.
Evidence
Where it's used
| Where | For |
|---|---|
| These docs | Every code sample and every example’s Show code. |
| mediadreams.co.uk | Insights that show code. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| Wide code ran off the side of a phone with nothing to say there was more, and no way to scroll it from the keyboard. | It scrolls in its box as a labelled region the keyboard can reach, with a "Scroll sideways" hint (1.5.0). | |
| Code in an article had no Copy button; code in these docs had. | One shared Copy button for code in running text (1.19.0). | |
| Writing this page’s checks: "Copied" was shown on the button and told to nobody, and every sample that fitted its box was still a stop for the keyboard, with no name or role. | The copy is announced, and only code that scrolls is a stop (1.84.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What we don't know yet
- How often code is copied is not counted.
Tokens
| Token | Light | Dark | Use |
|---|---|---|---|
#FFFFFFcolor.surface.raised | #131C2Ecolor.surface.raised | Code blocks and inline code sit on the raised surface, so they take on each brand like tables and cards | |
#152238color.text.primary | #F3F0E9color.text.primary | ||
#566074color.syntax.slate-light | #9AA6BAcolor.syntax.slate-dark | ||
#A8310Acolor.syntax.ember-light | #FF8F5Ccolor.syntax.ember-dark | ||
#0B6B52color.syntax.jade-light | #7FD6B0color.syntax.jade-dark | ||
#1E4FA8color.syntax.cobalt-light | #8DB4FFcolor.syntax.cobalt-dark | ||
#7A4300color.syntax.ochre-light | #F2C46Dcolor.syntax.ochre-dark | ||
#4B5567color.ink.600 | #B9C2D0color.ink.300 | ||
rgba(21,34,56,0.12)color.border.subtle | rgba(255,255,255,0.10)color.border.subtle |