amadan
Spec: the attribute grammar, and which repo the question is about
Reversed twice in one day, and both reversals were the same mistake in opposite directions: taking a conclusion drawn about one repo and applying it to a different one without re-deriving it. The unstyled-today argument is about markup leaning on rastrillo's stylesheet. Estilo ships its own components and their styling, so attribute-grammar components styled by estilo are not interim -- that is just estilo's styling, permanently, with nothing to migrate later. Paul made the sharper point: estilo is the variant system that exists because of this direction, so building it on the spelling being replaced is backwards. Settled: estilo's components and Docs' own markup use the attribute grammar, styled by estilo. rastrillo's partials emit whatever rastrillo emits, which is classes today and is not our migration.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA
1 file changed,
+33
−12
docs/superpowers/specs/2026-08-30-docs-design.md+33 −12
No CI script — run details
Intent
diff --git a/docs/superpowers/specs/2026-08-30-docs-design.md b/docs/superpowers/specs/2026-08-30-docs-design.md| index 35ae1e5..49521f0 100644 |
| --- a/docs/superpowers/specs/2026-08-30-docs-design.md |
| +++ b/docs/superpowers/specs/2026-08-30-docs-design.md |
| @@ -565,18 +565,39 @@ branch --merged` reports nothing useful about whether work has landed — |
| compare content, not ancestry. And a local checkout may sit on a feature |
| branch at a tag; cite `origin/main` explicitly or you will report the past.)* |
| -### 10.1.1 Markup uses the class vocabulary — reversed |
| - |
| -Revision 2 said to write the bare-attribute grammar and carry interim |
| -styling until it shipped. **Reversed**, because the thing being waited for is |
| -unstarted rather than in flight and carries no date. |
| - |
| -Docs writes `class="rst-*"`. That is what `ui` styles today and what ~585 |
| -call sites in rastrillo use. When the attribute grammar ships, Docs migrates |
| -mechanically alongside the framework's own call sites — the same change, |
| -done once, by whoever automates it. The alternative was a parallel styling |
| -implementation maintained for an unbounded period against a target nobody |
| -has started. |
| +### 10.1.1 Markup — the attribute grammar, and which repo the question is about |
| + |
| +This reversed twice in one day, which is worth recording because both |
| +reversals were the same mistake in opposite directions: applying a |
| +conclusion drawn about one repo to a different one without re-deriving it. |
| + |
| +**Revision 2** said write the attribute grammar and carry interim styling. |
| +**Then reversed** to `class="rst-*"`, on the grounds that the grammar exists |
| +in no rastrillo tree (verified: spec-only at `origin/main` `7a30456`, no |
| +branch working on it) so an app writing it renders unstyled. **Then reversed |
| +back**, once `oficina/estilo` existed, because that argument is about an app |
| +consuming rastrillo's CSS and estilo does not do that. |
| + |
| +**The settled split:** |
| + |
| +| Markup | Spelling | Styled by | |
| +|---|---|---| |
| +| Estilo's own components | Attribute grammar | Estilo | |
| +| Docs' own markup | Attribute grammar | Estilo | |
| +| rastrillo partials we consume | Whatever rastrillo emits — classes today | rastrillo | |
| + |
| +Estilo ships its own components *and their styling*, so attribute-grammar |
| +components styled by estilo are not interim anything — that is just estilo's |
| +styling, permanently, with nothing to migrate later. The unstyled-today |
| +problem only ever applied to markup leaning on rastrillo's stylesheet. |
| + |
| +And estilo is the variant system that exists *because* of this direction, so |
| +building it on the spelling being replaced is backwards. Estilo is where the |
| +new grammar gets proven rather than where it waits. |
| + |
| +Docs consumes rastrillo partials for chrome, and those emit classes. That is |
| +rastrillo's output, not a choice this spec makes, and it changes when |
| +rastrillo changes. |
| `tokens.css` is frozen into `static/` at scaffold time while partials upgrade |
| with the module, so re-copy it deliberately on every rastrillo upgrade until |