What happens
parisek/styleguide's ComponentParser decides whether a component is renderable from three signals: a styleguide.twig, any named variant sibling, or an explicit styleguide: true in the component metadata (ComponentParser.php:220 and :289). The third exists for components that render themselves globally and ship no fixture of their own.
schemas/component.fields.schema.json does not list styleguide among its root properties and sets additionalProperties: false, so the key cannot be carried in a <name>.yaml.
The same parser is YAML-first: once <name>.yaml exists it becomes the metadata source and the twig front-comment stops being read entirely. So for a component whose only catalogue claim is styleguide: true, authoring a definition silently drops it out of the catalogue — and with it, any visual or behaviour coverage keyed off the catalogue entry.
Nothing errors in either direction, which is what makes it worth reporting.
Reproduction
On a parisek/styleguide consumer, take a component that has no styleguide.twig and carries styleguide: true in its twig front-comment (ours is a cookie-consent bar — global chrome, renders itself, no fixture).
vendor/bin/fields-migrate path/to/component/<name> — succeeds, reports OK. The styleguide key is dropped, since the schema has no slot for it.- Run the catalogue audit — the component now appears in the "no fixture, nothing renders it" list.
- Delete the sidecar — it moves back out.
- Try to keep the key by hand-adding
styleguide: true to the YAML — fields-validate rejects it on additionalProperties.
There is no state in which the component has both a definition and its catalogue entry.
Suggested fix
Add styleguide (boolean) to the schema's root properties. It is metadata the styleguide package already consumes, and it projects into neither acf.json nor block.json, so it is inert for every generator and lint downstream.
The general rule behind the specific fix, which may be worth checking more broadly than this one key: every root key ComponentParser reads has to be expressible in a definition, or the two metadata formats are not interchangeable — and the YAML-first precedence already treats them as if they were. styleguide is the one we hit; it may not be the only one.
Downstream state
We are backfilling YAML sidecars across the whole component set. Every Basic-category component now has one except this cookie bar, which is deliberately left on the twig front-comment fallback until this is resolved.
We are separately considering whether the right answer on our side is to author a real styleguide.twig fixture for it, which would remove the need for the key entirely for us. That is not an argument against the schema gap — a component that legitimately has no fixture still cannot have a definition today — but it does mean this is not blocking us.
What happens
parisek/styleguide'sComponentParserdecides whether a component is renderable from three signals: astyleguide.twig, any named variant sibling, or an explicitstyleguide: truein the component metadata (ComponentParser.php:220and:289). The third exists for components that render themselves globally and ship no fixture of their own.schemas/component.fields.schema.jsondoes not liststyleguideamong its root properties and setsadditionalProperties: false, so the key cannot be carried in a<name>.yaml.The same parser is YAML-first: once
<name>.yamlexists it becomes the metadata source and the twig front-comment stops being read entirely. So for a component whose only catalogue claim isstyleguide: true, authoring a definition silently drops it out of the catalogue — and with it, any visual or behaviour coverage keyed off the catalogue entry.Nothing errors in either direction, which is what makes it worth reporting.
Reproduction
On a
parisek/styleguideconsumer, take a component that has nostyleguide.twigand carriesstyleguide: truein its twig front-comment (ours is a cookie-consent bar — global chrome, renders itself, no fixture).vendor/bin/fields-migrate path/to/component/<name>— succeeds, reports OK. Thestyleguidekey is dropped, since the schema has no slot for it.styleguide: trueto the YAML —fields-validaterejects it onadditionalProperties.There is no state in which the component has both a definition and its catalogue entry.
Suggested fix
Add
styleguide(boolean) to the schema's root properties. It is metadata the styleguide package already consumes, and it projects into neitheracf.jsonnorblock.json, so it is inert for every generator and lint downstream.The general rule behind the specific fix, which may be worth checking more broadly than this one key: every root key
ComponentParserreads has to be expressible in a definition, or the two metadata formats are not interchangeable — and the YAML-first precedence already treats them as if they were.styleguideis the one we hit; it may not be the only one.Downstream state
We are backfilling YAML sidecars across the whole component set. Every Basic-category component now has one except this cookie bar, which is deliberately left on the twig front-comment fallback until this is resolved.
We are separately considering whether the right answer on our side is to author a real
styleguide.twigfixture for it, which would remove the need for the key entirely for us. That is not an argument against the schema gap — a component that legitimately has no fixture still cannot have a definition today — but it does mean this is not blocking us.