Skip to content
UI
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, and hgroup.
  • Lists: ul, ol, li, dl, dt, and dd.
  • Text: pre, p, blockquote, em, mark, and h1 through h6.

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:

  • allow is the default. It permits atoms and local StyleX declarations.
  • disallow reports imports from the configured atoms source.
  • enforce rejects local stylex.create declarations and requires an atoms reference in JSX xstyle and sx expressions.

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.