From 07a7efa7935604026596e0518c2d12cb06f196c4 Mon Sep 17 00:00:00 2001 From: Lukas Wallrich Date: Thu, 12 Nov 2026 23:36:24 +0000 Subject: [PATCH 1/5] Add a design guide for forrt.org pages Records the principles settled in the Doors design rounds, building on the Doors acceptance checklist, and points to it from AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 1 + DESIGN.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 DESIGN.md diff --git a/AGENTS.md b/AGENTS.md index 4cab3039b5e..9fb6c2d0eb1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,7 @@ Announcement posts (`content/post//`) come from the "FORRT Announcements" - Templates: edit `layouts/`, which overrides `themes/academic/layouts/`. Change `themes/academic/` only when no override exists and an override would not do. - Styles: the site compiles `assets/scss/` (`main.scss`, `custom.scss`, `academic/*.scss`), whose files override the theme's same-named SCSS. +- Design principles for pages and components are in `DESIGN.md`; follow them when changing layouts or styles. - Configuration lives in `config/_default/`; the root `config.toml` exists only for blogdown compatibility. ## Build and preview diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 00000000000..5887e86d286 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,91 @@ +# Designing pages for forrt.org + +How pages on forrt.org should look and behave, for anyone changing a template, a style or the layout of a page. The site uses the Doors design. Its starting point is the [Doors acceptance checklist](https://github.com/forrtproject/forrt-design/blob/main/doors-mock/checklist.md), which records the community's requirements; IDs such as A9 below refer to it. The principles here come from applying that design across the site's templates, and they override the checklist where they differ. + +Styles live in `assets/css/doors/`, with colours and type defined once in `tokens.css`. Shared page parts are in `layouts/partials/doors/` and `layouts/shortcodes/`. + +## 1. Lead with what visitors came for + +- The page's main tool, list or action appears in the first screen at 390 px and at 1440 px. Background, history and acknowledgements come after it. +- Move information down, or put it behind a disclosure with a plain label ("About the glossary project, and how to cite it"). Do not delete it to make the page shorter. +- "How to cite" is a visible section of its own wherever a page asks to be cited. +- Keep images that explain something, such as the Replication Hub diagram, even when the page would look more uniform without them. + +## 2. One clear next step + +- Each screen has one main action. Other actions are quieter: smaller, outlined or plain links. +- Action labels say what the visitor will do ("Teach with open materials", "Explore replications"), not what FORRT has. +- Prefer routes into FORRT's own pages. A link that leaves forrt.org says where it goes. +- Every kind of submission starts at `/submit/`, which sends people on to the right form. Do not call submitting "contributing": contributors join the work and are listed as such. + +## 3. Calm, specific pages + +Every repeated device has to earn its place. In practice: + +- Pills and chips are for controls: filters, toggles, language switches. A list of links, such as related glossary terms, is a plain list. +- Search and filters belong on long lists (the glossary, the resources directory, Reversals). A list of fewer than about twenty items needs neither. +- Tags: a tag links to the tags page only when at least five pages and at most a quarter of all pages share it (`layouts/partials/functions/tag_counts.html`). Rarer tags are plain keywords; tags on more pages are not shown, because they no longer tell pages apart. +- In long lists of long entries, show the first two lines of each description (three on a phone) with a "more" button. Without JavaScript the full text shows. +- Avoid the generic template look (A9): no tracked capitals as labels above headings, no hairline-ruled columns as the main organising device, no grids of identical cards. Short schedule labels, such as MORNING and AFTERNOON in a programme, are the exception: tracked capitals help there. +- Cards for actions are the brick cards of `action_cards`. A set of bricks uses several area colours, never three near-identical ones. Lists of tools are rows: a linked title and a sentence, not boxes. + +## 4. Links look like links + +- A link is visible as a link without hovering, normally by an underline. A row that is clickable as a whole still shows its title as a link. +- Things that are not links never look like buttons or chips. An unlinked related term is plain text. +- Buttons in a row have a gap between them, on every screen size. + +## 5. Colour carries meaning + +- Each of the four areas has its colour: education `--edu` (green), research `--res` (blue), social justice `--jus` (purple), community `--com` (brown). Pages and cards that belong to an area use its colour and its pale background (`--edu-bg` and so on). The `area` argument of `action_cards` starts a row of bricks with that area's colour. +- `--hot` (orange) is for highlights, `--urgent` (red) only for urgency. +- No large areas of saturated colour, no dark bands across the page, no beige highlights (A11, A12). + +## 6. Type and reading + +- Newsreader for headings, Source Sans 3 for text. Body text is 18 px; nothing is smaller than 15 px. +- No italics outside reference lists (A2). Emphasis is semi-bold. +- Headings, buttons and labels are in sentence case. +- Reading lines stay under 80 characters (B8). The narrow reading column is for prose; tables, tools, programmes and directories may use the full width. + +## 7. Shared parts to reuse + +Before writing a new component, check these: + +| Need | Use | +|---|---| +| A page with a lead image beside its title | `doors/page_hero.html`, through `hero_image` in front matter (AWoP, Citational Justice, AI in Metascience) | +| A set of actions as cards | `{{< action_cards area="edu|res|jus|com" >}}` | +| Search and a count over a long list | `{{< list_filter >}}`, with `noun` for the count ("Showing 12 of 436 effects") | +| Contents on a phone | `doors/toc_phone.html`: an open, labelled list that collapses after six sections | +| Names with links | `doors/name_list.html` | +| Keywords on a resource | `doors/resource_keywords.html` | +| Previous and next | `doors/pager.html`: Previous on the left, Next on the right | +| Information to keep but not lead with | a `details` disclosure with a plain label | + +Images in the first screen are not lazy-loaded. + +## 8. Phones + +- Show the same information as on desktop, in a different order if needed. Hide a part only when it repeats something already on the screen; for example, the home page's secondary actions are hidden at 760 px and below. +- Tap targets are at least 44 px, including small close buttons. A small visible control can have a larger invisible tap area. +- A toolbar may stay on screen while a long list scrolls. On a phone only its search row stays, so the list keeps most of the screen. +- Do not repeat navigation: hide a "Go to" menu where the side contents card already lists the same sections. + +## 9. Words + +- Write plain, specific text, and explain a feature in one sentence ("Tags link pages and resources across the site on the same topic."). No marketing phrases, no exclamation marks, British English (B9). +- Shortening text that its authors wrote, such as a tool's description, goes in its own PR for the authors to review. +- Resource entries, glossary terms, cluster pages and other generated pages get their wording from spreadsheets and documents (see `AGENTS.md`). Change their presentation in the templates, and their wording at the source. + +## 10. Accessibility and the checks + +The floor is in checklist sections A3, C1 to C9: WCAG AA contrast, visible keyboard focus, alt text, no sideways scrolling at 390, 1024 and 1440 px, and none with text enlarged to 200%. `scripts/rebrand/check_design.py` and `scripts/rebrand/check_axe.py` test most of it on every push; `scripts/rebrand/README.md` lists what each check covers. + +## Proposing a design change + +1. Branch from the branch you are changing (`rebrand-doors` until launch, then `main`). Put each change that someone would judge on its own in its own PR. +2. Open the PR description with what changes for visitors. Then show, for each change, a before-and-after crop of the affected part at 390 px and at 1440 px, with one line above it saying what changed. Full-page screenshots side by side are too hard to compare. +3. List the choices that a reviewer may want to reverse under **Decisions to review**. +4. Run the checks above and say which passed. A change to a page's description needs an entry in `scripts/rebrand/allowed_changes.txt`. +5. For a larger review, have people or models rate a handful of representative pages from screenshots at both widths, and also try the live build to find problems that screenshots hide. Treat their suggestions as input: record which you accept and why, and judge them against this guide. From efeb55fd66cc84f0019da27a0d6a25184fa66bae Mon Sep 17 00:00:00 2001 From: Lukas Wallrich Date: Fri, 13 Nov 2026 00:01:44 +0000 Subject: [PATCH 2/5] Design guide: clusters keep one colour each across the spectrum Co-Authored-By: Claude Opus 5.5 --- DESIGN.md | 1 + 1 file changed, 1 insertion(+) diff --git a/DESIGN.md b/DESIGN.md index 5887e86d286..60ca72da55d 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -38,6 +38,7 @@ Every repeated device has to earn its place. In practice: ## 5. Colour carries meaning - Each of the four areas has its colour: education `--edu` (green), research `--res` (blue), social justice `--jus` (purple), community `--com` (brown). Pages and cards that belong to an area use its colour and its pale background (`--edu-bg` and so on). The `area` argument of `action_cards` starts a row of bricks with that area's colour. +- The 11 FORRT clusters are not areas. Each keeps a colour of its own, and together they span the spectrum (`layouts/partials/clusters/colors.html`), so the clusters can be told apart. Strong cluster colours are for small marks; their backgrounds stay pale. - `--hot` (orange) is for highlights, `--urgent` (red) only for urgency. - No large areas of saturated colour, no dark bands across the page, no beige highlights (A11, A12). From 5f7d823e5c2599c5c3e8cc0fdb1ca9342a0e0a53 Mon Sep 17 00:00:00 2001 From: Lukas Wallrich Date: Fri, 13 Nov 2026 00:21:36 +0000 Subject: [PATCH 3/5] Design guide: diagrams of a section's parts double as navigation Co-Authored-By: Claude Opus 5.5 --- DESIGN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESIGN.md b/DESIGN.md index 60ca72da55d..3c3932512d2 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -9,7 +9,7 @@ Styles live in `assets/css/doors/`, with colours and type defined once in `token - The page's main tool, list or action appears in the first screen at 390 px and at 1440 px. Background, history and acknowledgements come after it. - Move information down, or put it behind a disclosure with a plain label ("About the glossary project, and how to cite it"). Do not delete it to make the page shorter. - "How to cite" is a visible section of its own wherever a page asks to be cited. -- Keep images that explain something, such as the Replication Hub diagram, even when the page would look more uniform without them. +- Keep images that explain something, such as the Replication Hub diagram, even when the page would look more uniform without them. When such a diagram shows the parts of a section, such as the clusters diagram, make it the way in to those parts: each part links to its page, with readable labels and a keyboard route. ## 2. One clear next step From b8d3960cc86ba5c8e5667342126aaaaea88b3bd1 Mon Sep 17 00:00:00 2001 From: Lukas Wallrich Date: Fri, 13 Nov 2026 11:36:20 +0000 Subject: [PATCH 4/5] Design guide: stand alone, with the checklist's lasting requirements folded in Co-Authored-By: Claude Opus 5.5 --- DESIGN.md | 59 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 3c3932512d2..fecc78551f7 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,24 +1,32 @@ # Designing pages for forrt.org -How pages on forrt.org should look and behave, for anyone changing a template, a style or the layout of a page. The site uses the Doors design. Its starting point is the [Doors acceptance checklist](https://github.com/forrtproject/forrt-design/blob/main/doors-mock/checklist.md), which records the community's requirements; IDs such as A9 below refer to it. The principles here come from applying that design across the site's templates, and they override the checklist where they differ. +How pages on forrt.org should look and behave, for anyone changing a template, a style or the layout of a page. The site uses the Doors design, which came out of community feedback on the earlier site and a design brief; this guide holds what still applies from both, together with the principles learnt from applying Doors across the site's templates. Styles live in `assets/css/doors/`, with colours and type defined once in `tokens.css`. Shared page parts are in `layouts/partials/doors/` and `layouts/shortcodes/`. -## 1. Lead with what visitors came for +## 1. Character + +- FORRT is an organisation with several facets, run by a community. Pages should feel lively and communal: not sleek or corporate, not a newspaper, blog or severe institution, and not dark, menacing or heavy. +- The site has one idea of its own, the castle and its doors, which runs across pages without becoming tiresome. It must not depend on content that has to be refilled constantly. +- Avoid the generic template look: no ivory-serif-and-rust formula, no tracked capitals as labels above headings, no hairline-ruled columns as the main organising device, no grids of identical cards. Short schedule labels, such as MORNING and AFTERNOON in a programme, are the exception: tracked capitals help there. +- Real content only: no invented statistics, quotes or examples. + +## 2. Lead with what visitors came for - The page's main tool, list or action appears in the first screen at 390 px and at 1440 px. Background, history and acknowledgements come after it. - Move information down, or put it behind a disclosure with a plain label ("About the glossary project, and how to cite it"). Do not delete it to make the page shorter. - "How to cite" is a visible section of its own wherever a page asks to be cited. - Keep images that explain something, such as the Replication Hub diagram, even when the page would look more uniform without them. When such a diagram shows the parts of a section, such as the clusters diagram, make it the way in to those parts: each part links to its page, with readable labels and a keyboard route. +- Colour and size, not only position, make the order of importance clear, on phones too. -## 2. One clear next step +## 3. One clear next step - Each screen has one main action. Other actions are quieter: smaller, outlined or plain links. - Action labels say what the visitor will do ("Teach with open materials", "Explore replications"), not what FORRT has. - Prefer routes into FORRT's own pages. A link that leaves forrt.org says where it goes. - Every kind of submission starts at `/submit/`, which sends people on to the right form. Do not call submitting "contributing": contributors join the work and are listed as such. -## 3. Calm, specific pages +## 4. Calm, specific pages Every repeated device has to earn its place. In practice: @@ -26,30 +34,31 @@ Every repeated device has to earn its place. In practice: - Search and filters belong on long lists (the glossary, the resources directory, Reversals). A list of fewer than about twenty items needs neither. - Tags: a tag links to the tags page only when at least five pages and at most a quarter of all pages share it (`layouts/partials/functions/tag_counts.html`). Rarer tags are plain keywords; tags on more pages are not shown, because they no longer tell pages apart. - In long lists of long entries, show the first two lines of each description (three on a phone) with a "more" button. Without JavaScript the full text shows. -- Avoid the generic template look (A9): no tracked capitals as labels above headings, no hairline-ruled columns as the main organising device, no grids of identical cards. Short schedule labels, such as MORNING and AFTERNOON in a programme, are the exception: tracked capitals help there. - Cards for actions are the brick cards of `action_cards`. A set of bricks uses several area colours, never three near-identical ones. Lists of tools are rows: a linked title and a sentence, not boxes. +- Framed boxes (cards, panels, toolbars) keep space inside them and between them; text never runs up against a box's edge. -## 4. Links look like links +## 5. Links look like links - A link is visible as a link without hovering, normally by an underline. A row that is clickable as a whole still shows its title as a link. - Things that are not links never look like buttons or chips. An unlinked related term is plain text. - Buttons in a row have a gap between them, on every screen size. -## 5. Colour carries meaning +## 6. Colour carries meaning -- Each of the four areas has its colour: education `--edu` (green), research `--res` (blue), social justice `--jus` (purple), community `--com` (brown). Pages and cards that belong to an area use its colour and its pale background (`--edu-bg` and so on). The `area` argument of `action_cards` starts a row of bricks with that area's colour. +- FORRT works in four areas of equal standing: Education & Pedagogy, Meta-Science & Research, Social Justice & DEIA, and Community & Sustainability. Each has its colour: education `--edu` (green), research `--res` (dark blue), social justice `--jus` (purple), community `--com` (brown). Pages and cards that belong to an area use its colour and its pale background (`--edu-bg` and so on). The `area` argument of `action_cards` starts a row of bricks with that area's colour. - The 11 FORRT clusters are not areas. Each keeps a colour of its own, and together they span the spectrum (`layouts/partials/clusters/colors.html`), so the clusters can be told apart. Strong cluster colours are for small marks; their backgrounds stay pale. -- `--hot` (orange) is for highlights, `--urgent` (red) only for urgency. -- No large areas of saturated colour, no dark bands across the page, no beige highlights (A11, A12). +- `--hot` (orange) is for highlights, `--urgent` (red) only for urgency. White is a clean ground. +- Colour is fresh but not loud: no large areas of saturated colour, no intense full-bleed colour, no dark band across the page, no grey-and-beige, and no beige highlights. -## 6. Type and reading +## 7. Type and reading - Newsreader for headings, Source Sans 3 for text. Body text is 18 px; nothing is smaller than 15 px. -- No italics outside reference lists (A2). Emphasis is semi-bold. +- No italics anywhere outside reference lists, including menus, captions, labels and quotes. Emphasis is semi-bold. - Headings, buttons and labels are in sentence case. -- Reading lines stay under 80 characters (B8). The narrow reading column is for prose; tables, tools, programmes and directories may use the full width. +- Reading lines stay under 80 characters, measured on the rendered lines. The narrow reading column is for prose; tables, tools, programmes and directories may use the full width. +- Use the FORRT logo as supplied. Century Schoolbook is not a web font here. -## 7. Shared parts to reuse +## 8. Shared parts to reuse Before writing a new component, check these: @@ -66,22 +75,34 @@ Before writing a new component, check these: Images in the first screen are not lazy-loaded. -## 8. Phones +## 9. Phones - Show the same information as on desktop, in a different order if needed. Hide a part only when it repeats something already on the screen; for example, the home page's secondary actions are hidden at 760 px and below. - Tap targets are at least 44 px, including small close buttons. A small visible control can have a larger invisible tap area. - A toolbar may stay on screen while a long list scrolls. On a phone only its search row stays, so the list keeps most of the screen. - Do not repeat navigation: hide a "Go to" menu where the side contents card already lists the same sections. +- The phone menu keeps the chosen section visible, opens its submenu directly below it, and has a visible way to close it. -## 9. Words +## 10. Words -- Write plain, specific text, and explain a feature in one sentence ("Tags link pages and resources across the site on the same topic."). No marketing phrases, no exclamation marks, British English (B9). +- Write plain, specific text, and explain a feature in one sentence ("Tags link pages and resources across the site on the same topic."). No marketing phrases, no exclamation marks, British English. - Shortening text that its authors wrote, such as a tool's description, goes in its own PR for the authors to review. - Resource entries, glossary terms, cluster pages and other generated pages get their wording from spreadsheets and documents (see `AGENTS.md`). Change their presentation in the templates, and their wording at the source. -## 10. Accessibility and the checks +## 11. Motion + +- Animation never overlaps or hides text, and it can be paused with a mouse, a keyboard and on touch, through a control that appears on hover, focus or tap rather than at rest. +- Reduced-motion settings are respected, and every animated part has a static version that works without WebGL or JavaScript. + +## 12. Accessibility and the technical floor + +- Text has a contrast of at least 4.5:1, large text at least 3:1. +- Keyboard focus is always visible; pages have a skip link, landmarks and alt text on images. Escape closes menus, and an opened desktop menu takes the next Tab stop. +- No page scrolls sideways at 390, 1024 or 1440 px, nor at 390, 760, 1024 and 1440 px with text enlarged to 200%. +- Images, canvases and text never collide at any width, including the breakpoints either side of 760, 1000 and 1240 px, with the fonts loaded. +- No script errors and no broken images. -The floor is in checklist sections A3, C1 to C9: WCAG AA contrast, visible keyboard focus, alt text, no sideways scrolling at 390, 1024 and 1440 px, and none with text enlarged to 200%. `scripts/rebrand/check_design.py` and `scripts/rebrand/check_axe.py` test most of it on every push; `scripts/rebrand/README.md` lists what each check covers. +`scripts/rebrand/check_design.py` and `scripts/rebrand/check_axe.py` test most of this on every push; `scripts/rebrand/README.md` lists what each check covers. ## Proposing a design change From 461097be8c1c43ec5d2889fbc795fa60aacc48d7 Mon Sep 17 00:00:00 2001 From: Lukas Wallrich Date: Fri, 13 Nov 2026 12:24:55 +0000 Subject: [PATCH 5/5] Design guide: settle the first round of rules; point CONTRIBUTING.md to it Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 2 ++ DESIGN.md | 12 ++++++------ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8cfa0854da9..aeb6266b43b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,6 +128,8 @@ For browser edits, GitHub handles branch creation and opening the PR; see [stagi All proposed changes must be made on a feature branch and submitted via a Pull Request to `main`. We do not use a separate development branch. +If your change affects how pages look or behave, follow the design principles in [`DESIGN.md`](DESIGN.md). + 1. **Fork and clone** — fork the repository to your account and clone it locally (if you haven't already). 2. **Create a feature branch** from an up-to-date `main` (commit or stash any local work first): diff --git a/DESIGN.md b/DESIGN.md index fecc78551f7..83c773b4f5d 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,6 +1,6 @@ # Designing pages for forrt.org -How pages on forrt.org should look and behave, for anyone changing a template, a style or the layout of a page. The site uses the Doors design, which came out of community feedback on the earlier site and a design brief; this guide holds what still applies from both, together with the principles learnt from applying Doors across the site's templates. +How pages on forrt.org should look and behave, for anyone changing a template, a style or the layout of a page, on any part of the site. The site uses the Doors design, which came out of community feedback on the earlier site and a design brief; this guide holds what still applies from both, together with the principles learnt from applying Doors across the site's templates. Styles live in `assets/css/doors/`, with colours and type defined once in `tokens.css`. Shared page parts are in `layouts/partials/doors/` and `layouts/shortcodes/`. @@ -21,7 +21,7 @@ Styles live in `assets/css/doors/`, with colours and type defined once in `token ## 3. One clear next step -- Each screen has one main action. Other actions are quieter: smaller, outlined or plain links. +- Each screen leads with its main action, or with up to three equal ones. Other actions are quieter: smaller, outlined or plain links. - Action labels say what the visitor will do ("Teach with open materials", "Explore replications"), not what FORRT has. - Prefer routes into FORRT's own pages. A link that leaves forrt.org says where it goes. - Every kind of submission starts at `/submit/`, which sends people on to the right form. Do not call submitting "contributing": contributors join the work and are listed as such. @@ -30,8 +30,8 @@ Styles live in `assets/css/doors/`, with colours and type defined once in `token Every repeated device has to earn its place. In practice: -- Pills and chips are for controls: filters, toggles, language switches. A list of links, such as related glossary terms, is a plain list. -- Search and filters belong on long lists (the glossary, the resources directory, Reversals). A list of fewer than about twenty items needs neither. +- Pills and chips are for controls: filters, toggles, language switches. A list of links, such as related glossary terms, is a plain list. One exception: an item may carry one quiet tag for a category that visitors filter by on the same page, such as a resource's purpose. +- Search and filters belong on long lists (the glossary, the resources directory, Reversals). A list of fewer than about twenty items needs neither, and a longer one may do without when another clear route through it exists, such as a contents list. - Tags: a tag links to the tags page only when at least five pages and at most a quarter of all pages share it (`layouts/partials/functions/tag_counts.html`). Rarer tags are plain keywords; tags on more pages are not shown, because they no longer tell pages apart. - In long lists of long entries, show the first two lines of each description (three on a phone) with a "more" button. Without JavaScript the full text shows. - Cards for actions are the brick cards of `action_cards`. A set of bricks uses several area colours, never three near-identical ones. Lists of tools are rows: a linked title and a sentence, not boxes. @@ -52,7 +52,7 @@ Every repeated device has to earn its place. In practice: ## 7. Type and reading -- Newsreader for headings, Source Sans 3 for text. Body text is 18 px; nothing is smaller than 15 px. +- Newsreader for headings, Source Sans 3 for text. Body text is 18 px. Nothing is smaller than 15 px, except footnotes and similar small print, which may be 14 px. - No italics anywhere outside reference lists, including menus, captions, labels and quotes. Emphasis is semi-bold. - Headings, buttons and labels are in sentence case. - Reading lines stay under 80 characters, measured on the rendered lines. The narrow reading column is for prose; tables, tools, programmes and directories may use the full width. @@ -108,6 +108,6 @@ Images in the first screen are not lazy-loaded. 1. Branch from the branch you are changing (`rebrand-doors` until launch, then `main`). Put each change that someone would judge on its own in its own PR. 2. Open the PR description with what changes for visitors. Then show, for each change, a before-and-after crop of the affected part at 390 px and at 1440 px, with one line above it saying what changed. Full-page screenshots side by side are too hard to compare. -3. List the choices that a reviewer may want to reverse under **Decisions to review**. +3. List the choices that a reviewer may want to reverse under **Decisions to review**, including any place where the change departs from this guide, with the reason. When the same departure comes up a second time, change the guide instead. 4. Run the checks above and say which passed. A change to a page's description needs an entry in `scripts/rebrand/allowed_changes.txt`. 5. For a larger review, have people or models rate a handful of representative pages from screenshots at both widths, and also try the live build to find problems that screenshots hide. Treat their suggestions as input: record which you accept and why, and judge them against this guide.