@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/foundations/linter.md

@@ -0,0 +1,496 @@
+# 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](../components/button.md), 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/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](../components/button.md) or a [Gauge](../components/gauge.md).
+
+```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](../components/gauge.md) 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](../components/kbd.md).
+
+````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](../components/checkbox.md) and [Button](../components/button.md), 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](../components/surface.md), 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](../components/stack.md), a row to [Inline](../components/inline.md), and equal tracks to [Grid](../components/grid.md). 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](../components/progress.md), or `ListGroup.Meter` in a [ListGroup](../components/list-group.md) 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>
+```
+````
+
+### 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](agents.md)
+
+Covers the rules that coding agents follow and the checks they run.
+
+[Accessibility](accessibility.md)
+
+Covers the accessible names that the linter checks.
+
+[Getting Started](../introduction/getting-started.md)
+
+Covers the install and the Zyzz setup that the linter builds on.

package/dist/docs/product/foundations/motion.md

@@ -0,0 +1,151 @@
+# Motion
+
+Easing curves, durations, and reduced-motion rules for state changes.
+
+## Overview
+
+Motion in Tempo shows where something came from, confirms a press, and marks what is new. It is short, eases out, and never delays input, both in components and in anything you style yourself.
+
+## Easing
+
+Three ease-out curves cover interface motion, so each response starts at full speed. Use them by name instead of the browser default or a custom curve.
+
+* `ease.snappy`: `cubic-bezier(0.23, 1, 0.32, 1)`
+* `ease.spring`: `cubic-bezier(0.32, 0.72, 0, 1)`
+* `ease.overshoot`: `cubic-bezier(0.34, 1.36, 0.64, 1)`
+
+* **Snappy (ease.snappy):** Short changes, such as hover, focus, presses, popovers, and menus.
+* **Overshoot (ease.overshoot):** Only physical feedback, such as switch thumbs and check marks. A dialog or menu would wobble.
+* **Spring (ease.spring):** Larger travel, such as dialogs, drawers, toasts, and tabs.
+* **Constant Rate (linear):** Continuous indicators only, such as [Spinner](../components/spinner.md), which would pulse with easing.
+
+## Durations
+
+Small state changes finish fastest, overlays that travel farther run longer, and every overlay leaves faster than it enters.
+
+### Micro Interactions
+
+* **Press (100ms in, 160ms out):** Buttons scale down slightly and return on release.
+* **Item Highlight (120ms):** Menu, select, and combobox items highlight.
+* **Hover, Focus, and Color (160ms):** Buttons, tabs, and checkboxes change color.
+* **Check Indicators (200ms):** Checkbox and radio indicators overshoot slightly.
+* **Switch Thumb (240ms):** The switch thumb slides with a slight overshoot.
+* **Selection Indicator (240ms):** The tabs indicator slides to the selected tab.
+
+### Overlays and Content
+
+* **Tooltip (160ms in, 100ms out):** Tooltips fade in, and leave faster than they enter.
+* **Popover and Menu (200ms in, 140ms out):** Popovers and menus grow from their trigger.
+* **Select and Combobox List (240ms in, 150ms out):** Lists open on the spring curve and close on snappy.
+* **Expanding Content (240ms in, 180ms out):** Accordion panels expand and collapse.
+* **Dialog (280ms in, 180ms out):** Dialogs enter over a fading backdrop.
+* **Drawer and Toast (320ms in, 200 to 240ms out):** Drawers and toasts travel farthest and run longest.
+
+## Guidelines
+
+### Animate Every State Change
+
+Give every state change a transition, from hover and focus to checked, disabled, and invalid states. Animate overlays, toasts, expanding content, and changing values in and out.
+
+* **Press:** Scale the control to `scale.press` (0.98).
+* **Popover and Menu:** Fade and grow from `scale.enter` (0.96).
+* **Dialog and Drawer:** Fade the backdrop and slide or scale the panel.
+* **Value Change:** Fade or slide the new value in.
+
+### Use Transitions for State, Keyframes for Feedback
+
+A transition reverses from its current point when the state flips back, so a quick hover in and out never jumps. Keep keyframes for feedback that plays once.
+
+* **State Changes (transition):** Hover, press, checked, and open states, such as the switch thumb.
+* **One-Shot Feedback (keyframes):** The 360ms nudge of an invalid [TextInput](../components/text-input.md) or [OtpField](../components/otp-field.md), and the 240ms pop of a [CopyButton](../components/copy-button.md) check.
+
+### Animate Transform and Opacity
+
+Animate transforms, opacity, colors, shadows, and outlines, which change without a new layout. Animate size only when no transform produces the effect, as the components below do.
+
+**Do:** Scale a pressed control to `scale: 'press'` with `ease.snappy`.
+
+**Don't:** Animate `width`, `height`, or `margin` when a transform produces the same effect.
+
+* **Accordion (height):** Panels grow to a measured height, not a transform.
+* **SidebarMenu (height):** Nested items grow as a group expands.
+* **Progress (width):** The indicator grows and keeps its rounded ends.
+* **Tabs (size):** The indicator stretches to match each tab.
+* **Switch (width):** The pressed thumb stretches to keep its round ends.
+* **Toast (height):** Toasts shrink as their stack collapses.
+
+### Never Delay Input
+
+Controls respond on the first frame of a press. Don't hold an action until an animation finishes, and don't block the next interaction during an exit animation.
+
+**Do:** Use short transitions that respond on the first frame, such as the library's press feedback.
+
+```tsx
+<MotionDemo kind="press" />
+```
+
+**Don't:** Make the reader wait for an animation to finish before they can act.
+
+```tsx
+<MotionDemo kind="slow" />
+```
+
+## Authoring Motion
+
+Set each curve and duration by its token, and pair each transition with a reduced-motion override that removes movement and keeps color changes.
+
+```tsx
+import { style } from '@tempoxyz/ds'
+
+namespace styles {
+  export const row = style({
+    transitionDuration: '160',
+    transitionProperty: 'background-color, scale',
+    transitionTimingFunction: 'snappy',
+    selectors: {
+      '&:active': { scale: 'press' },
+      '&:hover': { backgroundColor: 'container.regular' },
+    },
+    '@media (prefers-reduced-motion: reduce)': {
+      transitionProperty: 'background-color',
+      selectors: { '&:active': { scale: 'none !custom' } },
+    },
+  })
+}
+```
+
+* **Durations (transitionDuration):** Name a duration in ms, such as `'160'`.
+* **Curves (transitionTimingFunction):** Name a curve, such as `'snappy'`.
+* **Keyframes (vars.ease):** A keyframe shorthand reads its curve from `vars`.
+
+## Reduced Motion
+
+When the system asks for reduced motion, components remove movement and scaling, and keep instant changes or brief opacity fades. Apply the same rule in your own styles, and honor Reduce Motion on iOS and Android.
+
+### What Components Change
+
+* **Pressable Controls:** Buttons, surfaces, and other pressable controls stop scaling and keep their color transitions.
+* **Overlays:** Popovers, menus, dialogs, and toasts fade in place, including the narrow-screen dialog sheet.
+* **Moving Indicators:** The tabs indicator and the switch thumb jump straight to their final position.
+* **Loading Indicators:** Spinners stop rotating, skeletons stop their sweep, and loading dots stop pulsing.
+* **Feedback:** [CopyButton](../components/copy-button.md) skips its pop, and invalid fields skip their nudge.
+
+## Accessibility
+
+[Accessibility](accessibility.md#motion) sets the limits for flashing and for content that moves on its own.
+
+* **Never Motion Alone (Field.Error):** Never convey information through motion alone. Pair a nudge on an invalid field with an error message.
+
+## Related
+
+[Loading](../patterns/loading.md)
+
+Covers spinners, skeletons, and progress.
+
+[Feedback and Status](../patterns/feedback-and-status.md)
+
+Covers toasts and confirmations.
+
+[Accessibility](accessibility.md)
+
+Covers reduced motion and other preferences.