Skip to main content
skill CX Codex

renderlint-fix — Claude Code skill: what it does, how to install

renderlint-fix is a Claude Code skill that fixes UI defects reported by renderlint. It runs after npx renderlint or a failing renderlint Stop hook.

MIT ★ 687 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ngocanhnckh/renderlint --skill renderlint-fix -a claude-code
Open on GitHub

What renderlint-fix does

The skill fixes UI defects reported by renderlint, including overflowing or clipped text, contrast failures, overlapping elements, broken mobile layouts, inaccessible content, and hidden popups. It also handles native browser dialogs, loading and error states, action feedback, keyboard focus, tooltip behavior, ARIA references, and duplicate submissions. npx renderlint exits with code 1 while errors remain.

It starts from a npx renderlint report or a renderlint Stop hook message. The skill reads the rule, selector, component, file, page, and viewport width, then opens a screenshot from .renderlint/screens/ when the finding is unclear. Rule details are available through npx renderlint explain <rule>, while .renderlint/report.json exposes the same data to scripts. After each fix, it runs the check again until the result is 0 errors.

What it helps with

  • fix text overflow and clipped content in a UI
  • remove overlapping elements from responsive layouts
  • replace alert(), confirm(), and prompt() with app UI
  • restore scrolling and keyboard focus around fixed panels
  • add loading, error, and duplicate-submit feedback

Example prompts for the agent

  • Fix every issue from the latest npx renderlint report and rerun the check until it reaches 0 errors.
  • Inspect the text-overflow finding, open its screenshot in .renderlint/screens/, and fix the root cause in the component.
  • Handle the errors reported by the renderlint Stop hook, then run npx renderlint again.

How to install renderlint-fix

1Skills CLI (Vercel)

npx skills add ngocanhnckh/renderlint --skill renderlint-fix -a claude-code

2Manually: put the files in place

~/.claude/skills/renderlint-fix/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/renderlint-fix/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about renderlint-fix

How do I install renderlint-fix in Claude Code?

Run npx skills add ngocanhnckh/renderlint --skill renderlint-fix -a claude-code. The skill file is placed at ~/.claude/skills/renderlint-fix/SKILL.md.

What does renderlint-fix do?

It fixes UI defects found by renderlint and reruns the check after each change. Its rules cover overflow, contrast, overlap, mobile layout, focus, loading, and action feedback.

What does renderlint-fix need to run?

It needs a report from npx renderlint or a renderlint Stop hook that reports errors. The workflow can use screenshots in .renderlint/screens/ and the .renderlint/report.json file.

Source text

SKILL.md · MIT
---
name: renderlint-fix
description: 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.
---

# 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).

© ngocanhnckh · MIT · ngocanhnckh/renderlint

Similar skills

All skills for Frontend and UI →

From the same set3

Project sponsors

Companies that keep this analytics open