# Renderlint Fix

> Fix the UI defects renderlint reports (text overflow, contrast, overlap, broken mobile layouts, fragile-layout, native alert/confirm dialogs, page-not-shown, auth-required, coverage gaps). Use after `npx renderlint` or the renderlint Stop hook reports errors, or before saying a UI task is done.

- Skill: `ngocanhnckh/renderlint-fix` (Agent Skill)
- Install (CLI): `npx get-skill add ngocanhnckh/renderlint-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ngocanhnckh/renderlint-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ngocanhnckh (https://skillmd.com/u/ngocanhnckh)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/ngocanhnckh/renderlint-fix

---


# 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`; `@1024px` comes 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: hidden` on `body` to mask sideways scrolling.
- Don't shrink text below 12px, and don't delete content to dodge a rule.
- Don't add `!important` piles.

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:

```html
<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:

```html
<h3 data-renderlint-maxlength="60">{project.name}</h3>
<span data-renderlint-sample="Aleksandra Wiśniewska-Kowalczyk">{user.name}</span>
```

Details: [docs/rules.md](https://github.com/ngocanhnckh/renderlint/blob/master/docs/rules.md).

