> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Styling and Theming

> Theme the drop-in components with CSS variables and color-scheme, or style their class names directly.

`<SchematicStyles />` injects one stylesheet for every drop-in component. It is driven by `--schematic-*` custom properties, follows your `color-scheme` for light and dark, and never wins a cascade against your own tokens. `schematicStylesCss` is the same stylesheet as a string, for a shadow root or a `<style>` you place yourself.

## Tokens

| Token                                                                                       | Controls                                                                                                                                                             |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--schematic-accent`                                                                        | Links, icons, meters, and focus rings                                                                                                                                |
| `--schematic-accent-contrast`                                                               | Text on an accent fill, for your own styles; no element sets one                                                                                                     |
| `--schematic-primary`, `--schematic-primary-contrast`                                       | The filled action, `schematic-cta`                                                                                                                                   |
| `--schematic-background`, `--schematic-card-divider`                                        | Card surface                                                                                                                                                         |
| `--schematic-border`                                                                        | Outlines on controls and small surfaces: chips, the period toggle, selects, notices, tooltips, and form inputs. Cards have no border; they use `--schematic-shadow`. |
| `--schematic-text`, `--schematic-muted`                                                     | Text and secondary text                                                                                                                                              |
| `--schematic-danger`, `--schematic-warning`, `--schematic-meter-track`                      | Status colors and the meter track                                                                                                                                    |
| `--schematic-font-body`, `--schematic-font-heading`, `--schematic-font-link`                | Typefaces: body text, headings, and link actions                                                                                                                     |
| `--schematic-line-height`, `--schematic-line-height-heading`                                | Line heights                                                                                                                                                         |
| `--schematic-surface`                                                                       | The tint behind the payment method pill, feature and credit icons (Pricing Table's included), user avatars, and Metered Features' price strip                        |
| `--schematic-inset`                                                                         | A lighter tint for panels set into a card: a credit's grants, Plan Manager's notice and auto top-up, and the Unsubscribe Button dialog's sidebar                     |
| `--schematic-backdrop`                                                                      | The dialog backdrop, drawn over an 8px blur                                                                                                                          |
| `--schematic-radius`, `--schematic-shadow`, `--schematic-space`, `--schematic-card-padding` | Shape and spacing                                                                                                                                                    |

## Light and dark

The components follow `color-scheme`. Declare it wherever your theme is decided and they come with it, with no attribute of ours to toggle:

```css
:root {
  color-scheme: light;
}
:root:where(.dark) {
  color-scheme: dark;
}
```

That is the whole contract. It works with a class-based switcher, with `color-scheme: light dark` to follow the OS, and with a page that is only ever one of the two. A host that themes without declaring `color-scheme` gets the light palette.

## Overriding a token

Set it anywhere, on `:root`, an ancestor, inside a cascade layer, at any specificity:

```css
:root {
  --schematic-accent: var(--brand);
  --schematic-radius: 12px;
  --schematic-font-body: "Inter", sans-serif;
}
```

The defaults are not declared in a rule; they are `var()` fallbacks inlined at each use. A fallback applies only when the property is set nowhere, so your value cannot lose a cascade to ours. A default declared on `:root` would beat a host's own `@layer base { :root }` tokens outright, because layer order resolves before specificity, and nothing about that failure would be visible.

The cost is that `--schematic-*` is undefined until you set it, so your own CSS cannot read our defaults. `schematicTokensCss` is the palette as a `:root` block if you want them globally; import it deliberately, and put it where your own tokens can still win. `SCHEMATIC_TOKENS` is the same data as an object.

Overriding `background` and `text` alone leaves a card looking half-themed; `card-divider`, `shadow`, and `border` carry the rest.

## One card or several

Each component draws its own card, so components stacked in a column read as separate cards. Wrap them in `schematic-card-group` to merge them into one:

```tsx
<div className="schematic-card-group">
  <UpcomingBill />
  <PaymentMethods />
  <Invoices />
</div>
```

The group draws one card with a `card-divider` line between its components, and between the per-row cards Metered Features and Credit Usage draw. The components must be its direct children, or the line between them does not draw.

## Styling the class names

Skip the stylesheet and write your own against the class names. They are API, and each component's page shows the tree it renders.

The stylesheet carries the Schematic icon font inlined as a `data:` URL, for feature and credit icons, the brand marks on payment methods, the dialog's close control, the tooltips' info trigger, the current plan's check, and the chevrons. If your Content Security Policy sets `font-src`, add `data:` to it, or the glyphs render empty. Every glyph is `aria-hidden`; the dialog's close control, a payment method's remove control, and a tooltip's info trigger are icon-only, so a blocked font leaves them empty.

A sheet of your own has to bring the icon font too. Render `<style>{iconsCss}</style>` once, exported from the same entry as `SchematicStyles`, or the glyphs render empty. The icon package's own stylesheet names its rules differently and does not light them up.

| Class                                                                                                                                                                                                                                                                   | Where                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schematic-element`                                                                                                                                                                                                                                                     | Every component's root, beside the component's own class.                                                                                                                                                                                                                                |
| `schematic-card`                                                                                                                                                                                                                                                        | A card surface: the root of Included Features, Upcoming Bill, Payment Methods, Invoices, and Unsubscribe Button, and each plan, feature, or credit card inside Plan Manager, Metered Features, Credit Usage, and Pricing Table.                                                          |
| `schematic-card-group`                                                                                                                                                                                                                                                  | Yours to add: merges the components inside it into one card.                                                                                                                                                                                                                             |
| `schematic-header`, `schematic-header__title`                                                                                                                                                                                                                           | The heading row and the heading.                                                                                                                                                                                                                                                         |
| `schematic-muted`, `schematic-small`                                                                                                                                                                                                                                    | Secondary and smaller text.                                                                                                                                                                                                                                                              |
| `schematic-chip`, `schematic-badge`                                                                                                                                                                                                                                     | A short inline label, such as a promo code; a filled pill.                                                                                                                                                                                                                               |
| `schematic-cta`                                                                                                                                                                                                                                                         | Filled action; `--outline`, `--ghost`, and `--small` modifiers.                                                                                                                                                                                                                          |
| `schematic-link-button`, `schematic-link-button__label`                                                                                                                                                                                                                 | Inline text action ("See more", "Load more"), and a toggle's label beside its chevron, which takes the hover underline.                                                                                                                                                                  |
| `schematic-chevron`                                                                                                                                                                                                                                                     | The chevron glyph on an expand or collapse toggle.                                                                                                                                                                                                                                       |
| `schematic-meter`, `schematic-meter__fill`                                                                                                                                                                                                                              | A usage meter; `--warning`, `--over`, `--tier`, and `--overage` modifiers follow its `data-tone`.                                                                                                                                                                                        |
| `schematic-row`, `schematic-row__label`, `schematic-row__value`                                                                                                                                                                                                         | A labelled line, such as a balance on Upcoming Bill.                                                                                                                                                                                                                                     |
| `schematic-toggle`, `schematic-toggle__option`, `schematic-select`, `schematic-select__option`                                                                                                                                                                          | Pricing Table's billing period switch, whose selected option carries `aria-pressed="true"`, and its currency picker. A period with a saving wraps its option in `schematic-toggle__tip` beside a `schematic-toggle__tip-content` tooltip.                                                |
| `schematic-tooltip`, `schematic-tooltip__trigger`, `schematic-tooltip__content`                                                                                                                                                                                         | An info glyph that shows its content on hover or focus, such as a hard limit or a price's tiers.                                                                                                                                                                                         |
| `schematic-tiers`, `schematic-tiers__list`, `schematic-tiers__tier`, `schematic-tiers__range`, `schematic-tiers__price`, `schematic-tiers__mode`                                                                                                                        | A price's tiers inside a tooltip: a `<dl>` of range and price pairs, then the volume or graduated note.                                                                                                                                                                                  |
| `schematic-usage-by-user`, `schematic-usage-by-user__title`, `schematic-usage-by-user__list`, `schematic-usage-by-user__user`, `schematic-usage-by-user__avatar`, `schematic-usage-by-user__name`, `schematic-usage-by-user__amount`, `schematic-usage-by-user__toggle` | The per-user breakdown under a feature on Metered Features or a credit on Credit Usage.                                                                                                                                                                                                  |
| `schematic-status`, `schematic-status__message`, `schematic-status__retry`                                                                                                                                                                                              | The error row that replaces a card's content.                                                                                                                                                                                                                                            |
| `schematic-status-note`, `schematic-error`                                                                                                                                                                                                                              | A failure reported under content that is still on screen; error text.                                                                                                                                                                                                                    |
| `schematic-hidden`                                                                                                                                                                                                                                                      | Text read by assistive technology and never seen, such as a loading label.                                                                                                                                                                                                               |
| `schematic-skeleton`, `schematic-skeleton__heading`, `schematic-skeleton__row`, `schematic-skeleton__cell`                                                                                                                                                              | The pending placeholder; each cell names its column on `data-column`.                                                                                                                                                                                                                    |
| `schematic-dialog`, `schematic-dialog__header`, `schematic-dialog__title`, `schematic-dialog__close`, `schematic-dialog__body`                                                                                                                                          | The Checkout dialog, the Unsubscribe Button confirmation, and the Payment Methods dialog, a native `<dialog>` inside the component's root.                                                                                                                                               |
| `schematic-icon`, `schematic-icon--<name>`                                                                                                                                                                                                                              | A glyph from the icon font, always `aria-hidden`: a brand mark, `close`, `chevron-down`, and the rest, named as in `iconsList` from `@schematichq/schematic-icons`. A feature or credit icon that is not a glyph name, such as an emoji, renders as text inside a bare `schematic-icon`. |

A component's root keeps the same class list in every state, and `data-state` is `pending`, `error`, or `ready`. Unsubscribe Button sets `data-state` only on a failed read.

## In the dashboard

The Theming page under Components in the dashboard lists every token with its light and dark default and what it paints.