Lint rules

First, choose a layout component and style with StyleX.

Rules

The local Oxlint plugin enforces styling methods and component contracts. Other StyleX consistency rules remain opt-in:

• yopem-ui/prefer-layout-primitives (recommended): replace <div> and <span> with layout primitives such as Box, Flex, Grid, Center, or Stack. Other semantic tags remain valid. Set elements to replace the checked tags, or turn the rule off for code that intentionally uses native elements.
• yopem-ui/no-restyle (recommended): restrict StyleX properties passed through xstyle to imported UI components. By default only layout properties pass, so color and shape changes prefer existing variant props, and spacing prefers size where those props exist. Resolves local stylex.create declarations, arrays, and conditional styles; skips imported or computed styles that cannot be verified within the file.
• yopem-ui/enforce-styling-methods: allow xstyle and consumer className on imported UI components; reject css, inline React style, and direct stylex.props spreads on those components. Set className: false for apps styled exclusively with StyleX, as this docs app does.
• yopem-ui/static-stylex: require statically analyzable StyleX declarations.
• yopem-ui/valid-polymorphic-as: validate native tags on Box and heading levels on Heading.
• yopem-ui/no-raw-stylex-colors (off in plugin's recommended preset): flag literal hex and CSS color functions on color properties in stylex.create. Tokens pass. CLI init and docs app enable it; shadows and unrelated CSS strings are not inspected.
• yopem-ui/atoms (off by default): mode: "allow" (default), "disallow" (reject atoms imports), or "enforce" (reject stylex.create declarations and require atoms in JSX xstyle/sx expressions). Official atoms compose alongside StyleX styles, not inside stylex.create objects.

Configuration

bunx @yopem-ui/cli init installs Oxlint and @yopem-ui/oxlint-plugin, then creates or merges .oxlintrc.json with the recommended rules and raw-color checks. Existing rules, including explicit "off" values, remain untouched. Copied src/components/ui/ implementations are exempted from the Yopem rules; app JSX is checked. Configure the plugin for your app source. The following docs-app policy allows xstyle but disallows className. Copied components still expose className for external integration.

.oxlintrc.json

{
  "jsPlugins": [
    {
      "name": "yopem-ui",
      "specifier": "@yopem-ui/oxlint-plugin"
    }
  ],
  "overrides": [
    {
      "files": ["apps/docs/src/**/*.{tsx,jsx}"],
      "rules": {
        "yopem-ui/enforce-styling-methods": [
          "error",
          { "methods": { "className": false } }
        ],
        "yopem-ui/no-raw-stylex-colors": "error",
        "yopem-ui/static-stylex": "error",
        "yopem-ui/valid-polymorphic-as": "error"
      }
    }
  ]
}

To enforce component contracts, enable no-restyle (included in plugin recommendedRules and CLI init; docs previews currently opt out while keeping raw-color consistency enabled):

{
  "yopem-ui/no-restyle": [
    "error",
    {
      "allow": ["layout", "margin*"],
      "deny": ["marginBlockStart"],
      "exclude": ["^Legacy"],
      "contracts": [
        {
          "pattern": "^CardTitle$",
          "allow": ["fontSize", "color"],
          "deny": [],
          "message": "Use a {{component}} variant instead of {{property}}."
        }
      ]
    }
  ]
}

allow and deny accept StyleX property names, * globs, or categories (layout, spacing, color, typography, shape, effects, motion). Omitted allow defaults to layout; an empty allow permits none. deny wins. Contract regexes match imported component names; last matching contract wins and replaces only keys it sets. exclude takes component name regexes. Set componentSources and styleComponents to replace imported UI recognition defaults. Messages support {{component}} and {{property}}. Use file overrides to exempt component implementations.

To use atoms, install and compile @stylexjs/atoms with StyleX's Babel plugin. Atoms use a default import and compose through StyleX props or sx:

import x from "@stylexjs/atoms"

const preview = <Button xstyle={[x.paddingInline._12px, x.color.blue]} />

Configure "yopem-ui/atoms": ["error", { "mode": "enforce" }] to require atoms instead of local stylex.create declarations and in JSX xstyle/sx. "disallow" rejects atoms imports; "allow" permits both. For a wrapper imported from @apps/stylexjs/atoms, set "source": "@apps/stylexjs/atoms". This repo does not currently include that wrapper or the atoms dependency; leave the atoms rule off until installed and compiled.

Opt out of the default native layout rule in your .oxlintrc.json with "yopem-ui/prefer-layout-primitives": "off", or replace its checked tags with ["error", { "elements": ["div", "span", "section"] }]. Use Oxlint file overrides for document shells or renderer code. The docs app does not enable this rule for its existing markup.

Native framework elements (for example TanStack Router links) can use stylex.props(...). Imported UI components should use xstyle instead of a StyleX prop spread, so component defaults and consumer styles compose in order.

Exceptions

Registry implementations and non-DOM JSX renderers are outside the docs rule scope. Run bun run lint from the repository root.