0003: Theme with --inkan-* CSS tokens

Context#

Every company wants the site in its own colours and most want to stop there. Forking the stylesheet or writing selectors against generated class names breaks on the next release. The theme needs a stable surface: a set of named values that the site promises to read everywhere, and a way to load a file that changes them.

Decision#

All colours, fonts, radii and motion values of the site are CSS custom properties prefixed --inkan-, declared on :root in tokens.css. They are the public theming API. The customCss option lists CSS files from your repository that are loaded after the built-in styles, so a plain :root { --inkan-...: ... } block retints the whole site, including cards, covers, code blocks and diagrams.

How to use it#

Load your CSS#

1
export default defineConfig({
2
  customCss: ['./brand/theme.css'],
3
});

The files go through the build like any other asset: hashed, minified and bundled into the page CSS. Changing one in dev hot-reloads the page. Anything valid in CSS is allowed, but overriding tokens is the supported path; selectors against the site’s class names may break between releases.

The token groups#

The full list is in app/src/styles/tokens.css inside the package. The groups and their most useful members:

The dark theme redefines the surfaces, inks, blend mode, foil outline, some status hues, focus, link and code colours. Geometry, type and motion are the same in both themes.

A realistic override#

A brand with a warm paper, its own blue as the first ink, a different display font and a link colour:

1
/* Day */
2
:root {
3
  --inkan-bg: #F8F5EE;
4
  --inkan-bg-2: #EEE9DD;
5
  --inkan-surface: #FFFDF8;
6
  --inkan-paper: #F6F2E8;
7
  --inkan-ink-c: #0057B8;        /* brand blue replaces cyan for projects using ink "c" */
8
  --inkan-link: #0057B8;
9
  --inkan-focus: #0057B8;
10
  --inkan-font-display: "Archivo", "Anybody", sans-serif;
11
  --inkan-radius-ui: 2px;
12
}
13

14
/* Stage: same brand on black. Both selectors are needed, see the Day and Stage record. */
15
:root[data-theme="dark"],
16
:root:not([data-theme="light"]) {
17
  --inkan-ink-c: #4D9BFF;
18
  --inkan-link: #8AB8FF;
19
}

If you replace a font, load it in the same file with @font-face or from a host you control; the built-in fonts stay available as fallbacks.

What reads the tokens#

Everything. The tokens are consumed by the page chrome, the Markdown styles, the photocards, the generated covers (--inkan-ink-*, --inkan-paper, --inkan-blend), the status stickers, the Expressive Code blocks (--inkan-code-*) and the Mermaid diagrams (--inkan-fg, --inkan-surface, --inkan-bg-2, --inkan-rule-strong). Changing an ink changes the covers of every project that uses it.

Project sections and cards also set a local --ink from their project’s ink class (.ink-c … .ink-o). Your own components can use var(--ink) to pick up the current project colour.

Consequences#

• Retinting a site is one CSS file and no fork. Token names are kept stable across releases; class names are not a contract.
• Overrides must be written twice when they differ between Day and Stage.
• The six ink slots are fixed; you can recolour them but not add a seventh.
• Contrast is your responsibility after an override. The defaults pass AA for text; a pale ink used for text will not.
• customCss is bundled, so a change needs a rebuild in production; there is no runtime theme file to swap.