Stabilizing Ink and Terminal for reading

Status, ownership and scope

Status and date: Draft, 2026-10-26; proposed design direction, not an implementation contract

Accountable owner: OINK maintainers; separate recorded acceptance for each preset

Delivery owners: Theme maintainers own CSS, resolvers and focused checkers; documentation maintainers own bilingual contracts, real-site fixtures and browser review; accessibility reviewers own manual task evidence

Baseline: OINK v1.4.0; local source identity and dirty-snapshot limits are recorded in the research

Affected surfaces: Architecture, Components, Shell, Landing and the visual preset decision

Release intent: A later release, subject to refinement and independent acceptance; no new preset recommended

Context and evidence

Ink and Terminal already exist as explicit experiments. Their shared shell is an advantage: readers retain navigation, search, appearance controls and content semantics when changing style. Their remaining problems are repeated decoration, typography outside ordinary prose, inconsistent owned geometry, and incomplete acceptance. Ink is already neutral sans editorial; making it serif would consume Folio’s separate territory. Terminal should become a readable engineering handbook, retaining mono technical roles alongside proportional explanations.

The dated research distinguishes source facts, measurements, design judgments and a limited CSS overlay. Normal-size measurements, spacing probes and focused checks are encouraging, but the whole-document footer failure survives them. Manual 200% text-resize and 400% browser-zoom checks remain separate from the 32px font-preference probe.

Goals and explicit exclusions

Both candidates must work across Docs, Book, Blog, galleries, Expo and Landing in EN/ZH, light/dark and narrow/wide views. Neither is a separate shell, accessibility mode or table-density mode. Exclude new renderers, global spacing changes, font downloads, runtime dependencies, terminal effects, moving selection tracks, raised Tabs, boxed Field names and Paper heading tails.

Two optional concepts remain outside 1.4 scope:

Proposed behavior and boundaries

Preserve the palette, assign each role

Retain these source colors initially. Values below are light/dark pairs, not a new configuration authority; preset SCSS remains the implementation owner. Refine repetition before changing hue.

Success, warning, error and information retain their semantic tones, icons and labels. Red is not every Ink status; mint is not every Terminal status. Keep neutral badges distinguishable from success. Decorative separators may remain subtle; required control boundaries need independent contrast measurements.

Authored theme_color remains authoritative for accent surfaces. Actual documentation uses blue #245f94/#5da2dd, Book orange #9a3412/#fb923c, and Blog violet #6d28d9/#a78bfa. These do not replace the link/code text roles. Review both authored accents and preset defaults.

Keep reading roles and verify actual fallback

Book captions, table descriptions and human-readable search titles/excerpts use the body role. Authored chapter numbers retain their meaning and follow their heading’s role. Technical paths, command controls and identifiers remain mono in Terminal. Field names stay unboxed, at weight 600. Descriptive Terminal table headers move to body 0.875rem/600; ordinary prose retains 1rem/1.7 and the shared reading measure. Display titles retain page-specific scale and wrap; do not shrink mobile prose to accommodate mono chrome.

The existing sans fallback order is -apple-system, BlinkMacSystemFont, PingFang SC, Hiragino Sans GB, Microsoft YaHei, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans SC, generic sans-serif and emoji. The mono list follows IBM Plex Mono with SFMono-Regular, Cascadia Code, Roboto Mono, Menlo, Consolas, Liberation Mono, Sarasa Mono SC, Noto Sans Mono CJK SC and generic monospace. Listed names do not install fonts. YaHei precedes Segoe and can supply Latin too. Chinese glyphs need not occupy Latin mono cells. Preserve language metadata, typography: system, explicit roles and legacy Sass precedence; inspect loaded, blocked, system and overridden font conditions on actual Windows/Android. (Font matching)

Establish hierarchy and language-sensitive links

Compare Ink article h1 at weight 750/tracking -.025em, h2/h3 at 700/-.012em, and a 1px strong-token top rule instead of the current heavier rule. Chinese headings use zero tracking. Remove enforced uppercase/tracking from minor headings, table headings and callout titles. Terminal headings use 600/zero tracking; remove generated ##/### and callout brackets while preserving authored Book numbers, semantic labels and heading anchors. No fake prompts, blinking cursor effects or decorative heading tails.

Ink prose links remain natively underlined at rest, including lists, notes and citations. Terminal retains a persistent non-color link distinction; verify its existing semibold cue in real prose and use native underlines where that cue is insufficient. Navigation relies on its location and persistent current-state marks. Hover must not change layout, weight or hit area. (GOV.UK links)

Underline geometry remains a review decision. The overlay uses max(1px, .06em) thickness, .22em offset, with a Chinese .25em/skip-ink: none comparison. A blanket .25em rule is not accepted. Compare English .12–.18em and Chinese text-underline-position: under with only 0–.06em extra offset, starting with skip-ink: auto. Scope by actual language, including Chinese blocks inside English pages. Test mixed glyphs, punctuation, descenders, inline code and wrapped links; no line may collide with glyphs or adjacent lines. (CSS Text Decoration draft)

Make component states coherent

Owned component corner radii: Ink 0px, Terminal 2px, no elevation shadows; include FileTree’s currently hard-coded 0.6rem corner radius. Preserve image, avatar, status-dot and vendor geometry.

Current/selected: Ink keeps a static accent rail; Terminal keeps neutral inverse rows/marker. Programmatic state remains. Hover, selection and keyboard focus stay distinct; no traveling pill.

Focus: Immediate static indicator, independently measured on every adjacent surface, visible in forced colors; no global outline reset.

Text selection: Start from current authored-accent fill at 22% light/35% dark; measure composited text/inline-code pairs. Change through the owning role if needed; do not assume the opacity passes.

Tabs: Flat labels, static bottom selection rule, separate focus; no raised active tab. Preserve keyboard, hash/storage behavior, long labels and touch hit areas.

Fields and inputs: Unboxed technical Field names; descriptions remain prose. Actual input controls retain persistent labels, identifiable boundaries and associated error text; placeholder alone is insufficient.

Code and tables: Quiet single frame; preserve syntax semantics, comments, copying, captions, header associations and numeric alignment. Descriptive headers can wrap; no whole-table uppercase. Preserve authored width/overflow policy and local scroll access.

Notes, quotes, footnotes: Keep essential text visible; restrained semantic marker/rule, close attribution and usable reference/backlinks. No oversized quote ornaments, blanket Chinese italics or added margin column.

Cards, steps, badges, disclosures: Stable labels and geometry; distinguish clickable from static content, keep real step numbers, native disclosure semantics and labeled states.

Search and appearance: Body-role result titles/excerpts, mono technical paths; readable matching/selected/muted text. Preserve dialog focus/return, IME editing, loading/error/no-results feedback and reachability with a mobile keyboard.

Landing, Blog/gallery, Book, Expo: Preserve existing composition and media behavior; fit display titles, captions, bylines and utilities into each reading task. Do not turn image surfaces into squared global resets.

Preserve output, vendor and security boundaries

Mermaid/ECharts remain mode-only; API widgets retain vendor palettes and their existing mode behavior. Do not add preset recoloring inside vendor DOM. Giscus automatic palettes follow preset and mode; explicit overrides remain authoritative, but blocked remote frames are not accepted by this review. Print keeps the light preset on white paper; no-JavaScript output keeps the site-default light palette and readable content. Markdown/RSS preserve semantic content without decorative prefixes or control leakage. Keep existing escaping, validated font/color inputs, local assets and appearance storage behavior; no new network permission or script dependency.

Compatibility and migration

Keep preset names, independent mode/style state, shell columns, breakpoints, content syntax and author overrides. Retain Paper as default and maintained consumers’ explicit [paper, slate, ink, terminal] menu. A refinement can ship while a preset remains experimental.

Promotion changes the meaning of preset_menu: true: it offers stable presets plus the site default, so promoting either experiment expands that automatic set. Make that change explicit in layouts/_partials/preset-config.html, its checker and bilingual configuration/release guidance. Explicit lists retain their chosen membership. Promotion requires per-preset maintainer acceptance, not a status-label edit. Preserve reserved Folio/Canvas warning/fallback behavior.

Implementation and owning-checker plan

Runtime edits additionally require node --test 'tests/js/**/*.test.js'; schema edits require python3 bin/generate-config-schema.py --check.

Acceptance gates and open decisions

Distinguish accessibility requirements from project targets

WCAG 2.2 A/AA is the baseline (references accessed on 2026-10-26).

Record complete tasks before promotion

Require both languages and modes at 320/390/768/1440px, with normal, enlarged and overridden text. Review long pages at top/middle/footer, heading/Book numbering, URLs, Fields, tables, code, search, appearance, media and Landing. Inspect rest/hover/current/selected/focus/text-selection, forced colors, reduced motion and no-JavaScript/print/Markdown/RSS. Record actual color pairs and human review of axe incompletes.

Actual Windows Chrome/Edge and Android Chrome font/rendering work remains pending, as do branded macOS/iOS Safari checks. Record device/OS/browser/font conditions. Pending manual tasks use NVDA on Windows, VoiceOver with actual Safari, and TalkBack on Android: traverse headings and meaningful numbers, read tables/field errors, search with Chinese input, hear concise status feedback, open/close dialogs and regain focus.

Open decisions are the Chinese underline treatment, stronger project targets, any state-specific color repair, and the promotion of each preset. If gates remain incomplete, retain experimental status or defer refinement; unrelated 1.4 work need not wait for new styles.

Decision log