Skip to content

The design language that makes your AI harness better at design.

JavaScript

flat-type-hierarchy declines a ladder that leaves out the page's headings

Paul Bakaus97e1939dbebb
diff --git a/crates/browser/tests/card_heuristics.rs b/crates/browser/tests/card_heuristics.rs
index 04ed537da..9dc39b2b6 100644
--- a/crates/browser/tests/card_heuristics.rs
+++ b/crates/browser/tests/card_heuristics.rs
@@ -234,6 +234,8 @@ fn undersized_ui_text_skips_links_inside_markers() {
fn page_level_misreads_stay_silent() {
for (fixture, rule) in [
("flat-type-hierarchy-h1-tie.html", "flat-type-hierarchy"),
+ ("flat-type-hierarchy-dropped-role.html", "flat-type-hierarchy"),
+ ("flat-type-hierarchy-h1-label.html", "flat-type-hierarchy"),
("oversized-h1-rendered.html", "oversized-h1"),
("first-viewport-column-overflow-outline.html", "first-viewport-column-overflow"),
("first-viewport-column-overflow-tabs.html", "first-viewport-column-overflow"),
diff --git a/crates/core/src/checks/rules.rs b/crates/core/src/checks/rules.rs
index 2b62526c5..571b5192e 100644
--- a/crates/core/src/checks/rules.rs
+++ b/crates/core/src/checks/rules.rs
@@ -1954,15 +1954,44 @@ pub fn check_flat_type_hierarchy_samples(samples: &[TypeSample]) -> Vec<RuleHit>
}
}
- let mut roles: Vec<(String, f64)> = by_role
- .into_iter()
- .filter_map(|(role, sizes)| dominant_type_role_size(&role, &sizes).map(|size| (role, size)))
- .collect();
+ // The ladder is read from the roles whose size the samples settle. When
+ // the heading level a page uses most has no dominant size (cnnbrasil.com.br
+ // sets its thirty h3s at 14, 16 and 20px, ten each), the ladder leaves
+ // out the headings a reader sees most, and what is left says nothing
+ // about the page's hierarchy.
+ let most_used_heading = by_role
+ .iter()
+ .filter(|(role, _)| role != "body")
+ .map(|(_, sizes)| sizes.len())
+ .max()
+ .unwrap_or(0);
+ let mut dropped_most_used = false;
+ let mut roles: Vec<(String, f64)> = Vec::new();
+ for (role, sizes) in by_role {
+ match dominant_type_role_size(&role, &sizes) {
+ Some(size) => roles.push((role, size)),
+ None => dropped_most_used |= role != "body" && sizes.len() == most_used_heading,
+ }
+ }
+ if dropped_most_used {
+ return Vec::new();
+ }
if roles.len() < TYPE_HIERARCHY_MIN_ROLES {
return Vec::new();
}
+ // An h1 set smaller than the body text is not the page's title but a
+ // label wearing the tag (phillips66.com's 14px "FIND FBOS:" form label
+ // over 16px copy); the page's real headline sits in some other element,
+ // and a ladder topped by the label measures nothing a reader sees.
+ let size_of = |name: &str| roles.iter().find(|(r, _)| r == name).map(|(_, size)| *size);
+ if let (Some(h1), Some(body)) = (size_of("h1"), size_of("body")) {
+ if h1 < body {
+ return Vec::new();
+ }
+ }
+
roles.sort_by(|a, b| {
a.1.partial_cmp(&b.1)
.unwrap_or(std::cmp::Ordering::Equal)
@@ -2179,6 +2208,38 @@ mod tests {
assert!(hits.is_empty() || !hits[0].snippet.contains("h3"), "{hits:?}");
}
+ /// observations-28 row 23: the ladder leaves out the headings a reader
+ /// sees. cnnbrasil.com.br sets its thirty h3 headlines at 14, 16 and 20px,
+ /// ten each, so the h3 role drops out and a 14/16/16 ladder of body, h1
+ /// and h2 reports; phillips66.com's h1 is a 14px form label over 16px
+ /// copy. Neither ladder describes the page, and neither reports.
+ #[test]
+ fn flat_type_hierarchy_declines_a_ladder_without_the_page_headings() {
+ let mut news = vec![("h1", 16.0)];
+ news.extend([("body", 14.0); 99]);
+ news.extend([("body", 16.0); 44]);
+ news.extend([("h2", 16.0); 6]);
+ news.extend([("h2", 30.0); 3]);
+ news.extend([("h3", 14.0); 10]);
+ news.extend([("h3", 16.0); 10]);
+ news.extend([("h3", 20.0); 10]);
+ assert!(check_flat_type_hierarchy_samples(&samples(&news)).is_empty(), "the h3 role drops out");
+ // With one h3 size settled, the ladder holds what a reader sees.
+ news.push(("h3", 16.0));
+ let hits = check_flat_type_hierarchy_samples(&samples(&news));
+ assert_eq!(hits.len(), 1, "{hits:?}");
+ assert!(hits[0].snippet.contains("h3 16px"), "{hits:?}");
+
+ let mut label = vec![("h1", 14.0)];
+ label.extend([("body", 16.0); 26]);
+ label.extend([("body", 15.0); 15]);
+ label.extend([("h2", 15.0); 3]);
+ assert!(check_flat_type_hierarchy_samples(&samples(&label)).is_empty(), "h1 under body size");
+ // An h1 at the body size still counts.
+ label[0] = ("h1", 16.0);
+ assert_eq!(check_flat_type_hierarchy_samples(&samples(&label)).len(), 1);
+ }
+
#[test]
fn a_provisional_claim_gives_way_to_a_copy_on_screen() {
let hit = || RuleHit::new("low-contrast", "2.2:1 (need 4.5:1) — text #c9a3c8 on #ffffff".to_string());
diff --git a/tests/fixtures/antipatterns/flat-type-hierarchy-dropped-role.html b/tests/fixtures/antipatterns/flat-type-hierarchy-dropped-role.html
new file mode 100644
index 000000000..c29c83811
--- /dev/null
+++ b/tests/fixtures/antipatterns/flat-type-hierarchy-dropped-role.html
@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Flat type hierarchy, the main heading level at three sizes</title>
+<!--
+ Should pass. A news front sets its h3 headlines, the heading level it uses
+ most, at three sizes equally often: 14px in a ticker, 16px in a list, 20px
+ on the lead cards (cnnbrasil.com.br). No h3 size is dominant, so the role
+ drops out of the ladder, and the ladder left (body 14px, h1 16px, h2 16px)
+ leaves out the headlines a reader sees. It says nothing about the page, and
+ the rule declines rather than report it. flat-type-hierarchy.html is the
+ twin that still reports.
+-->
+<style>
+ body { margin: 0; padding: 24px; font-family: system-ui, sans-serif; background: #ffffff; color: #111111; }
+ p { font-size: 14px; line-height: 1.5; }
+ h1 { font-size: 16px; font-weight: 400; }
+ h2 { font-size: 16px; }
+ .ticker { font-size: 14px; font-weight: 400; }
+ .list { font-size: 16px; }
+ .lead { font-size: 20px; }
+</style>
+</head>
+<body>
+ <h1>CNN front page</h1>
+ <h2>Politics</h2>
+ <h3 class="lead">The court opens the way for a vote on the case</h3>
+ <p>A short standfirst under the lead headline.</p>
+ <h3 class="lead">The analysis: the crisis in the institutions</h3>
+ <p>A short standfirst under the second lead.</p>
+ <h3 class="lead">The president turns to the benefits agenda</h3>
+ <p>A short standfirst under the third lead.</p>
+ <h2>Latest</h2>
+ <h3 class="list">Markets close higher on the day</h3>
+ <h3 class="list">The league confirms the fixture list</h3>
+ <h3 class="list">A storm front reaches the south coast</h3>
+ <p>More stories from the newsroom through the day.</p>
+ <h2>Live</h2>
+ <h3 class="ticker">Traffic slows on the ring road</h3>
+ <h3 class="ticker">The central bank holds its rate</h3>
+ <h3 class="ticker">Tickets go on sale for the final</h3>
+ <p>Updates from the live desk every few minutes.</p>
+</body>
+</html>
diff --git a/tests/fixtures/antipatterns/flat-type-hierarchy-h1-label.html b/tests/fixtures/antipatterns/flat-type-hierarchy-h1-label.html
new file mode 100644
index 000000000..0b2f544bd
--- /dev/null
+++ b/tests/fixtures/antipatterns/flat-type-hierarchy-h1-label.html
@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Flat type hierarchy, an h1 set as a label</title>
+<!--
+ Should pass. A map tool page puts its h1 on a 14px form label ("Find
+ FBOs:") over 16px copy, and sets its real headline, 48px, on a div
+ (phillips66.com). A ladder topped by an h1 smaller than the body text
+ measures a label, not the page's title, and the rule declines rather than
+ report it. flat-type-hierarchy.html is the twin that still reports.
+-->
+<style>
+ body { margin: 0; padding: 24px; font-family: system-ui, sans-serif; background: #ffffff; color: #111111; }
+ p { font-size: 16px; line-height: 1.5; font-weight: 300; }
+ .note { font-size: 15px; }
+ h1 { font-size: 14px; font-weight: 700; text-transform: uppercase; }
+ h2 { font-size: 15px; font-weight: 500; }
+ .headline { font-size: 48px; font-weight: 300; }
+</style>
+</head>
+<body>
+ <div class="headline">Use the search tool</div>
+ <h1>Find FBOs:</h1>
+ <p>Search by airport code, city or the name of the operator.</p>
+ <p>Results list every base with fuel, hangar and crew services.</p>
+ <p class="note">Hours and services change; call ahead to confirm.</p>
+ <h2>Company</h2>
+ <h2>Investors</h2>
+ <h2>Careers</h2>
+ <p>Links to the rest of the site sit in the footer columns.</p>
+</body>
+</html>