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.

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 Flexoki 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.

page.mdx

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.

heading.mdx

## <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.

Note

A note is the reason for a rule.

Tip

A tip is a check: a command, a file to open, or a count to compare.

Caution

A caution is a practice that fails the standard.

Danger

A danger is a practice that breaks the build or the request, such as an unguarded plugin call.

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

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

theme.json

{ "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.