Docs authoring

Pages on this site are reference docs. A page states the rule. It does not address a reader, and it does not date the rule. No “you”, and no “today”, “as of”, or a year attached to a standard.

Theme

Layout, type, and components come from starlight-theme-flexoki. Colour does not. src/styles/theme-one-dark-pro-night-flat.css replaces the Flexoki palette in dark mode and in light mode. astro.config.mjs loads that file on one customCss line.

Dark mode maps One Dark Pro Night Flat onto Starlight’s variables. The vendored file is src/themes/one-dark-pro-night-flat.json, commit 75c80ab18d90655e05ad837bb8d89f5e68d5ce53. The page background is editor.background (#16191d). Body text is editor.foreground (#abb2bf). Muted text is titleBar.activeForeground (#9da5b4); the theme’s line-number grey is dimmer than 4.5:1, so the UI does not use it. Links are textLink.foreground (#61afef). The badge blue #4d78cc is darkened on its own hue to #4371c9 so #f8fafd clears 4.5:1 on a filled control. Aside fills mix each accent into #16191d and stop while both the body text and the title colour stay at or above 4.6:1.

One Dark Pro has no light theme. Light neutrals keep the hue of #16191d and raise the lightness (#f6f7f8 for the page). Text and aside colours are the same hues, darkened until each pair clears 4.5:1 on its background.

Dark code blocks use the vendored Night Flat theme. Light code blocks use Atom One Light, the VS Code theme at akamud/vscode-theme-onelight commit 5866e900db932d580e978a58db42f65cde07998b, a port of Atom’s One Light syntax theme. The file is src/themes/atom-one-light.json. It omits type, so the config sets type to light. Expressive Code then lifts any syntax colour below its 5.5:1 floor. The gutter uses #9da5b4 in the dark theme and #737375 in the light theme, because the upstream gutter greys are below 4.5:1.

Icons

Icons are Lucide SVGs from @lucide/astro, drawn through src/components/Icon.astro. The wrapper sizes the icon to the surrounding text (1em) and sets color to currentColor, so the icon follows the text colour. A decorative icon is aria-hidden. A named icon takes a label, which sets aria-label and role="img".

Starlight’s Card icon prop accepts only Starlight’s own icon names. A Lucide icon does not go there. src/components/IconLinkCard.astro is the link card that takes a Lucide icon name. The index of the WordPress standards uses it.

Adding an icon is two steps: import the Lucide component in Icon.astro and add it to the icons map, then use it.

import Icon from '../../components/Icon.astro';

<Icon name="palette" />

Theming uses palette. Styling uses paintbrush. Blocks uses layout-grid. Code structure uses folder-tree. Accessibility uses accessibility. search marks a “How to check” heading. triangle-alert marks an “Avoid” heading.

## <Icon name="search" /> How to check

Components

Cards, asides, quotes, titled code, steps, and tabs are Starlight components, plus IconLinkCard for a Lucide icon on a link card. Each one earns its place. A page does not use a component for decoration.

Example card

A link card with one Lucide icon and one sentence.

A quote is one sentence: the principle, and nothing else.

A code example names its file. A command uses a terminal frame.

{ "settings": { "color": { "palette": [] } } }

grep -R -n 'pattern' --include='*.php' .

Steps are an ordered procedure. Tabs are two real alternatives, such as a block theme and a utility-class theme. Tabs are not a way to show the same idea twice.