@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/foundations/linter.md

@@ -0,0 +1,296 @@
+# 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.

package/dist/docs/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](/docs/components/spinner), 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](/docs/components/text-input) or [OtpField](/docs/components/otp-field), and the 240ms pop of a [CopyButton](/docs/components/copy-button) 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](/docs/components/copy-button) skips its pop, and invalid fields skip their nudge.
+
+## Accessibility
+
+[Accessibility](/docs/foundations/accessibility#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](/docs/patterns/loading)
+
+Covers spinners, skeletons, and progress.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers toasts and confirmations.
+
+[Accessibility](/docs/foundations/accessibility)
+
+Covers reduced motion and other preferences.

package/dist/docs/foundations/radius-and-padding.md

@@ -0,0 +1,86 @@
+# Radius and Padding
+
+How corner radius and padding pair, from fields to modals.
+
+## Overview
+
+Corners in Tempo are squircles that ease into each edge. Each kind of element has its own radius, from fields and buttons up to modals, and the radius stays the same at every size of that element.
+
+Padding keeps content clear of the curve. Boxes and modals pad by their own radius, and corners step down the scale as layers nest.
+
+## Scale
+
+* **Fields, Buttons, and Alerts (xs):** A 12px corner at every size, padded by at least 16px.
+* **Boxes and Tiles (sm):** A 16px corner, padded by 16px, as in a list group.
+* **Small Modals (md):** A 24px corner, padded by 24px, for one decision.
+* **Medium and Large Modals (lg):** A 32px corner, padded by 32px, for longer tasks.
+* **Pills (full):** Icon buttons, avatars, and token chips.
+
+**Do:** Pad a corner by at least its radius, so content sits clear of the curve.
+
+```tsx
+<RadiusDemo kind="padded" />
+```
+
+**Don't:** Pad a container by less than its radius.
+
+```tsx
+<RadiusDemo kind="cramped" />
+```
+
+## Squircles
+
+Every corner is a squircle where the browser supports it, and a round corner of the same radius everywhere else.
+
+* **Squircle (corner-shape):** Supporting browsers draw each radius token as a squircle.
+* **Fallback (border-radius):** Other browsers draw the same token as a round corner.
+* **Circles and Pills (full):** Full radius stays round, so circles keep their shape.
+
+To keep your own circle or pill round, set the round corner shape beside the full radius.
+
+```tsx
+import { style } from '@tempoxyz/ds'
+
+namespace styles {
+  export const badge = style({ borderRadius: 'full', cornerShape: 'round' })
+}
+```
+
+## Nested Corners
+
+A layer inside another takes a smaller radius: a modal at 32px holds boxes at 16px, which hold fields at 12px.
+
+**Do:** Step the radius down at each layer, from modal to box to field.
+
+```tsx
+<RadiusDemo kind="nested" />
+```
+
+**Don't:** Repeat the outer radius on the layers inside it.
+
+```tsx
+<RadiusDemo kind="repeated" />
+```
+
+## Corner Controls
+
+* **Close and Back Buttons (First line):** Align with the title beside them, not with the corner.
+
+## Bleed
+
+* **Edge-Aligned Controls (Up to the padding):** Lines a text button's label up with the content edge.
+* **Full-Bleed Content (Exactly the padding):** Lets rows and tables reach both edges of the box.
+
+## Related
+
+[Layout](/docs/foundations/layout)
+
+Covers the radius, spacing, and shadow scales.
+
+[Surface](/docs/components/surface)
+
+Use for padded boxes and cards.
+
+[Dialog](/docs/components/dialog)
+
+Use for modals.