Skip to content
AnglinAI Docs

Tags — Task-first UI redesign

The interactive prototype is in task-redesign-prototype.html. Open it in a browser. The published version is at https://claude.ai/artifact/NztduWgCEs3CZi95fqkRct.

This document extends interaction-spec.md. Where the two conflict, this document wins. That spec’s principles still apply: one structure model, every edit is an op, no false green, guided first with the raw tree one toggle away, and never changing page appearance.

0. Summary

The workspace is reorganized around three tasks. All three share one structure model, one undo history and one save:

TaskJobDefault when
AnalyzeA plain-language verdict: what is broken, who it affects, and how much can be fixed automaticallyFirst open of a document
RepairApply the safe fixes in one reviewed, undoable step, then go through the judgment calls one at a timeThe user clicks Repair
ExploreSynced tag tree, page and screen-reader transcript, with a walk barExpert inspection or editing

Settings (gear in the app bar) controls auto-accept confidence, compatibility mode, conformance profile, strict mode and AI checks and credits.

1. Decisions (Larry, 2026-10-04)

  1. Color: Gevell green (#046307, dark #5ccb60) is used for pass, accepted, done and the focus ring. Gevell blue #003da5 is the primary action color. In this product, this overrides the global “no green” rule. Status is never shown by color alone: every status also has an icon shape and a word.
  2. The user pays for the full analysis, in credits. The engine structure check is free.
  3. AI acceptance depends on confidence.
    • Every AI or inferred judgment carries a confidence score: alt text, reading order, link text, heading level, decorative or not, language of parts.
    • 100% means “Proven”: a deterministic rule shows only one answer is possible. Example: a single-column, text-only page whose geometry and tag order agree. Proven results are auto-accepted.
    • AI confidence is capped at 99%.
  4. Auto-accept levels per category: Never / Proven only / ≥95% / ≥90% / ≥80%.
    • 80% is a hard floor.
    • Org admins can lock a higher minimum per category.
    • The server enforces both the floor and the admin minimums.
  5. Auto-accepted ≠ reviewed. Auto-accepted changes appear in History as Auto · 97%, can be undone, and never count as human review. A person clicking Accept records an attestation (Reviewed · LA).
  6. Compatibility mode (default Acrobat Pro; also PAC 2024, CommonLook, Gevell standards-only).
    • It changes which rules count, the rule names, and how manual checks are shown.
    • Disagreements are listed as “Differs from Acrobat” and by default don’t lower the score. There is a toggle to count them.
    • Each mode is pinned to a named product version (for example “Compatible with Acrobat Pro 26.001”). The version is shown on the app-bar chip, in Analyze, in Settings, and on reports and verification receipts.
    • We re-run the test set whenever the vendor changes its checker.
  7. Conformance profile:
    • Profiles: ISO 14289-1 machine rules (veraPDF), Matterhorn 1.1 (adds the human checkpoints as review items), or PDF/UA-2 + WCAG 2.2.
    • Strict mode turns warnings into failures and won’t report “Ready” while anything is unchecked or unreviewed.
    • Individual strict rules can be toggled: no skipped heading levels, Lbl/LBody required, table Summary required (on in Acrobat mode).

2. Shell

  • App bar:
    • Left: Library link, document name, save state (“All changes saved” / “Saving…” / “Offline · 3 queued”), and the compatibility chip.
    • Center: task switcher (role=tablist; arrow keys move between tasks). Repair shows a live “N left” badge.
    • Right: score chip, Undo, Redo, History, Settings, Export ▾.
    • Density and theme toggles move into a settings menu.
  • Status bar: shows the last op in History wording (“Retyped P to H2 · 1 item”) with an inline Undo. The engine status appears only on error.
  • Every task keeps the existing F6 region cycling, the command palette and the live announcer.
  • ≤1024px: Analyze stacks into one column. Repair’s decision card becomes a bottom sheet. Explore uses the existing view tabs. Touch targets are 44px.

3. Analyze

  • Verdict block:
    • A score ring with two arcs: the current score, and a faint arc for the projected score after automatic repair.
    • A one-sentence verdict and up to three blockers, ranked by harm.
    • Main action: Repair · N fixes are automatic. Secondary action: Explore the structure.
  • Totals: Fail · Needs a person · Machine-verified · Not checked. “Not checked” counts against the verdict.
  • Findings table: columns are Area, Status, How it gets fixed (Automatic / Guided · AI drafts / You decide), and Items.
    • A vocabulary toggle switches each row between Plain language / WCAG 2.2 / PDF/UA-1 (clause + Matterhorn) / Acrobat names.
    • In Acrobat mode an agreement line appears above the table: “Agrees with the Acrobat Pro 26.001 Full Check on X of Y rules”. Rows that disagree get a “Differs from Acrobat” chip.
  • Side panel:
    • Projected score after automatic repair.
    • “Who this affects”: screen reader, keyboard, low vision/reflow. Clicking a group filters the table.
    • A clickable page heatmap that jumps to Explore at that page.
    • A “How this was checked” box (mode, profile, strict, AI checks, credits used) with a link to Settings.
    • A “What this check can’t tell you” box.
  • States:
    • Analyzing: step list plus a progress bar.
    • Untagged: “Auto-tag first” path.
    • Scanned: route to OCR.
    • Clean: “Ready to publish”, with Export as the main action.
    • Stale: the chip reads “Checking…” and old numbers are never shown as current.
  • Re-runs incrementally after each op.

4. Repair

  • Rail on the left:
    • Progress meter.
    • Automatic fixes (phase 1).
    • Your decisions: Images → Headings → Tables → Reading order → Language.
    • Verify & save.
    • Each step shows counts, for example “4 auto-accepted · 5 to review” or “46 pages proven · 2 to check”.
  • Automatic fixes sheet:
    • One row per deterministic rule, each with a checkbox and a count, and expandable to its instances.
    • Summary: “Fixes N · Introduces 0 · Page appearance unchanged”.
    • Apply creates one history group: Automatic repair (N).
  • Guided step layout (the same for every step):
    • The page in the middle, with everything but the current item dimmed.
    • A thumbnail queue along the bottom, each showing confidence %. A hollow check means auto-accepted; a solid check means accepted by a person.
    • A decision card on the right:
      • why it matters, with the WCAG, ISO and Matterhorn references
      • the AI draft with its confidence and the reason it needs you (“Below your 95% level”)
      • Accept / Decorative / Needs long description / Skip for now
      • what a screen reader says before and after
  • Keys: ↵ accept, D decorative, J/K next/previous, ⌘Z undo. “Accept all high-confidence” appears only when 3 or more items qualify, and opens a review sheet first.
  • Step-specific cards:
    • Headings: level picker with a live outline preview.
    • Tables: TH/TD grid workbench with header-association lines on the page.
    • Reading order: numbered path, reorder with ⌘⇧↑/↓ or drag.
    • Language: highlighted span plus a BCP-47 picker.
  • “Skip” keeps the item unresolved. A step badge never shows a check while items remain.

5. Explore

  • Top bar: lens chips (All tags, Headings, Figures, Tables, Artifacts, Reading order) replace the Overlays popover. A document outline skyline (heading density per page) jumps to a page on click.
  • Tree: virtualized ARIA tree with type chips colored by family (tag-families.ts) and an issue dot per row. A filter box uses filter.ts (type:Figure no:alt page:14). A context menu offers wrap, unwrap, retype, merge and delete, each with a keyboard path.
  • Page: overlays with reading order drawn as one numbered dashed path.
  • Right: a compact inspector (breadcrumb, type, key props, this node’s issues, “Fix in Repair ›”, and “More properties” for the existing inspector sections) above the screen-reader transcript (reader grammar). Problem lines are flagged.
  • Walk bar: Prev/Next, reading or tree order, position “N of M”, the current utterance, and ▶ Listen.
  • Selecting in the tree, the page or the reader selects in all three.
  • Role map, class map, tab order and document properties are reached through the command palette.

6. Settings

Sections: Automatic acceptance, Compatibility, Conformance, AI checks & credits. Each applies to the current document and can be saved as the user’s default.

  • Automatic acceptance:
    • Categories: image descriptions, reading order, link text, heading levels, decorative images, language of parts.
    • Each row has a segmented control. Options below an admin lock are disabled, with the note “Locked · your admin requires at least 90%”.
    • A trust line: “412 auto-accepted in the last 30 days · 6 undone”.
  • Compatibility: radio cards, each showing its pinned version. A list of mode quirks, and a toggle “Count Gevell-only findings in the score” (off by default).
  • Conformance: profile radio cards, a strict mode switch, and individual strict-rule switches.
  • AI checks & credits: switches for alt-text quality, reading-order sense and link text, each with a credit estimate. “Run full analysis on open”: Always / Ask over 25 credits / Never.

7. Visual system

  • Fonts (unchanged): Archivo (display), Public Sans (body), JetBrains Mono (tag names, references).

  • Status vocabulary:

    StatusIconColor
    Fail✕ octagonred #b3261e
    Needs a person? triangleamber #8a5300
    Pass✓ circlegreen
    Reviewed · initials✓ with person glyphgreen
    Not checked⊘grey

  • Overlay families are unchanged from tag-families.ts. Artifacts are dashed with no order number. Untagged content is dashed with a ”!” badge.

  • The focus ring is a 3px green outline with a 2px offset.

8. Backend work

NeedSourceStatus
Instant structure checkEngine checkStructure(), diagnostics()Exists
Score + WCAG + PDF/UA mapping/api/pdf-audit (scorer, veraPDF, manualRisks). Needs a tag-docs-aware route (docId + version)Wire up
Matterhorn IDsveraPDF clause → Matterhorn lookup tableNew
Previewable, undoable auto-fixesPort pdf-polish fixups to tags-core op-builders (artifact pagination, TH Scope, link /Contents, heading skips, orphans, Title/Lang/DisplayDocTitle). Must be engine ops, not a server byte rewrite.New
AI checksworkers/api/src/services/pdf-ai-opinions.ts: findAltTextQualityIssues, findScreenReaderCoherenceIssues, findLinkTextQualityIssues (ai tier, cost-ledgered)Exists
Confidence on every AI findingAlt-quality drops its internal 0–1 confidence (and filters out < 0.5). Link and coherence checks return only a severity. Add confidence to ManualReviewRisk and to all prompts.Extend
”Proven” reading orderSingle-column, text-only detection plus agreement between geometricOrder() (pdf-reading-order-correctness.ts) and tag order. Emit 100% only on a proof.Extend
AI alt text in Repair/api/pdf/alt-text returns {alt, decorative, confidence}. Add Supabase JWT auth and credit metering (today it requires an X-API-Key).Wire up
Compatibility profilesA rules table mapping each check → Acrobat / PAC / CommonLook verdict and name, versioned per product release, plus a test set of PDFs with each tool’s real report. CI fails when agreement drops. The pinned version string comes from the test set’s metadata.New
Profile + strict modePass both to the scorer. Print them on reports and receipts.New
Settings storagePer-user defaults, per-document overrides, per-org category minimums (Supabase migration). The server enforces the 80% floor and the org minimums.New
Undo, history, save, export UIsession-context.tsx, workspace/save/save-controller.ts, workspace/history/log.ts, workspace/sync/*. All built, none mounted.Wire up
Score on library cardsStore the latest analysis summary on the tag-doc recordNew

9. Build order

  1. Shell:
    • Task switcher, save state, Undo/Redo, History and Export in the app bar, wired to the existing controllers. The landing page already promises undo and save.
    • Status bar: last action with an inline Undo.
    • Settings route skeleton.
  2. Explore: lens chips, the single reading-order path, tree filter box, walk bar, compact inspector. Mostly a re-layout of existing views.
  3. Analyze + Settings:
    • One analysis model combining the engine check and the audit route, then the verdict screen, the vocabularies and the heatmap.
    • Settings: compatibility, profile and strict mode, and credits.
    • Build the Acrobat test set first; agreement with Acrobat is this phase’s acceptance test.
  4. Repair:
    • Auto-fix op-builders and the preview sheet.
    • Confidence on every AI result, and auto-accept by category.
    • Guided steps in order of harm: images, headings, tables, reading order, language.
    • Verify & save.

Every phase follows the repo standards: i18n keys in apps/tags/locales/en.json, WCAG 2.2 AA (test:a11y), mobile Playwright, 80% coverage, and a branch plus PR for each phase.