rule 04 — tier 4
react-aria-components is ui-lib's dependency, not yours. In app code import <Button> from @/components/button, never from react-aria-components — the primitive is unstyled and knows nothing about the quebi variants.
import-components-not-primitiveselement usage
Layout is yours. Appearance is the library's.
The element rules stop at the element name, and this walks straight past them. `import { Button } from "react-aria-components"` renders `<Button>`, which no element check objects to — and gets you a control with the accessibility but none of the design: no intents, no sizes, no focus ring in the quebi idiom, nothing that follows a token change. It is the same layering mistake as a hand-rolled `<button>`, one level up, and it is harder to spot in review because the JSX looks right.
There are exactly three layers here and each imports from the one below it. App code imports quebi components. Quebi components import react-aria primitives — that is what they are for; quebi's Button does not wrap `<button>`, it wraps react-aria's Button. React-aria renders the intrinsic. A layer reaching two levels down is the definition of a leaky abstraction, and the import is the last place it can leak.
The ban is derived, not curated: it is exactly the set of primitives the library's own source imports. Wrap a new one tomorrow and it becomes app-forbidden the same day. What stays importable is what the library does not wrap — `parseColor`, `useLocale`, `useFilter`, and every type, since types are erased and a value handed to you by a quebi component is often typed by react-aria.
Button (react-aria-components)TextField / Input (react-aria-components)Link (react-aria-components)Anything else the library wrapsThe banned list is generated from the library's own react-aria imports, so it always matches what ui-lib actually wraps — around 114 primitives today.
don't
import { Button } from "react-aria-components"
<Button onPress={save}>Save</Button>do
import { Button } from "@/components/button"
<Button intent="primary" onPress={save}>
Save
</Button>Both render an accessible button. Only one of them is a quebi button, and no element check can tell them apart — which is why this rule reads imports rather than JSX.
don't
import { ColorSwatch, parseColor } from "react-aria-components"do
import { parseColor } from "react-aria-components"
import type { DateValue } from "react-aria-components"
import { ColorSwatch } from "@/components/color-swatch"Helpers the library does not wrap (parseColor, useLocale, useFilter) and every type import are fine — types are erased, and a value a quebi component hands you is often typed by react-aria. Only the wrapped primitives are banned.
Add one of these to your project and the rule holds without anyone having to remember it — including the agent writing half the JSX. The exceptions below are already applied, so a documented carve-out will not be reported.
What it will and will not catch: The check reads the import list, so it says nothing about what you do with the primitive — and it cannot see a re-export chain that reaches react-aria by another name. The ripgrep version finds every react-aria import including the legitimate ones, so read it as a list to review rather than a list of violations.
A built-in Biome rule, so there is nothing to install and no pattern to maintain. One message per element, and the documented exceptions are ordinary `overrides`.
// biome.jsonc
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"level": "error",
"options": {
"paths": {
"react-aria-components": {
"importNames": [
"Autocomplete",
"Breadcrumb",
"Breadcrumbs",
"Button",
"Calendar",
"CalendarCell",
"CalendarGrid",
"CalendarGridBody",
"CalendarGridHeader",
"CalendarHeaderCell",
"CalendarStateContext",
"Cell",
"Checkbox",
"CheckboxContext",
"CheckboxGroup",
"Collection",
"CollectionRendererContext",
"ColorArea",
"ColorField",
"ColorFieldStateContext",
"ColorPicker",
"ColorPickerStateContext",
"ColorSlider",
"ColorSwatch",
"ColorSwatchPicker",
"ColorSwatchPickerItem",
"ColorThumb",
"ColorWheel",
"ColorWheelTrack",
"Column",
"ColumnResizer",
"ComboBox",
"DateField",
"DateInput",
"DatePicker",
"DateRangePicker",
"DateSegment",
"DefaultCollectionRenderer",
"Dialog",
"DialogTrigger",
"Disclosure",
"DisclosureGroup",
"DisclosurePanel",
"DisclosureStateContext",
"DropZone",
"FieldError",
"FieldErrorContext",
"FileTrigger",
"Form",
"GridList",
"GridListHeader",
"GridListItem",
"GridListSection",
"Group",
"Header",
"Heading",
"Input",
"Keyboard",
"Label",
"Link",
"ListBox",
"ListBoxItem",
"ListBoxSection",
"Menu",
"MenuItem",
"MenuSection",
"MenuTrigger",
"Meter",
"Modal",
"ModalContext",
"ModalOverlay",
"NumberField",
"OverlayArrow",
"OverlayTriggerStateContext",
"Popover",
"Pressable",
"ProgressBar",
"Radio",
"RadioGroup",
"RangeCalendar",
"RangeCalendarStateContext",
"ResizableTableContainer",
"Row",
"SearchField",
"Select",
"SelectValue",
"Separator",
"Slider",
"SliderOutput",
"SliderStateContext",
"SliderThumb",
"SliderTrack",
"SubmenuTrigger",
"Switch",
"Tab",
"TabList",
"TabPanel",
"TabPanels",
"Table",
"TableBody",
"TableHeader",
"TableLayout",
"TableLoadMoreItem",
"TableStateContext",
"Tabs",
"Tag",
"TagGroup",
"TagList",
"Text",
"TextArea",
"TextField",
"TimeField",
"ToggleButton",
"ToggleButtonGroup",
"Toolbar",
"Tooltip",
"TooltipTrigger",
"Tree",
"TreeItem",
"TreeItemContent",
"Virtualizer"
],
"message": "react-aria-components is ui-lib's dependency, not yours: import the quebi component instead (Button -> @/components/button, TextField -> @/components/text-field, and so on). Helpers the library does not wrap, like parseColor, and type-only imports stay allowed. See https://ui-lib.quebi.de/rules/import-components-not-primitives"
}
}
}
}
}
}
},
"overrides": [
{
"includes": [
"src/components/**",
"components/ui/**"
],
"linter": {
"rules": {
"style": {
"noRestrictedImports": "off"
}
}
}
}
]
}
Finds candidates for review in any repo, linter or not. Coarser than the Biome check: it reads lines, not syntax, so expect false positives and treat a clean run as weaker evidence than a clean lint run.
# import-components-not-primitives — candidates for review
rg -n -g '*.{jsx,tsx}' \
-g '!src/components/**' \
-g '!components/ui/**' \
"from \"react-aria-components\""
One exception on this rule is a judgement call, so it cannot be a path. Biome's suppression syntax has a slot for the reason — fill it, because that note is what makes the carve-out reviewable instead of invisible.
// biome-ignore lint/style/noRestrictedImports: A primitive the library genuinely does not wrap — If react-aria ships something with no quebi equivalent, importing it directly is the only option, and the derived ban will not contain it.
// Between JSX children, where a comment has to be an expression, the same
// line is written {/* biome-ignore … */}.Enforcing more than this one rule? Take the whole config instead of collecting snippets.
Carve-outs are part of the rule, not a way around it. Each one is already an ignore glob in the checks above, so the cases listed here need no disable comment — and a case that is not listed is one to argue for, not to silence.
app/**/*.{tsx,jsx}src/**/*.{tsx,jsx}