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] only overrides colors:. It does not affect title, logo, or any other site setting. You can override any of the same keys for dark mode.
• [site.dark] values apply automatically when the visitor's system preference is dark mode (via prefers-color-scheme: dark). There is no manual toggle.
• For primary, the hex is also used for luminance-based contrast (--mp-primary-contrast) and 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%

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. Pick colors with adequate contrast for text on solid backgrounds (especially bg:primary, bg:success, etc.). Subtle tints are meant for low-emphasis surfaces; avoid relying on them for small text without checking contrast.

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)
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 (auto-computed from luminance)
• bg:success, bg:danger, bg:info, bg:dark → white text
• bg:warning → dark text
• bg:primary-subtle, bg:muted → no override (dark text works fine)

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.

---

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

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