From 4d89bd426150e054cf42e3c05d6bc75585bcffbb Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Jul 2026 15:55:53 -0700 Subject: [PATCH] docs(prompting): document layout waivers and the contrast-gate side effect --- docs/prompting/rules-and-anti-patterns.mdx | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/prompting/rules-and-anti-patterns.mdx b/docs/prompting/rules-and-anti-patterns.mdx index 9b61c72fa..b83944863 100644 --- a/docs/prompting/rules-and-anti-patterns.mdx +++ b/docs/prompting/rules-and-anti-patterns.mdx @@ -48,6 +48,30 @@ Two more ways an SVG "line draws itself" effect (animated `strokeDasharray` / `s - **Don't declare a multi-value CSS `stroke-dasharray` on the same element GSAP is animating.** GSAP merges dash lists per component, so the CSS gap survives the animation and the draw-on hide only covers one gap's worth — the line stays visible for the whole scene. Put decorative dashing on a separate element if you need both effects. (`svg_drawon_css_dasharray_conflict`, PR [#2611](https://github.com/heygen-com/hyperframes/pull/2611)) - **Give the path a static `d` attribute before anything measures it.** `getTotalLength()` returns 0 in Chrome if the path's `d` isn't set yet — whether because `d` is only assigned inside a function that hasn't run, or never assigned as a static attribute at all — and a dash animation built on a 0-length path is silently dead. (`svg_measure_before_path_d`, PR [#2611](https://github.com/heygen-com/hyperframes/pull/2611)) +## Layout waivers, and the one that bites + +`hyperframes check` flags a text block covered by another element as `text_occluded`, and +two attributes waive it: `data-layout-allow-overlap` for intentional layering, and +`data-layout-allow-occlusion` for something deliberately painted over type. Both are +legitimate — a caption designed to sit behind a matted subject needs one. + +Two things about them are worth knowing before you reach for either: + +- **`data-layout-allow-occlusion` also silences the WCAG contrast gate for that whole + subtree.** Validating this guide's confetti example, moving the attribute onto a cluster + root took contrast coverage from 73 checks to 13 — and a deliberately near-invisible + numeral inside it then passed. Scope the attribute to the narrowest node that needs it, + and check the contrast count afterwards; if it dropped, you have waived more than you + meant to. +- **The occlusion audit is stricter than it looks on atomic labels.** A single glyph — a + digit, a `$`, a `.` — flags at *any* coverage, so one confetti particle grazing one + character is a hard error. `pointer-events: none` does not exempt an element, and a CSS + `mask-image` lets the audit probe through masked-away cells and attribute the occlusion + to whatever paints behind them. + +The cheaper fix is usually compositional: layer a particle burst *behind* the type rather +than over it. The type's ink cuts through, the reading stays clean, and no waiver is needed. + ## Anti-patterns Each one causes friction or wrong output for a specific engine reason — with the fix.