oficina / docs Public

Spec: v0.21.0 facts, estilo's prefix rule, and the markup decision unparked

Documentation only. rastrillo v0.21.0 styles both spellings (343
bare-attribute selectors alongside 398 class ones), so the spec's claim
that the attribute grammar existed in no tree was wrong, and doctor
landed, retiring the manual tokens.css re-copy step.

estilo is at oficina/estilo, and anything Docs contributes takes an
estilo-* prefix -- rst- is the framework's namespace and its own
migration found rst-form__foot and rst-form-foot both live inside ui.

Markup unparked by Paul once both his conditions were met and verified
here: Docs writes the attribute grammar, per screen not per element,
pinned to v0.21.0 or later.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA

Paul Campbell pushed by paul@keymail.dev 1 month ago d42c91bd0bf49588e549b0149b25423065e12809 parent 65a2396

2 files changed, +46 −14

AGENTS.md +17 −8
docs/superpowers/specs/2026-08-30-docs-design.md +29 −6

CI passed — run details

Intent

Attributed to this commit: 171 g CO₂e (14941219 tokens). This is an attribution, not a measurement — usage counted from this commit's own marker forward to the next one on main, never backward from it. A turn that produced more than one commit books all of its tokens to the last one, and a concurrent session on this branch can add to the same figure. Some of it was priced using the shared default rate, because no model-specific factor row exists yet for at least one model involved. The Carbon view has the repo total, which is never derived from this attribution.

full ledger: main

diff --git a/AGENTS.md b/AGENTS.md

index 3c0c68a..489956e 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -169,14 +169,23 @@ one session's question exposing another's bug.

## Conventions that are already settled

-- **Markup uses the `class="rst-*"` vocabulary.** Reversed 2026-08-30 after

- checking source. The bare-attribute grammar (`<div rst-inspector>`) is a

- ruled future direction that exists in **no tree** — not in the release, not

- on `main`, not on any branch — and it has no date. The class vocabulary is

- what ships, what `ui` styles, and what ~585 call sites in rastrillo use.

- Writing attributes now would mean maintaining a parallel styling

- implementation indefinitely; writing classes means one mechanical migration

- alongside the framework's own.

+- **Markup uses the bare `rst-*` attribute grammar** (`<div rst-inspector>`),

+ variants in the value matched with `~=`. Unparked by Paul 2026-08-31, once

+ both of his conditions were met and verified: `rastrillo v0.21.0` styles

+ **both** spellings (`ui/tokens.css` carries 343 bare-attribute selectors

+ alongside 398 class ones), and the design-system guidance exists.

+ Two constraints come with it. **Adopt per screen, not per element** —

+ mixed authoring inside one component matches neither spelling by design.

+ And **pin `v0.21.0` or later**, because on anything earlier attributes

+ render unstyled.

+ *(This reversed twice before landing here, both times by applying a

+ conclusion drawn about one repo to a different one without re-deriving it.

+ The reasoning is in spec §10.1.1.)*

+- **Anything Docs contributes to estilo takes an `estilo-*` prefix, never

+ `rst-*`.** That namespace is the framework's and a future version may claim

+ a name we took — rastrillo's own migration found `rst-form__foot` and

+ `rst-form-foot` both live inside `ui`.

- **A spec ruling, code on `main`, and code in the latest release are three

different things.** Reading one tells you nothing about the other two.

`v0.19.0` (2026-08-24) is 18 commits behind rastrillo's `main` and lacks

diff --git a/docs/superpowers/specs/2026-08-30-docs-design.md b/docs/superpowers/specs/2026-08-30-docs-design.md

index fd2d0aa..34e3652 100644

--- a/docs/superpowers/specs/2026-08-30-docs-design.md

+++ b/docs/superpowers/specs/2026-08-30-docs-design.md

@@ -591,7 +591,7 @@ Verified against `origin/main` and `v0.19.0`:

| `ui.TokensCSS()` | Released |

| `ui.ThemeCSS(name)`, `ThemeNames()`, `Layout(name)`, `LayoutNames()` | **Released in `v0.20.0`** (2026-08-30) — were `main`-only for six days |

| `Pair`, the allocation entry point | **Ruled only.** In no tree |

-| The bare-attribute grammar (`<div rst-inspector>`) | **Ruled only.** In no tree, no branch, unstarted |

+| The bare-attribute grammar (`<div rst-inspector>`) | **Released in `v0.21.0`** (2026-08-31). Verified: `ui/tokens.css` carries 343 bare-attribute selectors alongside 398 class selectors, so both spellings are styled |

**Resolved 2026-08-30: `v0.20.0` is tagged and level with `main`** (verified:

carries `ThemeCSS`, `ThemeNames` and `LayoutNames`; zero commits behind

@@ -633,11 +633,15 @@ consuming rastrillo's CSS and estilo does not do that.

|---|---|---|---|

-**The middle row is parked, deliberately** (Paul, 2026-08-30): design-system

-questions wait until rastrillo's design system settles and estilo is real.

+**Unparked by Paul, 2026-08-31**, once both of his conditions were met and

+independently verified: `<div rst-*>` is shipped (`v0.21.0` styles both

+spellings) and the design-system guidance exists. Docs writes the attribute

+grammar, adopting **per screen rather than per element** — mixed authoring

+inside one component matches neither spelling by design — and pinning

+`v0.21.0` or later, below which attributes render unstyled.

Docs writes no markup yet — plans 1 and 2 are a Rust crate and a wazero host

— so nothing is blocked, and answering it now would mean converging on a

decision that is about to be made upstream.

@@ -661,8 +665,10 @@ 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

-`rastrillo doctor` lands.

+with the module. **`rastrillo doctor` landed in `v0.21.0`**, so the manual

+re-copy step is retired: `doctor` compares an app's frozen `static/` against

+the module's and `--fix` re-copies, and it refuses across a version mismatch

+rather than manufacturing the fault it detects.

### 10.2 Colour

@@ -704,6 +710,23 @@ Paul, 2026-08-30, correcting earlier advice this spec had taken. An

inspector panel shared by a document editor and a spreadsheet is the

*suite's* component; the design system stays rastrillo's.

+The variant is **estilo**, at `amadan.net/oficina/estilo` — named by Paul and

+created 2026-08-30. Primitives stay app-local until one app copies or imports

+another's; **a copy is the trigger**, because "a second consumer appears"

+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.

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

**extraction**, and Sheets and Docs applied it correctly. But it says