Add Loop UI design system tokens and canonical state mapping (#194)

[mberrys]

Summary

Implements the load-bearing pieces of #194 ("Define and implement the Loupe UI design system"):

• pdfquick::tokens (LoopLibQuick/sources/looptokens.h/.cpp) — semantic spacing tokens (4px grid) and a ColorRole enum resolved per LoopTheme (Dark/Light/HighContrast). No call site hardcodes a colour; every foreground/background pair is WCAG contrast-checked in docs/LOOP_DESIGN_SYSTEM.md.
• resolveStateVisual() (LoopLibQuick/sources/loopstatevisual.h/.cpp) — the single canonical finding/check presentation mapping the issue calls for, consumed by (finding, status, decision). Implements the two invariants [0.2.1] Define and implement the Loupe UI design system #194 is actually about: an incomplete check never renders as a pass, and an actively-waived finding never renders as a pass.
• docs/LOOP_DESIGN_SYSTEM.md — the token table with contrast figures, the canonical state table, and current adoption state.
• UnitTests/tst_loopstatevisualtest.cpp (UnitTestsLoopStateVisual) — table-driven over severities, check statuses, waive/non-waive decisions, stale vs. active decisions, and out-of-schema inputs; explicitly asserts the two never-passed invariants.

Scope decisions (read before reviewing)

The issue text is stale. #194 (and #193/#195/#196/#127) were written against a pre-rebrand snapshot: Pdf4QtLibGui/loupe/… and Pdf4QtEditorPlugins/… no longer exist (Widgets GUI retired, Loupe → Loop rebrand). This PR implements against the repo's actual current layout — pdfquick::tokens in LoopLibQuick, docs/LOOP_DESIGN_SYSTEM.md — and explains the translation in the doc's "Naming note". docs/quick-design-tokens.json (issue #178) already defined a provisional dark-theme contract for the Quick canvas; this extends it to a full role set and a light theme rather than duplicating it.

Components are not included. Issue §3's finding card / inspector row / overlay / progress / empty-state / error-state / confirm implementations have no consuming surface yet — #193, #195, #196, and #127 are all still open. Building fixtures with nothing to host them would be speculative; docs/LOOP_DESIGN_SYSTEM.md records this and says each should land with its consuming surface, built on the tokens and mapping here.

CanvasPalette is left as-is. It already reuses one colour for both focus ring and warning severity, which the new ColorRole set intentionally separates (FocusRing vs. SeverityWarning). Re-pointing the canvas overlay at these tokens is canvas-specific work with its own visual-regression needs, tracked as adoption work rather than done here.

Build/test verification is incomplete. This environment has no configured Qt 6.11 CMake build (/home/user/loop/build does not exist) and provisioning one is outside this session's autonomous budget (configure_or_reconfigure and toolchain changes require approval). I ran everything that doesn't need a configured build:

• clang-format --dry-run --Werror on all touched/added C++ files — clean.
• scripts/ci/check_source_integrity.py — pass.
• scripts/generate-architecture-catalogs.py --check — pass (regenerated to add UnitTestsLoopStateVisual).
• scripts/agent/generate-adapters.py — pass, no drift beyond agent-policy.json itself.
• Changelog fragment present and valid.

cmake --build / ctest / clang-tidy-18 for the new UnitTestsLoopStateVisual target could not be run here and need CI or a maintainer to confirm the build. I read every relevant existing source (PreflightFinding/PreflightCheckStatus/PreflightDecision in LoopLibCore, CanvasPalette, the LoopLibQuick/ProductQuickAccessibilitySmoke CMake linkage) to keep the new code consistent, but flagging this honestly rather than claiming a green build I couldn't produce.

One build-graph note: UnitTests/CMakeLists.txt currently has no target linking LoopLibQuick at all (pre-existing — tst_quickcanvastest.cpp etc. exist as source but aren't wired to any target, and linking the SHARED LoopLibQuick library as a plain add_executable needs qt_add_executable() + qt_import_qml_plugins() per ProductQuickAccessibilitySmoke/CMakeLists.txt, which no existing UnitTests target does). Since looptokens.cpp/loopstatevisual.cpp only need QColor (no Qml/Quick), the new test compiles those two translation units directly into UnitTestsLoopStateVisual instead of linking the shared library, avoiding that untested link edge. UnitTests/CMakeLists.txt is a protected path (flagged risk: high by check-change.py) for this reason — the change is additive and follows the existing sibling-target pattern otherwise.

Test plan

• clang-format --dry-run --Werror on all new/changed files
• scripts/ci/check_source_integrity.py
• scripts/generate-architecture-catalogs.py --check
• scripts/agent/generate-adapters.py
• Changelog fragment (changes/cc-hopeful-galileo-k8b2cu.md)
• cmake --build + ctest -R UnitTestsLoopStateVisual (needs a configured Qt 6.11 build — not available in this session)

🤖 Generated with Claude Code

https://claude.ai/code/session_01NxoABBuEB3mYqr8QyA6KuB

---

Generated by Claude Code

[mberrys]

source_integrity failed on the first push: scripts/ci/test_check_loop_identity.py found 8 occurrences of the legacy pre-rebrand product-name token.

3 were mine — docs/LOOP_DESIGN_SYSTEM.md's "Naming note" quoted the old product name while explaining why this doc uses current naming instead of issue #194's stale paths. Fixed and pushed (f31f749): reworded to make the same point without the literal token.

The other 5 are pre-existing on dev and not introduced by this PR: .github/workflows/reusable-linux.yml:79, .github/workflows/reusable-windows.yml:92, UnitTests/testdata/budget-exhaustion/manifest.json:190, UnitTests/tst_budgetexhaustiontest.cpp:133, and scripts/budget_exhaustion/generate_corpus.py:14 all already contain the token on origin/dev (verified via git show origin/dev:<path>) — this check is already red on the base branch. I don't have a fix for those to port (no existing PR or revert addresses them), and fixing them is outside this design-system PR's scope. Leaving them for a separate fix.

---

Generated by Claude Code

[mberrys]

Follow-up on the Loop identity findings: fixed the 5 remaining legacy product-token occurrences so this PR is green on its own (base dev is still red at those paths).\n\n- .github/workflows/reusable-linux.yml:79 and reusable-windows.yml:92: working-directory loupe -> loop. This was also the agent-fast failure (No such file or directory .../loupe).\n- scripts/budget_exhaustion/generate_corpus.py:14, UnitTests/tst_budgetexhaustiontest.cpp:133, UnitTests/testdata/budget-exhaustion/manifest.json:190: schema_kind loupe-processing-budget-exhaustion-corpus -> loop-processing-budget-exhaustion-corpus (manifest regenerated via generate_corpus.py, --check passes locally).\n\nVerified locally: check_loop_identity.contract_findings() == [], check_source_integrity.py passes, generate_corpus.py --check passes, check-change.py dry-run passes with head-branch cc/hopeful-galileo-k8b2cu.

[mberrys]

agent-fast / build failed on 0aa0d4c: clang-tidy-18 on UnitTests/tst_budgetexhaustiontest.cpp errored with 'tst_budgetexhaustiontest.moc' file not found.

Root cause: agent-policy.json's core module already listed UnitTestsBudgetExhaustion under tests, but its source file wasn't in core's paths glob list. check-change.py runs clang-tidy on every changed C++ file regardless of module classification, but only cmake --builds the targets/tests selected by module classification — so when a change touches only tst_budgetexhaustiontest.cpp (as 0aa0d4c's schema_kind fix did), the file's own AUTOMOC target never gets built first, and clang-tidy can't find the generated .moc. (Everything else in 0aa0d4c's build was fine — worth noting UnitTestsLoopStateVisual itself built, linked, and passed cleanly in that same run.)

Fixed and pushed (ed178bd): added UnitTests/tst_budgetexhaustiontest.cpp to core.paths so its target builds before clang-tidy runs on it, same as every other core test file already listed there.

---

Generated by Claude Code