# Linter

Oxlint rules that check how your app uses Tempo Design System.

## Overview

The library ships an Oxlint plugin that reports the mistakes types cannot catch, such as an unnamed icon-only [Button](/docs/components/button), an import from an internal path, or a native control or hand-built card that a component replaces.

## Set Up the Linter

Spread the configuration for your surface, web, mobile, or marketing, into the lint options of Vite Plus, then run the linter.

```ts title="vite.config.ts"
import { web } from '@tempoxyz/ds/oxlint'
import { defineConfig } from 'vite-plus'

export default defineConfig({ lint: web })
```

```sh
vp lint
```

To change a severity, spread the rules and override one.

```ts title="vite.config.ts"
import { web } from '@tempoxyz/ds/oxlint'
import { defineConfig } from 'vite-plus'

export default defineConfig({
  lint: { ...web, rules: { ...web.rules, 'tds/no-raw-values': 'error' } },
})
```

Without Vite Plus, register both plugins and enable the rules in an Oxlint configuration file.

```json title=".oxlintrc.json"
{
  "jsPlugins": [
    { "name": "tds", "specifier": "@tempoxyz/ds/oxlint" },
    { "name": "zyzz", "specifier": "zyzz/oxlint" }
  ],
  "rules": {
    "tds/no-cross-surface": ["error", { "surface": "web" }],
    "tds/no-custom-values": "warn",
    "tds/no-internal-imports": "error",
    "tds/no-raw-values": "warn",
    "tds/no-single-key-shortcuts": "warn",
    "tds/prefer-component": "warn",
    "tds/prefer-layout": "warn",
    "tds/prefer-progress": "warn",
    "tds/prefer-surface": "warn",
    "tds/prefer-typography": "warn",
    "tds/require-accessible-name": "error",
    "tds/require-scroll-region": "warn"
  }
}
```

## Rules

### Import From Public Entrypoints

Reports a library import from a path that the package does not publish. The root, icons, mobile, and oxlint entrypoints pass, and so do icon SVG and font files.

```json
{ "rules": { "tds/no-internal-imports": "error" } }
```

**Do:** Import components from `@tempoxyz/ds` and icons from `@tempoxyz/ds/icons`.

````tsx
```tsx
import { Spinner } from '@tempoxyz/ds'
import { Copy } from '@tempoxyz/ds/icons'
```
````

**Don't:** Import from `src` or `dist`. Internal paths change without a release note.

````tsx
```tsx
import { Spinner } from '@tempoxyz/ds/src/web'
// @lint: tds/no-internal-imports: '@tempoxyz/ds/src/web' is not a published entrypoint. Import from '@tempoxyz/ds', '@tempoxyz/ds/mobile', or their `icons` subpaths.
import { Copy } from '@tempoxyz/ds/dist/icons'
// @lint: tds/no-internal-imports: '@tempoxyz/ds/dist/icons' is not a published entrypoint. Import from '@tempoxyz/ds', '@tempoxyz/ds/mobile', or their `icons` subpaths.
```
````

### Stay on One Surface

Reports an import from the surface that your app does not render. Without a surface option, it reports a file that imports from both surfaces.

```json
{ "rules": { "tds/no-cross-surface": ["error", { "surface": "web" }] } }
```

**Do:** Import every component and icon of a React Native app from the Mobile entrypoints.

````tsx
```tsx
import { Toggle } from '@tempoxyz/ds/mobile'
import { Copy } from '@tempoxyz/ds/mobile/icons'
```
````

**Don't:** Mix surfaces in one app. Each surface owns its variables, and a Web component does not render in React Native.

````tsx
```tsx
import { Toggle } from '@tempoxyz/ds/mobile'
import { Switch } from '@tempoxyz/ds'
// @lint: tds/no-cross-surface: '@tempoxyz/ds' belongs to the web surface, but this app uses the mobile surface.
```
````

### Name Controls Without Text

Reports a library component that renders no text and has no accessible name, such as an icon-only [Button](/docs/components/button) or a [Gauge](/docs/components/gauge).

```json
{ "rules": { "tds/require-accessible-name": "error" } }
```

**Do:** Name the action in `aria-label`, on the button or on the trigger that renders it.

````tsx
```tsx
<Button aria-label="Copy address" shape="icon">
  <Copy />
</Button>
```
````

**Don't:** Leave an icon-only button or a [Gauge](/docs/components/gauge) unnamed. Screen readers announce only its role.

````tsx
```tsx
<Button shape="icon">
  <Copy />
</Button>
// @lint: tds/require-accessible-name: 'Button' renders no text. Name it with `aria-label` or `aria-labelledby`.
```
````

### Name Scroll Regions

Reports a native element that scrolls without a role, a tab stop, and a name. A container whose content holds a link, a button, or a field passes, since its content takes focus.

```json
{ "rules": { "tds/require-scroll-region": "warn" } }
```

**Do:** Name the region and give it a tab stop, so keyboards can scroll it.

````tsx
```tsx
<div aria-label="Fee schedule" role="region" {...styles.scroll()} tabIndex={0}>
  <Table.Root>{rows}</Table.Root>
</div>
```
````

**Don't:** Leave a scroll container without a tab stop. Keyboard users cannot reach the hidden content.

````tsx
```tsx
<div style={{ overflowX: 'auto' }}>
// @lint: tds/require-scroll-region: This scrolling <div> needs role="region", tabIndex={0}, and an aria-label, so keyboard and screen reader users can reach and identify it.
  <Table.Root>{rows}</Table.Root>
</div>
```
````

### Require a Modifier on Shortcuts

Warns on a key listener on the window or the document that matches one printable character, such as G or /, and reads no modifier. A character key on the whole page fires while people type or dictate ([SC 2.1.4](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html)).

```json
{ "rules": { "tds/no-single-key-shortcuts": "warn" } }
```

A single-key shortcut is valid when people can turn it off or remap it, or when it works only while a component has focus. The rule cannot detect either case. If a shortcut meets one of them, disable the rule on that line and state the reason.

```tsx
window.addEventListener('keydown', (event) => {
  // oxlint-disable-next-line tds/no-single-key-shortcuts -- Settings turn this shortcut off.
  if (shortcuts.enabled && event.key === '/') open()
})
```

**Do:** Require Command or Control, and show the shortcut with [Kbd](/docs/components/kbd).

````tsx
```tsx
window.addEventListener('keydown', (event) => {
  if (event.key === 'k' && (event.metaKey || event.ctrlKey)) open()
})
```
````

**Don't:** Bind a lone character key on the whole page, unless people can turn it off or remap it.

````tsx
```tsx
window.addEventListener('keydown', (event) => {
  if (event.key === '/') open()
  // @lint: tds/no-single-key-shortcuts: '/' is a single-key shortcut on the whole page. Require a modifier, such as metaKey or ctrlKey, or let people turn it off or remap it (WCAG 2.1.4).
})
```
````

### Prefer Library Components

Warns on a native element that a library component replaces, such as a button, a checkbox, a dialog, a table, or a description list. The message links the docs page of the component. Elements in a render prop pass, and an allow list skips the elements you name.

```json
{ "rules": { "tds/prefer-component": ["warn", { "allow": ["table"] }] } }
```

**Do:** Use [Checkbox](/docs/components/checkbox) and [Button](/docs/components/button), which bring Tempo states, focus rings, and motion.

````tsx
```tsx
<Checkbox defaultChecked />
<Button variant="secondary">Cancel</Button>
```
````

**Don't:** Restyle a native control that the library already ships.

````tsx
```tsx
<input defaultChecked type="checkbox" />
// @lint: tds/prefer-component: Use 'Checkbox' from '@tempoxyz/ds' instead of <input>. See https://ds.tehq.dev/docs/components/checkbox
<button type="button">Cancel</button>
// @lint: tds/prefer-component: Use 'Button' from '@tempoxyz/ds' instead of <button>. See https://ds.tehq.dev/docs/components/button
```
````

### Use Surface for Cards

Warns on an article, aside, div, list item, or section whose styles draw a card: a corner radius and padding with a border or a background. Pills and positioned layers pass.

```json
{ "rules": { "tds/prefer-surface": "warn" } }
```

**Do:** Use [Surface](/docs/components/surface), which sets the radius and padding together.

````tsx
```tsx
<Surface>
  <Surface.Title>Balance</Surface.Title>
</Surface>
```
````

**Don't:** Rebuild a card from tokens. The radius and padding drift apart.

````tsx
```tsx
namespace styles {
  export const card = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    padding: '16',
  })
}

;<div {...styles.card()} />
// @lint: tds/prefer-surface: Use 'Surface' from '@tempoxyz/ds' instead of styling <div> as a card. It sets the radius and padding together.
```
````

### Use Layout Components

Warns on a block element whose only styles lay out its children with flex or grid and a gap. A column maps to [Stack](/docs/components/stack), a row to [Inline](/docs/components/inline), and equal tracks to [Grid](/docs/components/grid). An element with any other declaration or a class name passes.

```json
{ "rules": { "tds/prefer-layout": "warn" } }
```

**Do:** Space siblings with a layout component and its gap token.

````tsx
```tsx
<Stack gap="16">
  <Field.Root />
  <Field.Root />
</Stack>
```
````

**Don't:** Hand-build a flex or grid wrapper that a layout component replaces.

````tsx
```tsx
<div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
// @lint: tds/prefer-layout: Use 'Stack' from '@tempoxyz/ds' instead of laying out <div> with flex and a gap.
  <Field.Root />
  <Field.Root />
</div>
```
````

### Use Progress for Bars

Warns on an empty div or span whose inline width is a computed percentage, which draws the fill of a hand-built bar. An element with children passes, since a resizable pane sets its width the same way.

```json
{ "rules": { "tds/prefer-progress": "warn" } }
```

**Do:** Use [Progress](/docs/components/progress), or `ListGroup.Meter` in a [ListGroup](/docs/components/list-group) row, which announce the value.

````tsx
```tsx
<Progress.Root value={66}>
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
```
````

**Don't:** Draw a bar from a sized element. Screen readers announce nothing.

````tsx
```tsx
<div {...styles.track()}>
  <div style={{ width: `${used}%` }} />
  // @lint: tds/prefer-progress: Use 'Progress' from '@tempoxyz/ds', or 'ListGroup.Meter' in a ListGroup row, instead of drawing a bar with <div> and a percentage width.
</div>
```
````

### Set Type With a Typography Set

Warns when one `style` or `variants` object sets two or more of `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, and `lineHeight`, or one of them beside `typography`. These build a type style that no set defines. One property alone passes, such as a `fontSize` that sizes an icon.

```json
{ "rules": { "tds/prefer-typography": "warn" } }
```

**Do:** Set type with one set, as [Typography](/docs/foundations/typography#set-type-with-one-set) describes.

````tsx
```tsx
style({ color: 'content.secondary', typography: 'body.b2' })
```
````

**Don't:** Combine a family and a size from different sets.

````tsx
```tsx
style({ fontFamily: 'heading', fontSize: '14' })
// @lint: tds/prefer-typography: 'fontFamily' composes a type style outside a typography set. Use one `typography` set, such as 'body.b2'.
// @lint: tds/prefer-typography: 'fontSize' composes a type style outside a typography set. Use one `typography` set, such as 'body.b2'.
```
````

### Style With Tokens

Warns on a raw color, length, or font family in an inline style. A value that reads a custom property passes.

```json
{ "rules": { "tds/no-raw-values": "warn" } }
```

**Do:** Set colors and spacing with tokens in a `style` definition.

````tsx
```tsx
namespace styles {
  export const card = style({ padding: '16' })
}

;<div {...styles.card()} />
```
````

**Don't:** Hardcode colors and lengths in inline styles. They do not follow the scheme or the token scale.

````tsx
```tsx
<div style={{ color: '#000', padding: 16 }} />
// @lint: tds/no-raw-values: 'color' sets the raw value '#000'. Use a token through a Zyzz style instead.
// @lint: tds/no-raw-values: 'padding' sets the raw value 16. Use a token through a Zyzz style instead.
```
````

### Use Tokens for Custom Values

Warns on a `!custom` value in a `style` or `variants` definition that equals a token: a px or rem length that equals a spacing, radius, size, or container step, or a `zIndex` number that equals a layer. The message names the token. A value that no token fits, such as `'13px !custom'`, passes.

```json
{ "rules": { "tds/no-custom-values": "warn" } }
```

* **Spacing ('16'):** Padding, margins, and gaps, with keys in px.
* **Radius ('xs'):** Corners, from `3xs` at 4px to `2xl` at 64px.
* **Layers ('popover'):** `overlay` 40, `popover` 50, `modal` 60, and `toast` 1000.

**Do:** Set lengths and layers with tokens.

````tsx
```tsx
style({ borderRadius: 'xs', padding: '16', zIndex: 'popover' })
```
````

**Don't:** Mark a value with `!custom` when a token equals it.

````tsx
```tsx
style({ borderRadius: '12px !custom', zIndex: '50 !custom' })
// @lint: tds/no-custom-values: 'borderRadius' sets the custom value '12px !custom', which equals a token. Use the radius token 'xs'.
// @lint: tds/no-custom-values: 'zIndex' sets the custom value '50 !custom', which equals a token. Use the zIndex token 'popover'.
```
````

## Zyzz Rules

Both configurations also turn on the rules of the Zyzz plugin, which check style definitions and their use.

### Merge Styling Props Into the Style

Reports a className or style prop that would overwrite a style spread.

```json
{ "rules": { "zyzz/no-conflicting-props": "error" } }
```

**Do:** Pass the caller's class into the style call, which merges it.

````tsx
```tsx
<div {...styles.card({ className: props.className })} />
```
````

**Don't:** Set a class beside a style spread. One overwrites the other.

````tsx
```tsx
<div className="card" {...styles.card()} />
// @lint: zyzz/no-conflicting-props: Pass 'className' into the Zyzz style call to merge styling props.
```
````

### Remove Unused Styles

Warns on a style in a styles namespace that nothing applies.

```json
{ "rules": { "zyzz/no-unused": "warn" } }
```

**Do:** Keep only the styles that the module applies.

````tsx
```tsx
namespace styles {
  export const card = style({ padding: '16' })
}

;<div {...styles.card()} />
```
````

**Don't:** Leave a style that nothing applies. It still ships in the stylesheet.

````tsx
```tsx
namespace styles {
  export const card = style({ padding: '16' })

  export const legacy = style({ padding: '8' })
  // @lint: zyzz/no-unused: Style 'styles.legacy' is never used.
}
```
````

### Write Scalar Declarations

Reports a declaration whose value is not a string, a number, or a fallback array.

```json
{ "rules": { "zyzz/valid-styles": "error" } }
```

**Do:** Set each side with its own property.

````tsx
```tsx
style({ paddingTop: '8' })
```
````

**Don't:** Nest an object inside a declaration.

````tsx
```tsx
style({ padding: { top: '8' } })
// @lint: zyzz/valid-styles: CSS declarations require scalar values or fallback arrays.
```
````

## Related

[Agents](/docs/foundations/agents)

Covers the rules that coding agents follow and the checks they run.

[Accessibility](/docs/foundations/accessibility)

Covers the accessible names that the linter checks.

[Getting Started](/docs/introduction/getting-started)

Covers the install and the Zyzz setup that the linter builds on.
