Typography tokens for block content, inspired by shadcn Typeset #241

Summary

Give block content a small set of typography tokens that themes set on .content-area: fonts, base size, line height, vertical rhythm, and a heading scale. The model is shadcn's Typeset, but we adopt its philosophy, not its CSS file: the tokens feed the existing content.css rules from #200. Today's values become the defaults, so introducing the tokens is zero-diff.

Background

#200 moved block content from Tailwind utilities to plain CSS in each package's styles/content.css, in the plone-content layer, with zero-specificity rules and no reliance on a reset. Theming block colors and spacing is documented in Style blocks in a theme. Typography is the part that's still hard to theme, because the rules read Tailwind's global type scale directly.

How content typography is themed today

Problems this causes

• The editor and the public view disagree on typography, because Agave's typography lives in publicui.css (Block content: settle the visual quirks kept for zero diff in #200 #227, item 4).
• Under Agave, h6 renders larger than h5 in the public view. Agave raises --text-base to 1.15rem (18.4px) for body text, and .slate-h6 happens to read --text-base, while h5 reads --text-lg (18px). Raising the site's base text size reshuffles the heading order because the headings read the UI's global type scale.
• <sub> and <sup> have no content.css rules, so their size and position depend on the reset (Remove Tailwind from block content in @plone/plate and @plone/blocks #200's rule: content must not rely on one).

What Typeset does, and why we shouldn't ship it as is

Typeset is one CSS file that styles HTML inside a .typeset wrapper. Everything derives from three rhythm variables, --typeset-size, --typeset-leading and --typeset-flow, and three fonts, --typeset-font-body, --typeset-font-heading and --typeset-font-mono. Heading sizes, the gap under a heading, list indents and the space around rules all follow from them. Presets are classes that reset those variables, such as .typeset-docs and .typeset-chat, and not-typeset opts a subtree out.

#156 tried the file itself. It doesn't fit Aurora's content model:

• Cascade layer: it lives in components, so it loses to the base reset and sits below the content layer. Aurora's content styles belong in plone-content.
• Element selectors: it styles every h2 and p inside the wrapper, including those inside Plone blocks (teaser titles, listing items) and editor chrome. Each would need not-typeset. Aurora's rules target Plate nodes (.slate-h2), so they already scope themselves to the content.
• Spacing direction: it spaces blocks with margin-block-start. Aurora spaces them with the inner container's padding-bottom (--block-bottom-spacing), so the two would add up.
• Concerns Aurora doesn't share: streaming stability matters for chat output, not CMS content. Leaving the maximum width to the layout is already how Aurora works.

What's worth adopting is the token model: a handful of semantic values on the content root, with everything else derived from them, and presets as classes.

Proposal

Tokens

Set on .content-area, read by the content.css rules of @plone/plate and @plone/layout. Defaults are today's values, so nothing changes until a theme sets a token.

• Naming: --content-* is for content-wide typography; --block-* stays for values that belong to one block, such as --block-callout-background.
• Heading margins stay in em, so they scale with each heading's size automatically, as Typeset does.

Heading scale

The per-level tokens make every heading independently overridable. As a second step, their defaults can derive from one ratio, which makes the h5/h6 kind of inversion impossible:

:where(.content-area) {
  --content-scale: 1.25;
  --content-h6-size: var(--content-size);
  --content-h5-size: calc(var(--content-size) * var(--content-scale));
  --content-h4-size: calc(var(--content-h5-size) * var(--content-scale));
  /* … */
}

That changes how headings look, so it's a separate, deliberate step.

Presets

A preset is a class that resets a few tokens, as in Typeset:

.content-area.is-compact {
  --content-flow: calc(var(--spacing) * 2);
  --content-leading: 1.4;
}

.content-area.is-large-text {
  --content-size: 1.25rem;
  --content-leading: 1.7;
}

How a preset gets applied (site setting, content field, or theme-only) is out of scope for the first phases.

Agave

Agave's typography moves from publicui.css to agave/styles/content.css, as token values instead of bare h2/h3 rules with @apply. The editor then shows the same typography as the public view. This replaces #227's item 4.

/* packages/agave/styles/content.css */
.content-area {
  --content-font-body: 'Funnel', sans-serif;
  --content-font-heading: 'Funnel Display', serif;
  --content-size: 1.15rem;
  --content-leading: 1.5rem;
  --content-heading-weight: var(--font-weight-normal);
  --content-title-size: var(--text-5xl);
  --content-h2-size: var(--text-3xl);
  --content-h3-size: var(--text-2xl);
}

Gaps to close along the way

• sub and sup: add content.css rules (size, vertical-align, line-height) so they don't depend on the reset, and cover them in a reset-independence test.
• h5 versus h6 under Agave: fixed by giving h6 its own content token, so it no longer reads the UI's --text-base.

Documentation

Already available

• Style blocks in a theme: where content styles go, setting tokens on .content-area versus overriding rules, every block's classnames, and the current tokens. Its "Theme values" section lists the Tailwind values the content reads today, such as --text-sm and --font-weight-bold. This proposal replaces those for typography.
• Add-on styles loader: the plone-content layer and the authoring rules for styles/content.css.
• Block anatomy: the classname contract (slate-<type>, block-<type>__<part>, data-attribute variants).
• Upgrade guide: the Content CSS architecture: cascade layers, reset placement, and a shared block-styles entry point #199 and Remove Tailwind from block content in @plone/plate and @plone/blocks #200 changes, under "Block content is styled in styles/content.css".

To add: a "Theme the typography" section in "Style blocks in a theme"

A draft of the section, to land with the tokens:

## Theme the typography

Block content takes its typography from a few tokens on `.content-area`.
Set them in your add-on's `styles/content.css`, and they apply in both the Public UI and the editor.

```css
/* my-theme/styles/content.css */
.content-area {
  --content-font-body: 'Source Serif 4', serif;
  --content-font-heading: 'Inter', sans-serif;
  --content-size: 1.125rem;
  --content-leading: 1.7;
  --content-flow: 1rem;
}
```

- `--content-size` and `--content-leading` set the text of paragraphs, lists, blockquotes, and table cells.
- `--content-flow` sets the space between blocks. Heading margins are in `em`, so they follow each heading's size.
- Each heading level has its own size and line height, from `--content-title-size` and `--content-h1-size` to `--content-h6-size`. Set one to change that level only.
- `--content-heading-weight` and `--content-heading-tracking` set the weight and letter spacing of `h2` to `h6`.

To offer a variant, such as denser or larger text, define a class that resets a few tokens, and add it to the content root:

```css
.content-area.is-large-text {
  --content-size: 1.25rem;
  --content-leading: 1.75;
}
```

Don't set font sizes on `h2` or `p` directly: the tokens keep the editor and the public view consistent, and they keep the heading levels in order.

Phases

1. Tokens with today's values as defaults (zero diff):
   • content.css reads the new tokens, with the current values as fallbacks.
   • Validation as in Remove Tailwind from block content in @plone/plate and @plone/blocks #200: pixel-exact visual tests, a reset-independence test, and the docs section above.
2. Agave on tokens (accepted visual change, editor only):
   • Agave's typography moves to content.css as token values, and its bare h2/h3 and .content-area typography rules leave publicui.css.
   • Closes Block content: settle the visual quirks kept for zero diff in #200 #227's item 4 and the h5/h6 inversion. The editor screenshots change; the public ones shouldn't.
3. sub and sup rules, with a reset-independence test.
4. Optional: derive the heading sizes from --content-scale, and document presets. Visual change, decided separately.

Open questions

1. Naming:
   • --content-* (proposed): content-wide, and distinct from per-block --block-*;
   • --typeset-*: signals the lineage, but suggests compatibility with shadcn's file;
   • --block-*: one namespace, but blurs content-wide and per-block values.
2. Heading sizes: explicit per-level tokens only, or derived from --content-scale by default? Explicit is easier to read; derived prevents ordering bugs.
3. Rhythm: should --content-flow become the default for every category's --block-bottom-spacing, with the heading and action categories as multiples of it, or only for text blocks?
4. Agave's body text: does font-thin stay a theme choice, as --content-weight, or go?