> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Illustration

> Pick a named empty-state or header illustration from scenario, segment, and trade.

`Illustration` picks a named token SVG from `@servicetitan/anvil2-illustrations` using kebab-case `scenario` or header `context`, plus `segment` and `trade`. Prefer a named import from `@servicetitan/anvil2-illustrations` when you already know the artwork. `Illustration` pulls in every named illustration.

The catalog, filenames, and light/dark import paths live on [Illustrations](/docs/web/illustrations).

## Installation

```shell theme={null}
npm install @servicetitan/anvil2-ext-common
```

`Illustration` depends on `@servicetitan/anvil2-illustrations`. Theme follows `AnvilProvider` through illustration color tokens. There is no `mode` prop and no light/dark file swap.

## Usage

Pass the facts on the component, or set defaults with `IllustrationProvider`. Props override the provider.

```tsx theme={null}
import {
  Illustration,
  IllustrationProvider,
} from "@servicetitan/anvil2-ext-common";

<Illustration scenario="first-use" segment="residential" trade="mechanical" />;

<IllustrationProvider segment="residential" trade="mechanical">
  <Illustration scenario="first-use" />
  <Illustration type="header" context="customer" />
</IllustrationProvider>;
```

## Resolution

Empty states try an exact `segment` + `trade` file, then that segment's evergreen file, then a generic empty state. Generic is used only when `segment` is omitted. If a segment is present and there is no evergreen file, `Illustration` renders nothing and warns in development.

Headers have no generic fallback. `context="project"` also needs `trade`. `context="service-agreements"` exists only for commercial. Customer and location headers use `segment` and ignore `trade`.

| Facts                                                         | Example result                            |
| ------------------------------------------------------------- | ----------------------------------------- |
| `scenario="first-use"`, residential, mechanical               | `EmptyStateResidentialMechanicalFirstUse` |
| `scenario="success"`, residential, mechanical (no trade file) | `EmptyStateResidentialEvergreenSuccess`   |
| `scenario="first-use"` with no `segment`                      | `EmptyStateFirstUse`                      |
| `type="header"`, `context="project"`, residential, mechanical | `HeaderResidentialProjectMechanical`      |
| `type="header"`, `context="customer"`, residential            | `HeaderResidentialCustomer`               |

Missing art returns `null`.

## Accessibility

`Illustration` stays decorative unless you pass a non-empty `alt`. That sets `role="img"` and `aria-label`. Use empty `alt` or omit it when adjacent title and body already explain the state.

```tsx theme={null}
<Illustration scenario="first-use" alt="No jobs yet" />
```

Remaining SVG attributes such as `height` forward to the rendered SVG. Empty-state examples use `height={200}`.

## `Illustration` props

`type` defaults to `"empty-state"`. `scenario` is required for empty states. `context` is required for headers. `segment` and `trade` override `IllustrationProvider`.

| Prop       | Type                                                                                      | Notes                                                         |
| ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `scenario` | `"first-use" \| "error" \| "success" \| "user-cleared" \| "no-search-results"`            | Required when `type` is `"empty-state"`                       |
| `type`     | `"empty-state" \| "header"`                                                               | Defaults to `"empty-state"`                                   |
| `context`  | `"project" \| "customer" \| "location" \| "service-agreements"`                           | Required when `type` is `"header"`                            |
| `segment`  | `"residential" \| "commercial"`                                                           | `"commercial"` only for `service-agreements`                  |
| `trade`    | `"mechanical" \| "exteriors" \| "property-care" \| "emergency-compliance" \| "interiors"` | Required for project headers                                  |
| `alt`      | `string`                                                                                  | Accessible name. Omit or pass `""` to keep the SVG decorative |

## `IllustrationProvider` props

| Prop       | Type                                                                                      | Notes                                         |
| ---------- | ----------------------------------------------------------------------------------------- | --------------------------------------------- |
| `children` | `ReactNode`                                                                               | Nested `Illustration`s inherit these defaults |
| `segment`  | `"residential" \| "commercial"`                                                           | Default customer segment                      |
| `trade`    | `"mechanical" \| "exteriors" \| "property-care" \| "emergency-compliance" \| "interiors"` | Default trade                                 |