@tempoxyz/ds 0.3.10 → 0.3.13

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

@@ -0,0 +1,377 @@
+# Accessibility
+
+The accessibility baseline for every Tempo component, and what you still own.
+
+## Overview
+
+Tempo products target [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA on Web, in light and dark schemes, and follow the platform guidelines on iOS and Android. A screen conforms only when every part does, so one unlabelled button fails the page.
+
+Components render native elements, follow the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/), manage focus, and announce changes. You own names, content, page structure, composition, and testing. Rules below link their success criteria (SC).
+
+## Color and Contrast
+
+Every foreground and background pair meets these ratios in both schemes, and [Color](color.md#contrast) lists the pairs that pass.
+
+* **Body Text (4.5:1):** For readable text, such as `content.primary` or `content.secondary` ([SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)).
+* **Large Text (3:1):** For large text, at least 24px in regular weight or 18.66px in bold.
+* **Non-Text Contrast (3:1):** For control borders, focus outlines, and meaningful graphics such as status icons ([SC 1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)).
+* **Exempt Content:** Logos, decorative graphics, and disabled controls, which must still look disabled.
+
+### Never Use Color Alone
+
+Pair color with text, an icon, or a shape ([SC 1.4.1](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)), as [Color](color.md#never-use-color-alone) shows.
+
+* **Statuses:** Pair each status color with an icon and a label.
+* **Errors:** Pair the invalid fill with an error message.
+* **Selection:** Mark a selected item with a check or indicator.
+* **Links:** Underline links that sit in body text.
+
+## Keyboard and Focus
+
+Every action works with the keyboard alone, with no timing requirement ([SC 2.1.1](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html)), and focus never stays in a region the keyboard cannot leave ([SC 2.1.2](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html)). Modal overlays are the exception, and Escape closes them.
+
+### Focus Order
+
+Focus follows the reading order ([SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html)).
+
+* **Match the Visual Order:** Keep the DOM in reading order. Don't reorder content with CSS.
+* **Avoid Positive Tabindex (tabindex):** Never use a positive value. Use `-1` only on an element you focus with a script.
+* **One Stop per Widget (Tab):** Tabs, radio groups, and menus take one stop. Arrow keys move within them.
+
+### Common Keys
+
+Components use the keys the Authoring Practices define for each widget.
+
+* **Move Between Controls (Tab and Shift+Tab):** Moves focus to the next or previous control in the tab order.
+* **Activate or Submit (Enter):** Activates a button or a link, and submits a form from a text field.
+* **Activate or Toggle (Space):** Activates a button, and toggles a checkbox or a switch.
+* **Move Within a Widget (Arrow keys):** Move within tabs, radio groups, menus, listboxes, and calendar grids.
+* **Jump to the First or Last Item (Home and End):** Jump to the first or last item in a list or menu, or to either end of a slider.
+* **Close an Overlay (Escape):** Closes the open overlay, and returns focus to the control that opened it.
+
+### Shortcuts
+
+* **Reserved Keys:** Don't take over keys that browsers or assistive technology use.
+* **Single-Key Shortcuts:** Let the reader turn off or remap them, or limit them to a focused control ([SC 2.1.4](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html)).
+* **Show Shortcuts (Kbd):** Show them with [Kbd](../components/kbd.md), which reads modifiers by name, such as Command K.
+
+### Visible Focus
+
+Controls show an outline on keyboard focus ([SC 2.4.7](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html)).
+
+```tsx
+import { Button, Checkbox, Field, style, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Field.Root>
+        <Field.Label>Recipient</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control placeholder="0x…" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <Checkbox />
+          <Field.Label>Save as contact</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      <div {...styles.row()}>
+        <Button variant="secondary">Cancel</Button>
+        <Button>Continue</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ display: 'flex', gap: '12', justifyContent: 'flex-end' })
+
+  export const stack = style({
+    display: 'grid',
+    gap: '16',
+    maxWidth: '20rem !custom',
+    width: '100% !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Foundations/FocusVisible.tsx)
+
+* **Outline (border.focus):** Buttons, fields, and other standalone controls draw a 2px solid outline.
+* **Outline Contrast (3:1):** Measures 5.7:1 on the dark page, but 2.8:1 on the light page, below the minimum.
+* **Invalid Fields (border.negative):** An invalid field draws its focus outline in the negative border color.
+* **Keyboard Only (:focus-visible):** Shows for keyboard focus only, and stays hidden on a pointer press.
+* **Menus and Listboxes:** The highlighted item takes a tinted background instead of an outline.
+* **Keep the Outline:** Do not remove it with `outline: none`. A restyled control still needs one.
+* **Leave Room (2px offset):** Leave room for the outline. A parent with `overflow: hidden` can clip it.
+
+### Focus Not Obscured
+
+Never let sticky bars, banners, or toasts fully hide a focused control ([SC 2.4.11](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)).
+
+* **Sticky Bars (scroll-padding):** Set it on the scroll container to the height of sticky bars.
+* **Toasts:** Keep toasts clear of the next focused control. F6 reaches them, and focus pauses their timers.
+
+### Overlays
+
+Modal overlays, such as [Dialog](../components/dialog.md), [AlertDialog](../components/alert-dialog.md), and [Drawer](../components/drawer.md), manage focus from open to close. Anchored popups, such as [Popover](../components/popover.md), [Menu](../components/menu.md), and [Tooltip](../components/tooltip.md), follow their own rules.
+
+* **On Open:** Focus moves into the overlay, so the reader starts inside it.
+* **While Open (Tab and Shift+Tab):** Focus cycles within the overlay. The page behind is inert and locked. Escape closes it.
+* **On Close:** Focus returns to the control that opened it, so the reader keeps their place.
+* **Popover:** Moves focus inside without a trap, and the page behind stays interactive.
+* **Menu:** Returns focus to the trigger on Escape or an outside press, as [Popover](../components/popover.md) does.
+* **Tooltip:** Never moves focus. It opens on hover and keyboard focus, and Escape dismisses it.
+* **Removed Trigger:** If the trigger is gone on close, such as a deleted row, move focus to a logical place.
+
+## Screen Readers
+
+### Name, Role, and Value
+
+Every control exposes a name, a role, and its state ([SC 4.1.2](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html)). Components set the role and state, and you supply the name.
+
+* **Prefer Visible Labels:** Use a visible label where you can. Voice control users speak the visible text.
+* **Match the Label:** Start the accessible name with the visible label text ([SC 2.5.3](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html)).
+* **Use Aria-Label Sparingly (aria-label):** Use it only when a control has no visible text. Name the action.
+* **Leave the Role Out:** Don't put the role in the name. A screen reader already announces "button".
+
+### States and Values
+
+* **Loading (aria-busy):** A loading button sets it for you. Add an `aria-label` to a standalone spinner.
+* **Truncated Values (Hex):** Screen readers receive the full value behind the truncated text.
+* **Struck Amounts (strikethrough):** Screen readers skip the strike, so say in text that the amount is replaced.
+* **Tooltips (Tooltip):** Adds no ARIA to its trigger. Name the trigger itself, and keep essential content out.
+
+### Structure
+
+Screen reader users navigate by headings and landmarks ([SC 1.3.1](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html)).
+
+* **Title and H1 (h1):** Use one main heading per page, and a unique title that names it ([SC 2.4.2](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html)).
+* **Heading Levels:** Use headings in order, without skipping levels, and pick each level for the outline.
+* **Landmarks (main):** [AppShell](../components/app-shell.md) and [SidebarMenu](../components/sidebar-menu.md) render them. Layout primitives take one through `render`.
+* **Named Regions (aria-label):** Name tab lists and the sidebar, and give each landmark a distinct label.
+* **Skip Link:** If the sidebar holds many links, add a skip link to the main content.
+* **Lists and Tables (list):** Mark up lists as lists and tabular data as a [Table](../components/table.md), not as styled divs.
+
+### Status Messages
+
+A message that appears after page load needs a live region, which announces it without moving focus ([SC 4.1.3](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html)).
+
+* **Polite (polite):** Waits until the reader is idle. Use it for confirmations, progress, and result counts.
+* **Assertive (assertive):** Interrupts the reader. Use it only for a failure the reader must handle now.
+* **Render the Region First:** Render the region before its message, then update it. A new region can stay silent.
+* **Alert (intent):** Negative and warning alerts interrupt as alerts. Info and positive alerts announce politely.
+* **Toast (priority):** Announces politely. Set `'high'` only for urgent toasts, which interrupt.
+* **Banner (role):** Has no live region. Add `status` or `alert` when it appears after the page loads.
+
+## Forms
+
+### Labels and Instructions
+
+Label every field visibly, and state any format or requirement before the reader types ([SC 3.3.2](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html)).
+
+**Do:** Label every field with a visible `Field.Label`, with hints in `Field.Description`.
+
+```tsx
+/**
+ * Do example for "Labels and Instructions" on the Accessibility page.
+ * Label every field with a visible `Field.Label`, with hints in `Field.Description`.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Field.Root>
+        <Field.Label>Recipient</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control placeholder="0x…" />
+        </TextInput.Group>
+        <Field.Description>An address or contact name.</Field.Description>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '100% !custom', width: '16rem !custom' })
+}
+```
+
+**Don't:** Use a placeholder as the only label. It disappears on input.
+
+```tsx
+/**
+ * Don't example for "Labels and Instructions" on the Accessibility page.
+ * Don't use a placeholder as the only label. It disappears on input and sits below 4.5:1 contrast.
+ * @module
+ */
+import { style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Recipient" placeholder="Recipient address or contact" />
+      </TextInput.Group>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '100% !custom', width: '16rem !custom' })
+}
+```
+
+* **Linked Label (Field.Label):** [Field](../components/field.md) links the label to its control, which takes it as its name.
+* **Hints and Errors (aria-describedby):** `Field.Description` and a shown `Field.Error` read after the control's name.
+* **Required and Optional:** Mark required or optional fields in text, not by color or an asterisk alone.
+* **Group Related Controls (legend):** Group radios in a [Fieldset](../components/fieldset.md) whose legend asks one question.
+* **Autocomplete (autocomplete):** Set it on fields that collect personal data, such as email or name ([SC 1.3.5](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html)).
+
+### Errors
+
+* **Error Text:** Describe the error and its fix in text next to the field ([SC 3.3.1](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) and [SC 3.3.3](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html)).
+* **Review Before Payment:** Before an action that cannot be undone, such as a payment, show a review step ([SC 3.3.4](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html)).
+
+### Entry and Authentication
+
+* **Redundant Entry:** Fill in or offer information the reader already entered in this flow ([SC 3.3.7](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html)).
+* **Accessible Authentication (Paste):** Allow paste, passkeys, and password managers instead of a memory test ([SC 3.3.8](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html)).
+
+## Touch and Pointer
+
+### Target Size
+
+Every pointer target meets a minimum size ([SC 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)), and touch screens need larger targets.
+
+* **Minimum (24 by 24px):** Every pointer target on Web, in CSS pixels. Links inside text are exempt.
+* **Touch Screens (44 by 44):** Aim for this size on touch screens, including iOS and Android.
+* **Button (32 to 56px):** Every size meets the minimum. The large size meets the touch target.
+* **Checkbox and RadioGroup (36px):** The hit area around the indicator. Pair it with `Field.Label` so the label toggles it.
+* **Slider (24px):** The height of the interactive track, which meets the minimum target size.
+* **Smaller Targets:** Grow a small target, such as a row icon, or keep clear space around it.
+
+### Gestures and Dragging
+
+* **Dragging:** Offer a single-pointer alternative to each drag, such as a press on the track ([SC 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)).
+* **Gestures:** Provide a single tap alternative to multi-finger and swipe gestures ([SC 2.5.1](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html)).
+* **Pointer Cancellation:** Trigger actions on pointer up, so the reader can slide away to cancel ([SC 2.5.2](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html)).
+
+## Zoom and Reflow
+
+### Reflow
+
+Content reflows to a narrow viewport without loss and without scrolling in two directions ([SC 1.4.10](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)).
+
+* **Narrow Viewport (320px):** Reflow to this width, which a 1280px window reaches at 400% zoom.
+* **Text Resize (200%):** Text resizes to this size without loss of content or function ([SC 1.4.4](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html)).
+* **Columns:** Stack columns at narrow widths. Fitted grids, wrapping rows, and containers reflow by default.
+* **Long Values:** Wrap long values, or truncate them with a way to view and copy the full value.
+* **Wide Content:** Tables, code blocks, and charts may scroll horizontally inside their own container.
+
+### Text Spacing
+
+Content must survive these spacing overrides at once, without clipping or overlap ([SC 1.4.12](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)).
+
+* **Line Height (1.5):** A multiple of the font size, on every line.
+* **Paragraph Spacing (2):** A multiple of the font size, after paragraphs.
+* **Letter Spacing (0.12em):** Added between letters.
+* **Word Spacing (0.16em):** Added between words.
+
+**Do:** Size text containers with `min-height` and padding, so they grow with their content.
+
+```tsx
+<Surface
+  size="small"
+  style={{ letterSpacing: '0.12em', lineHeight: 1.5, minHeight: 40, width: 200 }}
+>
+  Alice sent you 25.00 USDC.
+</Surface>
+```
+
+**Don't:** Set a fixed `height` on a text container. Spacing overrides clip its text.
+
+```tsx
+<Surface
+  size="small"
+  style={{
+    height: 40,
+    letterSpacing: '0.12em',
+    lineHeight: 1.5,
+    overflow: 'hidden',
+    width: 200,
+  }}
+>
+  Alice sent you 25.00 USDC.
+</Surface>
+```
+
+## User Preferences
+
+* **Forced Colors (forced-colors):** In contrast themes, buttons and fields keep a system focus outline. Icons use text color.
+* **Text Size (rem):** Spacing scales with the default font size. Test with a larger one.
+
+## Motion
+
+[Motion](motion.md#reduced-motion) shows how to apply the reduced-motion preference to your own styles.
+
+* **Reduced Motion (prefers-reduced-motion):** Components remove movement and scaling, but keep color changes and brief fades.
+* **Moving Content (5 seconds):** Let the reader pause, stop, or hide anything that moves on its own for longer ([SC 2.2.2](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html)).
+* **Flashing (3 per second):** Never flash content more often than this, even for a short alert ([SC 2.3.1](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html)).
+
+## Content
+
+* **Link Text:** Describe the destination, even out of context ([SC 2.4.4](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html)). See [Writing Style](content/writing-style.md#links).
+* **Alt Text (alt):** Describe meaningful images, and leave it empty on decorative ones ([SC 1.1.1](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html)).
+* **Time Limits:** Announce a time limit before it starts, and let the reader extend it ([SC 2.2.1](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html)).
+* **Toast Actions (timeout: 0):** Offer a toast's action elsewhere too, or keep the toast open until dismissed.
+* **Page Language (lang):** Set the page language on the `<html>` element ([SC 3.1.1](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html)).
+
+## Testing
+
+Components run their tests in real Chromium at desktop and mobile widths, with real pointer and keyboard input, in both schemes and with reduced motion. Automated checks catch only some problems, so test each screen by hand.
+
+* **Automated Checks:** Run a checker on each screen, then confirm each result by hand.
+* **Keyboard:** Use every control by keyboard alone. Focus stays visible and never hides behind a sticky bar.
+* **Screen Reader (VoiceOver or NVDA):** Use VoiceOver with Safari and NVDA with Firefox or Chrome, and check each name and state.
+
+## Checklist
+
+Before you ship a screen, confirm each item.
+
+* **Structure:** One h1, headings in order, landmarks, and a DOM that matches the visual order.
+* **Keyboard:** Every action works by keyboard, without traps, and focus stays visible and returns on close.
+* **Names:** Visible field labels, named icon buttons, and links that make sense out of context.
+* **Messages:** Errors state the fix, and status messages announce without moving focus.
+* **Contrast:** Text at 4.5:1 and outlines at 3:1 in both schemes, with nothing shown by color alone.
+* **Zoom and Targets:** Works at 320px wide and 200% zoom, with 24px targets on Web and 44pt on mobile.
+* **Motion:** Respects reduced motion, and nothing flashes more than three times a second.
+* **Time:** Action toasts stay until dismissed, and sessions warn before they expire.
+
+## Related
+
+[Color](color.md)
+
+Covers contrast and color use.
+
+[Motion](motion.md)
+
+Covers reduced motion.
+
+[Forms](../patterns/forms.md)
+
+Covers labels and grouping.
+
+[Errors and Validation](../patterns/errors-and-validation.md)
+
+Covers writing and announcing errors.
+
+[Button](../components/button.md)
+
+Use for icon buttons and loading states.

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

@@ -0,0 +1,150 @@
+# Agents
+
+How coding agents read these docs and the source, and the rules they follow.
+
+## Overview
+
+Coding agents read the same guidance as people. This site serves every page as Markdown, and the library source documents every export, so an agent can work from the docs or from your codebase.
+
+The rules on this page turn that guidance into requirements for generated UI, and type checks and lint rules verify what a tool can check.
+
+## Point Your Agent at the Docs
+
+Give your agent one of these entry points.
+
+* **Agent Prompt:** The [Getting Started](../introduction/getting-started.md#agent-prompt) prompt points your agent at the home page, which returns the page index.
+* **Page Index (/llms.txt):** [The index](/llms.txt) lists every page in sidebar order, with its Markdown link and description.
+* **Full Text (/llms-full.txt):** [One file](/llms-full.txt) holds every page's Markdown, each after a `---` line and a `Source:` URL.
+* **Copy Page:** On wide screens, Copy page copies the page's Markdown, and View markdown opens it.
+* **In the Package (dist/docs):** The package ships every page's Markdown for its version, with an agent guide and an index for each system.
+
+### Markdown Twins
+
+Every page has a Markdown twin. The page URL returns the twin or the HTML page, depending on the request.
+
+```sh
+curl https://ds.tehq.dev/docs/components/button
+```
+
+* **Markdown Path:** A page path that ends in `.md` returns the twin, such as `/docs/components/button.md`.
+* **Terminal Clients:** Requests from curl, Wget, HTTPie, and xh receive the twin at the page URL.
+* **Agents and Crawlers:** Requests from a known AI agent or crawler receive the twin at the page URL.
+* **Accept Header:** Ranking `text/markdown` or `text/plain` at or above `text/html` returns the twin.
+* **Search and Previews:** Search engine crawlers and link previews still receive the HTML page.
+* **Canonical Link:** Each Markdown response carries a canonical `Link` header to the HTML page.
+
+### What Changes in Markdown
+
+A twin keeps the page's text, headings, and tables, and turns interactive parts into plain text.
+
+* **Do and Don't:** Each Do and Don't card becomes a plain paragraph in the twin, starting with **Do:** or **Don't:**.
+* **Live Examples (tsx):** Each live example becomes a code block with its full source and a link to the example.
+* **Source Links:** Component pages link to the source on GitHub, whose TSDoc documents every prop.
+* **Setup Options:** Each setup option on Getting Started takes its own heading, so the agent reads every one.
+
+## Documentation in the Source
+
+Each public component and part carries TSDoc with its purpose, accessibility behavior, and a short example, so an agent in your codebase reads it without fetching this site. Check the type declarations too, since prop and default coverage is still growing.
+
+```tsx
+/**
+ * An inline message tinted by `intent`. The `negative` and `warning`
+ * intents render `role="alert"` and interrupt screen readers.
+ */
+export function Alert(props: Alert.Props) {}
+```
+
+## Rules for Generating Tempo UI
+
+These rules are requirements, and so are the Guidelines, Content, and Accessibility sections of every page. If a request conflicts with a guideline, follow the request and point out the conflict.
+
+### Use Library Components First
+
+* **Catalog First:** Check the [Components](../components.md) overview, which compares similar ones, before you write markup.
+* **Intent First:** Choose each component by the job of its content, as [Building From Intent](intent.md) describes, not by the old markup.
+* **Public Entrypoints:** Import `@tempoxyz/ds` on Web and `@tempoxyz/ds/mobile` in React Native, with icons from `/icons`.
+* **No Rebuilds:** Don't rebuild a library component or swap in a raw Base UI primitive or another library.
+* **Named Parts:** Build larger components from their named parts, such as `Dialog.Root` and `Dialog.Title`.
+
+### Style With Tokens
+
+* **Style Definitions:** Style your own markup with `style` and `variants`, grouped in a `namespace styles` block.
+* **Tokens:** Set colors, spacing, type, and radii with tokens, such as `content.primary` and `'24'`.
+* **Custom Values:** Mark the rare literal that no token fits with `!custom`, as in `'24rem !custom'`.
+* **One Styling System:** Don't add utility classes or a separate stylesheet to UI built with the library.
+* **Variable Scopes:** Components inherit variables, so apply `vars()` only to override values or fix a color scheme.
+
+### Use Only Documented APIs
+
+* **Documented Props:** Use only the props, parts, and values that a component page or its TSDoc documents.
+* **Missing Pieces:** Build a missing variant or token locally with `style`, and flag it for a [proposal](../introduction/faq.md#how-do-i-request-a-component-variant-or-token).
+* **Installed Package:** Don't patch the installed package or target the class names that it generates.
+
+### Follow the Guidelines
+
+* **Whole Pages:** Read a component's whole page before you use it, not only its Examples section.
+* **Patterns:** Apply the foundations and patterns that fit, such as [Payments](../patterns/payments.md) and [Blockchain Values](../patterns/blockchain-values.md).
+* **Native Semantics:** Keep native semantics, and meet every item on the [Accessibility](accessibility.md#checklist) checklist.
+
+### Write Copy to the Content Guidelines
+
+* **Labels and Terms:** Use sentence case and verb-first button labels, as [Writing Style](content/writing-style.md#write-labels) describes.
+* **Amounts and Addresses:** Format amounts with [Amount](../components/amount.md) and a `currency` or `symbol`, and addresses and hashes with [Hex](../components/hex.md).
+* **Errors:** Write error messages that state the fix, as [Writing Style](content/writing-style.md#write-messages) describes.
+
+## Checks
+
+If a tool can check a rule, run it as a check.
+
+* **Types (tsc):** Token names are typed, so an unknown token fails to compile.
+* **Lint (@tempoxyz/ds/oxlint):** Checks styles, imports, accessible names, and hand-built components, as [Linter](linter.md) lists.
+
+## Add Rules to Your Project
+
+Add instructions like these to your project's AGENTS.md or CLAUDE.md file, so every agent session starts from the docs.
+
+```md title="AGENTS.md"
+## UI
+
+- Build UI with Tempo Design System: `@tempoxyz/ds` on web, `@tempoxyz/ds/mobile` in React Native.
+- Read https://ds.tehq.dev/llms.txt first. Before using a component, read its page as Markdown, such as https://ds.tehq.dev/docs/components/button.md.
+- Treat each page's Guidelines, Content, and Accessibility sections as requirements.
+- Choose each component by what its content means, not by the markup it replaces. Read https://ds.tehq.dev/docs/foundations/intent.md before you port a screen.
+- Style with `style` and TDS tokens. Don't hardcode colors or spacing.
+- Write interface copy with the Content foundations, such as Writing Style.
+```
+
+## Writing for Agents
+
+Keep documentation readable for both audiences.
+
+* **Title and Description:** Start each page with a title and a one-sentence description of the page.
+* **Shared Headings:** Use the same headings across pages, such as Overview, Guidelines, and Accessibility.
+* **One Rule per Sentence:** Put each rule in its own sentence, so an agent can quote it on its own.
+* **Do and Don't Cards:** Use Do and Don't cards for guidance, so their verdict survives in Markdown.
+
+## Related
+
+[Getting Started](../introduction/getting-started.md)
+
+Covers setup and the agent prompt.
+
+[FAQ](../introduction/faq.md)
+
+Covers common questions.
+
+[Components](../components.md)
+
+Covers the component catalog.
+
+[Building From Intent](intent.md)
+
+Covers choosing a component by the job of its content.
+
+[Linter](linter.md)
+
+Covers the lint rules that check library use.
+
+[Voice](content/voice.md)
+
+Covers how Tempo UI copy sounds.