@tempoxyz/ds 0.3.11 → 0.3.13

package/dist/docs/foundations/linter.md

@@ -1,296 +0,0 @@
-# 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 that a component replaces.
-
-## Set Up the Linter
-
-Spread the configuration for your surface, web or mobile, 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-internal-imports": "error",
-    "tds/no-raw-values": "warn",
-    "tds/prefer-component": "warn",
-    "tds/require-accessible-name": "error"
-  }
-}
-```
-
-## 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`.
-```
-````
-
-### Prefer Library Components
-
-Warns on a native element that a library component replaces, such as a button, a checkbox, a dialog, or a table. 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>.
-<button type="button">Cancel</button>
-// @lint: tds/prefer-component: Use 'Button' from '@tempoxyz/ds' instead of <button>.
-```
-````
-
-### 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.
-```
-````
-
-## 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.