oficina / estilo Public

Reverse ruling 4: estilo writes the attribute grammar

Paul challenged the rule I committed an hour ago and he is right.

I had written "use class=rst-*, because the attribute grammar exists in
no tree and renders unstyled". That reasoning is sound for an app leaning
on rastrillo's CSS and false for estilo, which ships its own components
AND their styling — so styling its own attribute-grammar components is
not interim anything, it is permanently estilo's styling. Nothing to
migrate, no parallel implementation to carry.

The stronger reason is positive rather than defensive: estilo is the
variant system that exists because of this direction, so birthing it on
the spelling being replaced is backwards. Estilo is where the new grammar
gets proven, not where it waits.

The error class is the one recorded in the same file two commits ago —
taking a conclusion that was correct for one repo and applying it to a
different one without re-deriving it, exactly as both consuming sessions
did with extraction-versus-destination. Recorded with its provenance
rather than silently corrected, because the outcome alone reads like a
mistake and the next reader needs to know which repo each rule is about.

Adds the three-way split that holds across the suite: estilo's components
and an app's markup using them are attribute grammar styled by estilo; an
app's markup using rastrillo's vocabulary stays whatever rastrillo emits,
which is classes today and is neither our choice nor our migration.

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

Paul Campbell pushed by paul@keymail.dev 1 month ago 596a2ced1453a5b5473213d67b841c85063c829c parent b3da1d6

2 files changed, +41 −12

AGENTS.md +37 −12
README.md +4 −0

Intent

full ledger: design

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

index 1e284bb..1e18c2b 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -36,7 +36,7 @@ empty repo invites the opposite.)

+| 4 | **Estilo's own components are written in the bare-attribute grammar, and estilo defines their styling** — §Vocabulary | `class="rst-*"` (right for an app consuming rastrillo's CSS, wrong for a library shipping its own) | Paul, 2026-08-30 |

**Two callers at design time is the bar for *extraction*. It says nothing

@@ -70,24 +70,49 @@ two-pin case and it is ours.

---

-## Vocabulary — `class`, not attributes

+## Vocabulary — attributes here, and why that differs from the apps

-**Write `class="rst-*"`.** The bare-attribute grammar (`rst-btn="primary"`)

-exists in **no tree** — not `v0.19.0`, not `main`, not the design-system

-branches — and rastrillo's §6-v3 migration is ruled but unstarted with no

-date. A component written in the attribute grammar renders **unstyled**

-today.

+**Estilo's own components use the bare-attribute grammar**

+(`<div rst-inspector>`, variants in the value matched with `~=`), and

+**estilo ships their styling.**

-This rule is here with its reason because the surrounding conversation all

-week said the opposite, and somebody will helpfully correct it back.

+**Read this before "correcting" it, because the surrounding conversation has

+said both things this week and the right answer depends on which repo you

+are in.**

-Migration is mechanical and happens alongside rastrillo's own ~585 call

-sites, via the staged dual-matching release. Not before.

+The argument for writing classes is: the attribute grammar exists in no

+rastrillo tree — verified again at `origin/main` `7a30456`, spec-only, no

+branch working on it — so a component written in it renders unstyled. **That

+is true for an app leaning on rastrillo's CSS, and false here.** Estilo

+ships its own components *and* their styling, so styling its own

+attribute-grammar components is not interim anything; it is permanently

+estilo's styling. There is nothing to migrate later and no parallel

+implementation to carry.

+And the positive reason, which is the stronger one: **estilo is the variant

+system that exists because of this direction.** Birthing it on the spelling

+being replaced is backwards. Estilo is where the new grammar gets proven,

+not where it waits.

+**The three-way split, which holds across the suite:**

+| Markup | Spelling | Styled by |

+|---|---|---|

+| Estilo's own components | Attribute grammar | Estilo |

+| An app's own markup, using estilo components | Attribute grammar | Estilo |

+| An app's own markup, using rastrillo's vocabulary | **Whatever rastrillo emits — classes today** | rastrillo's `tokens.css` |

+The third row is not our choice and not our migration. It changes when

+rastrillo changes.

Do not build on `.rst-page-header::after` — the accent rake line is retired

in favour of `--rst-header-rule`.

----

+**Provenance, because this reversed within an hour.** docs-e6 first advised

+classes, reasoning correctly about its own app and then applying the

+conclusion to a different repo without re-deriving it. Paul challenged it;

+the correction is his. Recorded with the reasoning rather than the outcome,

+because the outcome alone reads like an error.

## Standards every primitive meets

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

index 83d84d3..db15aaa 100644

--- a/README.md

+++ b/README.md

@@ -40,6 +40,10 @@ two.

are Sheets'. What lives here is what two apps genuinely share.

- **Not a second gallery generator.** `rastrillo/cmd/dsgen` is public and

generates a gallery for any module's own vocabulary. Use it.

+- **Not written in the class vocabulary.** Estilo's components use the

+ bare-attribute grammar and estilo ships their styling — see `AGENTS.md`.

+ The "write classes" rule is for apps leaning on rastrillo's CSS, and does

+ not apply to a library shipping its own.

## Ownership of the first primitives