The DOM contract and theming
DOM 契约与主题化
The renderer emits structure, class hooks and data attributes, and nothing else. This page sets out the two attribute families, the document shell, the token-first approach a theme should take, and the theme-swap test that keeps styles separate from content.
Theming
The renderer emits structure, class hooks and data attributes. It never emits colours, fonts, widths or animation. A theme is a plain CSS file written against that contract, and swapping the theme changes nothing in the data.
Two attribute families
- class hooks are for themes. They are prefixed ab- and follow a block, element, modifier pattern: ab-quote, ab-quote__by, ab-quote--attributed
- data attributes are for the editor and for scripts: data-role, data-block, data-field, data-gallery
Themes must not select on data attributes, and editors must not select on classes. The only inline style the renderer writes is a custom property carrying a fact, such as the ratio of a photograph or the number of items in a sheet. A theme decides what to do with it.
The document shell
Every page renders as an article with the class ab-doc and a modifier for the family's presentation variant. The head holds the apparatus fields. The cover, when present, comes next. A block-stream body follows, one wrapper per block with its kind and its stable id. Remaining fields and repeatable groups follow in the order the type declares them. A closing gallery holds photos the body did not place.
Tokens first
plain.css defines a working default for every token, so a site that sets nothing still renders legibly. A theme overrides tokens on ab-doc and ab-list first: fonts, sizes, colours, measure, spacing, photo ratios, motion. Only when a token cannot express the design does the theme reach for selectors. Family variants get their own token overrides, for example a different accent colour for columns.
Computed modifiers
Some facts about the data are exposed as modifier classes the renderer computes: whether a figure is landscape or portrait, whether a sheet is uniform or mixed, whether a cover should be cropped or shown whole. A theme may honour them or ignore them.
Overriding a block
A site may supply its own renderer for a block kind. It renders inside the wrapper the package always emits, so the editor's hooks survive any override.
The theme-swap test
The test suite renders the same fixture document, strips class and style attributes, and asserts the DOM is identical regardless of theme. Passing that test is what it means to change styles without touching content.