Fix what renderlint reports
npx renderlint exits 1 while errors remain. Fix every error, re-run, and repeat until it reports 0 errors. Treat it like a failing build.
Read the report
Each finding has:
- the rule;
- the element (a CSS selector, plus the component and file when renderlint can map it);
- the page, the role (
[role: viewer]) and the widths (@375px;@1024pxcomes from the width sweep); - a numbered marker on a screenshot in
.renderlint/screens/. Open the screenshot when a finding isn't obvious.
npx renderlint explain <rule> explains any rule. .renderlint/report.json has the same data for scripts.
Fix root causes, not symptoms
| Rule | Usual cause | Fix |
|---|---|---|
text-overflow, text-clipped, text-crowding |
Fixed width or height on a text box, white-space: nowrap, a flex child without min-width: 0 |
Let text wrap. Remove fixed sizes, use min-width: 0 on flex/grid children, add overflow-wrap: anywhere where emails, URLs or ids appear. |
unreachable-content |
A box that clips (overflow: hidden, often a 100vh app shell, its main area or a tab panel) holds content taller than itself, and nothing between them scrolls. Or overflow: hidden on body/html left on. The finding names the box |
Make the area that grows the scroller: overflow-y: auto on it, plus flex: 1 1 0%; min-height: 0 (or min-height: 0 on the grid row) so it shrinks to its parent instead of growing past it. Don't just remove the shell's overflow: hidden: the page would then scroll as a whole, under a fixed header and sidebar. For a scroll lock, remove it when the dialog or menu that set it closes. |
focus-obscured |
A sticky header or fixed bottom bar (cookie banner, mobile nav) covers the control the browser scrolled into view on Tab | html { scroll-padding-top: <header height>; scroll-padding-bottom: <bar height> }. Don't just raise the control's z-index. |
tooltip-keyboard |
A tooltip shown on :hover only, or one that ignores Escape |
Show it on :focus-visible too (or the library's focus trigger), tie it with aria-describedby, and close it on Escape without moving focus. |
aria-reference, label-in-name |
An id that was renamed or duplicated; an aria-label written separately from the visible text |
Point at the real id (useId() in React). Remove the aria-label, or start it with the visible text. |
cramped-control |
Tiny gap, padding: 2px, inline buttons with no space between them |
Use a spacing-scale value (8px). To join buttons on purpose, make the gap 0 and square the corners where they meet. |
viewport-overflow |
Something wider than the phone screen: fixed px widths, a table, a long unbroken word | Make it fluid (max-width: 100%, minmax(0, 1fr)), wrap rows (flex-wrap), put wide tables in a scroll container. |
contrast |
Light text on a light accent, gray-on-gray, text over an image | Darken the text or lighten the background until it passes. The finding suggests a passing color. |
text-overlap, element-overlap |
Absolute positioning, negative margins, overlapping grid areas | Lay elements out in flow; reserve space for labels. |
text-near-overlap |
Two absolutely positioned layers in one panel (header pinned top-left, centred empty state with inset: 0) |
Stack them in flow (header, then content area), or start the overlay below the header (inset: 64px 0 0). |
fragile-layout |
Passes with the sample data, breaks with longer text, long words, bigger numbers or longer API data | Same fixes as overflow: the design must survive real content. |
popup-obscured |
An open menu cut off by its card or a table's scroll box (overflow: hidden / auto), or drawn underneath the next element because an ancestor's z-index, transform or opacity traps its stacking order. The finding names that container or ancestor, and has a screenshot of the open menu |
Render the menu outside it: the library's portal (Radix/shadcn Portal, Headless UI anchor, MUI and Angular CDK overlays do this by default) or the popover attribute. Or remove the ancestor's overflow: hidden. Raising the menu's own z-index does nothing while an ancestor starts a stacking context: raise that ancestor while the menu is open, or portal the menu. |
native-dialog |
alert(), confirm() or prompt(): the browser's grey system box. The finding gives the file and line (or "called at" for one that opened in the page) |
Replace it with the app's own UI, reusing the toast or dialog component the project already has: a toast for notices, an inline message for form errors, a confirmation modal for confirm() (continue only when the user confirms there), a modal with an input for prompt(). Don't wrap the native call or rename it to dodge the rule. |
loading-state |
An area that stays blank while its data loads (renderlint held the requests for a second, as on a slow network). The finding names the request, the container and a sample of the content, and its screenshot shows both moments side by side | Render a loading state in that container until the data arrives, using what the project already has: a skeleton shaped like the content (best: no jump when it arrives), or a spinner. isPending/isLoading (TanStack Query, SWR), a Suspense fallback, useNavigation() for React Router loaders, loading.tsx in Next.js. Handle the error case at the same time. |
action-feedback |
(--ux) A click started a request and nothing on screen changed for a second |
Show the pending state at once: on the control (disabled + spinner or "Saving…") or where the result appears (skeleton, dimmed old content with aria-busy, a top progress bar for page changes). |
error-feedback |
(--ux) renderlint answered the request with HTTP 500 and nothing said so, or the spinner never stopped |
Catch the failure and show it where the user looks: an error message with "Try again" in place of the content, a toast or inline error for an action. Stop the loading state and re-enable the control. |
double-submit |
(--ux) A second click while the request was pending sent it again |
Disable the control (or ignore clicks) while the request is in flight, and show "Saving…". |
ui-freeze |
(--ux) A long task blocked the main thread for 500ms or more, on load or after a click |
Move the heavy work off the main thread (Web Worker), split it into chunks that yield, virtualize long lists, startTransition for slow React updates. Don't just add a spinner: a frozen page can't animate one. |
dead-control |
(--ux) A button that does nothing visible: no request, no change, no navigation |
Wire up or fix the handler. If its effect is invisible (copy to clipboard), confirm it ("Copied!"). Remove or disable placeholder buttons. |
layout-shift, slow-render |
Content jumps when the data arrives (CLS over 0.1); the main content shows up after 4s (--ux) |
Reserve space before the data comes (skeleton the size of the content, min-height, image width/height). For slow renders, remove request waterfalls (start requests together, or fetch on the server) and split large bundles. |
empty-state |
(--ux) With every list of records in the API responses emptied (a new account), the area is just blank, keeps its spinner, or the page breaks |
Render an empty state in that container: a short message ("No orders yet") and the action that adds one ("Create order"). Treat an empty list as a finished load. Guard code that assumes one record (items[0], reduce() with no initial value). Hiding a whole section, title and all, is also fine. |
dialog-focus |
(--ux) A dialog a click opened leaves focus behind it, ignores Escape, or drops focus to the top of the page when it closes |
Use the project's dialog component if it manages focus (Radix / shadcn Dialog, Headless UI, MUI, <dialog> with showModal()). By hand: focus the first field on open, close on Escape, and .focus() the opening control on close. |
back-navigation |
(--ux) After an in-app link, Back skips the page or changes the address without changing the page |
Use the router's links and push navigation; keep replace for redirects. If you call history.pushState yourself, render the matching view on popstate. |
page-not-shown |
Signed in, the app didn't show the page: a guard redirected, HTTP 401/403, or "Access denied" / "Not found" | Either the role isn't meant to see it (add the path to that role's deny), or it is (give the role what the guard checks). See the renderlint-setup skill. |
auth-required |
The page sent renderlint to the login page, so it was never checked | Set up auth (renderlint-setup skill). Don't ask the user for credentials and don't turn the rule off. |
coverage below coverage.min |
Routes that were found but not checked | Read the reasons in .renderlint/coverage.json and fix them as the renderlint-setup skill describes. |
Don'ts:
- Don't hide symptoms: no
overflow: hiddenonbodyto mask sideways scrolling. - Don't shrink text below 12px, and don't delete content to dodge a rule.
- Don't add
!importantpiles.
When the same component is flagged on many pages, fix the component once.
Intentional? Say so, rarely
If a finding is really intended (a decorative marquee, a deliberately cropped hero image), mark the element:
<div data-renderlint-ignore="text-clipped" data-renderlint-reason="ticker scrolls on purpose">…</div>
or in CSS, --renderlint-ignore: text-clipped;. A finding at a source line (at src/…:12) is marked with a comment on the line above: // renderlint-ignore native-dialog -- kiosk app, no custom UI. Always give the reason. These are reviewed like eslint-disable. Never use "rules": { "x": "off" } or ignore to make a run pass. page-not-shown, auth-required and coverage gaps are never "intentional": they mean pages went unchecked.
Declare worst cases you know about
When a field has a known limit, tell renderlint so it tests exactly that, and failures become errors:
<h3 data-renderlint-maxlength="60">{project.name}</h3>
<span data-renderlint-sample="Aleksandra Wiśniewska-Kowalczyk">{user.name}</span>
Details: docs/rules.md.