Site Colors & Section Modifiers

Micropage has a built-in default primary color that works out of the box. You can override it with a custom brand color in [site] and optionally set a different dark-mode value in [site.dark]. The primary color — default or custom — can be applied to any section, container, or hero via modifier tokens on the section header line.

Defining colors

Colors are declared inside an indented colors: block within the [site] (and optionally [site.dark]) block.

[site]
title: My Brand
colors:
  primary: #5c6fff
  secondary: #6c757d
  success: #198754
  warning: #ffc107
  info: #0dcaf0
  danger: #dc3545

[site.dark]
colors:
  primary: #8ba2ff
  success: #2ea043

Supported keys (all optional): primary, secondary, success, warning, info, danger. Use #rrggbb or #rgb hex values. Invalid hex for a key is ignored for that key only.

If no colors: block is defined, the built-in defaults apply for primary and link color in preview CSS (#526fff light / #7f98ff dark). Other semantic colors come from Bootstrap until you override them here.
[site.dark] accepts colors: and logo:. It does not affect title or any other site setting. You can override any of the same color keys for dark mode, and optionally provide a separate logo for dark mode (see Dark-mode logo below).
[site.dark] values apply automatically when the visitor's system preference is dark mode (via prefers-color-scheme: dark). There is no manual toggle.
A primary set in [site] applies in light mode only; dark mode uses [site.dark] primary if set, otherwise the default dark primary (#7f98ff). Other [site] colors apply in both modes unless [site.dark] overrides them.
Dark mode follows the visitor's OS setting through CSS only; published pages do not set a data-bs-theme attribute. In custom CSS (for example in a /// html block), target dark mode with @media (prefers-color-scheme: dark) { … }, not a [data-bs-theme="dark"] selector.
Every key you set also gets a black-or-white text color for sections on that background (--mp-{name}-contrast). For primary, the hex is also used for a darkened link hover shade.

Generated CSS variables

For primary (when set):

Variable	Value
`--mp-primary`	The hex value
`--mp-primary-rgb`	Comma-separated R, G, B
`--mp-primary-contrast`	`#ffffff` or `#111111` (WCAG contrast)
`--bs-primary`	Overrides Bootstrap's primary
`--bs-primary-rgb`	Overrides Bootstrap's primary RGB
`--bs-link-color`	Matches primary
`--bs-link-hover-color`	Primary darkened 10%
`--mp-btn-primary-bg`	The hex value
`--mp-btn-primary-hover-bg`	Primary darkened 10%
`--mp-btn-primary-color`	`#ffffff`, or `#111111` if white falls below 3:1

For each semantic key you set (including primary), the preview also injects Bootstrap 5.3–style derived variables using CSS color-mix against the current theme background, border, and body text:

Variable pattern	Role
`--bs-{name}-bg-subtle`	Tinted background (e.g. alerts, soft strips)
`--bs-{name}-border-subtle`	Tinted border
`--bs-{name}-text-emphasis`	Stronger text on subtle backgrounds

These are computed, not authored in markup; they update when light/dark theme switches because they reference --bs-body-bg, --bs-border-color, and --bs-body-color.

Section bg:primary-subtle uses var(--bs-primary-bg-subtle) (Bootstrap default when you do not set primary, or the generated value when you do).

Accessibility

Custom semantic hex values affect buttons, section backgrounds, and utilities that use those tokens. Micropage picks the text color on them for you:

Sections: text on bg:primary and on any other semantic color you set is #ffffff or #111111, whichever has more contrast by the WCAG formula. Muted text uses the same color at full strength.
Primary buttons: filled with solid primary. The label stays white unless white falls below 3:1, the WCAG ratio for large text, and then it is #111111. The two rules differ, so one color can give dark section text and white button labels. The default #526fff does this.
Outline buttons: btn-outline: follows the section's text color. On hover and keyboard focus it shows a 2px outline in that color.

A mid-tone color has limited contrast with both black and white, so check the result when you pick one.

`text:` on icons vs sections

The same spelling text: is used in two different places:

Section / hero / container (see below): text:light or text:dark only — fixed light or dark text on the section frame.
icon: lines (see Components & Aliases): text:primary, text:success, text:body-secondary, etc. — these map to Bootstrap text color utilities (text-primary, text-body-secondary, …) and use your site semantic colors when overridden.

Section modifiers

Modifiers are space-separated key:value tokens appended to the section header line after the section type. They work on section, container, and hero sections. The navbar is not a section and does not support modifiers.

/// section bg:primary
/// hero bg:primary align:center
/// section bg:dark text:light
/// section align:center

The bare token center is also accepted as shorthand for align:center:

/// section center

`bg:` — background color

Token	Background
`primary`	`var(--mp-primary)`
`primary-subtle`	`var(--bs-primary-bg-subtle)` (Bootstrap default or generated from your `primary`)
`secondary`	`var(--bs-secondary)`
`success`	`var(--bs-success)`
`warning`	`var(--bs-warning)`
`info`	`var(--bs-info)`
`danger`	`var(--bs-danger)`
`dark`	`var(--bs-dark)`
`light`	`var(--bs-light)`
`muted`	`var(--bs-secondary-bg)`

`text:` — explicit text color

Token	Color
`text:light`	`#ffffff`
`text:dark`	`#111111`

When text: is omitted:

bg:primary → uses --mp-primary-contrast (black or white by WCAG contrast)
bg:secondary, bg:success, bg:danger → --mp-{name}-contrast if you set that color, otherwise white
bg:info, bg:warning → --mp-{name}-contrast if you set that color, otherwise #111111
bg:dark → white
bg:light → #111111
bg:primary-subtle → the body text color, used for muted text too
bg:muted → no override

text:light and text:dark are fixed colors. bg:primary-subtle and bg:muted change in dark mode, so a fixed text color on them is unreadable in one mode. Leave text: out on those sections.

`align:` — column alignment

Token	Effect
`align:center`	Columns align vertically to center (`align-items-center`)
(omitted)	Columns align to the top (`align-items-start`)

Top alignment is the default, which gives a better result for unequal-height cards and pricing grids. Use align:center for image-and-text split layouts.

Dark-mode logo

[site.dark] also accepts a logo: directive. When both a light logo (in [site]) and a dark logo (in [site.dark]) are set, the renderer emits a <picture> element so the browser swaps logos automatically based on prefers-color-scheme.

[site]
logo: <- logo.svg

[site.dark]
logo: <- logo-dark.svg
colors:
  primary: #8ba2ff

Behavior summary:

Both logos set → <picture> swap via prefers-color-scheme: dark.
Light logo only → single <img> (existing behavior, unchanged).
Dark logo only → dark logo rendered unconditionally (valid but unusual).
Neither → site title text fallback (existing behavior).

Both logos should share an aspect ratio — or both carry explicit width/height — to prevent layout shift on theme change. The rendered <img> height is fixed at 32 px.

Full example

[site]
title: Color System Demo
description: Demonstrating bg:, text:, and align: modifiers
colors:
  primary: #5c6fff

[site.dark]
colors:
  primary: #8ba2ff

[nav]
Home -> /

[Home -> /]

/// hero bg:primary
h1: Welcome to My Brand
p: This hero uses the primary brand color as background.
button: Get started -> /signup

/// section bg:primary-subtle
h2: Primary subtle
p: Soft primary-tinted background — great for alternating sections.

/// section
h2: Default (top-aligned columns)
p: No bg modifier. Columns align at the top.

col:
  h3: Card A
  p: Short.

col:
  h3: Card B
  p: Longer content that stays top-aligned.

/// section bg:dark text:light
h2: Dark background
p: Explicit text:light for contrast.

/// section bg:success
h2: Bootstrap semantic token
p: success, warning, info, danger, dark, light work without any custom color config.

/// section align:center
h2: Center-aligned columns
p: Use for image-and-text split pairs.

col:
  img: <- workspace.jpg

col:
  h3: Paired with image
  p: Vertically centred next to the image.

Defining colors​

Generated CSS variables​

Accessibility​

text: on icons vs sections​

Section modifiers​

bg: — background color​

text: — explicit text color​

align: — column alignment​

Dark-mode logo​

Full example​