<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>renderlint blog</title>
<subtitle>UI quality checks for the rendered page.</subtitle>
<link href="https://renderlint.yitec.net/feed.xml" rel="self"/>
<link href="https://renderlint.yitec.net/blog/"/>
<id>https://renderlint.yitec.net/blog/</id>
<updated>2026-11-16T00:00:00Z</updated>
<author><name>ngocanhnckh</name><uri>https://github.com/ngocanhnckh</uri></author>
<entry>
<title>How to find text overflow and clipped text in responsive layouts</title>
<link href="https://renderlint.yitec.net/blog/text-overflow-clipped-text-responsive-layouts/"/>
<id>https://renderlint.yitec.net/blog/text-overflow-clipped-text-responsive-layouts/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Text overflows when a box has a fixed width, nowrap or overflow hidden. Check every width, not three, and try longer text, long words and bigger numbers.</summary>
<content type="html">&lt;p&gt;Text overflow happens when a line of text is wider than the box that is meant to hold it. The text either spills past the edge (overflow) or gets cut off by an &lt;code&gt;overflow: hidden&lt;/code&gt; ancestor (clipping). The cause is almost always a rule that stops the text from wrapping or shrinking: a fixed width, &lt;code&gt;white-space: nowrap&lt;/code&gt;, or a flex item that can&amp;#39;t get smaller than its content. To find it reliably you have to look at more than the three screen sizes and the sample data you built the page with.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Fixed &lt;code&gt;width&lt;/code&gt;, &lt;code&gt;height&lt;/code&gt; and &lt;code&gt;white-space: nowrap&lt;/code&gt; on text containers are the usual cause.&lt;/li&gt;
&lt;li&gt;Flex and grid items default to &lt;code&gt;min-width: auto&lt;/code&gt;, so a long unbreakable string stops them from shrinking.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;overflow: hidden&lt;/code&gt; turns a visible spill into silent clipping, which is harder to notice.&lt;/li&gt;
&lt;li&gt;A layout can fit at 375, 768 and 1280px and still break at 1024px, or the moment a real customer has a long name.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-does-text-overflow-its-container&quot;&gt;Why does text overflow its container?&lt;/h2&gt;
&lt;p&gt;A browser lays out text in lines. It can break a line at a space or a hyphen, and nowhere else. When the available width is smaller than the longest piece of text that can&amp;#39;t be broken, one of three things happens:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The box grows to fit (if its width is &lt;code&gt;auto&lt;/code&gt; and nothing limits it).&lt;/li&gt;
&lt;li&gt;The text sticks out of the box (the default for a box with a fixed or constrained width).&lt;/li&gt;
&lt;li&gt;The text is cut off (if the box, or an ancestor, has &lt;code&gt;overflow: hidden&lt;/code&gt; or &lt;code&gt;clip&lt;/code&gt;; with &lt;code&gt;auto&lt;/code&gt; or &lt;code&gt;scroll&lt;/code&gt; you get a scrollbar instead).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Case 2 is &lt;code&gt;text-overflow&lt;/code&gt; in renderlint terms. Case 3 is &lt;code&gt;text-clipped&lt;/code&gt;. A third, quieter state is a string that still fits but has run through the card&amp;#39;s padding and nearly touches the border. renderlint calls that &lt;code&gt;text-crowding&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;which-css-properties-cause-it-most-often&quot;&gt;Which CSS properties cause it most often?&lt;/h3&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;CSS&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;th&gt;Why it breaks&lt;/th&gt;
&lt;th&gt;Safer version&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;white-space: nowrap&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Forbids line breaks&lt;/td&gt;
&lt;td&gt;Text can&amp;#39;t wrap, so it is as wide as it is&lt;/td&gt;
&lt;td&gt;Remove it, or pair it with &lt;code&gt;text-overflow: ellipsis&lt;/code&gt; if truncating is intended&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;width: 300px&lt;/code&gt; on a card&lt;/td&gt;
&lt;td&gt;Fixes the box width&lt;/td&gt;
&lt;td&gt;Wider content spills out&lt;/td&gt;
&lt;td&gt;&lt;code&gt;max-width: 300px&lt;/code&gt;, or a fluid width&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;height: 40px&lt;/code&gt; with &lt;code&gt;line-height: 40px&lt;/code&gt; on a button&lt;/td&gt;
&lt;td&gt;Fixes the box height&lt;/td&gt;
&lt;td&gt;Wrapped text escapes the box&lt;/td&gt;
&lt;td&gt;&lt;code&gt;min-height&lt;/code&gt;, and padding instead of line-height&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Flex or grid item with default &lt;code&gt;min-width: auto&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The item won&amp;#39;t shrink below its longest word&lt;/td&gt;
&lt;td&gt;A long email or ID stretches the column&lt;/td&gt;
&lt;td&gt;&lt;code&gt;min-width: 0&lt;/code&gt; on the item&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;overflow: hidden&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Clips anything outside the box&lt;/td&gt;
&lt;td&gt;Hides the problem instead of showing it&lt;/td&gt;
&lt;td&gt;Let the text wrap, or truncate on purpose&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Large fixed &lt;code&gt;font-size&lt;/code&gt; on numbers&lt;/td&gt;
&lt;td&gt;Big text in a narrow column&lt;/td&gt;
&lt;td&gt;A seven-digit price doesn&amp;#39;t fit a three-column grid at 1024px&lt;/td&gt;
&lt;td&gt;&lt;code&gt;clamp()&lt;/code&gt; with a container query unit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;h3 id=&quot;why-do-flex-and-grid-items-refuse-to-shrink&quot;&gt;Why do flex and grid items refuse to shrink?&lt;/h3&gt;
&lt;p&gt;A flex item&amp;#39;s minimum width is its content&amp;#39;s minimum size, not zero. For text, that is the longest word or unbreakable string. So &lt;code&gt;flex: 1&lt;/code&gt; on a column with &lt;code&gt;dana.whitfield-procurement@northwind-enterprise.example.com&lt;/code&gt; inside it can&amp;#39;t go below the width of that address. The fix is to say the item may shrink:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.card { min-width: 0; }            /* flex or grid child may shrink below its content */
.card p { overflow-wrap: anywhere; } /* and long strings may break anywhere */&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;overflow-wrap: anywhere&lt;/code&gt; also lowers the item&amp;#39;s min-content size, so it works for layout, not just for painting. &lt;code&gt;overflow-wrap: break-word&lt;/code&gt; does not change the min-content size, which is why &lt;code&gt;anywhere&lt;/code&gt; is the better default in flex and grid children.&lt;/p&gt;
&lt;h2 id=&quot;why-does-it-only-break-at-1024px-or-with-real-data&quot;&gt;Why does it only break at 1024px, or with real data?&lt;/h2&gt;
&lt;p&gt;Most developers check the layout at a phone width and a desktop width, with whatever sample text was handy. Two things hide overflow from that approach.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Widths in between.&lt;/strong&gt; A grid that has four columns above 1024px and two below can be squeezed hardest right at the breakpoint, where each column is as narrow as it will ever be while still being a four-column layout. At 1280px the cards are wide. At 768px there are fewer columns. At 1024px, a value like &lt;code&gt;$4,939.27&lt;/code&gt; no longer fits.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-988.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-640.webp 640w, https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-960.webp 960w, https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-988.webp 988w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;988&quot; height=&quot;516&quot; alt=&quot;KPI cards: fine at 1280px, the spend value cut off at 1024px and boxed by renderlint&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;The same dashboard at two widths. At 1280px every value fits; at 1024px the Spend value is cut off by its card. The 1280px view is the one you would have checked by eye.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;&lt;strong&gt;Content you didn&amp;#39;t have.&lt;/strong&gt; Sample data is short. Production data has a company called &amp;quot;Internationale Versicherungsgesellschaft&amp;quot;, a long procurement email address, a revenue number with three more digits than the mock, or a translation that is 50% longer than the English. None of that exists in the development database.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-test-for-it-by-hand&quot;&gt;How do you test for it by hand?&lt;/h2&gt;
&lt;p&gt;You can do a decent job without any tool if you are systematic.&lt;/p&gt;
&lt;h3 id=&quot;sweep-the-widths&quot;&gt;Sweep the widths&lt;/h3&gt;
&lt;p&gt;Drag the browser&amp;#39;s responsive mode from 320px to 1920px slowly. Stop at each breakpoint in your CSS and check both sides of it: if the breakpoint is &lt;code&gt;max-width: 900px&lt;/code&gt;, look at 900 and 901. The failures cluster just above a breakpoint, where a multi-column layout is at its narrowest.&lt;/p&gt;
&lt;h3 id=&quot;stress-the-content&quot;&gt;Stress the content&lt;/h3&gt;
&lt;p&gt;Change the content in dev tools and see what breaks:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// Paste in the console: make every text node 50% longer
const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
for (let n; (n = walker.nextNode()); ) {
  const t = n.textContent.trim();
  if (t.length &amp;gt; 3) n.textContent = t + ' ' + t.slice(0, Math.ceil(t.length / 2));
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then try these cases one at a time:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Stress&lt;/th&gt;
&lt;th&gt;Example&lt;/th&gt;
&lt;th&gt;What it exposes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Longer text&lt;/td&gt;
&lt;td&gt;A button label 50% longer&lt;/td&gt;
&lt;td&gt;Fixed-width buttons, fixed-height cards&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Long unbreakable word&lt;/td&gt;
&lt;td&gt;A 40-character email, URL or ID&lt;/td&gt;
&lt;td&gt;Missing &lt;code&gt;min-width: 0&lt;/code&gt; and &lt;code&gt;overflow-wrap&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Bigger numbers&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$1,284,930.55&lt;/code&gt; instead of &lt;code&gt;$4,939.27&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;KPI tiles and table cells with &lt;code&gt;nowrap&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Long names from the API&lt;/td&gt;
&lt;td&gt;A full legal company name&lt;/td&gt;
&lt;td&gt;Headings in fixed-height cards&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;This is slow, and nobody repeats it after the next refactor.&lt;/p&gt;
&lt;h2 id=&quot;what-does-a-real-defect-look-like&quot;&gt;What does a real defect look like?&lt;/h2&gt;
&lt;p&gt;The example below is a small billing page. It has three KPI cards, an account card with a long email address, and a button. It was run through renderlint at 375, 768 and 1280px with the width sweep and stress passes on.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-overflow-before-f17aa732-375.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-overflow-before-f17aa732-375.webp 375w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;375&quot; height=&quot;399&quot; alt=&quot;A phone-width billing page: the spend value and the invoice count are cut off inside their cards, the email runs past the account card's edge, and the button label runs past its button, each boxed in red and numbered&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;renderlint&amp;#39;s annotated screenshot at 375px. The values are clipped by their cards, the email spills out of the account card and the button label spills out of its button.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;The CSS behind it is the usual suspects:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.kpi .v { font-size: 30px; font-weight: 700; white-space: nowrap; overflow: hidden; }
.acct   { width: 300px; }
.acct p { white-space: nowrap; }
.btn    { display: inline-block; width: 160px; height: 40px; line-height: 40px; white-space: nowrap; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And this is the report, copied exactly from the run:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ text-clipped (1)  Text is partially cut off by an `overflow: hidden` container or the edge of an &amp;lt;svg&amp;gt; (e.g. chart axis labels).&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Text is cut off by an overflow:hidden container (137px past the right edge). (×2 similar elements)
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; div.grid:nth-of-type(1) &amp;gt; div.card.kpi:nth-of-type(1) &amp;gt; div.v:nth-of-type(2)  &amp;quot;$1,284,930.55&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /overflow-before.html · all viewports · see .renderlint/screens/overflow-before-html-1ddxy@375.png #3&lt;/span&gt;

&lt;span class=&quot;e&quot;&gt;✖ text-overflow (2)  Text spills outside the box (card, button, badge, input) that is supposed to contain it.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Text spills outside its container (227px past the right edge).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; div.card.acct:nth-of-type(2) &amp;gt; p:nth-of-type(2)  &amp;quot;Email: dana.whitfield-procurement@northwind-enterprise.example.com&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;      with main &amp;gt; div.card.acct:nth-of-type(2)  &amp;quot;Account Owner: Dana Whitfield Email: dana.whitfiel&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /overflow-before.html · all viewports · see .renderlint/screens/overflow-before-html-1ddxy@375.png #1&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Text spills outside its box (46px past the right edge).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; div.card.acct:nth-of-type(2) &amp;gt; p:nth-of-type(3) &amp;gt; span.btn  &amp;quot;Start your free trial today&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /overflow-before.html · all viewports · see .renderlint/screens/overflow-before-html-1ddxy@375.png #2&lt;/span&gt;

&lt;span class=&quot;e&quot;&gt;✖ viewport-overflow (1)  Content is wider than the viewport: the page scrolls sideways on phones, or content is cut off at the screen edge.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Element extends 4px beyond the 320px viewport, causing horizontal page scroll.
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; div.card.acct:nth-of-type(2)  &amp;quot;Account Owner: Dana Whitfield Email: dana.whitfield-procurement@north…&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /overflow-before.html · at 320px · see .renderlint/screens/overflow-before-html-1ddxy@320.png #5&lt;/span&gt;

&lt;span class=&quot;w&quot;&gt;⚠ fragile-layout (1)  Stress test: the layout breaks with content the sample data doesn't have yet: ~50% longer text, long unbreakable emails/URLs/IDs, numbers with three more digits, longer API data, or the worst case declared with data-renderlint-maxlength / data-renderlint-sample (that last one is an error).&lt;/span&gt;
  &lt;span class=&quot;w&quot;&gt;warn&lt;/span&gt;  With bigger numbers (three more digits): Text is cut off by an overflow:hidden container (34px past the right edge).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; div.grid:nth-of-type(1) &amp;gt; div.card.kpi:nth-of-type(3) &amp;gt; div.v:nth-of-type(2)  &amp;quot;86,000&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /overflow-before.html · at 375px&lt;/span&gt;

&lt;span class=&quot;e&quot;&gt;✖ 5 error(s), 1 warning(s) · screenshots in .renderlint/screens&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Two things in that output are worth reading closely. The email overflow is reported at all widths in the sweep, because the card is a fixed 300px wide. The &lt;code&gt;viewport-overflow&lt;/code&gt; finding only happens at 320px, where the card is 4px wider than the screen. And the &lt;code&gt;fragile-layout&lt;/code&gt; warning is about the third KPI card, which looks fine today: the value is &lt;code&gt;86&lt;/code&gt;, but with three more digits it is clipped. That is a defect the sample data hides.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-fix-text-overflow&quot;&gt;How do you fix text overflow?&lt;/h2&gt;
&lt;p&gt;Give the text a way to wrap, and give the boxes a way to shrink. The fixed version of the page above:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.grid   { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; }
.kpi    { container-type: inline-size; min-width: 0; }
.kpi .v { font-size: clamp(1.25rem, 10cqi, 1.875rem); font-weight: 700; overflow-wrap: anywhere; }
.acct   { max-width: 300px; }
.acct p { overflow-wrap: anywhere; }
.btn    { display: inline-block; padding: 10px 14px; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;What changed and why:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;auto-fit&lt;/code&gt; with &lt;code&gt;minmax(220px, 1fr)&lt;/code&gt;&lt;/strong&gt; replaces a fixed three-column grid. The number of columns follows the available width, so there is no width at which the cards are squeezed to nothing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;clamp()&lt;/code&gt; with &lt;code&gt;cqi&lt;/code&gt;&lt;/strong&gt; sizes the number relative to its card (&lt;code&gt;container-type: inline-size&lt;/code&gt; makes the card a query container), so a longer number gets a smaller font instead of being cut.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;overflow-wrap: anywhere&lt;/code&gt;&lt;/strong&gt; lets the email break inside the card.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;max-width&lt;/code&gt; instead of &lt;code&gt;width&lt;/code&gt;&lt;/strong&gt;, and &lt;strong&gt;padding instead of a fixed height and line-height&lt;/strong&gt; on the button, so a longer label wraps and the button grows.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Re-running renderlint on the fixed page gives the whole report:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;renderlint — 1 page(s) × viewports 375px, 768px, 1280px
&lt;span class=&quot;o&quot;&gt;✔ No UI defects found.&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;when-is-clipping-on-purpose&quot;&gt;When is clipping on purpose?&lt;/h3&gt;
&lt;p&gt;Sometimes you do want to cut text: a table cell, a card title in a dense list. Do it explicitly with &lt;code&gt;text-overflow: ellipsis&lt;/code&gt; or &lt;code&gt;line-clamp&lt;/code&gt;, so the cut is visible as a design choice. A single line looks like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.cell { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 24ch; }&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;renderlint renders each page in headless Chromium at phone, tablet and desktop widths, then measures geometry inside the page: the rectangle of every run of text against its containers and clip boxes. Text outside its box is &lt;code&gt;text-overflow&lt;/code&gt;; text cut by an &lt;code&gt;overflow: hidden&lt;/code&gt; box or the edge of an SVG is &lt;code&gt;text-clipped&lt;/code&gt;; text that fits but runs through the padding is &lt;code&gt;text-crowding&lt;/code&gt;; a page that scrolls sideways is &lt;code&gt;viewport-overflow&lt;/code&gt;. All of these are errors by default. See &lt;a href=&quot;https://renderlint.yitec.net/rules/#text-overflow&quot;&gt;the rules reference&lt;/a&gt; for each rule&amp;#39;s guidance.&lt;/p&gt;
&lt;p&gt;The part that finds the &amp;quot;only at 1024px&amp;quot; and &amp;quot;only with real data&amp;quot; cases is the stress step. It runs these checks:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Check&lt;/th&gt;
&lt;th&gt;What renderlint does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Width sweep&lt;/td&gt;
&lt;td&gt;Re-runs the layout rules at 13 widths from 320 to 1920px and on both sides of every breakpoint the page uses&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Longer text&lt;/td&gt;
&lt;td&gt;Lengthens every text by 50%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Long words&lt;/td&gt;
&lt;td&gt;Turns emails, URLs, domains and IDs into 36+ character strings with no break points&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Big numbers&lt;/td&gt;
&lt;td&gt;Gives KPIs, prices and counters three more digits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Longer API data&lt;/td&gt;
&lt;td&gt;If the page fetched JSON, reloads it with longer names, titles and emails in every response&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Declared worst cases&lt;/td&gt;
&lt;td&gt;&lt;code&gt;data-renderlint-maxlength=&amp;quot;60&amp;quot;&lt;/code&gt; or &lt;code&gt;data-renderlint-sample=&amp;quot;…&amp;quot;&lt;/code&gt; on an element tests exactly that content; failures are errors&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Anything that only breaks under stress becomes a &lt;code&gt;fragile-layout&lt;/code&gt; warning. When a field has a known limit, declare it: &lt;code&gt;&amp;lt;h3 data-renderlint-maxlength=&amp;quot;60&amp;quot;&amp;gt;{project.name}&amp;lt;/h3&amp;gt;&lt;/code&gt;. The attribute does nothing in production.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-hero-overflow-5125f0d1-1240.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-hero-overflow-5125f0d1-640.webp 640w, https://renderlint.yitec.net/img/docs-hero-overflow-5125f0d1-960.webp 960w, https://renderlint.yitec.net/img/docs-hero-overflow-5125f0d1-1240.webp 1240w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1240&quot; height=&quot;750&quot; alt=&quot;Six real findings of text that doesn't fit its box: a long email running off a card, a total cut off at 1024px, a heading running off a phone screen, chart labels cut by the SVG edge, a heading clipped by its card, a feature list spilling out of a pricing card&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;Six findings, each from renderlint&amp;#39;s own annotated screenshots: example pages, apps built in Claude Code sessions, and an Elementor page. Each was a defect that looked fine on the screen it was built on.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;Things renderlint leaves alone on purpose, because they are usually intentional: &lt;code&gt;text-overflow: ellipsis&lt;/code&gt;, &lt;code&gt;line-clamp&lt;/code&gt;, scroll areas, screen-reader-only text. The &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint#limitations&quot; rel=&quot;noopener&quot;&gt;documented limitations&lt;/a&gt; include:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; charts are pixels, so their labels can&amp;#39;t be inspected. Use an SVG renderer for charts you want checked.&lt;/li&gt;
&lt;li&gt;Content behind clicks (dialogs, tabs, filled forms) is only linted when you list it in &lt;code&gt;states&lt;/code&gt; or reach it in a Playwright test.&lt;/li&gt;
&lt;li&gt;A single page takes about 4 to 10 seconds at three viewports with the sweep and stress passes. &lt;code&gt;--sweep 1024&lt;/code&gt; or &lt;code&gt;--no-sweep&lt;/code&gt; gives a faster inner loop.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;is-overflow-hidden-ever-the-right-fix-for-overflowing-text&quot;&gt;Is &lt;code&gt;overflow: hidden&lt;/code&gt; ever the right fix for overflowing text?&lt;/h3&gt;
&lt;p&gt;Only when cutting the text is the design. Then use &lt;code&gt;text-overflow: ellipsis&lt;/code&gt; or &lt;code&gt;line-clamp&lt;/code&gt; so the cut is deliberate. As a way to make an overflow warning go away, it replaces a visible bug with a hidden one.&lt;/p&gt;
&lt;h3 id=&quot;what-is-the-difference-between-overflow-wrap-anywhere-and-word-break-break-all&quot;&gt;What is the difference between &lt;code&gt;overflow-wrap: anywhere&lt;/code&gt; and &lt;code&gt;word-break: break-all&lt;/code&gt;?&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;overflow-wrap: anywhere&lt;/code&gt; breaks a word only when it would not fit on a line, and it also reduces the item&amp;#39;s minimum content size in flex and grid. &lt;code&gt;word-break: break-all&lt;/code&gt; breaks every word at any character, even when it would have fit, which makes normal text ugly.&lt;/p&gt;
&lt;h3 id=&quot;should-i-fix-a-fragile-layout-warning-if-the-page-looks-fine&quot;&gt;Should I fix a &lt;code&gt;fragile-layout&lt;/code&gt; warning if the page looks fine?&lt;/h3&gt;
&lt;p&gt;It means the page broke under content it doesn&amp;#39;t have yet, such as a longer name or a bigger number. If that content is realistic, fix it. If it is not, say so with &lt;code&gt;data-renderlint-maxlength&lt;/code&gt; and fix the limit instead.&lt;/p&gt;
</content>
</entry>
<entry>
<title>How to measure color contrast on gradients and background images</title>
<link href="https://renderlint.yitec.net/blog/color-contrast-gradients-images/"/>
<id>https://renderlint.yitec.net/blog/color-contrast-gradients-images/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Text on a gradient or photo has no single background color. Measure the pixels behind each glyph, compare to WCAG AA 4.5:1 and 3:1, then fix the background.</summary>
<content type="html">&lt;p&gt;To measure contrast on a gradient or a background image, you have to measure the pixels behind the text, not the CSS. WCAG 2 compares the text color with the background color, and a gradient or photo has many background colors. Tools that read only the DOM and computed styles can&amp;#39;t know which one sits behind each letter, so they report &amp;quot;needs review&amp;quot;. The reliable method is to render the page, remove the text, and read the real background pixels where each glyph was.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WCAG 2 AA needs 4.5:1 for normal text and 3:1 for large text.&lt;/li&gt;
&lt;li&gt;White text on a light-to-mid blue gradient fails in the light half, even if the dark end passes.&lt;/li&gt;
&lt;li&gt;A &lt;code&gt;text-shadow&lt;/code&gt; is not a fix: the formula compares the text color and the background, and a shadow is neither.&lt;/li&gt;
&lt;li&gt;The fix is a darker background, a darker set of gradient stops, or a scrim between the image and the text.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-contrast-ratio-does-wcag-require&quot;&gt;What contrast ratio does WCAG require?&lt;/h2&gt;
&lt;p&gt;WCAG 2 defines contrast as a ratio between the relative luminance of two colors, from 1:1 (identical) to 21:1 (black on white). The formula is:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;ratio = (L1 + 0.05) / (L2 + 0.05)     L1 = the lighter color's luminance, L2 = the darker one's
L = 0.2126 R + 0.7152 G + 0.0722 B     R, G, B linearised from the sRGB values&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The thresholds come from success criteria 1.4.3 (AA) and 1.4.6 (AAA):&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Text&lt;/th&gt;
&lt;th&gt;AA (the usual target)&lt;/th&gt;
&lt;th&gt;AAA&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Normal text&lt;/td&gt;
&lt;td&gt;4.5:1&lt;/td&gt;
&lt;td&gt;7:1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Large text: 24px and up, or 18.66px and up in bold&lt;/td&gt;
&lt;td&gt;3:1&lt;/td&gt;
&lt;td&gt;4.5:1&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;renderlint checks AA by default, and AAA when you set &lt;code&gt;&amp;quot;contrastLevel&amp;quot;: &amp;quot;AAA&amp;quot;&lt;/code&gt; in its config. Large text gets its lower threshold from the size and weight, which is why the same gradient can fail a caption and pass a headline.&lt;/p&gt;
&lt;h2 id=&quot;why-do-axe-and-lighthouse-say-needs-review-on-gradients&quot;&gt;Why do axe and Lighthouse say &amp;quot;needs review&amp;quot; on gradients?&lt;/h2&gt;
&lt;p&gt;Those tools read the DOM. For each text node they find the computed &lt;code&gt;color&lt;/code&gt; and walk up the ancestors to find a &lt;code&gt;background-color&lt;/code&gt;. That works when the background is one flat color. A &lt;code&gt;linear-gradient()&lt;/code&gt; is not a color: it is an image the browser paints. A &lt;code&gt;background-image: url(...)&lt;/code&gt;, a translucent overlay, or a &lt;code&gt;backdrop-filter&lt;/code&gt; glass panel is the same. The color at a given letter depends on where that letter lands, and the DOM does not say.&lt;/p&gt;
&lt;p&gt;So the tool cannot compute a ratio and, rather than guess, marks the element for manual review. That is the right thing for a tool that only has styles, and it is why a hero section with white text over a gradient so often ships without anyone measuring it. renderlint&amp;#39;s approach is different: it measures contrast from the real pixels behind each glyph, so a gradient or an image is not a special case.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-measure-contrast-on-a-gradient-by-hand&quot;&gt;How do you measure contrast on a gradient by hand?&lt;/h2&gt;
&lt;p&gt;Take a screenshot, then sample a color from the background next to or behind the text, at the lightest part of the area the text covers. Compare that against the text color with any WCAG calculator. Do it for the worst case, not the average: the ratio that matters is the lowest one under any letter.&lt;/p&gt;
&lt;p&gt;For the gradient below, you can compute the stops directly. White text (&lt;code&gt;#ffffff&lt;/code&gt;) against each stop of &lt;code&gt;linear-gradient(135deg, #bae6fd 0%, #60a5fa 55%, #2563eb 100%)&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Gradient stop&lt;/th&gt;
&lt;th&gt;White text contrast (computed with the formula above)&lt;/th&gt;
&lt;th&gt;Passes 4.5:1?&lt;/th&gt;
&lt;th&gt;Passes 3:1?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;#bae6fd&lt;/code&gt; (0%)&lt;/td&gt;
&lt;td&gt;1.33:1&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;#60a5fa&lt;/code&gt; (55%)&lt;/td&gt;
&lt;td&gt;2.54:1&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;#2563eb&lt;/code&gt; (100%)&lt;/td&gt;
&lt;td&gt;5.17:1&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;White text reaches 3:1 only about 70% of the way along the gradient and 4.5:1 only in the last 8% or so (interpolating the stops in sRGB). Anything placed on the light side of the hero is not readable. And in practice the text sits on the left.&lt;/p&gt;
&lt;h2 id=&quot;what-does-the-problem-look-like-on-a-real-page&quot;&gt;What does the problem look like on a real page?&lt;/h2&gt;
&lt;p&gt;The page here is a small weather card: a heading, a sentence and four day tiles over that exact gradient. Day tiles use &lt;code&gt;rgba(255,255,255,.25)&lt;/code&gt;, which makes the background under the text lighter still. It was checked at 375, 768 and 1280px; the screenshot below is the 768px one.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-contrast-before-08162bdb-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-contrast-before-08162bdb-640.webp 640w, https://renderlint.yitec.net/img/captures-contrast-before-08162bdb-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;299&quot; alt=&quot;A blue weather card with a light-blue to deep-blue gradient: the heading Lisbon 21 degrees, a sentence about the wind and four day tiles are each outlined in red and numbered, ten findings in all&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;renderlint&amp;#39;s annotated screenshot at 768px. Every piece of text is boxed: all of it is white or near-white on the light, mid-blue part of the gradient.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;The first three of the ten findings from the run, copied from its output:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ contrast (10)  Text does not have enough contrast with what is actually behind it (WCAG AA: 4.5:1, or 3:1 for large text). Measured from real rendered pixels, so it works over gradients and images.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Low text contrast: 1.64:1, needs 3:1 — #ffffff on a non-uniform background (≈#9bd0fc).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; section.hero &amp;gt; h1  &amp;quot;Lisbon, 21°&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /contrast-before.html · all viewports · see .renderlint/screens/contrast-before-html-eaveh@375.png #1&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;       fix use background #7096b5 (currently #ffffff on #9bd0fc)&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Low text contrast: 1.59:1, needs 4.5:1 — #e0f2fe on a non-uniform background (≈#8dc5fb).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; section.hero &amp;gt; p  &amp;quot;Light breeze from the north-west. Clear skies until the evening.&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /contrast-before.html · all viewports · see .renderlint/screens/contrast-before-html-eaveh@375.png #2&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;       fix use background #4f6e8d (currently #e0f2fe on #8dc5fb)&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Low text contrast: 1.66:1, needs 4.5:1 — #ffffff on a non-uniform background (≈#a0cdfc).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; section.hero &amp;gt; div.days &amp;gt; div.day:nth-of-type(1)  &amp;quot;Tue 22° Sunny&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /contrast-before.html · all viewports · see .renderlint/screens/contrast-before-html-eaveh@375.png #3&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;       fix use background #5d7792 (currently #ffffff on #a0cdfc)&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Read the first finding closely. The heading is large text, so it needs 3:1, not 4.5:1, and it still gets 1.64:1. The color in parentheses, &lt;code&gt;≈#9bd0fc&lt;/code&gt;, is the background renderlint measured behind that text. It is not a color in your CSS. Your stylesheet has &lt;code&gt;#bae6fd&lt;/code&gt;, &lt;code&gt;#60a5fa&lt;/code&gt; and &lt;code&gt;#2563eb&lt;/code&gt;; the pixels under &amp;quot;Lisbon, 21°&amp;quot; were closest to &lt;code&gt;#9bd0fc&lt;/code&gt;. And because the background is not uniform, the suggested fix is a background color, not a text color: you can&amp;#39;t make white text more readable than &amp;quot;as white as possible&amp;quot;.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-fix-low-contrast-on-a-gradient-or-an-image&quot;&gt;How do you fix low contrast on a gradient or an image?&lt;/h2&gt;
&lt;p&gt;Change what is behind the text, not the text. Four options, in order of how often they are right:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;th&gt;How&lt;/th&gt;
&lt;th&gt;Trade-off&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Darker gradient stops&lt;/td&gt;
&lt;td&gt;Keep the hue, lower the lightness of every stop the text covers&lt;/td&gt;
&lt;td&gt;Changes the look of the hero&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A scrim&lt;/td&gt;
&lt;td&gt;A semi-transparent dark layer between the image and the text&lt;/td&gt;
&lt;td&gt;Dims the whole image&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Move the text&lt;/td&gt;
&lt;td&gt;Put it on the part of the image that is dark enough, or on a solid panel&lt;/td&gt;
&lt;td&gt;Needs a layout change&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Change the text color&lt;/td&gt;
&lt;td&gt;Dark text on a light gradient, light text on a dark one&lt;/td&gt;
&lt;td&gt;Only works if the whole area is on one side of the line&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;A scrim in CSS is a second background layer:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.hero {
  background:
    linear-gradient(rgb(0 0 0 / 0.45), rgb(0 0 0 / 0.45)),  /* the scrim */
    url(&amp;quot;/img/hero.jpg&amp;quot;) center / cover;
  color: #fff;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Make the scrim just dark enough that the lightest part of the image under the text reaches 4.5:1. Measure that part, not the average of the photo.&lt;/p&gt;
&lt;h3 id=&quot;is-a-text-shadow-a-fix&quot;&gt;Is a text-shadow a fix?&lt;/h3&gt;
&lt;p&gt;No. WCAG 2&amp;#39;s contrast formula compares the text color with the background color. A shadow changes neither. It can make letters easier to pick out, but it does not change the ratio, and a checker that follows the formula will keep failing the page. If you add a shadow in addition to a proper scrim, that is fine. As the only fix, it is a workaround.&lt;/p&gt;
&lt;h3 id=&quot;the-fixed-version&quot;&gt;The fixed version&lt;/h3&gt;
&lt;p&gt;The fix for the page above changed three things. The gradient stops went to &lt;code&gt;#1d4ed8&lt;/code&gt;, &lt;code&gt;#1e40af&lt;/code&gt; and &lt;code&gt;#1e3a8a&lt;/code&gt;. The day tiles went from 25% white to 12% white, so they no longer lighten the area under the text. The small text went from &lt;code&gt;#f0f9ff&lt;/code&gt; at 85% opacity to &lt;code&gt;#dbeafe&lt;/code&gt;.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;/* before */
.hero  { background: linear-gradient(135deg, #bae6fd 0%, #60a5fa 55%, #2563eb 100%); color: #fff; }
.day   { background: rgba(255,255,255,.25); }
.day small { color: #f0f9ff; opacity: .85; }

/* after */
.hero  { background: linear-gradient(135deg, #1d4ed8 0%, #1e40af 55%, #1e3a8a 100%); color: #fff; }
.day   { background: rgba(255,255,255,.12); }
.day small { color: #dbeafe; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;White on the lightest new stop, &lt;code&gt;#1d4ed8&lt;/code&gt;, is 6.7:1 by the formula, and on &lt;code&gt;#1e3a8a&lt;/code&gt; it is 10.36:1. The re-run is clean:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;renderlint — 1 page(s) × viewports 375px, 768px, 1280px
&lt;span class=&quot;o&quot;&gt;✔ No UI defects found.&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;why-does-this-matter-more-with-ai-generated-ui&quot;&gt;Why does this matter more with AI-generated UI?&lt;/h2&gt;
&lt;p&gt;Contrast was the most common defect in renderlint&amp;#39;s own experiment. In the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/results.md&quot; rel=&quot;noopener&quot;&gt;experiment&amp;#39;s write-up&lt;/a&gt;, 22 headless Claude Code sessions each built a frontend, half of them with renderlint. The 11 baseline apps had 229 errors between them, almost all of them WCAG contrast failures: muted gray captions, orange labels on white, white text on light accent colors, chart axis ticks, and text on gradients. The weather app alone had 42 errors, mostly light text on a blue gradient.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1656.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-640.webp 640w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-960.webp 960w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1280.webp 1280w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1656.webp 1656w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1656&quot; height=&quot;578&quot; alt=&quot;The same weather-app prompt in two sessions. Left, without renderlint: 42 errors, light text on a blue gradient and gray captions, each boxed. Right, with renderlint: 0 errors&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;The same prompt in two sessions. Left: no renderlint, 42 contrast errors. Right: the session that ran renderlint and fixed its own findings.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;Contrast failures are hard to see on a good monitor and easy to miss in review. In those sessions, once the agent was given the numbers (&lt;code&gt;2.66:1, needs 4.5:1&lt;/code&gt;) and a suggested color, it fixed them in one pass.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;The &lt;code&gt;contrast&lt;/code&gt; rule is an error by default. For contrast, renderlint captures the page twice: once normally and once with all text made transparent. The second capture shows the real background behind each glyph, including gradients, images, translucent overlays and glass effects, and renderlint compares the text color with those pixels. On a flat background it does not need the screenshot: where the background provably is one flat color, contrast is measured from styles, which is faster.&lt;/p&gt;
&lt;p&gt;What it does and doesn&amp;#39;t do:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It follows WCAG 2 AA math (4.5:1, or 3:1 for large text) and can be set to AAA with &lt;code&gt;contrastLevel&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It doesn&amp;#39;t model font weight beyond the large-text rule, and it doesn&amp;#39;t apply APCA (see the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint#limitations&quot; rel=&quot;noopener&quot;&gt;documented limitations&lt;/a&gt;). If your team has adopted APCA, renderlint&amp;#39;s numbers are a WCAG 2 floor, not APCA scores.&lt;/li&gt;
&lt;li&gt;Dark mode is rendered too when your CSS has &lt;code&gt;prefers-color-scheme: dark&lt;/code&gt;. The rule&amp;#39;s own guidance is to check dark mode separately.&lt;/li&gt;
&lt;li&gt;When contrast is intentional (a watermark, a teaser), mark it with &lt;code&gt;data-renderlint-ignore=&amp;quot;contrast&amp;quot;&lt;/code&gt; and a &lt;code&gt;data-renderlint-reason&lt;/code&gt;, or &lt;code&gt;--renderlint-ignore: contrast&lt;/code&gt; in CSS. An ignore is reviewed like an &lt;code&gt;eslint-disable&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;npx renderlint explain contrast&lt;/code&gt; prints the rule&amp;#39;s meaning and fix in the terminal. The full entry is in &lt;a href=&quot;https://renderlint.yitec.net/rules/#contrast&quot;&gt;the rules reference&lt;/a&gt;, and other examples are on &lt;a href=&quot;https://renderlint.yitec.net/examples/&quot;&gt;the examples page&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;what-contrast-ratio-do-i-need-for-text-on-an-image&quot;&gt;What contrast ratio do I need for text on an image?&lt;/h3&gt;
&lt;p&gt;The same as anywhere else under WCAG 2 AA: 4.5:1 for normal text, 3:1 for large text. What changes is that the background varies, so the ratio has to hold at the lightest part of the image under the text.&lt;/p&gt;
&lt;h3 id=&quot;does-a-bigger-font-size-lower-the-requirement&quot;&gt;Does a bigger font size lower the requirement?&lt;/h3&gt;
&lt;p&gt;Yes, but only past the large-text line: 24px and up, or 18.66px and up in bold. Under that, 4.5:1 applies, however heavy the weight.&lt;/p&gt;
&lt;h3 id=&quot;can-i-trust-a-contrast-checker-that-gives-one-color-for-a-gradient&quot;&gt;Can I trust a contrast checker that gives one color for a gradient?&lt;/h3&gt;
&lt;p&gt;Only if the gradient is narrow enough that one color is a fair sample. For a wide gradient, a single sampled color is a guess. Check the lightest and darkest regions the text covers, or use a tool that reads the pixels.&lt;/p&gt;
&lt;h3 id=&quot;do-i-need-a-scrim-if-my-image-is-already-dark&quot;&gt;Do I need a scrim if my image is already dark?&lt;/h3&gt;
&lt;p&gt;Not if the ratio holds under every part of the text. Photos are rarely uniform, though, so measure it rather than judge it by eye.&lt;/p&gt;
</content>
</entry>
<entry>
<title>Content you can't scroll to: 100vh app shells, scroll locks and tall modals</title>
<link href="https://renderlint.yitec.net/blog/content-you-cant-scroll-to/"/>
<id>https://renderlint.yitec.net/blog/content-you-cant-scroll-to/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Why content past a fixed-height shell can't be scrolled to, which CSS causes it (100vh, overflow hidden, min-height, scroll locks), and how to fix it.</summary>
<content type="html">&lt;p&gt;Unreachable content is content that is rendered but that no one can scroll to. It happens when a box clips its overflow (&lt;code&gt;overflow: hidden&lt;/code&gt;), nothing inside or around it scrolls, and the content is taller than the box. The page looks complete, there is no scrollbar and no error, and everything below the edge of the screen simply does not exist for the user. The usual causes are a &lt;code&gt;height: 100vh; overflow: hidden&lt;/code&gt; app shell whose inner area never became a scroller, a scroll lock that was never released, and fixed-height cards.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The content is in the DOM and painted, so tests that look for it pass.&lt;/li&gt;
&lt;li&gt;No error is raised, and at a short list length the page looks right.&lt;/li&gt;
&lt;li&gt;It appears when the data grows: a short list fits, a long one doesn&amp;#39;t.&lt;/li&gt;
&lt;li&gt;The fix is to make exactly one area the scroller, and let it shrink to the space it has.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-cant-users-scroll-to-some-content&quot;&gt;Why can&amp;#39;t users scroll to some content?&lt;/h2&gt;
&lt;p&gt;Scrolling needs a scroll container: a box with &lt;code&gt;overflow: auto&lt;/code&gt; or &lt;code&gt;scroll&lt;/code&gt; whose content is taller than its height. &lt;code&gt;overflow: hidden&lt;/code&gt; creates a box that clips but gives the user no scrollbar and no wheel or touch scrolling. The clipped part is simply out of reach. (A script, or keyboard focus moving into the box, can still scroll it, which is why a visible clip does not always mean lost content.)&lt;/p&gt;
&lt;p&gt;An app shell makes this easy to do by accident. The shell is given the height of the window so the sidebar and header stay put, and the content area is meant to scroll inside it. If the content area is &lt;code&gt;overflow: hidden&lt;/code&gt;, or is a flex item that grew past its parent, nothing between the content and the screen is a scroller. The page itself doesn&amp;#39;t scroll either, because the shell is exactly one screen tall and clips the rest.&lt;/p&gt;
&lt;h3 id=&quot;the-common-causes&quot;&gt;The common causes&lt;/h3&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;What you wrote&lt;/th&gt;
&lt;th&gt;What happens&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Shell with no scroller&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.app { height: 100vh; overflow: hidden }&lt;/code&gt; and the content area has &lt;code&gt;overflow: hidden&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Everything past the first screenful is clipped&lt;/td&gt;
&lt;td&gt;&lt;code&gt;overflow-y: auto&lt;/code&gt; on the content area&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Flex or grid child grows&lt;/td&gt;
&lt;td&gt;A flex child with &lt;code&gt;flex: 1&lt;/code&gt; and long content, no &lt;code&gt;min-height: 0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The child&amp;#39;s minimum height is its content&amp;#39;s height, so it grows past the shell instead of scrolling&lt;/td&gt;
&lt;td&gt;&lt;code&gt;flex: 1 1 0%; min-height: 0&lt;/code&gt; on the child&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Scroll lock left on&lt;/td&gt;
&lt;td&gt;&lt;code&gt;body { overflow: hidden }&lt;/code&gt; set when a menu or modal opened, not removed when it closed&lt;/td&gt;
&lt;td&gt;The page can&amp;#39;t scroll at all&lt;/td&gt;
&lt;td&gt;Remove the lock when what set it closes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fixed-height card&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.card { height: 320px; overflow: hidden }&lt;/code&gt; around a list&lt;/td&gt;
&lt;td&gt;The list&amp;#39;s remaining rows are hidden&lt;/td&gt;
&lt;td&gt;Remove the height, or make the card&amp;#39;s list the scroller&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tall modal on a phone&lt;/td&gt;
&lt;td&gt;A dialog taller than the screen with no scrolling&lt;/td&gt;
&lt;td&gt;The buttons at the bottom are below the screen&lt;/td&gt;
&lt;td&gt;&lt;code&gt;max-height: 100dvh&lt;/code&gt; and &lt;code&gt;overflow-y: auto&lt;/code&gt; on the dialog body&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;h3 id=&quot;why-does-flex-need-min-height-0&quot;&gt;Why does flex need &lt;code&gt;min-height: 0&lt;/code&gt;?&lt;/h3&gt;
&lt;p&gt;A flex item&amp;#39;s automatic minimum size is its content size. In a column flex container, a child with long content will not shrink below that content&amp;#39;s height, so &lt;code&gt;flex: 1&lt;/code&gt; does not make it fit: it grows, and its parent clips it. Setting &lt;code&gt;min-height: 0&lt;/code&gt; removes the content-based minimum, and then &lt;code&gt;overflow-y: auto&lt;/code&gt; has a height to scroll within. Grid rows behave the same way, and the fix there is &lt;code&gt;min-height: 0&lt;/code&gt; on the row&amp;#39;s item or &lt;code&gt;minmax(0, 1fr)&lt;/code&gt; for the track.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.app    { display: grid; grid-template-columns: 200px 1fr; height: 100vh; overflow: hidden; }
.mainc  { display: flex; flex-direction: column; min-height: 0; }
.screen { flex: 1 1 0%; min-height: 0; overflow-y: auto; }  /* the one scroller */&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;is-100vh-itself-a-problem-on-phones&quot;&gt;Is &lt;code&gt;100vh&lt;/code&gt; itself a problem on phones?&lt;/h3&gt;
&lt;p&gt;It can be. On mobile browsers, &lt;code&gt;100vh&lt;/code&gt; is the height of the viewport with the address bar hidden, so a shell sized with it can be taller than the visible area while the bar is showing. &lt;code&gt;100dvh&lt;/code&gt; (dynamic viewport height) follows the visible area. Use &lt;code&gt;height: 100dvh&lt;/code&gt; for the shell, and keep a &lt;code&gt;100vh&lt;/code&gt; fallback line above it for older browsers.&lt;/p&gt;
&lt;h2 id=&quot;what-does-it-look-like-in-a-real-app&quot;&gt;What does it look like in a real app?&lt;/h2&gt;
&lt;p&gt;Here is a small order-management page: a sidebar, a header and a list of 24 orders. The shell is &lt;code&gt;height: 100vh; overflow: hidden&lt;/code&gt;, and the area holding the orders is a flex column with &lt;code&gt;overflow: hidden&lt;/code&gt; too. It was checked at 375, 768 and 1280px; the screenshot below is the 1280px one.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-unreachable-before-3aa28d73-1280.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-unreachable-before-3aa28d73-640.webp 640w, https://renderlint.yitec.net/img/captures-unreachable-before-3aa28d73-960.webp 960w, https://renderlint.yitec.net/img/captures-unreachable-before-3aa28d73-1280.webp 1280w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1280&quot; height=&quot;800&quot; alt=&quot;A Shopdesk orders screen at 1280px wide: a dark sidebar, an Orders header and a column of order cards from #4801 to #4809, the ninth cut by the bottom edge of the window, with a red outline around the list area and no scrollbar&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;renderlint&amp;#39;s annotated screenshot at 1280px. The red outline is the box that clips. Order #4809 stops at the screen edge and the orders after it can&amp;#39;t be reached.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;The markup and CSS of the broken area:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.app    { display: grid; grid-template-columns: 200px 1fr; height: 100vh; overflow: hidden; }
.mainc  { display: flex; flex-direction: column; overflow: hidden; min-height: 0; }
.screen { flex: 1; display: flex; flex-direction: column; overflow: hidden; min-height: 0; padding: 16px 20px; }
.panel  { display: flex; flex-direction: column; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Here &lt;code&gt;min-height: 0&lt;/code&gt; is already in place. The missing piece is the scroller: &lt;code&gt;.screen&lt;/code&gt; is &lt;code&gt;overflow: hidden&lt;/code&gt;, so it clips the panel instead of scrolling it. Both halves of the fix are needed in general, but a page that has one and not the other is broken in the same way.&lt;/p&gt;
&lt;p&gt;This is the report from the run, copied exactly:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;renderlint — 1 page(s) × viewports 375px, 768px, 1280px

&lt;span class=&quot;e&quot;&gt;✖ unreachable-content (1)  Content lies below the bottom of a box that clips (`overflow: hidden` or `clip`), or below the screen on a page that doesn't scroll, and nothing around it scrolls: users can never see it. Typical causes: a fixed-height app shell (`height: 100vh; overflow: hidden`) whose page or tab area isn't a scroller, or a scroll lock (`body { overflow: hidden }`) left on. Before reporting, renderlint turns the mouse wheel over the box: content that a script scrolls is not reported. Not reported: content moved away on purpose (transformed, absolute or fixed), small boxes (teasers, collapsed panels), boxes with a &amp;quot;Show more&amp;quot; control, faded or line-clamped text, and the page while a dialog is open.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Content can't be scrolled to: 30 pieces of text, reaching 1224px below the bottom of this box (overflow-y: hidden), and neither it nor anything around the content scrolls (&amp;quot;Order #4810&amp;quot;, &amp;quot;Shipped to Porto, 2 items, paid by card.&amp;quot;, &amp;quot;Order #4811&amp;quot;).
&lt;span class=&quot;d&quot;&gt;        at div.app &amp;gt; div.mainc &amp;gt; section  &amp;quot;Order #4801 Shipped to Porto, 2 items, paid by card. Order #4802 Ship…&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /unreachable-before.html · all viewports · see .renderlint/screens/unreachable-before-html-29ad6@375.png #1&lt;/span&gt;

How to fix
  unreachable-content: Make the area that grows scroll: `overflow-y: auto` on it, and in a flex or grid layout let it shrink to the space it has (`flex: 1 1 0%; min-height: 0`, or `min-height: 0` on the grid row) so it doesn't just grow past its parent. Or remove the fixed height so the page scrolls. Remove a scroll lock when what set it closes.

If a finding is intentional, mark the element: data-renderlint-ignore=&amp;quot;&amp;lt;rule&amp;gt;&amp;quot; (space-separated, or empty for all rules), or in CSS: --renderlint-ignore: &amp;lt;rule&amp;gt;; — both apply to the element and its descendants. Add data-renderlint-reason=&amp;quot;…&amp;quot; to explain why.

&lt;span class=&quot;e&quot;&gt;✖ 1 error(s), 0 warnings · screenshots in .renderlint/screens&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The finding names the box (&lt;code&gt;div.app &amp;gt; div.mainc &amp;gt; section&lt;/code&gt;), the property that clips it (&lt;code&gt;overflow-y: hidden&lt;/code&gt;), how far the content goes past the bottom (1224px) and which text is lost. The three quoted strings are examples of the lost text, not the full list.&lt;/p&gt;
&lt;p&gt;The fix is one line of intent: the content area becomes the scroller.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;/* before */
.screen { flex: 1; display: flex; flex-direction: column; overflow: hidden; min-height: 0; padding: 16px 20px; }

/* after */
.screen { flex: 1 1 0%; min-height: 0; overflow-y: auto; padding: 16px 20px; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Run again, the page is clean:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;renderlint — 1 page(s) × viewports 375px, 768px, 1280px
&lt;span class=&quot;o&quot;&gt;✔ No UI defects found.&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;what-about-scroll-locks-and-tall-modals&quot;&gt;What about scroll locks and tall modals?&lt;/h2&gt;
&lt;p&gt;A scroll lock is a way of stopping the page from scrolling behind an open menu or modal: &lt;code&gt;document.body.style.overflow = &amp;#39;hidden&amp;#39;&lt;/code&gt;, or a class that does the same. The bug is not the lock, it&amp;#39;s the code path that skips the release: the modal is closed by Escape, by a route change, or by an unmount, and the cleanup that restores &lt;code&gt;overflow&lt;/code&gt; never runs. The page is then stuck at whatever was on screen when it happened.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// Restore what was there before, and do it in every close path
function lockScroll() {
  const prev = document.body.style.overflow;
  document.body.style.overflow = 'hidden';
  return () =&amp;gt; { document.body.style.overflow = prev; };
}

// React: the cleanup runs on unmount, Escape, route change, everything
useEffect(() =&amp;gt; (open ? lockScroll() : undefined), [open]);&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A tall modal has the opposite problem: the dialog is meant to hold its own scroll, and on a phone it is taller than the screen. Give the panel a height limit and a scroller:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.modal-panel { max-height: 100dvh; display: flex; flex-direction: column; }
.modal-body  { overflow-y: auto; min-height: 0; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Keep the title and the action buttons outside &lt;code&gt;.modal-body&lt;/code&gt; so they stay in view.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-demo-unreachable-1f87a2fc-1200.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-demo-unreachable-1f87a2fc-640.webp 640w, https://renderlint.yitec.net/img/docs-demo-unreachable-1f87a2fc-960.webp 960w, https://renderlint.yitec.net/img/docs-demo-unreachable-1f87a2fc-1200.webp 1200w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1200&quot; height=&quot;580&quot; alt=&quot;Left: a run dashboard whose Findings tab stops at the screen edge with no scrollbar. Right: the same tab with the clipped part shaded as never reachable, next to renderlint's unreachable-content finding naming 62 pieces of text reaching 2644px below the box&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;A tab inside a fixed-height shell that never became a scroller. The shaded part is painted but can&amp;#39;t be reached.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;unreachable-content&lt;/code&gt; is an error by default. The rule looks for content lying below the bottom of a box that clips (&lt;code&gt;overflow: hidden&lt;/code&gt; or &lt;code&gt;clip&lt;/code&gt;), or below the screen on a page that doesn&amp;#39;t scroll, where nothing around it scrolls. It reads rendered geometry, so it does not depend on how the CSS got there: a shell, a scroll lock or a fixed-height card all show up the same way.&lt;/p&gt;
&lt;p&gt;The part that keeps it quiet is the mouse-wheel check. Before reporting a box, renderlint turns the mouse wheel over it. If something scrolls, the content is reachable and is not reported. That covers custom scrollbars and scroll-jacking pages, where a script moves the content and the CSS alone looks like a clip.&lt;/p&gt;
&lt;p&gt;What it deliberately does not report:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;content moved away on purpose (transformed, absolute or fixed);&lt;/li&gt;
&lt;li&gt;small boxes such as teasers and collapsed panels;&lt;/li&gt;
&lt;li&gt;boxes with a &amp;quot;Show more&amp;quot; control;&lt;/li&gt;
&lt;li&gt;faded or line-clamped text;&lt;/li&gt;
&lt;li&gt;the page while a dialog is open.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;When a clipped box&amp;#39;s bottom edge also cut text, the &lt;code&gt;text-clipped&lt;/code&gt; finding for it is folded into this one. When it was added, it was run on 99 benchmark pages and the 50 existing test targets and reported nothing new on any of them, which is the false-positive check that matters for an error-level rule.&lt;/p&gt;
&lt;p&gt;One limit worth knowing (see the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint#limitations&quot; rel=&quot;noopener&quot;&gt;documented limitations&lt;/a&gt;): pages are checked as they load, with each menu opened. Dialogs, tabs and filled forms are rendered by &lt;code&gt;--ux&lt;/code&gt;, but their layout is only linted when you list them in &lt;code&gt;states&lt;/code&gt; or reach them in a &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/playwright.md&quot; rel=&quot;noopener&quot;&gt;Playwright test&lt;/a&gt;. So a tall modal is not checked unless you take the page to that state. See &lt;a href=&quot;https://renderlint.yitec.net/rules/#unreachable-content&quot;&gt;the rules reference&lt;/a&gt;, and &lt;a href=&quot;https://renderlint.yitec.net/examples/&quot;&gt;the examples&lt;/a&gt; for more.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;why-doesnt-the-page-scroll-when-the-content-is-taller-than-the-window&quot;&gt;Why doesn&amp;#39;t the page scroll when the content is taller than the window?&lt;/h3&gt;
&lt;p&gt;Because something clips it. Either the shell is &lt;code&gt;height: 100vh&lt;/code&gt; with &lt;code&gt;overflow: hidden&lt;/code&gt;, or &lt;code&gt;html&lt;/code&gt; and &lt;code&gt;body&lt;/code&gt; have &lt;code&gt;overflow: hidden&lt;/code&gt; (a scroll lock). The page scrolls only if the document is taller than the viewport and neither &lt;code&gt;html&lt;/code&gt; nor &lt;code&gt;body&lt;/code&gt; is clipping.&lt;/p&gt;
&lt;h3 id=&quot;is-it-a-problem-if-a-box-clips-but-has-a-show-more-button&quot;&gt;Is it a problem if a box clips but has a &amp;quot;Show more&amp;quot; button?&lt;/h3&gt;
&lt;p&gt;Not for renderlint: boxes with a &amp;quot;Show more&amp;quot; control are not reported, because the user has a way to the rest.&lt;/p&gt;
&lt;h3 id=&quot;does-overflow-auto-on-the-content-area-always-fix-it&quot;&gt;Does &lt;code&gt;overflow: auto&lt;/code&gt; on the content area always fix it?&lt;/h3&gt;
&lt;p&gt;It needs a height to scroll within. In a flex or grid layout that means &lt;code&gt;min-height: 0&lt;/code&gt; as well, or the area grows past its parent and the parent clips it.&lt;/p&gt;
</content>
</entry>
<entry>
<title>Why your dropdown is cut off: overflow hidden, z-index and stacking contexts</title>
<link href="https://renderlint.yitec.net/blog/dropdown-cut-off-overflow-hidden-z-index/"/>
<id>https://renderlint.yitec.net/blog/dropdown-cut-off-overflow-hidden-z-index/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>A dropdown is cut off when an ancestor clips it with overflow or traps it in a stacking context. Here is why raising z-index fails and what fixes it.</summary>
<content type="html">&lt;p&gt;A dropdown is cut off for one of two reasons. Either an ancestor with &lt;code&gt;overflow: hidden&lt;/code&gt; (or &lt;code&gt;auto&lt;/code&gt;) clips it, or another element is painted on top of it because the menu&amp;#39;s &lt;code&gt;z-index&lt;/code&gt; only counts inside a stacking context that sits below that element. Raising the menu&amp;#39;s &lt;code&gt;z-index&lt;/code&gt; fixes neither. The reliable fix is to move the menu out of the ancestor that clips or traps it: a portal, the top layer, or a layout without the clipping.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A menu that is &lt;code&gt;position: absolute&lt;/code&gt; is clipped by an ancestor with &lt;code&gt;overflow&lt;/code&gt; other than &lt;code&gt;visible&lt;/code&gt; when that ancestor is its containing block or contains it.&lt;/li&gt;
&lt;li&gt;A &lt;code&gt;z-index&lt;/code&gt; of 9999 on the menu is compared only with its siblings inside the same stacking context.&lt;/li&gt;
&lt;li&gt;A transform, filter or similar on an ancestor changes what &lt;code&gt;position: fixed&lt;/code&gt; means for the menu.&lt;/li&gt;
&lt;li&gt;Menus are usually closed when you build the page, so you never see the defect unless you open them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-does-overflow-hidden-cut-off-my-dropdown&quot;&gt;Why does overflow: hidden cut off my dropdown?&lt;/h2&gt;
&lt;p&gt;An absolutely positioned menu is drawn relative to its containing block, the nearest positioned ancestor. Clipping follows the containing-block chain too, but in the other direction: an ancestor whose &lt;code&gt;overflow&lt;/code&gt; is not &lt;code&gt;visible&lt;/code&gt; clips the menu if it is the menu&amp;#39;s containing block or contains it. (A non-positioned ancestor that sits between the menu and its containing block does not clip it.) A card with &lt;code&gt;overflow: hidden&lt;/code&gt; (often there to round the corners of an image) therefore cuts off a menu that opens below its last line.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;section class=&amp;quot;card&amp;quot;&amp;gt;            &amp;lt;!-- overflow: hidden; height: 96px --&amp;gt;
  &amp;lt;h2&amp;gt;Billing&amp;lt;/h2&amp;gt;
  &amp;lt;div class=&amp;quot;dd&amp;quot;&amp;gt;                &amp;lt;!-- position: relative --&amp;gt;
    &amp;lt;button aria-haspopup=&amp;quot;menu&amp;quot; aria-controls=&amp;quot;m1&amp;quot;&amp;gt;Billing actions&amp;lt;/button&amp;gt;
    &amp;lt;ul role=&amp;quot;menu&amp;quot; id=&amp;quot;m1&amp;quot;&amp;gt;...&amp;lt;/ul&amp;gt;   &amp;lt;!-- position: absolute; z-index: 50 --&amp;gt;
  &amp;lt;/div&amp;gt;
&amp;lt;/section&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The menu has &lt;code&gt;z-index: 50&lt;/code&gt; and it still does not help, because z-index decides what is painted on top of what, not what is allowed to leave a box. &lt;code&gt;overflow: auto&lt;/code&gt; and &lt;code&gt;overflow: scroll&lt;/code&gt; do the same, which is why dropdowns inside table wrappers (&lt;code&gt;overflow-x: auto&lt;/code&gt;) are a classic case. Setting &lt;code&gt;overflow-x: auto&lt;/code&gt; also makes &lt;code&gt;overflow-y&lt;/code&gt; compute to &lt;code&gt;auto&lt;/code&gt;, so you cannot clip only one axis and let the other show.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-menu-before-9fa1cb22-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-menu-before-9fa1cb22-640.webp 640w, https://renderlint.yitec.net/img/captures-menu-before-9fa1cb22-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;360&quot; alt=&quot;renderlint's screenshot at 768px: the Billing card has a dashed red outline, and the menu that opened under the Billing actions button is cut off at the card's bottom edge, leaving a red box over empty space&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;At 768px, the Billing menu opens inside a card with &lt;code&gt;overflow: hidden&lt;/code&gt;. renderlint boxes where the options should be.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;h2 id=&quot;why-is-my-dropdown-hidden-behind-another-element-even-with-a-high-z-index&quot;&gt;Why is my dropdown hidden behind another element even with a high z-index?&lt;/h2&gt;
&lt;p&gt;Because z-index is not global. An element with &lt;code&gt;position&lt;/code&gt; and a &lt;code&gt;z-index&lt;/code&gt; other than &lt;code&gt;auto&lt;/code&gt; creates a stacking context, and everything inside it is painted as one unit at that z-index. The menu&amp;#39;s &lt;code&gt;z-index: 50&lt;/code&gt; is compared only against other things inside the same context. The context itself is compared with its siblings.&lt;/p&gt;
&lt;p&gt;This is the situation with the Team and Usage cards in the example. They are positioned siblings with &lt;code&gt;z-index: 1&lt;/code&gt; and &lt;code&gt;z-index: 2&lt;/code&gt;. The menu belongs to the first card. The first card sits below the second one, so the menu is below it as well, whatever number the menu has.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-menu-before-2-1ade59b8-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-menu-before-2-1ade59b8-640.webp 640w, https://renderlint.yitec.net/img/captures-menu-before-2-1ade59b8-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;366&quot; alt=&quot;renderlint's screenshot at 768px: the Team actions menu opens, but the Usage this month card is painted over it so only the top edge of the first option shows, with a red box marking the hidden options&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;At 768px, the Team menu opens, but the card after it is painted over the options.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;Properties that create a stacking context, beyond &lt;code&gt;position&lt;/code&gt; plus &lt;code&gt;z-index&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Property on the ancestor&lt;/th&gt;
&lt;th&gt;Creates a stacking context&lt;/th&gt;
&lt;th&gt;Also makes &lt;code&gt;position: fixed&lt;/code&gt; children relative to it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;z-index&lt;/code&gt; on a positioned element (or a flex/grid item)&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;opacity&lt;/code&gt; below 1&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;transform&lt;/code&gt; (any value but &lt;code&gt;none&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;filter&lt;/code&gt; (any value but &lt;code&gt;none&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;isolation: isolate&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;will-change: transform&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;overflow: hidden&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;overflow&lt;/code&gt; is a clipping problem, not a stacking one. A transform, on the other hand, is both: it traps the menu in its own stacking context and it becomes the containing block for &lt;code&gt;position: fixed&lt;/code&gt; descendants.&lt;/p&gt;
&lt;h2 id=&quot;does-position-fixed-escape-overflow-hidden&quot;&gt;Does position: fixed escape overflow: hidden?&lt;/h2&gt;
&lt;p&gt;Usually yes. A fixed element is positioned against the viewport and is not clipped by ancestors&amp;#39; &lt;code&gt;overflow&lt;/code&gt;. That is why &amp;quot;make the menu fixed&amp;quot; is a popular fix. It fails when any ancestor has a &lt;code&gt;transform&lt;/code&gt;, &lt;code&gt;filter&lt;/code&gt; or &lt;code&gt;will-change: transform&lt;/code&gt;. That ancestor becomes the containing block, so the fixed menu is positioned and clipped relative to it, as if it were absolute. Animated cards with a &lt;code&gt;transform: translateY(0)&lt;/code&gt; hover effect are a common way to break a fixed menu by accident.&lt;/p&gt;
&lt;p&gt;The fix text for this rule mentions Floating UI with &lt;code&gt;strategy: &amp;quot;fixed&amp;quot;&lt;/code&gt; for use outside transformed ancestors.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-fix-a-clipped-or-hidden-dropdown&quot;&gt;How do you fix a clipped or hidden dropdown?&lt;/h2&gt;
&lt;p&gt;Pick the least invasive option that works for your layout.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Remove the clipping.&lt;/strong&gt; If &lt;code&gt;overflow: hidden&lt;/code&gt; was only there for rounded corners or a clearfix, drop it, or move it to an inner wrapper that does not contain the menu. In the fixed version of the example the clipping card has no &lt;code&gt;overflow: hidden&lt;/code&gt; and no fixed height.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Raise the ancestor, not the menu.&lt;/strong&gt; When a card is the stacking context, give the card the higher z-index while the menu is open:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.card:has([aria-expanded=&amp;quot;true&amp;quot;]) { z-index: 10; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is the fix used in the &amp;quot;after&amp;quot; version of the example page, which also drops the fixed z-indexes on the cards. It is simple, but it depends on &lt;code&gt;:has()&lt;/code&gt; and on the card staying a sibling of the others.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Render the menu somewhere else.&lt;/strong&gt; A portal appends the menu to &lt;code&gt;document.body&lt;/code&gt; (Radix and shadcn &lt;code&gt;Portal&lt;/code&gt;, MUI Popper and Menu which portal by default, Angular CDK Overlay, Headless UI&amp;#39;s &lt;code&gt;anchor&lt;/code&gt;). Then no ancestor can clip it. You position it from the trigger&amp;#39;s bounding box, which is what Floating UI does.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Use the top layer.&lt;/strong&gt; The &lt;code&gt;popover&lt;/code&gt; attribute puts the element in the browser&amp;#39;s top layer, above everything regardless of z-index or ancestors&amp;#39; overflow:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;button popovertarget=&amp;quot;team-menu&amp;quot;&amp;gt;Team actions&amp;lt;/button&amp;gt;
&amp;lt;ul id=&amp;quot;team-menu&amp;quot; popover role=&amp;quot;menu&amp;quot;&amp;gt;
  &amp;lt;li&amp;gt;&amp;lt;button role=&amp;quot;menuitem&amp;quot;&amp;gt;Invite people&amp;lt;/button&amp;gt;&amp;lt;/li&amp;gt;
&amp;lt;/ul&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A modal &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; opened with &lt;code&gt;showModal()&lt;/code&gt; is in the top layer too. A popover gives you light dismiss (click outside, Escape) but not the positioning: you still anchor it yourself or with a library.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Approach&lt;/th&gt;
&lt;th&gt;Escapes &lt;code&gt;overflow&lt;/code&gt; clipping&lt;/th&gt;
&lt;th&gt;Escapes stacking contexts&lt;/th&gt;
&lt;th&gt;Cost&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Raise the menu&amp;#39;s z-index&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;None, and it does not work&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Raise the ancestor&amp;#39;s z-index while open&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Partly (against siblings)&lt;/td&gt;
&lt;td&gt;One CSS rule&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;position: fixed&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes, unless a transformed ancestor&lt;/td&gt;
&lt;td&gt;Only within its context&lt;/td&gt;
&lt;td&gt;Needs a scroll/resize update&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Portal to &lt;code&gt;body&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Positioning code or a library&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;popover&lt;/code&gt; attribute / top layer&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;You still position it&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;h2 id=&quot;how-do-you-test-dropdowns-automatically&quot;&gt;How do you test dropdowns automatically?&lt;/h2&gt;
&lt;p&gt;A static check of the CSS can&amp;#39;t answer this reliably: whether a menu is visible depends on its open size, its ancestors&amp;#39; clipping boxes and the paint order at that spot. The dependable way is to open the menu and look at it, at the widths where the layout changes.&lt;/p&gt;
&lt;p&gt;The same page can be fine at 1280px and broken at 375px because the card is shorter or the next card moves under the trigger. Check each width.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;The rule is &lt;code&gt;popup-obscured&lt;/code&gt; (error by default, &lt;a href=&quot;https://renderlint.yitec.net/rules/#popup-obscured&quot;&gt;rule reference&lt;/a&gt;). renderlint opens the menu triggers on each page: &lt;code&gt;aria-haspopup&lt;/code&gt;, comboboxes, Bootstrap dropdowns and &lt;code&gt;&amp;lt;details&amp;gt;&lt;/code&gt;. It opens two of each repeated kind, at most 8 a page, and closes each menu again with Escape. It then checks that the options can be seen. It follows containing blocks (a transformed ancestor traps a &lt;code&gt;position: fixed&lt;/code&gt; menu) and, for a menu drawn underneath, it names the ancestor whose stacking context traps it. Each finding has a screenshot of the open menu.&lt;/p&gt;
&lt;p&gt;This is the real output for the example page, at 375, 768 and 1280px:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ popup-obscured (2)  An open dropdown, menu, listbox or popover can't be seen: it is cut off by a container's `overflow: hidden` / `auto` (a card, a table wrapper), or drawn underneath a later element because of z-index and stacking order. renderlint opens the menu triggers on each page (`aria-haspopup`, comboboxes, Bootstrap dropdowns, `&amp;lt;details&amp;gt;`) to check, and checks menus already open in `states` and Playwright tests.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; The open menu of &amp;quot;Billing actions&amp;quot; is cut off by main &amp;gt; div.cards &amp;gt; section.card.clip:nth-of-type(1) (overflow: hidden): 3 of 3 options can't be seen.
&lt;span class=&quot;d&quot;&gt;        at #m1 &amp;gt; li:nth-of-type(1) &amp;gt; button  &amp;quot;Download invoice&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;      with main &amp;gt; div.cards &amp;gt; section.card.clip:nth-of-type(1)  &amp;quot;Billing Billing actions Download invoice Change pl&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /menu-before.html · all viewports · see .renderlint/screens/menu-before-html-vzm6w@375-menu1.png #1&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; The open menu of &amp;quot;Team actions&amp;quot; is drawn underneath another element (2 of 3 options hidden behind main &amp;gt; div.cards &amp;gt; section.card.stack:nth-of-type(3)). Its z-index only counts inside main &amp;gt; div.cards &amp;gt; section.card.stack:nth-of-type(2) (z-index: 1), which sits below that element.
&lt;span class=&quot;d&quot;&gt;        at #m2 &amp;gt; li:nth-of-type(2) &amp;gt; button  &amp;quot;Manage roles&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;      with main &amp;gt; div.cards &amp;gt; section.card.stack:nth-of-type(3)  &amp;quot;Usage this month 12,480 API calls of 50,000.&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /menu-before.html · all viewports · see .renderlint/screens/menu-before-html-vzm6w@375-menu2.png #1&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The second message is the useful one: it says the menu&amp;#39;s z-index &amp;quot;only counts inside&amp;quot; the card that is the stacking context. After the fix the run printed &lt;code&gt;✔ No UI defects found.&lt;/code&gt;&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-menu-after-f7fcff96-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-menu-after-f7fcff96-640.webp 640w, https://renderlint.yitec.net/img/captures-menu-after-f7fcff96-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;525&quot; alt=&quot;The fixed page at 768px: the Team actions menu is open and drawn over the Usage card, with Invite people, Manage roles and Export members all readable&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;At 768px after the fix, the Team menu is drawn over the next card.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;&lt;code&gt;menus: false&lt;/code&gt; in the config turns the opening off, so only menus that are already open (in &lt;code&gt;states&lt;/code&gt; or a &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/playwright.md&quot; rel=&quot;noopener&quot;&gt;Playwright test&lt;/a&gt;) are checked. One of the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint#limitations&quot; rel=&quot;noopener&quot;&gt;documented limitations&lt;/a&gt; is that &lt;code&gt;--ux&lt;/code&gt; doesn&amp;#39;t use hover menus; a &lt;code&gt;states&lt;/code&gt; entry can reach one, since it accepts &lt;code&gt;hover&lt;/code&gt;. If a finding is intentional, mark the element with &lt;code&gt;data-renderlint-ignore=&amp;quot;popup-obscured&amp;quot;&lt;/code&gt; and a &lt;code&gt;data-renderlint-reason&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;does-a-bigger-z-index-ever-fix-a-hidden-dropdown&quot;&gt;Does a bigger z-index ever fix a hidden dropdown?&lt;/h3&gt;
&lt;p&gt;Only when the menu and the element covering it are in the same stacking context. If an ancestor of the menu starts its own context, give that ancestor the higher z-index, or take the menu out of it.&lt;/p&gt;
&lt;h3 id=&quot;is-overflow-clip-different-from-overflow-hidden&quot;&gt;Is overflow: clip different from overflow: hidden?&lt;/h3&gt;
&lt;p&gt;Both clip. &lt;code&gt;overflow: clip&lt;/code&gt; does not create a scroll container, but a menu inside it is cut off all the same.&lt;/p&gt;
&lt;h3 id=&quot;should-every-dropdown-be-portaled&quot;&gt;Should every dropdown be portaled?&lt;/h3&gt;
&lt;p&gt;Not necessarily. A menu with room inside its card and no clipping ancestor works fine in place. Portals matter for menus in cards, tables, sidebars and modals, where clipping and stacking are most likely.&lt;/p&gt;
</content>
</entry>
<entry>
<title>Loading states and layout shift: testing what users see on a slow network</title>
<link href="https://renderlint.yitec.net/blog/loading-states-layout-shift/"/>
<id>https://renderlint.yitec.net/blog/loading-states-layout-shift/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Why pages with no loading state look fine on a dev machine and broken on a phone, what counts as a loading sign, and how to test it by holding requests.</summary>
<content type="html">&lt;p&gt;A missing loading state is an area of the page that stays blank while its data loads, with no spinner, skeleton, progress bar or &amp;quot;Loading…&amp;quot; text. On your machine the API answers in 50 milliseconds, so you never see the blank. On a phone with a slow connection the page sits empty for seconds and looks broken. The way to test it is to hold the page&amp;#39;s requests for a second, look at the screen, then release them and watch what moves.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Dev machines hide the problem: the API is local and answers almost at once.&lt;/li&gt;
&lt;li&gt;Any visible sign counts as a loading state. What fails is a blank area.&lt;/li&gt;
&lt;li&gt;A skeleton the size of the final content also prevents layout shift.&lt;/li&gt;
&lt;li&gt;Clicks have the same problem as loads: no response for a second feels like a frozen page.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-dont-you-see-missing-loading-states-while-developing&quot;&gt;Why don&amp;#39;t you see missing loading states while developing?&lt;/h2&gt;
&lt;p&gt;Because of speed. On a development machine the API runs next door, so the request finishes before the browser has painted the empty state. On a fast dev machine the API answers in 50ms, so a page with no loading state looks fine. The benchmark behind renderlint&amp;#39;s loading checks uses a Vite and React app whose API answers in 60ms, like a dev machine.&lt;/p&gt;
&lt;p&gt;Users meet the other end of that range. The page paints its shell, fires a request, and has nothing to show until the response comes. If the code renders nothing for that area, the card looks empty. A common version:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;fetch(&amp;quot;orders.json&amp;quot;)
  .then((r) =&amp;gt; r.json())
  .then((rows) =&amp;gt; {
    document.getElementById(&amp;quot;orders&amp;quot;).innerHTML = renderTable(rows);
  });&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The container &lt;code&gt;#orders&lt;/code&gt; starts empty. There is no pending state, no error path, and a failed request leaves the card blank forever.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-loading-before-f497f3b6-798.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-loading-before-f497f3b6-640.webp 640w, https://renderlint.yitec.net/img/captures-loading-before-f497f3b6-798.webp 798w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;798&quot; height=&quot;874&quot; alt=&quot;renderlint's screenshot at 375px, two phone-sized panels side by side. Left, titled Waiting 1s for GET /orders.json: the Recent orders card is empty with a red box where the table will go. Right, after the data arrived: the orders table fills that box&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;renderlint&amp;#39;s side-by-side capture, each panel 375px wide. Left: one second into the wait the area is blank. Right: the data has arrived and filled the red box.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;h2 id=&quot;what-counts-as-a-loading-state&quot;&gt;What counts as a loading state?&lt;/h2&gt;
&lt;p&gt;Anything that tells the user something is on its way. renderlint accepts &lt;code&gt;aria-busy&lt;/code&gt;, &lt;code&gt;role=&amp;quot;progressbar&amp;quot;&lt;/code&gt; or &lt;code&gt;role=&amp;quot;status&amp;quot;&lt;/code&gt;, a running animation, motion on screen, &amp;quot;Loading…&amp;quot; or &amp;quot;Saving…&amp;quot; text, skeleton or spinner class names, and placeholder blocks where the content appears. It also recognizes canvas and SVG spinners, and spinners with hashed class names.&lt;/p&gt;
&lt;p&gt;Skeleton or spinner? Both pass. A skeleton shaped like the content is better, because it holds the space the content will take, so nothing jumps when it arrives. A spinner is fine for small or unpredictable areas, but the container should still reserve a minimum height.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question&lt;/th&gt;
&lt;th&gt;Skeleton&lt;/th&gt;
&lt;th&gt;Spinner&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Tells the user something is coming&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Reserves space for the final content&lt;/td&gt;
&lt;td&gt;Yes, if sized like it&lt;/td&gt;
&lt;td&gt;Only with a &lt;code&gt;min-height&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Layout shift when data arrives&lt;/td&gt;
&lt;td&gt;Low&lt;/td&gt;
&lt;td&gt;Likely, unless space is reserved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Best for&lt;/td&gt;
&lt;td&gt;Lists, tables, cards, dashboards&lt;/td&gt;
&lt;td&gt;Buttons, small panels, unknown shapes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Needs an error state&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Whichever you choose, handle the failure path. A skeleton that never leaves the screen is its own defect.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-fix-a-blank-loading-area&quot;&gt;How do you fix a blank loading area?&lt;/h2&gt;
&lt;p&gt;Render a state where the data will appear and clear it on success or failure. This is the fixed version of the page above, and it is the one renderlint passes:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;div id=&amp;quot;orders&amp;quot; aria-busy=&amp;quot;true&amp;quot;&amp;gt;
  &amp;lt;div class=&amp;quot;bone&amp;quot;&amp;gt;&amp;lt;/div&amp;gt;
  &amp;lt;div class=&amp;quot;bone&amp;quot;&amp;gt;&amp;lt;/div&amp;gt;
  &amp;lt;div class=&amp;quot;bone&amp;quot;&amp;gt;&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;
&amp;lt;script&amp;gt;
  const box = document.getElementById(&amp;quot;orders&amp;quot;);
  fetch(&amp;quot;orders.json&amp;quot;)
    .then((r) =&amp;gt; { if (!r.ok) throw new Error(r.status); return r.json(); })
    .then((rows) =&amp;gt; { box.innerHTML = renderTable(rows); })
    .catch(() =&amp;gt; {
      box.innerHTML = '&amp;lt;p role=&amp;quot;alert&amp;quot;&amp;gt;Orders could not be loaded. ' +
        '&amp;lt;button onclick=&amp;quot;location.reload()&amp;quot;&amp;gt;Try again&amp;lt;/button&amp;gt;&amp;lt;/p&amp;gt;';
    })
    .finally(() =&amp;gt; box.removeAttribute(&amp;quot;aria-busy&amp;quot;));
&amp;lt;/script&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In frameworks the same idea has names: &lt;code&gt;isPending&lt;/code&gt; or &lt;code&gt;isLoading&lt;/code&gt; with TanStack Query and SWR, a &lt;code&gt;fallback&lt;/code&gt; on React Suspense, &lt;code&gt;useNavigation()&lt;/code&gt; for React Router loaders, &lt;code&gt;loading.tsx&lt;/code&gt; in Next.js. Render an error message when the request fails.&lt;/p&gt;
&lt;h2 id=&quot;what-is-layout-shift-and-why-does-it-come-with-loading&quot;&gt;What is layout shift and why does it come with loading?&lt;/h2&gt;
&lt;p&gt;Layout shift is content moving after it has been painted. Cumulative Layout Shift (CLS) adds up those moves, and Core Web Vitals rates a CLS of 0.1 or less as &amp;quot;good&amp;quot; (&lt;a href=&quot;https://web.dev/articles/cls&quot; rel=&quot;noopener&quot;&gt;web.dev&lt;/a&gt;). When data arrives into an empty container, everything below it is pushed down. Users lose their place or click the wrong button because it moved under their finger.&lt;/p&gt;
&lt;p&gt;Things that cause it while loading:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;An empty container that grows when its data arrives.&lt;/li&gt;
&lt;li&gt;Images, video and embeds without &lt;code&gt;width&lt;/code&gt; and &lt;code&gt;height&lt;/code&gt; or &lt;code&gt;aspect-ratio&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A banner inserted above content that is already visible.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Reserve the space before the content arrives:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.orders { min-height: 320px; }          /* area filled by data */
.thumb  { aspect-ratio: 4 / 3; width: 100%; }  /* images and embeds */
.skeleton-row { height: 44px; }         /* skeleton the size of a row */&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;what-about-clicks-not-only-page-loads&quot;&gt;What about clicks, not only page loads?&lt;/h2&gt;
&lt;p&gt;The same blank-screen problem happens after a click. A button starts a request, and for a second nothing on screen changes. The page looks frozen, and users click again or leave. Nielsen&amp;#39;s rule of thumb: about one second is the limit for the user&amp;#39;s flow of thought to stay uninterrupted (&lt;a href=&quot;https://www.nngroup.com/articles/response-times-3-important-limits/&quot; rel=&quot;noopener&quot;&gt;Nielsen Norman Group&lt;/a&gt;).&lt;/p&gt;
&lt;p&gt;The fix is the same shape as for loads: respond at once with a pending state on the control (a spinner, &amp;quot;Saving…&amp;quot;, disabled) or where the result will appear, then show the result. Failures need the same care. If the request fails, nobody should be left with a spinner that never stops, or a &amp;quot;Settings saved&amp;quot; message that appeared because the code never checked &lt;code&gt;response.ok&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;On every run, each page that loads data in the browser is reloaded with its &lt;code&gt;fetch&lt;/code&gt; and XHR requests held for one second. renderlint looks at the page, releases the requests, and finds the areas the data filled. An area that showed nothing meanwhile is a &lt;code&gt;loading-state&lt;/code&gt; warning. The same hold measures &lt;code&gt;layout-shift&lt;/code&gt;: it warns above a CLS of 0.1.&lt;/p&gt;
&lt;p&gt;This is the output for the example page. The run was at three widths; this finding is at 375px:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;w&quot;&gt;⚠ loading-state (1)  An area of the page stays blank while its data loads: no spinner, skeleton, progress bar or &amp;quot;Loading…&amp;quot; text, so on a slow connection the page looks empty, broken or frozen. renderlint reloads each page with its fetch/XHR requests held for a second (as on a slow network), looks at what is shown, releases them and finds the areas the data filled. Any loading sign on the page counts: aria-busy, role=progressbar/status, a running animation, motion on screen, &amp;quot;Loading…&amp;quot;/&amp;quot;Saving…&amp;quot; text, skeleton or spinner class names, placeholder blocks where the content appears. With `--ux`, also checked after each click.&lt;/span&gt;
  &lt;span class=&quot;w&quot;&gt;warn&lt;/span&gt;  While this page waited for its data (GET /orders.json; renderlint held it 1s, as on a slow network), the area where &amp;quot;Order · Customer · Total · Status&amp;quot; appears showed nothing: no spinner, skeleton, progress bar or &amp;quot;Loading…&amp;quot; text. On a slow connection the page looks empty or frozen. Render a loading state in #orders until the data arrives (a skeleton shaped like the content, or a spinner), and an error message if the request fails.
&lt;span class=&quot;d&quot;&gt;        at #orders  &amp;quot;Order Customer Total Status A-1042 Lena Fischer €184.00 Paid A-1043 T…&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /loading-before.html · at 375px&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With &lt;code&gt;--ux&lt;/code&gt;, renderlint also uses every kind of button, tab, in-app link, filter dropdown and form on each page (filled with test data), one of each repeated kind, each on a fresh load. &lt;code&gt;action-feedback&lt;/code&gt; is the click that starts a request and shows nothing for a second. &lt;code&gt;error-feedback&lt;/code&gt; answers the page&amp;#39;s data requests, and each action&amp;#39;s, with HTTP 500 and checks that something tells the user, instead of a spinner that never stops or a silent page. Requests that change data are answered by renderlint and never reach your server.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-ux-loading-state-39c18ad4-1968.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-ux-loading-state-39c18ad4-640.webp 640w, https://renderlint.yitec.net/img/docs-ux-loading-state-39c18ad4-960.webp 960w, https://renderlint.yitec.net/img/docs-ux-loading-state-39c18ad4-1280.webp 1280w, https://renderlint.yitec.net/img/docs-ux-loading-state-39c18ad4-1968.webp 1968w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1968&quot; height=&quot;670&quot; alt=&quot;renderlint's screenshot of a dashboard with a sidebar and four stat cards. Left, while GET /api/orders is held for 1s, the Recent orders card shows nothing in a red box. Right, after the data arrived, the orders table fills it&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;The same check on a dashboard with stat cards, a sidebar and a table, from a different example app.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;h3 id=&quot;how-accurate-is-the-detection&quot;&gt;How accurate is the detection?&lt;/h3&gt;
&lt;p&gt;The detection was designed by measurement on a benchmark of 75 dashboard pages on a Vite and React 19 app: 41 pages written by the renderlint authors, 24 &amp;quot;blind&amp;quot; pages written by a separate agent that never saw the detector, and 10 pages for the other &lt;code&gt;--ux&lt;/code&gt; checks. The methods compared:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Method&lt;/th&gt;
&lt;th&gt;Own set: caught · false alarms&lt;/th&gt;
&lt;th&gt;Blind set: caught · false alarms&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Loading words and ARIA only&lt;/td&gt;
&lt;td&gt;13/13 · 12&lt;/td&gt;
&lt;td&gt;12/12 · 3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Pixels only&lt;/td&gt;
&lt;td&gt;13/13 · 3&lt;/td&gt;
&lt;td&gt;12/12 · 3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DOM, plus animations, class names and placeholder boxes&lt;/td&gt;
&lt;td&gt;13/13 · 0&lt;/td&gt;
&lt;td&gt;12/12 · 1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DOM plus motion on screen (shipped)&lt;/td&gt;
&lt;td&gt;13/13 · 0&lt;/td&gt;
&lt;td&gt;12/12 · 0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The shipped default run at 375px flagged all 13 broken page loads and nothing on the other 52 pages of the first two sets. &lt;code&gt;--ux&lt;/code&gt; at 1280px caught every broken click and route change (6 in each set) and both main-thread freezes. It also found &lt;code&gt;error-feedback&lt;/code&gt; on 11 pages that show a loading state but never handle a failed request.&lt;/p&gt;
&lt;h3 id=&quot;what-are-the-limits&quot;&gt;What are the limits?&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The one &lt;code&gt;layout-shift&lt;/code&gt; miss in the benchmark was a promo banner that measured a CLS of 0.093 at 375px, just under the 0.1 threshold. At 1280px it measured 0.11 and was flagged.&lt;/li&gt;
&lt;li&gt;The default run costs about 2.5s per page that loads data in the browser. &lt;code&gt;--ux&lt;/code&gt; takes 5–15s per page on the benchmark.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--ux&lt;/code&gt; uses at most 12 actions per page, one control of each kind, and no hover menus or drag and drop.&lt;/li&gt;
&lt;li&gt;The look happens one second into the wait. A spinner that deliberately appears only after 400ms, to avoid a flash on fast responses, counts as a loading sign: the benchmark has such a page.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The &lt;code&gt;loading-state&lt;/code&gt; and &lt;code&gt;--ux&lt;/code&gt; findings are warnings, not errors, and each message names the request, the control and what to add.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;does-the-default-run-click-anything&quot;&gt;Does the default run click anything?&lt;/h3&gt;
&lt;p&gt;No. The default run reloads each page with its requests held. Broken clicks are left to &lt;code&gt;--ux&lt;/code&gt;, because the default run doesn&amp;#39;t click.&lt;/p&gt;
&lt;h3 id=&quot;how-long-should-a-loading-state-take-to-appear&quot;&gt;How long should a loading state take to appear?&lt;/h3&gt;
&lt;p&gt;At once for clicks. renderlint looks one second into the wait because that is Nielsen&amp;#39;s limit for keeping the user&amp;#39;s flow.&lt;/p&gt;
&lt;h3 id=&quot;is-a-skeleton-always-better-than-a-spinner&quot;&gt;Is a skeleton always better than a spinner?&lt;/h3&gt;
&lt;p&gt;For areas with a known shape, yes: it reserves the space and reduces layout shift. For a button waiting on a save, a spinner or &amp;quot;Saving…&amp;quot; label is the right size.&lt;/p&gt;
</content>
</entry>
<entry>
<title>How to test every route and role behind a login</title>
<link href="https://renderlint.yitec.net/blog/test-every-route-and-role-behind-login/"/>
<id>https://renderlint.yitec.net/blog/test-every-route-and-role-behind-login/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Automated UI checks usually see only the login form. Here is how to check every route as every role, with no backend, and fail CI when a page goes unchecked.</summary>
<content type="html">&lt;p&gt;Most of an app sits behind a login, and a crawler without a session sees one page: the login form. To test every route and role, give the tool the session your route guard accepts, mock the API the pages call, list your roles, and read a coverage report that gives each route a status. A check that quietly tests &lt;code&gt;/login&lt;/code&gt; in place of &lt;code&gt;/dashboard&lt;/code&gt; passes while the real page is never looked at.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A redirect to &lt;code&gt;/login&lt;/code&gt; is a missing page, not a passed page.&lt;/li&gt;
&lt;li&gt;Routes should come from your source and your router, not only from links.&lt;/li&gt;
&lt;li&gt;Roles need their own session, their own mock data and their own expected &amp;quot;no&amp;quot;.&lt;/li&gt;
&lt;li&gt;Coverage must be a number you can fail a build on.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-do-crawlers-miss-the-pages-behind-a-login&quot;&gt;Why do crawlers miss the pages behind a login?&lt;/h2&gt;
&lt;p&gt;A crawler loads a URL, collects the links, and loads those. That model breaks in four ways on a real app.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The SPA sends everything to &lt;code&gt;/login&lt;/code&gt;.&lt;/strong&gt; An Angular, React or Vue app with a route guard redirects every inner route to the sign-in page when there is no session. The crawler loads &lt;code&gt;/dashboard&lt;/code&gt;, lands on &lt;code&gt;/login&lt;/code&gt;, finds the login form, checks it, and reports no problems. The report is green and the dashboard was never opened.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Some routes have no link.&lt;/strong&gt; A page reached only by a button, a row click or a router call has no &lt;code&gt;&amp;lt;a href&amp;gt;&lt;/code&gt; to follow. It exists in the router and nowhere in the HTML.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Dynamic routes need values.&lt;/strong&gt; &lt;code&gt;/users/:id&lt;/code&gt; and &lt;code&gt;/products/[slug]&lt;/code&gt; are patterns. Nothing in them says which id to load.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Roles see different pages.&lt;/strong&gt; An admin sees &lt;code&gt;/admin/users&lt;/code&gt;. A viewer is turned away. An upgrade card appears only for free users. One session can&amp;#39;t show you all of that.&lt;/p&gt;
&lt;h2 id=&quot;how-should-a-ui-check-treat-a-redirect-to-the-login-page&quot;&gt;How should a UI check treat a redirect to the login page?&lt;/h2&gt;
&lt;p&gt;As a failure of coverage, never as a pass. renderlint reports a page that lands on a login page, or on an identity provider such as Entra ID, Auth0, Okta or Keycloak, as &lt;code&gt;auth-required&lt;/code&gt; instead of checking it. The login page itself is still checked, under its own name.&lt;/p&gt;
&lt;p&gt;This is the report from running renderlint on a small SPA fixture with a route guard and no session (the &lt;code&gt;test/fixtures/auth&lt;/code&gt; folder in the renderlint repository). The second finding, for &lt;code&gt;/hash.html&lt;/code&gt;, is left out here:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ auth-required (2)  A page renderlint was asked to check sent it to a login page or identity provider instead, so the page itself was never checked. …&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; /index.html was not checked: the app sent renderlint to /login instead. Pages behind a login need &amp;quot;auth&amp;quot; in renderlint.config (log in once, or set the token your route guard reads and mock the API: no backend needed).
&lt;span class=&quot;d&quot;&gt;        page /index.html · all viewports&lt;/span&gt;
  …&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The finding is an error for a page you listed, and a warning for a page found by crawling (an admin-only route for a non-admin user, for example). You can turn the rule off with &lt;code&gt;&amp;quot;rules&amp;quot;: { &amp;quot;auth-required&amp;quot;: &amp;quot;off&amp;quot; }&lt;/code&gt;, but the default makes a gap visible.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-get-a-session-without-a-backend&quot;&gt;How do you get a session without a backend?&lt;/h2&gt;
&lt;p&gt;A route guard usually checks only that a token exists. It can&amp;#39;t tell a test value from a real one. So set the token the guard reads and serve the API calls the pages make with &lt;code&gt;mock&lt;/code&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{
  &amp;quot;pages&amp;quot;: [&amp;quot;/dashboard&amp;quot;, &amp;quot;/accounts&amp;quot;],
  &amp;quot;auth&amp;quot;: { &amp;quot;storage&amp;quot;: { &amp;quot;sessionStorage&amp;quot;: { &amp;quot;acme.token&amp;quot;: &amp;quot;test-token&amp;quot; } } },
  &amp;quot;mock&amp;quot;: { &amp;quot;**/api/me&amp;quot;: { &amp;quot;name&amp;quot;: &amp;quot;Dana&amp;quot; }, &amp;quot;**/api/accounts&amp;quot;: &amp;quot;fixtures/accounts.json&amp;quot; }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With this, the inner pages render with nothing but the dev server running. No credentials are involved, the data is the same on every run, and it works the same in CI.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Where the app keeps its session&lt;/th&gt;
&lt;th&gt;What to set&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sessionStorage&lt;/code&gt; or &lt;code&gt;localStorage&lt;/code&gt; key&lt;/td&gt;
&lt;td&gt;&lt;code&gt;&amp;quot;auth&amp;quot;: { &amp;quot;storage&amp;quot;: { &amp;quot;sessionStorage&amp;quot;: { &amp;quot;key&amp;quot;: &amp;quot;test-token&amp;quot; } } }&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A persisted store (Pinia, Redux, NgRx, Zustand)&lt;/td&gt;
&lt;td&gt;The store&amp;#39;s JSON as an object: &lt;code&gt;&amp;quot;localStorage&amp;quot;: { &amp;quot;auth&amp;quot;: { &amp;quot;token&amp;quot;: &amp;quot;t&amp;quot;, &amp;quot;user&amp;quot;: { &amp;quot;id&amp;quot;: 1 } } }&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A cookie the frontend only checks for&lt;/td&gt;
&lt;td&gt;&lt;code&gt;&amp;quot;storage&amp;quot;: { &amp;quot;cookies&amp;quot;: [{ &amp;quot;name&amp;quot;: &amp;quot;session&amp;quot;, &amp;quot;value&amp;quot;: &amp;quot;test&amp;quot; }] }&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A JWT decoded in the frontend&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{ &amp;quot;$jwt&amp;quot;: { &amp;quot;sub&amp;quot;: &amp;quot;1&amp;quot;, &amp;quot;role&amp;quot;: &amp;quot;admin&amp;quot; } }&lt;/code&gt;: renderlint writes an unsigned token that expires in 2100&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;HttpOnly&lt;/code&gt; cookie checked by the server&lt;/td&gt;
&lt;td&gt;The real login form, or a backend&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;To find the key, search the auth service for &lt;code&gt;sessionStorage.setItem&lt;/code&gt; or &lt;code&gt;localStorage.setItem&lt;/code&gt;, or sign in once and look under Application &amp;gt; Storage in DevTools. The mocked endpoints are the Fetch/XHR calls in the network tab. Put worst cases in the fixtures, such as a 60-character email.&lt;/p&gt;
&lt;h3 id=&quot;can-it-log-in-through-the-real-form&quot;&gt;Can it log in through the real form?&lt;/h3&gt;
&lt;p&gt;Yes. renderlint fills the form once and reuses the session (cookies, localStorage, sessionStorage and IndexedDB) for every page and width:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{
  &amp;quot;auth&amp;quot;: { &amp;quot;login&amp;quot;: &amp;quot;/login&amp;quot;, &amp;quot;user&amp;quot;: &amp;quot;${RENDERLINT_USER}&amp;quot;, &amp;quot;password&amp;quot;: &amp;quot;${RENDERLINT_PASSWORD}&amp;quot; }
}&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;RENDERLINT_USER=qa@example.com RENDERLINT_PASSWORD=… npx renderlint&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Keep credentials in environment variables or CI secrets and use a test account. For SSO, MFA or magic links, a JavaScript config takes &lt;code&gt;auth.run&lt;/code&gt;, which receives a Playwright page and can do anything a test can. If a login fails, the run stops with what the form said and saves &lt;code&gt;.renderlint/screens/login-failed.png&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-find-routes-that-have-no-links&quot;&gt;How do you find routes that have no links?&lt;/h2&gt;
&lt;p&gt;Read them from the source, then from the running router. renderlint reads routes from Next.js (&lt;code&gt;app/&lt;/code&gt; and &lt;code&gt;pages/&lt;/code&gt;), Nuxt, SvelteKit, Astro, React Router 7 and Remix, TanStack Router, Angular &lt;code&gt;Routes&lt;/code&gt; arrays (including lazy &lt;code&gt;loadChildren&lt;/code&gt;), Vue Router and React Router configs, all without running the app. It also reads the route table of the running router (Vue Router, React Router, Angular Router), which catches routes built at runtime and pages reached only by a button. &lt;code&gt;sitemap.xml&lt;/code&gt;, &lt;code&gt;robots.txt&lt;/code&gt; and build output add more.&lt;/p&gt;
&lt;p&gt;&lt;code&gt;npx renderlint routes&lt;/code&gt; lists what it found, and &lt;code&gt;--files&lt;/code&gt; adds the files each route renders.&lt;/p&gt;
&lt;p&gt;For dynamic routes, values come from &lt;code&gt;generateStaticParams&lt;/code&gt;, &lt;code&gt;getStaticPaths&lt;/code&gt; and &lt;code&gt;entries&lt;/code&gt; when they return literals, from the build manifest and sitemap, from links it crawls, and from ids in the JSON lists your API returns (&lt;code&gt;/api/users&lt;/code&gt; fills &lt;code&gt;/users/:id&lt;/code&gt;). When nothing names a value, set it:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{ &amp;quot;params&amp;quot;: { &amp;quot;/users/:id&amp;quot;: [&amp;quot;7&amp;quot;, &amp;quot;9&amp;quot;], &amp;quot;/docs/:path+&amp;quot;: [&amp;quot;getting-started/install&amp;quot;], &amp;quot;slug&amp;quot;: &amp;quot;hello-world&amp;quot; } }&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;how-do-you-test-every-role-at-once&quot;&gt;How do you test every role at once?&lt;/h2&gt;
&lt;p&gt;List the roles. renderlint checks every page as each of them in one run:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{
  &amp;quot;auth&amp;quot;: { &amp;quot;storage&amp;quot;: { &amp;quot;sessionStorage&amp;quot;: { &amp;quot;app.token&amp;quot;: &amp;quot;test-token&amp;quot; } } },
  &amp;quot;roles&amp;quot;: {
    &amp;quot;admin&amp;quot;:  { &amp;quot;mock&amp;quot;: { &amp;quot;**/api/me&amp;quot;: { &amp;quot;name&amp;quot;: &amp;quot;Ada Admin&amp;quot;, &amp;quot;role&amp;quot;: &amp;quot;admin&amp;quot; } }, &amp;quot;pages&amp;quot;: [&amp;quot;/admin&amp;quot;] },
    &amp;quot;viewer&amp;quot;: { &amp;quot;mock&amp;quot;: { &amp;quot;**/api/me&amp;quot;: { &amp;quot;name&amp;quot;: &amp;quot;Vic Viewer&amp;quot;, &amp;quot;role&amp;quot;: &amp;quot;viewer&amp;quot; } }, &amp;quot;deny&amp;quot;: [&amp;quot;/admin/**&amp;quot;] }
  },
  &amp;quot;mock&amp;quot;: { &amp;quot;**/api/projects&amp;quot;: &amp;quot;fixtures/projects.json&amp;quot; }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A role can take its own sign-in settings, its own &lt;code&gt;mock&lt;/code&gt;, &lt;code&gt;pages&lt;/code&gt; it must see, and &lt;code&gt;deny&lt;/code&gt; paths it must not. Pages show up as &lt;code&gt;/admin [role: admin]&lt;/code&gt;, and the report has a route by role table.&lt;/p&gt;
&lt;h3 id=&quot;what-is-the-difference-between-page-not-shown-and-auth-required&quot;&gt;What is the difference between page-not-shown and auth-required?&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;auth-required&lt;/code&gt; means the session wasn&amp;#39;t accepted and the app sent the visitor to sign in. &lt;code&gt;page-not-shown&lt;/code&gt; means the visitor was signed in but not shown the page. It fires when a guard redirects (&lt;code&gt;/admin&lt;/code&gt; to &lt;code&gt;/403&lt;/code&gt;), the server answers HTTP 401 or 403, or the app renders &amp;quot;Access denied&amp;quot; or &amp;quot;Page not found&amp;quot; in place of the page.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Situation&lt;/th&gt;
&lt;th&gt;Reported as&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;One role sees the page and another doesn&amp;#39;t&lt;/td&gt;
&lt;td&gt;&lt;code&gt;page-not-shown&lt;/code&gt; warning for the other role&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The page is in that role&amp;#39;s &lt;code&gt;deny&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&amp;quot;denied (expected)&amp;quot;, not a finding&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;No role could see a page you listed, or a page in a role&amp;#39;s own &lt;code&gt;pages&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;error&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redirected to the login page&lt;/td&gt;
&lt;td&gt;&lt;code&gt;auth-required&lt;/code&gt;: the role&amp;#39;s session wasn&amp;#39;t accepted&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;A page that is not shown is never checked in that role&amp;#39;s name. Home page forwarding (&lt;code&gt;/&lt;/code&gt; to &lt;code&gt;/dashboard&lt;/code&gt;), a section opening its default child, trailing slashes and locale prefixes are not findings. The &amp;quot;Access denied&amp;quot; detection uses English phrases, so for a guard that renders an empty page in another language, add a &lt;code&gt;deny&lt;/code&gt; entry.&lt;/p&gt;
&lt;h2 id=&quot;what-about-server-rendered-apps&quot;&gt;What about server-rendered apps?&lt;/h2&gt;
&lt;p&gt;In Next.js, Nuxt, SvelteKit, React Router or Remix, and Angular SSR, the session check and data fetching run on the server. A browser-side mock can&amp;#39;t reach &lt;code&gt;middleware.ts&lt;/code&gt;, &lt;code&gt;getServerSideProps&lt;/code&gt; or loaders. When renderlint starts the server itself, a small preload makes &lt;code&gt;mock&lt;/code&gt; answer the server&amp;#39;s own requests too (global &lt;code&gt;fetch&lt;/code&gt;, undici, and &lt;code&gt;node:http&lt;/code&gt;/&lt;code&gt;node:https&lt;/code&gt;). The real login form runs, the app mints its own session, and only the API call that checks the password is mocked.&lt;/p&gt;
&lt;p&gt;The preload does nothing unless &lt;code&gt;RENDERLINT_SERVER_MOCK&lt;/code&gt; is set, and it only answers requests to a loopback host. It can&amp;#39;t help servers that aren&amp;#39;t Node (Django, Rails, Laravel, Go), or logins that check a password against the app&amp;#39;s own database with no HTTP call to mock. Those need a seeded backend with test accounts. See the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/server-mocks.md&quot; rel=&quot;noopener&quot;&gt;server mocks docs&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-know-every-route-was-checked&quot;&gt;How do you know every route was checked?&lt;/h2&gt;
&lt;p&gt;Every run prints a coverage line and writes &lt;code&gt;.renderlint/coverage.json&lt;/code&gt;. A report on a larger app looks like this (the example is from renderlint&amp;#39;s documentation):&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;◐ Coverage 412 URL(s), 38 route(s): 35 checked, 2 need a role, 1 need param values
  needs a role /admin/users  app/admin/users/page.tsx — the page says &amp;quot;Access denied&amp;quot;
  needs param values /reports/:id  app/reports/[id]/page.tsx — no value for :id (…set &amp;quot;params&amp;quot;)&lt;/code&gt;&lt;/pre&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Status&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;th&gt;What to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;checked&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;At least one instance got the full check&lt;/td&gt;
&lt;td&gt;Nothing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;need sign-in&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Sent to the sign-in page, or HTTP 401&lt;/td&gt;
&lt;td&gt;Set up &lt;code&gt;auth&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;need a role&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A guard redirect, HTTP 403 or an access-denied page&lt;/td&gt;
&lt;td&gt;Add a role that may see it, or &lt;code&gt;deny&lt;/code&gt; it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;need param values&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A dynamic route with no known value&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;params&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;redirect elsewhere&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Always lands on another page&lt;/td&gt;
&lt;td&gt;Usually fine&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;not checked&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A catch-all route, &lt;code&gt;exclude&lt;/code&gt;, a log-out route, a URL that looks destructive, or the page limit&lt;/td&gt;
&lt;td&gt;List it in &lt;code&gt;pages&lt;/code&gt;, or raise &lt;code&gt;maxPages&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Then make it a gate. &lt;code&gt;--min-coverage 100&lt;/code&gt; (or &lt;code&gt;coverage.min&lt;/code&gt;) fails when routes go unchecked, and &lt;code&gt;--coverage-baseline &amp;lt;file&amp;gt;&lt;/code&gt; fails when a route that was checked in an earlier run no longer is:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{ &amp;quot;coverage&amp;quot;: { &amp;quot;min&amp;quot;: 100, &amp;quot;ignore&amp;quot;: [&amp;quot;/internal/*&amp;quot;], &amp;quot;baseline&amp;quot;: &amp;quot;.renderlint-baseline/coverage.json&amp;quot; } }&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;does-checking-hundreds-of-urls-take-hours&quot;&gt;Does checking hundreds of URLs take hours?&lt;/h3&gt;
&lt;p&gt;A shop with 2,000 product pages has one product route. renderlint gives every instance of a route a quick check (narrowest viewport, light scheme, no stress or sweep), then gives the instances that look most unlike the first the full check. This is the measurement from the docs, on a 260-URL Next.js shop with 36 routes and 70 real defects planted on 51 instances:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Strategy&lt;/th&gt;
&lt;th&gt;Time&lt;/th&gt;
&lt;th&gt;Defects found&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Check every URL fully&lt;/td&gt;
&lt;td&gt;1025 s&lt;/td&gt;
&lt;td&gt;100%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;quick: true&lt;/code&gt; (default)&lt;/td&gt;
&lt;td&gt;527 s&lt;/td&gt;
&lt;td&gt;97% (missed one desktop-only overflow)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;quick: &amp;quot;ends&amp;quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;732 s&lt;/td&gt;
&lt;td&gt;100%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2 instances per route, first found, no quick check&lt;/td&gt;
&lt;td&gt;171 s&lt;/td&gt;
&lt;td&gt;26%&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The last row is why the default isn&amp;#39;t &amp;quot;check the first two&amp;quot;. Without the quick pass, about three quarters of the planted defects were missed.&lt;/p&gt;
&lt;h2 id=&quot;what-this-looks-like-with-a-coding-agent&quot;&gt;What this looks like with a coding agent&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;renderlint init&lt;/code&gt; installs a &lt;code&gt;renderlint-setup&lt;/code&gt; skill that tells an agent to handle &lt;code&gt;auth-required&lt;/code&gt; and &lt;code&gt;page-not-shown&lt;/code&gt; the same way: find the key the guard reads and where the role comes from, set test values, mock the API calls. No credentials are needed. The suggested setup prompt tells the agent to use the skill until the coverage report shows every route checked. More in &lt;a href=&quot;https://renderlint.yitec.net/blog/catch-ui-bugs-ai-coding-agents/&quot;&gt;catch UI bugs written by AI coding agents&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;auth-required&lt;/code&gt; and &lt;code&gt;page-not-shown&lt;/code&gt; are not visual rules. They protect the other rules from a false green. After each navigation renderlint looks at where the page ended up (login page, identity provider, 401 or 403, a redirect, an &amp;quot;Access denied&amp;quot; body) and records the outcome per viewport. A role&amp;#39;s outcome counts only when every viewport agrees, so one slow render can&amp;#39;t flip it. Neither finding is ever counted as a pass, and the coverage report names each unchecked route and why. See the &lt;a href=&quot;https://renderlint.yitec.net/rules/#auth-required&quot;&gt;rules reference&lt;/a&gt; and the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/roles-and-coverage.md&quot; rel=&quot;noopener&quot;&gt;roles and coverage docs&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Limits: the &amp;quot;Access denied&amp;quot; detection uses English phrases. Server mocks are Node only, and pages prerendered at &lt;code&gt;next build&lt;/code&gt; keep their build-time data. A page behind a click (a dialog, a wizard step) is linted only if you list it in &lt;code&gt;states&lt;/code&gt; or reach it in a Playwright test. Credentials are never sent anywhere, and log-out and destructive links (delete, cancel, unsubscribe) are never opened.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;do-i-need-real-credentials&quot;&gt;Do I need real credentials?&lt;/h3&gt;
&lt;p&gt;No, for the frontend-only setup. You set a token the guard accepts and mock the API. If you use the real login form, use a test account and keep the password in an environment variable.&lt;/p&gt;
&lt;h3 id=&quot;will-renderlint-click-sign-out-or-delete&quot;&gt;Will renderlint click &amp;quot;Sign out&amp;quot; or &amp;quot;Delete&amp;quot;?&lt;/h3&gt;
&lt;p&gt;No. Log-out links and destructive links are never followed, and with &lt;code&gt;--ux&lt;/code&gt; the requests that change data are answered by renderlint and never reach your server.&lt;/p&gt;
</content>
</entry>
<entry>
<title>How to catch UI bugs written by AI coding agents</title>
<link href="https://renderlint.yitec.net/blog/catch-ui-bugs-ai-coding-agents/"/>
<id>https://renderlint.yitec.net/blog/catch-ui-bugs-ai-coding-agents/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Coding agents ship code that compiles and pages that look wrong. Here is why, what a 22-session experiment found, and how to make an agent check its own UI.</summary>
<content type="html">&lt;p&gt;AI coding agents write valid code and never see the page it draws, so they ship visual bugs that TypeScript, ESLint and unit tests can&amp;#39;t detect: low-contrast text, clipped chart labels, a layout that breaks at 320px. The fix is a check that renders the app in a real browser, reports each defect with a concrete fix, and blocks the agent from finishing until the errors are gone. In the renderlint experiment, 11 baseline apps had 229 errors between them, and the 11 apps built with renderlint finished at 0.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents can&amp;#39;t judge pixels from code, so contrast and overflow slip through.&lt;/li&gt;
&lt;li&gt;A plain-text report with element, source file and fix is something an agent can act on.&lt;/li&gt;
&lt;li&gt;A Stop hook (Claude Code) or &lt;code&gt;AGENTS.md&lt;/code&gt; instructions (other agents) make the check automatic.&lt;/li&gt;
&lt;li&gt;The check has to be narrow and quick, or agents skip it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-do-ai-coding-agents-ship-visual-bugs&quot;&gt;Why do AI coding agents ship visual bugs?&lt;/h2&gt;
&lt;p&gt;The agent writes a component, the build passes, the types pass, and the agent reports success. Nothing in that loop looks at the result. The code is fine. The pixels are wrong.&lt;/p&gt;
&lt;p&gt;Some of what goes wrong:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Contrast.&lt;/strong&gt; A muted gray caption, an orange-600 label on white, white text on a light accent color, chart axis ticks, text on a gradient. These are hard to see in review on a good monitor.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Text that doesn&amp;#39;t fit.&lt;/strong&gt; A long email running off a card, a price cut off at 1024px, donut-chart labels clipped by the SVG edge on a phone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Emoji as icons.&lt;/strong&gt; Rocket and sparkle characters where an icon set belongs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Layouts tuned to the sample copy.&lt;/strong&gt; Fine with &amp;quot;Acme Inc&amp;quot;, broken with a real 40-character name.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;None of this is a syntax or type problem, so none of the usual gates fire. That is the gap between &amp;quot;the code is valid&amp;quot; and &amp;quot;the page looks right&amp;quot;.&lt;/p&gt;
&lt;h2 id=&quot;what-happened-when-agents-checked-their-own-ui&quot;&gt;What happened when agents checked their own UI?&lt;/h2&gt;
&lt;p&gt;renderlint ran headless Claude Code sessions (&lt;code&gt;claude -p&lt;/code&gt;), each vibe-coding a frontend from one prompt. There were 22 sessions on Opus and Haiku, building landing pages, dashboards, a kanban board, a weather app, an SVG org chart and analytics charts in HTML, React, Next.js, Vue and Svelte. Half also got a one-line setup prompt.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Measure&lt;/th&gt;
&lt;th&gt;Baseline apps (11)&lt;/th&gt;
&lt;th&gt;Apps built with renderlint (11)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Errors at the time of the experiment&lt;/td&gt;
&lt;td&gt;229&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Errors rescored later with the newer checks&lt;/td&gt;
&lt;td&gt;225&lt;/td&gt;
&lt;td&gt;11, in 5 apps&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The numbers behind that, from the &lt;a href=&quot;https://github.com/ngocanhnckh/renderlint/blob/master/docs/results.md&quot; rel=&quot;noopener&quot;&gt;published results&lt;/a&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The 11 baseline apps had 229 errors, mostly WCAG contrast failures, plus emoji icons and clipped chart labels.&lt;/li&gt;
&lt;li&gt;All 11 apps built with renderlint finished at 0 errors, because the agents fixed the issues themselves.&lt;/li&gt;
&lt;li&gt;Rescoring with the width sweep, stress profiles and form rules later gave 11 errors in 5 of the renderlint-built apps, against 225 for the baselines. Every new finding was checked by eye. 9 of the 11 only appear at 320 or 360px, narrower than the 375px viewport the agents had been checking, and the other 2 are &lt;code&gt;dropdown-arrow&lt;/code&gt; on native selects. None was checkable when the sessions ran.&lt;/li&gt;
&lt;/ul&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1656.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-640.webp 640w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-960.webp 960w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1280.webp 1280w, https://renderlint.yitec.net/img/docs-compare-weather-0d72675f-1656.webp 1656w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1656&quot; height=&quot;578&quot; alt=&quot;Same weather-app prompt in two Claude Code sessions: 42 contrast errors without renderlint, 0 with it&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;/figure&gt;


&lt;p&gt;&lt;em&gt;Caption:&lt;/em&gt; The same weather-app prompt in two sessions. Left: no renderlint, 42 errors (its annotated report). Right: the session that ran renderlint and fixed its own findings.&lt;/p&gt;
&lt;p&gt;Two other observations are worth repeating. The models mostly got layout right but failed contrast all the time: in every Opus baseline, almost all the defects were contrast failures. And once the agent had numbers (&lt;code&gt;2.66:1, needs 4.5:1 — #ffffff on #459bf4&lt;/code&gt;) and a suggested color, it fixed them in one pass. The experiment also surfaced bugs in renderlint itself, which were fixed, and one false positive the Svelte agent handled by suppressing it with &lt;code&gt;data-renderlint-ignore&lt;/code&gt; and a written reason.&lt;/p&gt;
&lt;p&gt;This is one set of prompts, one tool, and a count of errors that the same tool defined. It shows that agents act on this kind of report. It doesn&amp;#39;t prove the apps are free of every visual defect.&lt;/p&gt;
&lt;h2 id=&quot;what-does-an-agent-friendly-report-look-like&quot;&gt;What does an agent-friendly report look like?&lt;/h2&gt;
&lt;p&gt;An agent needs the element, where it lives in the source, and what to change, as plain text. This is a real finding from the weather-page example:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ contrast (10)  Text does not have enough contrast with what is actually behind it (WCAG AA: 4.5:1, or 3:1 for large text). Measured from real rendered pixels, so it works over gradients and images.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Low text contrast: 1.64:1, needs 3:1 — #ffffff on a non-uniform background (≈#9bd0fc).
&lt;span class=&quot;d&quot;&gt;        at main &amp;gt; section.hero &amp;gt; h1  &amp;quot;Lisbon, 21°&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /contrast-before.html · all viewports · see .renderlint/screens/contrast-before-html-eaveh@375.png #1&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;       fix use background #7096b5 (currently #ffffff on #9bd0fc)&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Each run also saves annotated screenshots with each finding boxed and numbered, so an agent with vision can look at what is wrong.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-compare-donut-a32ee2f3-806.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-compare-donut-a32ee2f3-640.webp 640w, https://renderlint.yitec.net/img/docs-compare-donut-a32ee2f3-806.webp 806w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;806&quot; height=&quot;478&quot; alt=&quot;Donut labels clipped at 375px without renderlint, wrapped with it&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;/figure&gt;


&lt;p&gt;&lt;em&gt;Caption:&lt;/em&gt; A real Haiku session: donut labels clipped on phones, then fixed.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-make-claude-code-check-its-ui-every-time&quot;&gt;How do you make Claude Code check its UI every time?&lt;/h2&gt;
&lt;p&gt;Install a Stop hook. &lt;code&gt;npx -y @yitec/renderlint init&lt;/code&gt; adds one to &lt;code&gt;.claude/settings.json&lt;/code&gt; (&lt;code&gt;--no-hook&lt;/code&gt; skips it). It runs &lt;code&gt;npx renderlint hook&lt;/code&gt; when Claude is about to end a turn. If errors remain, the hook prints the report to stderr and exits with code 2, which makes Claude keep working instead of stopping.&lt;/p&gt;
&lt;p&gt;How the hook behaves:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Behaviour&lt;/th&gt;
&lt;th&gt;Detail&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Runs only when UI files changed&lt;/td&gt;
&lt;td&gt;It fingerprints UI files (HTML, JSX/TSX, Vue, Svelte, Astro, CSS and similar, plus templates) by modified time and size, and skips folders such as &lt;code&gt;node_modules&lt;/code&gt;, &lt;code&gt;dist&lt;/code&gt; and &lt;code&gt;.next&lt;/code&gt;. No change since the last clean run, or no UI files touched this turn: it exits 0.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Blocks with exit code 2&lt;/td&gt;
&lt;td&gt;The message says the agent is not done, to fix every error in the source, and not to silence a finding to get done.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gives up after 4 attempts&lt;/td&gt;
&lt;td&gt;After 4 blocks in a row it prints how many errors remain and lets Claude stop, telling it to report the unresolved defects. It can&amp;#39;t trap the agent.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Never traps on its own failures&lt;/td&gt;
&lt;td&gt;If renderlint can&amp;#39;t run (no server, an internal error), it prints a note and exits 0.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Re-checks only affected routes&lt;/td&gt;
&lt;td&gt;After a full run it knows which files each route renders. It re-checks the routes an edit can affect, plus any route that still had errors, and says so (for example, &amp;quot;re-checked 3 of 46 route(s) affected by 1 changed file(s)&amp;quot;).&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;On a 46-route Next.js app, an edit to one component re-checked 3 to 9 pages in 6 to 17 seconds, global CSS re-checked 46 pages in 79 seconds, and a full run took 167 seconds. Across 30 typical edits the hook missed no page whose rendering changed. An edit to global CSS, the layout or a shared module re-checks every route.&lt;/p&gt;
&lt;p&gt;The message also says how to ignore something, but only if the user wants it that way: &lt;code&gt;data-renderlint-ignore=&amp;quot;&amp;lt;rule&amp;gt;&amp;quot;&lt;/code&gt; and &lt;code&gt;data-renderlint-reason=&amp;quot;…&amp;quot;&lt;/code&gt; on the element, or a &lt;code&gt;// renderlint-ignore &amp;lt;rule&amp;gt; -- &amp;lt;reason&amp;gt;&lt;/code&gt; comment above a source line.&lt;/p&gt;
&lt;h2 id=&quot;what-about-cursor-codex-copilot-and-other-agents&quot;&gt;What about Cursor, Codex, Copilot and other agents?&lt;/h2&gt;
&lt;p&gt;The Stop hook is installed for Claude Code only. For other agents the workflow goes into instructions. &lt;code&gt;init&lt;/code&gt; writes a &amp;quot;UI quality gate: renderlint&amp;quot; section into &lt;code&gt;AGENTS.md&lt;/code&gt;, which Codex, Cursor, Copilot, Gemini CLI, Amp, Zed and others read, and creates &lt;code&gt;CLAUDE.md&lt;/code&gt; importing it. The section tells the agent to run &lt;code&gt;npx renderlint&lt;/code&gt; after UI changes, fix every error, never hide symptoms, and read the matching skill before setup or fix work.&lt;/p&gt;
&lt;p&gt;&lt;code&gt;init&lt;/code&gt; also installs three skills in &lt;code&gt;.claude/skills/&lt;/code&gt;, plain Markdown any agent can read:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Skill&lt;/th&gt;
&lt;th&gt;What it covers&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;renderlint-setup&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Making every page and role checked: sign-in, roles, mocks, dynamic route params, coverage gaps&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;renderlint-fix&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Fixing findings at the root, rule by rule, and marking intentional cases with a reason&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;renderlint-e2e&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The Playwright fixture, Storybook stories, MSW handlers and HAR recordings&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;If your agent reads &lt;code&gt;.cursorrules&lt;/code&gt;, &lt;code&gt;.github/copilot-instructions.md&lt;/code&gt; or &lt;code&gt;GEMINI.md&lt;/code&gt; instead, copy the section there or point those files at &lt;code&gt;AGENTS.md&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;what-is-the-one-line-setup-prompt&quot;&gt;What is the one-line setup prompt?&lt;/h3&gt;
&lt;p&gt;Paste this into the agent:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Set up renderlint in this project: run &lt;code&gt;npx -y @yitec/renderlint init&lt;/code&gt;, then follow the &amp;quot;UI quality gate: renderlint&amp;quot; section it adds to AGENTS.md: after every UI change run &lt;code&gt;npx renderlint&lt;/code&gt; and fix every reported error until it shows 0 errors.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The experiment&amp;#39;s second condition added a similar sentence to the prompt. Running &lt;code&gt;init&lt;/code&gt; again is safe: it updates skills it installed and leaves ones you edited alone.&lt;/p&gt;
&lt;h2 id=&quot;should-you-also-check-at-build-time-and-while-coding&quot;&gt;Should you also check at build time and while coding?&lt;/h2&gt;
&lt;p&gt;Yes, with different tools for different moments. In CI, &lt;code&gt;npx renderlint --format github&lt;/code&gt; gives inline PR annotations, and &lt;code&gt;init&lt;/code&gt; appends a check to your build script, such as &lt;code&gt;vite build &amp;amp;&amp;amp; renderlint dist&lt;/code&gt;. During development, the Vite plugin shows a live overlay that links each finding to its component file and line.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-dev-overlay-617d0ea5-1280.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-dev-overlay-617d0ea5-640.webp 640w, https://renderlint.yitec.net/img/docs-dev-overlay-617d0ea5-960.webp 960w, https://renderlint.yitec.net/img/docs-dev-overlay-617d0ea5-1280.webp 1280w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1280&quot; height=&quot;800&quot; alt=&quot;renderlint's dev overlay on a React dashboard, listing findings with source file and line&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;/figure&gt;


&lt;p&gt;&lt;em&gt;Caption:&lt;/em&gt; The Vite plugin&amp;#39;s overlay: hover a finding to highlight it.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;The defects agents ship come from a few rules. &lt;code&gt;contrast&lt;/code&gt; captures the page twice, once normally and once with all text transparent, so it reads the real background behind each glyph, including gradients and images. &lt;code&gt;text-clipped&lt;/code&gt; and &lt;code&gt;text-overflow&lt;/code&gt; compare the rects of every text run with its containers and clip boxes, including SVG chart labels. &lt;code&gt;fragile-layout&lt;/code&gt; re-runs the layout rules at 13 widths from 320 to 1920px and with longer text, long words, bigger numbers and longer API data, and reports what only breaks under stress. &lt;code&gt;emoji&lt;/code&gt; scans the rendered DOM and source files. See &lt;a href=&quot;https://renderlint.yitec.net/rules/#contrast&quot;&gt;rules&lt;/a&gt; and the &lt;a href=&quot;https://renderlint.yitec.net/blog/text-overflow-clipped-text-responsive-layouts/&quot;&gt;text overflow guide&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Limits: &lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; charts are pixels, so their labels can&amp;#39;t be inspected. Contrast follows WCAG 2 AA and doesn&amp;#39;t apply APCA. A single page takes about 4 to 10 seconds at three viewports with the sweep and stress passes, so use &lt;code&gt;--sweep 1024&lt;/code&gt; or &lt;code&gt;--no-sweep&lt;/code&gt; for a faster inner loop. Pages behind a login need &lt;code&gt;auth&lt;/code&gt; (&lt;a href=&quot;https://renderlint.yitec.net/blog/test-every-route-and-role-behind-login/&quot;&gt;how to test every route and role&lt;/a&gt;). An agent can still add an ignore, which is why the instructions require a written reason and reviewers should read ignores like an &lt;code&gt;eslint-disable&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;does-the-hook-slow-the-agent-down&quot;&gt;Does the hook slow the agent down?&lt;/h3&gt;
&lt;p&gt;Only when UI files changed, and after a full run it re-checks only the routes an edit affects. A page takes about 4 to 10 seconds with the sweep and stress passes.&lt;/p&gt;
&lt;h3 id=&quot;can-the-hook-get-the-agent-stuck-in-a-loop&quot;&gt;Can the hook get the agent stuck in a loop?&lt;/h3&gt;
&lt;p&gt;No. It gives up after 4 blocks in a row and tells the agent to report what is unresolved.&lt;/p&gt;
&lt;h3 id=&quot;do-agents-just-add-ignore-comments&quot;&gt;Do agents just add ignore comments?&lt;/h3&gt;
&lt;p&gt;The instructions tell them to fix root causes first and to add a reason when they ignore something. Review ignores in the diff.&lt;/p&gt;
</content>
</entry>
<entry>
<title>Visual regression testing vs rendered-UI linting</title>
<link href="https://renderlint.yitec.net/blog/visual-regression-testing-vs-rendered-ui-linting/"/>
<id>https://renderlint.yitec.net/blog/visual-regression-testing-vs-rendered-ui-linting/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Visual regression tools diff screenshots against an approved baseline. A rendered-UI linter judges the page itself. When to use each, and how to run both in CI.</summary>
<content type="html">&lt;p&gt;Visual regression testing compares screenshots of your pages with approved images and fails when pixels change. Rendered-UI linting opens the page in a browser and checks it against rules, such as text that doesn&amp;#39;t fit, contrast below 4.5:1, or content nobody can scroll to, with no baseline. They answer different questions. Visual regression asks &amp;quot;did this change?&amp;quot;. A rendered-UI linter asks &amp;quot;is this wrong?&amp;quot;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Use visual regression to protect a design you have approved from unintended change.&lt;/li&gt;
&lt;li&gt;Use a rendered-UI linter for pages nobody has approved yet, and for defects that appear at widths and with data your screenshots never used.&lt;/li&gt;
&lt;li&gt;They don&amp;#39;t compete. You can run both.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-does-visual-regression-testing-do&quot;&gt;What does visual regression testing do?&lt;/h2&gt;
&lt;p&gt;You capture a screenshot of each page or component, store it as the baseline, and on later runs capture it again and compare. If the difference is over a threshold, the test fails and a person looks at the diff. Percy and Chromatic are hosted services built around this review step. BackstopJS keeps reference images on disk, usually committed with your code, and compares against them (&lt;code&gt;backstop reference&lt;/code&gt;, then &lt;code&gt;backstop test&lt;/code&gt;). Playwright&amp;#39;s &lt;code&gt;toHaveScreenshot()&lt;/code&gt; does the same inside your test runner, with options such as a pixel-difference threshold.&lt;/p&gt;
&lt;p&gt;This is excellent at one thing: telling you that something moved. A designer approved a page, a refactor changes a margin by 4px, and the diff shows it.&lt;/p&gt;
&lt;h2 id=&quot;what-does-a-rendered-ui-linter-do&quot;&gt;What does a rendered-UI linter do?&lt;/h2&gt;
&lt;p&gt;It renders the app in headless Chromium at several widths, measures it, and applies rules. renderlint measures the rects of every text run against their containers and clip boxes, tests overlap and occlusion with &lt;code&gt;elementsFromPoint&lt;/code&gt;, reads computed styles, and for contrast captures the page twice, once normally and once with all text transparent, to read the real background behind each glyph. Then it reports each defect with the element, the source file, an annotated screenshot and a fix.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-988.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-640.webp 640w, https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-960.webp 960w, https://renderlint.yitec.net/img/docs-demo-sweep-296d33c6-988.webp 988w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;988&quot; height=&quot;516&quot; alt=&quot;KPI cards: fine at 1280px, the spend value cut off at 1024px and boxed by renderlint&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;/figure&gt;


&lt;p&gt;&lt;em&gt;Caption:&lt;/em&gt; A layout that is fine at 1280px and cut off at 1024px. renderlint boxes the failing value and reports the width.&lt;/p&gt;
&lt;h2 id=&quot;how-do-they-compare&quot;&gt;How do they compare?&lt;/h2&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question&lt;/th&gt;
&lt;th&gt;Visual regression (Percy, Chromatic, BackstopJS, Playwright screenshots)&lt;/th&gt;
&lt;th&gt;renderlint&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;What it reads&lt;/td&gt;
&lt;td&gt;Pixels, against approved images&lt;/td&gt;
&lt;td&gt;Rendered geometry and pixels&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Needs a baseline&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Finds a defect in a page nobody has approved&lt;/td&gt;
&lt;td&gt;No: the first version becomes the baseline&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Overflow, overlap, clipping&lt;/td&gt;
&lt;td&gt;Only as a diff from the baseline&lt;/td&gt;
&lt;td&gt;Yes, at every width and with stressed content&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Contrast over gradients and images&lt;/td&gt;
&lt;td&gt;Only as a diff&lt;/td&gt;
&lt;td&gt;Yes, from the real pixels behind each glyph&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tells you the fix&lt;/td&gt;
&lt;td&gt;No: shows what changed, not what&amp;#39;s wrong&lt;/td&gt;
&lt;td&gt;Yes: element, source file, screenshot and fix&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Catches &amp;quot;someone changed the design&amp;quot;&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Intentional redesign&lt;/td&gt;
&lt;td&gt;Update the baseline&lt;/td&gt;
&lt;td&gt;Nothing to update&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Works on canvas charts&lt;/td&gt;
&lt;td&gt;As pixels, against a baseline&lt;/td&gt;
&lt;td&gt;No: canvas labels are pixels the DOM doesn&amp;#39;t describe&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The row to look at is the third one: a defect in the first version becomes the baseline. If a page ships with white text on a light gradient and someone approves the first screenshot, every later run agrees with it. The tool is working correctly. It was never asked whether the page was right.&lt;/p&gt;
&lt;p&gt;For comparison with other tools: ESLint, stylelint and TypeScript read source code and can&amp;#39;t see rendered overflow. axe-core and Lighthouse read the DOM and computed CSS, catch no overflow or overlap, and report contrast over gradients and images as &amp;quot;needs review&amp;quot;. renderlint doesn&amp;#39;t replace those. It covers the gap between &amp;quot;the code is valid&amp;quot; and &amp;quot;the page looks right&amp;quot;.&lt;/p&gt;
&lt;h2 id=&quot;when-do-baselines-help&quot;&gt;When do baselines help?&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Approved design, stable page.&lt;/strong&gt; A marketing page the design team signed off, a component library, a checkout. You want any change to be a conscious one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refactors.&lt;/strong&gt; Swapping a CSS framework or upgrading a UI library should change nothing visible. A diff proves that.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Browsers other than Chromium.&lt;/strong&gt; renderlint renders in headless Chromium only. If you need other engines compared, that is a job for a tool built for it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Review.&lt;/strong&gt; A diff that a designer can approve in a pull request is a workflow a linter doesn&amp;#39;t have.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;when-do-baselines-fail-you&quot;&gt;When do baselines fail you?&lt;/h2&gt;
&lt;h3 id=&quot;what-happens-when-the-first-version-is-already-broken&quot;&gt;What happens when the first version is already broken?&lt;/h3&gt;
&lt;p&gt;It becomes the baseline. This is the case for any code an AI coding agent wrote in the last hour: nobody has approved the page, and the first screenshot is whatever came out. In the renderlint experiment (22 headless Claude Code sessions), the 11 baseline apps had 229 errors, mostly WCAG contrast failures. A baseline taken from any of them would have frozen those failures in. See &lt;a href=&quot;https://renderlint.yitec.net/blog/catch-ui-bugs-ai-coding-agents/&quot;&gt;how to catch UI bugs written by AI coding agents&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;why-are-screenshot-diffs-flaky&quot;&gt;Why are screenshot diffs flaky?&lt;/h3&gt;
&lt;p&gt;Several things differ between runs and have nothing to do with your change: font loading and anti-aliasing, animations caught mid-frame, lazy content, scroll-reveal sections, timestamps and live data, a hover state, ad slots. The usual answer is to freeze the clock, mock the data, disable animations, wait for fonts, mask regions, and raise the diff threshold. Every one of those reduces what the test can see. renderlint waits for fonts and images, scrolls to trigger lazy content, and jumps animations to their final state before measuring. It also measures rects and pixels behind text against rules, rather than comparing whole images with a baseline.&lt;/p&gt;
&lt;h3 id=&quot;how-many-widths-and-content-variants-do-you-really-screenshot&quot;&gt;How many widths and content variants do you really screenshot?&lt;/h3&gt;
&lt;p&gt;A baseline covers the viewport and data you captured. A layout that breaks only at 1024px, or only when a name is 40 characters long, shows up in a screenshot suite only if you took that screenshot, and the baseline for it has to be approved first. renderlint re-runs its layout rules at 13 widths from 320 to 1920px and on both sides of every breakpoint the page uses, then with 50% longer text, 36+ character words with no break points, three more digits on numbers, declared worst cases (&lt;code&gt;data-renderlint-maxlength=&amp;quot;60&amp;quot;&lt;/code&gt;) and longer API data. Anything that only breaks under stress becomes a &lt;code&gt;fragile-layout&lt;/code&gt; warning.&lt;/p&gt;
&lt;h3 id=&quot;does-a-diff-tell-you-what-to-fix&quot;&gt;Does a diff tell you what to fix?&lt;/h3&gt;
&lt;p&gt;It tells you what changed. A red region says &amp;quot;these pixels differ&amp;quot;, and someone works out why. A renderlint finding says what is wrong, where, and what to try:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; Text is cut off by an overflow:hidden container (12px past the right edge).
&lt;span class=&quot;d&quot;&gt;        at div.kpis &amp;gt; div.kpi:nth-of-type(1) &amp;gt; div.v  &amp;quot;$4,939.27&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /usage · at 1024px · see .renderlint/screens/usage@1024.png #1&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That example comes from renderlint&amp;#39;s own documentation, not from one of the captured runs. A contrast finding adds a &lt;code&gt;fix&lt;/code&gt; line, for example &lt;code&gt;use text #2e2e2e (currently #ffffff on #459bf4)&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;what-can-a-linter-find-that-no-diff-would&quot;&gt;What can a linter find that no diff would?&lt;/h2&gt;
&lt;p&gt;Defects that are the same in every version:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Defect&lt;/th&gt;
&lt;th&gt;Rule&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Text running past its card, button or badge&lt;/td&gt;
&lt;td&gt;&lt;code&gt;text-overflow&lt;/code&gt;, &lt;code&gt;text-clipped&lt;/code&gt;, &lt;code&gt;text-crowding&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Contrast below WCAG AA on gradients and images&lt;/td&gt;
&lt;td&gt;&lt;code&gt;contrast&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Content painted below an &lt;code&gt;overflow: hidden&lt;/code&gt; app shell that never became a scroller&lt;/td&gt;
&lt;td&gt;&lt;code&gt;unreachable-content&lt;/code&gt; (renderlint turns the mouse wheel to make sure)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A dropdown opening behind the next card&lt;/td&gt;
&lt;td&gt;&lt;code&gt;popup-obscured&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A page that stays blank while its data loads&lt;/td&gt;
&lt;td&gt;&lt;code&gt;loading-state&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A page that only showed the login form&lt;/td&gt;
&lt;td&gt;&lt;code&gt;auth-required&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;undefined&lt;/code&gt;, &lt;code&gt;NaN&lt;/code&gt;, &lt;code&gt;Invalid Date&lt;/code&gt; in a tile&lt;/td&gt;
&lt;td&gt;&lt;code&gt;placeholder-text&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Some of these can&amp;#39;t be a screenshot test at all. &lt;code&gt;popup-obscured&lt;/code&gt; opens each menu, which a static screenshot of the closed page never shows. &lt;code&gt;loading-state&lt;/code&gt; holds the page&amp;#39;s fetch and XHR requests for a second, because on a fast dev machine the page never looks blank. &lt;code&gt;auth-required&lt;/code&gt; is about a page the screenshot never reached.&lt;/p&gt;
&lt;h2 id=&quot;what-cant-renderlint-do&quot;&gt;What can&amp;#39;t renderlint do?&lt;/h2&gt;
&lt;p&gt;Being fair means saying where a baseline tool wins or renderlint stops:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It can&amp;#39;t tell you a page is ugly, off brand, or different from the mock-up. It has no design reference.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; charts (Chart.js, ECharts in canvas mode) are pixels, so renderlint can&amp;#39;t inspect their labels. A screenshot diff sees them, as pixels.&lt;/li&gt;
&lt;li&gt;Contrast follows WCAG 2 AA math. It doesn&amp;#39;t model font weight beyond the large-text rule, and doesn&amp;#39;t apply APCA.&lt;/li&gt;
&lt;li&gt;Pages are checked as they load, with each menu opened. Dialogs, tabs and filled forms are rendered and judged by &lt;code&gt;--ux&lt;/code&gt;, but their layout is only linted when you list them in &lt;code&gt;states&lt;/code&gt; or reach them in a Playwright test.&lt;/li&gt;
&lt;li&gt;A run takes about 4 to 10 seconds per page at three viewports with the sweep and stress passes. &lt;code&gt;--sweep 1024&lt;/code&gt; or &lt;code&gt;--no-sweep&lt;/code&gt; gives a faster inner loop.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It is also tuned for a low false-positive rate, so it leaves alone what is usually intentional: &lt;code&gt;text-overflow: ellipsis&lt;/code&gt;, &lt;code&gt;line-clamp&lt;/code&gt;, screen-reader-only text, closed accordions, off-canvas menus, carousels, scroll areas and modals. Anything on purpose can be marked &lt;code&gt;data-renderlint-ignore&lt;/code&gt; with a reason.&lt;/p&gt;
&lt;h2 id=&quot;can-you-use-both-in-ci&quot;&gt;Can you use both in CI?&lt;/h2&gt;
&lt;p&gt;Yes, and they don&amp;#39;t need to know about each other. A reasonable split:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Every PR:&lt;/strong&gt; run the linter. It needs no baseline, so there is nothing to approve. Exit code 1 means errors. &lt;code&gt;npx renderlint --format github&lt;/code&gt; annotates the PR.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stable, approved pages:&lt;/strong&gt; add screenshot comparison for the pages and components where unintended change matters.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The two meet in Playwright.&lt;/strong&gt; If your e2e tests already use &lt;code&gt;toHaveScreenshot()&lt;/code&gt;, &lt;code&gt;withRenderlint(test)&lt;/code&gt; checks each state those tests reach, so a state is both diffed and linted.&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;# every pull request: no baseline needed
npx renderlint --format github

# fail when routes go unchecked
npx renderlint --min-coverage 100&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;In this comparison renderlint is the second tool: it looks at the rendered page rather than at a change. Geometry rules find text that doesn&amp;#39;t fit, &lt;code&gt;contrast&lt;/code&gt; reads the real pixels behind each glyph, the stress passes find what breaks only with other widths or data, and &lt;code&gt;unreachable-content&lt;/code&gt; and &lt;code&gt;popup-obscured&lt;/code&gt; interact with the page (the mouse wheel, opening menus). The checks and their limits are in the &lt;a href=&quot;https://renderlint.yitec.net/rules/#text-overflow&quot;&gt;rules reference&lt;/a&gt; and the &lt;a href=&quot;https://renderlint.yitec.net/examples/&quot;&gt;examples&lt;/a&gt;. On a page that already passes, there is nothing for it to report, and then a baseline tool is what tells you the page later changed.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;is-renderlint-a-replacement-for-percy-chromatic-or-backstopjs&quot;&gt;Is renderlint a replacement for Percy, Chromatic or BackstopJS?&lt;/h3&gt;
&lt;p&gt;No. It doesn&amp;#39;t compare against approved images and can&amp;#39;t tell you a page changed. It finds defects in a page without one.&lt;/p&gt;
&lt;h3 id=&quot;can-a-visual-regression-test-catch-contrast-or-overflow&quot;&gt;Can a visual regression test catch contrast or overflow?&lt;/h3&gt;
&lt;p&gt;Only if the baseline already showed a correct page, and only as a diff. A defect present from the start is part of the baseline.&lt;/p&gt;
&lt;h3 id=&quot;do-i-need-a-baseline-for-renderlint&quot;&gt;Do I need a baseline for renderlint?&lt;/h3&gt;
&lt;p&gt;No. Rules run on the rendered page. Tell it about intentional cases with &lt;code&gt;data-renderlint-ignore&lt;/code&gt; and a reason.&lt;/p&gt;
</content>
</entry>
<entry>
<title>How to replace alert(), confirm() and prompt() in a web app</title>
<link href="https://renderlint.yitec.net/blog/replace-alert-confirm-prompt/"/>
<id>https://renderlint.yitec.net/blog/replace-alert-confirm-prompt/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Native alert(), confirm() and prompt() block the page and can't be styled or translated. Replace them with toasts, inline messages and a promise-based dialog.</summary>
<content type="html">&lt;p&gt;&lt;code&gt;alert()&lt;/code&gt;, &lt;code&gt;confirm()&lt;/code&gt; and &lt;code&gt;prompt()&lt;/code&gt; open the browser&amp;#39;s own gray system dialog. It blocks the page, ignores your design, can&amp;#39;t be styled or translated by you, and can be suppressed by the browser. Replace each by what it was used for: a toast for a notice, an inline message for a validation error, and a modal &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; for a confirmation or a question. The &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; element with &lt;code&gt;showModal()&lt;/code&gt; handles focus and Escape for you.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;alert(&amp;quot;Saved&amp;quot;)&lt;/code&gt; becomes a toast or a status message.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;alert(&amp;quot;Invalid email&amp;quot;)&lt;/code&gt; becomes an inline message next to the field.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;confirm(&amp;quot;Delete this project?&amp;quot;)&lt;/code&gt; becomes a modal dialog with Cancel and Delete.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;prompt(&amp;quot;Name?&amp;quot;)&lt;/code&gt; becomes a dialog with a labeled input.&lt;/li&gt;
&lt;li&gt;Keep the old code path working by returning a promise.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;whats-wrong-with-alert-confirm-and-prompt&quot;&gt;What&amp;#39;s wrong with alert(), confirm() and prompt()?&lt;/h2&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Problem&lt;/th&gt;
&lt;th&gt;Why it matters&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;They block the page&lt;/td&gt;
&lt;td&gt;The script stops until the user answers. Timers and updates wait.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;You can&amp;#39;t style them&lt;/td&gt;
&lt;td&gt;The gray box ignores your fonts, colors and brand, and looks out of place in a product.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;You can&amp;#39;t translate them&lt;/td&gt;
&lt;td&gt;The buttons and the browser&amp;#39;s chrome follow the browser&amp;#39;s language, not your app&amp;#39;s.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;They can be suppressed&lt;/td&gt;
&lt;td&gt;Browsers can stop a page from showing them, for example after a &amp;quot;prevent this page from creating additional dialogs&amp;quot; choice, or when called from some embedded frames. Code that relies on &lt;code&gt;confirm()&lt;/code&gt; can then behave as if the user had cancelled, with no prompt ever shown.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;They carry little information&lt;/td&gt;
&lt;td&gt;Plain text only: no title, no danger styling on the destructive button, no link to details.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Suppression and plain text matter most for destructive actions. A confirmation that disappears, or that looks the same as every other prompt, is a weak guard in front of &amp;quot;delete project&amp;quot;.&lt;/p&gt;
&lt;h2 id=&quot;what-should-you-use-instead&quot;&gt;What should you use instead?&lt;/h2&gt;
&lt;p&gt;Match the replacement to the purpose of the dialog:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You used&lt;/th&gt;
&lt;th&gt;For&lt;/th&gt;
&lt;th&gt;Use instead&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;alert(&amp;quot;Saved&amp;quot;)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A notice&lt;/td&gt;
&lt;td&gt;A toast or snackbar (&lt;code&gt;role=&amp;quot;status&amp;quot;&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;alert(&amp;quot;Enter a valid email&amp;quot;)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A validation error&lt;/td&gt;
&lt;td&gt;An inline message next to the field&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;confirm(&amp;quot;Delete this project?&amp;quot;)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A confirmation&lt;/td&gt;
&lt;td&gt;A modal dialog: &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; with &lt;code&gt;showModal()&lt;/code&gt;, or Radix / shadcn AlertDialog, Headless UI Dialog, Angular Material MatDialog, Vuetify v-dialog&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;prompt(&amp;quot;Rename to:&amp;quot;)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Asking for a value&lt;/td&gt;
&lt;td&gt;The same dialog with a labeled input&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;Use the toast and dialog components the project already has before adding a library. Most design systems have both.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-build-a-confirm-replacement-with-the-dialog-element&quot;&gt;How do you build a confirm() replacement with the dialog element?&lt;/h2&gt;
&lt;p&gt;The &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; element is built into the browser. Opened with &lt;code&gt;showModal()&lt;/code&gt; it sits in the top layer, puts a backdrop behind it, makes the rest inert, closes on Escape, and returns focus to the element that opened it. That is most of what a custom modal normally gets wrong. This is close to the markup of the fixed example page:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;dialog id=&amp;quot;confirm&amp;quot; aria-labelledby=&amp;quot;ct&amp;quot;&amp;gt;
  &amp;lt;h2 id=&amp;quot;ct&amp;quot;&amp;gt;Delete this project?&amp;lt;/h2&amp;gt;
  &amp;lt;p&amp;gt;This removes 214 deployments and can't be undone.&amp;lt;/p&amp;gt;
  &amp;lt;form method=&amp;quot;dialog&amp;quot; class=&amp;quot;row&amp;quot;&amp;gt;
    &amp;lt;button value=&amp;quot;cancel&amp;quot; autofocus&amp;gt;Cancel&amp;lt;/button&amp;gt;
    &amp;lt;button value=&amp;quot;delete&amp;quot; class=&amp;quot;danger&amp;quot;&amp;gt;Delete project&amp;lt;/button&amp;gt;
  &amp;lt;/form&amp;gt;
&amp;lt;/dialog&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A form with &lt;code&gt;method=&amp;quot;dialog&amp;quot;&lt;/code&gt; closes the dialog on submit and puts the clicked button&amp;#39;s &lt;code&gt;value&lt;/code&gt; in &lt;code&gt;dialog.returnValue&lt;/code&gt;. Putting &lt;code&gt;autofocus&lt;/code&gt; on Cancel makes the safe choice the default for a destructive action.&lt;/p&gt;
&lt;p&gt;To keep the call sites as simple as &lt;code&gt;if (confirm(...))&lt;/code&gt;, wrap it in a promise:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function confirmDialog({ title, message, confirmLabel = &amp;quot;OK&amp;quot; }) {
  return new Promise((resolve) =&amp;gt; {
    const dlg = document.createElement(&amp;quot;dialog&amp;quot;);
    dlg.setAttribute(&amp;quot;aria-labelledby&amp;quot;, &amp;quot;cd-title&amp;quot;);
    dlg.innerHTML = `
      &amp;lt;h2 id=&amp;quot;cd-title&amp;quot;&amp;gt;&amp;lt;/h2&amp;gt;
      &amp;lt;p&amp;gt;&amp;lt;/p&amp;gt;
      &amp;lt;form method=&amp;quot;dialog&amp;quot;&amp;gt;
        &amp;lt;button value=&amp;quot;cancel&amp;quot; autofocus&amp;gt;Cancel&amp;lt;/button&amp;gt;
        &amp;lt;button value=&amp;quot;ok&amp;quot; class=&amp;quot;danger&amp;quot;&amp;gt;&amp;lt;/button&amp;gt;
      &amp;lt;/form&amp;gt;`;
    dlg.querySelector(&amp;quot;h2&amp;quot;).textContent = title;
    dlg.querySelector(&amp;quot;p&amp;quot;).textContent = message ?? &amp;quot;&amp;quot;;
    dlg.querySelector(&amp;quot;[value=ok]&amp;quot;).textContent = confirmLabel;
    dlg.addEventListener(&amp;quot;close&amp;quot;, () =&amp;gt; {
      resolve(dlg.returnValue === &amp;quot;ok&amp;quot;);
      dlg.remove();
    });
    document.body.append(dlg);
    dlg.showModal();
  });
}

// before: if (window.confirm(&amp;quot;Delete this project?&amp;quot;)) { ... }
// after:
if (await confirmDialog({ title: &amp;quot;Delete this project?&amp;quot;, confirmLabel: &amp;quot;Delete&amp;quot; })) {
  await fetch(&amp;quot;/api/projects/42&amp;quot;, { method: &amp;quot;DELETE&amp;quot; });
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Escape fires &lt;code&gt;close&lt;/code&gt; with the &lt;code&gt;returnValue&lt;/code&gt; unchanged (empty), so it resolves to &lt;code&gt;false&lt;/code&gt;: cancelling by Escape is the same as pressing Cancel. The text is set with &lt;code&gt;textContent&lt;/code&gt;, not interpolated into HTML, so a project name with markup in it can&amp;#39;t inject anything. A &lt;code&gt;prompt()&lt;/code&gt; replacement is the same pattern with an &lt;code&gt;&amp;lt;input&amp;gt;&lt;/code&gt; inside the form and &lt;code&gt;returnValue&lt;/code&gt; plus the input&amp;#39;s value read on close.&lt;/p&gt;
&lt;h2 id=&quot;do-you-still-need-to-manage-focus-and-escape&quot;&gt;Do you still need to manage focus and Escape?&lt;/h2&gt;
&lt;p&gt;If you use &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; with &lt;code&gt;showModal()&lt;/code&gt;, mostly no. If you build a modal from divs, you do:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Move focus into the dialog when it opens (the first field, or the close button).&lt;/li&gt;
&lt;li&gt;Close it on Escape.&lt;/li&gt;
&lt;li&gt;When it closes, call &lt;code&gt;.focus()&lt;/code&gt; on the element that opened it, so keyboard users don&amp;#39;t land at the top of the page.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This is the WAI-ARIA dialog pattern and WCAG 2.4.3 (focus order). Hand-made modals are where it tends to go wrong, which is why renderlint checks it separately with &lt;code&gt;dialog-focus&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;The rule is &lt;code&gt;native-dialog&lt;/code&gt; (error by default, &lt;a href=&quot;https://renderlint.yitec.net/rules/#native-dialog&quot;&gt;rule reference&lt;/a&gt;). renderlint finds native dialogs two ways. At runtime, when one opens while a page is checked, it records the call and where it was made, and answers confirm and prompt with Cancel. In source code, it finds &lt;code&gt;window.confirm(…)&lt;/code&gt; and &lt;code&gt;alert(…)&lt;/code&gt;, which also catches the ones behind a click.&lt;/p&gt;
&lt;p&gt;For the example page, a plain run at three widths found the &lt;code&gt;alert()&lt;/code&gt; that opens on load:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ native-dialog (1)  The app uses the browser's own alert(), confirm() or prompt() box: a grey system dialog that blocks the page, ignores the app's design and can't be styled or translated. Found when one opens while a page is checked, and in source code (`window.confirm(…)`, `alert(…)`), which also catches the ones behind a click. The browser's &amp;quot;Leave site?&amp;quot; prompt from `beforeunload` is not flagged.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; alert() &amp;quot;Your trial ends in 3 days&amp;quot; opened the browser's native dialog, called at /dialog-before.html:4:51. Replace it with the app's own toast or snackbar (&amp;quot;Saved&amp;quot;), or with an inline message next to the field for a form error. Use the toast/dialog component the project already has (search for one: sonner, react-hot-toast, a components/ui/dialog, MatDialog / MatSnackBar, ElMessageBox…) before adding a library.
&lt;span class=&quot;d&quot;&gt;        page /dialog-before.html · all viewports&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The same page also calls &lt;code&gt;confirm(&amp;quot;Delete this project?&amp;quot;)&lt;/code&gt; from a click handler. The plain run did not report it. A run with &lt;code&gt;--ux&lt;/code&gt;, which clicks the page&amp;#39;s buttons, reports two errors:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ native-dialog (2)  The app uses the browser's own alert(), confirm() or prompt() box: a grey system dialog that blocks the page, ignores the app's design and can't be styled or translated. Found when one opens while a page is checked, and in source code (`window.confirm(…)`, `alert(…)`), which also catches the ones behind a click. The browser's &amp;quot;Leave site?&amp;quot; prompt from `beforeunload` is not flagged.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; alert() &amp;quot;Your trial ends in 3 days&amp;quot; opened the browser's native dialog, called at /dialog-before.html:4:51. …
&lt;span class=&quot;d&quot;&gt;        page /dialog-before.html · all viewports&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; confirm() &amp;quot;Delete this project?&amp;quot; opened the browser's native dialog, called at /dialog-before.html:5:72. Replace it with the app's own confirmation modal and continue only when the user confirms there (e.g. `if (await confirmDialog({ title: 'Delete this project?', confirmLabel: 'Delete' }))`, an AlertDialog with Cancel / Delete). Use the toast/dialog component the project already has (search for one: sonner, react-hot-toast, a components/ui/dialog, MatDialog / MatSnackBar, ElMessageBox…) before adding a library.
&lt;span class=&quot;d&quot;&gt;        page /dialog-before.html · at 375px&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;(The &lt;code&gt;…&lt;/code&gt; stands for the rest of the alert message, which is the same as above.) The fixed page, with a &lt;code&gt;role=&amp;quot;status&amp;quot;&lt;/code&gt; notice instead of the alert and a &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; instead of the confirm, printed &lt;code&gt;✔ No UI defects found.&lt;/code&gt;&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-dialog-after-3a3602e2-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-dialog-after-3a3602e2-640.webp 640w, https://renderlint.yitec.net/img/captures-dialog-after-3a3602e2-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;546&quot; alt=&quot;The fixed Project settings page at 768px: a yellow notice reads Your trial ends in 3 days, and a modal dialog over a dimmed page asks Delete this project? with Cancel and Delete project buttons&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;The fixed page at 768px: a status message for the trial notice and a styled modal for the delete confirmation. A native alert can&amp;#39;t be screenshotted, so there is no &amp;quot;before&amp;quot; picture.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;&lt;code&gt;dialog-focus&lt;/code&gt; is a &lt;code&gt;--ux&lt;/code&gt; warning. It checks the modal dialogs that its clicks open: &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; opened with &lt;code&gt;showModal()&lt;/code&gt;, &lt;code&gt;aria-modal&lt;/code&gt;, &lt;code&gt;alertdialog&lt;/code&gt;, or a dialog over a full-screen overlay. It flags a dialog that leaves focus on the page behind it, doesn&amp;#39;t close on Escape, or drops focus to the top of the page when it closes instead of returning it to the control that opened it. In the renderlint benchmark it flagged 3 of 3 bad hand-made modals and none of the 3 correct ones, including &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; with &lt;code&gt;showModal()&lt;/code&gt;. renderlint never clicks &amp;quot;OK&amp;quot; or &amp;quot;Done&amp;quot; to close a dialog.&lt;/p&gt;
&lt;h3 id=&quot;what-isnt-flagged&quot;&gt;What isn&amp;#39;t flagged?&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The browser&amp;#39;s &amp;quot;Leave site?&amp;quot; prompt from &lt;code&gt;beforeunload&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A &lt;code&gt;useConfirm()&lt;/code&gt; hook, a component&amp;#39;s own &lt;code&gt;confirm()&lt;/code&gt; method, and Angular or Vue template bindings.&lt;/li&gt;
&lt;li&gt;Lines marked &lt;code&gt;// renderlint-ignore native-dialog&lt;/code&gt; on the line above, for the rare case where a native dialog is intended.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;is-it-ever-fine-to-use-confirm&quot;&gt;Is it ever fine to use confirm()?&lt;/h3&gt;
&lt;p&gt;For a quick internal script or a prototype, yes. In a product, it fails the checks above. If it is deliberate, mark it with &lt;code&gt;// renderlint-ignore native-dialog&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;does-the-dialog-element-work-in-all-browsers&quot;&gt;Does the dialog element work in all browsers?&lt;/h3&gt;
&lt;p&gt;It is built into current browsers. If you must support one that lacks it, use your component library&amp;#39;s dialog.&lt;/p&gt;
&lt;h3 id=&quot;how-do-i-replace-prompt-when-i-need-a-value&quot;&gt;How do I replace prompt() when I need a value?&lt;/h3&gt;
&lt;p&gt;Use a &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; with a labeled input and a form with &lt;code&gt;method=&amp;quot;dialog&amp;quot;&lt;/code&gt;. Read the input&amp;#39;s value when the dialog closes.&lt;/p&gt;
</content>
</entry>
<entry>
<title>Form controls that render wrong: dropdown arrows, checkboxes and input icons</title>
<link href="https://renderlint.yitec.net/blog/form-control-layout-bugs/"/>
<id>https://renderlint.yitec.net/blog/form-control-layout-bugs/</id>
<published>2026-11-16T00:00:00Z</published>
<updated>2026-11-16T00:00:00Z</updated>
<summary>Why checkboxes stretch, select arrows ignore padding, input icons cover text and fields get squashed, with the CSS fixes and how to catch them from pixels.</summary>
<content type="html">&lt;p&gt;Form controls break in a handful of repeatable ways. A global &lt;code&gt;input { width: 100% }&lt;/code&gt; stretches checkboxes across the row. A native &lt;code&gt;&amp;lt;select&amp;gt;&lt;/code&gt; draws its arrow near the border and ignores &lt;code&gt;padding-right&lt;/code&gt;. An absolutely positioned icon sits on top of the text because the input has no padding for it. A fixed &lt;code&gt;height&lt;/code&gt; plus padding squashes the text. And controls in a row end up different heights. All five are CSS interactions that look fine in code and wrong on screen.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Scope full-width input styles to text fields, not to every &lt;code&gt;input&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Style the select arrow yourself with &lt;code&gt;appearance: none&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Give an input padding on the side where an icon sits.&lt;/li&gt;
&lt;li&gt;Use either &lt;code&gt;height&lt;/code&gt; with &lt;code&gt;padding-block: 0&lt;/code&gt;, or padding with &lt;code&gt;height: auto&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Give controls in one row the same height, or let the row stretch them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-is-my-checkbox-stretched-across-the-whole-form&quot;&gt;Why is my checkbox stretched across the whole form?&lt;/h2&gt;
&lt;p&gt;Because a reset like this applies to checkboxes too:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;input { width: 100%; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A checkbox is an &lt;code&gt;input&lt;/code&gt;. With &lt;code&gt;width: 100%&lt;/code&gt; its box is stretched to the container&amp;#39;s width, and the tick is drawn in the middle of that space, far from its label. Radio buttons do the same. Often the label then wraps onto its own row.&lt;/p&gt;
&lt;p&gt;Fix it in two places: scope the rule to text-like fields, and lay the box and label out as a row.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;input:not([type=checkbox]):not([type=radio]) { width: 100%; }

.check { display: flex; align-items: center; gap: 8px; }
.check input { width: 18px; height: 18px; flex-shrink: 0; margin: 0; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Use &lt;code&gt;align-items: flex-start&lt;/code&gt; for labels that wrap onto several lines. In Tailwind: &lt;code&gt;w-4 h-4 shrink-0&lt;/code&gt; on the box.&lt;/p&gt;
&lt;h2 id=&quot;why-does-the-select-arrow-ignore-my-padding&quot;&gt;Why does the select arrow ignore my padding?&lt;/h2&gt;
&lt;p&gt;Chrome and Safari draw the native arrow of a &lt;code&gt;&amp;lt;select&amp;gt;&lt;/code&gt; close to the border, and &lt;code&gt;padding-right&lt;/code&gt; doesn&amp;#39;t move it. So a select with &lt;code&gt;padding: 0 22px&lt;/code&gt; has its text starting 27px from the left and its arrow jammed against the right edge. The mismatch looks careless even though each value in the CSS is reasonable.&lt;/p&gt;
&lt;p&gt;Draw the arrow yourself and put it inside the padding:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;select.field {
  appearance: none;
  padding-right: 44px;
  background: #fff url(&amp;quot;chevron.svg&amp;quot;) no-repeat right 18px center;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Keep the arrow&amp;#39;s right inset close to the text&amp;#39;s left inset. The example page uses a 22px left padding for text and an 18px right offset for the chevron. The same applies to custom triggers and &lt;code&gt;background-image&lt;/code&gt; chevrons: the point is that the two insets look equal, not which technique draws the arrow.&lt;/p&gt;
&lt;h2 id=&quot;why-does-my-search-icon-overlap-the-text&quot;&gt;Why does my search icon overlap the text?&lt;/h2&gt;
&lt;p&gt;The usual pattern is a wrapper with &lt;code&gt;position: relative&lt;/code&gt; and an SVG with &lt;code&gt;position: absolute; left: 14px&lt;/code&gt;. Absolute elements don&amp;#39;t take space, so the input&amp;#39;s text starts at the input&amp;#39;s normal left padding and runs under the icon. Typed text and the placeholder collide with it.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.search { position: relative; }
.search svg { position: absolute; left: 14px; top: 15px; width: 16px; height: 16px; }
.search input { padding-left: 40px; }  /* 14px + 16px icon + 10px gap */&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;For a trailing icon use &lt;code&gt;padding-right&lt;/code&gt;. Tailwind: &lt;code&gt;pl-10&lt;/code&gt; for a 16px icon at &lt;code&gt;left: 12px&lt;/code&gt;, &lt;code&gt;pr-10&lt;/code&gt; for a trailing one.&lt;/p&gt;
&lt;h2 id=&quot;why-is-my-input-too-short-for-its-text&quot;&gt;Why is my input too short for its text?&lt;/h2&gt;
&lt;p&gt;A fixed &lt;code&gt;height&lt;/code&gt; plus vertical padding leaves the text a content box that is too small. A &lt;code&gt;&amp;lt;select&amp;gt;&lt;/code&gt; keeps its padding, so a 32px select with 12px of padding top and bottom has only a few pixels left for 16px text. An &lt;code&gt;&amp;lt;input&amp;gt;&lt;/code&gt; with &lt;code&gt;height: 16px&lt;/code&gt; and 16px text has almost none. The glyphs are cut at the top and bottom or squeezed against the border.&lt;/p&gt;
&lt;p&gt;Pick one approach:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;/* A: fixed height, no vertical padding */
.field { height: 44px; padding-block: 0; }

/* B: padding decides the height */
.field { height: auto; padding-block: 10px; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As a rule of thumb, a 16px font needs about 20px of content height (this is the &lt;code&gt;squashed-control&lt;/code&gt; rule&amp;#39;s own guidance).&lt;/p&gt;
&lt;h2 id=&quot;why-are-the-input-and-the-button-next-to-it-different-heights&quot;&gt;Why are the input and the button next to it different heights?&lt;/h2&gt;
&lt;p&gt;An input has &lt;code&gt;height: 40px&lt;/code&gt;; the button next to it has &lt;code&gt;height: 48px&lt;/code&gt;. Neither looks wrong alone, but side by side their edges don&amp;#39;t line up. It also happens when a &lt;code&gt;&amp;lt;select&amp;gt;&lt;/code&gt; sits next to a text field styled by a different class. Give both the same height, or let the row stretch them:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.row { display: flex; gap: 8px; align-items: stretch; }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Or set one shared token, for example &lt;code&gt;h-10&lt;/code&gt; on both in Tailwind.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-spot-these-bugs&quot;&gt;How do you spot these bugs?&lt;/h2&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Likely cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;Checkbox in the middle of a wide row&lt;/td&gt;
&lt;td&gt;&lt;code&gt;input { width: 100% }&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;:not([type=checkbox])&lt;/code&gt; scope, &lt;code&gt;width: auto&lt;/code&gt;, flex row&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Arrow touching the right border&lt;/td&gt;
&lt;td&gt;Native select arrow ignores &lt;code&gt;padding-right&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;appearance: none&lt;/code&gt; plus your own chevron&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Text under a search icon&lt;/td&gt;
&lt;td&gt;Absolute icon, no padding&lt;/td&gt;
&lt;td&gt;&lt;code&gt;padding-left&lt;/code&gt; past the icon&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Text cut off in a field&lt;/td&gt;
&lt;td&gt;Fixed &lt;code&gt;height&lt;/code&gt; plus vertical padding&lt;/td&gt;
&lt;td&gt;&lt;code&gt;height&lt;/code&gt; with &lt;code&gt;padding-block: 0&lt;/code&gt;, or &lt;code&gt;height: auto&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Input and button edges don&amp;#39;t line up&lt;/td&gt;
&lt;td&gt;Different heights&lt;/td&gt;
&lt;td&gt;Same height or &lt;code&gt;align-items: stretch&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The reliable way is to look at pixels. Computed styles lie here: the arrow of a native select isn&amp;#39;t in the DOM, and an icon&amp;#39;s overlap depends on where the text actually starts. Open the page, look at the control, and measure.&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/docs-demo-forms-annotated-b5356d8e-1100.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/docs-demo-forms-annotated-b5356d8e-640.webp 640w, https://renderlint.yitec.net/img/docs-demo-forms-annotated-b5356d8e-960.webp 960w, https://renderlint.yitec.net/img/docs-demo-forms-annotated-b5356d8e-1100.webp 1100w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;1100&quot; height=&quot;461&quot; alt=&quot;renderlint's annotated screenshot of an alert form with a dark card: two select boxes with red boxes labeled dropdown-arrow, a search field whose icon is boxed and labeled input-icon-overlap, and a wide red box labeled checkbox-layout with a checkbox drawn in the middle of the row&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;renderlint&amp;#39;s annotation on a form with all three defects: stretched checkbox, jammed select arrows and an icon over the placeholder.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;h2 id=&quot;how-renderlint-catches-it&quot;&gt;How renderlint catches it&lt;/h2&gt;
&lt;p&gt;Five rules cover these bugs. The first four are errors and the last is a warning (&lt;a href=&quot;https://renderlint.yitec.net/rules/#dropdown-arrow&quot;&gt;rule reference&lt;/a&gt;):&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Rule&lt;/th&gt;
&lt;th&gt;Default&lt;/th&gt;
&lt;th&gt;What it reports&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;&lt;tr&gt;
&lt;td&gt;&lt;code&gt;dropdown-arrow&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;error&lt;/td&gt;
&lt;td&gt;The arrow is much closer to the border than the text is to the other side. Measured from pixels, so it covers native arrows, background-image chevrons and custom triggers.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;checkbox-layout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;error&lt;/td&gt;
&lt;td&gt;A checkbox or radio stretched to full width, or on its own row above its label.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;input-icon-overlap&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;error&lt;/td&gt;
&lt;td&gt;An icon drawn over the area where the field shows text and placeholder.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;squashed-control&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;error&lt;/td&gt;
&lt;td&gt;Height minus vertical padding leaves less room than the font needs.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;control-height-mismatch&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;warn&lt;/td&gt;
&lt;td&gt;Controls side by side with different heights.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;This is the real output for the example form (a 46px field with 22px padding, an unscoped &lt;code&gt;input { width: 100% }&lt;/code&gt;, and a search icon at &lt;code&gt;left: 14px&lt;/code&gt;), checked at 375, 768 and 1280px:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ checkbox-layout (1)  A checkbox or radio button is stretched to the full width (drawn in the middle, away from its label), or sits on its own row above its label.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; A checkbox is stretched to 289px wide, so the box is drawn in the middle of that space, away from its label (usually a global `input { width: 100% }`).
&lt;span class=&quot;d&quot;&gt;        at #e&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /forms-before.html · all viewports · see .renderlint/screens/forms-before-html-vwbhz@375.png #1&lt;/span&gt;

&lt;span class=&quot;e&quot;&gt;✖ dropdown-arrow (1)  A dropdown's arrow sits much closer to the border than its text does to the other side, so it looks jammed against the edge. Measured from pixels, so it covers native arrows, background-image chevrons and custom triggers.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; The dropdown arrow sits 3px from the right border while the text starts 27px from the left, so the arrow looks jammed against the edge. The browser draws the native arrow near the border regardless of padding-right.
&lt;span class=&quot;d&quot;&gt;        at #f  &amp;quot;Every hour Daily digest&amp;quot;&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /forms-before.html · all viewports · see .renderlint/screens/forms-before-html-vwbhz@375.png #3&lt;/span&gt;

&lt;span class=&quot;e&quot;&gt;✖ input-icon-overlap (1)  An icon (search, mail, calendar) is drawn over the part of an input where its text and placeholder appear, so typed text runs underneath it.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; An icon is drawn over the area where the field shows its text and placeholder (16px of overlap on the left). Typed text will run underneath it.
&lt;span class=&quot;d&quot;&gt;        at #q&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;      with main &amp;gt; form.card &amp;gt; div &amp;gt; svg&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;        page /forms-before.html · all viewports · see .renderlint/screens/forms-before-html-vwbhz@375.png #2&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-forms-before-811deef5-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-forms-before-811deef5-640.webp 640w, https://renderlint.yitec.net/img/captures-forms-before-811deef5-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;372&quot; alt=&quot;renderlint's screenshot of the Alert settings form at 768px: a search field with its icon boxed and labeled input-icon-overlap, a Frequency select labeled dropdown-arrow with its arrow at the far right, and a checkbox row labeled checkbox-layout with the tick in the middle&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;The 768px capture. The numbers in the messages come from the pixels: 3px from the border, 27px of text inset, 289px for a checkbox.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;The fixed page printed &lt;code&gt;✔ No UI defects found.&lt;/code&gt;&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;https://renderlint.yitec.net/img/captures-forms-after-a7834ffc-768.webp&quot; srcset=&quot;https://renderlint.yitec.net/img/captures-forms-after-a7834ffc-640.webp 640w, https://renderlint.yitec.net/img/captures-forms-after-a7834ffc-768.webp 768w&quot; sizes=&quot;(max-width: 820px) 100vw, 720px&quot; width=&quot;768&quot; height=&quot;351&quot; alt=&quot;The fixed Alert settings form at 768px: the search icon sits left of the placeholder, the select shows its chevron inset from the right edge, and the checkbox sits beside its label&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot;&gt;&lt;figcaption&gt;After the fix, at 768px: icon padding, a custom chevron and a flex row for the checkbox.&lt;/figcaption&gt;&lt;/figure&gt;


&lt;p&gt;&lt;code&gt;squashed-control&lt;/code&gt; and &lt;code&gt;control-height-mismatch&lt;/code&gt; have their own fixtures. On &lt;code&gt;test/fixtures/defects/squashed-control.html&lt;/code&gt; (a 32px select with 12px padding and a 16px-tall input, both with 16px text) renderlint reports:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;e&quot;&gt;✖ squashed-control (2)  An input or select is too short for its text: height minus vertical padding leaves less room than the font needs, so the text is cut off at the top and bottom.&lt;/span&gt;
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; The field is too short for its text: 6px of room inside the padding for 16px text, so the text is cut off at the top and bottom.
&lt;span class=&quot;d&quot;&gt;        at #r  &amp;quot;Engineering manager&amp;quot;&lt;/span&gt;
        …
  &lt;span class=&quot;e&quot;&gt;error&lt;/span&gt; The field is too short for its text: 14px of room inside the border for 16px text, so the text is squeezed against the border.
&lt;span class=&quot;d&quot;&gt;        at #t&lt;/span&gt;
        …&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;On &lt;code&gt;test/fixtures/defects/form-warnings.html&lt;/code&gt;, a 40px input beside a 48px button, renderlint reports this among other findings:&lt;/p&gt;
&lt;pre class=&quot;term&quot;&gt;&lt;code&gt;&lt;span class=&quot;w&quot;&gt;⚠ control-height-mismatch (1)  Controls placed side by side (an input and its button, a select next to a text field) have different heights, so their edges don't line up.&lt;/span&gt;
  &lt;span class=&quot;w&quot;&gt;warn&lt;/span&gt;  Controls side by side have different heights (40px and 48px), so their edges don't line up.
&lt;span class=&quot;d&quot;&gt;        at form.row &amp;gt; input&lt;/span&gt;
&lt;span class=&quot;d&quot;&gt;      with form.row &amp;gt; button  &amp;quot;Subscribe&amp;quot;&lt;/span&gt;
        …&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Findings are tuned to avoid false positives. If one is intentional, mark the element with &lt;code&gt;data-renderlint-ignore=&amp;quot;&amp;lt;rule&amp;gt;&amp;quot;&lt;/code&gt; and a &lt;code&gt;data-renderlint-reason&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;frequently-asked-questions&quot;&gt;Frequently asked questions&lt;/h2&gt;
&lt;h3 id=&quot;do-these-bugs-only-show-at-some-screen-widths&quot;&gt;Do these bugs only show at some screen widths?&lt;/h3&gt;
&lt;p&gt;Some do. renderlint checks each page at three viewports (375, 768 and 1280px by default) and, with the sweep, at more widths. A stretched checkbox is visible at all three in the example, but a row of controls that wraps can only break at one width.&lt;/p&gt;
&lt;h3 id=&quot;can-i-keep-the-native-select-arrow&quot;&gt;Can I keep the native select arrow?&lt;/h3&gt;
&lt;p&gt;You can, but Chrome and Safari draw it near the border regardless of &lt;code&gt;padding-right&lt;/code&gt;. The fix is &lt;code&gt;appearance: none&lt;/code&gt; with your own chevron, or an icon positioned inside the padding.&lt;/p&gt;
&lt;h3 id=&quot;why-not-use-a-visual-regression-tool-for-this&quot;&gt;Why not use a visual regression tool for this?&lt;/h3&gt;
&lt;p&gt;A baseline tool will show these bugs as diffs only if a design was approved without them. The first screenshot of a broken form becomes the baseline.&lt;/p&gt;
</content>
</entry>
</feed>
