amadan
Spec: the guidance has a permanent URL, and v0.22.0 flips the framework
Documentation only. The design-system guidance is published at rastrillo.org/docs/design-system, and v0.22.0 flips the framework itself to the attribute grammar -- verified, class= in ui/ui.go fell 56 to 5 -- so Docs and rastrillo now write the same spelling. The one breaking rename does not reach us, checked rather than assumed. The upgrade is therefore optional and left as Paul's call rather than taken as an unattended dependency bump.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA
1 file changed,
+24
−8
docs/superpowers/specs/2026-08-30-docs-design.md+24 −8
landed from spec-v022-guidance
diff --git a/docs/superpowers/specs/2026-08-30-docs-design.md b/docs/superpowers/specs/2026-08-30-docs-design.md| index 34e3652..43be865 100644 |
| --- a/docs/superpowers/specs/2026-08-30-docs-design.md |
| +++ b/docs/superpowers/specs/2026-08-30-docs-design.md |
| @@ -718,14 +718,30 @@ never fires while copying is cheap and immediate. |
| **Estilo's components take an `estilo-*` prefix, never `rst-*`.** That |
| namespace belongs to the framework and a future version may claim a name we |
| took — which is not hypothetical: rastrillo's own stage-1 migration found |
| -`rst-form__foot` and `rst-form-foot` both live inside `ui`. The guidance is |
| -at `docs/site/design-system.md` in the rastrillo repo, published at |
| -rastrillo.org/docs/design-system once stage 2 lands; it covers the |
| -customisation ladder, where app-specific components belong, the extraction |
| -rule, and upgrading via `doctor`. Two caveats on it: it has not been through |
| -the copy gate, so its prose may change; and its line about the class spelling |
| -being dropped before 1.0 describes stage 3, which is ruled and unstarted — |
| -intent rather than a shipped fact. |
| +`rst-form__foot` and `rst-form-foot` both live inside `ui`. The guidance is published at **https://rastrillo.org/docs/design-system** |
| +(2026-08-31); it covers the customisation ladder, where app-specific |
| +components belong, the extraction rule, and upgrading via `doctor`. Its |
| +earlier claim that the class spelling would be dropped before 1.0 has been |
| +corrected to what is true today: attributes are what the framework writes, |
| +and classes are kept so apps can migrate. |
| + |
| +**`v0.22.0` (2026-08-31): the framework itself now writes the attribute |
| +grammar.** Verified — `class=` occurrences in `ui/ui.go` fell from 56 to 5, |
| +the remainder being the utilities that keep the class spelling by design. So |
| +Docs and rastrillo now write the same spelling. |
| + |
| +**`rastrillo markup` exists**, the codemod that performed that flip. Docs does |
| +not need it — we were written in the attribute grammar from the first line — |
| +but the order matters if it is ever used: `doctor --fix` first, because the |
| +CSS must match both spellings before the markup moves. It also lists every |
| +`.rst-` selector in an app's own stylesheet, which is the case nothing else |
| +catches: markup flips, stylesheet does not. |
| + |
| +**One breaking rename in `v0.22.0` does not reach us**, checked rather than |
| +assumed: the hand-written sticky save-bar idiom became `rst-form-bar`, with |
| +`rst-form-foot` now belonging to the partial that emits it. Docs uses |
| +neither. The upgrade from `v0.21.0` is therefore optional and low-risk, and |
| +is Paul's call rather than an overnight dependency bump. |
| The correction is worth keeping because the reasoning was subtly wrong |
| rather than simply wrong. Two callers at design time is the right bar for |