# 🤖 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.

> **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."* This settles what "as its base" above meant: estilo's
> theme **is** `day`, not derived from it or based on it — identical.
> See "Theme" below.
>
> **Superseded 2026-09-29.** Paul chose Calma: estilo's theme is now the
> suite's own, not `day` (decisions table, row 8; "Theme" below). The two
> rulings above are kept as the history of how estilo started.

The CARLOS suite's design-system variant. See `README.md` for what it is.

This file is binding. Where it disagrees with a general skill, this file
wins.

---

## The one rule

> **Two specs are guesses. Two implementations are facts.**

So: **one app builds a primitive here, and the other adopts it.** Not two
implementations merged afterwards, and not an interface designed from two
specs at once.

A document editor's inspector shows text and style properties. A
spreadsheet's shows cell format and data validation. A shape designed from
both specs at once risks fitting neither — **the second use is what corrects
it**, and it can only do that if there is something concrete to correct.

**Until a second adoption, estilo is a home, not an agreed interface.**
Treating it as an interface earlier buys exactly the ill-fitting abstraction
that building it here was meant to avoid.

(From ui-guidelines-52 via docs-e6, 2026-08-30. Written down because an
empty repo invites the opposite.)

---

## Settled decisions

| # | Ruling | Rejected | Who, when |
|---|---|---|---|
| 1 | **Shared suite components live here, not in rastrillo's `ui`** | Proposing them to the framework | Paul, 2026-08-30 |
| 2 | **A separate repo, created before any primitive is written** | App-local until a second consumer; a nested module inside an app | Paul, 2026-08-30 |
| 3 | **Resolved: use released Rastrillo v0.23.0** — §Dependency | Pinning a `main` pseudo-version | This session, 2026-08-30 |
| 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 |
| 5 | **The colour engine stays in rastrillo's `ui`** | Moving `Pair` and allocation here | ui-guidelines-52, 2026-08-30 |
| 6 | *(Superseded by 8.)* **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 |
| 7 | **Private module path is `amadan.net/oficina/estilo.git`**, using authenticated Git and `GOPRIVATE` on every builder; checked consumer `go.sum` records integrity. Preserve this path when discovery support changes. | Public visibility solely to obtain Go metadata; local filesystem replaces; a later cosmetic module rename | Overnight coordinator, 2026-09-07; Claude Fable 5.1 branch review |
| 8 | **Estilo's theme is Calma, the suite's own — no longer `day`.** Every app's colour sits on one ring of equal OKLCH lightness (`theme/apps.go`); each app is themed with its own accent (`theme.ForApp`). The marks are Calma's (Fanned Oficina mark, app icons with a glow of their own hue) and the suite's ambient effect is a seeded nebula (`sky`), placed at the sign-in, the team's home and the front page, **never inside an app** — §Theme | Keeping `day` "as a base"; one hue per app chosen by eye (Mail and Files would not fit); rim light, cores and motes in the sky | Paul, 2026-09-28/29, after six rounds of design directions: *"Calma is by far the best"*; *"Grain and filaments. No cores, no rim lights. Then go."* |

**Two callers at design time is the bar for *extraction*. It says nothing
about *destination*.** Both consuming apps were told to propose their
primitives to the framework, applied the right bar, and got the wrong
answer, because the first question looked like it settled the second. Keep
the two apart.

---

## Theme — RULED: Calma

> **Paul, 2026-08-31, 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."*
>
> **Paul, 2026-09-28/29**, choosing among six rounds of design directions
> (`~/amadan.net/oficina/design-directions/`, published for review at a
> temporary site): Calma, *"by far the best"*, with the aurora that became
> a nebula; then *"Grain and filaments. No cores, no rim lights. Then go."*

`day` was the position estilo held until the suite chose its own look.
It has now: **estilo's theme is Calma.** The "named need" row 6 asked for
is Paul's decision to give the suite an identity, recorded as row 8.

What Calma is, and where each part lives:

- **`theme/estilo.css`** — the suite's tokens: a cool off-white page,
  white cards, one grey text scale, 12px shapes, a long low shadow, and
  Oficina's own accent. Status tones are `day`'s, unchanged.
- **`theme/apps.go`** — the ring. Every app has a hue; all share one
  OKLCH lightness and chroma, so no app is louder than another. The hues
  are spaced to the eye (34-50°, widest across the muddy yellow-greens),
  with room for Mail and Files. `theme.ForApp(slug)` is an app's whole
  theme: estilo.css, then its accent. The ring is a closed set.
- **`theme/fonts.go`** — Onest, Calma's typeface, served by
  `theme.FontHandler`; the theme falls back to the system face without it.
- **`brand/`** — the marks, generated from `icons.json` (hues must equal
  the ring; `brand_test` checks) in web, iPhone and Mac shapes.
- **`sky/`** — the ambient nebula: seeded per team; its colour (haze and
  clouds) an inline placeholder painted in the first frame, its grain and
  filaments two static files,
  no script, still for anyone who asks for less motion. **It goes where
  the suite meets you — the sign-in, the team's home, the front page —
  and never inside an app.** Inside an app, only the icons carry colour.

**The gates that replaced `TestMatchesDayByteForByte`**
(`theme/theme_test.go`), and why each exists:

- `TestDeclaresDaysTokenSet` — exactly `day`'s token *names*, so
  rastrillo's `tokens.css` never meets an undefined `var(--rst-*)`, and
  a rastrillo upgrade that adds or drops a token still fails here.
- `TestContrastMeetsWCAG` — every pair rastrillo's own gate checks, in
  both schemes, for estilo.css **and every app's accent**, through
  rastrillo's `ui.ContrastRatio` (parsing copied verbatim).
- `TestAccentGoldens` — each app's accent block against `testdata/`, so
  no colour moves without a diff that says so.

**Changing a value is still a design decision for Paul**, not a
session's. Change the ring or a token, regenerate the goldens
deliberately (`go test ./theme -run Goldens -update`), read the diff, and
record the reason here. "It would look better" is still not a reason on
its own; Paul saying so is.

---

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

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
carrying stale tokens while its consumers upgrade underneath it. **A
tokens-drift check ships in the first commit that has code**, not after it
bites. `rastrillo doctor` mechanises the single-pin case; this is the
two-pin case and it is ours.

---

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

**Estilo's own components use the bare-attribute grammar**
(`<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.**

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

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

Inherited from rastrillo's gates, and not negotiable downward:

- **Twelve locales.** A primitive that only reads in English is unfinished.
- **The script-required line stated per primitive.** Say plainly what works
  with scripts off and what does not. "Acceptable for a grid, unacceptable
  for a form" is the test.
- **24×24 minimum target size**, measured on the smaller axis. Do not lean
  on 2.5.8's spacing exception — a real hit area is honest, and the
  exception is an argument you have to keep making.
- **320px reflow.** Content requiring two-dimensional layout may scroll in
  both axes; everything else reflows or it is a bug, not an exemption.
- **Colour never carries meaning alone.** Whatever a colour *means* must
  survive greyscale.
- **Contrast arithmetic copied verbatim** from `ui/contrast_test.go`, never
  reimplemented — two gates disagreeing by a rounding decision is a gate
  that certifies the wrong thing while passing.

---

## The gallery

**`rastrillo/cmd/dsgen` does NOT generate a gallery for an arbitrary
module — verified 2026-08-31.** Its public surface is `-out`/`-mount`, and
`internal/designsystem.Render` hardcodes imports of
`github.com/carlosframework/rastrillo/ui`. It renders *rastrillo's own*
vocabulary. Pointed at estilo it would reproduce rastrillo.org's gallery.

An earlier version of this file claimed the opposite, on good authority
that turned out to be wrong. Recorded rather than quietly deleted, because
the next person will hear the same claim.

So estilo's gallery is an open question, not a solved one. **Do not build a
second generator on the strength of that** — the right move is probably to
ask rastrillo for the seam rather than to fork the tool.

---

## Process

Worktree per session, branch per piece of work, regular pushes,
squash-merge to `main` only when the work is done, approved, and **CI is
actually green** — checked, not assumed.

**Every spec and every branch is reviewed by the highest-capability model
available** before approval or merge, and **the reviewing model is
recorded** in the branch discussion. A review nobody can attribute is a
review nobody can check.

**Every branch gets a discussion, and that discussion is the review
record** — it survives a squash where a PR body does not. **A refusal gets
surfaced in the discussion, never routed around.**

🤖 / 👨 markers, `Co-Authored-By` trailers, published prompt ledgers.

## Known constraints

Measured facts about Calma's values that bear on the next change.

- **The tightest text pair is faint text on an accent-tinted surface**:
  4.63:1 for Files in dark, against a 4.5:1 floor. Darkening an accent's
  soft tint or lightening `--rst-text-faint` in dark goes under first.
- **The tightest boundary is a control border on the sunk surface**:
  `--rst-line-strong` on `--rst-surface-2` in light, just over 3:1.
- **At the accent's lightness some hues cannot hold full chroma in
  sRGB.** `theme.Hex` takes chroma down until the colour fits, so hue and
  lightness stay true (Files' light accent carries about 0.09, not 0.15).
  An app that looks greyer than its neighbours is this, not a bug.
- **A strict 40° ring always puts one app in olive or lime** at this
  lightness; that is why the hues are spaced by eye.

`TestContrastMeetsWCAG` measures all of these on every run; the numbers
here are for the conversation before a change, not instead of the test.

## Work in a worktree, and catch main up first

Take a worktree for the work. Do not work in the shared checkout.

    git -C <repo> fetch origin
    git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main

Both halves matter, for different reasons.

**The worktree**, because several sessions share this machine and some
share this repository, and a checkout has one HEAD, one index and one
working tree between all of them. A branch switch under somebody else's
uncommitted work destroys it with nothing on screen to say so, and two
sessions editing the same paths disagree quietly instead of conflicting
loudly. A worktree gives the work its own HEAD and its own files, and
costs a directory.

**From `origin/main`, after a fetch** — not from whatever the checkout
happens to be sitting on. A branch cut from a stale main is a merge
conflict scheduled for later, against files somebody else has renamed in
the meantime. A branch cut from another task's branch is worse: it
carries that task's commits into yours, where they are reviewed as
though you wrote them, and the two can only be separated by hand.

Remove it when the work has landed — `git worktree remove` — so that
`git worktree list` keeps saying something true.

Written down because of 2026-09-17, in `meet`. The shared checkout was
sitting on one task's branch while holding a *different* task's feature
uncommitted on disk — some four hundred lines, a new migration among
them — put there by a session nobody else knew was working in that tree.
Two other sessions were meanwhile coordinating over the same checkout by
asking each other not to touch it, which is the arrangement a worktree
makes unnecessary. Nothing was lost. Nothing about the arrangement would
have said so if it had been, and by then the same feature existed twice,
once on each side of a rename, because the two sessions had branched
from different starting points.