# FAQ

Answers to common questions from teams building Tempo products with the design system.

## Getting Started

### Which Surface Should I Use?

Choose the surface by the platform you ship to. The two surfaces share a design language but not components, so a product with a web app and a mobile app uses both entrypoints.

| I am building...          | Surface | Import                |
| ------------------------- | ------- | --------------------- |
| A web application         | Web     | `@tempoxyz/ds`        |
| A React Native mobile app | Mobile  | `@tempoxyz/ds/mobile` |

Web components render DOM elements and compile with a Zyzz bundler plugin. Mobile components render React Native views and compile with Metro, as in Expo apps. See [Getting Started](/docs/introduction/getting-started) for each setup.

### Do I Need to Import a Stylesheet?

No. On web, the Zyzz plugin emits the variables, Geist fonts, and keyframes once, and each component brings its own rules, so a build carries only the styles it uses. On mobile, Metro compiles library and app styles while it bundles.

The Zyzz plugin is the only supported web setup. Vite, Rollup, Webpack, and esbuild all have adapters.

### How Do I Style My Own Markup?

Use `style` and `variants` from `@tempoxyz/ds` with TDS tokens, such as `foreground`, `background.surface`, `'6'`, and `copy.14`. Group the definitions in a `namespace styles` block, as the examples in these docs do.

When your app needs tokens of its own, extend `variables` in your own Zyzz config. Getting Started shows the Custom Variables setup for web and mobile.

## Components

### What If the Library Doesn't Have the Component I Need?

Build it in your app from library components and `style`, using TDS tokens. Keep that code in the consuming app, detached from the library.

If other products would 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.

Reuse an existing issue when one covers the same proposal. 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 or experimental Figma components don't establish a contract, so they stay out until a production version exists.

Check the [Components](/docs/components) overview for what ships today. Sidebar pages marked 🚧 haven't been 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`                       |
| `Badge`      | `Tag`                          |
| `Button`     | `Button`                       |
| `CodeInput`  | `OtpField`                     |
| `IconButton` | `Button` with `shape="icon"`   |
| `Skeleton`   | `Skeleton`                     |
| `Spinner`    | `Spinner`                      |
| `TextButton` | `Button` with `variant="text"` |
| `TextInput`  | `Input` inside a `Field`       |
| `Toast`      | `Toast`                        |
| `Toggle`     | `Switch`                       |

### Do Web Components Work in Mobile Browsers?

Yes. `@tempoxyz/ds` components run in mobile browsers. See [Responsive Layout](/docs/patterns/responsive-layout) for adapting a layout from a phone to a desktop.

## Design

### How Does Dark Mode Work?

On web, light and dark values follow the inherited CSS `color-scheme`. Set `color-scheme: light dark` on the root element to follow the operating system, or spread `vars({ colorScheme: 'dark' })` on a wrapper to fix one scheme for everything inside it.

On mobile, `Provider colorScheme="system"` follows the device setting. Pass `light` or `dark` to override it, and `vars="inverse"` to render a subtree with inverse variables.

The library doesn't 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, and no tooling synchronizes them, so the two can drift.

If a component doesn't match its production Figma design, use Report issue on its page and include the Figma link. For a change you need before the library catches up, keep the implementation in your app.

### Where Are the Figma Files?

* Web: the [Figma file](https://www.figma.com/design/exXRvQNL6yrBlkNgW1mFwR/Emma-DS?node-id=18-801) linked from the repository README.
* Mobile: [TDS App](https://www.figma.com/design/8iu5856rBEI3pnZ6YaIBgw), whose families the mobile components implement.

## Docs

### How Do I Report a Docs Issue?

On wide screens, the actions under On this page include:

* **Report issue**, which opens a GitHub issue titled with the page name and its path.
* **Edit page**, which opens the page's MDX source 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, and `/llms.txt` indexes them all. See [Agents](/docs/foundations/agents) for the files and the rules an agent follows when it generates Tempo UI.