Design tokens #

styles/theme.css styles rendered Markdown through --md-* custom properties. Put class="md" on the element that holds the HTML.

<link rel="stylesheet" href="mdlib-pure/theme.css" />
<article class="md">…rendered markdown…</article>

How the theme behaves #

• Zero specificity. Every rule is inside @layer mdlib and :where(). Any class, utility or unlayered rule of yours wins, with no !important.
• Inherits the page. Text color and fonts are not set unless you set the tokens marked "unset" below: an undefined var() makes the property fall back to inheritance.
• Neutrals follow the text color. Borders, surfaces and muted text are color-mix() of currentColor, so they fit light and dark backgrounds without configuration.
• Hues follow color-scheme. Link, accent, mark and alert colors use light-dark(). Declare color-scheme: light dark on :root (and <meta name="color-scheme" content="light dark">), or color-scheme: dark on your .dark class.
• Where tokens live. Defaults are declared on :root and :host (so they also reach shadow DOM). Override them on :root, on .md, or on any ancestor to theme a single section.

Browser support: Baseline 2024.

Color #

Typography #

Space and shape #

Tailwind CSS v4 #

@import "tailwindcss";
@import "mdlib-pure/tailwind.css";

/* Map the tokens to your design system */
:root {
  --md-color-link: var(--color-primary);
  --md-font-heading: var(--font-display);
}
.dark { color-scheme: dark; }

tailwind.css loads the theme into Tailwind's components layer, so utilities always win, and .md looks the same with or without Tailwind: the theme undoes what Tailwind's preflight resets inside it (list markers, link underlines, inline images, heading sizes, spacing). A browser test compares every element of a sample document in both setups. It also exposes the tokens as theme values: text-md-link, bg-md-surface, border-md-border, bg-md-code-bg, text-md-muted, font-md-mono. No radius utility is added: rounded-md belongs to Tailwind (use rounded-[var(--md-radius)]).

Without the theme, plain semantic output works with @tailwindcss/typography (<article class="prose">), or add utilities per node type with the classes option (see the README).

Podcast sample tokens #

The podcast sample scopes these tokens to .podcast in site/assets/podcast.css. They belong to the example, not to the core theme.

Tag chips (.podcast-tag) carry their own background and text colour inline: the colour belongs to the name, not to the theme.

Naming rules (for contributors) #

--md-{category}-{role}[-{state}]: --md-color-link-hover, --md-space-block. Name the role, never the value: --md-color-surface, not --md-gray-50. Every new token goes in this file.