Buckets:
| <html lang="en"> | |
| <head> | |
| <meta charset="utf-8"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| <title>Birch HTML Rendering Checker Pipeline Explainer</title> | |
| <style data-birch-system>/* | |
| Birch HTML Design System | |
| Opinionated single-option stylesheet for reliable LLM-generated artifacts. | |
| Model: | |
| 1. Design tokens as CSS variables. | |
| 2. Layout primitives as classes. | |
| 3. Semantic components as classes with data-* variants. | |
| */ | |
| /* ==================== 1. TOKENS ==================== */ | |
| :root { | |
| color-scheme: light; | |
| /* Palette */ | |
| --color-ivory: #FAF9F5; | |
| --color-slate: #141413; | |
| --color-clay: #D97757; | |
| --color-clay-dark: #B85C3E; | |
| --color-oat: #E3DACC; | |
| --color-olive: #788C5D; | |
| --color-rust: #B04A3F; | |
| --color-sky: #6A8CAF; | |
| --color-white: #FFFFFF; | |
| --color-gray-50: #F7F5EE; | |
| --color-gray-100: #F0EEE6; | |
| --color-gray-150: #E8E4DA; | |
| --color-gray-200: #DED9CD; | |
| --color-gray-300: #D1CFC5; | |
| --color-gray-500: #87867F; | |
| --color-gray-700: #3D3D3A; | |
| --color-gray-800: #242421; | |
| /* Semantic colors */ | |
| --bg: var(--color-ivory); | |
| --surface: var(--color-white); | |
| --surface-tint: var(--color-gray-100); | |
| --surface-warm: var(--color-oat); | |
| --text: var(--color-slate); | |
| --text-muted: var(--color-gray-500); | |
| --text-soft: var(--color-gray-700); | |
| --muted: var(--text-muted); | |
| --border-color: var(--color-gray-300); | |
| --accent: var(--color-clay); | |
| --accent-strong: var(--color-clay-dark); | |
| --success: var(--color-olive); | |
| --warning: #C78E3F; | |
| --danger: var(--color-rust); | |
| --info: var(--color-sky); | |
| /* Typography */ | |
| --font-serif: ui-serif, Georgia, "Times New Roman", serif; | |
| --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; | |
| --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace; | |
| --text-xs: 11px; | |
| --text-sm: 12px; | |
| --text-md: 14px; | |
| --text-base: 15px; | |
| --text-lg: 17px; | |
| --text-xl: 21px; | |
| --text-2xl: 26px; | |
| --text-3xl: 36px; | |
| --text-4xl: 44px; | |
| --leading-tight: 1.15; | |
| --leading-title: 1.25; | |
| --leading-body: 1.55; | |
| --leading-loose: 1.7; | |
| /* Spacing */ | |
| --space-1: 4px; | |
| --space-2: 8px; | |
| --space-3: 12px; | |
| --space-4: 16px; | |
| --space-5: 24px; | |
| --space-6: 32px; | |
| --space-7: 48px; | |
| --space-8: 64px; | |
| --space-9: 96px; | |
| /* Shape */ | |
| --radius-xs: 4px; | |
| --radius-sm: 8px; | |
| --radius-md: 12px; | |
| --radius-lg: 16px; | |
| --radius-xl: 20px; | |
| --radius-pill: 999px; | |
| --border: 1.5px solid var(--border-color); | |
| --border-thin: 1px solid var(--border-color); | |
| --shadow-sm: 0 1px 2px rgba(20, 20, 19, 0.06); | |
| --shadow-md: 0 4px 14px rgba(20, 20, 19, 0.08); | |
| --shadow-lg: 0 12px 28px rgba(20, 20, 19, 0.12); | |
| /* Motion */ | |
| --ease: cubic-bezier(0.2, 0, 0, 1); | |
| --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1); | |
| --dur-fast: 120ms; | |
| --dur: 180ms; | |
| --hover-y: -2px; | |
| /* Page sizing */ | |
| --page-max: 1100px; | |
| --page-pad: 28px; | |
| --page-pad-block: 48px; | |
| /* Legacy aliases used by source examples */ | |
| --ivory: var(--color-ivory); | |
| --slate: var(--color-slate); | |
| --clay: var(--color-clay); | |
| --clay-d: var(--color-clay-dark); | |
| --oat: var(--color-oat); | |
| --olive: var(--color-olive); | |
| --rust: var(--color-rust); | |
| --sky: var(--color-sky); | |
| --white: var(--color-white); | |
| --gray-50: var(--color-gray-50); | |
| --gray-100: var(--color-gray-100); | |
| --gray-150: var(--color-gray-150); | |
| --gray-200: var(--color-gray-200); | |
| --gray-300: var(--color-gray-300); | |
| --gray-500: var(--color-gray-500); | |
| --gray-700: var(--color-gray-700); | |
| --gray-800: var(--color-gray-800); | |
| --serif: var(--font-serif); | |
| --sans: var(--font-sans); | |
| --mono: var(--font-mono); | |
| } | |
| /* ==================== BASE ==================== */ | |
| *, | |
| *::before, | |
| *::after { | |
| box-sizing: border-box; | |
| } | |
| html { | |
| background: var(--bg); | |
| color: var(--text); | |
| font-family: var(--font-sans); | |
| -webkit-text-size-adjust: 100%; | |
| } | |
| body { | |
| margin: 0; | |
| background: var(--bg); | |
| color: var(--text); | |
| font-family: var(--font-sans); | |
| font-size: var(--text-base); | |
| line-height: var(--leading-body); | |
| -webkit-font-smoothing: antialiased; | |
| text-rendering: optimizeLegibility; | |
| } | |
| img, | |
| svg { | |
| max-width: 100%; | |
| } | |
| a { | |
| color: inherit; | |
| text-decoration-color: rgba(217, 119, 87, 0.45); | |
| text-underline-offset: 3px; | |
| } | |
| a:hover { | |
| color: var(--accent); | |
| } | |
| h1, | |
| h2, | |
| h3, | |
| p { | |
| margin-block: 0; | |
| } | |
| h1, | |
| h2, | |
| h3 { | |
| font-family: var(--font-serif); | |
| font-weight: 500; | |
| letter-spacing: -0.01em; | |
| line-height: var(--leading-title); | |
| } | |
| h1 { | |
| font-size: clamp(32px, 5vw, var(--text-4xl)); | |
| } | |
| h2 { | |
| font-size: var(--text-2xl); | |
| } | |
| h3 { | |
| font-size: var(--text-xl); | |
| } | |
| code, | |
| kbd, | |
| pre { | |
| font-family: var(--font-mono); | |
| } | |
| code { | |
| font-size: 0.92em; | |
| white-space: normal; | |
| word-break: normal; | |
| } | |
| h1 code, | |
| h2 code, | |
| h3 code { | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| } | |
| button, | |
| input, | |
| textarea, | |
| select { | |
| font: inherit; | |
| } | |
| button { | |
| cursor: pointer; | |
| } | |
| ::selection { | |
| background: rgba(217, 119, 87, 0.24); | |
| } | |
| /* ==================== 2. LAYOUT PRIMITIVES ==================== */ | |
| .page { | |
| width: min(100% - (var(--page-pad) * 2), var(--page-max)); | |
| margin-inline: auto; | |
| padding-block: var(--page-pad-block) var(--space-9); | |
| } | |
| .page[data-size="narrow"] { | |
| --page-max: 820px; | |
| } | |
| .page[data-size="wide"] { | |
| --page-max: 1280px; | |
| } | |
| .page[data-size="full"] { | |
| --page-max: 1440px; | |
| } | |
| .section { | |
| margin-block: var(--section-gap, var(--space-5)); | |
| } | |
| .section[data-gap="lg"] { | |
| --section-gap: var(--space-6); | |
| } | |
| .section[data-gap="xl"] { | |
| --section-gap: var(--space-7); | |
| } | |
| .section:first-child { | |
| margin-block-start: 0; | |
| } | |
| .stack > .section { | |
| margin-block: 0; | |
| } | |
| .rule { | |
| border: 0; | |
| border-top: var(--border-thin); | |
| margin: var(--space-3) 0 var(--space-5); | |
| } | |
| .stack { | |
| display: flex; | |
| flex-direction: column; | |
| gap: var(--stack-gap, var(--space-4)); | |
| } | |
| .stack[data-gap="xs"] { --stack-gap: var(--space-2); } | |
| .stack[data-gap="sm"] { --stack-gap: var(--space-3); } | |
| .stack[data-gap="md"] { --stack-gap: var(--space-4); } | |
| .stack[data-gap="lg"] { --stack-gap: var(--space-6); } | |
| .stack[data-gap="xl"] { --stack-gap: var(--space-8); } | |
| .stack > :is(.button, .btn, .chip, .badge) { | |
| align-self: flex-start; | |
| } | |
| .cluster { | |
| display: flex; | |
| flex-wrap: wrap; | |
| align-items: center; | |
| gap: var(--cluster-gap, var(--space-3)); | |
| } | |
| .cluster[data-align="start"] { align-items: flex-start; } | |
| .cluster[data-align="end"] { align-items: flex-end; } | |
| .cluster[data-justify="between"] { justify-content: space-between; } | |
| .cluster[data-justify="end"] { justify-content: flex-end; } | |
| .grid { | |
| display: grid; | |
| gap: var(--grid-gap, var(--space-5)); | |
| } | |
| .grid[data-cols="2"] { | |
| grid-template-columns: repeat(2, minmax(0, 1fr)); | |
| } | |
| .grid[data-cols="3"] { | |
| grid-template-columns: repeat(3, minmax(0, 1fr)); | |
| } | |
| .grid[data-cols="4"] { | |
| grid-template-columns: repeat(4, minmax(0, 1fr)); | |
| } | |
| .auto-grid { | |
| display: grid; | |
| grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--grid-min, 240px)), 1fr)); | |
| gap: var(--grid-gap, var(--space-5)); | |
| } | |
| .auto-grid > * { | |
| min-width: 0; | |
| } | |
| .split { | |
| display: grid; | |
| grid-template-columns: minmax(0, 1fr) minmax(280px, var(--split-side, 360px)); | |
| gap: var(--split-gap, var(--space-6)); | |
| align-items: start; | |
| } | |
| .split > * { | |
| min-width: 0; | |
| } | |
| .section-head { | |
| min-width: 0; | |
| } | |
| .section-rail { | |
| display: grid; | |
| grid-template-columns: minmax(0, 1fr) minmax(280px, var(--rail-width, 360px)); | |
| column-gap: var(--rail-gap, var(--space-6)); | |
| row-gap: var(--space-5); | |
| align-items: start; | |
| } | |
| .section-rail > .section-head { | |
| grid-column: 1 / -1; | |
| } | |
| .section-rail > .reference-panel, | |
| .section-rail > aside { | |
| align-self: start; | |
| } | |
| .sidebar-layout { | |
| display: grid; | |
| grid-template-columns: var(--sidebar-width, 240px) minmax(0, 1fr); | |
| gap: var(--sidebar-gap, var(--space-7)); | |
| align-items: start; | |
| } | |
| .sidebar-layout > :first-child, | |
| .sticky { | |
| position: sticky; | |
| top: var(--sticky-top, var(--space-5)); | |
| } | |
| .bleed { | |
| margin-inline: calc(var(--page-pad) * -1); | |
| } | |
| .scroll-x { | |
| overflow-x: auto; | |
| overscroll-behavior-inline: contain; | |
| } | |
| .center { | |
| display: grid; | |
| place-items: center; | |
| } | |
| .spacer { | |
| flex: 1; | |
| } | |
| @media (max-width: 860px) { | |
| :root { | |
| --page-pad: 20px; | |
| --page-pad-block: 40px; | |
| } | |
| .grid[data-cols], | |
| .split, | |
| .section-rail, | |
| .sidebar-layout { | |
| grid-template-columns: 1fr; | |
| } | |
| .sidebar-layout > :first-child, | |
| .sticky { | |
| position: static; | |
| } | |
| } | |
| /* ==================== TYPOGRAPHY UTILITIES ==================== */ | |
| .eyebrow { | |
| display: inline-flex; | |
| align-items: center; | |
| gap: var(--space-2); | |
| color: var(--accent); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 700; | |
| letter-spacing: 0.08em; | |
| text-transform: uppercase; | |
| } | |
| .eyebrow::before { | |
| content: ""; | |
| width: 24px; | |
| height: 1.5px; | |
| background: currentColor; | |
| } | |
| .lede { | |
| max-width: 720px; | |
| color: var(--text-soft); | |
| font-size: var(--text-lg); | |
| line-height: 1.6; | |
| } | |
| .muted { | |
| color: var(--text-muted); | |
| } | |
| .caption { | |
| color: var(--text-muted); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| } | |
| .stat-value { | |
| display: block; | |
| color: var(--text); | |
| font-family: var(--font-serif); | |
| font-size: clamp(30px, 3.2vw, 42px); | |
| font-variant-numeric: tabular-nums; | |
| font-weight: 550; | |
| letter-spacing: -0.025em; | |
| line-height: 1; | |
| } | |
| .stat-card { | |
| gap: var(--space-2); | |
| } | |
| .stat-card .caption { | |
| letter-spacing: 0.08em; | |
| text-transform: uppercase; | |
| } | |
| .stat-card .muted { | |
| max-width: 34ch; | |
| font-size: var(--text-sm); | |
| } | |
| .mono { | |
| font-family: var(--font-mono); | |
| } | |
| /* ==================== 3. SEMANTIC COMPONENTS ==================== */ | |
| .panel, | |
| .card { | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-md); | |
| } | |
| .panel { | |
| padding: var(--panel-pad, var(--space-5)); | |
| } | |
| .card { | |
| padding: var(--card-pad, var(--space-5)); | |
| transition: | |
| transform var(--dur-fast) var(--ease), | |
| border-color var(--dur-fast) var(--ease), | |
| box-shadow var(--dur-fast) var(--ease), | |
| background-color var(--dur-fast) var(--ease); | |
| } | |
| .card[data-hover="lift"]:hover, | |
| .card[data-clickable]:hover { | |
| transform: translateY(var(--hover-y)); | |
| border-color: rgba(217, 119, 87, 0.55); | |
| box-shadow: var(--shadow-md); | |
| } | |
| .card[data-clickable] { | |
| cursor: pointer; | |
| } | |
| .card[data-variant="flat"] { | |
| background: transparent; | |
| border-color: transparent; | |
| box-shadow: none; | |
| } | |
| .card[data-variant="outlined"] { | |
| background: var(--surface); | |
| border: var(--border); | |
| } | |
| .card[data-variant="elevated"] { | |
| border-color: transparent; | |
| box-shadow: var(--shadow-md); | |
| } | |
| .card[data-variant="filled"], | |
| .card[data-tone="oat"] { | |
| background: var(--surface-warm); | |
| } | |
| .card[data-tone], | |
| .panel[data-tone], | |
| .callout[data-tone] { | |
| background: var(--surface); | |
| } | |
| .card[data-tone="danger"], | |
| .panel[data-tone="danger"], | |
| .callout[data-tone="danger"] { | |
| border-color: rgba(176, 74, 63, 0.36); | |
| } | |
| .card[data-tone="warning"], | |
| .panel[data-tone="warning"], | |
| .callout[data-tone="warning"] { | |
| border-color: rgba(199, 142, 63, 0.38); | |
| } | |
| .card[data-tone="success"], | |
| .panel[data-tone="success"], | |
| .callout[data-tone="success"] { | |
| border-color: rgba(120, 140, 93, 0.38); | |
| } | |
| .card[data-tone="info"], | |
| .panel[data-tone="info"], | |
| .callout[data-tone="info"] { | |
| border-color: rgba(106, 140, 175, 0.36); | |
| } | |
| .card[data-accent] { | |
| position: relative; | |
| overflow: hidden; | |
| } | |
| .card[data-accent]::before { | |
| content: ""; | |
| position: absolute; | |
| inset: 0 auto 0 0; | |
| width: 5px; | |
| background: var(--accent); | |
| } | |
| .card-head { | |
| display: flex; | |
| align-items: center; | |
| gap: var(--space-3); | |
| min-width: 0; | |
| max-width: 100%; | |
| } | |
| .card-head > :first-child { | |
| flex: 0 0 auto; | |
| } | |
| .card-titles { | |
| flex: 1 1 0; | |
| min-width: 0; | |
| max-width: 100%; | |
| } | |
| .card-title { | |
| max-width: 100%; | |
| margin: 0; | |
| font-family: var(--font-serif); | |
| font-size: var(--text-xl); | |
| font-weight: 550; | |
| line-height: var(--leading-title); | |
| overflow-wrap: anywhere; | |
| } | |
| .card-sub { | |
| margin: 2px 0 0; | |
| color: var(--text-muted); | |
| font-size: var(--text-sm); | |
| overflow-wrap: anywhere; | |
| } | |
| .toolbar { | |
| display: flex; | |
| flex-wrap: wrap; | |
| align-items: center; | |
| gap: var(--space-4); | |
| padding: var(--space-4) var(--space-5); | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-md); | |
| } | |
| .toolbar[data-sticky] { | |
| position: sticky; | |
| top: 0; | |
| z-index: 10; | |
| } | |
| .chip, | |
| .badge { | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| gap: 6px; | |
| border-radius: var(--radius-pill); | |
| white-space: nowrap; | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 650; | |
| line-height: 1; | |
| } | |
| .chip { | |
| min-height: 24px; | |
| padding: 0 10px; | |
| color: var(--text-soft); | |
| background: var(--surface-tint); | |
| border: 1px solid transparent; | |
| } | |
| .badge { | |
| min-height: 22px; | |
| padding: 0 9px; | |
| color: var(--text-muted); | |
| background: var(--surface); | |
| border: var(--border-thin); | |
| text-transform: uppercase; | |
| letter-spacing: 0.06em; | |
| } | |
| .chip[data-tone="clay"], | |
| .badge[data-tone="clay"] { | |
| color: var(--accent); | |
| background: rgba(217, 119, 87, 0.14); | |
| } | |
| .chip[data-tone="olive"], | |
| .badge[data-tone="olive"], | |
| .chip[data-tone="success"], | |
| .badge[data-tone="success"] { | |
| color: var(--success); | |
| background: rgba(120, 140, 93, 0.15); | |
| } | |
| .chip[data-tone="warning"], | |
| .badge[data-tone="warning"] { | |
| color: var(--warning); | |
| background: rgba(199, 142, 63, 0.16); | |
| } | |
| .chip[data-tone="rust"], | |
| .badge[data-tone="rust"], | |
| .chip[data-tone="danger"], | |
| .badge[data-tone="danger"] { | |
| color: var(--danger); | |
| background: rgba(176, 74, 63, 0.13); | |
| } | |
| .chip[data-tone="sky"], | |
| .badge[data-tone="sky"], | |
| .chip[data-tone="info"], | |
| .badge[data-tone="info"] { | |
| color: var(--info); | |
| background: rgba(106, 140, 175, 0.14); | |
| } | |
| .finding { | |
| border-left: 6px solid var(--border-color); | |
| } | |
| .finding[data-severity="blocker"], | |
| .finding[data-severity="critical"], | |
| .finding[data-severity="danger"], | |
| .finding[data-tone="danger"] { | |
| border-left-color: var(--danger); | |
| } | |
| .finding[data-severity="high"], | |
| .finding[data-severity="warning"], | |
| .finding[data-tone="warning"] { | |
| border-left-color: var(--warning); | |
| } | |
| .finding[data-severity="medium"], | |
| .finding[data-severity="info"], | |
| .finding[data-tone="info"] { | |
| border-left-color: var(--info); | |
| } | |
| .finding[data-severity="low"], | |
| .finding[data-severity="success"], | |
| .finding[data-tone="success"] { | |
| border-left-color: var(--success); | |
| } | |
| .button, | |
| .btn { | |
| appearance: none; | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| min-height: 36px; | |
| padding: 0 14px; | |
| border: 1.5px solid transparent; | |
| border-radius: var(--radius-sm); | |
| font-family: var(--font-sans); | |
| font-size: var(--text-md); | |
| font-weight: 650; | |
| line-height: 1; | |
| text-decoration: none; | |
| transition: | |
| transform var(--dur-fast) var(--ease), | |
| background-color var(--dur-fast) var(--ease), | |
| border-color var(--dur-fast) var(--ease), | |
| box-shadow var(--dur-fast) var(--ease); | |
| } | |
| .button:hover, | |
| .btn:hover { | |
| transform: translateY(-1px); | |
| } | |
| .button[data-variant="primary"], | |
| .btn-primary { | |
| color: var(--color-white); | |
| background: var(--color-slate); | |
| } | |
| .button[data-variant="primary"]:hover, | |
| .btn-primary:hover { | |
| background: var(--color-gray-700); | |
| } | |
| .button[data-variant="secondary"], | |
| .btn-secondary { | |
| color: var(--text); | |
| background: var(--surface-tint); | |
| border-color: var(--border-color); | |
| } | |
| .button[data-variant="ghost"], | |
| .btn-ghost { | |
| color: var(--text-soft); | |
| background: transparent; | |
| } | |
| .button[data-variant="ghost"]:hover, | |
| .btn-ghost:hover { | |
| color: var(--text); | |
| background: var(--surface-tint); | |
| } | |
| .button[data-variant="danger"], | |
| .btn-danger { | |
| color: var(--color-white); | |
| background: var(--danger); | |
| } | |
| .input { | |
| width: 100%; | |
| min-height: 38px; | |
| padding: 0 12px; | |
| color: var(--text); | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-sm); | |
| outline: none; | |
| } | |
| .input:focus { | |
| border-color: var(--accent); | |
| box-shadow: 0 0 0 3px rgba(217, 119, 87, 0.16); | |
| } | |
| .avatar { | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| width: var(--avatar-size, 38px); | |
| height: var(--avatar-size, 38px); | |
| border-radius: 50%; | |
| color: var(--text-soft); | |
| background: var(--surface-warm); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| font-weight: 700; | |
| letter-spacing: 0.02em; | |
| flex: 0 0 auto; | |
| } | |
| .code-block { | |
| margin: 0; | |
| padding: var(--space-4) var(--space-5); | |
| overflow-x: auto; | |
| color: #E8E6DC; | |
| background: var(--color-slate); | |
| border-radius: var(--radius-md); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| line-height: var(--leading-loose); | |
| } | |
| .code-block[data-kind="command"], | |
| .code-block[data-wrap="true"], | |
| .command-block { | |
| max-width: 100%; | |
| min-width: 0; | |
| box-sizing: border-box; | |
| white-space: pre-wrap; | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| overflow-x: hidden; | |
| } | |
| .code-block[data-wrap="true"] code, | |
| .code-block[data-kind="command"] code { | |
| display: block; | |
| max-width: 100%; | |
| white-space: pre-wrap; | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| } | |
| .copyable { | |
| position: relative; | |
| } | |
| .copyable > .code-block { | |
| padding-inline-end: 88px; | |
| } | |
| .copy-button { | |
| appearance: none; | |
| position: absolute; | |
| inset-block-start: var(--space-2); | |
| inset-inline-end: var(--space-2); | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| min-height: 26px; | |
| padding: 0 9px; | |
| border: 1px solid rgba(250, 249, 245, 0.18); | |
| border-radius: var(--radius-sm); | |
| color: var(--color-gray-100); | |
| background: rgba(255, 255, 255, 0.08); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 700; | |
| letter-spacing: 0.04em; | |
| text-transform: uppercase; | |
| transition: | |
| background-color var(--dur-fast) var(--ease), | |
| border-color var(--dur-fast) var(--ease), | |
| transform var(--dur-fast) var(--ease); | |
| } | |
| .copy-button:hover { | |
| transform: translateY(-1px); | |
| border-color: rgba(250, 249, 245, 0.35); | |
| background: rgba(255, 255, 255, 0.14); | |
| } | |
| .copy-button[data-copied="true"] { | |
| color: var(--color-white); | |
| background: rgba(120, 140, 93, 0.55); | |
| border-color: rgba(120, 140, 93, 0.75); | |
| } | |
| .reference-panel { | |
| --panel-pad: var(--space-5); | |
| } | |
| .callout { | |
| padding: var(--space-5); | |
| color: var(--text-soft); | |
| background: var(--surface-tint); | |
| border: var(--border); | |
| border-inline-start: 4px solid var(--accent); | |
| border-radius: var(--radius-md); | |
| } | |
| .callout[data-tone="success"] { | |
| border-inline-start-color: var(--success); | |
| background: rgba(120, 140, 93, 0.10); | |
| } | |
| .callout[data-tone="warning"] { | |
| border-inline-start-color: var(--warning); | |
| background: rgba(199, 142, 63, 0.11); | |
| } | |
| .callout[data-tone="danger"] { | |
| border-inline-start-color: var(--danger); | |
| background: rgba(176, 74, 63, 0.10); | |
| } | |
| .callout[data-tone="info"] { | |
| border-inline-start-color: var(--info); | |
| background: rgba(106, 140, 175, 0.11); | |
| } | |
| .callout-label { | |
| display: block; | |
| margin-bottom: var(--space-2); | |
| color: var(--text-muted); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 700; | |
| letter-spacing: 0.09em; | |
| text-transform: uppercase; | |
| } | |
| .callout > :last-child { | |
| margin-bottom: 0; | |
| } | |
| .checklist { | |
| list-style: none; | |
| margin: 0; | |
| padding: 0; | |
| display: grid; | |
| gap: var(--space-3); | |
| } | |
| .checklist li { | |
| display: block ; | |
| position: relative ; | |
| min-width: 0; | |
| padding-inline-start: calc(18px + var(--space-3)); | |
| overflow-wrap: anywhere; | |
| } | |
| .checklist li::before { | |
| content: "✓"; | |
| position: absolute ; | |
| inset-block-start: 2px; | |
| inset-inline-start: 0; | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| width: 18px; | |
| height: 18px; | |
| border-radius: 50%; | |
| color: var(--success); | |
| background: rgba(120, 140, 93, 0.12); | |
| font-family: var(--font-mono); | |
| font-size: 12px; | |
| font-weight: 700; | |
| line-height: 1; | |
| } | |
| .checklist code { | |
| white-space: normal; | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| } | |
| .plain-list { | |
| margin: 0; | |
| padding-inline-start: 1.15em; | |
| color: var(--text-soft); | |
| } | |
| .plain-list li { | |
| overflow-wrap: anywhere; | |
| } | |
| .plain-list li + li { | |
| margin-top: var(--space-2); | |
| } | |
| .plain-list li::marker { | |
| color: var(--text-muted); | |
| } | |
| .insight-list, | |
| .takeaway-list { | |
| list-style: none; | |
| margin: 0; | |
| padding: 0; | |
| display: grid; | |
| gap: var(--space-3); | |
| } | |
| .insight-list li, | |
| .takeaway-list li { | |
| position: relative; | |
| display: block; | |
| padding-inline-start: calc(10px + var(--space-3)); | |
| color: var(--text-soft); | |
| } | |
| .insight-list li::before, | |
| .takeaway-list li::before { | |
| content: ""; | |
| position: absolute; | |
| inset-block-start: 0.65em; | |
| inset-inline-start: 0; | |
| width: 7px; | |
| height: 7px; | |
| border-radius: 50%; | |
| background: var(--accent); | |
| } | |
| .insight-list li > *, | |
| .takeaway-list li > * { | |
| min-width: 0; | |
| } | |
| .insight-list[data-tone="success"] li::before, | |
| .takeaway-list[data-tone="success"] li::before { | |
| background: var(--success); | |
| } | |
| .insight-list[data-tone="info"] li::before, | |
| .takeaway-list[data-tone="info"] li::before { | |
| background: var(--info); | |
| } | |
| .metric-list { | |
| --metric-label: 132px; | |
| --metric-value: 64px; | |
| display: grid; | |
| gap: var(--space-3); | |
| } | |
| .metric-row { | |
| display: grid; | |
| grid-template-columns: var(--metric-label) minmax(120px, 1fr) var(--metric-value); | |
| gap: var(--space-3); | |
| align-items: center; | |
| } | |
| .metric-row > :first-child { | |
| min-width: 0; | |
| } | |
| .metric-row > :last-child { | |
| justify-self: end; | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| } | |
| .meter { | |
| height: 9px; | |
| overflow: hidden; | |
| border-radius: var(--radius-pill); | |
| background: var(--surface-tint); | |
| } | |
| .meter span { | |
| display: block; | |
| width: var(--value); | |
| height: 100%; | |
| background: var(--tone, var(--accent)); | |
| } | |
| .flow-list { | |
| list-style: none; | |
| margin: 0; | |
| padding: 0; | |
| display: grid; | |
| gap: var(--space-3); | |
| } | |
| .flow-step { | |
| position: relative; | |
| display: grid; | |
| grid-template-columns: 42px minmax(0, 1fr); | |
| gap: var(--space-3); | |
| align-items: start; | |
| padding: var(--space-4); | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-md); | |
| } | |
| .flow-step > .flow-num { | |
| grid-column: 1; | |
| } | |
| .flow-step > :not(.flow-num) { | |
| grid-column: 2; | |
| min-width: 0; | |
| } | |
| .flow-step::after { | |
| content: ""; | |
| position: absolute; | |
| inset-block-start: calc(100% + 1px); | |
| inset-inline-start: 36px; | |
| width: 1.5px; | |
| height: var(--space-3); | |
| background: var(--border-color); | |
| } | |
| .flow-step:last-child::after { | |
| display: none; | |
| } | |
| .flow-num { | |
| display: inline-flex; | |
| align-items: center; | |
| justify-content: center; | |
| width: 34px; | |
| height: 34px; | |
| border-radius: var(--radius-pill); | |
| color: var(--text); | |
| background: var(--surface-warm); | |
| box-shadow: inset 0 0 0 1px rgba(20, 20, 19, 0.10); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| font-weight: 700; | |
| } | |
| .flow-title { | |
| margin: 0 0 var(--space-1); | |
| font-family: var(--font-serif); | |
| font-size: var(--text-xl); | |
| font-weight: 550; | |
| line-height: var(--leading-title); | |
| } | |
| .flow-detail { | |
| margin: 0; | |
| color: var(--text-soft); | |
| } | |
| .flow-branch { | |
| display: grid; | |
| grid-template-columns: repeat(2, minmax(0, 1fr)); | |
| gap: var(--space-3); | |
| } | |
| .flow-branch .flow-step::after { | |
| display: none; | |
| } | |
| .flow-step[data-tone="success"] { | |
| border-color: rgba(120, 140, 93, 0.38); | |
| background: rgba(120, 140, 93, 0.08); | |
| } | |
| .flow-step[data-tone="warning"] { | |
| border-color: rgba(199, 142, 63, 0.42); | |
| background: rgba(199, 142, 63, 0.09); | |
| } | |
| @media (max-width: 620px) { | |
| .metric-row { | |
| grid-template-columns: 1fr max-content; | |
| } | |
| .metric-row .meter { | |
| grid-column: 1 / -1; | |
| order: 3; | |
| } | |
| .flow-branch { | |
| grid-template-columns: 1fr; | |
| } | |
| } | |
| /* ---------- Charts and numeric data ---------- */ | |
| .chart-panel { | |
| max-width: 100%; | |
| min-width: 0; | |
| overflow: hidden; | |
| } | |
| .chart-panel > * { | |
| min-width: 0; | |
| } | |
| .chart-panel svg, | |
| svg.chart-svg { | |
| display: block; | |
| width: 100%; | |
| height: auto; | |
| } | |
| .chart-caption { | |
| color: var(--text-muted); | |
| font-size: var(--text-sm); | |
| } | |
| .numeric-table-wrap { | |
| overflow-x: auto; | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-md); | |
| } | |
| .numeric-table { | |
| width: 100%; | |
| min-width: 720px; | |
| border-collapse: collapse; | |
| } | |
| .numeric-table th, | |
| .numeric-table td { | |
| padding: var(--space-3) var(--space-4); | |
| border-bottom: 1px solid var(--color-gray-200); | |
| vertical-align: middle; | |
| } | |
| .numeric-table th { | |
| color: var(--text-muted); | |
| background: var(--surface-tint); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 700; | |
| letter-spacing: 0.08em; | |
| text-align: left; | |
| text-transform: uppercase; | |
| } | |
| .numeric-table tr:last-child td { | |
| border-bottom: 0; | |
| } | |
| .numeric-table .metric, | |
| .numeric-table .num { | |
| text-align: right; | |
| font-variant-numeric: tabular-nums; | |
| white-space: nowrap; | |
| } | |
| .numeric-table .entity, | |
| .numeric-table .label-cell { | |
| font-weight: 650; | |
| } | |
| .numeric-table .note { | |
| color: var(--text-soft); | |
| } | |
| .numeric-table code { | |
| white-space: normal; | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| } | |
| .numeric-table .subtle { | |
| display: block; | |
| margin-top: 2px; | |
| color: var(--text-muted); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| font-weight: 400; | |
| } | |
| @media (max-width: 620px) { | |
| .numeric-table { | |
| min-width: 0; | |
| } | |
| .numeric-table thead { | |
| display: none; | |
| } | |
| .numeric-table tbody, | |
| .numeric-table tr, | |
| .numeric-table td { | |
| display: block; | |
| } | |
| .numeric-table tr { | |
| padding: var(--space-3) var(--space-4); | |
| border-bottom: 1px solid var(--color-gray-200); | |
| } | |
| .numeric-table tr:last-child { | |
| border-bottom: 0; | |
| } | |
| .numeric-table td { | |
| padding: var(--space-1) 0; | |
| border-bottom: 0; | |
| } | |
| .numeric-table td[data-label] { | |
| display: flex; | |
| justify-content: space-between; | |
| gap: var(--space-4); | |
| } | |
| .numeric-table td[data-label]::before { | |
| content: attr(data-label); | |
| color: var(--text-muted); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-xs); | |
| text-transform: uppercase; | |
| } | |
| } | |
| /* ---------- Diff ---------- */ | |
| .diff { | |
| overflow-x: auto; | |
| color: #E8E6DC; | |
| background: var(--color-slate); | |
| border-radius: var(--radius-md); | |
| font-family: var(--font-mono); | |
| font-size: 12.5px; | |
| line-height: var(--leading-loose); | |
| } | |
| .diff-row { | |
| display: grid; | |
| grid-template-columns: 48px 18px minmax(max-content, 1fr); | |
| align-items: baseline; | |
| min-width: max-content; | |
| padding-inline-end: var(--space-4); | |
| white-space: pre; | |
| } | |
| .diff-row .ln { | |
| padding-inline-end: 14px; | |
| color: var(--color-gray-500); | |
| text-align: right; | |
| user-select: none; | |
| } | |
| .diff-row .mark { | |
| color: var(--color-gray-500); | |
| text-align: center; | |
| } | |
| .diff-row .code { | |
| color: #E8E6DC; | |
| } | |
| .diff-row.ctx .code, | |
| .diff-row[data-kind="ctx"] .code { | |
| color: #B8B6AC; | |
| } | |
| .diff-row.add, | |
| .diff-row[data-kind="add"] { | |
| background: rgba(120, 140, 93, 0.24); | |
| box-shadow: inset 3px 0 0 rgba(120, 140, 93, 0.78); | |
| } | |
| .diff-row.add .mark, | |
| .diff-row[data-kind="add"] .mark { | |
| color: #B9D394; | |
| font-weight: 800; | |
| } | |
| .diff-row.del, | |
| .diff-row[data-kind="del"] { | |
| background: rgba(176, 74, 63, 0.24); | |
| box-shadow: inset 3px 0 0 rgba(176, 74, 63, 0.82); | |
| } | |
| .diff-row.del .mark, | |
| .diff-row[data-kind="del"] .mark { | |
| color: #F19A8D; | |
| font-weight: 800; | |
| } | |
| .diff-row.hunk, | |
| .diff-row[data-kind="hunk"] { | |
| background: rgba(255, 255, 255, 0.045); | |
| } | |
| .diff-row.hunk .code, | |
| .diff-row[data-kind="hunk"] .code { | |
| color: var(--color-gray-500); | |
| } | |
| .diff[data-wrap="true"] { | |
| overflow-x: hidden; | |
| } | |
| .diff[data-wrap="true"] .diff-row { | |
| grid-template-columns: 42px 18px minmax(0, 1fr); | |
| min-width: 0; | |
| white-space: normal; | |
| } | |
| .diff[data-wrap="true"] .code { | |
| white-space: pre-wrap; | |
| overflow-wrap: anywhere; | |
| } | |
| /* ---------- Timeline ---------- */ | |
| .timeline { | |
| position: relative; | |
| display: grid; | |
| gap: 0; | |
| padding-inline-start: var(--space-6); | |
| } | |
| .timeline:is(ol, ul) { | |
| margin: 0; | |
| list-style: none; | |
| } | |
| .timeline::before { | |
| content: ""; | |
| position: absolute; | |
| inset-block: 4px 4px; | |
| inset-inline-start: 9px; | |
| width: 1.5px; | |
| background: var(--border-color); | |
| } | |
| .timeline-item, | |
| .tl-entry { | |
| position: relative; | |
| display: grid; | |
| grid-template-columns: minmax(84px, max-content) minmax(0, 1fr); | |
| gap: var(--space-4); | |
| padding-block: 0 var(--space-5); | |
| } | |
| .timeline-item:last-child, | |
| .tl-entry:last-child { | |
| padding-block-end: 0; | |
| } | |
| .timeline-item::before, | |
| .tl-entry::before { | |
| content: ""; | |
| position: absolute; | |
| inset-block-start: 4px; | |
| inset-inline-start: calc(4.25px - var(--space-6)); | |
| width: 11px; | |
| height: 11px; | |
| border: 2px solid var(--surface); | |
| border-radius: 50%; | |
| background: var(--accent); | |
| box-shadow: 0 0 0 1.5px var(--accent); | |
| } | |
| .timeline-item:not(:has(> .timeline-time, > .tl-time)), | |
| .tl-entry:not(:has(> .timeline-time, > .tl-time)) { | |
| display: block; | |
| } | |
| .timeline-time, | |
| .tl-time { | |
| color: var(--text-muted); | |
| font-family: var(--font-mono); | |
| font-size: var(--text-sm); | |
| white-space: nowrap; | |
| } | |
| .timeline-body, | |
| .tl-body { | |
| min-width: 0; | |
| color: var(--text-soft); | |
| } | |
| .timeline-body strong, | |
| .tl-body strong { | |
| color: var(--text); | |
| } | |
| @media (max-width: 620px) { | |
| .timeline-item, | |
| .tl-entry { | |
| grid-template-columns: 1fr; | |
| gap: var(--space-1); | |
| } | |
| } | |
| /* ---------- Flowchart ---------- */ | |
| .flowchart { | |
| display: block; | |
| width: 100%; | |
| height: auto; | |
| } | |
| svg.flow, | |
| svg.flowchart { | |
| display: block; | |
| width: 100%; | |
| height: auto; | |
| } | |
| .flow text, | |
| .flowchart text { | |
| fill: var(--text); | |
| font-family: var(--font-sans); | |
| font-size: 12px; | |
| } | |
| .flow .sub, | |
| .flowchart .sub { | |
| fill: var(--text-muted); | |
| font-size: 10px; | |
| } | |
| .flow-edge, | |
| .edge { | |
| fill: none; | |
| stroke: var(--text-muted); | |
| stroke-width: 1.5; | |
| } | |
| .flow-edge[data-kind="yes"], | |
| .edge.yes { | |
| stroke: var(--success); | |
| } | |
| .flow-edge[data-kind="no"], | |
| .edge.no { | |
| stroke: var(--danger); | |
| stroke-dasharray: 4 4; | |
| } | |
| /* SVG flow nodes */ | |
| .flow-node, | |
| .flow .node { | |
| cursor: pointer; | |
| transition: transform var(--dur-fast) var(--ease); | |
| } | |
| .flow-node:hover, | |
| .flow .node:hover { | |
| transform: translateY(-1px); | |
| } | |
| .flow-node rect, | |
| .flow .node rect { | |
| fill: var(--surface); | |
| stroke: var(--border-color); | |
| stroke-width: 1.5; | |
| rx: 8; | |
| } | |
| .flow-node path, | |
| .flow .node.gate path { | |
| fill: var(--surface); | |
| stroke: var(--border-color); | |
| stroke-width: 1.5; | |
| } | |
| .flow-node[data-shape="term"] rect, | |
| .flow .node.term rect { | |
| fill: var(--surface-tint); | |
| rx: 22; | |
| } | |
| .flow-node[data-kind="ok"] rect, | |
| .flow .node.ok rect { | |
| fill: rgba(120, 140, 93, 0.12); | |
| stroke: var(--success); | |
| } | |
| .flow-node[data-kind="bad"] rect, | |
| .flow .node.bad rect { | |
| fill: rgba(176, 74, 63, 0.10); | |
| stroke: var(--danger); | |
| } | |
| .flow-node.active rect, | |
| .flow-node.active path, | |
| .flow .node.active rect, | |
| .flow .node.active path { | |
| stroke: var(--accent); | |
| stroke-width: 2; | |
| } | |
| /* HTML flow nodes, for non-SVG diagrams */ | |
| div.flow-node { | |
| padding: var(--space-3) var(--space-4); | |
| background: var(--surface); | |
| border: var(--border); | |
| border-radius: var(--radius-sm); | |
| transition: | |
| transform var(--dur-fast) var(--ease), | |
| border-color var(--dur-fast) var(--ease), | |
| box-shadow var(--dur-fast) var(--ease); | |
| } | |
| div.flow-node:hover { | |
| transform: translateY(var(--hover-y)); | |
| border-color: rgba(217, 119, 87, 0.55); | |
| box-shadow: var(--shadow-sm); | |
| } | |
| div.flow-node[data-shape="term"] { | |
| border-radius: var(--radius-pill); | |
| background: var(--surface-tint); | |
| } | |
| div.flow-node[data-kind="ok"] { | |
| border-color: var(--success); | |
| background: rgba(120, 140, 93, 0.12); | |
| } | |
| div.flow-node[data-kind="bad"] { | |
| border-color: var(--danger); | |
| background: rgba(176, 74, 63, 0.10); | |
| } | |
| @media (prefers-reduced-motion: reduce) { | |
| *, | |
| *::before, | |
| *::after { | |
| scroll-behavior: auto ; | |
| transition-duration: 0.01ms ; | |
| animation-duration: 0.01ms ; | |
| animation-iteration-count: 1 ; | |
| } | |
| } | |
| /* Responsive safety net for generated artifacts. */ | |
| p, | |
| li { | |
| overflow-wrap: anywhere; | |
| } | |
| @media (max-width: 860px) { | |
| .split, | |
| .section-rail, | |
| .sidebar-layout { | |
| grid-template-columns: minmax(0, 1fr) ; | |
| } | |
| .split > *, | |
| .section-rail > *, | |
| .sidebar-layout > *, | |
| .chart-panel { | |
| width: 100%; | |
| max-width: 100%; | |
| min-width: 0; | |
| } | |
| }</style> | |
| <style> | |
| /* Custom SVG sizing and adjustments */ | |
| svg.flowchart { | |
| display: block; | |
| width: 100%; | |
| height: auto; | |
| max-width: 460px; | |
| margin: 0 auto; | |
| } | |
| /* Mobile wrapping safety */ | |
| .numeric-table code, | |
| .numeric-table .note { | |
| white-space: normal; | |
| overflow-wrap: anywhere; | |
| word-break: break-word; | |
| } | |
| .diff-row .code { | |
| overflow-wrap: anywhere; | |
| word-break: break-all; | |
| } | |
| </style> | |
| </head> | |
| <body> | |
| <main class="page stack" data-gap="lg"> | |
| <header class="stack" data-gap="sm"> | |
| <div class="eyebrow">Module Explainer</div> | |
| <h1>The Rendering Checker Pipeline</h1> | |
| <p class="lede">A developer-focused guide to the static contract checker, headless browser auditor, and visual regression suite that ensures design system compliance across all generated Birch HTML artifacts.</p> | |
| <div class="cluster"> | |
| <span class="chip" data-tone="clay">Pipeline Core</span> | |
| <span class="chip" data-tone="olive">Static Contracts</span> | |
| <span class="chip" data-tone="sky">Chrome DOM Audit</span> | |
| <span class="chip" data-tone="rust">Pillow Screenshots</span> | |
| </div> | |
| </header> | |
| <!-- Section 1: Mental Model & High Level Architecture --> | |
| <section class="section-rail" data-gap="lg"> | |
| <div class="section-head"> | |
| <span class="eyebrow">System Architecture</span> | |
| <h2>Mental Model & Visual Gates</h2> | |
| </div> | |
| <div class="stack" data-gap="md"> | |
| <p>The rendering checker acts as an automated <strong>visual gatekeeper</strong> for generated HTML documents. Rather than relying on computationally heavy visual-language models (VLMs) for basic sanity testing, the checker adopts a <strong>deterministic-first approach</strong>, dividing document validation into three increasingly strict execution gates:</p> | |
| <div class="grid" data-cols="3"> | |
| <article class="card stack" data-variant="outlined" data-accent="clay"> | |
| <h3>1. Static HTML Contract Gate</h3> | |
| <p class="muted">Runs fast syntactic evaluations. Subclasses of <code>HTMLParser</code> extract element structures, verify nested layout rules, check CSS variables, and flag illegal style patterns (such as background gradients) before launching a browser.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="olive"> | |
| <h3>2. Dynamic Browser Geometry Gate</h3> | |
| <p class="muted">Launches Headless Chrome to render the artifact. Injects custom diagnostic JavaScript (<code>audit_js</code>) to query element bounding rectangles on load, diagnosing overflow, squeezing, or vertical misalignments.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="sky"> | |
| <h3>3. Visual Regression Gate</h3> | |
| <p class="muted">Performs screenshot capture. Uses Pillow to sample the visual color palette (verifying conformity with canonical Birch ivory/clay tones) and calculates Mean and RMS RGB distance metrics against original reference files.</p> | |
| </article> | |
| </div> | |
| <div class="callout stack" data-tone="info" data-gap="xs"> | |
| <span class="callout-label">Operating Modes</span> | |
| <p>The suite supports two main execution pathways: <strong>Candidate-only Mode</strong> (using <code>--artifact <path></code>) which renders and verifies a newly generated artifact in isolation, and <strong>Pair Comparison Mode</strong> (using <code>--pair <ref>:<cand></code>) which computes visual regression deltas and contact sheets against a reference baseline.</p> | |
| </div> | |
| </div> | |
| <aside class="reference-panel stack" data-gap="md"> | |
| <h3>Pipeline CLI Commands</h3> | |
| <p class="muted">Use these commands in your local shell to execute verification tests manually:</p> | |
| <div class="stack" data-gap="sm"> | |
| <div class="stack" data-gap="xs"> | |
| <span class="caption">Artifact Verification</span> | |
| <pre class="code-block" data-kind="command" data-copy>python3 scripts/check_birch_renderings.py --artifact 24-birch-chart-brief.html</pre> | |
| </div> | |
| <div class="stack" data-gap="xs"> | |
| <span class="caption">Pair Comparison</span> | |
| <pre class="code-block" data-kind="command" data-copy>python3 scripts/check_birch_renderings.py --pair 05-design-system.html:05-design-system-birch.html</pre> | |
| </div> | |
| <div class="stack" data-gap="xs"> | |
| <span class="caption">Dynamic Viewports</span> | |
| <pre class="code-block" data-kind="command" data-copy>python3 scripts/check_birch_renderings.py --artifact 24-birch-chart-brief.html --viewport mobile:390x900</pre> | |
| </div> | |
| </div> | |
| </aside> | |
| </section> | |
| <!-- Section 2: Runtime Execution Path --> | |
| <section class="section stack" data-gap="lg"> | |
| <div class="section-head"> | |
| <span class="eyebrow">Execution Path</span> | |
| <h2>The Pipeline Runtime Walkthrough</h2> | |
| </div> | |
| <div class="split"> | |
| <div class="stack" data-gap="lg"> | |
| <p>From initial option parsing to final report writing, the rendering checker executes a linear pipeline. The flow diagram below illustrates how code contracts are statically scanned, browser-rendered, and pixel-analyzed sequentially.</p> | |
| <div class="panel chart-panel stack" data-gap="sm"> | |
| <!-- Inline SVG Flowchart --> | |
| <svg class="flowchart" viewBox="0 0 460 480" role="img" aria-label="Visual representation of the Rendering Checker Pipeline execution flow."> | |
| <!-- Edges --> | |
| <path class="flow-edge" d="M230,56 L230,92"></path> | |
| <path class="flow-edge" d="M230,140 L230,176"></path> | |
| <path class="flow-edge" d="M230,224 L230,260"></path> | |
| <path class="flow-edge" d="M230,308 L230,344"></path> | |
| <path class="flow-edge" d="M230,392 L230,428"></path> | |
| <!-- Node 1 --> | |
| <g class="flow-node" data-shape="term"> | |
| <rect x="150" y="12" width="160" height="44" rx="22"></rect> | |
| <text x="230" y="38" text-anchor="middle" font-weight="650">Input Files / Pairs</text> | |
| </g> | |
| <!-- Node 2 --> | |
| <g class="flow-node"> | |
| <rect x="110" y="92" width="240" height="48" rx="8"></rect> | |
| <text x="230" y="112" text-anchor="middle" font-weight="650">1. Static Contract Checks</text> | |
| <text class="sub" x="230" y="128" text-anchor="middle">HTMLParser subclasses · CSS Variables</text> | |
| </g> | |
| <!-- Node 3 --> | |
| <g class="flow-node"> | |
| <rect x="110" y="176" width="240" height="48" rx="8"></rect> | |
| <text x="230" y="196" text-anchor="middle" font-weight="650">2. Headless Chrome Launch</text> | |
| <text class="sub" x="230" y="212" text-anchor="middle">Dynamic Height Measure · Screenshots</text> | |
| </g> | |
| <!-- Node 4 --> | |
| <g class="flow-node" data-kind="ok"> | |
| <rect x="110" y="260" width="240" height="48" rx="8"></rect> | |
| <text x="230" y="280" text-anchor="middle" font-weight="650">3. In-Browser Geometry Audit</text> | |
| <text class="sub" x="230" y="296" text-anchor="middle">data-birch-audit JSON Injection</text> | |
| </g> | |
| <!-- Node 5 --> | |
| <g class="flow-node"> | |
| <rect x="110" y="344" width="240" height="48" rx="8"></rect> | |
| <text x="230" y="364" text-anchor="middle" font-weight="650">4. Pillow Image Analysis</text> | |
| <text class="sub" x="230" y="380" text-anchor="middle">Palette Close · RMS Distance · Diff Sheet</text> | |
| </g> | |
| <!-- Node 6 --> | |
| <g class="flow-node" data-shape="term" data-kind="ok"> | |
| <rect x="130" y="428" width="200" height="44" rx="22"></rect> | |
| <text x="230" y="454" text-anchor="middle" font-weight="650">Reports Compiled</text> | |
| </g> | |
| </svg> | |
| <p class="chart-caption">Figure 1: The six distinct sequential phases of the rendering check execution pipeline, flowing from raw file input to compiled visual reports.</p> | |
| </div> | |
| </div> | |
| <aside class="reference-panel stack" data-gap="md"> | |
| <h3>The Runtime Path in Detail</h3> | |
| <p class="muted">Follow the pipeline's algorithmic steps as it compiles findings:</p> | |
| <ol class="flow-list"> | |
| <li class="flow-step"> | |
| <span class="flow-num">1</span> | |
| <div> | |
| <h4 class="flow-title">Option Parsing & System Initialization</h4> | |
| <p class="flow-detail">Resolves physical file directories, matches CLI viewport rules (e.g., <code>desktop:1365x900</code>), and loads the canonical CSS tokens directly from <code>styles/birch-system.css</code> to compile standard CSS variables.</p> | |
| </div> | |
| </li> | |
| <li class="flow-step"> | |
| <span class="flow-num">2</span> | |
| <div> | |
| <h4 class="flow-title">Static Syntactic Scans</h4> | |
| <p class="flow-detail">Reads the HTML in-memory. Subclasses of <code>HTMLParser</code> assess formatting structures. Specifically: | |
| <code>StatsParser</code> (toggles tag counters), | |
| <code>DiffRowParser</code> (checks line-num/mark/code cells), | |
| <code>MetricRowParser</code> (checks progress-bar columns), and | |
| <code>FlowStepParser</code> (ensures correct container wrapping). | |
| Also checks for inline gradient definitions and accidental '+' characters. | |
| </p> | |
| </div> | |
| </li> | |
| <li class="flow-step"> | |
| <span class="flow-num">3</span> | |
| <div> | |
| <h4 class="flow-title">Headless Chrome Boot & Height Adjustment</h4> | |
| <p class="flow-detail">Launches Chrome in headless mode. For viewport profiles containing 'deep' specifications, <code>capture_height_for_viewport()</code> registers a load listener and queries <code>document.documentElement.scrollHeight</code> dynamically to prevent cut-off captures.</p> | |
| </div> | |
| </li> | |
| <li class="flow-step"> | |
| <span class="flow-num">4</span> | |
| <div> | |
| <h4 class="flow-title">In-Browser Geometry Audit</h4> | |
| <p class="flow-detail">Injects <code>audit_js</code> into the page. The script utilizes browser bounding boxes to diagnose defects invisible to static files: document-level scrolling, squeezed stat boxes, misaligned sidebar containers, and mismatched numeric table column alignments.</p> | |
| </div> | |
| </li> | |
| <li class="flow-step"> | |
| <span class="flow-num">5</span> | |
| <div> | |
| <h4 class="flow-title">Pillow Screenshot & Palette Analysis</h4> | |
| <p class="flow-detail">Saves visual snaps. In pair mode, computes Mean and RMS RGB distances between reference and candidates, generating 4x-amplified difference sheets. In both modes, <code>palette_metrics()</code> resizes images to calculate canonical color density, flagging blank pages.</p> | |
| </div> | |
| </li> | |
| <li class="flow-step" data-tone="success"> | |
| <span class="flow-num">6</span> | |
| <div> | |
| <h4 class="flow-title">Consolidation & Exit Signalling</h4> | |
| <p class="flow-detail">Compiles all anomalies into a detailed JSON payload (<code>reports/birch-rendering-check.json</code>) and a human-readable Markdown digest (<code>reports/birch-rendering-check.md</code>). Exits with exit code <code>1</code> on severe failures.</p> | |
| </div> | |
| </li> | |
| </ol> | |
| </aside> | |
| </div> | |
| </section> | |
| <!-- Section 3: File Onboarding Tour --> | |
| <section class="section stack" data-gap="lg"> | |
| <div class="section-head"> | |
| <span class="eyebrow">Onboarding</span> | |
| <h2>File Tour for New Contributors</h2> | |
| </div> | |
| <p class="lede">To safely modify the rendering checker without breaking the existing test suites or failing candidate evaluations, follow this structured file tour in order:</p> | |
| <div class="timeline"> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 1</div> | |
| <div class="timeline-body"> | |
| <strong><code>styles/birch-system.css</code> (The Visual Grammar)</strong> | |
| <p class="muted">Read this first to master the design system's variables (e.g. <code>--bg</code>, <code>--surface</code>, <code>--accent</code>), spacing sizes (<code>--space-1</code> to <code>--space-9</code>), and primitives (grids, splits, cards). It forms the layout dictionary the checker validates candidates against.</p> | |
| </div> | |
| </div> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 2</div> | |
| <div class="timeline-body"> | |
| <strong><code>docs/birch-llm-style-guide.md</code> (The LLM Contract)</strong> | |
| <p class="muted">Understand the style contracts, nested grid rules, and design guidelines that LLM-generated artifacts are required to fulfill. It documents the exact structural rules that the checker's parser subclasses enforce.</p> | |
| </div> | |
| </div> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 3</div> | |
| <div class="timeline-body"> | |
| <strong><code>scripts/check_birch_renderings.py</code> (The Execution Engine)</strong> | |
| <p class="muted">Study the parser's logic. Examine the <code>HTMLParser</code> subclasses (e.g., <code>MetricRowParser</code>, <code>DiffRowParser</code>) and explore the raw Javascript inside the <code>geometry_audit()</code> function to understand how elements are queried for layout errors inside the headless browser.</p> | |
| </div> | |
| </div> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 4</div> | |
| <div class="timeline-body"> | |
| <strong><code>scripts/birch_mpl.py</code> (Visualization Helpers)</strong> | |
| <p class="muted">Inspect how Matplotlib's global <code>rcParams</code> are temporarily overridden (via the <code>birch_theme()</code> context manager) to match Birch color palette variables. Review the axes cleanup (<code>polish_axes()</code>) and SVG serialization helpers.</p> | |
| </div> | |
| </div> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 5</div> | |
| <div class="timeline-body"> | |
| <strong><code>evals/charts/build_chart_brief.py</code> (Reference Artifact Creator)</strong> | |
| <p class="muted">Analyze this script to see an end-to-end implementation of Birch HTML generation. It reads raw sample CSV rows, creates visual charts with <code>birch_mpl.py</code>, formats metric rows, and compiles a clean, right-aligned numeric table.</p> | |
| </div> | |
| </div> | |
| <div class="timeline-item"> | |
| <div class="timeline-time">Step 6</div> | |
| <div class="timeline-body"> | |
| <strong><code>evals/charts/run_eval.py</code> (Evaluation Test Runner)</strong> | |
| <p class="muted">Conclude your file tour by reviewing the automated evaluation script. It generates the chart brief and passes it to the rendering checker at desktop, mobile, deep, and mobile-deep viewports to validate cross-platform responsiveness.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </section> | |
| <!-- Section 4: Gotchas, Extensions, and behavioral changes --> | |
| <section class="section stack" data-gap="lg"> | |
| <div class="section-head"> | |
| <span class="eyebrow">Modification Guide</span> | |
| <h2>Gotchas, Modifications, and Extension Points</h2> | |
| </div> | |
| <div class="grid" data-cols="2"> | |
| <!-- Gotchas Column --> | |
| <div class="stack" data-gap="md"> | |
| <h3>Critical Pipeline Gotchas</h3> | |
| <article class="card stack" data-variant="outlined" data-accent="clay"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="danger">SQUEEZE</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">1. Direct Children in Flex/Grid Containers</h4> | |
| </div> | |
| </div> | |
| <p class="muted">Layout classes like <code>.insight-list li</code>, <code>.takeaway-list li</code>, <code>.flow-step</code>, and <code>.diff-row</code> use explicit grid layouts. Putting loose direct text or un-wrapped elements under these elements converts them into extra, anonymous grid columns. This squishes code text, forcing single characters to wrap in vertical trails. <strong>Fix:</strong> Always wrap multi-part text and details inside a single block container such as a <code><div></code> or <code><span></code>.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="clay"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="danger">BLACK WEDGE</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">2. Default Fill in Custom SVG Path Elements</h4> | |
| </div> | |
| </div> | |
| <p class="muted">In SVG, <code><polyline></code> and <code><path></code> elements default to a solid black fill unless configured. Under browsers, this turns line charts into big solid black wedges. The checker statically catches this in <code>svg_chart_mark_presentation</code>. <strong>Fix:</strong> Always set an explicit <code>fill="none"</code> and configure a stroke color on custom line marks.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="clay"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="danger">BASE PATH</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">3. Headless Chrome Relative Resource Failures</h4> | |
| </div> | |
| </div> | |
| <p class="muted">Headless Chrome runs the browser audit on a copy of the HTML inside a temp directory. This causes relative stylesheet links (e.g. <code>styles/birch-system.css</code>) to break, causing a complete lack of styles and throwing false-positive overflow failures. <strong>Fix:</strong> The checker dynamically detects the workspace root and injects an absolute <code><base href="..."></code> tag to preserve stylesheet resolution during the audit.</p> | |
| </article> | |
| </div> | |
| <!-- Extension Points Column --> | |
| <div class="stack" data-gap="md"> | |
| <h3>Pipeline Extension Points</h3> | |
| <article class="card stack" data-variant="outlined" data-accent="sky"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="success">MODIFY</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">Adding a New Static HTML Contract Check</h4> | |
| </div> | |
| </div> | |
| <p class="muted">Create a new parser class extending <code>html.parser.HTMLParser</code> inside <code>scripts/check_birch_renderings.py</code> (similar to <code>MetricRowParser</code>). Instantiate and run it inside the <code>contract_findings()</code> function. If a violation is found, append a <code>Finding("fail", "your_check_name", "evidence detail")</code> object to the return list.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="sky"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="success">MODIFY</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">Extending In-Browser Geometry Audits</h4> | |
| </div> | |
| </div> | |
| <p class="muted">To check for new layout issues (such as text overlapping page margins, icon dimensions, or un-clickable buttons), locate the <code>audit_js</code> string template inside <code>scripts/check_birch_renderings.py</code>. Add a DOM query, compute bounding rectangles via <code>getBoundingClientRect()</code>, flag any alignment defects, and append them to the final serialized JSON inside the <code>data-birch-audit</code> body attribute.</p> | |
| </article> | |
| <article class="card stack" data-variant="outlined" data-accent="sky"> | |
| <div class="card-head"> | |
| <span class="badge" data-tone="success">MODIFY</span> | |
| <div class="card-titles"> | |
| <h4 class="card-title">Updating the System Palette Tolerances</h4> | |
| </div> | |
| </div> | |
| <p class="muted">To expand the canonical color spectrum or adapt to a design token change, adjust the global <code>PALETTE</code> dictionary inside <code>scripts/check_birch_renderings.py</code> (which defines acceptable colors checked by Pillow's palette compliance functions) and coordinate those modifications inside the <code>COLORS</code> and <code>PALETTE</code> configurations in <code>scripts/birch_mpl.py</code>.</p> | |
| </article> | |
| </div> | |
| </div> | |
| </section> | |
| <!-- Section 5: Grounded Diff & Code Evidence --> | |
| <section class="section stack" data-gap="lg"> | |
| <div class="section-head"> | |
| <span class="eyebrow">Implementation Evidence</span> | |
| <h2>Code Modification & Report Payload Concrete Examples</h2> | |
| </div> | |
| <div class="grid" data-cols="2"> | |
| <div class="stack" data-gap="md"> | |
| <h3>Code Example: Adding a Static Contract Check</h3> | |
| <p class="muted">The code patch below demonstrates exactly how a contributor would implement and register a new static contract validation inside <code>scripts/check_birch_renderings.py</code>:</p> | |
| <!-- Canonical Diff Block --> | |
| <div class="diff" data-wrap="true"> | |
| <div class="diff-row hunk"> | |
| <span class="ln"></span><span class="mark"></span><span class="code">@@ -410,6 +410,12 @@ def contract_findings(candidate: Path, stats: PageStats, system_defined_vars: s</span> | |
| </div> | |
| <div class="diff-row ctx"> | |
| <span class="ln">410</span><span class="mark"> </span><span class="code"> check("viewport", stats.viewport, "viewport meta present", "missing viewport meta"),</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">411</span><span class="mark">+</span><span class="code"> check(</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">412</span><span class="mark">+</span><span class="code"> "page_has_valid_gap",</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">413</span><span class="mark">+</span><span class="code"> "lg" in html or "xl" in html,</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">414</span><span class="mark">+</span><span class="code"> "main page has vertical gaps defined",</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">415</span><span class="mark">+</span><span class="code"> "page does not specify spacing gaps via data-gap"</span> | |
| </div> | |
| <div class="diff-row add"> | |
| <span class="ln">416</span><span class="mark">+</span><span class="code"> ),</span> | |
| </div> | |
| <div class="diff-row ctx"> | |
| <span class="ln">417</span><span class="mark"> </span><span class="code"> check(</span> | |
| </div> | |
| <div class="diff-row ctx"> | |
| <span class="ln">418</span><span class="mark"> </span><span class="code"> "uses_birch_system_css",</span> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="stack" data-gap="md"> | |
| <h3>Example Output: JSON Findings Schema</h3> | |
| <p class="muted">The listing below represents an actual serialized segment from a pipeline run report, mapping findings and Pillow screenshot palette measurements to the structured JSON payload:</p> | |
| <pre class="code-block" data-wrap="true"><code>{ | |
| "mode": "artifact", | |
| "artifact": "24-birch-chart-brief.html", | |
| "stats": { | |
| "bytes": 24531, | |
| "title": "Birch chart brief — rendering checker", | |
| "birch_css_valid": true | |
| }, | |
| "screenshot": { | |
| "png": "reports/birch-screenshots/chart-brief-desktop.png", | |
| "size": [1365, 900], | |
| "background_fraction": 0.8142, | |
| "non_background_fraction": 0.1858, | |
| "palette": { | |
| "palette_close_fraction": 0.9841, | |
| "ivory_fraction": 0.8142, | |
| "blackish_fraction": 0.0021 | |
| } | |
| }, | |
| "findings": [ | |
| { | |
| "level": "pass", | |
| "name": "doctype", | |
| "evidence": "doctype present" | |
| }, | |
| { | |
| "level": "pass", | |
| "name": "viewport", | |
| "evidence": "viewport meta present" | |
| } | |
| ] | |
| }</code></pre> | |
| </div> | |
| </div> | |
| </section> | |
| </main> | |
| </body> | |
| </html> | |
Xet Storage Details
- Size:
- 57.4 kB
- Xet hash:
- 2c6c44808ea968f94e94d1c633b32de80504da23fb0cca0630b75566c04b5e34
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.