Skip to content

UX specifications (UXS)

Purpose

A UXS describes the experience: what a user sees on each page, what each control does, what the commands print and in which order a newcomer meets them. It is the contract reviewers and the browser tests check a change against. It complements:

When to write one

Write or extend a UXS when work adds or changes a surface: a catalog page, the inspector, a command's output or flags, or the onboarding path. A change that only moves internals needs an RFC, not a UXS.

The rules every surface keeps

These hold across all three specifications below; a change that breaks one needs a decision (an ADR), not just a UXS edit.

  1. The catalog is read-only. No page writes to the data tree. A decision the pages suggest is shown as the command that makes it, run locally.
  2. Command-line parity. Every view and every action in the UI also exists as an evh command that asks the same adapter and computes with the same functions, so a number on a page is the number in the terminal. New surfaces add both. The table is in UXS-003.
  3. No item text in static pages, unless the repository already publishes it (a profile written --with-text, refused unless git has committed every item's file). Outputs, references and the items themselves otherwise reach a browser only through the local inspector server.
  4. Say what a number is measured against. Every row of arms names its reference or judge, and the tints in UXS-001 mark the ones not scored against gold.
  5. Refuse, do not guess. A comparison that cannot be made (two datasets, two references) is refused or set aside with the reason, never computed anyway.

UXS vs RFC boundary

A UXS owns what is visible: pages, sections, columns, controls, words, tokens, the order of output. The RFC owns behaviour behind it: data formats, caching, the server's limits, the algorithms. When a rule could live in either, it goes in the RFC and the UXS links it.

Status lifecycle

Status Meaning
Draft Under review; may change before it is built
Active Describes what is built; changes to the surface update it in the same PR
Superseded Replaced by a newer UXS, linked from it

UX specifications

UXS Title Status Related PRDs / RFCs What it covers
UXS-001 The catalog Active PRD-004, PRD-005, PRD-006; RFC-003 The shared shell and tokens; home, dataset, goal (answer first, rounds), reference and metrics pages; tints, paging, search
UXS-002 The run inspector Active PRD-004, PRD-006; RFC-003 Choosing arms, testing against a baseline, conditions, fields, the analysis charts, the per-item table, one item side by side
UXS-003 The command line and the first evaluation Active PRD-001, PRD-007 The onboarding path, how commands speak (refusals, hints, exit codes), the parity table, the round flow

Adding one

Name it UXS-NNN-short-slug.md (next number, three digits), with Status, Authors, Related PRDs, Related RFCs and Implementation paths, then Summary, Principles, Scope (with non-goals), and the surface itself. Add its row here.