GEWU/docs/development/VISUAL_DESIGN_PROTOCOL.md

# Visual design protocol

Direction: editorial research workspace, selected by the owner on 12 October 2026. Status: proposed implementation specification v0.1. Exact colors, typefaces and geometry require a rendered review.

## Artistic and functional premise

The interface should feel like working with a well-edited research folio: a warm page, strong titles, legible annotations and precise references. Its central visual relationship is between an assertion and the evidence beside it. Project context stays visible while the reader moves between a problem, an approach and its source.

Use the editorial/technical typography contrast from Sonification, adapted for sustained reading. Large titles can carry character. Operational labels remain quiet and readable. Space and thin rules organize the page; dense technical metadata appears when it helps the reader assess origin, freshness or a relationship.

The website searches, navigates and displays knowledge. It has no capture, edit, approve, merge or generate controls. Account sign-in and view preferences do not change that knowledge boundary.

## Information architecture

Primary destinations are Search, Problems & topics, Sources and Stale knowledge, within an explicit project or all-projects scope. A project landing view shows its owner-defined purpose and key questions before recent records. Avoid a dashboard of counts without a reading task.

The core journey is: choose scope -> find a problem or note -> inspect applicable approaches and their conditions -> open the supporting quote -> inspect the source revision. History and typed neighbors are available without taking over the reading surface. Accepted relationships and similarity suggestions occupy separately labeled sections.

Desktop uses a modest navigation rail, a flexible reading/results area and an optional evidence panel. Target a 224 px rail and a 360–440 px evidence panel where space permits; the reading column has a maximum measure of about 68 characters. At insufficient width, evidence becomes a route or drawer and navigation collapses. Do not force three columns into a narrow viewport or hide primary reading content to preserve panel dimensions.

At 390 px, use one natural document flow. Search filters open on demand; citation links navigate to a focused evidence view with an obvious return path. At 200% zoom, preserve content and function. Long IDs/URLs wrap or offer a labeled copy action. Data tables may have a local horizontal scroll region with headers; the page itself must not overflow.

## Proposed visual tokens

Light theme is the initial acceptance target. A dark theme is a later token variant requiring its own contrast and screenshot checks, not a color inversion.

| Token | Proposed value | Role |
| --- | --- | --- |
| `surface.canvas` | `#F4F1EA` | Warm page background. |
| `surface.paper` | `#FFFDF8` | Reading/evidence surface. |
| `surface.subtle` | `#EAE5DA` | Quiet grouping and selected rows. |
| `text.primary` | `#242722` | Main reading text. |
| `text.secondary` | `#596057` | Secondary content, still readable. |
| `border.subtle` | `#D6D0C3` | Decorative separators only. |
| `border.control` | `#777C71` | Control boundaries where required for recognition. |
| `accent.link` | `#315D50` | Links, focus and active scope. |
| `status.caution` | `#85520B` | Stale or incomplete context, always labeled. |
| `status.error` | `#A1342B` | Failed/unavailable states, always labeled. |

These are candidate foreground/background pairs. Verify their actual rendered use; a palette list is not accessibility proof. Never lower text opacity to suggest age. Superseded content retains reading contrast and a clear status label.

Use semantic CSS properties once in the token layer; components cannot invent hex colors, spacing scales or animation durations. Spacing scale: 4, 8, 12, 16, 24, 32, 48 and 64 px. Typical radii: 2–6 px. Use shadows for overlays only. Thin rules and typography establish ordinary hierarchy.

Proposed fonts: Source Serif 4 for editorial titles and long-form reading; Source Sans 3 for navigation, search results and controls; JetBrains Mono for IDs, code and compact technical values. Self-host licensed assets with local fallbacks and `font-display: swap`. Verify Cyrillic and any required CJK fallback coverage with the actual source corpus. Font choice must not create a network dependency for local/offline reading.

Reading text begins at 17–18 px with roughly 1.6 line-height. Controls and result descriptions use 16 px; secondary metadata uses at least 14 px. Use sentence case. Small uppercase may identify a short section, but must never carry the main content or hide warnings. Dates/numeric tables use tabular figures.

## Component contracts

| Component | Must communicate | Interaction/state requirement |
| --- | --- | --- |
| Scope selector | Current project, included shared/cross-project scope | Changing scope updates URL and query; hidden exclusions are disclosed. |
| Search result | Title, concise assertion/summary, origin, relevant dates and evidence availability | Full title is a link; keyboard focus visible; stale warning survives truncation. |
| Reading header | Node type/title, project, lifecycle and dates | Keep revision/history discoverable without showing raw schema jargon by default. |
| Evidence block | Exact quote, source title, location, captured revision and availability | Opens the cited revision/location; explains when preview is unavailable; original/download remain permission-checked. |
| Support details | Location check, semantic assessment, source reliability and assessor | Separate labels; never collapse into a green “verified” badge. |
| Relationship row | Typed verb, target, conditions and support/rationale | Distinguish accepted link from related suggestion; omit out-of-scope target content with an explanation. |
| Freshness notice | As-of date and why stale/unknown | Text plus icon; no color-only indication. |
| History | Previous revision, actor category, date and reason | Reading old material visibly retains its revision context. |
| System state | Loading, empty, failed, forbidden, offline or index behind | Give the correct next action; do not label request failures as “No results.” |

Source quotations must look like quotations. Interpretation text must be labeled as interpretation and retain its supporting references. A model's confidence is not a truth probability; expose its meaning in details rather than presenting a spurious percentage meter.

Use a small application-owned component catalog: AppShell, ScopeSelector, SearchField, FilterBar, ResultRow, ReadingHeader, EvidenceBlock, SourceLocator, RelationshipRow, FreshnessNotice and StateMessage. Build each with fixtures for long titles, missing metadata and failure states before composing large pages.

## Motion, accessibility and content safety

Frequent search, selection and keyboard navigation should respond immediately. Optional disclosure transitions are brief, typically 120–180 ms, and respect reduced-motion preferences. No animated text entrance, CRT fringing, pulsing telemetry, scanlines or decorative graph animation in the reading surface.

Use semantic HTML, logical headings, landmarks and a skip link. All interactions work by keyboard. Dialogs trap focus and restore it on close; non-modal panels do not trap focus. Announce asynchronous result counts and errors without moving focus unexpectedly. Copy actions have visible success/failure feedback.

Target WCAG 2.2 AA: normal text contrast at least 4.5:1; large text and meaningful control graphics at least 3:1 where applicable. GEWU's preferred touch target is 44 x 44 CSS px, a product standard stricter than the AA minimum target-size criterion. Do not claim this preference is the universal WCAG minimum. See [W3C's criterion reference](https://www.w3.org/WAI/WCAG22/quickref/), checked 12 October 2026.

Render source Markdown as untrusted content. Disable raw HTML by default, sanitize any supported extensions, and do not execute source scripts or MDX. Source CSS cannot enter the application styles. Code and formulas have bounded rendering and horizontal scrolling where needed. Downloads use controlled, authenticated routes; embedded previews have an explicit sandbox policy.

## Visual acceptance

Before a page is called complete, inspect real renders at 1440 x 900, 1024 x 768 and 390 x 844, plus 200% zoom and a 320 CSS-pixel reflow case. Exercise keyboard-only scope -> search -> node -> quote -> return, and test a screen reader on the primary path. Run axe, then manually check reading order, focus restoration and meaningful labels; an automated score alone cannot establish accessibility.

Use fixtures for: long multilingual titles, missing archive, scanned PDF extraction failure, unsupported claim draft outside accepted results, stale datapoint, superseded node, contradiction, cross-project omission, empty search and index lag. Verify contrast on actual states, including selected/hover/focus/disabled appearances.

Record screenshots with route, fixture, viewport, revision and browser version. Evaluate whether a person finds a cited answer within the PRD's two-minute target. Screenshots prove layout at those dimensions; the reading task measures usefulness. Neither substitutes for the other.

This document specifies direction and review criteria. No rendered GEWU page or accessibility pass exists yet.