# Theming

Every --orb-* token, the contrast pairs the defaults meet, the slots parts carry, and the components' styles with or without Tailwind.

The components' look is a set of `--orb-*` tokens and a stylesheet of classes that read them. [Customize](/docs/customize) shows the steps; this page lists what they work with:

```css title="apps/shop/app/app.css"
@import "@orbsearch/react/orbsearch.css";
@import "./theme.css";
```

## The tokens

Each token starts with `--orb-`; after the first in a row, the table names the rest by what follows:

| Tokens                                                                  | Set                                                                                      |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `--orb-color-ground`, `surface`, `well`                                 | The page, panels and popups, the well behind a photo                                     |
| `--orb-color-ink`, `ink-muted`, `line`, `line-strong`                   | Text, quieter text, lines; `line-strong` outlines a control                              |
| `--orb-color-accent`, `on-accent`, `accent-soft`                        | The one action color, text on it, a chosen value's tint                                  |
| `--orb-color-hover`, `sale`, `rating`, `focus`, `scrim`                 | A hovered row, sale prices, filled stars, focus rings, what dims the page behind a sheet |
| `--orb-font-sans`, `font-display`, `display-weight`, `tracking-display` | Type                                                                                     |
| `--orb-text-display`, `text-display-sm`                                 | The size of a page's title                                                               |
| `--orb-radius-control`, `radius-card`, `radius-sheet`, `radius-row`     | Corners of controls, tiles and popups, the sheet, a facet's value row                    |
| `--orb-shadow-pop`                                                      | A popup's shadow                                                                         |
| `--orb-spacing-target`, `spacing-gutter`                                | The smallest target (2.75rem), the side margin on a phone                                |
| `--orb-container-shop`, `aspect-media`                                  | How wide a page's content grows, a product photo's frame                                 |
| `--orb-tile-columns`, `tile-columns-md`, `tile-columns-xl`              | Tiles in a row: 2, 3 from 48rem, 4 from 80rem                                            |
| `--orb-grade-width`, `grade-step`, `grade-shape`, `grade-tip`           | A grade's badge, such as an energy class                                                 |
| `--orb-swatch-count`                                                    | A swatch's count `beside` its name or `on` it                                            |
| `--orb-ease-out-soft`, `motion-fast`, `motion-base`                     | Motion's curve, a press or popover (140 ms), a sheet or panel (220 ms)                   |
| `--orb-motion-wait`                                                     | How long a quick answer may take before the results' photos dim (150 ms)                 |

Every default stands in the `:root` block of `packages/react/orbsearch.css`. `packages/react/src/theme.css` explains each one, written without the prefix Tailwind's `prefix(orb)` adds: its `--color-ink` is `--orb-color-ink`.

## Contrast the defaults meet

The default colors meet WCAG 2.2 AA in these pairs:

- **Text:** `ink`, `ink-muted`, `sale` and `accent` reach 4.5:1 on `ground`, `surface`, `well` and `accent-soft`.
- **Lines and marks:** `line-strong`, `rating` and `focus` reach 3:1 on `ground` and `surface`.

<Callout type="warn">
    Keep these pairs when a theme changes a color, or the shop fails AA where the components met it.
</Callout>

## Slots and states

Every part carries a `data-slot` attribute to select it by, such as `search-input`, `suggestions`, `product-tile`, `tile-price`, `rating`, `price-now`, `facet`, `filter-chip`, `sheet` or `load-more`. Some say their state too:

- `data-field` and `data-kind` on a [facet](/docs/reference/glossary#facet), `data-kind` on a suggestion.
- `data-sold-out` on a tile; the ad label's slot is `tile-sponsored` or `suggestion-sponsored`.
- `data-source` on a chip: `shopper`, `query` or `rule`.
- `data-placement` (`top`, `grid` or `bottom`) and `data-kind` (`banner` or `teaser`) on a `banner`.

Load rules that select them after the components' styles, as a theme.

## Without Tailwind

`orbsearch.css` holds the tokens' defaults and every class the components use, unlayered, so a reset such as `button { all: unset }` loses to it. Import it once, as a stylesheet or from JavaScript, and your theme after it. A shop whose own Tailwind has no prefix uses it too.

## With Tailwind v4

Build the components' classes with your own Tailwind, under the `orb` prefix they are written with, as the demo's `app/styles/app.css` does:

```css title="apps/shop/app/app.css"
@import "tailwindcss/theme.css" prefix(orb);
@import "@orbsearch/react/theme.css";
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" source(none);
/* The shop's own files, and the components' source, relative to this file. */
@source "../";
@source "../../../packages/react/src";
```

Your own classes use the prefix too, such as `orb:text-ink`. `theme.css` adds `orb:hover:`, which applies only to a pointer that hovers, and `orb:press`, the components' press for a button of yours; set `--orb-press-scale: 0.98` on one as wide as its panel.

## Next

- [Customize](/docs/customize): tokens, slots, swapped parts and components of your own, step by step.
- [Accessibility](/docs/accessibility): what a theme keeps for keyboard and screen reader users.
- [React components](/docs/react): the parts the slots belong to.