Files
craft-libs/crates/theme/src/explain.rs
T
aiongg e89d434cc1 framework-01-w2: net change of 7 commits
- framework-01-w2: repair 1
- framework-01-w2: RowStyle and ShapeTokens::rows go (size.rs, lib.rs rows of the sheet)
- framework-01-w2: list rows: option rows rounded, others square; layer rules in every theme (show.rs row of the sheet)
- framework-01-w2: review fixes (review-1)
- framework-01-w2: review fixes (review-1, files the rulings name)
- framework-01-w2: the escaped-sweep trial follows the sweep rule: only the eyes it switched are restored (fw01 round 2)
- framework-01-w2: a drop past the last item in reading order lands at the end, in every layout (fwcw round 3)
2026-11-15 04:46:05 +00:00

262 lines
12 KiB
Rust

//! Why each colour has its value: the steps of [`resolve`] for one theme and appearance, with
//! every contrast pair the rules measure. The gallery's token browser shows them.
use super::app_sizes::{AppSizes, SizeValue, base_path};
use super::color::Rgba;
use super::derive::{Anchoring, ContrastCheck, PassMove, Ramps};
use super::resolve::{self, Resolved};
use super::sizes::{Preset, Slot, leaves};
use super::theme::{Appearance, PinLayer, Size, ThemeDef};
use super::tokens::{ColorToken, StatusKind};
use super::values::{self, ColorSource};
use crate::AppId;
/// The steps of [`crate::resolve()`] for one theme and appearance.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct Explained {
/// Equal to `resolve(theme, appearance, app)`.
pub resolved: Resolved,
/// The ramps of the mode used ([`Resolved::variant_used`]).
pub ramps: Ramps,
/// One per [`ColorToken::ALL`], in that order.
pub colors: Vec<ColorOrigin>,
/// Every pair the contrast rules measure, failing or not, in rule order.
pub pairs: Vec<PairReport>,
/// The base size, spacing, radius and type values in the order of a size set file.
pub sizes: Vec<SizeOrigin>,
}
/// Which layer of the size model set a value.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SizeLayer {
/// A base value from the size set.
SizeSet,
/// A base value the app overrides.
App,
}
impl SizeLayer {
/// Whether the app layer set the value.
pub fn from_app(self) -> bool {
self == SizeLayer::App
}
}
/// How a size, spacing, radius or type value got its value.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct SizeOrigin {
/// The path an app's `sizes.json` names it by, such as `size.control.md`.
pub path: String,
/// The layer that set it.
pub layer: SizeLayer,
/// The final value, after the theme's shape and Text size.
pub value: SizeValue,
/// The least and greatest number an app may set.
pub range: (f32, f32),
}
/// How a colour token got its value.
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub struct ColorOrigin {
/// The token.
pub token: ColorToken,
/// Its derivation rule in the mode used.
pub source: ColorSource,
/// The value `source` gives without this token's pin, before the contrast pass. A token
/// defined by other tokens takes their pinned values when it is not pinned itself, so the
/// value explains what it shows, and their unpinned values when it is.
pub derived: Rgba,
/// The layer whose pin the token takes, if it is pinned.
pub pin: Option<PinLayer>,
/// The value before the contrast pass, when the pass changed it. Tokens defined by other
/// tokens count as changed when they follow a token the pass moved.
pub contrast_move: Option<Rgba>,
/// For an anchored token ([`Anchored`](ColorSource::Anchored),
/// [`StateVariant`](ColorSource::StateVariant)), what it keeps its curve distance from.
pub anchoring: Option<Anchoring>,
/// How the contrast pass last moved the token as a background, which set its final value;
/// `contrast_move` then holds the value before the pass.
pub pass_move: Option<PassMove>,
/// The final value.
pub value: Rgba,
}
impl ColorOrigin {
/// The derivation rule in words, with the contrast pass's move when there is one: "neutral
/// 4, anchored on surface.panel, pulled toward it for text.muted".
pub fn source_words(&self) -> String {
let rule = source_words(self.source, self.anchoring.map(|a| a.on));
match self.pass_move {
Some(PassMove::Pulled(fg)) => format!("{rule}, pulled toward it for {}", fg.path()),
Some(PassMove::Relaxed(fg)) => format!("{rule}, moved away from {} for high contrast", fg.path()),
Some(PassMove::Solid(fg)) => format!("{rule}, moved away from {}", fg.path()),
None => rule,
}
}
}
/// A derivation rule in words, e.g. "neutral 10", "neutral 4, anchored on surface.panel" or
/// "accent 9 → 10 at 0.5". `anchored_on` names what an anchored token keeps its distance from.
fn source_words(source: ColorSource, anchored_on: Option<ColorToken>) -> String {
let status = |kind: StatusKind| match kind {
StatusKind::Good => "good",
StatusKind::Warn => "warn",
StatusKind::Bad => "bad",
StatusKind::Info => "info",
};
match source {
ColorSource::Neutral(n) => format!("neutral {n}"),
ColorSource::Anchored(n) => format!("neutral {n}, anchored on {}", anchored_on.unwrap_or(ColorToken::SurfacePanel).path()),
ColorSource::StateVariant { base, step } => match anchored_on {
Some(on) => format!("neutral {step}, anchored on {}", on.path()),
None => format!("neutral {step}, anchored on {} when pinned, else {}", base.path(), ColorToken::SurfacePanel.path()),
},
ColorSource::Lighting(amount) if amount >= 0.0 => format!("{} lit by {amount}", ColorToken::SurfacePanel.path()),
ColorSource::Lighting(amount) => format!("{} shaded by {}", ColorToken::SurfacePanel.path(), -amount),
ColorSource::NeutralAlpha(n, a) => format!("neutral {n} at alpha {a}"),
ColorSource::Faded(t, a) => format!("= {} at alpha {a}", t.path()),
ColorSource::Accent(n) => format!("accent {n}"),
ColorSource::AccentMix { from, to, t } => format!("accent {from} → {to} at {t}"),
ColorSource::Status(kind, n) => format!("status {} {n}", status(kind)),
ColorSource::StatusMix { kind, from, to, t } => format!("status {} {from} → {to} at {t}", status(kind)),
ColorSource::Fixed(c) => format!("fixed {}", c.to_hex()),
ColorSource::Oklch(l, c, h) => format!("oklch {l} {c} {h}"),
ColorSource::Same(t) | ColorSource::SolidFrom(t) => format!("= {}", t.path()),
ColorSource::ShiftedFrom { base, from, to, away_from } => {
format!("= {} moved away from {} as far as {} lies from {}", base.path(), away_from.path(), to.path(), from.path())
}
ColorSource::OnSolid([only]) => format!("white or black on {}", only.path()),
ColorSource::OnSolid(solids) => match solids.first() {
Some(first) => format!("white or black on {} and {} more solids", first.path(), solids.len() - 1),
None => "white or black".to_owned(),
},
}
}
/// One measured contrast pair. Translucent backgrounds are measured over `surface.panel`;
/// pairs on `overlay.halo` report the lower of the ratios over black and over white.
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub struct PairReport {
/// The pair on the final colours.
pub pair: ContrastCheck,
/// The ratio before any contrast pass.
pub ratio_before: f64,
/// Whether the contrast pass moved the foreground or the background.
pub moved_by_pass: bool,
/// Whether the pair failed before the passes and passes after them.
pub fixed_by_pass: bool,
}
impl PairReport {
/// Whether `token` is this pair's foreground or background.
pub fn involves(&self, token: ColorToken) -> bool {
self.pair.fg == token || self.pair.bg == token
}
}
impl Explained {
/// The origin of `token`.
pub fn color(&self, token: ColorToken) -> Option<&ColorOrigin> {
self.colors.iter().find(|o| o.token == token)
}
/// Every pair `token` takes part in, as foreground or background.
pub fn pairs_of(&self, token: ColorToken) -> impl Iterator<Item = &PairReport> + '_ {
self.pairs.iter().filter(move |p| p.involves(token))
}
}
/// Resolves `theme` for `appearance` as [`crate::resolve()`] does, and reports how every colour got its
/// value and every contrast pair the rules measure.
pub fn explain(theme: &ThemeDef, appearance: Appearance, app: Option<&AppId>) -> Explained {
explain_sized(theme, appearance, app, &AppSizes::default())
}
/// [`explain`] for the app's size overrides, as [`resolve_sized`](crate::resolve_sized) applies
/// them: `resolved` equals `resolve_sized(theme, appearance, app, sizes)`, and `sizes` reports the
/// layer of every size value.
pub fn explain_sized(theme: &ThemeDef, appearance: Appearance, app: Option<&AppId>, sizes: &AppSizes) -> Explained {
let (resolved, steps) = resolve::resolve_with_steps(theme, appearance, app, sizes);
let mode = resolved.variant_used;
let final_colors = &resolved.tokens.color;
let changed = |before: Rgba, after: Rgba| (before != after).then_some(before);
let colors: Vec<ColorOrigin> = ColorToken::ALL
.iter()
.map(|&token| {
let value = final_colors.get(token);
ColorOrigin {
token,
source: values::source(token, mode),
derived: steps.color.derived.get(token),
pin: steps.color.pins.get(&token).copied(),
contrast_move: changed(steps.color.before_pass.get(token), value),
anchoring: steps.color.anchors.get(&token).copied(),
pass_move: steps.color.moves.get(&token).copied(),
value,
}
})
.collect();
let moved = |t: ColorToken| colors.iter().any(|o| o.token == t && o.contrast_move.is_some());
let before: Vec<&ContrastCheck> = steps.color.pairs_before.iter().collect();
let report = |pair: &ContrastCheck| {
let ratio_before = before.iter().find(|b| b.fg == pair.fg && b.bg == pair.bg).map_or(pair.ratio, |b| b.ratio);
PairReport {
pair: *pair,
ratio_before,
moved_by_pass: moved(pair.fg) || moved(pair.bg),
fixed_by_pass: ratio_before < pair.minimum && pair.passes(),
}
};
let mut pairs: Vec<PairReport> = steps.color.pairs.iter().map(report).collect();
// The variant table's own fill and ink pairs are measured, not derived: no colour moves for them, and a
// shortfall is a finding about the theme.
for (fg, bg) in crate::variant::variant_pairs() {
if pairs.iter().any(|p| p.pair.fg == fg && p.pair.bg == bg) {
continue;
}
let ratio = crate::contrast::contrast_ratio(final_colors.get(fg), final_colors.get(bg));
let minimum = match appearance.contrast {
crate::Contrast::Standard => values::TEXT_MIN.0,
crate::Contrast::High => values::TEXT_MIN.1,
};
pairs.push(PairReport { pair: ContrastCheck { fg, bg, ratio, minimum }, ratio_before: ratio, moved_by_pass: false, fixed_by_pass: false });
}
let sizes = size_origins(&resolved, appearance.size, sizes);
Explained { resolved, ramps: steps.color.ramps, colors, pairs, sizes }
}
/// The layer of every base value in `resolved`.
fn size_origins(resolved: &Resolved, size: Size, app: &AppSizes) -> Vec<SizeOrigin> {
let merged = app.merged(size);
let tokens = &resolved.tokens;
let mut base = Preset {
size: tokens.size,
space: tokens.space,
radius: tokens.shape.radius,
edge: tokens.shape.edge,
stroke: tokens.stroke,
typography: tokens.typography,
};
let mut out = Vec::new();
for leaf in leaves(&mut base) {
let Some(path) = leaf.path.strip_prefix("base.").filter(|p| base_path(p)) else { continue };
let value = match leaf.slot {
Slot::Num(x) | Slot::Length(x) => SizeValue::Number(*x),
_ => continue,
};
// A theme's own corner radii win over the app's, so an override that did not take is the set's.
let set_by_app = merged.get(path).is_some_and(|o| !path.starts_with("radius.") || *o == value);
let layer = if set_by_app { SizeLayer::App } else { SizeLayer::SizeSet };
out.push(SizeOrigin { path: path.to_owned(), layer, value, range: (leaf.lo, leaf.hi) });
}
out
}