oficina / estilo Public

Resolve Estilo release documentation prerequisites

Co-Authored-By: Codex <noreply@openai.com>

Paul Campbell pushed by paul@keymail.dev 1 month ago 9fbeff92d33fc245ce0da592095829bce931bda1 parent dec3908

5 files changed, +34 −77

AGENTS.md +9 −13
README.md +20 −62
savestatus/doc.go +3 −0
theme/estilo.css +1 −1
theme/theme_test.go +1 −1

CI passed — run details

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

index 2b6e592..dabbd87 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -45,7 +45,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 |

| 6 | **Estilo's theme is `day`, unchanged — not "derived from" or "based on" it. Divergence is allowed but must be driven by a named need, not a preference** — §Theme | Restyling on the strength of "day as a base"; changing a token because it "would look better" | Paul, 2026-08-31 |

@@ -96,17 +96,10 @@ get around it.

## Dependency — RULED, and check it before adding an import

-Estilo needs `ui.ThemeCSS`, `ThemeNames`, `Layout`, `LayoutNames`. Verified

-2026-08-30 at source:

-- **`v0.19.0`: none of them.** `main`: all four. `main` is 19 commits ahead.

-- **`Pair` and the colour-allocation entry point: in no tree.** Specified,

- unwritten. Every consumer keeps a local shim behind the real signature

- until they ship.

-**We wait for the release rather than pinning a pseudo-version.** Three apps

-pin estilo; estilo pinning unreleased code makes a four-deep chain resting

-on a moving target, and the apps inherit it without ever choosing it.

+Rastrillo v0.23.0 supplies the theme and layout APIs Estilo needs. The earlier

+wait for a release is resolved; this module pins that released version.

+Use authenticated Git and `GOPRIVATE=amadan.net/oficina/estilo.git` for the

+private Estilo module. Consumer go.sum files record its integrity.

**The two-pins trap.** Estilo pins rastrillo; the apps pin estilo. That is

the frozen-`tokens.css` problem one layer down — a component library

@@ -123,6 +116,9 @@ two-pin case and it is ours.

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

**estilo ships their styling.**

+**Historical context:** Rastrillo v0.23.0 now ships attribute grammar. The

+following paragraphs record the earlier decision, before that release.

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

@@ -147,7 +143,7 @@ not where it waits.

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

| 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` |

+| An app's own markup, using rastrillo's vocabulary | **The grammar emitted by the pinned release — attributes in v0.23.0** | rastrillo's `tokens.css` |

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

rastrillo changes.

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

index a32ff44..96db7ba 100644

--- a/README.md

+++ b/README.md

@@ -1,69 +1,27 @@

-# 🤖 estilo

+# Estilo

-> **Confirmed 2026-08-31.** Paul's ruling: if Docs, Sheets and other

-> Oficina apps are going to share a design system, estilo makes sense and

-> should be started, with rastrillo's `day` theme as its base.

+Estilo is the CARLOS suite's shared design system, at

+`amadan.net/oficina/estilo.git`. It's a private Go module: pull it with

+authenticated Git and `GOPRIVATE=amadan.net/oficina/estilo.git`.

-> **Ruled, same day.** Paul, verbatim: *"Let's have estilo just be day

-> for now, but we can add oficina specific changes and components to it

-> as we need to."* Estilo's theme **is** `day` — identical, not derived

-> from it or based on it — until a named need says otherwise. See

-> `AGENTS.md`, "Theme."

+The body of `theme/estilo.css` stays byte-identical to Rastrillo's

+released `day` theme, pinned at v0.23.0. A test keeps them aligned.

-The CARLOS suite's design-system variant. Components shared by

-[Sheets](https://amadan.net/oficina/sheets),

-[Docs](https://amadan.net/oficina/docs) and the

-[home](https://amadan.net/oficina/home).

+`savestatus` is a save-status indicator, already adopted by Docs and

+Slides. It renders state (saved, saving, retrying, failed) inside a

+polite status region for screen readers; callers supply the localized

+message text for each state.

-A **variant**, precisely: it depends on

-[rastrillo](https://rastrillo.org)'s `ui`, keeps its bones — the `--rst-*`

-tokens, the partial vocabulary, the measured accessibility floors — and adds

-components, themes and its own gallery on top. Not a fork, and more than a

-theme, because a theme cannot add a component.

+`homeconnect` holds templates and data for Home account-connection and

+OAuth screens, being adopted by the shared home/connect flow and other

+apps. It carries no authentication logic — callers validate the

+destination and supply translated labels. The screens run without

+scripts.

-The design system stays rastrillo's. An inspector panel shared by a document

-editor and a spreadsheet is the *suite's* component, not the framework's.

-(Paul's ruling, 2026-08-30.)

+App shells and permission/session logic stay app-owned. There is no

+shared component gallery yet.

-## There is no code yet, and that is deliberate

+## Building

-Estilo needs `ui.ThemeCSS`, `ThemeNames`, `Layout` and `LayoutNames`. Those

-exist only on rastrillo's `main` — **`v0.19.0` has none of them**, and `main`

-is 19 commits ahead of it. `Pair` and the colour-allocation entry point

-exist in no tree at all; they are specified and unwritten.

-So estilo could pin a `main` pseudo-version — and then three apps pin

-estilo, which pins a pseudo-version, and a four-deep chain rests on

-unreleased code. **We are waiting for the release instead**, which is

-approved and next. Until then this repo carries its decisions and no

-imports, which is honest rather than empty: the decisions are the part that

-is expensive to get wrong later.

-It also means the release now has **three consumers waiting on it**, not

-two.

-## What it is not

-- **Not an agreed interface.** Until two apps have adopted a primitive, this

- is a *home* for it, not a contract. See `AGENTS.md`.

-- **Not a place for app shells.** A spreadsheet's menu bar and formula bar

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

-- **No gallery yet, and `dsgen` will not give us one as it stands.**

- `rastrillo/cmd/dsgen` renders rastrillo's own vocabulary — its

- `internal/designsystem.Render` hardcodes imports of rastrillo's `ui`, so

- it cannot be pointed at another module (verified 2026-08-31; an earlier

- claim here said otherwise and was wrong). Ask rastrillo for the seam

- before considering anything else.

-## Ownership of the first primitives

-| Primitive | First build |

-|---|---|

-| Toolbar groups | Sheets |

-| Inspector panel | Docs |

-| Presence stack | Docs |

-| Comment thread | Docs |

-Docs owns comment threads because its anchoring case is harder — a thread

-anchored to a position inside text that can be edited away, plus suggestion

-mode — and the harder case should own the design.

+`make test` is the gate: `go vet`, a `gofmt` check, `go build`, then

+`go test`. `savestatus`'s own tests run under Node.

diff --git a/savestatus/doc.go b/savestatus/doc.go

new file mode 100644

index 0000000..1b131ec

--- /dev/null

+++ b/savestatus/doc.go

@@ -0,0 +1,3 @@

+// Package savestatus presents localized save feedback shared by Oficina apps.

+// Initial text renders without scripts; live state changes use the supplied JS.

+package savestatus

diff --git a/theme/estilo.css b/theme/estilo.css

index c61eaac..9782398 100644

--- a/theme/estilo.css

+++ b/theme/estilo.css

@@ -1,5 +1,5 @@

/* estilo — the CARLOS suite's shared theme. It IS rastrillo's day

- (v0.22.0), not derived from it and not based on it — identical, in

+ (v0.23.0), not derived from it and not based on it — identical, in

every declaration and every value (Paul's ruling, AGENTS.md,

"Theme"). Structure lives in rastrillo's tokens.css, unchanged; this

file is colour, type and shape, carried across from day token for

diff --git a/theme/theme_test.go b/theme/theme_test.go

index 98aa6fd..bceafd2 100644

--- a/theme/theme_test.go

+++ b/theme/theme_test.go

@@ -130,7 +130,7 @@ func TestMatchesDayByteForByte(t *testing.T) {

sort.Strings(extra)

var b strings.Builder

- b.WriteString("theme/estilo.css has drifted from rastrillo's day.css (v0.22.0, as pinned in go.mod), past the header comment:\n")

+ b.WriteString("theme/estilo.css has drifted from rastrillo's day.css (the version pinned in go.mod), past the header comment:\n")

for _, name := range changed {

fmt.Fprintf(&b, " %s: day has %q, estilo has %q\n", name, dayTokens[name], estiloTokens[name])

}