Content CSS Phase 11: theming guide for blocks and cleanup

[sneridagh]

Phase 11 of #200, the last one: a theming guide for blocks, fixed docs examples, and the last Tailwind helper left in content code. No visual change.

Stacked on #218 (Phase 10). The base is b10-plone-blocks. This PR's own change is only the last commit.

Changes

New how-to: "Style blocks in a theme"

docs/how-to-guides/style-blocks-in-a-theme.md, linked from the how-to index, covers:

• Where block styles go: an add-on's styles/content.css, loaded in both the Public UI and the editor. It links to the authoring rules in the styles loader guide (Content CSS architecture: cascade layers, reset placement, and a shared block-styles entry point #199).

• Two ways to change a block: set a token on .content-area (preferred), or override a rule, since the framework rules have zero specificity.

• The hooks: block root, Plate node, inner part and variant.

• Every block's parts and variants:

  • native blocks: paragraph and lists, headings, blockquote, separator, code block, table, callout, toggle, columns, table of contents, and inline elements;
  • Plone blocks: image, video, teaser, listing and maps.

• Every token, with its default:

  • layout (--block-bottom-spacing, the container widths, --block-float-max-size);
  • native blocks (--block-*-background, --block-separator-color, --block-table-border-color, …);
  • all --code-token-* syntax colors and the hljs-* classes each one covers;
  • the theme values the framework reads with fallbacks.

  It also names the internal properties a theme shouldn't set.

• Examples: dark code blocks via prefers-color-scheme, and a callout override.

• Resets: a theme's own reset belongs in the base layer.

Docs fixes

• add-on-styles-loader.md: the override example used a .block-image__caption part that doesn't exist. It now uses the callout's real rule and token, and links to the new guide.
• block-anatomy.md:
  • The shared-type-name example used block-video, but since Content CSS Phase 7: remove the Plate media nodes from Aurora's presets #215 Aurora has no native video node; it's now generic.
  • Part names shared across blocks are the real ones (__link, __item, __image).
  • It says which acceptance tests guard the contract.
  • The heading says "themes", not "themers".
• Vale: the accept list gets "blockquote", "callout" and "classname". The docs already used them.

Cleanup

• BlockInnerContainer merges its classes with clsx, not cn: cn is twMerge. The content code's other Tailwind helpers (cn, cva) went away in Phases 2–8.
• Kept on purpose: EditorStatic's cva. Only the stock full preset's export and AI chat use it, which makes it chrome.

Validation

• make docs-html: builds. The 6 warnings are all pre-existing: news fragments outside a toctree, and a /storybook link.
• Vale on the changed pages: no new errors. The remaining ones are the vocabulary's pre-existing Plone term pattern, flagged on every page.
• CI=1 pnpm visual-test --retries=0: 26/26 pixel-identical.
• pnpm acceptance-test: 182 passed.
• pnpm --filter @plone/plate test --run: 75 passed. check:ts and eslint: clean.

With this, the phases of #200 are complete. What's left is the review and merge order of the stack, and the VRT baseline updates noted in #217 and #218.

Part of #200.