feat(core): rule color/palette-conformance

[aram-devdocs]

Target branch

• This PR targets main

Spec

Fixes #23

Summary

• Adds the color/palette-conformance built-in rule. Flags computed colors whose CIEDE2000 distance to every entry in color.tokens exceeds color.delta_e_tolerance (default 2.0).
• Translucent colors are composited over the closest opaque ancestor background-color (default #ffffff) in linear sRGB before the ΔE measurement, so overlays are judged where they actually render.
• Palette is converted to CIE Lab once per check call (never per node) and cached as Vec<PaletteEntry>.

Crates touched

• plumb-core
• plumb-format
• plumb-cdp
• plumb-config
• plumb-mcp
• plumb-cli
• xtask
• docs/
• .agents/ or .claude/
• .github/

System impact

• New public API item (needs doc + # Errors section if fallible)
• New MCP tool (needs tools/list entry + protocol test)
• New rule (needs docs page + golden test + register_builtin entry)
• CDP / browser surface change (needs security-auditor review)
• Config schema change (run cargo xtask schema + commit result)
• Dependency added / bumped (cargo-deny must still pass)
• Determinism invariant touched (see .agents/rules/determinism.md)

The rule reuses Config::color (tokens + delta_e_tolerance), which already shipped with PR #109; no schema change required.

Architectural compliance

• Layer discipline: plumb-core has no internal deps; unsafe only in plumb-cdp; println!/eprintln! only in plumb-cli.
• Error shape: thiserror-derived in libs; anyhow only in plumb-cli::main.
• No new unwrap/expect/panic! in library crates.
• No new SystemTime::now / Instant::now in plumb-core.
• No new HashMap in observable output paths (use IndexMap).
• Every #[allow(...)] is local and has a one-line rationale.

Test plan

• just validate passes locally
• cargo xtask pre-release passes (4 built-in rules; all have docs pages)
• just determinism-check passes (3× byte-diff clean)
• cargo deny check passes
• New/changed behavior has a test — unit tests in palette_conformance.rs::tests, golden snapshot in tests/golden_color_palette_conformance.rs

Documentation

• Rustdoc added for every new public item (PaletteConformance)
• # Errors section on every new public fallible fn (no new fallible fn)
• docs/src/ updated when user-visible behavior changed
• docs/src/rules/<category>-<id>.md written for new rules
• CHANGELOG updated if user-visible (otherwise release-please handles it)
• Humanizer skill run on docs changes (avoided AI-tell phrasing in color-palette-conformance.md)

Breaking change?

• No
• Yes — describe migration path

Checklist

• Conventional Commits title
• Branch name: codex/<primary>-<type>-<slug>
• All review gates passed: spec → quality → architecture → test (+ security if triggered)
• /gh-review --local-diff main...HEAD run locally

Implementation notes

ΔE00 implementation choice. palette 0.7 only implements Ciede2000 for Lab<D65, _> and Lch<D65, _>; the Oklab type carries EuclideanDistance only. Per the spec's "use what palette exposes" hint, I converted candidates and tokens through LinSrgb → Xyz → Lab(D65) and used Ciede2000::difference for ΔE00. Math runs on f32 to keep the conversion path light.

Backdrop fallback. resolve_backdrop walks parent_dom_order until it finds an ancestor with background-color and alpha == 1.0. If the walk never finds one (or hits the root), the rule defaults to CssColor { r: 1.0, g: 1.0, b: 1.0, a: 1.0 } — the User Agent default. The walk starts at start.parent, never the start node, since the start node's own color is what's being judged.

Compositing. Standard "source over" Porter–Duff in linear-light sRGB. The ancestor walk guarantees the destination has alpha == 1.0, so the simplified out = src.a * src + (1 - src.a) * dst form is correct.

🤖 Generated with Claude Code

[github-actions]

I have a complete picture. Here is the full review.

---

Review: feat(core): rule color/palette-conformance + fix(core): downgrade color/palette violation confidence on translucent sources

Files reviewed: crates/plumb-core/src/rules/color/{mod,palette_conformance}.rs, crates/plumb-core/src/rules/{mod,util}.rs, crates/plumb-core/tests/golden_color_palette_conformance.rs, crates/plumb-core/tests/snapshots/…snap, docs/src/rules/color-palette-conformance.md

---

1. Determinism — ✅ Clean

• No SystemTime, Instant, or rand anywhere in the production path.
• metadata fields are inserted into IndexMap in the same hard-coded order every call; serialization is deterministic.
• COLOR_PROPERTIES (color/mod.rs:20–27) is alphabetically sorted — within-node emission order is deterministic and that order is preserved by the engine's stable sort on (rule_id, viewport, selector, dom_order).
• nearest_palette_entry uses strict < and comment-documents the first-seen tie-winner policy (palette_conformance.rs:194), which is deterministic given IndexMap's insertion-order guarantee on config.color.tokens.
• delta_e_metadata rounds to 3 d.p. before serialization (palette_conformance.rs:225), eliminating float-printing churn.
• No HashMap/HashSet in any observable output path.

2. Workspace layering — ✅ Clean

• All new code lives in plumb-core. No internal cross-crate imports.
• No unsafe, no println!/eprintln!, no tracing inside check.
• palette, indexmap, serde_json were already present in plumb-core's dependency set; no new crate boundaries crossed.

3. Error handling — ✅ Clean

• All expect() hits are inside #[cfg(test)] blocks (palette_conformance.rs:339,341,347,357; util.rs:384–441). The production path has none.
• unwrap_or(input) at util.rs:111 is the non-panicking combinator — safe; strip_prefix('#') is called only after starts_with('#') is confirmed.
• delta_e_metadata(...).unwrap_or(serde_json::Value::Null) at palette_conformance.rs:121,125 is defensive and correct; the ΔE for valid in-gamut colors is always finite, making the fallback dead in practice but harmless.
• The early-return guard on tolerance.is_finite() || tolerance < 0.0 (palette_conformance.rs:63) is correct defensive design.

4. Test coverage — ✅ Solid

• Golden snapshot test covering: exact match (no violation), within-tolerance (no violation), off-palette opaque (violation), off-palette translucent-over-ancestor (violation, Confidence::Low).
• Determinism test: three consecutive runs diffed at the String level.
• Empty-palette edge case: zero violations asserted.
• util.rs unit tests cover all six hex lengths, rgb()/rgba() with commas, space-separated CSS Color 4 form, percentage channels, transparent, and malformed inputs.
• palette_conformance.rs unit tests cover build_palette skip-unparseable, nearest_palette_entry minimum-delta, and three composite_over invariants.

5. Documentation — ✅ Clean

• Full docs/src/rules/color-palette-conformance.md with status, severity, behavior description, example violation JSON, configuration TOML, suppression guidance, and "See also" cross-links.
• RFC 2119 MUST/SHOULD used correctly for normative statements.
• No AI-tell phrasing ("dive in", "seamless", "leverage", etc.) detected.
• doc_url wired correctly at palette_conformance.rs:141.
• All pub(crate) items in util.rs have field-level doc comments.

---

Punch list (non-blocking warnings)

palette_conformance.rs:238–243 — node_by_dom_order is O(n) per call

fn node_by_dom_order(snapshot: &PlumbSnapshot, dom_order: u64) -> Option<&SnapshotNode> {
    snapshot.nodes.iter().find(|n| n.dom_order == dom_order)
}

resolve_backdrop calls this inside a while loop that climbs the ancestor chain, once per translucent node. Worst-case complexity is O(nodes × ancestor_depth) per rule invocation. A pre-built IndexMap<u64, usize> (dom_order → vec index), built alongside parent_index on line 77, would drop this to O(1) per hop. Not a blocker at current snapshot sizes, but a real cliff for large pages with many translucent layers.

util.rs:156 — Vec allocation in parse_rgb_functional hot path

let parts: Vec<&str> = if inner.contains(',') { ... } else { ... };

Called for every color property of every node. A fixed [&str; 4] with a manual split loop avoids the heap allocation. Minor at current call volumes; note for future optimization.

---

Verdict: APPROVE