Rules — quebi ui-lib

why these exist

04 failure modes

These rules are written for the code an agent writes. Not because agents are careless — because they optimise for the shortest path to something that looks right, and four specific detours are the predictable result.

It rebuilds what already exists

Asked for a card, a button, a badge, an agent writes one. Producing four Tailwind classes is faster and more certain than discovering that the library ships the component — and the result renders correctly, so nothing in review objects. The same reflex reaches past the library for the values inside those components: toLocaleString() is one call, and it looks right on the machine that wrote it. Repeated across a codebase, that is how a design system stops being a system: not through one bad decision, but through fifty reasonable ones in fifty files. And once it has found the component, it uses it for every box — a card per section inside a card — which is the library's own surface, pressed into service as a layout.

It hand-rolls forms it was told to bind

Forms are where an agent's training data pulls hardest against the project's conventions. It writes useState, value, onChange and a literal name because that is the shape it has seen most often, rather than reading the binding off Conform's field metadata or posting to a React Router action. The form submits, so it looks finished — while the error wiring, the default values, and the server-side validation are simply absent.

It takes the shortcut the runtime offers

A global needs no import, no provider and no discovery. alert() is there; Array.prototype.sort is there; both produce something that works on the first click, in the one tab the agent can see. Neither is wrong as JavaScript, which is what makes them hard to catch in review. But alert() draws a dialog the design system does not own, cannot theme and cannot render in a test, and sorting the rows already in memory reorders the answer the server just gave rather than asking it a different question — so the table and the query behind it quietly stop agreeing. The shape that would have been right in both cases — a toast under a provider, an awaited confirmation under another, a re-query through the callback the component already exposes — costs an import and a round trip. The shortcut costs neither, and that is the whole of its appeal.

It appends until the file is unreadable

Adding to the file already open is the cheapest edit available, and an agent never has to scroll the result. Nothing pushes back at 400 lines, or 900, or 2,000 — and past that point no human reviews the file properly and every later agent edit starts from a worse position, because reading it costs more and landing an edit in the right place is less certain.

File length

Why a linter, and not just instructions

Instructions are read once, at best: A CLAUDE.md or a skill competes for attention with the actual task, and loses — it is skipped when context is tight, skimmed when it is long, and interpreted generously when it is vague. None of that is visible to you: the agent does not report which of your conventions it decided not to apply.
A rule is checked every time, on every file: A lint run does not get tired, does not run out of context, and does not weigh your convention against the feature it is trying to ship. It applies the same way on the first file and the four-hundredth.
The error arrives where the mistake is: This is the part that changes agent behaviour. A rule does not say "follow the design system" — it says, on the line in question, "use <Button> from @/components/button". That is a correction an agent can act on immediately and verify, which is why every message here names the replacement rather than the offence.
It survives the people who wrote it: Instructions decay as the codebase changes and nobody notices. These rules are generated from records the build validates, so a rule pointing at a component that no longer exists fails CI instead of quietly misleading whoever reads it next.

element usage

07 rules

Layout is yours. Appearance is the library's.

When a raw HTML element is allowed in an app that uses quebi ui-lib, and which component to import when it is not. Seven tiers, outward from the element: interactive and semantic elements are always the library's; layout elements are yours as long as they only lay things out; design values are always tokens; the primitives underneath belong to the library layer; a file past 500 lines is doing more than one job; the numbers and dates rendered inside all of it are formatted through the library, with a locale that is written down; and the library's own surfaces are not stacked inside each other — a card inside a card is a section.

forms

06 rules

Validation is yours. Wiring is the library's.

How a form is bound, where its errors come from, what has to be true on the server, and the three details that make the difference between a form that submits and a form that works. The schema is your app's — it encodes rules nobody else can know. Everything between that schema and the DOM (name, id, defaultValue, aria-describedby, the error text itself) belongs to the components, and hand-wiring it is how a form quietly loses its accessibility while still looking correct.

platform defaults

02 rules

The platform will do it for you. That is not the same as your app doing it.

Two rules about the shortcut the runtime hands you for free. alert() and confirm() draw a dialog with no import, no provider and no state — and no theme, no focus management and nothing to render in a test, because that dialog belongs to the browser rather than to the app. Sorting the array you are already holding reorders the table with no round trip — and no agreement with the server that produced the rows, which is the one thing a server-driven table is for. Both warn rather than fail: the fix is a change of shape, not a change of import, and that is a judgement the linter cannot make for you.

enforcement

run these in your own project

All 15 rules as one Biome config, with a GritQL plugin for each rule Biome has no built-in for and the documented exceptions already applied.

set it up →