On this page
Lint rules
Check component usage and StyleX styles. Compare examples that pass or fail each rule. Choose its configuration options.
Use Oxlint to check component usage and StyleX styles in your application. Each rule below explains what it checks, how to fix errors, and which options you can change.
Configuration
Run init to install Oxlint and @yopem-ui/oxlint-plugin:
The command creates or updates .oxlintrc.json. It preserves existing rule
settings, including explicit "off" values.
The recommended preset enables four rules: prefer-layout-primitives,
no-restyle, enforce-styling-methods, and static-stylex. CLI init also
enables no-raw-stylex-colors. Enable no-unused-stylex-styles and atoms
separately when needed.
For manual setup, install the development dependencies:
Use this configuration:
The override excludes copied component implementations. Keep these checks on application code that uses the components. Check your project:
Rules
yopem-ui/prefer-layout-primitives
Recommended. Use layout and typography components instead of native elements with equivalent components. Each error names a replacement. Keep native attributes, events, and refs when you change the element.
Rejected: native wrappers and text elements.
Accepted: components preserve the semantic elements through render.
Choose Flex, Stack, Grid, or another layout component for the layout you need. The rule does not use CSS to choose a component.
By default, the rule checks these tags:
- Layout:
div,span,main,section,article,aside,header,footer,nav,address,figure,figcaption,search, andhgroup. - Lists:
ul,ol,li,dl,dt, anddd. - Text:
pre,p,blockquote,em,mark, andh1throughh6.
Props, spreads, refs, conditional branches, and nested JSX do not exclude these
tags from checks. Native elements inside a render prop are permitted. The rule
does not check native anchors or framework links. It also permits controls,
tables, document metadata, SVG, custom elements, strong, and inline code.
Use Pre for generic preformatted content. Preserve native props and refs. Use
Codeblock for code displays. Codeblock adds a wrapper and toolbar, so it cannot
directly replace a native pre or its ref.
Set elements to replace the default tag list. An empty array disables tag
checks.
yopem-ui/no-restyle
Recommended. Restrict properties passed through xstyle on imported UI
components. By default, only properties in the layout category are permitted.
Use component props such as variant and size before you change their styles.
Rejected: changing Button color and padding through xstyle.
Accepted: use Button props and a layout override.
The rule checks local stylex.create declarations, arrays, conditional styles,
logical results, static string bracket access, and nested selectors. It does not
check the left guard of &&. It cannot verify imported styles or dynamic
computed access. Registry Link is excluded by default.
Use property names, * patterns, or categories in allow and deny.
Categories are layout, spacing, color, typography, shape, effects,
motion, and unclassified. For example, margins and dimensions belong to
layout; padding and gaps belong to spacing. An empty allow array permits
no properties. A matching deny entry takes priority over allow.
exclude and contract pattern values are regular expressions for imported
component names. The last matching contract wins. It replaces only the policy
fields that it sets. Custom messages support {{component}} and {{property}}.
The rule also checks controlXstyle on Input, Textarea, and AutocompleteInput.
It checks surfaceXstyle on SheetPopup. Each slot inherits its component
policy. Use a slot contract to change that slot without changing xstyle:
Slot contracts use the same last-match order. Put specific slot contracts after broad component patterns. Fields not set by a slot contract keep the component policy values. Other component props do not become style slots.
yopem-ui/enforce-styling-methods
Recommended. Choose which styling methods imported UI components can accept.
The defaults permit xstyle and className. They reject css, inline React
style, and direct stylex.props spreads on those components.
Rejected: an inline React style bypasses the component's style composition.
Accepted: pass StyleX styles through xstyle.
Native elements and framework links can still use stylex.props(...). Registry
Link is excluded by default.
Set individual methods to true or false. Omitted methods keep their
defaults. reactStyle controls React style; stylexStyle controls StyleX
spreads and stylex.props(...).style.
yopem-ui/static-stylex
Recommended. Keep stylex.create object shapes and keys static so StyleX
can compile them. The rule rejects a non-object argument, object spreads, and
computed keys. It permits computed stylex.when.ancestor and
stylex.when.descendant conditions.
Rejected: a spread hides the declaration's properties.
Accepted: write the properties in the declaration.
This rule has no options. It does not replace the StyleX compiler's validation of property values.
yopem-ui/no-raw-stylex-colors
Optional in the recommended preset; enabled by CLI init. Use design tokens
instead of literal colors in stylex.create. The rule reports hex values and
CSS color functions on color properties, including nested state values.
Rejected: a literal hex color.
Accepted: a semantic color token follows the active theme.
Checked properties include color, background, backgroundColor, border
colors, outlineColor, textDecorationColor, fill, and stroke. Checked
functions include rgb, hsl, oklch, oklab, lab, lch, and color. The
rule does not check named colors, shadows, gradients, or other CSS strings. This
rule has no options.
yopem-ui/no-unused-stylex-styles
Optional. Report unused top-level style keys in local stylex.create
declarations. Remove unused keys after you check whether their values have side
effects. The rule has no automatic fix.
Rejected: unused has no reference.
Accepted: every declared key is used.
The rule recognizes import aliases, lexical scope, dot access, string-literal bracket access, and dynamic style functions. It skips exported objects, objects passed to other code, destructured objects, and dynamic property access. It also skips declarations with spreads or computed keys because it cannot verify their use in the file.
Enable it as a warning or error. This rule has no options.
yopem-ui/atoms
Optional. Control whether your application can use StyleX atoms. Install
@stylexjs/atoms and compile it with the StyleX Babel plugin before using
atoms.
Choose a mode:
allowis the default. It permits atoms and local StyleX declarations.disallowreports imports from the configured atoms source.enforcerejects localstylex.createdeclarations and requires an atoms reference in JSXxstyleandsxexpressions.
Rejected in enforce mode: local styles without atoms.
Accepted in enforce mode: use atoms in xstyle.
Combine atoms in an xstyle array. Do not place atoms inside stylex.create
objects. The enforce mode checks for an atoms reference, not whether every
array entry is an atom. Other enabled rules still apply; configure no-restyle
to permit the properties you need.
Set source to your atoms module if you use a custom wrapper.
Component imports
no-restyle and enforce-styling-methods identify components through their
imports. Default sources are @/components/ui/, @registry/components/ui/, and
@yopem-ui/ui. Source patterns match an exact import or an import that starts
with the pattern. The rules support import aliases and namespace imports.
Set componentSources and styleComponents when you use custom import paths or
component names. These arrays replace their defaults. Include every source and
component that you want checked.
Exceptions
Use file overrides for copied primitives, document shells, and non-DOM renderers
that need native elements. Disable only the rules that do not apply to those
files. Filenames and data-slot attributes do not automatically exclude code
from checks.