Colors

Use semantic tokens instead of hardcoded colors in content components. This keeps light mode, dark mode, borders, links, and active states consistent.

Token example#

This example shows the shape of the tokens you can adjust before changing component markup.

:root {
  --bg: oklch(1 0 0);
  --fg: oklch(0.15 0 0);
  --muted-fg: oklch(0.48 0 0);
}

Semantic names#

Use names based on purpose, not appearance. A token named muted-fg is easier to reuse than a token named gray-500.

Dark mode#

Review every interactive state in dark mode. Active links, borders, code blocks, and callouts usually need separate attention.

Token guidance#

Use these rules as a quick review before changing the color system.

• Keep background and foreground contrast strong.
• Use muted text for secondary information.
• Use accent colors for active and interactive states.
• Check code blocks in both light and dark mode.

Contrast checks#

Run contrast checks on text, borders, and keyboard focus states. Docs pages usually contain long reading sessions, so weak contrast becomes tiring faster than it does on a marketing page.

State colors#

Define color roles for hover, active, selected, disabled, and focus-visible states before styling individual components. This keeps navigation, buttons, tabs, and code controls visually related.

Review workflow#

Treat colors as a system review, not a single file change. A token that looks good in one component can fail inside a callout, table, sidebar item, or code block.

Pages to review#

Check at least one overview page, one code-heavy page, one blog article, and one long sidebar state. These screens usually reveal token problems quickly.