# A quiet frame, made usable

Readers is the visual reference: Wrenfold Text reading content, Georgia interface text, bold Palatino
interface headings, monospaced values, paper and charcoal surfaces, restrained state colors, square controls,
and thin rules. Improve the ability to read and operate the material before
adding decoration. Subject identity belongs inside this common language, not in
a separate visual system for each page.

## Choose the surface from the task

| Surface | First useful screen | Structure | Example here |
| --- | --- | --- | --- |
| Reading/reference | Title, brief context, actual text or document links | 66–72 characters, contents beside or above text | mtl-guide; site essays |
| Collection/comparison | Search/filter and real rows | Compact paginated rows with detail, or a true comparison matrix | mystery-report |
| Live monitor | Connection truth, priorities, current state | Summary then evidence; no decorative metrics | ngu-idle-dashboard |
| Visual exploration | Meaningful chart plus its controls and equivalent text | Chart-specific layout; disclosures for detail | profile |
| Puzzle workspace | Board and primary solve/step actions | Stable board geometry; options next to controls | logical-solver |

Do not put a marketing hero in front of a working surface. Do not change ranking,
health interpretation, puzzle rules, or bot decisions while restyling their UI.

## Type and interaction scale

| Role | Target | Implementation |
| --- | --- | --- |
| Sustained reading | 18–20px for sustained prose; 16px for dense reference | `--text-body: 1rem`, line height roughly 1.6 |
| Regular labels, navigation, controls | 14px or larger | `--text-ui: .875rem` |
| Secondary metadata | 12px or larger | `--text-meta: .75rem` |
| Page titles | Usually 26–32px | `--display`, Palatino stack, weight 700 |
| Desktop interface controls | At least 36px high | `--control-size: 2.25rem` |
| Coarse-pointer interface controls | Aim for 44px high | `--control-size: 2.75rem` |

These are project design targets, not a claim of accessibility certification.
Tiny puzzle candidate marks and chart annotations need a local solution (zoom,
detail view, equivalent text); enlarging every value blindly can break geometry.
Do not silently shrink ordinary labels below the scale to make a layout fit.
Move controls to a second line, simplify columns, or use bounded overflow instead.
Use normal case for task labels and table headings: synthetic small caps can
shrink lowercase glyphs despite a nominal 14px font size. Main spreadsheet values
are task text, not secondary metadata. Reserve small caps for occasional editorial
eyebrows, never as a way to fit controls or columns.

Ordinary single-choice dropdowns use the shared `data-ui-select` enhancement:
normal-case 14px text, square triggers at least 36px high, and the same quiet
option surface as the VN readers. Keep their native select as form/data authority.
Retain the richer VN chapter browsers where grouping and chapter context are part
of the task; equal-role voyage/chapter controls still share the control scale.
See `COMPONENTS.md` for keyboard behavior, native fallback, and programmatic sync.

### Font contracts

`--reading` starts with Wrenfold Text and includes system serif and CJK fallbacks. Apply it to article prose, proof text, book chapters, and translations. Article headings can use the same role. `--serif` retains Georgia and Times New Roman. `--display` retains Palatino. `--ui: var(--serif)` keeps menus and controls unchanged. Decorative homepage symbols retain their original font. The Regular WOFF2 uses `font-display: swap`. Browsers synthesize bold and italic styles. Numerical grids, code, and mathematical notation retain their dedicated fonts. Code listings use `--mono` at `--text-ui` with the `--code-*` palette. Keep font notices in `v2/fonts/`.

Use ink-colored links and navigation with restrained underlines. Status, selected controls, scientific plots, and game/puzzle cues retain meaningful color. Borders should organize content rather than outline every label; use neutral tag surfaces and one rule per transition.

## Ownership and CSS order

`v2/base.css`: palette, type roles, common header/shell, focus, controls, tables,
print foundation, reduced-motion behavior. `v2/theme.js`: saved/system preference,
control creation, browser chrome, and both theme events. `v2/docs.css`: theme
reference pages. `v2/reader.css`: the shared bilingual and English reader surface,
used by Black Sheep Town and Albatross Koukairoku.

`v2/components.css` and `v2/components.js` are an optional layer for code listings, directories,
controls, select menus, disclosures, navigation, overflow, dialogs, and copying. See
`COMPONENTS.md` for explicit contracts and the working gallery. Existing pages do
not gain behavior merely by using a coincidentally similar class name.

Local CSS owns data visualization, board geometry, tables with special columns,
and page-specific hierarchy. Local files currently contain shared overrides;
remove one only after comparing its function with the shared rule. Use a default
fallback when referencing a newly added token so independently deployed consumers
remain usable with the earlier v2 stylesheet.

## States and access

A count, empty result, disconnected feed, uncertain result, disabled control, and
failed operation are different states. Keep their distinctions visible in words.
Use native links, buttons, labels, tables, details, and dialogs. A scroll region
that needs keyboard access gets a name and `tabindex="0"`. A dialog gets a title
relationship and returns focus. Focus on a hidden/offscreen control is a defect.

Choose table navigation before adding overflow. For a ranked collection, paginate
compact rows in normal page flow and disclose secondary fields in record details;
keep all fields available to sorting/export where those capabilities exist. For a
genuine matrix, use a named scroll region and legible columns without pagination.
Do not require pagination plus internal horizontal and vertical scrolling. Show
sort direction in the heading, with primary/secondary order explained in advanced
controls and accessible names rather than visible priority numbers.

Mobile navigation in a short reference guide can be an in-flow disclosure.
A modal drawer is appropriate only when its benefit pays for focus management,
background inertness, Escape handling, and breakpoint transitions.

A sticky index must not cover its target at enlarged text sizes. Do not hide its
scrollbar solely for appearance. Avoid fixed control heights that clip wrapped
labels. Keep text and background tokens paired in both modes and in print.

## Color and boundaries

Blue carries links, focus, and selection. Dataset colors retain their meanings.
Syntax tokens use the `--code-*` aliases of the theme tones: muted comments, blue keywords,
and quiet green, ochre, plum, and teal for strings, numbers, names, and types. Each passes 4.5:1 on paper
and surface in both modes. Print turns the palette gray. Highlight during the build.
Use muted ink for secondary text, and reserve faint ink for nonessential marks;
check contrast in context. A section boundary has one owner. Preserve the existing
rule/ornament grammar rather than stacking borders around the same whitespace.
Use a dedicated transition ornament rather than repeating the masthead logo. A
thin, square puzzle sheet may enclose the complete main unit; its top edge is the
divider, not a second parallel rule. Keep diagram colors unchanged and reserve
compact action-row treatment for verified solver-only content.

Place one PNG-centered divider at the start of the main puzzle unit, after the
complete rules and worked examples. Keep the main puzzle's lead-in, solve-link
paragraph, grids, and reference diagrams together below it. The first image may
be an example, so image position alone cannot identify this boundary. Preserve
the original text, links, diagram order, and paired-grid grouping; do not frame
the decorative mark as a content image. The divider's orientation follows the
page layout rather than changing the content's semantic grouping.

## Independent pages, related identities

Each project retains its subject identity and useful project-local navigation.
Masthead titles are plain text. Omit current-page links and author lists from headers.
Keep author navigation in the Readers catalogue. The root directory omits the Home self-link. A single,
symbol-only Home anchor returns to `https://jehlp.net/` from the existing header,
paired with the theme dial. The fine compass rose echoes the homepage's
atlas and typographic studies. Home, theme and the homepage search slash share a
44px target, 1.6rem icon field, .375rem gap, neutral ink and hover rule. Keep visible
keyboard focus and the Home accessible name/tooltip `Home — jehlp.net`. Keep the utility pair in a reserved CSS-positioned lane of the in-flow masthead.
The shared `--site-frame-width` and `--site-frame-top` follow the homepage: a 74rem
maximum with 2.5rem gutters, a 48rem maximum/1.5rem gutters below 60rem, and 1rem
gutters/.75rem top inset below 38rem. Desktop top inset is 1.5rem. Insets honor
safe areas; a stable document scrollbar gutter prevents short pages from shifting
sideways. Content shells keep their own widths. Titles reserve the pair’s space;
mobile local navigation gets a full-width row below it. Do not override header
width/top padding locally or reposition native controls after DOM readiness.
The pair scrolls with its existing header: do not add a fixed footer, reserved
bottom space, focus-driven scrolling, or a new sticky bar. NDB Idle remains exempt.

Include native `.site-home` markup in generators so it works without JavaScript.
Where a theme button is authored, wrap both in `.site-utility-pair`. The controller
fills missing markup and relocates cached first-release footer links to the
header. Only pages without any existing header receive a small in-flow utility
header. Readers retains its original Contents/Search mobile toolbar, with Home
in the page-top controls. Keep GitHub Source links out of headers; useful provenance
may remain with the material or in the footer.

Use the opt-in identity header in `COMPONENTS.md`: one relevant transparent PNG
as `img.site-mark` at 32px with empty `alt`, a serif title, and only useful local
navigation. Choose a maintained asset from `v2/marks/`; do not substitute Unicode
or emoji. These are single-ink abstract symbols generated from `v2/symbols/`: black
on paper and inverted to white on charcoal. Run `python3 tools/make_symbols.py`
(Inkscape and Pillow) to regenerate mastheads and white-on-black favicons from the
same geometry. Keep the approved Home compass and theme dial. Links, focus,
selection, game art and data/status colors retain their existing meanings.

Make margins useful: place context alongside the material when it saves space,
balance column heights where practical, and remove unexplained number gutters or
empty hero space. A serif row title and open lists can provide character without
new containers. Remove headings that repeat navigation, redundant controls in the
same context, and instructions already conveyed by controls. Keep scientific
uncertainty, privacy boundaries, provenance, failure
states, and instructions needed to operate an unfamiliar tool. On small screens,
bring margin labels into the content flow; never pay for decoration with overflow
or smaller text.

Keep CSS icon URLs relative to their stylesheet; HTML masthead images use the
shared mark URL or an appropriate relative path. Inline builds must embed all
referenced assets, including PNG marks. Do not trade an offline deliverable for an unnoticed CDN
dependency. Preserve existing favicon identity and canonical metadata.

## Original technical writing

Use [the writing policy](WRITING-STYLE.md) for original explanations, instructions, and interface text.
Use ASD-STE100 Issue 9. Preserve source text, translations, quotations, NDB fiction and item descriptions, and technical meaning.
Keep the existing typography, layout, math presentation, and interactive examples during a writing edit.