# 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).
