The design language that makes your AI harness better at design.
JavaScript
//! The browser engines' reading of [`DecorativeTextFacts`] off the `Dom`
//! probe. The decision is [`classify_decorative_text`]; this only measures.
use crate::checks::decorative_text::{
avatar_sized, centred_in, classify_decorative_text, is_mockup_marker, is_signature_marker,
is_wordmark_size, DecorativeShape, DecorativeTextFacts, MOCKUP_MARKER_SKIP_TAGS, WORDMARK_H1_PATH_MIN_PX, WORDMARK_MAX_OPACITY,
WORDMARK_MIN_PX,
};
use super::dom::{class_attr, closest_or_none, pf0, tag_lower, Dom, ElId};
use crate::color::{parse_any_color, parse_rgb, Rgba};
use crate::js;
fn parse_rgb_or_any(value: &str) -> Option<Rgba> {
parse_rgb(Some(value)).or_else(|| parse_any_color(Some(value)))
}
/// Controls whose whole text is their label.
const CONTROL_SELECTOR: &str = "a, button, label, summary, select, option, [role=\"button\"], [role=\"link\"], [role=\"tab\"], [role=\"menuitem\"], [role=\"option\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"switch\"]";
const HEADING_SELECTOR: &str = "h1, h2, h3, h4, h5, h6, [role=\"heading\"]";
fn collapsed_text(dom: &dyn Dom, el: ElId) -> String {
js::trim(&dom.text_content(el))
.split_whitespace()
.collect::<Vec<_>>()
.join(" ")
}
/// Whether a box paints something a letter could sit on: a fill, an image,
/// a visible border, or (for an `svg`) its own shapes.
fn box_paints(dom: &dyn Dom, el: ElId) -> bool {
if tag_lower(dom, el) == "svg" {
return true;
}
let fill = parse_rgb_or_any(&dom.style(el, "backgroundColor"));
if fill.is_some_and(|c| c.alpha_or_one() > 0.1) {
return true;
}
let image = dom.style(el, "backgroundImage");
if !image.is_empty() && image != "none" {
return true;
}
["Top", "Right", "Bottom", "Left"].iter().all(|side| {
pf0(&dom.style(el, &format!("border{side}Width"))) > 0.0
&& parse_rgb_or_any(&dom.style(el, &format!("border{side}Color")))
.is_some_and(|c| c.alpha_or_one() > 0.1)
})
}
/// The element, or its parent or grandparent, as a small painted box that
/// holds only this text, with the text centred in it.
fn in_avatar_box(dom: &dyn Dom, el: ElId, text: &str) -> bool {
let own = dom.direct_text_rect(el).unwrap_or_else(|| dom.rect(el));
let text_box = (own.left, own.top, own.width, own.height);
let mut cur = Some(el);
for _ in 0..3 {
let Some(b) = cur else { break };
if collapsed_text(dom, b) != text {
break;
}
let r = dom.rect(b);
if avatar_sized(r.width, r.height)
&& box_paints(dom, b)
&& centred_in(text_box, (r.left, r.top, r.width, r.height))
{
return true;
}
cur = dom.parent(b);
}
false
}
/// `(picture, marked)`: an HTML ancestor is `role="img"`, or an ancestor's
/// class or id names a mockup. A `figcaption` on the way up ends both.
fn marked_mockup(dom: &dyn Dom, el: ElId) -> (bool, bool) {
// `role="img"` names an HTML subtree drawn as a picture. On an `svg` (or
// inside one) it is how a chart, a logo or an icon is labelled, and a
// chart's axis labels are read, so it says nothing there.
let mut in_svg = closest_or_none(dom, el, "svg").is_some();
let mut cur = Some(el);
while let Some(c) = cur {
let tag = tag_lower(dom, c);
if tag == "figcaption" {
return (false, false);
}
if !in_svg && dom.attr(c, "role").is_some_and(|r| js::trim(&r).eq_ignore_ascii_case("img")) {
return (true, false);
}
if tag == "svg" {
in_svg = false;
}
if !MOCKUP_MARKER_SKIP_TAGS.contains(&tag.as_str())
&& (is_mockup_marker(&class_attr(dom, c))
|| is_mockup_marker(&dom.attr(c, "id").unwrap_or_default()))
{
return (false, true);
}
cur = dom.parent(c);
}
(false, false)
}
/// Whether a box sits in a drawn product mockup: under an HTML `role="img"`
/// outside any `svg`, or in or itself a framed demo by its structure (r5-p26's
/// three title-bar dots, preview caption, or scaled or tilted device frame,
/// and r8-t1's frame box with a sample caption on it or beside it).
/// `nested-cards` reports an inner box here as advisory (decision
/// r6-t3-nested-cards-mockups); `text-occlusion` asks
/// [`covered_text_in_mockup_dom`]. A mockup class or id is not read: an
/// `illustration` names a feature tile's picture as often as a mockup, and
/// r4-p17 keeps such a tile failing.
pub fn box_in_mockup_dom(dom: &dyn Dom, el: ElId) -> bool {
under_html_picture(dom, el)
|| super::text_context::in_framed_demo_dom(dom, el)
|| super::text_context::is_demo_frame_dom(dom, el)
}
/// Whether covered text sits in a drawn product mockup and is not a
/// control's: `text-occlusion` reports it as advisory (decision
/// r8-t2-occlusion-stacked-mockup). The framed-demo walk ends at a control
/// on its own; the `role="img"` path does not, so the control is asked here.
pub fn covered_text_in_mockup_dom(dom: &dyn Dom, el: ElId) -> bool {
closest_or_none(dom, el, CONTROL_SELECTOR).is_none() && box_in_mockup_dom(dom, el)
}
/// `el` or an ancestor is an HTML element marked `role="img"`, outside any
/// `svg`; a `figcaption` on the way up ends the walk, as in [`marked_mockup`].
fn under_html_picture(dom: &dyn Dom, el: ElId) -> bool {
let mut in_svg = closest_or_none(dom, el, "svg").is_some();
let mut cur = Some(el);
while let Some(c) = cur {
let tag = tag_lower(dom, c);
if tag == "figcaption" {
return false;
}
if !in_svg && dom.attr(c, "role").is_some_and(|r| js::trim(&r).eq_ignore_ascii_case("img")) {
return true;
}
if tag == "svg" {
in_svg = false;
}
cur = dom.parent(c);
}
false
}
fn marked_signature(dom: &dyn Dom, el: ElId) -> bool {
[Some(el), dom.parent(el)].into_iter().flatten().any(|c| {
is_signature_marker(&class_attr(dom, c))
|| is_signature_marker(&dom.attr(c, "id").unwrap_or_default())
})
}
/// How much of its ink `el` shows once it settles: its effective opacity as
/// the paint gates count it (a box a scroll timeline or a timed entrance
/// holds at 0 at its end frame, [`super::painted::effective_opacity_scrolled`])
/// times its colour's alpha. A heading caught mid-entrance is not a faint
/// wordmark. A colour that does not parse counts as opaque.
fn shown_opacity(dom: &dyn Dom, el: ElId) -> f64 {
let ink = parse_rgb_or_any(&dom.style(el, "color")).map_or(1.0, |c| c.alpha_or_one());
// A heading whose opacity is moving toward an end the capture cannot
// read, or that a paused loop holds part way, is not known to be faint.
super::painted::settled_opacity(dom, el).unwrap_or(1.0) * ink
}
/// The names the site goes by: its host name run together and without its
/// top-level label (`screen.movie` gives `screenmovie` and `screen`), and
/// its `og:site_name` or `application-name`. Where neither meta names it,
/// the title: whole when it has one part, and otherwise only the parts
/// between separators that the host name holds (`Incredible · AI that does
/// tasks` on incredible.ai gives `Incredible`). The other parts name a page
/// or a section (`Pricing | Acme`), and a faint display heading that
/// repeats one is not the site's wordmark.
fn site_names(dom: &dyn Dom) -> Vec<String> {
let mut names: Vec<String> = Vec::new();
let host = js::to_lower_case(&dom.hostname());
let host = host.strip_prefix("www.").unwrap_or(&host);
let labels: Vec<&str> = host.split('.').filter(|l| !l.is_empty()).collect();
if !labels.is_empty() {
names.push(labels.concat());
if labels.len() > 1 {
names.push(labels[..labels.len() - 1].concat());
}
}
let mut declared = false;
for selector in ["meta[property=\"og:site_name\"]", "meta[name=\"application-name\"]"] {
for meta in dom.query_all(None, selector).unwrap_or_default() {
if let Some(content) = dom.attr(meta, "content").filter(|c| !js::trim(c).is_empty()) {
names.push(content);
declared = true;
}
}
}
if declared {
return names;
}
if let Some(title) = dom.query_one(None, "title").ok().flatten() {
let title = collapsed_text(dom, title);
// A hyphen joins words (`e-commerce`) and separates nothing here.
let parts: Vec<String> = title
.split(['|', '·', '•', '—', '–', ':'])
.map(|part| js::trim(part).to_string())
.filter(|part| !part.is_empty())
.collect();
if parts.len() > 1 {
let run = |text: &str| -> String {
text.chars().filter(|c| c.is_alphanumeric()).flat_map(char::to_lowercase).collect()
};
// The host read the same way, without its top-level label:
// `get-acme-studio.com` holds `Acme Studio`, and a part that only
// repeats the TLD (`Studio` on acme.studio) names nothing.
let site_labels = if labels.len() > 1 { &labels[..labels.len() - 1] } else { &labels[..] };
let host_run = run(&site_labels.concat());
for part in parts {
let joined = run(&part);
if joined.chars().count() >= 3 && host_run.contains(&joined) {
names.push(part);
}
}
} else {
names.push(title);
}
}
names
}
/// What the `Dom` says about one element's text.
pub fn decorative_text_facts_dom(dom: &dyn Dom, el: ElId) -> DecorativeTextFacts {
let text = collapsed_text(dom, el);
let control = closest_or_none(dom, el, CONTROL_SELECTOR);
let control_label = control.is_some_and(|c| collapsed_text(dom, c) == text);
let (picture_ancestor, mockup_ancestor) = marked_mockup(dom, el);
let font_size_px = pf0(&dom.style(el, "fontSize"));
// The page's `h1` sizes decide only type between the h1 path's floor and
// the plain display floor; the walk over the page is skipped for the
// rest, which is nearly every text the checks ask about.
let largest_h1_px = if (WORDMARK_H1_PATH_MIN_PX..WORDMARK_MIN_PX).contains(&font_size_px) {
dom.query_all(None, "h1")
.unwrap_or_default()
.into_iter()
.map(|h| pf0(&dom.style(h, "fontSize")))
.fold(0.0, f64::max)
} else {
0.0
};
let display = is_wordmark_size(font_size_px, largest_h1_px);
let shown_opacity = if display { shown_opacity(dom, el) } else { 1.0 };
let site_names = if display && shown_opacity <= WORDMARK_MAX_OPACITY {
site_names(dom)
} else {
Vec::new()
};
DecorativeTextFacts {
font_size_px,
largest_h1_px,
shown_opacity,
site_names,
avatar_box: !text.is_empty() && text.chars().count() <= 3 && in_avatar_box(dom, el, &text),
in_kbd: closest_or_none(dom, el, "kbd").is_some(),
font_family: dom.style(el, "fontFamily"),
in_heading: closest_or_none(dom, el, HEADING_SELECTOR).is_some(),
control_label,
in_control: control.is_some(),
signature_marked: marked_signature(dom, el),
mockup_ancestor,
picture_ancestor,
framed_demo: super::text_context::in_framed_demo_dom(dom, el),
text,
}
}
/// The decorative shape one element's text has, if any.
pub fn decorative_text_shape_dom(dom: &dyn Dom, el: ElId) -> Option<DecorativeShape> {
classify_decorative_text(&decorative_text_facts_dom(dom, el))
}
/// Whether one element's text has no reading job.
pub fn is_decorative_text_dom(dom: &dyn Dom, el: ElId) -> bool {
decorative_text_shape_dom(dom, el).is_some()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::browser::fake_dom::FakeDom;
#[test]
fn avatar_initial_in_a_round_tile() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let tile = d.add(Some(body), "span");
d.add_text(tile, "JD");
d.set_styles(tile, &[("backgroundColor", "rgb(19, 130, 232)"), ("fontFamily", "Inter")]);
d.set_rect(tile, 0.0, 0.0, 40.0, 40.0);
assert_eq!(decorative_text_shape_dom(&d, tile), Some(DecorativeShape::AvatarInitials));
// The same letters as a link's whole label are the control's name.
let mut d2 = FakeDom::new();
let (_h, body) = d2.with_page();
let a = d2.add(Some(body), "a");
let tile = d2.add(Some(a), "span");
d2.add_text(tile, "JD");
d2.set_styles(tile, &[("backgroundColor", "rgb(19, 130, 232)")]);
d2.set_rect(tile, 0.0, 0.0, 40.0, 40.0);
assert_eq!(decorative_text_shape_dom(&d2, tile), None);
}
/// The page's `h1` sizes are read only for type the h1 path can decide:
/// body text and plain display type skip the walk over the page.
#[test]
fn the_h1_walk_runs_only_where_it_decides() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let h1 = d.add(Some(body), "h1");
d.add_text(h1, "Title");
d.set_style(h1, "fontSize", "30px");
let p = d.add(Some(body), "p");
d.add_text(p, "Body copy");
for (size, h1_read) in [("14px", 0.0), ("96px", 30.0), ("160px", 0.0)] {
d.set_style(p, "fontSize", size);
assert_eq!(decorative_text_facts_dom(&d, p).largest_h1_px, h1_read, "{size}");
}
}
/// incredible.one (10048155): `span.br-footer-monogram`, "Incredible" at
/// 272px in `rgba(0, 0, 0, 0.07)`, the site's `og:site_name`.
#[test]
fn a_faint_footer_wordmark_is_decorative() {
let mut d = FakeDom::new();
let (html, body) = d.with_page();
d.hostname = "www.incredible.one".into();
let head = d.add(Some(html), "head");
let title = d.add(Some(head), "title");
d.add_text(title, "Incredible · AI that does tasks on your computer");
let h1 = d.add(Some(body), "h1");
d.add_text(h1, "Do more with less");
d.set_style(h1, "fontSize", "64px");
let footer = d.add(Some(body), "footer");
let mark = d.add(Some(footer), "span");
d.add_text(mark, "Incredible");
d.set_styles(mark, &[("fontSize", "272.102px"), ("color", "rgba(0, 0, 0, 0.07)")]);
d.set_rect(mark, 42.0, 10411.0, 1173.0, 201.0);
assert_eq!(decorative_text_shape_dom(&d, mark), Some(DecorativeShape::Wordmark));
// The same name in ink a reader is meant to read is not.
d.set_style(mark, "color", "rgba(0, 0, 0, 0.6)");
assert_eq!(decorative_text_shape_dom(&d, mark), None);
// Faded by its box rather than its colour, it is.
d.set_style(mark, "color", "rgb(255, 255, 255)");
d.set_style(footer, "opacity", "0.1");
assert_eq!(decorative_text_shape_dom(&d, mark), Some(DecorativeShape::Wordmark));
// Caught at 0 by a timed entrance that settles at 1, it is the name
// in full ink, not a faint wordmark.
d.keyframes.insert(
"reveal".into(),
vec![
crate::browser::dom::KeyframeFrame { decls: vec![("opacity".into(), "0".into())] },
crate::browser::dom::KeyframeFrame { decls: vec![("opacity".into(), "1".into())] },
],
);
d.keyframe_keys.insert("reveal".into(), vec!["0%".into(), "100%".into()]);
d.set_styles(
footer,
&[
("opacity", "0"),
("animationName", "reveal"),
("animationIterationCount", "1"),
("animationFillMode", "forwards"),
("animationDirection", "normal"),
("animationDuration", "0.6s"),
("animationDelay", "1s"),
("animationTimeline", "auto"),
("animationPlayState", "running"),
("animationComposition", "replace"),
],
);
d.set_running_animations(footer, &["opacity"]);
assert_eq!(decorative_text_shape_dom(&d, mark), None);
// Review of #1044: caught at 0.2 part way through the same fade, it
// settles at 1 and is not a wordmark either.
d.set_style(footer, "opacity", "0.2");
assert_eq!(decorative_text_shape_dom(&d, mark), None);
// An opacity transition running, whose end the capture cannot read,
// leaves where it settles unknown: not a wordmark.
d.set_styles(footer, &[("animationName", "none"), ("transitionProperty", "opacity"), ("transitionDuration", "0.6s")]);
assert_eq!(decorative_text_shape_dom(&d, mark), None);
// The same footer at 0.2 with nothing moving it is a faint wordmark.
d.set_running_animations(footer, &[]);
assert_eq!(decorative_text_shape_dom(&d, mark), Some(DecorativeShape::Wordmark));
d.set_styles(footer, &[("animationName", "reveal"), ("opacity", "0"), ("transitionProperty", "all"), ("transitionDuration", "0s")]);
d.set_running_animations(footer, &["opacity"]);
// A section name in the middle of a title is not the site's name,
// and a hyphen separates nothing.
d.add_text(title, " | Blog | Latest");
let blog = d.add(Some(footer), "span");
d.add_text(blog, "Blog");
d.set_styles(blog, &[("fontSize", "272.102px"), ("color", "rgb(255, 255, 255)")]);
assert_eq!(decorative_text_shape_dom(&d, blog), None);
// Another word at the same size and opacity is not the site's name.
let other = d.add(Some(footer), "span");
d.add_text(other, "Tasks");
d.set_styles(other, &[("fontSize", "272.102px"), ("color", "rgb(255, 255, 255)")]);
assert_eq!(decorative_text_shape_dom(&d, other), None);
}
/// #1076: a faint display heading that repeats the page's part of the
/// title (a 120px "Pricing" on "Pricing | Acme") is a page name, not
/// the site's wordmark. Only the part the host name or an explicit
/// site name corroborates names the site.
#[test]
fn a_title_part_names_the_site_only_where_something_backs_it() {
let build = |host: &str, site_name: Option<&str>, title_text: &str, text: &str| {
let mut d = FakeDom::new();
let (html, body) = d.with_page();
d.hostname = host.into();
let head = d.add(Some(html), "head");
let title = d.add(Some(head), "title");
d.add_text(title, title_text);
if let Some(name) = site_name {
let meta = d.add(Some(head), "meta");
d.add_selector(meta, "meta[property=\"og:site_name\"]");
d.set_attr(meta, "property", "og:site_name");
d.set_attr(meta, "content", name);
}
let mark = d.add(Some(body), "span");
d.add_text(mark, text);
d.set_styles(mark, &[("fontSize", "160px"), ("color", "rgba(0, 0, 0, 0.1)")]);
d.set_rect(mark, 0.0, 400.0, 900.0, 160.0);
decorative_text_shape_dom(&d, mark)
};
let wordmark = Some(DecorativeShape::Wordmark);
assert_eq!(build("", None, "Pricing | Acme", "Pricing"), None);
assert_eq!(build("", None, "Pricing | Acme", "Acme"), None, "nothing backs either part");
assert_eq!(build("getacme.io", None, "Pricing | Acme", "Acme"), wordmark);
assert_eq!(build("getacme.io", None, "Pricing | Acme", "Pricing"), None);
assert_eq!(build("get-acme-studio.com", None, "Pricing | Acme Studio", "Acme Studio"), wordmark);
assert_eq!(build("acme.studio", None, "Pricing | Studio", "Studio"), None);
assert_eq!(build("www.acme.io", None, "Acme | io", "io"), None);
assert_eq!(build("www.acme.io", None, "Acme | io", "Acme"), wordmark);
assert_eq!(build("", Some("Acme"), "Pricing | Acme", "Acme"), wordmark);
assert_eq!(build("", Some("Acme"), "Pricing | Acme", "Pricing"), None);
// A title of one part is the site's name, opened word for word.
assert_eq!(build("", None, "Screen Movie Blog", "Screen Movie"), wordmark);
}
#[test]
fn a_key_or_an_info_badge_is_not_initials() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let p = d.add(Some(body), "p");
let key = d.add(Some(p), "kbd");
d.add_text(key, "K");
d.set_styles(key, &[("backgroundColor", "rgb(246, 246, 246)")]);
d.set_rect(key, 0.0, 0.0, 20.0, 20.0);
assert_eq!(decorative_text_shape_dom(&d, key), None);
let info = d.add(Some(body), "span");
d.add_text(info, "i");
d.set_styles(info, &[("backgroundColor", "rgb(242, 242, 242)")]);
d.set_rect(info, 0.0, 40.0, 16.0, 16.0);
assert_eq!(decorative_text_shape_dom(&d, info), None);
// A brand's lower-case letter in a chat avatar is an avatar.
let brand = d.add(Some(body), "span");
d.add_text(brand, "r");
d.set_styles(brand, &[("backgroundColor", "rgb(19, 130, 232)")]);
d.set_rect(brand, 0.0, 80.0, 28.0, 28.0);
assert_eq!(decorative_text_shape_dom(&d, brand), Some(DecorativeShape::AvatarInitials));
}
#[test]
fn a_letter_in_an_unpainted_or_wide_box_is_text() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let bare = d.add(Some(body), "span");
d.add_text(bare, "A");
d.set_rect(bare, 0.0, 0.0, 40.0, 40.0);
assert_eq!(decorative_text_shape_dom(&d, bare), None);
let wide = d.add(Some(body), "span");
d.add_text(wide, "A");
d.set_styles(wide, &[("backgroundColor", "rgb(0, 0, 0)")]);
d.set_rect(wide, 0.0, 0.0, 120.0, 40.0);
assert_eq!(decorative_text_shape_dom(&d, wide), None);
}
#[test]
fn mockup_marker_reaches_through_ancestors_but_not_sections() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let frame = d.add(Some(body), "div");
d.set_attr(frame, "class", "hero-mockup");
let row = d.add(Some(frame), "div");
let label = d.add(Some(row), "span");
d.add_text(label, "Ready");
assert_eq!(decorative_text_shape_dom(&d, label), Some(DecorativeShape::Mockup));
let sec = d.add(Some(body), "section");
d.set_attr(sec, "class", "mockups");
let p = d.add(Some(sec), "p");
d.add_text(p, "Every mockup ships with source files");
assert_eq!(decorative_text_shape_dom(&d, p), None);
// A practice exam and an image credit are not pictures of a UI.
for class in ["mock-exam", "illustration-credit"] {
let wrap = d.add(Some(body), "div");
d.set_attr(wrap, "class", class);
let q = d.add(Some(wrap), "p");
d.add_text(q, "Short label");
assert_eq!(decorative_text_shape_dom(&d, q), None, "{class}");
}
}
#[test]
fn role_img_marks_html_pictures_not_svg_charts() {
let mut d = FakeDom::new();
let (_h, body) = d.with_page();
let pic = d.add(Some(body), "div");
d.set_attr(pic, "role", "img");
let code = d.add(Some(pic), "code");
d.add_text(code, "$ npm run build");
assert_eq!(decorative_text_shape_dom(&d, code), Some(DecorativeShape::Mockup));
let chart = d.add(Some(body), "svg");
d.set_attr(chart, "role", "img");
let label = d.add(Some(chart), "text");
d.add_text(label, "Nov 2022");
assert_eq!(decorative_text_shape_dom(&d, label), None);
}
}