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.

Upgrade guide

docs/upgrade-guide/plone-aurora.md gets a section for 1.0.0-alpha.19, "Block content is styled in styles/content.css". It has one subsection per breaking change of #199 and #200, each with a versionadded, versionchanged or versionremoved admonition:

• the cmsui layer is removed, and plone-content is added to config.settings.cssLayers (Move the Tailwind reset out of the top cascade layer in the CMS UI (#199 A1) #203);
• the styles/content.css entry point, and the editor's content-area root (Add the styles/content.css entry point to the add-on styles loader (#199 A2) #204, Move the image block and inner container styles to styles/content.css (#199 A3) #205);
• block content has no Tailwind classes (Move the text block styles to styles/content.css (#200 Phase 2) #209–Content CSS Phase 8: structural blocks and content root to styles/content.css #216);
• block spacing applies in the editor (Content CSS Phase 9: share the block spacing between the Public UI and the editor #217);
• the Plone block class renames (Content CSS Phase 10: Plone blocks use the content contract classnames #218);
• the Plate.js media nodes are removed (Content CSS Phase 7: remove the Plate media nodes from Aurora's presets #215);
• EditorView and PlateRenderer don't take variant (Content CSS Phase 8: structural blocks and content root to styles/content.css #216).

Nothing was deprecated first: the changes take effect directly, and the guide says so. The media removal fragments are now breaking, and the variant removal has its own breaking fragment.

Wording

The block docs and the plate AGENTS.md say "Plate.js blocks" instead of "native" blocks, as suggested in review. Other docs pages are tracked in #231.

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.

[davisagli]

I would remove the word "native" here and just say Plate block (what is native depends on context and assumptions).

Why do the classes say slate instead of plate?

[sneridagh]

Ok, I will take note and do a full pass at the end.
The base plate libraries use this convention, leaving slate naming in the classnames. Change it would be painful, I think it's fine...

[sneridagh]

Done in ecabff0: the block anatomy doc and the new "Style blocks in a theme" guide now say "Plate.js blocks" instead of "native" blocks. That includes the older "Plate-native" mentions in the block anatomy doc, so the page is consistent. Other docs pages that say "Plate-native" aren't part of this stack; they can get the same pass separately.

[sneridagh]

LGTM