[LukasWallrich]

The design rounds settled a set of rules, such as when to use pills, how tags are shown, where citations go and how phones differ. So far they existed only in PR threads. This PR writes them into a short guide, DESIGN.md, so that the next rounds, and anyone else changing a template, can apply them to the rest of the site.

• The guide builds on the Doors acceptance checklist and cites its IDs. It does not repeat the checklist.
• It covers ten areas: leading with the task, one main action, calm pages, links, colour, type, shared parts to reuse, phones, words and accessibility. It ends with how to propose a design change: one PR per change, with labelled before-and-after crops.
• AGENTS.md gets a one-line pointer to it.

No checks were added; the guide points to the existing check_design.py and check_axe.py.

Decisions to review

• Placed at the repository root, not in scripts/rebrand/, because that folder is deleted after launch.
• Where today's decisions differ from the checklist, the guide follows the decisions. Tracked capitals are allowed for short schedule labels (MORNING, AFTERNOON), although A9 rules them out elsewhere.
• Some rules are my reading of several of your decisions rather than one stated rule:
  • pills only for controls;
  • no search on lists under about twenty items;
  • a set of bricks never in near-identical colours;
  • prefer routes into FORRT's own pages.

Created with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

---

Summary by cubic

Records the design principles settled in the Doors design rounds in DESIGN.md, so they live outside PR threads and can be applied to the rest of the site. AGENTS.md gets a one-line pointer to it. A follow-up commit clarifies that each FORRT cluster keeps one colour of its own across the spectrum.

Decisions to review

• The guide sits at the repository root, not in scripts/rebrand/, because that folder is deleted after launch.
• Where decisions differ from the checklist, the guide follows the decisions, such as allowing tracked capitals for short schedule labels despite rule A9.
• Some rules are readings of several decisions rather than one stated rule: pills only for controls; no search on lists under about twenty items; no sets of bricks in near-identical colours; prefer routes into FORRT's own pages, and a diagram of a section's parts doubles as navigation into those parts.

^{Written for commit 5f7d823. Summary will update on new commits.}

[github-actions]

👍 All image files/references (if any) are in webp format, in line with our policy.

[github-actions]

✅ Spell Check Passed

No spelling issues found when checking 2 changed file(s)! 🎉

[cubic-dev-ai]

4 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="DESIGN.md">

<violation number="1" location="DESIGN.md:19">
P3: The replication submission form lives at `/replication-hub/submit/`, not under `/submit/`, so this rule is not true of the current site. Either name that route as an exception or state that the other forms should be linked from `/submit/`.</violation>

<violation number="2" location="DESIGN.md:27">
P2: The tag threshold is a quarter of the tagged pages, not of all pages. `tag_counts.html` divides the count of pages that carry at least one tag by four. Change "all pages" to "tagged pages" so the guide matches the code.</violation>

<violation number="3" location="DESIGN.md:58">
P2: This example passes `edu|res|jus|com` as one area value, so none of the area-specific color classes match. Show one valid value and list the other choices separately.</violation>

<violation number="4" location="DESIGN.md:60">
P3: The phone contents show five sections, not six, when there are more than six. State the actual visible count so authors know what `toc_phone.html` does.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The tag threshold is a quarter of the tagged pages, not of all pages. tag_counts.html divides the count of pages that carry at least one tag by four. Change "all pages" to "tagged pages" so the guide matches the code.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At DESIGN.md, line 27:

<comment>The tag threshold is a quarter of the tagged pages, not of all pages. `tag_counts.html` divides the count of pages that carry at least one tag by four. Change "all pages" to "tagged pages" so the guide matches the code.</comment>

<file context>
@@ -0,0 +1,91 @@
+
+- 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.
</file context>

Suggested change

	- 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.
	- Tags: a tag links to the tags page only when at least five pages and at most a quarter of the tagged 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.

[cubic-dev-ai]

P2: This example passes edu|res|jus|com as one area value, so none of the area-specific color classes match. Show one valid value and list the other choices separately.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At DESIGN.md, line 58:

<comment>This example passes `edu|res|jus|com` as one area value, so none of the area-specific color classes match. Show one valid value and list the other choices separately.</comment>

<file context>
@@ -0,0 +1,91 @@
+| 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 |
</file context>

Suggested change

	| A set of actions as cards | `{{< action_cards area="edu|res|jus|com" >}}` |
	| A set of actions as cards | `{{< action_cards area="edu" >}}` (use one value: `edu`, `res`, `jus`, or `com`) |

[cubic-dev-ai]

P3: The replication submission form lives at /replication-hub/submit/, not under /submit/, so this rule is not true of the current site. Either name that route as an exception or state that the other forms should be linked from /submit/.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At DESIGN.md, line 19:

<comment>The replication submission form lives at `/replication-hub/submit/`, not under `/submit/`, so this rule is not true of the current site. Either name that route as an exception or state that the other forms should be linked from `/submit/`.</comment>

<file context>
@@ -0,0 +1,91 @@
+- 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
</file context>

[cubic-dev-ai]

P3: The phone contents show five sections, not six, when there are more than six. State the actual visible count so authors know what toc_phone.html does.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At DESIGN.md, line 60:

<comment>The phone contents show five sections, not six, when there are more than six. State the actual visible count so authors know what `toc_phone.html` does.</comment>

<file context>
@@ -0,0 +1,91 @@
+| 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` |
</file context>

Suggested change

	| Contents on a phone | `doors/toc_phone.html`: an open, labelled list that collapses after six sections |
	| Contents on a phone | `doors/toc_phone.html`: an open, labelled list; over six sections, it shows the first five and a button for the rest |

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="DESIGN.md">

<violation number="1" location="DESIGN.md:41">
P2: The current palette has only five colours, and `cluster_section.html` cycles through them for all 11 clusters, so clusters repeat colours instead of each having their own. Update the palette and assignment to match this decision, or describe the five-colour cycle accurately.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The current palette has only five colours, and cluster_section.html cycles through them for all 11 clusters, so clusters repeat colours instead of each having their own. Update the palette and assignment to match this decision, or describe the five-colour cycle accurately.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At DESIGN.md, line 41:

<comment>The current palette has only five colours, and `cluster_section.html` cycles through them for all 11 clusters, so clusters repeat colours instead of each having their own. Update the palette and assignment to match this decision, or describe the five-colour cycle accurately.</comment>

<file context>
@@ -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).
</file context>