DESIGN.md git:20261026.88ad0b2A

Immutable. This exact content never changes and is served at /api/v1/blob/eeebef8eaa58e3d8.

# DESIGN.md

The look of the website (`site/`, `just site`), in rules. It follows the manner of the author's
sister sites, h0ffmann/closed-source and h0ffmann/ww3-gpu, with its own palette.

## One sentence

Uma folha, a caneta de quem escreve e a caneta da revisão.

## The two pens

Each pen means one thing, everywhere on the page. Words always back up the colour: a reader who
does not see colour loses nothing.

| Pen | Hex | It means |
|---|---|---|
| `--pen` | `#1D3FD0` | the writer: the title, the links, the main button |
| `--review` | `#C8102E` | the correction: a rule's id (`PTW-1`), a level of rigor |

No third pen. A new colour is a new meaning, and it starts here.

## The ground

Light only, like paper: `--paper #FBF8F1` behind everything, `--sheet #FFFFFF` under code,
`--rule #E4DDCD` for the lines between sections, `--ink #1B1A17` for the text and
`--muted #6B665C` for what is secondary.

## Type

- Fraunces (800 and 600) for the title and the headings.
- Source Serif 4 for the prose.
- JetBrains Mono for data: rule ids, levels, commands, the navigation.

The fonts load from Google Fonts, as on the sister sites. No font file is stored here.

## Shape and words

- **Portuguese, lower case** for what the page says in its own voice: headings, buttons, intros.
  A fact read from a file keeps its own case (a rule's title, a recipe's comment).
- **Round.** Buttons, level chips and roadmap statuses are pills. A section is set apart by a
  line, not a box.
- **Status by shape, then colour.** A roadmap row says its status in words first. `feito` is a
  filled `--pen` pill, `em andamento` an outlined one, `planejado` a **dashed** `--muted` one:
  dashed means "not there yet".
- **Star me.** The second button is the GitHub pill, "★ star me no github", with the star count
  drawn by shields.io as an image. It is the only image from another host.

## Facts

Every fact on the page comes from a file of this repository, through `site/content`: the lede,
the usage, the levels, the rules and the output format from `SKILL.md`, the recipes from the
`justfile` (each recipe with a comment block above it, its first line), and the limits and the
origin of the rules from `## Limites` and `## Origem` when `SKILL.md` has them. Four tables hold
what no other file holds: `site/data/awesome.tsv`, the related repositories: first the original PTC,
the source of this fork, then each one with the URL of the curated list it was found in; `site/data/origins.tsv`, where each rule comes from (the rule of the source repository, the
repository and its creator as a GitHub login, never a full name, linked; a rule may have more than one row, and every rule needs one);
`site/data/planned.tsv`, the levels that are planned and not yet in `SKILL.md`, shown with a
dashed PLANEJADO pill next to the IMPLEMENTADO ones; `site/data/roadmap.tsv`, production readiness, each row with a
status of `feito`, `em andamento` or `planejado` and the file that proves it. Never type a rule, a
level, a recipe, a repository or a status into `site/src`. A `SKILL.md` that loses one of its
sections, or a table row that is malformed, stops the build.

## Credit

The fork notice is the last line of the page, small, in the footer: it credits the Português
Técnico Controlado without leading the page.

## Logos and pictures

No logo is stored. The favicon, also the README's picture, is an original one-line drawing of a
writing quill. Two public-domain images from Wikimedia Commons are stored in `site/static/img/` and
credited in the footer: the flag of Brazil (`Flag_of_Brazil.svg`) and Machado de Assis's signature
(`Assinatura_de_Machado_de_Assis.png`, the 960 px rendering). Machado is credited by name, as
`REUSE.md` asks.

## Made with

"feito com" sits on the cover, under the buttons, and again in the footer. It names the languages
of the repository (Gleam first, then Rust, the browser extension's), then
"com" the agents and the local model servers: Claude Code, OpenCode, OpenCodeReview, Ollama and
Ollaya. Each name is a pill with its owner's icon; a language's owner is the body that keeps it (TC39
for JavaScript, WHATWG for HTML), or its official logo's repository at a pinned commit (the GNU Bash
logo, the community CSS logo). The icon is loaded from where it is published and never stored here (the pattern is h0ffmann/closed-source's). The footer says the names and icons are
their owners' marks, not licensed here.

## Layout

- The cover: a mono kicker, the quill beside the title, and the `--review` pen's stroke under it.
- A notebook page behind the whole page: blue rules every 32 px (`--rule-ink`) and the red margin
  line (`--margin-ink`) left of the text. Visible, but under the text.
- pt-BR first: the cover's kicker opens with the flag of Brazil and a green "pt-BR first" pill.
- Calligraphy: Machado de Assis's signature, in ink, beside the title (on its own line below
  1000 px).
- Each section heading carries `§ 01`, `§ 02`…, counted by CSS: the numbers are never typed.
- A rule is a small card on `--sheet` with a `--review` edge: text at 0.92 rem, the origin line smaller still, and three columns when the page is wide enough (two, then one, as it narrows).
- A roadmap item is a card; a planned one is dashed.

## Motion

One entrance, and only when the reader allows motion (`prefers-reduced-motion`): the title
settles, the review stroke draws, the lede and the buttons rise. The page is prerendered. Its one
script (`page.gleam`) shows the copy button of the install command and puts the command on the
clipboard; without JavaScript the button stays hidden and the command is still there to select.

## Install

The install command comes first, under the lede: a dark box with the one command (read from
`plugin.json` by `site/content`, never typed) and a copy button in `--pen`.

## Before you change the look

1. Change this file in the same pull request.
2. `just site-serve`, then look at the page at 1280 px and at 390 px.
3. Tab through the page: every link shows its focus ring.