- ready 3
- done 1
- fixed 1
Relationships
Implemented by 6
Related 16
Branches 3
Summary
The identity transform puts the same facts on its output twice: as data attributes (data-rune, data-name, data-section, data-zone-layout, modifier values) and as BEM classes built from them (rf-codegroup__topbar, rf-hint--warning). This spec makes the data attributes the contract, and makes classes a theme setting:
classes: "bem"is the default built-in generator. It classes the vocabulary: primitives and drawings. Domain runes get no rune classes (D8). A rune not yet moved to a definition keeps today's classes, so nothing changes until each rune is converted;classes: "none"emits no classes, for classless stylesheets;- a mapping table adds the classes a theme names, so a theme can be built on a CSS framework with fixed class names (DaisyUI, Bootstrap) or on utility classes.
It also settles which runes get BEM classes, by what a rune is for, not by how it is built. Converting a rune aims at a simpler design language, not at parity with its current look: a domain rune is styled through the primitives it places and the universal dimensions, and its own stylesheet is triaged away at conversion (D11).
Before classes can be optional, the output must carry everything they carry: every fact a class holds gets a data attribute (D5), behaviour scripts select by attribute only (D6), and the contract is written in data attributes, with each theme's classes as a second layer (D7). A rune has one name, its tag name, which is also its block (D10).
Context
- ADR-043 decision 3 already made this move once. The engine stopped adding
rf-badgeto field values because "the engine emits meaning, not shape"; pill geometry moved to CSS keyed on[data-meta-type]. BEM classes are the remaining shape the engine decides. - The class prefix is already the theme's (
ThemeConfig.prefix,packages/transform/src/types.ts), so class naming is partly a theme setting today. - The question that prompted this. In an early draft of SPEC-194 D5, a native rune that moved to a definition kept its
block, and so its BEM classes, while a composed rune had none (SPEC-145 D2). Theme authors would have faced two kinds of output, split by how each rune happens to be implemented: the boundary ADR-048 set out to remove. The options considered (blocks by implementation, by role, or for every definition) each had the engine deciding a theme's class names. This spec moves the decision to the theme; its default setting then classes by role (D8).
What exists, measured
Measured on 2026-11-09.
Where the engine makes classes (
packages/transform/src/engine.ts,packages/transform/src/facets/):Class Made by Data-attribute twin today block, rf-{block}transformRune(engine.ts:351)data-runeon the rootelement, rf-{block}__{name}applyBemClasses(engine.ts:711)data-namemodifier, rf-{block}--{value}modifiersFacetyes, data-{modifier}width, spacing, inset ( --{value},--spacing-…,--inset-…)facets/box.tsyes, from the axis values --has-bgfacets/bg.tsyes, data-bg--tintedfacets/tint.ts, only when tint tokens resolvealmost: data-tintdiffers only for an unknown tint name ortint="custom"with no tokens (D5)context modifier, --{suffix}when nested in a named parent (rf-card--in-recipe)contextModifiersFacetnone static modifier, always applied staticModifiersFacetyes, in every first-party use (D5) rf-{block}__ordinalon sequence itemsnumberItems(engine.ts:905)yes, data-name="ordinal"(D5)Corrected 2026-11-09 after the D5 measurement: an earlier draft listed the last two as having no twin.
Classes made outside the engine. Some output carries hard-coded classes that no theme setting reaches, and some of them are read back by code:
- the code-block wrapper
rf-codeblock(packages/runes/src/nodes.ts:146) andrf-table-wrapper(nodes.ts:426), read back bydatatable.ts:48andcompare.ts:52; rf-nav--collapsible, written by thenavschema itself (packages/runes/src/tags/nav.ts:331);- rune markup rebuilt by hand in resolvers and helpers, with the rune's classes written literally: a drawer in
xref-preview-resolve.ts:181andfile-ref-resolve.ts:290(rf-drawer__*), and accordion items incollection-helpers.ts:323(rf-accordion-item). A theme's setting never reaches them. SPEC-194's "Candidate primitives" has these resolvers place the real runes instead, which removes the hard-coded classes; - the layout chrome in
packages/transform/src/layouts.ts: the mobile panel, the search trigger's key hint and the docs sidebar (rf-docs-sidebar, whichThemeShell.svelteselects at lines 76 and 95).
- the code-block wrapper
JavaScript selects by class.
@refrakt-md/behaviorshas 27 hard-coded.rf-selector sites, and the Svelte components 2 more (for example.rf-datatable__sort-indicator,.rf-chart__bar,.rf-codeblock), beside 40 that already usedata-nameordata-rune. Because the prefix is configurable, these break today for any theme with another prefix: a latent bug, whatever this spec decides.The contracts record class selectors.
contracts/structures.json(and its copy inpackages/lumina/contracts/) records each rune'sroot(.rf-accordion), elementselectors (.rf-accordion__preamble) and axis selectors (.rf-accordion--tinted). The CSS coverage test (packages/lumina/test/css-coverage.test.ts) derives expected BEM selectors from config and checks they exist in Lumina's CSS.Lumina is written in BEM. Its rune stylesheets hold 1,780
.rf-selectors and 894[data-*]selectors. 766 of the.rf-selectors are in stylesheets for runes planned to become compositions, which lose their block under SPEC-145 D2 anyway.The three composed runes need no rune CSS.
hero,ctaandtestimonialare styled only through the primitives they place: no selector names them in Lumina, the skeleton or the marketing plugin.
Decisions
D1: the output's contract is its data attributes
What a rune's output means is carried by data attributes: data-rune, data-name, data-section, data-zone-layout, data-meta-type, the modifier and axis attributes, and the rest of the vocabulary ADR-043 names. Classes carry nothing the attributes do not. A theme, behaviour script, component or test that needs to recognise something in the output reads its attributes.
D2: the theme's classes setting
classes: "bem" // the default: primitives and drawings get classes (D8) classes: "none" // no classes at all classes: [ … ] // a mapping table (D3) classes: { bem: { prefix: "rf" }, add: [ … ] } // BEM plus mapped classes
"bem"classes primitives and drawings (D8), naming each block after the rune'sdata-rune(D10). A rune still configured in code keeps its configuredblockand today's classes until it moves to a definition, so the setting changes no output on the day it lands.ThemeConfig.prefixbecomes this generator's option."none"serves classless stylesheets (Pico, Water.css), and themes written entirely against data attributes.- The setting is declarative. It is data in the theme's config, never a function. A theme stays possible as data and CSS alone, and no theme code runs in a hosted site.
- It only adds classes. It cannot add or remove attributes or elements, or remove classes an author wrote. So it can never become a way around SPEC-194 D11.
- A site may extend its theme's setting, as it overrides tokens: its
addentries are appended after the theme's.
D3: the mapping table
classes: [ { match: { rune: "hint" }, add: "rounded-lg border p-4" }, { match: { rune: "hint", "hint-type": "warning" }, add: "border-amber-400 bg-amber-50" }, { match: { "zone-layout": "bar" }, add: "flex items-center gap-2" }, { match: { section: "header" }, add: "font-semibold" }, { match: { "meta-type": "status" }, add: "badge" }, ]
Match keys are the vocabulary.
rune: the element's owning rune (D4);name: itsdata-name;root: true: the rune's root element;section,zone-layout,meta-type,media: their attributes;- any other key matches the
data-<key>attribute; parent: the parent rune, for what context modifiers express today.
Every key in an entry must match. An unknown key, or a value outside a closed vocabulary set, is reported when the theme loads.
All matching entries apply, in table order, and their classes are joined. There are no priorities and no removal.
Class names appear literally in the table, so Tailwind's content scanner, pointed at the theme's config, sees every utility the table uses.
Matching on
runeis presentation, not rune configuration. It is the same power as CSS on[data-rune], which ADR-043 lists as the theme's special-case hook. The add-only rule (D2) is what keeps it presentation.
D4: an element's owner is its nearest ancestor with data-rune
BEM element classes are owned: today the engine gives rf-codegroup__topbar only to codegroup's own elements, never to an element of a rune nested in one of its slots. The class setting keeps that. An element belongs to its nearest ancestor that carries data-rune, and rune in a match (and the block in "bem") is that owner. This is exactly the owner the engine uses today.
The setting is applied in the engine's existing pass, where applyBemClasses runs now. It does not add a second walk over the tree.
D5: every fact a class carries becomes an attribute first
Before classes become optional, each fact that only a class carries today gets a data attribute. The engine then emits both, so that nothing is lost when a theme chooses "none":
| Class only today | Attribute |
|---|---|
context modifier (rf-card--in-recipe) | data-in="<parent rune>" on runes that declare the parent |
| static modifier | none needed: retarget the CSS |
rf-{block}__ordinal | none needed: already data-name="ordinal" |
--tinted (tokens resolved) | data-tinted, a presence flag; the class itself is styled nowhere |
Settled 2026-11-09 by a measurement of every producer and every CSS selector:
- Context modifiers are the only fact truly lost under
"none". 9 runes declare them (hintinheroandfeature,actionsinbar,showcaseinbento-cell, three design runes indesign-context,previewandfeature). Lumina and the skeleton use them in 31 selectors, most oftenactions--in-bar(11) andshowcase--in-bento-cell(6). The parent'sdata-runeis on an ancestor, but no ancestor selector says "the nearest enclosing rune". Every suffix is exactlyin-plus the parent's name, socontextModifiersreduces to a list of parents, anddata-incarries it. - Static modifiers are already said by attributes in every first-party use:
rf-featured-tier--featuredbydata-rune="featured-tier", and thecovermodifier oncard,sectionandrecipebydata-media-position="cover"anddata-cover-scope. The 14 selectors using them (9section--cover, always beside[data-media-position="cover"], and 5tier--featured) are retargeted, and the field is deprecated (SPEC-194 D5). - The ordinal is already satisfied. The engine emits
data-name="ordinal"anddata-meta-type="quantity"on it (engine.ts:903), and every rule styling it uses[data-sequence="numbered"] > li > [data-name="ordinal"]. No CSS uses the class. --tintedis styled nowhere (0 selectors;[data-tint]has 16). It differs fromdata-tintonly for an unknown tint name ortint="custom"with no tokens.data-tinted=""follows thedata-tint-dark=""convention.data-tintis not narrowed, since that would change what existing[data-tint]rules match.- The names are free.
data-in,data-tinted,data-coveranddata-featuredappear nowhere in the packages or plugins.data-parentis taken (arealmfield), which is whydata-inis used.
Each addition is additive: no existing selector stops matching.
D6: behaviour scripts and components select by attribute only
Selectors in @refrakt-md/behaviors and the Svelte components move to data-name, data-rune and the other vocabulary attributes, and a test fails on any .rf- selector there. This is worth doing first and regardless: it fixes the latent prefix bug.
Measured 2026-11-09 (every behaviour and web component read; a few toolbar builders skimmed):
- 27 class-selector sites, plus 2 in Svelte (
ThemeShell.svelteselectsrf-docs-sidebar):13 select classes the behaviour injected itself, and keep matching under
"none";14 select classes something else emits, and break. Their swaps:
Behaviour Selects Becomes drawer.rf-drawer__close[data-name="close"](exists)rf-diagram.rf-diagram__container; returns before rendering under"none"[data-name="container"](exists)rf-map.rf-map__container,ol[data-name="container"],[data-name="pins"](exist)mockup.rf-mockup__frame, andparentElementof the host[data-name="frame"](exists),closest('[data-section="media"]')datatable.rf-datatable__scroll[data-name="scroll"](exists)copyrf-codeblock(×2)a new attribute on the code-block wrapper mobile-menu.rf-mobile-paneland--nav(×3)new attributes on the layout chrome search.rf-search-trigger__kbda new attribute on the layout chrome Three of the 14 are dead:
.rf-map__fallbackandsection-nav's.rf-plan-relationships(×2) have no emitter anywhere.
- Classes written onto rune-owned elements must stop, since under
"none"they put classes back:reveal(rf-reveal-step--visible/--hidden),tabs(an--activeclass derived from the first button's class, which a mapping would turn into junk likepx-3--active), the audio player (rf-track--active) andcopy. Each already has, or gets,data-state, and the CSS moves to it. - Classes on elements a behaviour creates (about 70
className =writes: toolbars, buttons, indicators) are the behaviour's own UI. They also get adata-name, so the CSS styling them can move to attributes and"none"holds for the whole page. They are lower priority than the two kinds above, because nothing breaks while they keep their classes. - Classes made outside the engine (listed under "What exists") get data-attribute twins, so the swaps above have something to select.
- A bug found on the way:
nav-menubarlooks for each group's list as:scope > ul, :scope > ol(packages/behaviors/src/behaviors/nav-menubar.ts:30), butnav-groupalways wraps its items in<div data-name="panel">(packages/runes/src/tags/nav.ts:252), so every group is skipped. It was confirmed by reading, not run, and there is no menubar behaviour test. The swap to[data-name="panel"]fixes it. Filed as BUG-048, to be fixed on its own, ahead of this spec.
D7: contracts in two layers
- The vocabulary contract is theme-neutral. It records each rune's structure in data attributes (
[data-rune="accordion"],[data-name="preamble"], axis attributes), wherestructures.jsonrecords.rf-selectors today. It is whatrefrakt contracts --checkgates, and what ADR-043 decision 5's vocabulary coverage check reads. - A theme's class contract records the classes its setting produces for each element. It is generated by running the setting over the vocabulary contract, and shipped in the theme's
contractsexport, as Lumina shipsstructures.jsontoday (and as ADR-045 already makes contracts per theme for templates). - Lumina's CSS coverage test reads its expected selectors from Lumina's class contract instead of deriving BEM from config. With
"bem", the selectors it checks are the ones it checks today. - The two committed copies of
structures.jsonstay in lock-step as now. The vocabulary contract replaces them, and Lumina's class contract is added beside its copy.
D8: "bem" classes primitives and drawings, never domain runes
Revised 2026-11-09. An earlier draft gave every rune classes under "bem", composed ones included, so that existing rune CSS would keep matching after conversion. Parity is the wrong goal: a class that exists invites a rule that names the rune, which is the per-rune styling ADR-044 drains. So "bem" classes only what the shared design language is made of:
A definition's role | What it is | Classes under "bem" |
|---|---|---|
primitive | something other runes place: section, card, grid, tab-group, the value primitives, nav's tree | rf-{rune} and its elements: these are the vocabulary themes style |
drawing | a rune whose inside the vocabulary cannot express: chart, map, diagram, audio, juxtapose (SPEC-194 D8) | rf-{rune} and its elements, as hooks for its own token-only CSS (ADR-044 tier 3) |
| domain (the default) | a rune that arranges primitives: recipe, hero, embed, pagination, collection | none. It carries data-rune and its parts' data-names like every rune, and is styled through the primitives it places |
roleis declared in the definition (SPEC-194 D1). It defaults to domain, so a rune has to claim to be part of the vocabulary.The test for
role: primitive(added 2026-11-09). Both must hold:- another rune places it, or a planned one will, and the definition names that rune in
placedBy(pullquote:placedBy: [testimonial];codegroup:placedBy: [preview]); - its look is the same wherever it appears. A code window looks like a code window in a recipe, a doc or a design preview. A domain rune is the opposite: its identity is its meaning, so its look comes from the primitives it places.
hintfails the second: a warning looks like a warning because of what it means, which is what SPEC-163'ssentimentaxis carries.recipe,paginationandcollectionfail both.- another rune places it, or a planned one will, and the definition names that rune in
Changing a rune's role is reviewed like an allowlist entry (D11): with a recorded reason. A primitive's CSS is vocabulary and sits outside the allowlist, so claiming the role is the one way to keep rune CSS, and it must not become a loophole.
For composed domain runes this is SPEC-145 D2 unchanged: no block, and no CSS shipped. A composed primitive (
cardonce SPEC-160 D3 composes it) does get classes, which is the one amendment to D2.The rare special case a theme needs for one domain rune is CSS on
[data-rune], which ADR-043 lists as the theme's special-case hook, and which D11's lint keeps on a reviewed list.A theme that wants per-rune classes can add them with a mapping entry (
{ match: { rune: "recipe" }, add: "…" }). It is possible, explicit, and never the default.
The three composed runes show that this works: hero, cta and testimonial have no rune CSS anywhere and render through section, pullquote and the universal dimensions.
D9: migration
- Nothing changes on the day the setting lands. Every rune is still configured in code (and keeps its classes) or is a composed domain rune (which has none already), so Lumina's CSS, every site's CSS and the SEO and structure baselines are untouched.
- Classes then change one rune at a time, when the rune becomes a definition: a domain rune loses its classes through D11's triage, and a primitive keeps them unchanged (D10). Each is a breaking change for that rune, recorded in its migration note, as SPEC-181 already does for each composition's go-live.
- D5 is additive (new attributes only), and D6 is internal to refrakt's packages.
- D7 changes the contract file's shape. That is a breaking change for anyone reading
structures.json, and it ships through SPEC-189's migration table.
D10: a rune has one name, its tag name
Decided 2026-11-09; revised the same day after the acceptance review. A definition has one name: the tag authors write, which is also its file name (pullquote.md). The "bem" generator names a block after it, and the rune's data-rune is the same name. block stops being a separate setting: definitions already reject a block key (STYLE_KEYS, packages/runes/src/lib/composition.ts:1735).
The measurement that decided it. Eight native runes carry two names today, and in every case the tag name equals the BEM block. Only data-rune differs:
| Tag (and block) | data-rune today | Role (provisional) | References to the old data-rune in source |
|---|---|---|---|
codegroup | code-group | primitive: a code window, placed by preview | 4 |
toc | table-of-contents | domain | 5 |
pullquote | pull-quote | primitive, placed by testimonial | 3 |
textblock | text-block | primitive, to confirm | 2 |
mediatext | media-text | primitive | 2 |
tabs | tab-group | primitive | 3 |
datatable | data-table | primitive | 4 |
howto (learning) | how-to | domain, a planned composition | — |
So naming the rune after its tag changes no class: about 190 .rf- selectors keep matching. What changes is data-rune, which source references 2 to 5 times per rune, including the rune's own declaration. An earlier draft named the rune after its data-rune and renamed the classes instead; that would have moved every selector.
- The
data-runechanges ship through SPEC-189's migration table, each when its rune becomes a definition: CSS, behaviours and component registries that select the old value move to the tag name. The old names are kept as tag aliases where authors use them (pull-quotealready is one). - A domain rune still loses its classes when it becomes a definition (D8), and its CSS is triaged (D11). A primitive keeps them, unchanged.
featured-tieris not a tag but a value oftier'sfeaturedattribute that today gets its owndata-rune. In thepricingcomposition (SPEC-161 D4) it becomestierwithdata-featured, and its classes stayrf-tier.- Roles are settled rune by rune, in the work item that gives each its definition, by D8's test.
D11: a converted rune ships no rune CSS: its stylesheet is triaged
Decided 2026-11-09. Converting a rune, to a composition or to a native definition, aims at a simpler design language that relies on primitives and universal dimensions, not at parity with how the rune looks today. So conversion is where its stylesheet is dealt with, rule by rule.
Every rule in the rune's stylesheet ends in one of three places:
| Outcome | When | Example |
|---|---|---|
| dropped | the difference is an accepted simplification | a rune-specific gap or border the primitive's own spacing replaces |
| promoted | the rule expresses something other runes need too | a new universal dimension value, an arrangement, a primitive option, a vocabulary value (data-meta-type, data-sentiment) |
| an exception, on the list | the rune is a drawing (D8), or a reviewed special case on [data-rune] | map's tiles, chart's bars |
Visual differences after conversion are expected. Each one is either accepted or becomes a vocabulary improvement that every rune gets.
A lint holds the line where CSS is written. Lumina's coverage test fails on any selector naming a domain rune (.rf-<rune>… or [data-rune="<rune>"]) that is not on a reviewed allowlist:
- the allowlist starts as today's rune stylesheets, so nothing fails on the day the lint lands;
- it may only shrink: a test fails if an entry is added without a drawing role or a recorded reason;
- each conversion removes its rune from the list, which is its triage gate (SPEC-181's fifth go-live gate);
- drawings keep their entries, with their CSS in tokens only (ADR-044 tier 3).
The scale is real. About 1,000 of Lumina's 1,780 rune-stylesheet selectors belong to runes that stay native, mostly domain runes (collection, pagination, embed, form, blog, relationships, actions and others). nav alone has 229, and most of those stay with its tree primitive. Triaging them is design work, not a mechanical migration. The allowlist lets it happen one rune at a time.
Rationale
- It moves a presentation decision to the presentation layer. Class names are how a stylesheet is organised. They have never been meaning, and the output already carries the meaning separately.
- It ends the native/composed split in CSS. Whether a rune has classes follows from what it is for (D8), never from how it is built.
- It keeps pressure on the vocabulary. A domain rune that cannot be styled through primitives and dimensions shows a gap in them. D11 turns that gap into a vocabulary improvement instead of another rune stylesheet.
- It makes existing CSS frameworks usable as themes. A framework with fixed class names (DaisyUI's
btnandalert, Bootstrap'scard) cannot be retargeted with selectors; a mapping is the only way to use it. Utility-first themes gain less: a Tailwind site can already write[data-rune="hint"] { @apply … }against today's output. Classless stylesheets gain"none". - It costs nothing by default and runs in a pass the engine already makes.
Acceptance criteria
- Every fact a class carries today also has a data attribute (D5), and a test derives the list of classes from the engine and fails on one without a twin
@refrakt-md/behaviorsand the Svelte components contain no.rf-selectors, and a test enforces it (D6)- On the day
classes: "bem"lands, output is byte-identical to today across the structure contracts, the SEO baseline and Lumina's CSS coverage test (every rune is still configured in code or is a composed domain rune) - Under
"bem", a definition withrole: primitiveorrole: drawinggetsrf-{rune}classes, and a domain definition gets none (D8) - Lumina's coverage test fails on a selector naming a domain rune that is not on the allowlist; the allowlist starts as today's rune stylesheets and a test fails when an entry is added without a drawing role or a recorded reason (D11)
classes: "none"produces output with no engine-made classes, and every behaviour still works- A mapping table adds classes by vocabulary match, joins all matching entries in order, reports unknown keys and values, and cannot add attributes or elements
- An element's owner for matching and for
"bem"is its nearest ancestor withdata-rune(D4), with a test on nested runes - The vocabulary contract records data-attribute selectors, and Lumina ships a class contract generated from its setting (D7)
- A fixture theme built on a mapping table renders
hint,codegroupand a composedherowith framework classes only - A definition's
data-runeis its tag name; the eightdata-runechanges in D10 ship through SPEC-189, and no class changes for a primitive - The engine emits
data-infor declared parents anddata-tintedwhen tint tokens resolve (D5) - Behaviour scripts keep their state in
data-state, not in classes written onto rune-owned elements (D6) - A site can append entries to its theme's
classessetting, andprefixis an option of the"bem"generator (D2) - A definition with
role: primitivenames the runes that place it (placedBy), and a change of role is reviewed with a recorded reason (D8) - The theme-authoring docs describe the setting, with
"bem","none"and a mapping-table example
Open questions
- Combining settings across themes. A theme that extends Lumina may want Lumina's BEM plus its own mapped classes;
{ bem, add }covers that. Whether a child theme can also drop the parent's mapping is undecided; add-only suggests not. - Specificity. Rules written against data attributes and descendant combinators have different specificity from single classes. A theme moving from BEM to attribute selectors may need
@scopeor:where()to keep its cascade. That is guidance for theme authors, not a constraint on this spec, but the docs should say it. - The editor. Its previews show the active theme's classes. Nothing should depend on them, but it is worth checking that the editor reads attributes, as D6 requires of behaviours.
References
- ADR-043: decision 3 (the engine emits meaning, not shape) and decision 5 (vocabulary coverage).
- ADR-044: Lumina's per-rune CSS drains as runes compose.
- ADR-045: contracts per theme.
- ADR-048, SPEC-194: the native/composed boundary this removes from CSS; SPEC-194 D1 makes a rune's tag name its only name.
- SPEC-145: D2 and D2a, which D8 keeps for domain runes and amends for composed primitives.
- SPEC-181: the go-live gates D11 adds a fifth to.
- SPEC-189: the migration table for the contract change.