# Tempo Design System
> Foundations, guidelines, and components for Tempo products.
---
Source: https://ds.tehq.dev/product/introduction/getting-started
# Getting Started
Install Tempo Design System and render your first component.
## Overview
Tempo Design System is the shared design language of Tempo products. `@tempoxyz/ds` ships it as components and variables for web and React Native.
The APIs accept only design system values. Zyzz compiles the components and your styles ahead of time for each platform.
## Agent Prompt
Paste this prompt into your coding agent:
Read ds.tehq.dev and help me build my project with Tempo Design System.
## Setup
### Install the Library
Install `@tempoxyz/ds` and its Zyzz peer.
```sh
npm install @tempoxyz/ds zyzz
```
### Choose Framework
Choose a compilation target and a variable mode:
* **TDS Variables (Quick):** Uses the components and variables as they ship.
* **Custom Variables (Advanced):** Extends the TDS variables with app tokens.
### Vite
### Configure Vite
Add Zyzz beside the existing framework plugin.
```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import { zyzz } from 'zyzz/vite'
export default defineConfig({
plugins: [zyzz()],
ssr: { noExternal: ['@tempoxyz/ds', 'zyzz'] },
})
```
Run the existing dev or build command. The plugin emits the TDS variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once, and each component emits its own rules. You import no stylesheet.
With `ssr.noExternal`, the plugin reads the library's contracts in a server build.
#### TDS Variables (Quick)
### Use a Component
Import components from `@tempoxyz/ds`. Style your own markup with TDS tokens through `style`.
```tsx title="Checkout.tsx"
import { Button, style } from '@tempoxyz/ds'
export function Checkout() {
return (
Ready to continue?
)
}
namespace styles {
export const card = style({
backgroundColor: 'background.elevated',
borderRadius: 'sm',
color: 'content.primary',
padding: '24',
typography: 'body.b2',
})
}
```
Tokens such as `content.primary`, `'24'`, and `body.b2` type-check against the TDS variables. Light and dark values follow the inherited `color-scheme`.
#### Custom Variables (Advanced)
### Define Config
Extend the TDS variables with app tokens, and export the bound helpers.
```ts title="zyzz.config.ts"
import { variables } from '@tempoxyz/ds'
import { Config, Vars } from 'zyzz'
export const { style, vars } = Config.create({
id: 'app',
vars: Vars.extend(variables, { spacing: { bleed: '-0.75rem' } }, { id: 'app/vars' }),
})
```
Place `zyzz.config.ts` at the root of the application source, such as `src/zyzz.config.ts`. The Vite plugin scans its directory for global styles.
### Use a Component
Apply `vars()` to the app root. Style your markup with the bound `style` helper, which accepts TDS and app tokens.
```tsx title="Checkout.tsx"
import { Button } from '@tempoxyz/ds'
import { style, vars } from './zyzz.config.js'
export function App() {
return (
)
}
function Checkout() {
return (
Ready to continue?
)
}
namespace styles {
export const card = style({
backgroundColor: 'background.elevated',
color: 'content.primary',
marginInline: 'bleed',
padding: '24',
})
}
```
### Other Bundlers
### Configure the Bundler
Add the matching unplugin adapter to the bundler configuration. Keep the existing TypeScript and JSX transforms.
```ts title="rollup.config.ts"
import { zyzz } from 'zyzz/unplugin'
const plugins = [zyzz.rollup()]
// Use zyzz.webpack() or zyzz.esbuild() for those bundlers.
```
Load the emitted stylesheet and script in the document. Adjust the paths to the deployment base.
```html title="index.html"
```
Run the existing build command. [Bundler Setup](https://zyzz.style/docs/api/unplugin) lists the configuration for each bundler.
#### TDS Variables (Quick)
### Use a Component
Import components from `@tempoxyz/ds`. Style your own markup with TDS tokens through `style`.
```tsx title="Checkout.tsx"
import { Button, style } from '@tempoxyz/ds'
export function Checkout() {
return (
Ready to continue?
)
}
namespace styles {
export const card = style({
backgroundColor: 'background.elevated',
borderRadius: 'sm',
color: 'content.primary',
padding: '24',
typography: 'body.b2',
})
}
```
Tokens such as `content.primary`, `'24'`, and `body.b2` type-check against the TDS variables. Light and dark values follow the inherited `color-scheme`.
#### Custom Variables (Advanced)
### Define Config
Extend the TDS variables with app tokens, and export the bound helpers.
```ts title="zyzz.config.ts"
import { variables } from '@tempoxyz/ds'
import { Config, Vars } from 'zyzz'
export const { style, vars } = Config.create({
id: 'app',
vars: Vars.extend(variables, { spacing: { bleed: '-0.75rem' } }, { id: 'app/vars' }),
})
```
### Use a Component
Apply `vars()` to the app root. Style your markup with the bound `style` helper, which accepts TDS and app tokens.
```tsx title="Checkout.tsx"
import { Button } from '@tempoxyz/ds'
import { style, vars } from './zyzz.config.js'
export function App() {
return (
)
}
function Checkout() {
return (
Ready to continue?
)
}
namespace styles {
export const card = style({
backgroundColor: 'background.elevated',
color: 'content.primary',
marginInline: 'bleed',
padding: '24',
})
}
```
### React Native
### Configure Metro
Install the React Native peers, then wrap the Expo Metro configuration with Zyzz. Keep the existing transformer and Expo settings.
```sh
npx expo install expo-haptics react-native-reanimated react-native-svg react-native-worklets
```
```ts title="metro.config.ts"
import { getDefaultConfig } from 'expo/metro-config'
import { zyzz } from 'zyzz/metro'
export default zyzz(getDefaultConfig(import.meta.dirname), {
fonts: { 'HB Set v0.96': 'HBSet', Inter: 'Inter', 'JetBrains Mono': 'JetBrainsMono' },
units: { px: 1, rem: 16 },
})
```
`fonts` maps each Figma family to a font that your app registers. The library bundles no font files. To preview with iOS system fonts, map a family to `System`.
#### TDS Variables (Quick)
### Use a Component
Render components from `@tempoxyz/ds/mobile` below a `Provider` at the app root. Styles resolve against the nearest `Provider` above them.
```tsx title="App.tsx"
import { Button, Provider, style } from '@tempoxyz/ds/mobile'
import { Text, View } from 'react-native'
export function App() {
return (
)
}
function Checkout() {
return (
Ready to continue?
)
}
namespace styles {
export const card = style({
backgroundColor: 'background.elevated',
gap: '12',
paddingHorizontal: '20',
paddingVertical: '16',
})
export const label = style({ color: 'content.primary', typography: 'body.b2' })
}
```
`colorScheme="system"` follows the device setting. To override it, pass `light` or `dark`.
#### Custom Variables (Advanced)
### Define Config
Define app tokens in sets named `base` and `inverse`. Every Zyzz config reads the set that `Provider` selects. Reference TDS values through `variables` and `inverse`.
```ts title="zyzz.config.ts"
import { inverse as tdsInverse, variables } from '@tempoxyz/ds/mobile'
import { Vars } from 'zyzz'
import { defineConfig } from 'zyzz/react-native'
export const base = Vars.define({
color: {
caption: { light: variables.color.content.secondary, dark: variables.color.content.secondary },
},
})
export const inverse = Vars.extend(base, {
color: {
caption: {
light: tdsInverse.color.content.secondary,
dark: tdsInverse.color.content.secondary,
},
},
})
export const { style } = defineConfig({ defaultVars: 'base', id: 'app', vars: { base, inverse } })
```
Zyzz extensions only replace existing tokens. Put app tokens in your own sets, not in extensions of the TDS sets.
### Use a Component
Render TDS components below a `Provider`. Style your own elements with the bound `style` helper.
```tsx title="App.tsx"
import { Button, Provider } from '@tempoxyz/ds/mobile'
import { Text, View } from 'react-native'
import { style } from './zyzz.config.js'
export function App() {
return (
Ready to continue?
)
}
namespace styles {
export const caption = style({ color: 'caption' })
}
```
## Next Steps
[Build a Layout](/docs/components/app-shell)
Place a sticky sidebar beside the main content column.
[Trigger Actions](/docs/components/button)
Submit forms, send payments, and run other actions.
[Collect TextInput](/docs/components/field)
Link labels, descriptions, and errors to form controls.
[Show Feedback](/docs/components/toast)
Confirm results with brief notifications.
---
Source: https://ds.tehq.dev/product/introduction/faq
# FAQ
Common questions about building with, and contributing to, Tempo Design System.
## Getting Started
### Which Surface Should I Use?
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` |
| 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.
### 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.
* **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.
The Zyzz plugin is the only supported web setup.
### How Do I Style My Own Markup?
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.
## Components
### Can I Change How a Component Looks?
Use the component's props first, such as `variant` and `size`.
* **Web:** Components accept `className` and `style`, and keep your classes beside their own.
* **Mobile:** Components accept React Native `style`. Import variables from `@tempoxyz/ds/mobile`.
If you need a token the library does not have, extend `variables` as [How Do I Style My Own Markup?](#how-do-i-style-my-own-markup) shows.
### What If the Library Doesn't Have the Component I Need?
Build it in your app from library components and `style`, with TDS tokens. Keep that code in your app. If other products need it too, propose it for the library.
### How Do I Request a Component, Variant, or Token?
Open an issue in the Design System project in Linear. Include:
* The use case.
* The proposed contract, such as props, variants, or token names.
* Links to the relevant Figma designs.
* Consumer code or a pull request that shows the need.
If an issue already covers the proposal, reuse it. A proposal joins `@tempoxyz/ds` after designer approval and an approved Figma definition.
### Why Isn't a Figma Component in the Library?
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.
### Which Components Exist on Mobile?
`@tempoxyz/ds/mobile` has a smaller set, and some names differ from web.
| 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) |
### 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.
## Design
### How Do Light and Dark Schemes Work?
Every color has a light and a dark value, so you write each color once.
* **Web:** Values follow the inherited CSS `color-scheme`. Set `color-scheme: light dark` on the root to follow the system, or apply `vars({ colorScheme: 'dark' })` to fix one region.
* **Mobile:** `Provider colorScheme="system"` follows the device setting. To override it, pass `light` or `dark`. To render a subtree with inverse variables, pass `vars="inverse"`.
The library does not store a scheme preference. If your app offers a theme setting, persist the choice yourself.
### Which Is Right When Figma and Code Disagree?
Figma is the design reference. Variables, icons, and components are maintained by hand, so the two can drift.
If a component does not match its production Figma design, use Report issue on its page and include the Figma link. If you need the change before the library has it, keep the implementation in your app.
### Where Are the Figma Files?
The Figma files define every variable, icon, and component:
* [TPDS 1.0 Platform](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs/TPDS-1.0-Platform) for Web variables and components
* [TDS Platform](https://www.figma.com/design/pcO4NIuw8wx9U2nGJOcjzE) for Web icons
* [TDS App](https://www.figma.com/design/8iu5856rBEI3pnZ6YaIBgw) for Mobile, whose families the mobile components implement
## Docs
### How Do I Report a Docs Issue?
On wide screens, On this page includes two actions:
* **Report issue:** Opens a GitHub issue titled with the page name and its path.
* **Edit page:** Opens the MDX source of the page on GitHub.
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.
## License
### How Is the Library Licensed?
The library is open source under the [MIT license](https://github.com/tempoxyz/ds/blob/main/LICENSE-MIT).
---
Source: https://ds.tehq.dev/product/foundations/color
# Color
Color tokens for text, surfaces, borders, and status, with contrast rules.
## Overview
Color in Tempo is mostly black and white. Text, fills, and edges are neutrals at different strengths, so a screen reads through contrast and hierarchy rather than hue. A white card on a light gray page, black text, and one black primary action carry most of the interface.
Hue is the exception. Green, orange, and red report status in alerts, banners, and field states, and never decorate. Blue and violet mark tips and announcements.
Every color is a token named for its role. Backgrounds and containers fill, content colors text and icons, and lines and borders draw edges. Each token holds a light and a dark value, so one token works in both schemes.
## Scales
Scales hold the raw colors that tokens draw from. Use a scale step directly only for charts and categories.
### Neutral
| TokenLogo | Value |
| --- | --- |
| `neutral.000` | `#fff` |
| `neutral.003` | `#f7f7f7` |
| `neutral.004` | `#f5f5f5` |
| `neutral.006` | `#f0f0f0` |
| `neutral.008` | `#ebebeb` |
| `neutral.012` | `#e0e0e0` |
| `neutral.016` | `#d6d6d6` |
| `neutral.020` | `#ccc` |
| `neutral.024` | `#c2c2c2` |
| `neutral.028` | `#b8b8b8` |
| `neutral.032` | `#adadad` |
| `neutral.036` | `#a3a3a3` |
| `neutral.040` | `#999` |
| `neutral.044` | `#8f8f8f` |
| `neutral.048` | `#858585` |
| `neutral.052` | `#7a7a7a` |
| `neutral.056` | `#707070` |
| `neutral.060` | `#666` |
| `neutral.064` | `#5c5c5c` |
| `neutral.068` | `#525252` |
| `neutral.072` | `#474747` |
| `neutral.076` | `#3d3d3d` |
| `neutral.080` | `#333` |
| `neutral.084` | `#292929` |
| `neutral.088` | `#1f1f1f` |
| `neutral.092` | `#141414` |
| `neutral.096` | `#0a0a0a` |
| `neutral.100` | `#000` |
Each step names a percentage of black, from white to black.
### Shade and Tint
| TokenLogo | Value |
| --- | --- |
| `neutral.shade.000` | `#00000000` |
| `neutral.shade.003` | `#00000008` |
| `neutral.shade.004` | `#0000000a` |
| `neutral.shade.008` | `#00000014` |
| `neutral.shade.012` | `#0000001f` |
| `neutral.shade.016` | `#00000029` |
| `neutral.shade.020` | `#00000033` |
| `neutral.shade.032` | `#00000052` |
| `neutral.shade.040` | `#00000066` |
| `neutral.shade.056` | `#0000008f` |
| `neutral.shade.060` | `#00000099` |
| `neutral.shade.080` | `#000000cc` |
| TokenLogo | Value |
| --- | --- |
| `neutral.tint.000` | `#ffffff00` |
| `neutral.tint.008` | `#ffffff14` |
| `neutral.tint.012` | `#ffffff1f` |
| `neutral.tint.016` | `#ffffff29` |
| `neutral.tint.020` | `#ffffff33` |
| `neutral.tint.024` | `#ffffff3d` |
| `neutral.tint.040` | `#ffffff66` |
| `neutral.tint.048` | `#ffffff7a` |
| `neutral.tint.052` | `#ffffff85` |
| `neutral.tint.056` | `#ffffff8f` |
| `neutral.tint.064` | `#ffffffa3` |
| `neutral.tint.080` | `#ffffffcc` |
Shades are black and tints are white, at the opacity the step names, so a fill keeps the same relative step on any background.
### Accent
| Hue | Background | Foreground |
| --- | --- | --- |
| blue | `accent.blue.background` (`#4471ed` light, `#7498fb` dark) | `accent.blue.foreground` (`#3059d3` light, `#7498fb` dark) |
| cyan | `accent.cyan.background` (`#00aacb` light, `#48cce6` dark) | `accent.cyan.foreground` (`#056e85` light, `#48cce6` dark) |
| green | `accent.green.background` (`#13a963` light, `#59e5a4` dark) | `accent.green.foreground` (`#007441` light, `#59e5a4` dark) |
| magenta | `accent.magenta.background` (`#cc055b` light, `#e54088` dark) | `accent.magenta.foreground` (`#ba0352` light, `#e54088` dark) |
| olive | `accent.olive.background` (`#95b226` light, `#c4dc65` dark) | `accent.olive.foreground` (`#596d01` light, `#c4dc65` dark) |
| orange | `accent.orange.background` (`#e06f12` light, `#fa8e36` dark) | `accent.orange.foreground` (`#a14d04` light, `#fa8e36` dark) |
| purple | `accent.purple.background` (`#ba59dd` light, `#cf79ef` dark) | `accent.purple.foreground` (`#9835ba` light, `#cf79ef` dark) |
| red | `accent.red.background` (`#eb3417` light, `#f55c45` dark) | `accent.red.foreground` (`#bf1d00` light, `#f55c45` dark) |
| violet | `accent.violet.background` (`#7e59e4` light, `#9877f1` dark) | `accent.violet.foreground` (`#6f47d1` light, `#9877f1` dark) |
Each hue has a background, which switches with the scheme, and a foreground for accent text that stays readable on every surface.
## Backgrounds
Two backgrounds sit below every component, and a third fills small chips on a visual. Components on them take their fills, borders, and text from the tokens that follow.
* `background.primary` (`#f5f5f5` light, `#141414` dark): The page behind cards, tables, and the app shell.
* `background.elevated` (`#fff` light, `#1a1a1a` dark): Cards, dialogs, menus, and popovers above the page.
* `background.secondary` (`#fff` light, `#141414` dark): Badges and chips that sit on a visual or a tint.
## Containers
Containers fill components such as menu items, badges, and selected rows. They are translucent, so a fill keeps the same relative step on the page and on an elevated surface.
* `container.subtle` (`#00000008` light, `#ffffff14` dark): The faintest fill, such as a disabled field.
* `container.regular` (`#0000000a` light, `#ffffff14` dark): Secondary buttons, filled fields, and tags.
* `container.strong` (`#00000014` light, `#ffffff29` dark): Hovered and pressed controls, and slider tracks.
* `container.positive` (`rgb(19 169 99 / 0.08)` light, `rgb(89 229 164 / 0.16)` dark): Positive alerts and tags, and copied values.
* `container.warning` (`rgb(224 111 18 / 0.08)` light, `rgb(250 142 54 / 0.16)` dark): Warning alerts, banners, and tags.
* `container.negative` (`rgb(235 52 23 / 0.08)` light, `rgb(245 92 69 / 0.16)` dark): Negative alerts, banners, and tags.
## Borders
Lines outline edges and divide content, and borders mark focus and validation.
* `line.secondary` (`#00000014` light, `#ffffff14` dark): Dividers, table borders, and resting outlined fields.
* `line.primary` (`#00000029` light, `#ffffff3d` dark): Outlined fields on hover, and unchecked choices.
* `border.focus` (`#00000066` light, `#ffffff85` dark): The 2px outline that controls draw on keyboard focus.
* `border.positive` (`rgb(19 169 99 / 0.16)` light, `rgb(89 229 164 / 0.32)` dark): The ring around a field that passed validation.
* `border.warning` (`rgb(224 111 18 / 0.16)` light, `rgb(250 142 54 / 0.32)` dark): A ring that flags a field the reader should check.
* `border.negative` (`rgb(235 52 23 / 0.16)` light, `rgb(245 92 69 / 0.32)` dark): The ring around an invalid field, checkbox, or switch.
## Content
Content tokens color text and icons. Pick one by how much the reader needs it.
* `content.primary` (`#000` light, `#fff` dark): Titles, values, body text, and primary fills.
* `content.secondary` (`#0000008f` light, `#ffffffa3` dark): Descriptions, captions, table cells, and placeholders.
* `content.tertiary` (`#00000066` light, `#ffffff85` dark): Icons, chevrons, and separators beside a label.
* `content.subtle` (`#00000033` light, `#ffffff33` dark): Tracks and marks that carry no text, such as a gauge.
* `content.positive` (`#13a963` light, `#59e5a4` dark): Success text and icons, such as a confirmed payment.
* `content.warning` (`#e06f12` light, `#fa8e36` dark): Caution text and icons, such as a fee warning.
* `content.negative` (`#eb3417` light, `#f55c45` dark): Error text, field errors, and negative button fills.
## Materials and Scrims
Materials are translucent layers in five strengths, and scrims dim the page behind an overlay. No component uses them yet.
* `material.ultrathin` (`#00000014` light, `#ffffff29` dark): The lightest translucent layer.
* `material.thin` (`#00000033` light, `#ffffff3d` dark): A light translucent layer.
* `material.regular` (`#00000066` light, `#ffffff7a` dark): A translucent layer of medium strength.
* `material.thick` (`#00000099` light, `#ffffffa3` dark): A dense translucent layer.
* `material.ultrathick` (`#000000cc` light, `#ffffffcc` dark): The densest translucent layer.
* `scrim.regular` (`#00000029`): Dims the page behind an overlay, at 16% black.
* `scrim.strong` (`#00000052`): Dims the page further, at 32% black.
## Intents
Components that report status take an intent, not a hue, so a status looks the same everywhere. Choose the intent by the message. An [Alert](/docs/components/alert) tints its container and colors its indicator by intent.
* **Neutral (content.subtle):** Default states and features, such as a payment that is still pending.
* **Positive (content.positive):** Success, completion, and incoming funds, such as a confirmed payment.
* **Warning (content.warning):** A risk that the reader must know about before they confirm an action.
* **Negative (content.negative):** Errors, failures, and destructive actions, such as a payment that failed.
* **Tip (accent.blue.background):** Optional context, such as the token that pays the network fee for a payment.
* **Special (accent.violet.background):** A new feature to announce, such as a vault that earns on idle USDC balances.
Cyan, magenta, olive, and purple have no intent, so keep them for charts and categories.
## Guidelines
### Choose Tokens by Role
Pick the token that names the role, not a scale step that looks right in one scheme. Never write a raw color into product styles, and propose a token in the Design System project when none fits.
**Do:** Use tokens, which switch value with the scheme.
```tsx
/**
* Do example for "Choose Tokens by Job" on the Color page.
* Use tokens, which switch value with the scheme.
* @module
*/
import { style, variants } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Balance1,250.00 USDC
Balance1,250.00 USDC
)
}
namespace styles {
export const label = style({ color: 'content.secondary', typography: 'body.b3' })
export const panel = variants({
base: {
backgroundColor: 'background.elevated',
borderColor: 'line.secondary',
borderRadius: 'xs',
borderStyle: 'solid',
borderWidth: 'regular',
display: 'grid',
gap: '4',
padding: '16',
},
variants: {
scheme: {
dark: { colorScheme: 'dark !custom' },
light: { colorScheme: 'light !custom' },
},
},
})
export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '12' })
export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```
**Don't:** Fix a color that only passes in one scheme.
```tsx
/**
* Don't example for "Choose Tokens by Job" on the Color page.
* Don't fix a color that only passes in one scheme.
* @module
*/
import { style, variants } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Balance1,250.00 USDC
Balance1,250.00 USDC
)
}
namespace styles {
export const label = style({ color: '#666666 !custom', typography: 'body.b3' })
export const panel = variants({
base: {
backgroundColor: 'background.elevated',
borderColor: 'line.secondary',
borderRadius: 'xs',
borderStyle: 'solid',
borderWidth: 'regular',
display: 'grid',
gap: '4',
padding: '16',
},
variants: {
scheme: {
dark: { colorScheme: 'dark !custom' },
light: { colorScheme: 'light !custom' },
},
},
})
export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '12' })
export const value = style({ color: '#171717 !custom', typography: 'body.b1Strong' })
}
```
### Keep Text at Readable Contrast
Set text in the primary or secondary content color, since WCAG counts it as text. Field placeholders are the exception: they take the tertiary color, as the design draws them, below 4.5:1. Otherwise keep the tertiary color for glyphs, such as chevrons and separators.
**Do:** Set descriptions in `content.secondary`, which stays above 4.5:1 on both backgrounds.
```tsx
/**
* Do example for "Keep Text at Readable Contrast" on the Color page.
* Set descriptions in `content.secondary`, which stays above 4.5:1 on both backgrounds.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Network feePaid in PathUSD. Settles with the payment.
)
}
namespace styles {
export const description = style({ color: 'content.secondary', typography: 'body.b2' })
export const stack = style({ display: 'grid', gap: '4' })
export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```
**Don't:** Set text people need to read in `content.tertiary`.
```tsx
/**
* Don't example for "Keep Text at Readable Contrast" on the Color page.
* Don't set text people need to read in `content.tertiary`.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Network feePaid in PathUSD. Settles with the payment.
)
}
namespace styles {
export const description = style({ color: 'content.tertiary', typography: 'body.b2' })
export const stack = style({ display: 'grid', gap: '4' })
export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```
### Reserve Accents for Meaning
Blue marks information, green success, orange caution, and red errors and destructive actions. Focus and selection stay neutral.
**Do:** Use red for an error or a removal.
```tsx
This access key was revoked.
```
**Don't:** Use red to draw attention to a safe event.
```tsx
Your funds arrived.
```
### Use One Intent per Message
**Do:** Use a single warning for a single risk.
```tsx
This address has never received a payment from you.
```
**Don't:** Stack alerts of different intents for one risk.
```tsx
New address.Check the address.Payments cannot be reversed.
```
### Never Use Color Alone
Pair every status color with text or an icon. In charts, name each series in a label or a legend.
**Do:** Name each status in text beside its color.
```tsx
/** Do example for "Never Use Color Alone" on the Color page: name each status in text beside its color. @module */
import { Alert, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
ConfirmedPendingFailed
)
}
namespace styles {
export const stack = style({
display: 'flex',
flexDirection: 'column',
gap: '8',
width: '100% !custom',
})
}
```
**Don't:** Rely on colored dots to tell Confirmed from Failed.
```tsx
/**
* Don't example for "Never Use Color Alone" on the Color page.
* Don't rely on colored dots to tell Confirmed from Failed.
* @module
*/
import { style, variants } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const dot = variants({
base: { borderRadius: 'full', cornerShape: 'round', height: '12', width: '12' },
variants: {
intent: {
negative: { backgroundColor: 'content.negative' },
positive: { backgroundColor: 'content.positive' },
warning: { backgroundColor: 'content.warning' },
},
},
})
export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })
}
```
## Contrast
Tempo targets WCAG 2.2 AA in both schemes.
* **Body Text (4.5:1):** Body text against its background.
* **Large Text (3:1):** Text from 24px, or bold text from 18.66px.
* **Non-Text (3:1):** Focus outlines, state borders, and icons.
Each ratio lists light mode first. Several pairs fall below these targets.
* **Primary on Elevated (21:1 and 18.4:1):** `content.primary` on `background.elevated`. Passes for any text, in light and dark.
* **Secondary on Elevated (4.9:1 and 6.4:1):** `content.secondary` on `background.elevated`. Passes for body text, such as card descriptions.
* **Secondary on Page (4.8:1 and 6.5:1):** `content.secondary` on `background.primary`. Passes for body text, such as page captions.
* **Tertiary on Elevated (2.9:1 and 3.8:1):** `content.tertiary` glyphs, such as breadcrumb separators. Too faint for text in either scheme.
* **Status Text on Status Fill (2.8:1+ and 4.7:1+):** `content.positive`, `warning`, and `negative` on their containers. Below 4.5:1 in light mode.
* **Focus Outline (2.8:1 and 5.7:1):** The `border.focus` outline against the page. Below the 3:1 minimum in light mode.
* **Invalid Border (1.3:1 and 1.6:1):** The `border.negative` ring against a surface. Below 3:1, so pair it with `Field.Error` text.
Lines measure below 3:1, so they divide content but never identify a control alone. Disabled controls are exempt, but must still look disabled.
## Accessibility
* **Visible Focus (border.focus):** Components draw a 2px outline on keyboard focus. Don't replace it with a color change alone.
* **Forced Colors (forced-colors):** Fields and buttons swap their resting outline for a system color outline on keyboard focus.
## Related
[Typography](/docs/foundations/typography)
Covers text sizes that change contrast thresholds.
[Accessibility](/docs/foundations/accessibility)
Covers the full WCAG 2.2 AA checklist.
[Feedback and Status](/docs/patterns/feedback-and-status)
Covers choosing an intent.
[Banner](/docs/components/banner)
Use for status text on a status fill.
[Alert](/docs/components/alert)
Use for intent colors in context.
[Banner](/docs/components/banner)
Use for intent colors in context.
---
Source: https://ds.tehq.dev/product/foundations/layout
# Layout
Page structure, grid, spacing, radius, and elevation.
## Overview
Tempo pages are calm and orderly. Flat cards sit on a tinted page, line up on a twelve-column grid, and keep generous space between groups, so the content stands out more than its frame.
Space follows relationships. Elements sit close within a group, further apart between groups, and furthest apart between sections. As the screen widens, the margins grow and the sidebar opens, while the content keeps a comfortable width.
For page frames and width changes, see [Responsive Layout](/docs/patterns/responsive-layout).
## Page Structure
Every page shares one frame, which [App Shell](/docs/components/app-shell) provides.
* **Sidebar:** Navigation on the start edge, which moves into a drawer on small screens.
* **Top Bar:** The page title and its main action, in one bar above the content.
* **Content:** Cards, charts, and tables, arranged on the page grid below the bar.
## Grid
Wide pages divide into twelve columns. Each card, chart, and table takes a share of them, and every row keeps the same gutters. [Grid](/docs/components/grid) lays out the columns.
* **Summary Cards (3 of 12):** Key figures in a row of equal cards.
* **Chart and Panel (8 and 4):** A wide chart beside a narrow panel.
* **Tables (12 of 12):** Lists and tables across the full width.
* **Small Screens (phone):** Cards pair up, and panels stack.
## Spacing
Spacing comes from one scale of steps. Pick a step by how closely the elements relate: the closer the relationship, the smaller the gap.
* **Related Elements (4 to 8):** An icon and its label, or a label and its value.
* **Items and Fields (12 to 16):** Items in a list, fields in a form, and buttons.
* **Groups and Cards (24 to 32):** Groups within a section, such as cards in a grid.
* **Page Sections (40 to 64):** The sections of a page, such as a table.
## Radius
Larger elements get rounder corners, from fields at 12px to modals at 32px. [Radius and Padding](/docs/foundations/radius-and-padding) covers each role and its padding.
* `none`: `0rem`
* `3xs`: `calc(0.25rem * var(--tds-corner-scale, 1))`
* `2xs`: `calc(0.5rem * var(--tds-corner-scale, 1))`
* `xs`: `calc(0.75rem * var(--tds-corner-scale, 1))`
* `sm`: `calc(1rem * var(--tds-corner-scale, 1))`
* `md`: `calc(1.5rem * var(--tds-corner-scale, 1))`
* `lg`: `calc(2rem * var(--tds-corner-scale, 1))`
* `xl`: `calc(2.5rem * var(--tds-corner-scale, 1))`
* `2xl`: `calc(4rem * var(--tds-corner-scale, 1))`
* `full`: `62.4375rem`
## Elevation
Shadows mark layers that float above the page, and most surfaces need none. In dark mode, a layer lifts with a lighter surface rather than a deeper shadow.
* **Flat (none):** Cards and panels, which sit flat on the page.
* **Small (shadow.small):** Controls that lift off a track, such as a switch thumb.
* **Regular (shadow.regular):** Menus, toasts, and other popups over the page.
* **Large (shadow.large):** Dialogs and drawers, above the dimmed page.
## Widths
[Container](/docs/components/container) centers content at a maximum width, with side gutters that grow on larger screens. Pick its size by the content, not by the screen.
* **Narrow (48rem):** Forms, settings, and single-task flows.
* **Medium (64rem):** Detail pages, such as a transaction or an API key.
* **Wide (80rem):** The default, for dashboards, tables, and card grids.
* **Full (none):** Charts and canvases that manage their own width.
## Breakpoints
Design for the smallest screen first, then let content spread into more columns as space allows. Components change layout at the same widths, so a layout that shifts beside one should switch with it.
* **Phone (0 to 639px):** One column, with the sidebar in a drawer.
* **Tablet (640 to 1023px):** Two columns, where the content allows.
* **Desktop (1024px and up):** The sidebar opens, and grids gain columns.
Write a breakpoint as a query inside a style.
```tsx
import { style } from '@tempoxyz/ds'
namespace styles {
export const metrics = style({
display: 'grid',
gap: '16',
'@media >=768': { gridTemplateColumns: 'repeat(3, minmax(0, 1fr)) !custom' },
})
}
```
## Layout Primitives
Primitives arrange content without adding meaning. When a region needs meaning, render the primitive as a semantic element, such as a list or the main landmark.
* **Stack (gap 16):** [Stack](/docs/components/stack) spaces a vertical run, such as fields in a form.
* **Inline (gap 8):** [Inline](/docs/components/inline) spaces a horizontal run, such as actions or badges.
* **Grid (gap 24):** [Grid](/docs/components/grid) arranges similar items, such as metric tiles.
* **Container (size):** [Container](/docs/components/container) sets the page width and side gutters.
* **Inset (space):** [Inset](/docs/components/inset) pads a region without drawing a container.
* **Surface (size):** [Surface](/docs/components/surface) is a visible card that groups related content.
## Guidelines
### Space Siblings With Gap
Space siblings from their parent. Margins on each child collapse, double up when items reorder, and leave stray space after the last item.
**Do:** Space the items of a list from their parent.
```tsx
/**
* Do example for "Space Siblings With Gap" on the Layout page.
* Space the items of a list with `gap` on the parent.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Sent 25.00 USDC to 0x3c44…93bcReceived 120.00 USDCSent 8.50 USDC to 0x90f7…b906
)
}
namespace styles {
export const item = style({
backgroundColor: 'container.regular',
borderRadius: '2xs',
color: 'content.primary',
paddingBlock: '8',
paddingInline: '12',
typography: 'body.b2',
})
export const list = style({
borderColor: 'line.secondary',
borderRadius: 'xs',
borderStyle: 'dashed',
borderWidth: 'regular',
display: 'flex',
flexDirection: 'column',
gap: '12',
maxWidth: '100% !custom',
padding: '12',
width: '18rem !custom',
})
}
```
**Don't:** Add a margin to each child, which leaves space after the last one.
```tsx
/**
* Don't example for "Space Siblings With Gap" on the Layout page.
* Don't add a margin to each child, which leaves space after the last one.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Sent 25.00 USDC to 0x3c44…93bcReceived 120.00 USDCSent 8.50 USDC to 0x90f7…b906
)
}
namespace styles {
export const item = style({
backgroundColor: 'container.regular',
borderRadius: '2xs',
color: 'content.primary',
marginBottom: '12',
paddingBlock: '8',
paddingInline: '12',
typography: 'body.b2',
})
export const list = style({
borderColor: 'line.secondary',
borderRadius: 'xs',
borderStyle: 'dashed',
borderWidth: 'regular',
display: 'flex',
flexDirection: 'column',
maxWidth: '100% !custom',
padding: '12',
width: '18rem !custom',
})
}
```
### Group Related Content by Proximity
Put less space inside a group than between groups. A label sits close to its value, and separate pairs sit well apart, so they need no dividers.
**Do:** Keep each label close to its value and leave more space between pairs.
```tsx
/**
* Do example for "Group Related Content by Proximity" on the Layout page.
* Keep each label close to its value and leave more space between pairs.
* @module
*/
import { Stack, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Recipient0x3c44…93bcAmount250.00 PathUSDNetwork fee0.01 PathUSD
)
}
namespace styles {
export const label = style({ color: 'content.secondary', typography: 'body.b3' })
export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```
**Don't:** Space every line equally, which makes labels and values hard to pair.
```tsx
/**
* Don't example for "Group Related Content by Proximity" on the Layout page.
* Don't space every line equally, which makes labels and values hard to pair.
* @module
*/
import { Stack, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Recipient0x3c44…93bcAmount250.00 PathUSDNetwork fee0.01 PathUSD
)
}
namespace styles {
export const label = style({ color: 'content.secondary', typography: 'body.b3' })
export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```
### Keep Cards Flat
Separate a [Surface](/docs/components/surface) from the page with its lighter background, not a shadow. Keep shadows for content that floats over other content.
**Do:** Keep cards flat, and add a shadow only to the layer above them.
```tsx
```
**Don't:** Give every card a shadow.
```tsx
```
### Use One Surface per Group
**Do:** Use one surface with a title for one group.
```tsx
Balances120.00 USDC
```
**Don't:** Nest surfaces to create structure.
```tsx
120.00 USDC
```
### Size Containers by Content
Pick the narrowest [Container](/docs/components/container) that fits the content.
**Do:** Keep a form in a narrow container, so each field is as wide as its content needs.
```tsx
Recipient
```
**Don't:** Stretch a form across a wide page.
```tsx
```
### Let Collections Reflow
For cards and metric tiles, let the grid fit as many columns as the width allows. A fitted grid collapses to one column on a phone without extra breakpoints.
**Do:** Let a collection reflow to one column at 320px.
```tsx
```
**Don't:** Fix a column count that runs past a narrow screen.
```tsx
```
### Keep Source Order Visual Order
Don't reorder content visually. Keyboard focus and screen readers follow the source, so a reordered layout makes focus jump.
**Do:** Write elements in the order they appear, so focus moves left to right.
```tsx
/**
* Do example for "Keep Source Order Visual Order" on the Layout page.
* Write elements in the order they appear, so focus moves left to right.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
12
)
}
namespace styles {
export const item = style({
alignItems: 'center',
display: 'flex',
flexDirection: 'column',
gap: '8',
})
export const row = style({ alignItems: 'flex-end', display: 'flex', gap: '12' })
export const step = style({
alignItems: 'center',
backgroundColor: 'accent.blue.background',
borderRadius: 'full',
color: 'white !custom',
cornerShape: 'round',
display: 'inline-flex',
height: '20',
justifyContent: 'center',
typography: 'body.b3Strong',
width: '20',
})
}
```
**Don't:** Reverse the visual order, which makes focus jump backward.
```tsx
/**
* Don't example for "Keep Source Order Visual Order" on the Layout page.
* Don't reverse the visual order, which makes focus jump backward.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
12
)
}
namespace styles {
export const item = style({
alignItems: 'center',
display: 'flex',
flexDirection: 'column',
gap: '8',
})
export const row = style({
alignItems: 'flex-end',
display: 'flex',
flexDirection: 'row-reverse',
gap: '12',
justifyContent: 'flex-end',
})
export const step = style({
alignItems: 'center',
backgroundColor: 'accent.blue.background',
borderRadius: 'full',
color: 'white !custom',
cornerShape: 'round',
display: 'inline-flex',
height: '20',
justifyContent: 'center',
typography: 'body.b3Strong',
width: '20',
})
}
```
## Accessibility
* **Reflow (320px):** Content reflows without sideways scrolling, as fitted grids do by default.
* **Regions (render):** Primitives add no roles, so render regions as meaningful elements.
* **Text Size (200%):** Spacing grows with larger default text, so check layouts at 200%.
## Related
[Responsive Layout](/docs/patterns/responsive-layout)
Covers page frames and width changes.
[Stack](/docs/components/stack)
Use for arranging content.
[Inline](/docs/components/inline)
Use for arranging content.
[Grid](/docs/components/grid)
Use for arranging content.
[Container](/docs/components/container)
Use for width and padding.
[Inset](/docs/components/inset)
Use for width and padding.
[Surface](/docs/components/surface)
Use for cards.
[App Shell](/docs/components/app-shell)
Use for the application frame.
[Radius and Padding](/docs/foundations/radius-and-padding)
Covers how padding pairs with each radius.
---
Source: https://ds.tehq.dev/product/foundations/radius-and-padding
# 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
```
**Don't:** Pad a container by less than its radius.
```tsx
```
## 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
```
**Don't:** Repeat the outer radius on the layers inside it.
```tsx
```
## 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.
---
Source: https://ds.tehq.dev/product/foundations/typography
# Typography
Type sets for titles, body text, values, and code.
## Overview
Type in Tempo is quiet and direct. Inter carries the interface and its numbers, Pilat gives titles their character, and JetBrains Mono keeps addresses and code legible.
Each set bundles a family, size, weight, line height, and tracking into one token, so you choose a role instead of tuning properties. A set keeps one size at every screen width.
```tsx
import { style } from '@tempoxyz/ds'
namespace styles {
export const title = style({ typography: 'heading.h2' })
export const body = style({ color: 'content.secondary', typography: 'body.b2' })
}
```
## Typefaces
Three bundled families cover every set.
* **Inter (100 to 900):** Body text, labels, buttons, table cells, and numbers.
* **Pilat (100 to 900):** Page, dialog, section, card, and hero titles only.
* **JetBrains Mono (400 to 700):** Addresses, hashes, keys, and code.
## Type Sets
Six sets cover the interface, from hero titles down to small labels.
### Display
Hero titles in Pilat, in light and regular weights that let size carry the emphasis.
* `display.d1`: Pilat, 44px, weight 300, line height 41.8px
* `display.d2`: Pilat, 36px, weight 400, line height 34.2px
### Value
Large readings in Inter, such as a balance, with tight tracking so the digits read as one figure.
* `value.v1`: Inter, 80px, weight 400, line height normal
* `value.v2`: Inter, 52px, weight 400, line height normal
* `value.v3`: Inter, 40px, weight 400, line height normal
### Heading
Page, dialog, section, and card titles, in Pilat at a medium weight. Only the heading and display sets use Pilat. Tracking tightens as the size grows, so large titles stay compact.
* `heading.h1`: Pilat, 32px, weight 500, line height 36.8px
* `heading.h2`: Pilat, 24px, weight 500, line height 27.6px
* `heading.h3`: Pilat, 20px, weight 500, line height 23px
* `heading.h4`: Pilat, 18px, weight 500, line height 20.7px
### Body
Paragraphs, descriptions, labels, buttons, and table cells, in a regular and a strong weight at each size.
* `body.b1`: Inter, 16px, weight 400, line height 22px
* `body.b1Strong`: Inter, 16px, weight 500, line height 22px
* `body.b2`: Inter, 14px, weight 400, line height 20px
* `body.b2Strong`: Inter, 14px, weight 500, line height 20px
* `body.b3`: Inter, 12px, weight 400, line height 16px
* `body.b3Strong`: Inter, 12px, weight 500, line height 16px
* **Weight (400 and 500):** Strong sets add emphasis without a larger size.
* **Default (body.b1):** The page default, a size down on dense screens.
* **Inputs (body.b1):** Large fields keep 16px, so iOS Safari won't zoom.
* **Buttons (body.b2Strong):** Buttons set their own labels, one size per button.
### Mono
Addresses, hashes, keys, and code, in one size.
* **Addresses and Hashes (mono.m1):** Hex values and monospace table cells.
* **Commands and Keys (mono.m1):** Snippets and secret values.
### Utility
Short metadata labels in the mono family, with wide tracking. The design sets them in uppercase, which a component applies itself, since the sets keep the text's case.
* `utility.m1`: JetBrains Mono, 12px, weight 400, line height 16px
* `utility.m2`: JetBrains Mono, 10px, weight 400, line height 12px
* **Label (utility.m1):** Metadata labels above or beside a value.
* **Small Label (utility.m2):** The smaller size, for labels in tight spaces.
## Guidelines
### Build Hierarchy With Few Sizes
Build hierarchy with size and weight, not color. Most screens need a page title, section titles, and body text.
* **Page Title (heading.h2):** One per page, including app shell and dialog titles.
* **Section and Card Title (heading.h3):** Section, surface, and popover titles.
* **Small Title (body.b1Strong):** Compact titles, such as empty states and legends.
* **Body and Secondary Text (body.b1):** Reading text, in the primary or secondary color.
Keep headings in order. Choose the element by its place in the outline and the set by its look.
**Do:** Let the component set the label and description sizes.
```tsx
AmountAvailable balance: 120.00 USDC.
```
**Don't:** Use all caps or bold every line to create hierarchy. Write in [sentence case](/docs/foundations/content/writing-style#capitalization).
```tsx
AMOUNT
Available balance: 120.00 USDC.
```
### Match Sets to Their Role
* **Wrapping Text (body):** Anything that can wrap.
* **Labels (body.b2Strong):** Field labels and short lines beside controls.
* **Titles (heading):** Page, dialog, section, and card titles.
* **Hero Numbers (value):** One balance or reading per screen, in Inter.
### Reserve Pilat for Titles
Pilat sets titles only: page, dialog, section, and card titles in the heading sets, and hero titles in the display sets, from 18px up. Inter sets everything else, including labels, tabs, toasts, buttons, and numbers.
**Do:** Set the title in Pilat and the text below it in Inter.
```tsx
Recent payments
```
**Don't:** Set Pilat on labels, tabs, toasts, or numbers, or below 18px.
```tsx
{"fontFamily: 'heading'"}
```
### Use Five Styles per Screen
Dense screens, such as consoles and internal tools, use at most five styles. Add `mono.m1` as a sixth only where the screen shows hex values or code.
* **Page Title (heading.h2):** One per screen, in Pilat.
* **Section Title (heading.h3):** Sections, cards, and dialogs, in Pilat.
* **Body (body.b2):** Text, table cells, and descriptions.
* **Strong (body.b2Strong):** Labels, buttons, and emphasis.
* **Meta (body.b3):** Timestamps, hints, and secondary details.
* **Hex and Code (mono.m1):** The sixth style, only for hex values and code.
* **Families (2 per screen):** Inter and Pilat, plus mono only for hex and code.
* **Content Sizes (3 per screen):** Below the titles, use weight and color before size.
### Let Components Set Their Type
Components set the type of their own parts, such as a field label, a table cell, or a button. Pass text as children, and don't restyle it.
* **Component Text (children):** Pass plain text. The component applies its set and color.
* **Your Own Text (typography):** Choose a set by role, from the five styles above.
### Set Type With One Set
Set your own text with one `typography` set. Don't combine a family, size, or weight from different sets, which renders a style that the designs don't define. The [Linter](/docs/foundations/linter#set-type-with-a-typography-set) reports these.
**Do:** Set the role as one set.
```tsx
{"typography: 'body.b2'"}
```
**Don't:** Build or adjust a style with separate type properties.
```tsx
{"fontWeight: '600 !custom'"}
```
### Reserve the Expressive Sets
* **Display (display):** One hero title per screen, in Pilat. Never in cards, tables, or dialogs.
* **Value (value):** One headline reading per screen, in Inter. Not for a row of metrics.
* **Utility (utility):** A metadata label above a value. No other text uses all caps.
* **Mono (mono):** Hex values and code only. Not for numbers, amounts, dates, or labels.
### 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.
**Do:** Align amounts with tabular figures, such as `Amount` with `align="right"`.
```tsx
/**
* Do example for "Use Tabular Figures for Numbers" on the Typography page.
* Align amounts with tabular figures, such as `Amount` with `align="right"`.
* @module
*/
import { Amount, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const column = style({ display: 'grid', gap: '8', width: '12rem !custom' })
}
```
**Don't:** Stack amounts in proportional figures, where digits drift out of line.
```tsx
/**
* Don't example for "Use Tabular Figures for Numbers" on the Typography page.
* Don't stack amounts in proportional figures, where digits drift out of line.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
1,111.11 PathUSD8,808.80 PathUSD4,170.25 PathUSD
)
}
namespace styles {
export const amount = style({
color: 'content.primary',
fontVariantNumeric: 'proportional-nums !custom',
textAlign: 'right',
typography: 'body.b2Strong',
})
export const column = style({ display: 'grid', gap: '8', width: '12rem !custom' })
}
```
If you render a number yourself, such as a metric tile, set tabular figures in its style.
```tsx
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.
**Do:** Set hashes in `mono.m1`, so they align and `I`, `l`, `0`, and `O` stay distinct.
```tsx
/**
* Do example for "Use Monospace for Hashes and Code" on the Typography page.
* Set hashes in a `.mono` set, so they align and `I`, `l`, `0`, and `O` stay distinct.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const column = style({ display: 'grid', gap: '8' })
export const value = style({ color: 'content.primary', typography: 'mono.m1' })
}
```
**Don't:** Set hashes in a proportional set, where equal-length values drift apart.
```tsx
/**
* Don't example for "Use Monospace for Hashes and Code" on the Typography page.
* Don't set hashes in a proportional set, where equal-length values drift apart.
* @module
*/
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const column = style({ display: 'grid', gap: '8' })
export const value = style({ color: 'content.primary', typography: 'body.b3' })
}
```
### Keep Lines Readable
* **Line Length (45 to 75 characters):** Cap paragraphs with `maxWidth: '65ch !custom'`. Dialogs already cap their width.
* **Alignment:** Left-align text. Center only short text, such as an empty state title.
* **Minimum Size (12px):** Don't set interface text smaller. The smallest body set, `body.b3`, stops here.
---
Source: https://ds.tehq.dev/product/foundations/iconography
# Iconography
Icons from the Tempo catalog, and how to size, color, and label them.
## Overview
Icons support a label rather than replace it. Every icon in the catalog shares one grid and stroke weight, so any group of icons reads as one family.
* **Grid (16 by 16):** Every icon draws on the same square grid.
* **Size (1em):** An icon matches the font size of its text.
* **Color (currentColor):** An icon fills with the color of its text.
* **Imports (one module each):** A build carries only the icons it imports.
```tsx
import { Send } from '@tempoxyz/ds/icons'
export function SendButton() {
return (
)
}
```
## Size and Color
Components size and color their own icons, so inside a [Button](/docs/components/button) you add only the icon as a child.
### Size
* **Beside Text (1em):** The default in buttons, links, and running text.
* **Beside Titles (20px):** A larger icon beside a section or card title.
* **Status Icons (20px):** A status icon beside a message, as in a [Toast](/docs/components/toast).
* **Alert Indicator (16px):** An [Alert](/docs/components/alert) marks its tone with a square in a 16px box.
* **Modal Icons (24px):** An [IconTile](/docs/components/icon-tile) frames the icon above a modal title.
* **Standalone Icons (fontSize):** Set its font size, not its width and height.
### Color
Set the color on the icon or its parent, with the same roles as text.
* **Primary (content.primary):** The default, beside primary labels and text.
* **Secondary (content.secondary):** Beside metadata, such as an update time.
* **Status (content.warning):** Only for an icon that reports a status.
## Guidelines
### Pair Icons With Text
Drop the label only for actions that are familiar without words, such as Close, Copy, and More. Don't give an icon to only one of several buttons, since it draws attention to that action.
**Do:** Use icon-only buttons for actions with a universal icon.
```tsx
```
**Don't:** Drop the label from actions that have no universal icon.
```tsx
```
### Match Icons to Their Text
An icon that inherits from its label scales with the type and stays aligned. Any other color reads as a status.
**Do:** Let an inline icon inherit the size and color of its label.
```tsx
/**
* Do example for "Match Icons to Their Text" on the Iconography page.
* Let an inline icon inherit the size and color of its label.
* @module
*/
import { Copy } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Copy address
)
}
namespace styles {
export const label = style({
alignItems: 'center',
color: 'content.primary',
display: 'inline-flex',
gap: '4',
typography: 'body.b2Strong',
})
}
```
**Don't:** Enlarge or recolor an inline icon apart from its text.
```tsx
/**
* Don't example for "Match Icons to Their Text" on the Iconography page.
* Don't enlarge or recolor an inline icon apart from its text.
* @module
*/
import { Copy } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Copy address
)
}
namespace styles {
export const icon = style({ color: 'accent.blue.background', fontSize: '30' })
export const label = style({
alignItems: 'center',
color: 'content.primary',
display: 'inline-flex',
gap: '4',
typography: 'body.b2Strong',
})
}
```
### Use Catalog Icons Only
Icons from another set break the shared grid and stroke weight. If the catalog lacks an icon, propose one with its use case in the Design System project.
**Do:** Draw every icon in a group from the catalog.
```tsx
/**
* Do example for "Use Catalog Icons Only" on the Iconography page.
* Draw every icon in a group from the catalog.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
import { ArrowDownLeft, Send, SwapHorizontal } from '@tempoxyz/ds/icons'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```
**Don't:** Mix in an icon from another set.
```tsx
/**
* Don't example for "Use Catalog Icons Only" on the Iconography page.
* Don't mix in an icon from another set.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
import { ArrowDownLeft, Send } from '@tempoxyz/ds/icons'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const icon = style({ height: '1.25em !custom', width: '1.25em !custom' })
export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```
* **Token Logos (TokenLogo):** Render token and network logos with [TokenLogo](/docs/components/token-logo).
* **Account Images (Identicon):** Render accounts with [Avatar](/docs/components/avatar) or [Identicon](/docs/components/identicon).
## Accessibility
* **Decorative by Default (aria-hidden):** An icon without `aria-label` or `aria-labelledby` is hidden, so screen readers skip it.
* **Meaningful Icons (role=img):** Add `aria-label` only if no nearby text states its meaning, such as a lone status icon.
* **Icon-Only Buttons (aria-label):** Label the button, not the icon. Name the action, such as Close dialog rather than X.
* **Tooltips (Tooltip):** Pair an icon-only button with a [Tooltip](/docs/components/tooltip) that repeats its label for sighted mouse users.
* **Contrast (3:1):** Applies to meaningful icons. Both `content.primary` and `content.secondary` pass.
* **Forced Colors (currentColor):** Icons follow the system text color in forced colors mode, with no extra styles.
## Catalog
* **Names (PascalCase):** Names match the design, such as `QRCode`.
* **Reserved Names (InfinityIcon):** Avoids the JavaScript global `Infinity`.
* **Shared Names (2):** A second icon with a taken name ends in `2`.
* **Component Names (as):** Rename on import, such as `TableIcon`.
* **Raw SVGs (.svg):** The original exports, for use outside React.
```tsx
import { Table } from '@tempoxyz/ds'
import { Table as TableIcon } from '@tempoxyz/ds/icons'
import copyUrl from '@tempoxyz/ds/icons/Copy.svg'
```
## Related
[Button](/docs/components/button)
Use for icon buttons and icons beside labels.
[IconTile](/docs/components/icon-tile)
Use for framed icons in headers and lists.
[Tooltip](/docs/components/tooltip)
Use for labelling icon buttons.
[Color](/docs/foundations/color)
Covers icon colors.
---
Source: https://ds.tehq.dev/product/foundations/motion
# 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
```
**Don't:** Make the reader wait for an animation to finish before they can act.
```tsx
```
## 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.
---
Source: https://ds.tehq.dev/product/foundations/content/voice
# Voice
Tempo's personality in words, consistent across every product.
## Overview
Voice is how Tempo sounds in every product: a knowledgeable colleague who explains plainly and wastes no time, as on [tempo.xyz](https://tempo.xyz) and in the [developer docs](https://tempo.xyz/developers). [Tone](/docs/foundations/content/tone) adapts it to each situation, such as a first visit or a failed payment.
## How Tempo Writes
* **Cover Three Points:** State what is happening, what it costs, and what happens next.
* **Define Before Explaining:** Open with one sentence that defines the thing, then list its parts.
* **State Rules as Facts:** State limits and protections as what Tempo enforces, not as warnings.
* **Name Availability Plainly (Testnet only):** Name a stage, such as beta or devnet only, with where it applies and what changes it.
* **State What an Operation Doesn't Do:** State plainly that a refund is a new payment, not a reversal.
## Traits
Each trait names the line it must not cross.
### Clear, Not Simplistic
**Do:** Describe a payment in everyday money words, and format each value with
[Amount](/docs/components/amount) or [Hex](/docs/components/hex).
```tsx
/**
* Do example for "Clear, Not Simplistic" on the Voice page.
* Describe a payment in everyday money words, and format each value with Amount or Hex.
* @module
*/
import { Amount, Hex, ListGroup, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
ToAmountNetwork fee
)
}
namespace styles {
export const rows = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```
**Don't:** Show protocol fields, base units, or gas parameters on a payment review.
```tsx
/**
* Don't example for "Clear, Not Simplistic" on the Voice page.
* Don't show protocol fields, base units, or gas parameters on a payment review.
* @module
*/
import { ListGroup, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Recipient EOA0x3c44cddd…Value250000000Gas limit21000
)
}
namespace styles {
export const rows = style({ maxWidth: '18rem !custom', width: '100% !custom' })
export const value = style({ typography: 'mono.m1' })
}
```
### Precise, Not Approximate
**Do:** State the exact amount, time, or limit.
```tsx
This quote expires in 10 minutes.
```
**Don't:** Use vague words such as soon or shortly.
```tsx
This quote expires soon.
```
### Confident, Not Boastful
**Do:** Confirm the result as a fact, and stop.
```tsx
Payment sentAlice received 25.00 USDC.
```
**Don't:** Use hype, hedging, exclamation marks, or emoji for a routine result.
```tsx
Woohoo! 🎉Your lightning-fast payment is on its way!
```
### Calm, Not Casual
**Do:** State what failed, and reassure the reader with a fact.
```tsx
The payment did not go through. Your balance has not changed.
```
**Don't:** Joke about a failure that involves money.
```tsx
Oops! Something broke. Our bad.
```
### Respectful, Not Condescending
**Do:** Address the reader as you, and describe the problem and the fix.
```tsx
This address isn't valid. Check it and try again.
```
**Don't:** Blame the reader for an error.
```tsx
You entered an invalid address.
```
### Helpful, Not Pushy
**Do:** Offer the next step plainly, and let the reader decide.
```tsx
```
**Don't:** Use fear or urgency to drive a choice.
```tsx
```
---
Source: https://ds.tehq.dev/product/foundations/content/tone
# Tone
How Tempo's voice adjusts to the reader, from a first visit to an error.
## Overview
[Voice](/docs/foundations/content/voice) stays the same everywhere. Tone shifts with what the reader is doing and how they feel, and grows plainer and more specific as more money or access is at stake.
## Situations
### Onboarding
Welcome a new reader, and explain each new term once, in one sentence.
**Do:** Explain the first step and why it matters.
```tsx
Add funds to startDeposit dollars or stablecoins to send your first payment.
```
**Don't:** Assume crypto vocabulary.
```tsx
Bridge assetsBridge ERC-20s to the L1 to bootstrap liquidity.
```
### Success
State what finished in a positive [Toast](/docs/components/toast) when nothing is left to do, then stop.
* **Name the Result:** Use a noun and a past-tense verb.
* **Add the Detail:** Add the amount or recipient as confirmation.
* **Skip the Celebration:** Leave out praise, exclamation marks, and emoji.
* **Wait for the Network:** Show a pending state until the network confirms.
### In Progress
Be calm and specific about what happens next and how long it takes.
* **Name the Step:** End a status label with an ellipsis (…).
* **Explain Long Waits:** Name the wait, and whether to stay on the page.
**Do:** State what the system does and set an expectation.
```tsx
Confirming payment
This usually takes less than a second.
```
**Don't:** Leave the reader with an open-ended wait.
```tsx
Please wait…
```
### Warnings
State a risk once, beside the content it affects, and only if the reader can act on it.
**Do:** State the risk and what to check in one or two plain sentences.
```tsx
/**
* Do example for "Warnings" on the Tone page.
* State the risk and what to check in one or two plain sentences.
* @module
*/
import { Alert, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Payments are final. Check that the address matches the one you were given.
)
}
namespace styles {
export const alert = style({ maxWidth: '20rem !custom' })
}
```
**Don't:** Shout, stack exclamation marks, or use the `negative` intent for a warning.
```tsx
/**
* Don't example for "Warnings" on the Tone page.
* Don't shout, stack exclamation marks, or use the `negative` intent for a warning.
* @module
*/
import { Alert, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
WARNING!! Double-check everything or your money is GONE forever!
)
}
namespace styles {
export const alert = style({ maxWidth: '20rem !custom' })
}
```
* **Local Risk (Alert):** Use a warning [Alert](/docs/components/alert) for a field or section.
* **Product-Wide Condition (Banner):** Use a warning [Banner](/docs/components/banner) for the whole product.
### Errors
Stay neutral and direct, and follow the [error message structure](/docs/foundations/content/writing-style#structure-error-messages).
* **Lead With the Fix:** Add the cause only if it helps the reader act.
* **Show It Inline:** Show a blocking error inline, not in a [Toast](/docs/components/toast).
* **Keep the TextInput:** Keep the input, and state what to change.
* **Skip Blame and Jokes:** Don't apologize at length, blame, or joke.
### Security and Keys
**Do:** State the exact consequence and who is responsible.
```tsx
Save your recovery keyAnyone with this key can move your funds. Tempo cannot recover it for you.
```
**Don't:** Use humor for a security step.
```tsx
Your secret sauce 🤫Keep it somewhere safe-ish!
```
### Sending Money
Repeat the exact amount, recipient, and fee on every step.
**Do:** Put the exact amount on the final action.
```tsx
```
**Don't:** Use a playful label for a payment.
```tsx
```
### Irreversible Actions
Use a serious, explicit tone, as [Destructive Actions](/docs/patterns/destructive-actions) shows.
* **Name the Consequence:** Name exactly what the action removes or ends.
* **Confirm Payments on Review:** On review, state once that payments are final.
---
Source: https://ds.tehq.dev/product/foundations/content/writing-style
# Writing Style
How Tempo writes interface text: sentence case, a verb first, and plain words.
## Overview
Tempo's interface text is short, specific, and plain. It names the thing and the action in words that a reader new to crypto knows.
The rules follow [tempo.xyz](https://tempo.xyz) and the [developer docs](https://tempo.xyz/developers). [Where the Sources Differ](#where-the-sources-differ) records the choice for product screens.
## Principles
* **Clear Before Clever:** State what happens, in familiar words.
* **Short:** Cut each word that doesn't change the meaning.
* **Specific:** Name the action and its object, not Continue.
* **Consistent:** Call one thing by one name everywhere.
## Capitalization
Use sentence case everywhere, capitalizing only the first word and proper nouns.
**Do:** Capitalize the first word of each heading, sentence, and label.
```tsx
/**
* Do example for "Writing Style" on the Writing Style page.
* Capitalize the first word of each heading, sentence, and label.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Add funds
Deposit USDC from another wallet or an exchange.
)
}
namespace styles {
export const card = style({
alignItems: 'flex-start',
display: 'flex',
flexDirection: 'column',
gap: '8',
maxWidth: '18rem !custom',
})
export const text = style({
color: 'content.secondary',
margin: '0 !custom',
typography: 'body.b2',
})
export const title = style({
color: 'content.primary',
margin: '0 !custom',
typography: 'body.b1Strong',
})
}
```
**Don't:** Capitalize every word, in headings or anywhere else in the interface.
```tsx
/**
* Don't example for "Writing Style" on the Writing Style page.
* Don't capitalize every word, in headings or anywhere else in the interface.
* @module
*/
import { Button, style } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
Add Funds
Deposit USDC From Another Wallet or an Exchange.
)
}
namespace styles {
export const card = style({
alignItems: 'flex-start',
display: 'flex',
flexDirection: 'column',
gap: '8',
maxWidth: '18rem !custom',
})
export const text = style({
color: 'content.secondary',
margin: '0 !custom',
typography: 'body.b2',
})
export const title = style({
color: 'content.primary',
margin: '0 !custom',
typography: 'body.b1Strong',
})
}
```
### Proper Nouns
* **Tempo Products and Standards:** Tempo Wallet, Tempo Explorer, and TIP-20.
* **Companies and Networks:** Other companies, products, and networks.
* **People, Places, and Languages:** Including currencies named after a place.
* **Symbols and Values:** Keep USDC, iOS, and 0x1a2b… exactly as written.
* **Lowercase Symbols:** Rewrite a sentence that starts with pathUSD.
* **Features and Concepts:** Keep access key and passkey lowercase in titles.
**Do:** Capitalize the product name and nothing else.
```tsx
Recipient addressPaste a Tempo address or choose a saved contact.
```
**Don't:** Capitalize common words or lowercase a product name.
```tsx
Recipient AddressPaste a tempo address or choose a saved Contact.
```
### Never All Caps
**Do:** Choose clearer words, or use size and weight sparingly.
```tsx
This quote expires in 10 minutes.
```
**Don't:** Set text in all caps or use capitals for emphasis.
```tsx
THIS QUOTE EXPIRES IN 10 MINUTES.
```
## Write Labels
### Buttons
* **Verb First:** Start each button and menu item with a verb.
* **Short Labels:** Use one to three words, such as Add funds.
* **One Label per Action:** Use the same label for an action everywhere.
**Do:** Name the action and the object it affects.
```tsx
```
**Don't:** Use generic labels such as "OK", "Yes", or "Submit".
```tsx
```
### Form Labels
* **Name the Value:** Use a noun phrase, with no colon or Enter your.
* **Hints in the Description:** Put format hints in the field's description.
* **Example Placeholders:** Use a placeholder only for an example value.
* **Mark the Minority:** Mark optional fields when most are required.
### Headings and Titles
* **Name the Page:** Name the page or task, such as API keys.
* **Verb for a Task:** Start a task title with its verb.
* **Question to Confirm:** Write a confirmation title as a question.
* **One Phrase:** Use one phrase, with no end punctuation.
### Links
* **Name the Destination:** Name where the link goes.
* **No Typed Arrows:** Leave out →, and let [ListGroup](/docs/components/list-group) draw a chevron.
### Tooltips
* **A Few Words:** Name or clarify the trigger of a [Tooltip](/docs/components/tooltip).
* **Definitions:** A definition can be one full sentence.
* **Nothing Essential:** Keep actions and essential details on the page.
### Status Labels
* **Short Status:** Use one or two words in a [Badge](/docs/components/badge) or status column.
* **One Name per Status:** Keep one name for each status on every screen.
## Write Messages
### Structure Error Messages
Most errors state three things, in this order.
* **What Happened:** State the outcome first, in plain words.
* **Why:** State the cause if it helps the reader act.
* **What to Do:** End with the action that resolves it.
* **Beside a Field:** Lead with the fix when context shows the issue.
* **Unknown Cause:** Say what to try, not only Something went wrong.
* **Support Reference:** Add a support reference as secondary text.
**Do:** State how to fix the value, with the limit that applies.
```tsx
/**
* Do example for "Structure Error Messages" on the Writing Style page.
* State how to fix the value, with the limit that applies.
* @module
*/
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
AmountEnter an amount up to your balance of 1,250.00 USDC.
)
}
namespace styles {
export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```
**Don't:** Show raw error names, codes, or RPC messages as the message.
```tsx
/**
* Don't example for "Structure Error Messages" on the Writing Style page.
* Don't show raw error names, codes, or RPC messages as the message.
* @module
*/
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
AmountError: InsufficientBalance
)
}
namespace styles {
export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```
### Empty States
* **Why It's Empty:** Say why the area has nothing to show.
* **What to Do Next:** Offer the next step, as [Empty States](/docs/patterns/empty-states) shows.
### Confirmations
* **Two to Four Words:** Title a [Toast](/docs/components/toast) with the outcome.
* **Needed Detail Only:** Describe only needed detail, such as the amount.
* **Shortcut Actions:** Make each toast action reachable elsewhere too.
## Put the Important Words First
Readers scan the first few words of a line.
**Do:** Start with the subject, and put conditions after it.
```tsx
Transfers over $10,000 need a second approval.
```
**Don't:** Open with filler or bury the rule at the end.
```tsx
Please note that, depending on the amount, a second approval may be needed.
```
## Use Plain Words
Write for a reader new to crypto.
* **Everyday Words:** Say network fee, not gas.
* **Define at First Use:** Explain a technical term at its first use.
## Address the Reader as You
* **Your, Not My:** Use your for what belongs to the reader, not my.
* **We for Tempo:** Use we only for Tempo as a company, and rarely.
**Do:** Address the reader and state what happens next.
```tsx
No payments yetPayments you send or receive appear here.
```
**Don't:** Describe the reader in the third person.
```tsx
No payments yetThe user has not made any payments.
```
## Keep It Short
* **Buttons (1 to 3 words):** A verb and its object.
* **Headings (under 6 words):** The page or the task.
* **Descriptions (1 sentence):** The detail that the title leaves out.
* **Error Messages (1 or 2 sentences):** The outcome, then the fix.
* **Sentences (under 20 words):** Split a longer sentence in two.
**Do:** Cut filler such as please, simply, just, and successfully.
```tsx
Payment sent
```
**Don't:** Pad a message with words that add nothing.
```tsx
Your payment was sent successfully
```
## Write for Everyone
* **Name the Control:** Name the control, not below, above, or click.
* **Prefer Common Words:** Skip idioms, which translate poorly.
## Where the Sources Differ
| Topic | What the sources do | Product screens |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Heading case | Site and docs headings use sentence case. The docs home and one docs heading use Title Case. Tempo Performance mixes both. | Sentence case. |
| Contractions | The docs mix can't with cannot, and doesn't with does not. Tempo Wallet errors use Cannot. | Contractions. |
| Repeated labels | The marketing site words one contact button two ways. | One label per action. |
| Link arrows | Some docs links end with →. | No typed arrows. |
| Colon titles | Some docs and site titles join two phrases with a colon. | One phrase per title. |
## Related
[Button](/docs/components/button)
Use for button labels.
[Field](/docs/components/field)
Use for labels, descriptions, and errors.
[Errors and Validation](/docs/patterns/errors-and-validation)
Covers when and where to show errors.
---
Source: https://ds.tehq.dev/product/foundations/accessibility
# 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](/docs/foundations/color#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](/docs/foundations/color#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](/docs/components/kbd), 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 (
RecipientSave as contact
)
}
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](/docs/components/dialog), [AlertDialog](/docs/components/alert-dialog), and [Drawer](/docs/components/drawer), manage focus from open to close. Anchored popups, such as [Popover](/docs/components/popover), [Menu](/docs/components/menu), and [Tooltip](/docs/components/tooltip), 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](/docs/components/popover) 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](/docs/components/app-shell) and [SidebarMenu](/docs/components/sidebar-menu) 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](/docs/components/table), 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 (
RecipientAn address or contact name.
)
}
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 (
)
}
namespace styles {
export const frame = style({ maxWidth: '100% !custom', width: '16rem !custom' })
}
```
* **Linked Label (Field.Label):** [Field](/docs/components/field) 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](/docs/components/fieldset) 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
Alice sent you 25.00 USDC.
```
**Don't:** Set a fixed `height` on a text container. Spacing overrides clip its text.
```tsx
Alice sent you 25.00 USDC.
```
## 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](/docs/foundations/motion#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](/docs/foundations/content/writing-style#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 `` 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](/docs/foundations/color)
Covers contrast and color use.
[Motion](/docs/foundations/motion)
Covers reduced motion.
[Forms](/docs/patterns/forms)
Covers labels and grouping.
[Errors and Validation](/docs/patterns/errors-and-validation)
Covers writing and announcing errors.
[Button](/docs/components/button)
Use for icon buttons and loading states.
---
Source: https://ds.tehq.dev/product/foundations/agents
# 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](/docs/introduction/getting-started#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 the Markdown for its version in a few files by topic, with an agent guide that holds these rules.
### 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](/docs/components) overview, which compares similar ones, before you write markup.
* **Intent First:** Choose each component by the job of its content, as [Building From Intent](/docs/foundations/intent) 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.
### Set Type With Few Sets
* **Component Type:** Let each component set the type of its parts. Pass text as children and don't restyle it.
* **One Set per Style (typography):** Set your own text with one `typography` set, never a separate family, size, or weight.
* **Few Sets per Screen:** Use at most five styles on a screen, and Pilat only for titles.
* **Expressive Sets:** Follow [Typography](/docs/foundations/typography#reserve-the-expressive-sets) before you use display, value, utility, or mono.
### 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](/docs/introduction/faq#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
* **Guidance First:** Read a component's Guidelines, Content, and Accessibility before you use it, not only its examples.
* **Patterns:** Before you build a screen, read the patterns it uses, such as [Forms](/docs/patterns/forms) and [Tables and Lists](/docs/patterns/tables-and-lists).
* **Native Semantics:** Keep native semantics, and meet every item on the [Accessibility](/docs/foundations/accessibility#checklist) checklist.
### Write Copy to the Content Guidelines
* **Labels and Terms:** Use sentence case and verb-first button labels, as [Writing Style](/docs/foundations/content/writing-style#write-labels) describes.
* **Amounts and Addresses:** Format amounts with [Amount](/docs/components/amount) and a `currency` or `symbol`, and addresses and hashes with [Hex](/docs/components/hex).
* **Errors:** Write error messages that state the fix, as [Writing Style](/docs/foundations/content/writing-style#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](/docs/foundations/linter) 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.
- Set text with one `typography` set, and let components set the type of their own parts. Use Pilat only for titles, and at most five styles on a screen. Read https://ds.tehq.dev/docs/foundations/typography.md before you style text.
- Read the pattern pages that a screen uses, such as https://ds.tehq.dev/docs/patterns/forms.md and https://ds.tehq.dev/docs/patterns/tables-and-lists.md.
- 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](/docs/introduction/getting-started)
Covers setup and the agent prompt.
[FAQ](/docs/introduction/faq)
Covers common questions.
[Components](/docs/components)
Covers the component catalog.
[Building From Intent](/docs/foundations/intent)
Covers choosing a component by the job of its content.
[Linter](/docs/foundations/linter)
Covers the lint rules that check library use.
[Voice](/docs/foundations/content/voice)
Covers how Tempo UI copy sounds.
---
Source: https://ds.tehq.dev/product/foundations/intent
# Building From Intent
Choose each component by the job of its content, not by the markup it replaces.
## Overview
Every part of a screen does a job, such as a list of records to compare, a status to read, or an identifier to check. Each component page documents one job, so the right component follows from the job and not from the look of the old markup.
## The Method
### Inventory the Screen by Job
Name the job of each part before you open the catalog: records, details, status, identifier, amount, metric, message, action, choice, or navigation.
### Choose by Documented Job
Find the job in [Common Intents](#common-intents) or the comparisons on [Components](/docs/components#choosing-a-component). Then read the When to Use section of the component page.
### Check When Not to Use
Read the When Not to Use section of the same page. If it names your case, use the component that the section links instead.
### Write the Labels
Write every label from the [Writing Style](/docs/foundations/content/writing-style) rules. Map a raw API value, such as `payment_failed`, to a word, such as Failed.
### Check the Fit
Render the result at the narrowest width that its column or container reaches, and confirm that nothing overlaps or clips. In a table, follow [Keep Multi-Line Rows Readable](/docs/patterns/tables-and-lists#keep-multi-line-rows-readable).
## Common Intents
Each tile names a job, the component for it, and the question that tells it apart from similar components.
### Data
* **Records (Table):** Do people compare many records across the same fields? Use a [Table](/docs/components/table), one row per record.
* **One Record (ListGroup):** Does the view show the fields of one record? Use [ListGroup](/docs/components/list-group) rows with `ListGroup.Label`.
* **Identifier (Hex):** Is it an address or a hash outside a table? Use [Hex](/docs/components/hex) with `copy`. A table column uses a `mono` cell.
* **Amount (Amount):** Is it money or a token balance? Use [Amount](/docs/components/amount) with a `currency` or a `symbol`.
* **Metric (Surface):** Is it a headline number on a dashboard? Use a small [Surface](/docs/components/surface) tile, as [Dashboards](/docs/patterns/dashboards) shows.
### Status
* **Status in a Table (status):** Does the status sit in a table row? Set `status` on its [Table](/docs/components/table) cell, and keep the status word beside the color.
* **Status of a Payment (StatusChip):** Does a payment, an authorization, or a network have a status outside a table? Use a [StatusChip](/docs/components/status-chip).
* **Live System Status (StatusIndicator):** Does a service or a connection report its live state? Use a [StatusIndicator](/docs/components/status-indicator).
* **Running Task (StatusRow):** Does a person wait on one task that finishes within minutes? Follow it with a [StatusRow](/docs/components/status-row).
* **Attribute (Badge):** Does a word name a category or an attribute, such as Testnet? Use a [Badge](/docs/components/badge) beside the title.
### Interaction
* **Message (Alert):** Does a sentence explain a condition? Use an [Alert](/docs/components/alert) for a section and a [Banner](/docs/components/banner) for the page.
* **Action (Button):** Does it start something in the current view? Use a [Button](/docs/components/button) with a verb label, such as Send payment.
* **Choice (RadioGroup):** Does a person pick one option? Compare [RadioGroup](/docs/components/radio-group) and the others on [Components](/docs/components#choosing-one-option).
* **Navigation (SidebarMenu):** Does it open another page? Use a link, or a [SidebarMenu](/docs/components/sidebar-menu) for the main destinations of an app.
## Porting an Existing Interface
A port replaces old markup with library components. Map the job of each part instead, since the old screen can already use the wrong element for it.
### Show Records as Rows
**Do:** Show records that share fields as the rows of a [Table](/docs/components/table).
```tsx
/**
* Do example for "Show Records as Rows" on the Building From Intent page.
* Show records that share fields as the rows of a Table.
* @module
*/
import { Table } from '@tempoxyz/ds'
const payouts = [
['Ada Lovelace', 'Oct 19', '120.00'],
['Alan Turing', 'Oct 19', '80.00'],
['Grace Hopper', 'Oct 18', '45.50'],
] as const
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
```
**Don't:** Wrap each record in a [Surface](/docs/components/surface) card because the old screen drew
cards.
```tsx
/**
* Don't example for "Show Records as Rows" on the Building From Intent page.
* A card per record repeats each label and breaks the columns that people compare.
* @module
*/
import { Grid, style, Surface } from '@tempoxyz/ds'
const payouts = [
['Ada Lovelace', 'Oct 19', '120.00 USDC'],
['Alan Turing', 'Oct 19', '80.00 USDC'],
['Grace Hopper', 'Oct 18', '45.50 USDC'],
] as const
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
{payouts.map(([recipient, date, amount]) => (
{recipient}
Date: {date}
Amount: {amount}
))}
)
}
namespace styles {
export const card = style({
boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
})
export const grid = style({ width: '100% !custom' })
export const meta = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
export const title = style({ margin: '0', typography: 'body.b2' })
}
```
### Write Status Words, Not API Values
**Do:** Color a status word in sentence case with the `status` of its [Table](/docs/components/table)
cell.
```tsx
/**
* Do example for "Write Status Words, Not API Values" on the Building From Intent page.
* Color a status word in sentence case with the `status` of its Table cell.
* @module
*/
import { Table } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
```
**Don't:** Copy a grey pill into a [Badge](/docs/components/badge) with the raw value from the API.
```tsx
/**
* Don't example for "Write Status Words, Not API Values" on the Building From Intent page.
* A grey pill copied from the old screen shows raw API values and no status color.
* @module
*/
import { Badge, Table } from '@tempoxyz/ds'
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
```
### Fit Identifiers to Their Column
[Hex](/docs/components/hex) truncates to its container, down to the prefix, one character on each side, and its copy button. A narrower column lets it overflow into the next cell.
**Do:** Set `mono` on the cell and shorten the value with `formatHex` from `@tempoxyz/ds`, which keeps
four characters on each side. Show the full value with `copy` on the details view.
```tsx
/**
* Do example for "Fit Identifiers to Their Column" on the Building From Intent page.
* Shorten an address in a table column with a `mono` cell and `formatHex`.
* @module
*/
import { formatHex, Table } from '@tempoxyz/ds'
const accounts = [
['Ada Lovelace', '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc', '120.00'],
['Alan Turing', '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', '80.00'],
] as const
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
```
**Don't:** Place a [Hex](/docs/components/hex) with `copy` in a column narrower than its minimum
width.
```tsx
/**
* Don't example for "Fit Identifiers to Their Column" on the Building From Intent page.
* A Hex with `copy` in a narrow column stops at its minimum width and overlaps the next cell.
* @module
*/
import { Hex, style, Table } from '@tempoxyz/ds'
const accounts = [
['Ada Lovelace', '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc', '120.00'],
['Alan Turing', '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', '80.00'],
] as const
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
return (
)
}
namespace styles {
export const narrow = style({ width: '3rem !custom' })
export const table = style({ tableLayout: 'fixed !custom' })
}
```
## Checklist
Before you ship a screen, confirm each item.
* **Jobs Named:** Each part of the screen has a named job, and each component matches that job.
* **Exclusions Checked:** No component appears in a case that its When Not to Use section excludes.
* **Labels Written:** Labels are words in sentence case, with one word per status and no raw API values.
* **Fit Checked:** Every cell and tile fits at the narrowest width of its layout, without overlap or clipping.
## Related
[Components](/docs/components)
Covers the catalog and the comparisons between similar components.
[Agents](/docs/foundations/agents)
Covers the rules that coding agents follow.
[Tables and Lists](/docs/patterns/tables-and-lists)
Covers tables, lists, and the details of one record.
[Feedback and Status](/docs/patterns/feedback-and-status)
Covers status words and the channel for each message.
[Writing Style](/docs/foundations/content/writing-style)
Covers labels, status words, and sentence case.
---
Source: https://ds.tehq.dev/product/foundations/linter
# 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 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/prefer-typography": "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](/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
```
````
**Don't:** Leave an icon-only button or a [Gauge](/docs/components/gauge) unnamed. Screen readers announce only its role.
````tsx
```tsx
// @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
{rows}
```
````
**Don't:** Leave a scroll container without a tab stop. Keyboard users cannot reach the hidden content.
````tsx
```tsx
// @lint: tds/require-scroll-region: This scrolling
needs role="region", tabIndex={0}, and an aria-label, so keyboard and screen reader users can reach and identify it.
{rows}
```
````
### 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](/docs/components/kbd).
````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](/docs/components/checkbox) and [Button](/docs/components/button), which bring Tempo states, focus rings, and motion.
````tsx
```tsx
```
````
**Don't:** Restyle a native control that the library already ships.
````tsx
```tsx
// @lint: tds/prefer-component: Use 'Checkbox' from '@tempoxyz/ds' instead of . See https://ds.tehq.dev/docs/components/checkbox
// @lint: tds/prefer-component: Use 'Button' from '@tempoxyz/ds' instead of