Skip to content

Latest commit

 

History

History
42 lines (28 loc) · 26 KB

rules.md

File metadata and controls

42 lines (28 loc) · 26 KB

Rules

Eight rules, the same in check_ui, onsystem check and the Claude Code hook. Every finding has a rule id, a location and a message that says what to write instead; most carry a fix as text edits. When a fix renames a tag to a component the file does not import yet (<button> to <Button>), the message names the import to add, and the ESLint plugin offers that rename as a suggestion rather than a fix, so eslint --fix never writes a component the file does not import or declare. The rules catalog on the website shows each one on a real example.

Rule Default Catches Suggests
no-hardcoded-color error Hex/rgb/hsl/oklch literals in classes (bg-[#ef4444], [color:red]), styles and color attributes (<svg fill>; on components, only hex and color functions in props without known values); Tailwind default-palette classes (bg-gray-100, also as their variable: bg-[var(--color-gray-100)]) and its opaque white and black (bg-white, text-black); as a warning, a chart-* token outside a chart (text-chart-2 on a status label) The nearest token of the same hue whose role fits the utility (text-gray-500 → text-muted-foreground), or the variant that already applies it
no-hardcoded-spacing warn Arbitrary padding, margin and gap (p-[13px], style={{ marginTop: 6 }}) Nearest step on the spacing scale, keeping the sign; with Tailwind v4, any whole or half step of --spacing (p-3, p-4.5, p-13) or p-px; values of 1px or less are left alone unless positive and on the scale (py-[1px] → py-px)
no-hardcoded-radius warn Arbitrary radius (rounded-[7px], borderRadius: 14) Nearest radius token (rounded-sm), including Tailwind's default keys; rounded-full (or a pill token) for values far above the scale (rounded-[999px])
prefer-design-system-component error Native elements a component is named for (Button for <button>, Link, Input/TextField, Label, Select, Textarea, Image, Separator, Dialog, Table), or that a component renders and replaces without needing anything the element does not (no required props of its own, the element's attributes). It leaves alone what is not UI to restyle: an element that is hidden, aria-hidden, or invisible and out of the tab order; the asChild child of a component with classes of its own; a bare <button />, <a /> or <label /> passed to render into; an element styled by a cva/tv definition in its own file; and an <input> whose every attribute is spread in The root component and its import, preferring one that renders the element (NativeSelect over Select); the rename is auto-fixed when it renders that element, takes its attributes or is mapped in elements
no-unknown-component error Invented components, dot-notation members that do not exist (<Card.Header>), typos. A name from a module the model left out (an excluded folder, a barrel that re-exports one) is not called invented: check says once which components it could not check The flat part (<CardHeader>), auto-fixed, or the closest name, auto-fixed only when that component is imported. A part a family does not have (DialogContent where Dialog is the content, as in shadcn/ui on React Aria) gets the family's component and its parts, without a fix, rather than the part spelled closest; a misspelled part (DialogTitel, AvatarImg) is still that part
no-unknown-prop error Props a component does not accept, own or inherited (tone, isDisabled) Closest prop, with cross-library synonyms (tone → variant) and equivalents in either direction (checked ↔ isSelected, open ↔ isOpen); asChild on a Base UI component (or render on a Radix one) gets how that library composes. React Aria has neither: on a trigger that takes neither and renders no element of its own, asChild, as, component or render gets that it takes the element that opens it as a child (a button, or a menu item for a submenu); on a component whose render is React Aria's function, asChild, as, component and href get that a link is a link component, or to pass href when the component takes it
no-unknown-variant error Values outside a cva variant or literal union (variant="danger") Allowed values and a synonym match (danger → destructive, small → sm)
icon-button-accessible-name error Buttons whose only content is an icon (from an icon library or icons module, or named like one: XIcon, Trash2), with no aria-label, aria-labelledby, title, visually hidden text or <label htmlFor> for its id. A child with text in its props (<IconMenu text=…>) or an unknown component makes it skip; a button passed as Base UI's render, conditionally too, is judged by its own and its host's children, a render-prop child ({() => <Trash2 />}) by what it returns, and hidden buttons and a story's args.render are skipped; an icon-only link a button renders through asChild (<Button asChild><Link href=…><Pencil /></Link></Button>) is judged as that button aria-label, guessed from the icon (Trash2 → "Delete"), and fixed only when the icon or the code says what the button does

Known limits

Class strings are checked where they are written: in className or class, and in the arguments of cn, clsx, cva and the like, wherever those are called. From there they are followed to where the same file keeps them: a const (className={tone}, cn("p-4", extra)), a key of a const object map (className={statusStyles[status]} with const statusStyles = { New: "bg-green-50 text-green-700" }), or what a function of the file returns (className={toneOf(status)}), through conditions, templates and +. A value from another file, a parameter or prop, or a let is not followed, so a palette color there is not reported, and neither are class names built at runtime (bg-${color}-500 in a template) or classes in other props, such as tw for @vercel/og. Keep such classes in the file that uses them, or make them a cva variant. @shadcn/lint's require-static-classes reports a className it cannot check. The other limits are listed in How it works.

How fixes are chosen

Color matches under ΔE 0.02 count as the same color. Under 0.1 the fix is offered, except for a Tailwind palette class: it is fixed only to a token that matches it or that is nearest to the class's own shade (of the shades in its family) and within ΔE 0.037 of it, the most Tailwind v3 and v4 differ on one shade. Another close token is suggested without a fix, and the message says why (one shade darker, or closest to another color of the same shade). Beyond 0.1 the message names the nearest token but leaves the choice to the agent. Opacity is part of the color: a token more than 0.02 apart in opacity is never a fix, so bg-[#e7000b33] (the red at 20%) is not fixed to an opaque bg-destructive, nor dark:border-[#fff] to a dark border that is 10% white. The message gives both opacities, and an opacity modifier stays on the token (bg-[#fff]/40 → bg-background/40). A fix is only offered for a token of the same hue (within 15°), or a gray for a gray, whether the color is a palette class, an arbitrary value or a literal: a pale color counts as a hue by its chroma relative to its lightness, so bg-[#fef2f2] is never swapped for a light gray that happens to be close. Status colors (destructive, warning, success, info and their foregrounds) are only offered for nearly the same hue (within 8°), never for a gray, so a brand-orange button does not become bg-destructive. The other way round, a fix to another token is held back when a status color of the color's hue (within 15°) is close too and at most ΔE 0.03 further: next to a rose brand, bg-[#ef4444] may be an error, so the message offers bg-destructive if the color shows a status and bg-brand otherwise, and error text does not follow the next rebrand. When a color is a hue and no token has it, the finding is a warning that names no token: add a token for the hue, or keep the color with a suppression comment and a reason ({/* */} between JSX children). A chart token outside a chart, such as text-chart-2 on a green "Active" label in a theme with no success color, is a warning with no fix: it is a token, but it changes with the chart palette and does not say what a status color says, so add a status token (status colors) or use the token that fits. A file that draws a chart (it imports a chart library, renders <ChartContainer> or <BarChart>, declares chartData, or is named for charts) is left alone, legend dots and all, as is an element in an <svg>, a <figure> or a role="img", and every chart token when the design system's own components use them outside a chart. Tailwind's white and black (bg-white, border-black) are fixed only to a token of exactly that color, such as bg-background for bg-white in a stock shadcn/ui theme. A hardcoded background (white or black, a palette class or an arbitrary color) is not fixed to a token while hardcoded text on it stays as it is and would no longer stand out from the token in some mode. The text is white or black, a tint of them (text-black/80), or a color whose own finding has no fix (text-neutral-900 held back as another shade, text-[#000], an allowed class), on the element or an element inside it, in the background's state (hover:bg-black), or on an element around it whose text color the element inherits (no element in between sets one or is a component, which can set its own, and the element has content). So bg-black text-white and bg-zinc-900 text-white are not fixed to bg-primary, which is near white in shadcn/ui's dark mode, and bg-white text-neutral-600 is not fixed to a background token that is black in dark mode. The text stands out from a color 0.25 apart in lightness (OKLCH L) or with 3:1 contrast (WCAG's minimum for large text), and the fix is held when the token takes away either one that the hardcoded background gave it: text-neutral-600 is 0.44 lighter than black, but has 2.7:1 on it. The message names the token to change the text to with it (text-primary-foreground), except for a hue (text-green-800), which a gray foreground would not keep. The fix stays when the text's own finding fixes it too, when the class list sets the dark-mode background or text itself (dark:bg-zinc-900, dark:text-white), or when the token keeps the text standing out in each mode; a token with no dark value onsystem reads may still have one, so it counts as changing. A theme that defines --color-white or --color-black makes them its own tokens, which are not reported. White or black text, fill or stroke is a warning without a fix, since its token depends on the surface under it, and is not reported on a surface it stands out from in each mode it shows in (dark mode too, unless its class list sets its dark color): a color at least 0.25 apart in lightness (OKLCH L), a gradient, an image, a background in style (a swatch known only at run time counts) or a tint it stands out from (bg-black/60 under white text), set in its class list (in the same state: hover:bg-red-600 hover:text-white), by its component's variants or by the nearest element around it that sets a background. A tint it does not stand out from (bg-white/10 under white text) shows what is under it: the element around it, or else the theme's background. So shadcn/ui's bg-destructive text-white passes, and text-white on bg-muted, on bg-white, or on bg-primary where primary is near white in dark mode, is reported. With an opacity modifier (bg-black/50, border-white/10) white and black tint what is under them and are left alone, as they are inside an SVG <mask>. Among the tokens that qualify, the one made for the utility wins: foreground and muted-foreground for text-*, fill-* and stroke-*; surfaces such as muted for bg-*; border, input and ring for border-* and ring-*. Tokens named on-* are text colors, and so are content-* tokens unless the rest of the name says border or background (content-border, content-background). A close token made for another role is named in the message but never swapped in. sidebar-* and chart-* tokens are only suggested in a sidebar or a chart (by file, enclosing component or classes), and so is any other family that at most one design-system file uses, such as syntax-highlighting colors or one screen's background, outside that file's components; dark: classes are compared with dark-mode values. A class under a condition (hover:, focus-visible:, md:) is not fixed to the token the same class list has or gets without it, nor the other way round, unless the two already have exactly the same color: bg-[#2563eb] hover:bg-[#1d4ed8] would become bg-primary hover:bg-primary, and the hover would change nothing. The message suggests keeping them apart (hover:bg-primary/90). dark: is not such a condition: a dark: class is compared with dark-mode values, so the same token there is a fix. Nor is a variant for a pseudo-element or other elements (placeholder:, *:, prose-a:, [&_svg]:), whose color the class without it does not set. Two hardcoded classes of exactly the same color (a palette class and its hex count as one) keep their fixes too, since the condition changed nothing before either: border-red-500 focus:border-red-500 keeps an error border red on focus. A slight change is still a change: bg-[#fff] hover:bg-[#fafafa] keeps its hover, though both are within 0.02 of background. A state class is compared with the class it starts from: a dark:hover: class with the list's dark: class, when there is one.

Likewise, a spacing or radius step that is off by more than half the value (and more than 4px) is suggested but not auto-fixed. Spacing of 1px or less is not reported unless the scale has that exact step and the value is not negative (py-[1px] → py-px): the nearest step (4px, say) would change the layout, and a negative hairline (mt-[-1px], -mt-[1px], marginTop: -1) is a deliberate border overlap. A length in em (px-[0.5em], padding: "0.5em") grows with the font, which no step of the scale does, so its nearest step is suggested and never fixed. Rules that need tokens are skipped when the design system defines none of that category; a stylesheet that imports tailwindcss brings Tailwind's default spacing unit and radius scale, and so does a Tailwind v4 theme partial (@theme, where no token stylesheet imports tailwindcss, such as a design-system package ships) in a project on Tailwind v4 (@tailwindcss/postcss, @tailwindcss/vite or @tailwindcss/cli in its package.json, or tailwindcss in a range other than v3's), unless the theme resets that namespace (--spacing-*: initial, --radius-*: initial), in which case only the project's own steps are suggested. Syntax errors are reported as syntax, and so is code nested too deeply for TypeScript's parser (thousands of levels), which is then not checked.

An icon button's label is fixed only when the icon means one thing on a button (a trash can, pencil, magnifier, gear, copy, download, upload, share or filter icon, named plainly: Trash2 or TrashIcon, not Binary or FilterX) or the code says what the button does: "More options" on a menu's trigger, and for an X, "Close" in a close part (DialogClose) whatever its onClick calls, or elsewhere "Remove", "Clear" or "Close" when every function its onClick calls says that one action (removeAssertion(index), clearSearch(), setOpen(false); clearTimeout does not count). Otherwise the message names a label without a fix, since a plus may add or expand, a chevron go to the next page or expand a row, and an X close, remove or clear: an X that resets a form and closes (form.reset(); setOpen(false)) is named "Close", and one that calls closeDeleteDialog or onCancelDelete, or acts only in a callback such as onSuccess, is named without a fix. A chevron or arrow in a collapsible's or accordion's trigger, or on a button with aria-expanded, data-state or data-[state=open]: classes, is named "Toggle", not "Next" or "Previous".

Suppressing findings

A comment turns rules off where a finding is intended, and says why after --:

// onsystem-disable-next-line no-hardcoded-color -- the brand's exact orange
<Button className="bg-[#ff6b00]">Sign in</Button>

<p className="text-[#737373]" /> // onsystem-disable-line no-hardcoded-color

{/* onsystem-disable-next-line no-hardcoded-color, no-hardcoded-spacing */}
<div className="bg-[#0a0a0a] p-[13px]" />

onsystem-disable-next-line covers the next line, onsystem-disable-line its own, and /* onsystem-disable */ the rest of the file (at the top, the whole file). Without rule names they turn every rule off. A misspelled rule name is reported as a suppression warning, with the closest one, and suppresses nothing; syntax errors cannot be suppressed. For whole folders or kinds of files, such as legacy screens or generated code, use overrides in the config.