@tempoxyz/ds 0.3.11 → 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/{foundations → product/foundations}/motion.md

@@ -17,7 +17,7 @@ Three ease-out curves cover interface motion, so each response starts at full sp
 * **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.
+* **Constant Rate (linear):** Continuous indicators only, such as [Spinner](../components/spinner.md), which would pulse with easing.
 
 ## Durations
 
@@ -57,7 +57,7 @@ Give every state change a transition, from hover and focus to checked, disabled,
 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.
+* **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
 
@@ -128,24 +128,24 @@ When the system asks for reduced motion, components remove movement and scaling,
 * **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.
+* **Feedback:** [CopyButton](../components/copy-button.md) 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.
+[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](/docs/patterns/loading)
+[Loading](../patterns/loading.md)
 
 Covers spinners, skeletons, and progress.
 
-[Feedback and Status](/docs/patterns/feedback-and-status)
+[Feedback and Status](../patterns/feedback-and-status.md)
 
 Covers toasts and confirmations.
 
-[Accessibility](/docs/foundations/accessibility)
+[Accessibility](accessibility.md)
 
 Covers reduced motion and other preferences.

package/dist/docs/{foundations → product/foundations}/radius-and-padding.md

@@ -73,14 +73,14 @@ A layer inside another takes a smaller radius: a modal at 32px holds boxes at 16
 
 ## Related
 
-[Layout](/docs/foundations/layout)
+[Layout](layout.md)
 
 Covers the radius, spacing, and shadow scales.
 
-[Surface](/docs/components/surface)
+[Surface](../components/surface.md)
 
 Use for padded boxes and cards.
 
-[Dialog](/docs/components/dialog)
+[Dialog](../components/dialog.md)
 
 Use for modals.

package/dist/docs/{foundations → product/foundations}/typography.md

@@ -32,7 +32,7 @@ Six sets cover the interface, from hero titles down to small labels.
 
 ### Display
 
-Hero titles and large amounts, in light and regular weights that let size carry the emphasis. [Amount](/docs/components/amount) uses display type at its largest size.
+Hero titles and large amounts, in light and regular weights that let size carry the emphasis. [Amount](../components/amount.md) uses display type at its largest size.
 
 * `display.d1`: 44px, weight 300, line height 41.8px
 * `display.d2`: 36px, weight 400, line height 34.2px
@@ -112,7 +112,7 @@ Keep headings in order. Choose the element by its place in the outline and the s
 </Field.Root>
 ```
 
-**Don't:** Use all caps or bold every line to create hierarchy. Write in [sentence case](/docs/foundations/content/writing-style#capitalization).
+**Don't:** Use all caps or bold every line to create hierarchy. Write in [sentence case](content/writing-style.md#capitalization).
 
 ```tsx
 <p>
@@ -132,7 +132,7 @@ Keep headings in order. Choose the element by its place in the outline and the s
 
 ### Use Tabular Figures for Numbers
 
-Tabular figures align digits in columns and keep live values from shifting. [Amount](/docs/components/amount), [NumberField](/docs/components/number-field), [Slider](/docs/components/slider), and numeric table cells already set them.
+Tabular figures align digits in columns and keep live values from shifting. [Amount](../components/amount.md), [NumberField](../components/number-field.md), [Slider](../components/slider.md), and numeric table cells already set them.
 
 **Do:** Align amounts with tabular figures, such as `Amount` with `align="right"`.
 
@@ -201,7 +201,7 @@ style({ fontVariantNumeric: 'tabular-nums !custom' })
 
 ### Use Monospace for Hashes and Code
 
-Set addresses, hashes, keys, and code in monospace, so similar characters stay distinct and equal-length values align. [Hex](/docs/components/hex), [Snippet](/docs/components/snippet), and [SecretValue](/docs/components/secret-value) apply it. Labels and prose stay out of it.
+Set addresses, hashes, keys, and code in monospace, so similar characters stay distinct and equal-length values align. [Hex](../components/hex.md), [Snippet](../components/snippet.md), and [SecretValue](../components/secret-value.md) apply it. Labels and prose stay out of it.
 
 **Do:** Set hashes in `mono.m1`, so they align and `I`, `l`, `0`, and `O` stay distinct.
 

package/dist/docs/{introduction → product/introduction}/faq.md

@@ -8,18 +8,19 @@ Common questions about building with, and contributing to, Tempo Design System.
 
 Choose the surface by the platform you ship to. The surfaces share a design language but not code, so don't import one from the other.
 
-| I am building...          | Surface | Import                |
-| ------------------------- | ------- | --------------------- |
-| A web application         | Web     | `@tempoxyz/ds`        |
-| A React Native mobile app | Mobile  | `@tempoxyz/ds/mobile` |
+| I am building...          | Surface   | Import                   |
+| ------------------------- | --------- | ------------------------ |
+| A web application         | Web       | `@tempoxyz/ds`           |
+| A React Native mobile app | Mobile    | `@tempoxyz/ds/mobile`    |
+| A marketing website       | Marketing | `@tempoxyz/ds/marketing` |
 
-Web components render DOM elements and compile with a Zyzz bundler plugin. Mobile components render React Native views and compile with Metro. [Getting Started](/docs/introduction/getting-started) shows each setup.
+Web components render DOM elements and compile with a Zyzz bundler plugin. Mobile components render React Native views and compile with Metro. [Getting Started](getting-started.md) shows each setup.
 
 ### Do I Need to Import a Stylesheet?
 
 No. The library publishes no stylesheet.
 
-* **Vite:** The [Vite plugin](/docs/introduction/getting-started#setup) emits the variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once. Each component emits its own rules, so a build carries only the styles it uses.
+* **Vite:** The [Vite plugin](getting-started.md#setup) emits the variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once. Each component emits its own rules, so a build carries only the styles it uses.
 * **Rollup, Webpack, and esbuild:** The adapters emit a generated `/zyzz.css` that you load once.
 * **Mobile:** Metro compiles library and app styles during the bundle.
 
@@ -29,7 +30,7 @@ The Zyzz plugin is the only supported web setup.
 
 Use `style` and `variants` from `@tempoxyz/ds` with TDS tokens, such as `content.primary`, `background.elevated`, `'24'`, and `body.b2`. Group the definitions in a `namespace styles` block.
 
-If your app needs its own tokens, extend `variables` in your own Zyzz config, as the Custom Variables setup in [Getting Started](/docs/introduction/getting-started#setup) shows.
+If your app needs its own tokens, extend `variables` in your own Zyzz config, as the Custom Variables setup in [Getting Started](getting-started.md#setup) shows.
 
 ## Components
 
@@ -61,7 +62,7 @@ If an issue already covers the proposal, reuse it. A proposal joins `@tempoxyz/d
 
 The library includes only components with a verified production family in Figma. Archived and experimental Figma components stay out until a production version exists.
 
-The [Components](/docs/components) overview lists what ships today. Sidebar pages marked 🚧 are not written yet.
+The [Components](../components.md) overview lists what ships today. Sidebar pages marked 🚧 are not written yet.
 
 ### Which Components Exist on Mobile?
 
@@ -69,21 +70,21 @@ The [Components](/docs/components) overview lists what ships today. Sidebar page
 
 | Mobile       | Web counterpart                                                                   |
 | ------------ | --------------------------------------------------------------------------------- |
-| `Avatar`     | [Avatar](/docs/components/avatar)                                                 |
-| `Badge`      | [Badge](/docs/components/badge)                                                   |
-| `Button`     | [Button](/docs/components/button)                                                 |
-| `CodeInput`  | [OtpField](/docs/components/otp-field)                                            |
-| `IconButton` | [Button](/docs/components/button) with `shape="icon"`                             |
-| `Skeleton`   | [Skeleton](/docs/components/skeleton)                                             |
-| `Spinner`    | [Spinner](/docs/components/spinner)                                               |
-| `TextButton` | [Button](/docs/components/button) with `variant="tertiary"`                       |
-| `TextInput`  | [TextInput](/docs/components/text-input) inside a [Field](/docs/components/field) |
-| `Toast`      | [Toast](/docs/components/toast)                                                   |
-| `Toggle`     | [Switch](/docs/components/switch)                                                 |
+| `Avatar`     | [Avatar](../components/avatar.md)                                                 |
+| `Badge`      | [Badge](../components/badge.md)                                                   |
+| `Button`     | [Button](../components/button.md)                                                 |
+| `CodeInput`  | [OtpField](../components/otp-field.md)                                            |
+| `IconButton` | [Button](../components/button.md) with `shape="icon"`                             |
+| `Skeleton`   | [Skeleton](../components/skeleton.md)                                             |
+| `Spinner`    | [Spinner](../components/spinner.md)                                               |
+| `TextButton` | [Button](../components/button.md) with `variant="tertiary"`                       |
+| `TextInput`  | [TextInput](../components/text-input.md) inside a [Field](../components/field.md) |
+| `Toast`      | [Toast](../components/toast.md)                                                   |
+| `Toggle`     | [Switch](../components/switch.md)                                                 |
 
 ### Do Web Components Work in Mobile Browsers?
 
-Yes. [Responsive Layout](/docs/patterns/responsive-layout) shows how to adapt a layout from a phone to a desktop.
+Yes. [Responsive Layout](../patterns/responsive-layout.md) shows how to adapt a layout from a phone to a desktop.
 
 ## Design
 
@@ -123,7 +124,7 @@ On narrower screens, use the GitHub link at the bottom of the sidebar.
 
 ### How Should Coding Agents Use These Docs?
 
-Every page has a Markdown twin, `/llms.txt` indexes them all, and the library documents each export in its source. [Agents](/docs/foundations/agents) lists the files and the rules an agent follows when it generates Tempo UI.
+Every page has a Markdown twin, `/llms.txt` indexes them all, and the library documents each export in its source. [Agents](../foundations/agents.md) lists the files and the rules an agent follows when it generates Tempo UI.
 
 ## License