Files
rea/website/style-guide.md
T
12ee785e5e feat(website): follow the system dark mode and fix small-screen text (#1894)
* fix(website): keep text inside small screens and tidy small type and spacing

From a layout audit of the built pages:

- Long terminal prompts and code-header buttons wrap instead of being cut
  off at 320px (WCAG 1.4.10).
- Headings and table cells break long words, so the 1.4.12 text-spacing
  test no longer widens pages past 320px.
- Header and footer links get a 24px minimum height (2.5.8).
- Labels that rendered under 12px now render at 12px or more, and inline
  code never drops under 0.75rem.
- The home page's hero and definition rows share one column gap and align
  on the first baseline, and stacked boxes share one corner size.
- Highlight chips get room around the text, and the active run in a step
  listing is one band instead of a box per line.

Colors are unchanged.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊

* feat(website): follow the system dark mode

The site was light only, so a reader with a dark system still got a white
page. Add one prefers-color-scheme: dark block to the stylesheet that swaps
the six color variables to Catppuccin Mocha (MIT) and overrides the fixed
colors that would break on a dark page: selection, buttons, tinted
highlights, flow nodes and arrows, and a visible border on the agent
terminal.

Add a dark theme-color tag beside the light one in the page template and
the 17 pages, and a Dark column to the style guide's color table.

Light colors are unchanged. The SVG figures follow in the next commit; the
blog page's inline strokes, the dinosaur game and the social card are left
as they are.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊

* feat(website): give the five SVG figures a dark scheme

Pages load the figures with <img>, so page CSS cannot reach inside them.
Each figure now carries its own @media (prefers-color-scheme: dark) block
of attribute-selector overrides that map every light color to a Catppuccin
Mocha color, with one shared map across all five. No markup, labels,
shapes or positions change, and nothing uses !important.

Four figures also paint a mantle canvas so "Open figure" works on its own;
analyst-thinking.svg stays transparent, since it sits on the page rather
than in a figure box.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊

* chore(website): refresh translation source references

The theme-color tags move the page lines that the catalogs cite, so
python3 scripts/website.py translations extract rewrites the source
references in messages.pot and the 18 PO files. No message text changes.
The same run moves the "Main navigation" entry to its new position in each
catalog.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊

* fix(website): keep inline step highlights inline

The full-width band for the active step now applies only to code-step
blocks. The inline parameter highlights in the dx-ball and th04
signatures stay inline again.

🤖 Generated with Claude Code (Opus 5.5) 🦊

* test(website): check every page offers light and dark theme colors

Each authored reading page, and its built copy in every language,
must carry one theme-color tag for light and one for dark. The
stylesheet must keep its dark color scheme block. On the commit before
dark mode, this test fails on every page.

🤖 Generated with Claude Code (Opus 5.5) 🦊

* fix(website): draw the dinosaur game in the page colors

In dark mode the game box turned dark, but the game still drew with
its light colors, so the dinosaur, cacti and text fell to about 2:1
contrast. The canvas now reads five colors from CSS variables on
.dino-stage. Light values are the old ones, so light mode draws the
same pixels. Dark values are Catppuccin Mocha: 8.3:1 for the
dinosaur, 7.9:1 for cacti and text, 7.6:1 for the crash color.

The moved lines in dino-demo.js shift the translation catalog
references, so the catalogs are refreshed too (reference comments
only).

🤖 Generated with Claude Code (Opus 5.5) 🦊

* fix(website): recolor the Touhou flywheel arrows in dark mode

The inline flywheel SVG on the Touhou article hard-codes its stroke
colors, so on the dark page its connectors fell to about 2:1. Two
dark-only rules map those strokes to the page accent and muted colors
(7.8:1 and 7.4:1). Light mode is unchanged.

🤖 Generated with Claude Code (Opus 5.5) 🦊

* fix(website): redraw the dinosaur game when the system theme changes

The canvas reads its colors only when it draws, so an idle, paused or
crashed game kept the old palette after a theme switch. Each demo now
redraws on a prefers-color-scheme change.

The added lines shift the translation catalog references, so the
catalogs are refreshed too (reference comments only).

🤖 Generated with Claude Code (Opus 5.5) 🦊

---------

Co-authored-by: Claude Sonnet 5.5 <sonnet@cassie-pc>
Co-authored-by: Claude Opus 5.5 <opus@cassie-pc>
2026-10-12 03:17:49 +08:00

303 lines
17 KiB
Markdown

# REA website writing and design guide
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
>
> — N0zoM1z0
For REA, that means a concrete question, a figure that explains the process,
evidence the reader can inspect, and a useful next step. A clean, refined
appearance comes from precise wording, readable figures, consistent typography
and deliberate spacing.
Use this guide for new pages and revisions. Create the common page structure
with `python3 scripts/website.py new-page`, then reuse the relevant components
from an existing page, `public/assets/styles.css` and `public/assets/main.js`.
Keep shared regions in sync with `templates/`. Contribution, preview and
publication commands are in [README.md](README.md).
## What a reader should understand
A reader scanning for five seconds should see the subject and the result. After
ten seconds, the main figure should explain the sequence. After fifteen seconds,
the prompt or first example should show how to start.
These are reading goals, not a requirement to fit every investigation above the
fold. Keep the main path short and let readers open the supporting details.
## Write the task directly
Write the English source first. Keep translated wording just as concrete: a
reader should understand the question, the evidence and the next action without
decoding a literal translation. Preserve commands, code and recorded values.
Read a whole example together when reviewing its translation. Check headings,
figures and interactive labels at phone widths, including right-to-left editions.
The [translation guide](locales/README.md) explains the catalogs and update process.
Name the software, behavior or action in headings. Give the opening paragraph
one job: explain what the page covers. Use concrete verbs such as install, trace,
read, compare and calculate.
| General wording | More useful wording |
| ------------------------------------------------ | ------------------------------------------------------------------ |
| Start with a question. | Set up REA. |
| Follow a feature across the app. | Trace an Electron CSV export. |
| Following a copy through Notion. | How Notion copies text and HTML. |
| A position becomes a sound. | Calculate left/right sound panning. |
| Follow the investigation. | REA case studies. |
| Reviewed boundary / source owner / target extent | The helper / its surrounding code / the code section being checked |
Questions also work when they name a behavior: “Where is the CSV created?” and
“How does a copied block keep its structure?” give the reader something specific
to look for.
Explain necessary terms where they first matter. An IPC channel can be described
as a named message between Electron processes. Keep exact API names, addresses
and JSON paths in the code or result they identify.
Give each paragraph new information. A diagram can summarize a sequence, while
the code below explains individual steps. Repeating that REA supplies
instructions, callers and constants in several surrounding paragraphs adds no
new step. Explain that role once, then show the results.
Use captions for useful context: which values are illustrative, where an excerpt
comes from, or what a check covers. Scope a claim positively and precisely:
“The compiled function matches 63 bytes” is more useful than a broad claim
followed by several qualifications.
Search titles and sharing previews follow this standard too. Name the software
or task so someone can understand the page before opening it. Keep titles and
descriptions accurate and concise; use technical terms when they identify the
actual topic. Preserve a clear visible headline rather than repeating search
terms throughout the page. See [README.md](README.md#search-and-sharing-metadata)
for canonical URLs, automatic sitemap generation and sharing assets.
## Build a page around one question
### Introductions and first exercises
Explain reverse engineering with a familiar behavior. Pair a short, authentic
code excerpt with readable logic and a figure that explains the result without
requiring the reader to understand either language. Show a simple agent prompt
and the specific facts REA supplies to answer it.
Put compact setup at the beginning of the homepage: a copyable installation
prompt and the ordinary setup command. Then explain what reverse engineering
means and what it lets someone do, before the worked examples.
Begin each example with its goal and the reason to inspect that program.
Name the actual evidence REA returned and what the agent did with it.
Give long pages a short table of contents with concrete section names. Preserve
the reading width: the homepage uses the side gutter when it has room,
and a collapsible sticky menu on smaller screens. Highlight the current
section, keep fragment links usable without JavaScript, and leave room above
the destination for the sticky control. Offer experienced readers a direct
route from setup to the analysis guides. Keep full case-study previews on the
Showcases page, linked from the opening actions.
Use short labels, selective bold text and the shared blue highlight to make
those facts visible when scanning. Keep source, interpretation and new code
attributed to their respective roles. On mobile, the demo can precede its
supporting code once its purpose is clear.
Show how the reader's task changes using the same question on both sides of a
manual/agent comparison. Let returned evidence make REA's contribution visible.
When showing manual analysis, use authentic instructions and specific analyst
questions: what a command ID means, which call performs arithmetic, or which
operand enters a calculation. Numbered selections can connect the code to
illustrative thought bubbles. Keep the agent side brief: one visible prompt,
a concrete answer, and the evidence used to reach it.
When a small reconstruction makes the finding tangible, let readers change an
input or setting and try the result. Connect inspection, recovered logic,
reconstruction and the new experiment. Keep the recovered rule distinct from
new teaching mechanics, and check it against the inspected program.
Offer a supplied target for the next step. A first exercise should take the reader through
setup, a question, an answer with source references, one prediction they can
check, and a follow-up. Introduce specialized prerequisites when the chosen
target requires them.
### Guides
1. Name the task and introduce a small example.
2. Show a short flow of the relevant files, calls or observations.
3. Provide a copyable agent prompt and its prerequisites.
4. Explain the important code or returned fields.
5. Let the reader try the example, with a command or one ZIP download.
6. State the expected result and where to find it.
7. Offer a specific follow-up question or another relevant guide.
A command should work after the steps immediately before it. Use `npx` for a
first CLI query when global installation is optional. Browser examples should
open the hosted fixture by default; a local URL needs a server-start step. Keep
target paths, debugging endpoints and other required inputs explicit.
### Case studies
1. Introduce the project and the particular feature being examined.
2. Show a figure that explains the investigation or behavior.
3. Give a short example prompt.
4. Pair important REA queries with selected returned evidence.
5. Connect that evidence to readable source or an explanation.
6. Explain how the result was checked.
7. Link the reconstruction repository and supporting sources.
Show REA's useful contribution through a concrete finding: a missing stack
argument, a caller, bytes behind a constant, or source ranges in a packaged
bundle. Explain what the agent does with that finding. Credit source
interpretation, reconstruction and external checks to the work that performed
them.
Keep a second investigation optional. Notion's clipboard path is the main
story; Markdown tables and SQLite are additional examples. Native `<details>`
keeps them available without interrupting the first question.
Keep the explanation on the website. Repository links provide source,
reproduction instructions and further evidence. Use specific links for those
purposes, and immutable commit links for checkpoint-dependent facts.
### Method articles in the Blog
Use longer articles to explain methods, choices and ideas through project
experience. Open with a clear takeaway. A personal essay can follow how the
author's understanding changed, using concrete episodes to develop a deeper
argument. Keep the reasoning easy to follow; a Blog article does not need to
become a tutorial. Figures are optional. Add one when it explains something
useful rather than repeating a familiar opening flow.
Choose cases that teach different decisions. For example, TH08 illustrates
continuing existing work, TH095 illustrates reusing an established method in a
new project, and TH04 illustrates adapting checks to an older platform. Close
each case with the lesson the reader can apply. Put dates and progress figures
beside the milestone they measure, with pinned evidence links in supporting
details. Calendar time, source presence, exact comparison, build success and
runtime checks each describe a different result.
Make an analogy concrete. The industrial analogy can connect agent execution,
quality checks, durable knowledge and a change in how work is organized. Explain
what changes and support the argument with experience. Keep necessary terms
plain and leave engine inventories in references. A method guide can finish with
a first task; an essay can finish with the implications of its argument.
When discussing another project's approach, preserve its credit and contribution
history. Attribute quotations, link their context and distinguish the author's
interpretation from the other project's stated position. Describe the technical
or contribution-model disagreement without assigning motives to its authors.
Working outlines should be visibly labeled and marked `noindex` until they
become finished articles.
## Make figures explain a relationship
Each figure should answer a question that a reader can name. Choose the visual
form that fits it:
| Relationship | Existing example | Useful form |
| ----------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| Analysis and verification steps | DX-Ball sound pan | Flow with separate verification branches |
| Code across process boundaries | Electron CSV export and Notion clipboard | HTML flow with APIs and channel names |
| A mathematical transformation | TH04's fixed and aimed rings | SVG drawn from the angle formula |
| Original instructions and readable source | DX-Ball and TH04 | Selectable HTML code with matching step highlights |
| A request caused by an action | Notes browser export | Flow, observed result table and script excerpt |
| Recovered behavior and a new experiment | Dinosaur speed reconstruction | Inspected code, playable demo and original-result check |
| Time blocks and changing output | Aegis login-code reconstruction | Adjustable clock, block number and code beside recovered methods |
Use SVG or semantic HTML for diagrams with exact text, numbers and arrows.
Generated illustrations can help explore a layout, but the published labels,
relationships and values need to be checked. [figures.md](figures.md) records the
existing assets and original layout references.
Keep labels short, align related nodes, and give arrows an explicit direction.
Use color to identify the relevant operation or connection. Add a legend when
the visual encoding needs one. Avoid making the diagram repeat the entire page.
State illustrative inputs in the caption. TH04's diagram uses a count of 16 and
a player direction of 40; its dots are calculated from those values. Give an
image useful alternative text, and keep source code as selectable HTML.
On small screens, HTML flows stack. A wide SVG can have its own horizontal scroll
and an “Open figure” link. A diagram should remain readable at its intended
display size; scaling small labels down is not a mobile layout.
## Use the existing visual system
The shared stylesheet defines the site. Its core colors are:
| Token | Light | Dark | Use |
| ---------- | --------- | --------- | -------------------------------- |
| `--page` | `#ffffff` | `#1e1e2e` | Page background |
| `--ink` | `#20252b` | `#cdd6f4` | Main text |
| `--muted` | `#5b6570` | `#a6adc8` | Secondary text |
| `--line` | `#e0e5e9` | `#45475a` | Section and component boundaries |
| `--soft` | `#f4f6f8` | `#181825` | Code and supporting surfaces |
| `--accent` | `#294f82` | `#89b4fa` | Links and meaningful highlights |
The light values are the default. When the reader's system is set to dark, a
`prefers-color-scheme: dark` block at the end of the stylesheet swaps in the dark
values, which are [Catppuccin Mocha](https://github.com/catppuccin/palette)
(MIT). There is no toggle. Any new fixed color needs a dark counterpart in
that block.
Use the system sans-serif stack for prose and the shared monospace stack for
code. The current container is at most 1080px wide, with article text limited to
760px. Reuse the existing heading sizes, line heights, section spacing and
component classes.
Whitespace separates ideas. Thin rules identify sections. Headings establish
hierarchy. The blue accent identifies something useful. Keep these elements
consistent rather than adding a new treatment for each page. Decorative
gradients, large shadows and scroll effects do not help explain the examples.
Agent terminals contain short, copyable prompts. Use the existing continuous
cursor animation and reduced-motion behavior. Label an example prompt as an
example; a real recorded result belongs in an evidence block. Copy buttons
should copy only the intended text, without the prompt symbol or cursor.
Include the shared `↑ Top` link on reading pages, with `id="top"` on the body.
Keep its 44px minimum touch height, safe-area spacing and keyboard focus return.
Use the shared script for visibility and reduced-motion behavior.
Use `minmax(0, 1fr)` for grid tracks that contain long commands or nested panels.
Allow code blocks to scroll within their own area. Check expanded details as
well as the default page. Document-level horizontal scrolling usually means a
component needs a width constraint; hiding it can conceal content.
## Keep evidence accurate and public
Preserve target identity, source locations, relevant versions and the scope of
checks. Keep observations, interpretation and unknowns distinguishable in plain
language. Put lengthy provenance in an evidence document or collapsed details.
Label simplified source and selected instruction excerpts. When compiler checks
apply to the maintained project source, say so; a readable summary is a separate
presentation of the calculation. Historical checks and a fresh REA inspection
retain their own dates and attribution.
Use generic example data and display paths. Machine paths, personal account
identifiers, credentials, local configuration, full vendor bundles and raw
captures belong outside the public website. If a path is shortened in a displayed
query, identify that in its caption and keep the original capture separately.
## Review and publish
Before merging a change:
- Read the default page in order. Check that every section advances the task.
- Open details and confirm that sources and extra examples remain usable.
- Verify commands, prerequisites, expected results and downloadable files.
- Keep links and asset paths working at both `/` and `/rea/`.
- Check desktop, intermediate and mobile widths, including 320px.
- Check copying, downloads, code-step selection, keyboard access and reduced
motion. Core content and native details should work without JavaScript.
- Confirm that figures and code excerpts agree with the supporting evidence.
- Run site preparation, verification and formatting checks.
Match verification to the change. Copy edits need page and interaction checks.
New analysis or behavior claims need the real evidence that supports them; a mock
or a page-loading check cannot establish those claims.
Follow the PR review and CI process, then publish using the existing manual
`website-pages.yml` workflow on `main`. Its default `both` target publishes the
same verified artifact to Cloudflare and GitHub Pages and checks both published
commit markers. Use `pages` only for an explicitly requested publication while
Cloudflare credentials are being configured.
Ordinary commits should not publish the site. After deployment, check both live
pages and confirm they match the reviewed version. The legacy VitePress build
remains separate from the Pages publisher.