# For AI & LLMs (/work/petavue-design-system/docs/ai)

Coding agents build screens faster when they work from the design system instead of guessing. This site gives them the same information people read, in plain text.

## Files for agents [#files-for-agents]

| Address | What it is |
|---|---|
| [/llms.txt](/work/petavue-design-system/llms.txt) | An index of every page, with a one-line summary and a link to its Markdown |
| [/llms-full.txt](/work/petavue-design-system/llms-full.txt) | Every page in one file, for agents that read everything up front |
| `/llms.mdx/docs/<page>/content.md` | One page as Markdown, such as [the Button page](/work/petavue-design-system/llms.mdx/docs/components/button/content.md). "Copy Markdown" at the top of every page copies the same text. |

These files are built from the same MDX that renders this site (`design-system/content/docs`), so they cannot fall out of date with it. Live examples appear on the site only; the Markdown keeps the code next to them.

## Starting an agent [#starting-an-agent]

Give the agent this before it writes any UI:

```text
Before writing UI for this project, read /llms.txt and the pages it links that
match the task (always: Getting started, Colour, Typography, Writing, and the
components you will use). Use components from @/ui and tokens from the CSS
variables. Follow the rules in /llms.mdx/docs/ai/content.md. If something
you need is not in the design system, say so instead of inventing it.
```

## Rules for agents [#rules-for-agents]

1. **Import from `@/ui`.** Never re-create a component that exists there, and never import from a component's folder.
2. **Use tokens.** `var(--color-…)`, `var(--spacing-…)`, `var(--radius-…)`, `var(--shadow-…)`. Do not write hex values, and do not invent token names: if it is not in [Colour](/work/petavue-design-system/docs/foundations/colour) or [Spacing](/work/petavue-design-system/docs/foundations/spacing), it does not exist.
3. **Product palette only.** Primary blue for actions, greys for structure, green, red and orange for status. Never purple for anything new.
4. **Text is 14px or 12px** in the interface. Titles use the type scale. Nothing below 12px.
5. **Menus use the dropdown menu** in `@/components/shadcn/dropdown-menu` with a Petavue Button as the trigger.
6. **Icons are Phosphor**, sized to the text: 14px next to 12px text, 16px next to 14px text.
7. **One primary button per area.** Everything else is `secondary`, `secondaryGhost` or `ghost`.
8. **Copy follows [Writing](/work/petavue-design-system/docs/foundations/writing):** sentence case, no exclamation marks, no taglines, no "powerful" or "seamless", no dashes joining a slogan to a claim.
9. **Class names describe the thing** (BEM: `campaign-card__title`). Tailwind is for page layout.
10. **Do not edit shared components for a one-off.** Style around them with a scoped class, and say what you changed.
11. **Verify in the browser.** Build, open the screen, check the console is clean, and look at it at 1440 and 1280 pixels wide.

## Keeping this site current [#keeping-this-site-current]

- Tokens on the Foundations pages are read from `src/ui/tokens/tokens.css`, `src/ui/colorography/tokens.css` and `src/ui/typography/typography.css`. Change a token there and the site updates.
- Component pages are MDX files in `design-system/content/docs/components`, with live examples in `design-system/app/live`. When you change a component's props, update its page in the same change.
- A new page needs only an MDX file with `title` and `description` at the top, and its name in the folder's `meta.json` to set its place in the sidebar. It then appears in search, in `/llms.txt` and as Markdown automatically.


# Avatar (/work/petavue-design-system/docs/components/avatar)

```jsx
import { Avatar } from "@/ui";
```

Avatar matches the Figma **Avatar** and **Profile** components. Figma splits them in two; in code they are one component with a `type` prop.

## Types [#types]

The fill says who the person is. Use `profile` for the signed-in user, and `admin` or `user` when you list people by role.


```jsx
<Avatar initials="AU" type="profile" />
<Avatar initials="AU" type="admin" />
<Avatar initials="AU" type="user" />
```

| `type` | Fill | Token |
|---|---|---|
| `profile` | #E0EBFE | `--color-primary-100` |
| `admin` | #FCE9F4 | `--color-tag-pink` |
| `user` | #E0FDFF | `--color-tag-blue` |

## Sizes [#sizes]


```jsx
<Avatar initials="AU" size="lg" />
<Avatar initials="AU" size="sm" />
```

| `size` | Circle | Text |
|---|---|---|
| `lg` (default) | 40px | 14px medium |
| `sm` | 24px | 12px regular |

<Callout>

Figma sets the small avatar's initials at 10px. Code uses 12px, because 12px is the smallest text in the product.

</Callout>

## States [#states]

Pass `onClick` and the avatar becomes a button: hovering turns the initials blue. `active` adds a 1px blue ring. Use it while the avatar's menu is open.


```jsx
<Avatar initials="AU" name="Alex Underwood" active={open} onClick={toggleMenu} />
```

| Figma state | In code |
|---|---|
| Rest | default |
| Hover | `:hover` when `onClick` is set |
| Active | `active` |
| Active hover | `active` plus `:hover` |

## In a list [#in-a-list]

Use `sm` beside a 14px name. The role goes in its own column as text, so the colour is never the only signal.


```jsx
<Avatar initials="PS" name="Priya Shah" type="admin" size="sm" />
```

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `initials` | `string` | `""` | One or two letters. Shown in upper case. |
| `name` | `string` | | Full name. Used as the tooltip and the accessible label. |
| `type` | `"profile" \| "admin" \| "user"` | `"profile"` | Sets the fill. |
| `size` | `"lg" \| "sm"` | `"lg"` | 40px or 24px. |
| `active` | `boolean` | `false` | Blue ring. Also sets `aria-pressed` on a button. |
| `onClick` | `function` | | Renders a `<button>` with hover and focus styles. |
| `className` | `string` | `""` | For layout only. |

## Not yet using Avatar [#not-yet-using-avatar]

These places draw their own initials circle. Move them to Avatar when you next touch them:

- `UserProfile` in the menu bar (`.user-profile__avatar`, 32px, which is not a Figma size).
- `settings/user-management/components/Avatar.jsx` (20 to 32px, with five colours picked from the first letter, purple included).
- `my-profile/UserDetails.jsx`.

## Do and don't [#do-and-dont]

- Do pass `name` so screen readers and the tooltip get the full name.
- Do pass `onClick` when the avatar opens something, so it is a real button.
- Don't pick a fill by hashing the name. The fill means a role.
- Don't add more sizes. Use 40px or 24px.


# Banner (/work/petavue-design-system/docs/components/banner)

```jsx
import { Banner } from "@/ui";
```

Banner matches the Figma **Banner** component. Use it for something the person should know about the page they are on, and that stays true until they act or dismiss it. For a short-lived confirmation, use a [Toast](/work/petavue-design-system/docs/components/toast).

## Default [#default]

A title in blue, one or two lines of supporting text, and a close button. Click × to try it.


```jsx
<Banner title="Validate your key definitions" onDismiss={() => setOpen(false)}>
  You have successfully added <strong>10</strong> key definitions. Validate them
  now to ensure accurate results and insights based on your specific business context.
</Banner>
```

Wrap numbers or names in `<strong>` to set them in medium weight, as Figma does with "10".

## Variants [#variants]

Every part except the fill is optional. Leave out `onDismiss` when the banner must stay, change the icon with `icon`, or pass `icon={null}` for text only.


```jsx
<Banner title="HubSpot sync is paused">Campaign numbers stop updating until you reconnect.</Banner>
<Banner title="3 recommendations are ready" icon={Lightning} onDismiss={dismiss} />
<Banner icon={null}>Showing data up to Oct 12. Today's numbers arrive after the nightly sync.</Banner>
```

## Anatomy [#anatomy]

| Part | Spec | Token |
|---|---|---|
| Container | 8px 12px padding, 8px radius, full width | `--color-primary-50` |
| Icon | 18px Phosphor, `fill` weight | `--color-primary-500` |
| Title | 12px medium, 19px line height | `--color-primary-500` |
| Text | 12px regular, 19px line height | `--color-text-primary` |
| Gaps | 8px icon to text, 4px title to text | |
| Dismiss | `Button` `blueGhost` `sm`, 28px, 12px × | |

In Figma the banner sits in a white strip with 16px side and 8px top and bottom padding. That strip belongs to the page layout, so it is not part of the component.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `title` | `string` | | One line. |
| `children` | `ReactNode` | | Supporting text. |
| `icon` | Phosphor icon \| `null` | `Info` | Drawn at 18px, `fill` weight. |
| `onDismiss` | `function` | | Shows the × button. |
| `className` | `string` | `""` | For layout only. |

## Accessibility [#accessibility]

- The banner has `role="status"`, so screen readers announce it when it appears without moving focus.
- The × button is labelled "Dismiss".
- The icon is hidden from screen readers. The title has to carry the meaning.

## Do and don't [#do-and-dont]

- Do say what happened and what to do next. Keep the title under about six words.
- Do show one banner at a time on a page.
- Don't use a banner for errors that block a form. Show those next to the field.
- Don't change the fill to red or green. Banner is blue only; for a coloured status, use a [Notification](/work/petavue-design-system/docs/components/notification).


# Button (/work/petavue-design-system/docs/components/button)

```jsx
import { Button } from "@/ui";
```

## Variants [#variants]

Pick the variant by how important the action is on that screen, not by colour.


```jsx
<Button variant="primary" label="Publish" />
<Button variant="secondary" label="Save as template" />
<Button variant="secondaryGhost" label="Cancel" />
<Button variant="ghost" label="Skip" />
<Button variant="blueGhost" label="View all" />
```

| Variant | Use for |
|---|---|
| `primary` | The one main action in a header, dialog or form. Publish, Save, Send. |
| `secondary` | A second action next to a primary one, or the main action in a quiet area. |
| `secondaryGhost` | Neutral actions with a border: Cancel, Close, filters and menu triggers. |
| `ghost` | Low-emphasis actions in toolbars and rows: Skip, Reject, View all. |
| `blueGhost` | A text-like action that should still read as a link. |

## Status variants [#status-variants]

Use these only when the action itself is destructive or confirms something positive.


```jsx
<Button variant="red" label="Delete page" icon={Trash} />
<Button variant="green" label="Approve" />
```

## Sizes [#sizes]

The four sizes match Figma's Small, Medium, Large and XL. `md` is the default and fits almost everywhere. Use `sm` in dense rows and table cells, `lg` for the main action in a dialog footer, and `xl` only for a page's single main call to action.


```jsx
<Button size="sm" label="Small" />
<Button size="md" label="Medium" />
<Button size="lg" label="Large" />
<Button size="xl" label="Extra large" />
```

| Size | Figma | Height | Padding | Gap | Text | Icon | Icon-only |
|---|---|---|---|---|---|---|---|
| `sm` | Small | 28px | 6px 12px | 6px | 12px regular | 12px | 28 × 28px |
| `md` | Medium | 32px | 6px 12px | 6px | 12px regular | 12px | 32 × 32px |
| `lg` | Large | 36px | 6px 16px | 8px | 14px medium | 16px | 40 × 36px |
| `xl` | XL | 42px | 10px 24px | 12px | 14px medium | 16px | 48 × 42px |

All sizes have an 8px radius.

<Callout>

Figma sets Small's label at 10px. Code uses 12px, because 12px is the smallest text in the product. Figma's Large and XL icon-only buttons are wider than they are tall (40 × 36 and 48 × 42); code follows Figma.

</Callout>

## With an icon [#with-an-icon]

Pass a Phosphor icon component, not an element. Icons sit before the label by default; use `iconPosition="suffix"` for arrows that point to where the action goes. An icon-only button must have an `aria-label`.


```jsx
import { ArrowRight, Plus, Trash } from "@phosphor-icons/react";

<Button variant="primary" label="New page" icon={Plus} />
<Button variant="ghost" label="View all 11" icon={ArrowRight} iconPosition="suffix" />
<Button variant="secondaryGhost" icon={Trash} aria-label="Delete" />
```

Button sizes the icon for you: 12px on `sm` and `md`, 16px on `lg` and `xl`.


## States [#states]

Each variant has four states in Figma: Default, Hover, Pressed and Disabled. In code, Hover is `:hover`, Pressed is `:active`, and Disabled is the `disabled` prop. Hover over and press the buttons above to see them.

| Variant | Default | Hover | Pressed | Disabled |
|---|---|---|---|---|
| `primary` | Primary 500 fill, white text | Primary 800 fill | Primary 300 fill | Grey 100 fill, Grey 300 text |
| `secondary` | White fill, Primary 500 border and text | Primary 100 fill | Primary 50 fill, Primary 100 border, Primary 300 text | Grey 100 fill, Grey 300 text |
| `ghost` | No fill, Grey 600 text | Grey 50 fill, Grey 800 text | No fill, Grey 300 text | No fill, Grey 300 text |
| `blueGhost` | No fill, Primary 500 text | Primary 50 fill, Primary 800 text | No fill, Primary 300 text | No fill, Primary 300 text |

`secondaryGhost`, `red` and `green` are code-only variants with no Figma component yet.

## Disabled [#disabled]

Disable a button when its action cannot run yet, and say why nearby or in a tooltip. Do not hide the button: people should see the action exists.


```jsx
<Button variant="primary" label="Publish" disabled />
```

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `variant` | `"primary" \| "secondary" \| "secondaryGhost" \| "ghost" \| "blueGhost" \| "red" \| "green"` | `"primary"` | |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | |
| `label` | `string` | | The text. `children` also works when you need markup. |
| `icon` | Phosphor icon component | | Rendered at 12px (`sm`, `md`) or 16px (`lg`, `xl`). |
| `iconPosition` | `"prefix" \| "suffix"` | `"prefix"` | |
| `iconWeight` | `"regular" \| "bold" \| "fill" \| …` | `"regular"` | |
| `disabled` | `boolean` | `false` | |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Set `"submit"` inside forms. |
| `className` | `string` | | For layout only (width, margin). Do not restyle the button. |

Any other prop (`aria-*`, `data-*`, `onClick`) is passed to the `<button>`. The ref is forwarded, so a Button can be a menu or tooltip trigger.

## Accessibility [#accessibility]

- It renders a native `<button>`, so keyboard and screen reader support come for free.
- The focus ring uses `--shadow-focus`. Do not remove it.
- Icon-only buttons need `aria-label`. When you wrap one in a Tooltip, pass `describeChild` so the tooltip does not replace that label.

## Do and don't [#do-and-dont]

- Do write labels as a verb and an object: "Publish page", "Add to dashboard".
- Do keep one `primary` per area.
- Don't make a lookalike with a `<div>` or a styled `<a>`. If you need a link that looks like a button, use a Button with `onClick` that navigates.
- Don't override colours with `className`. If no variant fits, the design needs a decision, not a new colour.


# Card Loader (/work/petavue-design-system/docs/components/card-loader)

```jsx
import { CardLoader } from "@/ui";
```

Card Loader matches the Figma **Card Loader Animation**. Use it to fill a panel while something takes several seconds, like building an analysis plan, by showing short tips about the product. In the app it is shown in the workbook chat's plan panel while the plan is getting ready and while modifications are applied.

## Default [#default]

Three cards are stacked, the front one largest. Every 3 seconds the front card drops to the back and the next card grows into its place. The rail on the left shows which card is in front. The buttons on the right go to the previous card, pause or resume, and go to the next card.


```jsx
<CardLoader
  cards={[
    { title: "Understanding your Data", description: "See what data is available...", image: dataPreview },
    { title: "Understanding Key Definitions (KDs)", description: "Standardize how metrics...", image: kdPreview },
    { title: "Petavue Visualization", description: "Create trustworthy charts...", image: vizPreview },
  ]}
/>
```

The first card in `cards` starts in front. Each card needs a unique `title`.

## With a status line [#with-a-status-line]

Card Loader doesn't say what is loading. Put a short status line with a [Spinner](/work/petavue-design-system/docs/components/spinner) under it, as the workbook chat does.


```jsx
<CardLoader cards={tips} />
<div className="status">
  <Spinner size={16} />
  Getting ready...
</div>
```

## Without images [#without-images]

A card without an `image` shows a Grey 100 block in its place. Use it for a draft before the screenshots exist. This example also sets `interval` to 4 seconds.


```jsx
<CardLoader cards={tipsWithoutImages} interval={4000} />
```

## Anatomy [#anatomy]

| Part | Size | Style |
|---|---|---|
| Frame | 500 × 378px | Shrinks to its container's width |
| Front card | 400px wide, 40px from the top | White, image 234px |
| Next card | 364px wide, 20px from the top | White, 269px tall, image 163px |
| Back card | 304px wide, at the top | Grey 50, 206px tall, image hidden behind a Grey 100 block 100px tall |
| Card | 12px padding, 10px gap | 1px Grey 100 border, 8px radius, `0 8px 4px` shadow at 8% |
| Title | 16px / 26px, medium | `--color-text-primary`, one line, cut off with an ellipsis |
| Description | 12px / 19px | `--color-text-secondary` |
| Progress rail | 6px wide, 6px gap | Primary 100 dots; the current card is a 60px Primary 500 bar |
| Buttons | 32px round, 8px gap | Grey 50 fill, 1px Grey 100 border, 12px Grey 600 icon; Grey 100 on hover |

Card images are anchored to the top left and cropped to fill the space, so the top left of a screenshot is what shows. Use screenshots about 2:1 wide.

Cards move with a 0.6s ease. With reduced motion turned on, they switch without moving.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `cards` | `{ title, description, image? }[]` | `[]` | Three cards. Nothing renders when it is empty. |
| `interval` | `number` | `3000` | Milliseconds each card stays in front. |
| `label` | `string` | `"Product tips"` | Accessible name of the carousel. |
| `className` | `string` | | Other props are passed to the root too. |

Card Loader keeps its own place and pause state. It starts again from the first card each time it mounts.

## Differences from Figma [#differences-from-figma]

- Figma has no state after Pause is pressed. Here the Pause button turns into a Play button.
- Figma has no hover state for the buttons. Here they turn Grey 100.
- The back card's fill is Figma's #FCFCFC, which isn't a token. It uses Grey 50 (#F8F9FC).

## Accessibility [#accessibility]

- The root is a `section` with `aria-roledescription="carousel"` and the `label` as its name. Only the front card is exposed to screen readers; the other two are `aria-hidden`.
- While cards change by themselves, changes aren't announced. Once paused, Previous and Next announce the new front card.
- The Pause button stops the cycle, which people need for anything that moves for more than 5 seconds. Keep it.
- Images are decorative (`alt=""`). The title and description carry the content.

## Do and don't [#do-and-dont]

- Do keep each description to one or two lines.
- Do use it only for waits of several seconds. For a short wait, use a [Spinner](/work/petavue-design-system/docs/components/spinner) or [Skeleton](/work/petavue-design-system/docs/components/skeleton).
- Don't use it for content people need to read to continue. It cycles on its own.
- Don't use more or fewer than three cards. The stack is drawn for three.


# Card (/work/petavue-design-system/docs/components/card)

```jsx
import { Card } from "@/ui";
```

Card is a plain `<div>` with a background, a border, rounded corners and a hover effect. It has no padding, header or footer: you add the layout inside it.

<Callout>

No screen imports Card yet. About 20 places in `src/pages` write the same `rounded-xl border border-[var(--border-primary)]` classes by hand. Use Card for new work so the style stays in one place.

</Callout>

## Basic card [#basic-card]

Give it padding and a width with `className`. `p-4` (16px) is the usual padding.


```jsx
<Card className="p-4 w-[300px]">
  <div className="text-[14px] font-medium">Pipeline by channel</div>
  <div className="text-[12px] text-[var(--color-text-secondary)] mt-1">
    Paid search $268K, LinkedIn $191K, Events $140K.
  </div>
</Card>
```

| Property | Value |
|---|---|
| Background | `--bg-tertiary` (#FFFFFF) |
| Border | 1px `--border-primary` (#D4D9EA) |
| Radius | 12px (`rounded-xl`) |
| Padding | None |
| Hover | Shadow `--shadow-card` (0 8px 24px, 15% grey) and a 2px lift |
| Transition | All properties, 200ms |

<Callout>

Card uses the older `--bg-tertiary` and `--border-primary` variables rather than `--color-white` and `--color-grey-200`. The values are the same today.

</Callout>

## A row of metrics [#a-row-of-metrics]

Cards line up well as a row of KPIs. Hover over one to see the lift.


```jsx
<Card className="p-4 w-[200px]">
  <div className="text-[12px] text-[var(--color-text-secondary)]">Sourced pipeline</div>
  <div className="text-[14px] font-semibold">$1.2M</div>
  <div className="text-[12px] text-[var(--color-green)]">+18% vs last quarter</div>
</Card>
```

## A card with an action [#a-card-with-an-action]

Card is not a button or a link. When the card leads somewhere, put a real Button or link inside it, so it can be reached with the keyboard.


```jsx
<Card className="p-4 w-[300px] flex flex-col gap-3">
  <div className="flex items-center justify-between gap-2">
    <span className="text-[14px] font-medium">Q3 webinar series</span>
    <Tag color="success-green">Live</Tag>
  </div>
  <div className="text-[12px] text-[var(--color-text-secondary)]">
    $412K pipeline from 96 leads. Paid search and LinkedIn.
  </div>
  <Button variant="blueGhost" size="sm" label="View campaign" icon={ArrowRight} iconPosition="suffix" onClick={openCampaign} />
</Card>
```

## Turning off the hover [#turning-off-the-hover]

The hover lift is always on, which suggests the card can be clicked. For a card that does nothing on click, override it in `className`. Hover over the card below: it stays still.


```jsx
<Card className="p-4 w-[200px] hover:shadow-none! hover:translate-y-0">
  …
</Card>
```

<Callout>

There is no prop for this. `tailwind-merge` replaces the lift (`hover:translate-y-0` wins over `hover:-translate-y-[2px]`), but it does not see `hover:shadow-none` as clashing with `hover:shadow-[var(--shadow-card)]`, so both stay and the card's shadow wins. The `!` makes the override important. A static card is the more common case, so the hover default works against most uses.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `children` | `ReactNode` | | |
| `className` | `string` | | Merged with `cn` (`clsx` and `tailwind-merge`), so it can override padding, radius and hover. |

Any other prop (`onClick`, `role`, `aria-*`, `data-*`) is passed to the `<div>`.

## Accessibility [#accessibility]

- Card has no role. Screen readers read its contents in order, which is what you want for grouped content.
- Do not put `onClick` on a Card on its own: a `<div>` cannot be focused or used with the keyboard. Put a Button or link inside instead.
- When a list of cards is the main content of a page, give each card a heading so people can jump between them.

## Do and don't [#do-and-dont]

- Do use Card to group one object or one metric: a campaign, an integration, a KPI.
- Do keep padding consistent within a row of cards.
- Don't nest cards inside cards. Use spacing or a divider inside one card.
- Don't change the border colour or radius per screen. If a design needs a different card, that needs a design decision first.
- Don't leave the hover lift on cards that do nothing when clicked.


# Cascader Item (/work/petavue-design-system/docs/components/cascader-item)

```jsx
import { CascaderItem } from "@/ui";
```

Cascader Item matches the Figma **Cascader Component**. It is one row of a picker that goes from a source's tables to their columns, like choosing the columns a definition or analysis should use. Stack rows in a list; each row draws its own line underneath.

## Tables and columns [#tables-and-columns]

Click a table to open its columns. The open table is selected: Primary 50 fill, a 3px blue bar on the left and a medium label. Tick columns from anywhere on the row. The count on each table is how many of its columns are ticked.


```jsx
{tables.map((t) => (
  <CascaderItem
    key={t.id}
    label={t.label}
    logo={t.logo}
    count={picked[t.id]?.length || undefined}
    selected={t.id === open}
    onClick={() => setOpen(t.id)}
  />
))}

{table.columns.map((c) => (
  <CascaderItem
    key={c.id}
    type="column"
    label={c.label}
    tag={c.id}
    info={c.info}
    checked={picked.includes(c.id)}
    onCheckedChange={(on) => toggle(c.id, on)}
  />
))}
```

## History [#history]

`type="history"` shows a clock icon and a time on the right, for recently used tables and columns. Long labels are cut off with an ellipsis.


```jsx
<CascaderItem type="history" label="Accounts" time="2:01 PM" selected />
<CascaderItem type="history" label="Account ID" tag="AccountId" time="1:47 PM" count={2} />
```

## Variants [#variants]


| Figma property | Prop |
|---|---|
| Type: Table | `type="table"` (default), ends in a caret |
| Type: Column | `type="column"`, ends in an info icon when `info` is set |
| Type: History / History (Tag) | `type="history"` with `time`, plus `tag` for the tag version |
| Icon: Source | `logo` (a 16px image) |
| Icon: Check Box | `checked` and `onCheckedChange` |
| Icon: History | Added for `type="history"` |
| Icon: None | Leave out `logo` and `checked` |
| Indicator: Enabled | `count` |
| State: Rest (Selected) | `selected` |

Hover looks the same with or without `selected`, as in Figma.

## Anatomy [#anatomy]

| Part | Size | Style |
|---|---|---|
| Row | 46px tall, 12px × 16px padding (history 12px) | White, 1px Grey 100 line below |
| Hover | | Primary 50 fill |
| Selected | | Primary 50 fill, 3px Primary 500 bar on the left drawn inside the row |
| Label | 14px / 22px | `--color-text-primary`; medium when a table or history row is selected |
| Leading icon | 16px, 8px gap | Logo, checkbox or Grey 900 clock |
| Tag | Small [Tag](/work/petavue-design-system/docs/components/tag) in the Column colour | The column's API name |
| Count | 16px tall, 6px sides, 6px radius | Primary 500 with white 12px text |
| Caret / info | 16px, 12px after the count | Grey 300, Grey 600 when selected |
| Time | 12px / 19px | `--color-text-secondary` |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `type` | `"table" \| "column" \| "history"` | `"table"` | |
| `label` | `string` | | |
| `tag` | `string` | | Column API name. |
| `logo` | `string` | | Image URL for the source logo. |
| `checked` | `boolean` | | Setting it shows a checkbox. |
| `onCheckedChange` | `(checked) => void` | | |
| `count` | `number \| string` | | |
| `info` | `string` | | Column description for the info icon. |
| `time` | `string` | | History rows. |
| `selected` | `boolean` | `false` | The row whose next level is showing. |
| `onClick` | `(e) => void` | | |
| `className` | `string` | | Other props are passed to the root too. |

## Differences from Figma [#differences-from-figma]

- Tag and count text is 12px, not 10px.
- The info icon shows the column description as a browser tooltip. Figma doesn't show what it opens.
- Figma's checkbox rows are never ticked. Ticked rows use the [Checkbox](/work/petavue-design-system/docs/components/checkbox) checked style.

## Accessibility [#accessibility]

- Rows without a checkbox are buttons. The selected one has `aria-current="true"`.
- In checkbox rows the checkbox is the control: it is named by the label and described by `info`. Clicking anywhere else on the row toggles it too.
- The info text is also in the page for screen readers, linked with `aria-describedby`.

## Do and don't [#do-and-dont]

- Do show the source logo on table rows when the picker mixes sources.
- Do use `count` to show how many columns are picked in each table, so people can see their picks without opening every table.
- Don't use it for a short menu of actions. Use [Dropdown Panel](/work/petavue-design-system/docs/components/dropdown-panel).


# Checkbox (/work/petavue-design-system/docs/components/checkbox)

```jsx
import { Checkbox } from "@/ui";
```

## Usage [#usage]

Checkbox is controlled: pass `checked` and flip it in `onChange`. `onChange` receives the native change event; most call sites ignore it and toggle their own state.


```jsx
const [same, setSame] = useState(true);

<Checkbox
  label="Same as SEO title tag"
  checked={same}
  onChange={() => setSame(!same)}
/>
```

The whole row, box and label, is clickable. The label sits 8px to the right of the box.

## Select all [#select-all]

Set `indeterminate` on a parent checkbox when some, but not all, of its children are checked. It shows a dash instead of a tick. Clicking it should check everything; clicking it again when everything is checked should clear everything.


```jsx
const all = picked.length === DASHBOARDS.length;
const some = picked.length > 0 && !all;

<Checkbox
  label="All dashboards"
  checked={all}
  indeterminate={some}
  onChange={() => setPicked(all ? [] : DASHBOARDS)}
/>
{DASHBOARDS.map((d) => (
  <Checkbox key={d} label={d} checked={picked.includes(d)} onChange={() => toggle(d)} />
))}
```

Derive `checked` and `indeterminate` from the children, as above. Checkbox re-applies `indeterminate` after every render, so the dash stays even though the browser clears it on click.

## States [#states]


```jsx
<Checkbox label="Unchecked" checked={false} />
<Checkbox label="Checked" checked />
<Checkbox label="Indeterminate" indeterminate />
<Checkbox label="Unchecked, disabled" checked={false} disabled />
<Checkbox label="Checked, disabled" checked disabled />
<Checkbox label="Indeterminate, disabled" indeterminate disabled />
```

| Figma state | Box | Hover |
|---|---|---|
| Uncheck | 1px `--color-grey-900` border, white | `--color-primary-100` fill, same border |
| Check | `--color-primary-500` fill, white tick | `--color-primary-800` fill |
| Intermediate | `--color-primary-500` fill, white dash | `--color-primary-800` fill |
| Focus (keyboard) | `--shadow-focus` ring around the box | |
| Disabled, unchecked | `--color-grey-200` border | none |
| Disabled, checked or intermediate | `--color-primary-300` fill | none |

The box is 12px square with 1px corners, centred in a 16px space, as in the Figma **Checkbox** component. When both `checked` and `indeterminate` are set, only the dash shows and screen readers hear "mixed". The label is 14px regular `--color-text-primary`, and `--color-text-disabled` when disabled.

There is no error state. If a checkbox must be ticked to continue, such as accepting terms, show the reason in text next to it and keep the submit button disabled until it is ticked.

## Without a visible label [#without-a-visible-label]

In a table row or list where the row's own text names the item, leave out `label` and pass an `aria-label` that names what the checkbox selects.


```jsx
<Checkbox
  aria-label="Select LinkedIn, Q4 retargeting"
  checked={rows.linkedin}
  onChange={() => flip("linkedin")}
/>
<span>LinkedIn, Q4 retargeting</span>
```

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | `""` | Text after the box. When empty, nothing is rendered and you must pass `aria-label`. |
| `checked` | `boolean` | `false` | Controlled. |
| `indeterminate` | `boolean` | `false` | Shows a dash. Takes visual priority over `checked`. |
| `onChange` | `(event) => void` | | Receives the native change event. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Added to the wrapping `<label>`. Use for layout only. |

Any other prop (`name`, `value`, `aria-label`, `aria-describedby`, `ref`) is passed to the `<input type="checkbox">`.

## Accessibility [#accessibility]

- It is a native checkbox, visually hidden, inside a `<label>`. Space toggles it, and screen readers announce checked, unchecked and mixed (indeterminate) states.
- The focus ring shows on keyboard focus only (`:focus-visible`).
- With no `label`, the checkbox has no name unless you pass `aria-label`. Text in a separate `<span>` beside it, as in the dashboard picker in Workbook chat, is not connected and is not read out.
- A group of related checkboxes should sit under a heading or inside a `<fieldset>` with a `<legend>`, so the question is read before the options. Checkbox has no group component.

## Do and don't [#do-and-dont]

- Do use a Checkbox when each option is independent and people can pick any number, including none.
- Do write the label as the thing that becomes true when it is ticked: "Same as SEO title tag", "Include archived campaigns".
- Don't use a Checkbox for a setting that takes effect immediately, such as turning tracking on. Use [Toggle](/work/petavue-design-system/docs/components/toggle).
- Don't use Checkboxes for options where only one can be picked. Use [Radio](/work/petavue-design-system/docs/components/radio).


# Data table (/work/petavue-design-system/docs/components/data-table)

```jsx
import { DataTable } from "@/ui";
```

DataTable takes a list of columns and a list of row objects and renders a table. It sorts on the client, scrolls sideways when the columns do not fit, and scrolls down once there are more than 10 rows. There is no pagination, filtering, selection or row click.

<Callout>

No screen uses DataTable yet. The tables in chat sessions come from `DataTableViewer`, a separate component.

</Callout>

<Callout>

**Style clash.** `src/index.css` has global `.data-table th` and `.data-table td` rules, written for older session tables, and DataTable's root also has the class `data-table`. Those global rules are more specific than DataTable's own CSS, so they win everywhere in the app, including this page. What you see below is what ships today: uppercase 12px headers on `--bg-secondary` (#EEF0F7), 12px JetBrains Mono cells with 6px 10px padding, and cells capped at 240px with an ellipsis. `DataTable.css` intends 12px semibold Poppins headers in `--color-text-secondary` on `--color-grey-50`, and 14px Poppins cells with 12px 16px padding. Renaming the root class would fix it.

</Callout>

## Basic table [#basic-table]

Each column has a `key` that matches a field on the rows and a `label` for the header. Click a sortable header to sort ascending, again for descending.


```jsx
const columns = [
  { key: "campaign", label: "Campaign", sortable: true, width: "200px" },
  { key: "channel", label: "Channel", sortable: true },
  { key: "spend", label: "Spend ($)", sortable: true },
  { key: "leads", label: "Leads", sortable: true },
  { key: "pipeline", label: "Pipeline ($)", sortable: true },
];

const rows = [
  { id: 1, campaign: "Q3 webinar series", channel: "Events", spend: 18400, leads: 96, pipeline: 412000 },
  { id: 2, campaign: "Brand search", channel: "Paid search", spend: 22150, leads: 141, pipeline: 268000 },
  // …
  { id: 5, campaign: "Competitor comparison page", channel: "Organic", spend: null, leads: 52, pipeline: 140000 },
];

<DataTable columns={columns} rows={rows} />
```

Missing values (`null` or `undefined`) show as a dash and always sort to the bottom. Rows use `row.id` as their React key, or their index if there is no `id`, so give rows an `id`.

## How sorting works [#how-sorting-works]

| Values in the column | Compared as |
|---|---|
| Both numbers | Numbers |
| Anything else | Lower-cased strings |

Sorting uses the raw value in the row, and the cell shows that same raw value. There is no separate formatter. So you choose between numbers that sort correctly but show as `412000`, or formatted strings such as `"$412K"` that show well but sort as text (`"$87K"` comes after `"$412K"`). The examples put the unit in the header and keep numbers raw.

A click on the sorted column flips the direction. There is no way to clear the sort except by reloading the component.

## Zebra rows [#zebra-rows]

`zebra` gives every second row a `--color-grey-50` background. On a white table it is a very light stripe.


```jsx
<DataTable columns={columns} rows={rows} zebra />
```

## Components in cells [#components-in-cells]

A cell can hold any React node, such as a Tag. Do not make that column sortable: sorting would compare the nodes as the text `[object Object]`.


```jsx
const columns = [
  { key: "page", label: "Landing page" },
  { key: "status", label: "Status" },
  { key: "visits", label: "Visits", sortable: true },
  { key: "conversion", label: "Conversion (%)", sortable: true },
];

const rows = [
  { id: "a", page: "/q3-webinar", status: <Tag color="success-green">Published</Tag>, visits: 4820, conversion: 6.1 },
  { id: "b", page: "/pipeline-report", status: <Tag color="warning-yellow">Unpublished changes</Tag>, visits: 2310, conversion: 4.4 },
  { id: "c", page: "/abm-demo", status: <Tag color="column">Draft</Tag>, visits: null, conversion: null },
];
```

## Long tables [#long-tables]

With more than 10 rows the body gets a 480px maximum height and scrolls, and the header stays fixed at the top (`stickyHeader`, on by default).


```jsx
<DataTable columns={columns} rows={sixteenWeeksOfNurtureEmails} />
```

<Callout>

The 480px cap was sized for 10 rows of 44px. With the clash above, rows are about 35px, so about 12 fit. With `DataTable.css` alone, rows would be about 47px and about 9 would fit. Either way it is not exactly 10.

</Callout>

## Empty state [#empty-state]

With no rows, the table keeps its header and shows `emptyMessage` in a single centred cell. `DataTable.css` gives that cell 48px of vertical padding, but the global `td` rule cuts it to 6px, so the empty state is a thin row.


```jsx
<DataTable
  columns={columns}
  rows={[]}
  emptyMessage="No campaigns match these filters. Try a wider date range."
/>
```

## Styles [#styles]

| Part | Value |
|---|---|
| Frame | 1px `--color-grey-200` border, 8px radius (`--radius-md`), white background |
| Row hover | `--color-primary-50` on the row, with `--bg-hover` (#EDF2FE) on the cells from the global rule |
| Zebra row | `--color-grey-50` |
| Sort icons | 10px bold carets, `--color-grey-300`, the active one `--color-primary-500` |
| Row divider | 1px `--border-primary` (#D4D9EA) from the global rule; `DataTable.css` intends `--color-grey-100` |

<Callout>

`DataTable.css` colours the sorted column's header `--color-primary-500`, but the global header rule overrides that too, so only the caret turns blue.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `columns` | `{ key, label, sortable?, width? }[]` | `[]` | `width` is applied as the column's `min-width`. |
| `rows` | `object[]` | `[]` | Fields are read by column `key`. Give each row an `id`. |
| `zebra` | `boolean` | `false` | |
| `stickyHeader` | `boolean` | `true` | Only matters once the table scrolls. |
| `emptyMessage` | `string` | `"No data available"` | |
| `className` | `string` | | On the outer wrapper. |

Any other prop (`aria-label`, `id`, `data-*`) goes to the outer `<div>`, not to the `<table>`. The source comment mentions pagination; there is none.

## Accessibility [#accessibility]

- It renders a real `<table>` with `<thead>`, `<th>` and `<td>`, so screen readers can move by row and column.
- The sorted column gets `aria-sort="ascending"` or `"descending"`. Other sortable columns get no `aria-sort`.
- Sortable headers are plain `<th>` elements with a click handler. They cannot be focused or used with the keyboard, so keyboard users cannot sort. Sorting should move into a `<button>` inside each header.
- There is no caption, and `aria-label` lands on the wrapper `<div>`. Put a visible heading right above the table that says what it lists.

## Do and don't [#do-and-dont]

- Do use DataTable for up to a few hundred rows already in memory, such as campaign results for one quarter.
- Do keep numbers raw in sortable columns and put the unit in the header.
- Do write an `emptyMessage` that says why it is empty and what to try.
- Don't mark columns that hold components or formatted strings as sortable.
- Don't use it for large or server-paged data. It has no pagination.
- Don't add the class `data-table` to other elements. It already causes the clash described above.


# Date picker (/work/petavue-design-system/docs/components/date-picker)

```jsx
import { DatePicker } from "@/ui";
```

DatePicker matches the Figma **Date Picker** component, including its day, month and year cells. It is the panel only. Put it in a popover under the field or button that opens it.

The examples on this page fix today at Dec 11, 2024, to match Figma. In the app, leave `today` out and it uses the real date.

## Single date [#single-date]

Click a day to pick it. Today has a blue outline, and the picked day is filled blue. The arrows change the month.


```jsx
const [date, setDate] = useState(null);

<DatePicker value={date} onChange={setDate} />
```

## With Cancel and Apply [#with-cancel-and-apply]

With `footer`, picks are a draft until the person clicks Apply. Use it when a change reloads data, such as a dashboard's date filter.


```jsx
<DatePicker value={applied} footer onApply={setApplied} onCancel={close} />
```

## Range [#range]

`mode="range"` shows two months side by side. The first click sets the start, the second sets the end, and the days between turn light blue. A click before the start swaps them. While you choose the end, the range follows the pointer.


```jsx
const [range, setRange] = useState({ from: null, to: null });

<DatePicker mode="range" value={range} onChange={setRange} />
```

Use `months={1}` when the range fits in one month or space is tight.


## In a popover [#in-a-popover]

Open the picker under a trigger that shows the current value. With a footer, Apply closes it.


```jsx
<Button variant="secondaryGhost" label="Nov 1, 2024 – Nov 30, 2024" onClick={toggle} />
{open && (
  <DatePicker mode="range" value={range} footer onApply={(r) => { setRange(r); close(); }} onCancel={close} />
)}
```

## Month and year menus [#month-and-year-menus]

Click the month or the year in the header to jump. The current month and year are blue, and the one on screen is filled. The year list scrolls to the selected year.

## Cells [#cells]

| Cell | Rest | Hover | Selected |
|---|---|---|---|
| Day | #757A97 text | Primary 50 fill, Primary 500 text | Primary 500 fill, white text |
| Today | Adds a 1px Primary 500 border | | |
| Day in a range | Primary 50 fill, square corners | | |
| Month or year | #757A97 text (Primary 500 when current) | Primary 50 fill, Primary 500 text | Primary 500 fill, white text |

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Panel | 264px wide (512px for two months), 12px padding, 8px radius, white, shadow 0 8px 12px at 10% |
| Header | 20px blue arrows. Month and year in 14px medium, each with a 12px caret |
| Weekdays | 12px primary text, Sunday first |
| Days | 32px tall, 8px radius, 12px text, 4px between weeks |
| Month and year menus | 80px wide, 8px padding, 4px gaps, items 2px 20px with a 4px radius |
| Footer | `ghost` Cancel and `secondary` Apply, both `sm` |

<Callout>

Figma's footer buttons use 10px text. Code uses `sm` Buttons, which are 12px, because 12px is the smallest text in the product.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `mode` | `"single" \| "range"` | `"single"` | |
| `value` | `Date \| null` or `{ from, to }` | | Controlled value. |
| `defaultValue` | same as `value` | | Uncontrolled start value. |
| `onChange` | `function` | | Every pick without a footer; on Apply with one. |
| `months` | `1 \| 2` | `1`, or `2` for a range | |
| `footer` | `boolean` | `false` | Cancel and Apply. Apply stays disabled until the pick is complete. |
| `onApply` | `function` | | Gets the draft. |
| `onCancel` | `function` | | The draft resets to `value`. |
| `today` | `Date` | now | |
| `yearRange` | `[number, number]` | 10 years back to 5 ahead | Years in the year menu. |
| `className` | `string` | `""` | For layout only. |

## Accessibility [#accessibility]

- Every day is a button labelled with the full date, such as "Wednesday, December 11, 2024". Picked days have `aria-pressed`, and today has `aria-current="date"`.
- Only one day is in the tab order. Arrow keys move by a day or a week, Home and End go to the start or end of the week, and Page Up and Page Down change the month. The view follows the focus.
- The month and year menus are listboxes. Escape or a click outside closes them.

## Do and don't [#do-and-dont]

- Do show the chosen date or range on the trigger, so people can see it without opening the picker.
- Do use the footer when picking reloads data.
- Don't use a date picker for a fixed set of periods like "Last 7 days". Use a [Dropdown](/work/petavue-design-system/docs/components/dropdown).


# Dependency dialog (/work/petavue-design-system/docs/components/dependency-dialog)

```jsx
import { DependencyDialog } from "@/ui";
```

DependencyDialog matches the Figma **Dependency Dialog** component. Use it when someone tries to disable or delete a thing that other things still use, such as a column used by Definitions. It is a Small [Dialog](/work/petavue-design-system/docs/components/dialog) with no icon, a collapsible table of dependents and one line on what happens next.

## Modes [#modes]

`mode` sets the rail. In `error` mode the action button is red.


```jsx
<DependencyDialog
  title="Disable Region"
  description="This column is used in the Definitions listed below. To disable it, first delete those Definitions. Once they are deleted, you can disable the column."
  items={[{ name: "Pipeline by region", owner: "John Diego" }, …]}
  footnote="You can't disable this column while these Definitions use it."
  mode="normal"
  onConfirm={goToDefinitions}
  onCancel={close}
  onClose={close}
/>
```

| `mode` | Rail | Action |
|---|---|---|
| `normal` | Primary 500 | `primary` |
| `warning` | #FBBF24 | `primary` |
| `error` | Red | `red` |

## Collapsed [#collapsed]

The toggle shows or hides the table. The blue count stays visible either way, so people know how many items depend on it before they open the list. Pass `defaultExpanded={false}` to start closed.


## Over the page [#over-the-page]

Like Dialog, it is the panel only. Wrap it in a backdrop with `role="dialog"`. See [Opening a dialog](/work/petavue-design-system/docs/components/dialog#opening-a-dialog).


## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Panel | Small Dialog, 460px, no icon |
| Body | 12px text, 0 12px 16px padding, 10px gaps |
| Toggle | 12px caret and label, then the count: Primary 500, white 12px text, 6px radius |
| Table | 1px Grey 100 border, 8px radius. Header on Grey 50 in 12px medium secondary text. Rows in 12px primary text, 60% for the name, scrolling after 95px (about four rows) |
| Footnote | 14px medium |

<Callout>

Figma sets the count at 10px. Code uses 12px, because 12px is the smallest text in the product.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `title` | `string` | | Name the action and the thing: "Disable Region". |
| `description` | `ReactNode` | | What is blocked and how to unblock it. |
| `items` | `{ name, owner }[]` | `[]` | The dependents. |
| `itemLabel` | `string` | `"Definition Details"` | Follows "Show" or "Hide" on the toggle. |
| `columns` | `[string, string]` | `["Definition Name", "Owner"]` | Table headings. |
| `footnote` | `ReactNode` | | One line on the consequence. |
| `mode` | `"normal" \| "warning" \| "error"` | `"normal"` | |
| `defaultExpanded` | `boolean` | `true` | |
| `confirmLabel` | `string` | `"Go to Definitions"` | Take people to where they can fix it. |
| `onConfirm`, `onCancel`, `onClose` | `function` | | |

## Do and don't [#do-and-dont]

- Do make the action take people to the dependents, so they can fix the blocker.
- Do name the owners, so people know who to ask.
- Don't offer to delete the dependents from this dialog.


# Dialog (/work/petavue-design-system/docs/components/dialog)

```jsx
import { Dialog } from "@/ui";
```

Dialog matches the Figma **Dialog_info** component. It is the panel that the library, publishing, workflow review and workbook screens use for confirmations and short forms. It draws the frame: a 4px coloured rail along the top, a state icon, the title and a close button, your content, and a footer with Cancel on the left and Confirm on the right.

<Callout>

Dialog is only the panel. It has no `open` prop, no backdrop, no `role="dialog"`, and it does not handle Escape or focus. You render it when it should show and wrap it yourself, as every screen that uses it does. See [Opening a dialog](#opening-a-dialog). For how it compares with Modal and which to use, see [Modal](/work/petavue-design-system/docs/components/modal).

</Callout>

## Anatomy [#anatomy]

Shown here without its backdrop so you can see the parts.


```jsx
<Dialog size="sm" title="Rename dashboard" confirmLabel="Rename" onClose={close} onCancel={close} onConfirm={save}>
  <TextInput label="Dashboard name" value={name} onChange={(e) => setName(e.target.value)} />
</Dialog>
```

| Part | Style |
|---|---|
| Panel | White, `--radius-lg` (12px) corners, a soft `0 8px 12px` shadow at 10% grey. |
| Rail | 4px top border in `--color-primary-500`, or `--color-orange` (#FBBF24) and `--color-red` for the warning and error states. |
| Header | 16px by 12px padding. A 24px icon in the rail colour, 6px gap, then the title in `--font-size-h2` (16px) semibold, `--color-text-primary`, on one line. A 16px close icon on the right, in a 24px hit area. |
| Body | 16px by 12px padding. Children are stacked with a 24px gap (`--spacing-24`). |
| Footer | A 1px `--color-grey-100` line above, 16px by 12px padding. Cancel is a `ghost` Button, Confirm a `primary` Button. |

## Opening a dialog [#opening-a-dialog]

Keep an open flag in state and render the Dialog inside a backdrop only while it is true. The wrapper gives it the dialog role and a name, closes on Escape and on a click outside, moves focus into the dialog when it opens and back to the trigger when it closes.


```jsx
function PublishDialog({ changes, onPublish, onClose }) {
  const box = useRef(null);

  useEffect(() => {
    const back = document.activeElement;
    box.current?.querySelector("input, textarea, button:not([aria-label='Close'])")?.focus();
    const onKey = (e) => e.key === "Escape" && onClose();
    window.addEventListener("keydown", onKey);
    return () => { window.removeEventListener("keydown", onKey); back?.focus?.(); };
  }, [onClose]);

  return (
    <div className="fixed inset-0 z-[80] grid place-items-center p-4 bg-[rgba(31,33,46,0.45)]" onClick={onClose}>
      <div ref={box} role="dialog" aria-modal="true" aria-label="Publish 3 changes?" onClick={(e) => e.stopPropagation()}>
        <Dialog
          size="md"
          title="Publish 3 changes?"
          confirmLabel="Publish"
          onClose={onClose}
          onCancel={onClose}
          onConfirm={() => { onPublish(); onClose(); }}
        >
          <ChangeList changes={changes} />
          <p>They go to the Recommendations page for everyone who can see this workflow. Nothing changes in your ad accounts until someone applies a recommendation.</p>
        </Dialog>
      </div>
    </div>
  );
}

{open && <PublishDialog changes={changes} onPublish={publish} onClose={() => setOpen(false)} />}
```

Wire all three handlers. `onClose` runs from the close icon and `onCancel` from the Cancel button. Neither closes the dialog by itself.

## Sizes [#sizes]

Pick the size by what is inside, not by how important the dialog is. The examples below open with the wrapper above.


```jsx
<Dialog size="sm" title="Rename workbook" confirmLabel="Rename">…</Dialog>
<Dialog size="md" title="Save as a template" confirmLabel="Save template">…</Dialog>
<Dialog size="lg" title="Import from your website" confirmLabel="Read my website">…</Dialog>
```

| Size | Width | Footer buttons | Use for |
|---|---|---|---|
| `sm` | 460px | `md` | One field or one sentence. The body centres its content and is at least 70px tall. |
| `md` | 650px | `lg` | A short form or a list of what will change. Content is left-aligned. |
| `lg` | 800px | `lg` | Previews and multi-step flows. Content is left-aligned. |

The widths are fixed. On a narrow screen, cap them through `className`, as the workflow review does with `max-width: calc(100vw - 32px)`.

## States [#states]

`state` sets the rail and icon colour, and the icon: Info, Warning or XCircle. In the error state Confirm turns into a red Button, so a destructive action reads as one.


Open them over the page:


```jsx
<Dialog size="sm" state="warning" title="Unsaved changes" confirmLabel="Leave">…</Dialog>
<Dialog size="sm" state="error" title="Delete page?" confirmLabel="Delete">…</Dialog>
```

| State | Rail and icon | Icon | Confirm |
|---|---|---|---|
| `default` | `--color-primary-500` | Info | `primary` |
| `warning` | `--color-orange` | Warning | `primary` |
| `error` | `--color-red` | XCircle | `red` |

Use `confirmDisabled` to grey out Confirm until the form is valid. This is the disabled button Figma draws in its warning and error examples. Use `confirmVariant` to pick another Button variant.

<Callout>

Figma uses Warning and XCircle icons only on Small dialogs. Its Medium and Large dialogs show the Info icon in every state, just recoloured. Code uses the state's icon at every size. Pass `icon={null}` for no icon, as the [Dependency dialog](/work/petavue-design-system/docs/components/dependency-dialog) and [Widget access dialog](/work/petavue-design-system/docs/components/widget-access-dialog) do.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` | 460, 650 or 800px wide. |
| `state` | `"default" \| "warning" \| "error"` | `"default"` | Rail, icon and, for `error`, a red Confirm. |
| `title` | `string` | `""` | Shown on one line and not truncated, so keep it short. |
| `icon` | Phosphor icon \| `null` | by state | `null` hides it. |
| `children` | `ReactNode` | | The body. |
| `cancelLabel` | `string` | `"Cancel"` | |
| `confirmLabel` | `string` | `"Confirm"` | Name the action: "Publish", "Rename", "Save template". |
| `onClose` | `() => void` | | The close icon. |
| `onCancel` | `() => void` | | The Cancel button. |
| `onConfirm` | `() => void` | | The Confirm button. |
| `confirmVariant` | Button variant | `red` for error, else `primary` | |
| `confirmDisabled` | `boolean` | `false` | |
| `footer` | `ReactNode \| false` | | Replaces Cancel and Confirm, or `false` hides the footer. |
| `className` | `string` | | On the panel. Use it for width limits or to adjust `.dialog__body` from your own CSS. |

Other props (`aria-*`, `id`, `data-*`) are passed to the panel. `ref` is not forwarded.

## Accessibility [#accessibility]

What Dialog gives you:

- The close icon is a `<button>` with `aria-label="Close"`. The footer actions are product Buttons.

What the wrapper has to add, because Dialog does not:

- `role="dialog"`, `aria-modal="true"` and a name. The title is a plain `<span>`, so pass the same text as `aria-label` on the wrapper.
- Escape to close. The library and workflow screens add their own key listener. The workbook rename dialog has none, so Escape does nothing there.
- Focus. Move focus into the dialog when it opens (the first field, or the first button) and back to the trigger when it closes, as the example does.
- Focus does not stay inside. Tab moves past the last button and on into the page behind the backdrop. None of the current wrappers trap it.

## Do and don't [#do-and-dont]

- Do use Dialog for new confirmations and short forms, inside the wrapper above.
- Do write the title as a question or an action ("Publish 3 changes?", "Rename dashboard") and the Confirm label as the verb.
- Do say in the body what will happen, including what will not change.
- Don't put a long form or a whole workflow in a dialog. Give it a page.
- Don't open a dialog from inside another dialog.
- Do use the error state for a destructive action, so Confirm is red.
- Don't use the warning state just to draw attention. Use it when going ahead loses something, like unsaved edits.


# Dropdown menu (/work/petavue-design-system/docs/components/dropdown-menu)

This is the product's one dropdown menu. It was added with `shadcn add @reui/c-dropdown-menu-3`, which is built on the Base UI Menu, and then set in Petavue colours: a white panel, `--color-primary-50` behind the highlighted item, primary text, and a blue check on the selected item. ListDropdown, ModelModeMenu and Dropdown are all built on it, so a fix here reaches every menu.

```jsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuDescription,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuGroup,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
  DropdownMenuShortcut,
} from "@/components/shadcn/dropdown-menu";
```

<Callout>

For filters with search and a Reset, Cancel and Apply footer, use the [Dropdown panel](/work/petavue-design-system/docs/components/dropdown-panel). It matches the Figma Dropdown component. This menu is more compact than Figma's: 36px items inside a padded panel, with the check on the right, where Figma has 46px items edge to edge with the checkbox or radio on the left.

</Callout>

## Actions [#actions]

Pass the product Button to the trigger with `render`, so the trigger looks and focuses like every other button. Give each item an `onClick`. The menu closes after an item is chosen.


```jsx
import { CaretDown, CopySimple, FolderSimple, PencilSimple, Trash } from "@phosphor-icons/react";
import { Button } from "@/ui";

<DropdownMenu>
  <DropdownMenuTrigger
    render={<Button variant="secondaryGhost" label="Page actions" icon={CaretDown} iconPosition="suffix" />}
  />
  <DropdownMenuContent>
    <DropdownMenuItem label="Rename" onClick={rename}>
      <PencilSimple size={16} /> Rename
    </DropdownMenuItem>
    <DropdownMenuItem label="Duplicate" onClick={duplicate}>
      <CopySimple size={16} /> Duplicate
    </DropdownMenuItem>
    <DropdownMenuItem label="Move to folder" onClick={move}>
      <FolderSimple size={16} /> Move to folder
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem label="Delete page" variant="destructive" onClick={remove}>
      <Trash size={16} /> Delete page
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

<Callout>

Items use `onClick`, not `onSelect`. Base UI has no `onSelect` on items, so code copied from Radix-based shadcn examples silently does nothing.

</Callout>

When an item starts with an icon, also pass `label` with its plain text. Without it, typing a letter to jump to that item does not find it.

Put a destructive item last, after a separator, with `variant="destructive"`. It is drawn in `--color-error-500` (falling back to `#f93d3d`) with a pale red highlight. Confirm the action in a dialog if it cannot be undone.

## Choosing one value [#choosing-one-value]

For a filter or a setting that shows its current value on the trigger, list the options as items and mark the chosen one with a bold 16px `Check` in `--color-primary-500`. This is how the Recommendations filters and the composer menus work. Put the value on the trigger and say what it is in `aria-label`.


```jsx
import { CaretDown, Check } from "@phosphor-icons/react";

<DropdownMenu>
  <DropdownMenuTrigger
    render={<Button variant="secondary" label={current.label} icon={CaretDown} iconPosition="suffix" aria-label={`Date range: ${current.label}`} />}
  />
  <DropdownMenuContent className="min-w-[200px]">
    {RANGES.map((r) => (
      <DropdownMenuItem key={r.id} aria-current={r.id === range || undefined} onClick={() => setRange(r.id)}>
        <span className="flex-1">{r.label}</span>
        {r.id === range && <Check size={16} weight="bold" className="text-[var(--color-primary-500)]" />}
      </DropdownMenuItem>
    ))}
  </DropdownMenuContent>
</DropdownMenu>
```

A plain item with a check does not tell a screen reader which option is chosen. If that matters, use a radio group instead (see below), which announces the checked option.

## With a description [#with-a-description]

`DropdownMenuDescription` is a Petavue addition. It puts a second line in 12px `--color-grey-500` under an item's label. Use it when the label alone does not say what will happen. Add `items-start` to the item so the icon lines up with the first line.


```jsx
<DropdownMenuContent align="end" sideOffset={6} aria-label="Export">
  {options.map((o) => (
    <DropdownMenuItem key={o.id} className="items-start" onClick={o.run}>
      <o.icon size={16} className="mt-0.5" />
      <span className="flex min-w-0 flex-1 flex-col">
        <span>{o.label}</span>
        <DropdownMenuDescription>{o.description}</DropdownMenuDescription>
      </span>
    </DropdownMenuItem>
  ))}
</DropdownMenuContent>
```

## Groups, labels and shortcuts [#groups-labels-and-shortcuts]

Group related items and name the group with `DropdownMenuLabel`. A label must sit inside a `DropdownMenuGroup`. Separate groups with `DropdownMenuSeparator`.


```jsx
import { DotsThree } from "@phosphor-icons/react";

<DropdownMenu>
  <DropdownMenuTrigger
    render={<Button variant="secondaryGhost" icon={DotsThree} iconWeight="bold" aria-label="Campaign actions" />}
  />
  <DropdownMenuContent className="min-w-[220px]">
    <DropdownMenuGroup>
      <DropdownMenuLabel>Campaign</DropdownMenuLabel>
      <DropdownMenuItem>Open in Google Ads <DropdownMenuShortcut>⌘O</DropdownMenuShortcut></DropdownMenuItem>
      <DropdownMenuItem>Duplicate <DropdownMenuShortcut>⌘D</DropdownMenuShortcut></DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuLabel>Reporting</DropdownMenuLabel>
      <DropdownMenuItem>Add to dashboard</DropdownMenuItem>
      <DropdownMenuItem>Schedule a weekly summary</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

<Callout>

`DropdownMenuShortcut` only shows the text. It does not bind the key. Show a shortcut only when the page really handles it.

</Callout>

## Checkbox items [#checkbox-items]

Use checkbox items to switch several things on or off, such as table columns. The menu stays open after each click so people can change more than one. Checked items show the blue check on the right.


```jsx
<DropdownMenuContent className="min-w-[220px]">
  <DropdownMenuGroup>
    <DropdownMenuLabel>Show in table</DropdownMenuLabel>
    {COLUMNS.map((c) => (
      <DropdownMenuCheckboxItem key={c} checked={shown.includes(c)} onCheckedChange={(on) => toggle(c, on)}>
        {c}
      </DropdownMenuCheckboxItem>
    ))}
  </DropdownMenuGroup>
</DropdownMenuContent>
```

## Radio items [#radio-items]

Use a radio group to choose one value when you want the choice announced as checked. Radio items stay open after a click by default. Pass `closeOnClick` when choosing should close the menu, as most single-choice menus should.


```jsx
<DropdownMenuRadioGroup value={attribution} onValueChange={setAttribution}>
  <DropdownMenuRadioItem value="first" closeOnClick>First touch</DropdownMenuRadioItem>
  <DropdownMenuRadioItem value="last" closeOnClick>Last touch</DropdownMenuRadioItem>
  <DropdownMenuRadioItem value="linear" closeOnClick>Linear</DropdownMenuRadioItem>
  <DropdownMenuRadioItem value="w" closeOnClick>W-shaped</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
```

## Sub menus [#sub-menus]

A sub menu opens to the right on hover or with the right arrow key. Keep to one level. If you need a second level, the choice probably belongs in a dialog.


```jsx
<DropdownMenuContent className="min-w-[200px]">
  <DropdownMenuItem onClick={downloadCsv}>Download as CSV</DropdownMenuItem>
  <DropdownMenuSub>
    <DropdownMenuSubTrigger>Add to dashboard</DropdownMenuSubTrigger>
    <DropdownMenuSubContent>
      {dashboards.map((d) => (
        <DropdownMenuItem key={d.id} onClick={() => addTo(d)}>{d.name}</DropdownMenuItem>
      ))}
    </DropdownMenuSubContent>
  </DropdownMenuSub>
</DropdownMenuContent>
```

## Placement [#placement]

The panel opens below the trigger, lined up with its left edge, 4px away. Use `align="end"` for triggers on the right of a header or row, so the panel stays on screen. Use `side="top"` for triggers at the bottom of the screen, such as a composer. If there is not enough room, the panel flips to the other side by itself.


```jsx
<DropdownMenuContent align="start">…</DropdownMenuContent>
<DropdownMenuContent align="end">…</DropdownMenuContent>
<DropdownMenuContent side="top" sideOffset={8}>…</DropdownMenuContent>
```

The panel is at least as wide as the trigger and at most 360px (or 92% of the screen). It grows to fit its longest item, so set `min-w-[…]` through `className` when a short list from a small trigger looks cramped. It scrolls when it is taller than the space available. Set a `max-h-[…]` for long lists.

## States [#states]


```jsx
<DropdownMenuItem disabled className="items-start">
  <span className="flex flex-col">
    <span>Publish to Recommendations</span>
    <DropdownMenuDescription>Approve the latest run first</DropdownMenuDescription>
  </span>
</DropdownMenuItem>

<DropdownMenuTrigger disabled render={<Button variant="secondary" label="Export" icon={CaretDown} iconPosition="suffix" />} />
```

| State | Look |
|---|---|
| Default | 14px `--color-text-primary` on white, 8px by 10px padding, 6px corners. |
| Highlighted (hover or arrow keys) | `--color-primary-50` background. |
| Checked | Bold 16px check in `--color-primary-500`, 10px from the right edge. |
| Disabled item | 50% opacity. Arrow keys still reach it, but it cannot be chosen. Say why in a description. |
| Disabled trigger | Set `disabled` on `DropdownMenuTrigger`. The Button shows its own disabled style. |
| Open sub menu trigger | Keeps the `--color-primary-50` background while its sub menu is open. |

## Props [#props]

### DropdownMenu [#dropdownmenu]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `open` | `boolean` | | Controlled open state. Leave it out unless you need to open or close the menu from code. |
| `onOpenChange` | `(open, details) => void` | | |
| `defaultOpen` | `boolean` | `false` | |
| `modal` | `boolean` | `true` | While open, the page does not scroll and clicks outside only close the menu. |
| `loopFocus` | `boolean` | `true` | Arrow keys wrap from the last item to the first. |
| `disabled` | `boolean` | `false` | |

### DropdownMenuTrigger [#dropdownmenutrigger]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `render` | element | | Pass `<Button … />`. Its props are merged with the trigger's. Children of the trigger become the Button's children. |
| `disabled` | `boolean` | `false` | |
| `openOnHover` | `boolean` | `false` | Avoid. Menus in the product open on click. |

### DropdownMenuContent [#dropdownmenucontent]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `align` | `"start" \| "center" \| "end"` | `"start"` | |
| `alignOffset` | `number` | `0` | |
| `side` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | |
| `sideOffset` | `number` | `4` | The product uses `4` or `6`, and `8` above a composer. |
| `className` | `string` | | Width and height only, such as `min-w-[240px] max-h-[320px]`. |
| `aria-label` | `string` | | The panel is labelled by its trigger already. Add this when the trigger text is a value rather than a name. |

It renders in a portal at `z-index: 2000`, with a 1px `--color-grey-200` border, 8px corners, 6px padding and a `0 8px 24px rgba(31, 33, 46, 0.12)` shadow.

### DropdownMenuItem [#dropdownmenuitem]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `onClick` | `(event) => void` | | Runs when the item is chosen by mouse, Enter or Space. |
| `variant` | `"default" \| "destructive"` | `"default"` | |
| `disabled` | `boolean` | `false` | |
| `label` | `string` | | The text used when someone types to jump to an item. Set it when the item starts with an icon. |
| `closeOnClick` | `boolean` | `true` | |
| `inset` | `boolean` | | Adds 32px left padding so text lines up with items that have an icon. Also on Label, CheckboxItem, RadioItem and SubTrigger. |

### Other parts [#other-parts]

| Part | Props | Notes |
|---|---|---|
| `DropdownMenuCheckboxItem` | `checked`, `onCheckedChange(checked)`, `defaultChecked`, `disabled`, `closeOnClick` (default `false`) | |
| `DropdownMenuRadioGroup` | `value`, `onValueChange(value)`, `defaultValue` | |
| `DropdownMenuRadioItem` | `value` (required), `disabled`, `closeOnClick` (default `false`) | |
| `DropdownMenuSub` | `open`, `onOpenChange` | Wraps a SubTrigger and SubContent. |
| `DropdownMenuSubTrigger` | `disabled`, `openOnHover` (default `true`), `delay` (default `100`) | Adds a 14px caret on the right. |
| `DropdownMenuSubContent` | Same as Content | Defaults to `side="right"`, `alignOffset={-3}`, `sideOffset={0}`, min width 96px. |
| `DropdownMenuLabel` | `className`, `inset` | 12px medium `--color-grey-500`. Must be inside a Group. |
| `DropdownMenuDescription` | `className` | 12px, 18px line height, `--color-grey-500`. A plain `<span>`. |
| `DropdownMenuShortcut` | `className` | 12px `--color-grey-500`, pushed to the right. Text only. |
| `DropdownMenuSeparator` | `className` | 1px `--color-grey-100`, full width of the panel. |
| `DropdownMenuGroup` | | Groups items for screen readers. |

## Accessibility [#accessibility]

- The trigger gets `aria-haspopup="menu"` and `aria-expanded`. The panel has `role="menu"` and is labelled by the trigger.
- Enter, Space or the down arrow on the trigger opens the menu and highlights the first item. The up arrow opens it on the last item.
- Up and down arrows move through items and wrap around. Home and End jump to the first and last. Typing a letter jumps to the next item that starts with it.
- Enter or Space chooses the highlighted item. The menu closes and focus returns to the trigger.
- Escape closes the menu and returns focus to the trigger. Inside a sub menu, Escape or the left arrow closes only the sub menu.
- The right arrow opens a sub menu and moves into it.
- Tab closes the menu and moves focus on to the next control on the page.
- Checkbox and radio items are announced as `menuitemcheckbox` and `menuitemradio` with `aria-checked`. Plain items with a drawn check are not, so use `aria-current` on them at least.
- An icon-only trigger needs `aria-label`, as in the campaign actions example.

## Do and don't [#do-and-dont]

- Do use the product Button as the trigger, through `render`.
- Do write items as a verb and an object: "Duplicate page", "Add to dashboard".
- Do put destructive items last, after a separator.
- Do use `align="end"` for triggers near the right edge.
- Don't build a menu from a `<div>` and a click handler, or bring in another menu library. Use this one.
- Don't nest more than one level of sub menus.
- Don't restyle items with colour classes. If a menu needs a new look, change it here so every menu gets it.


# Dropdown panel (/work/petavue-design-system/docs/components/dropdown-panel)

```jsx
import { DropdownPanel } from "@/ui";
```

DropdownPanel matches the Figma **Dropdown** and **Dropdown Element** components: a 260px list with optional search and an Apply footer. Use it for filters, where people pick several things and apply them together. For a short menu of actions or a single choice that applies at once, use the product [Dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu).

It is the panel only. Open it under a trigger the way the [Date picker](/work/petavue-design-system/docs/components/date-picker#in-a-popover) does.

<Callout>

This replaces the `DropdownMenu` that `@/ui` used to export. That was an unfinished static version of the same Figma panel, and nothing used it. The name clashed with the product's Dropdown menu, so it is gone.

</Callout>

## Actions [#actions]

With the default `type`, a click calls `onSelect` with the item's value. Items can have a 16px icon on the left and a caret on the right when they open a submenu.


```jsx
<DropdownPanel
  items={[
    { value: "rename", label: "Rename", icon: PencilSimple },
    { value: "move", label: "Move to folder", icon: FolderSimple, submenu: true },
  ]}
  onSelect={run}
/>
```

## Several choices, with Apply [#several-choices-with-apply]

`type="checkbox"` puts a checkbox on each item. With `footer`, ticks are a draft until Apply. Cancel goes back to what was applied, and Reset clears every tick. Search to filter the list, and try a word that matches nothing.


```jsx
<DropdownPanel type="checkbox" items={channels} value={applied} searchable footer onApply={setApplied} />
```

## One choice [#one-choice]

`type="radio"` puts a radio on each item. Without a footer, `onChange` runs on every click.


```jsx
<DropdownPanel type="radio" items={periods} value={period} onChange={setPeriod} />
```

## Format hints and logos [#format-hints-and-logos]

`hint` shows a format on the right, in italic on a grey pill with an info icon. Use it for fields where people type a value later, like dates. `logo` shows a 16px integration logo in place of an icon.


```jsx
{ value: "close", label: "Close date", hint: "yyyy/mm/dd", hintInfo: "Dates use the workspace format" }
{ value: "salesforce", label: "Salesforce", logo: "/logos/integrations/salesforce.png" }
```

## Search [#search]


| Figma state | What shows |
|---|---|
| Search Bar=No | The list, five items tall, then the footer |
| Search Bar=Yes | A search field (Grey 200 border) above a list four items tall |
| Searching | Blue border, a clear button, and "Search results for “term”" |
| Search Empty | "No results for “term”" and a Clear search button |

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Panel | 260px, white, 8px radius, shadow 0 8px 12px at 10% |
| Item | 12px by 16px padding (46px tall), 14px text, Primary 50 on hover |
| Item extras | 16px checkbox, radio, icon or logo on the left with a 12px gap; 16px caret on the right |
| Search | 12px 12px 6px around a 32px field, 12px text and icons |
| Status line | 12px secondary text, the term in medium primary text |
| Footer | 42px, 0.5px Grey 100 line above. Reset is a `ghost` Button; Cancel `secondary` and Apply `primary`, all `sm` |

<Callout>

Figma's footer and Clear search buttons use 10px text. Code uses `sm` Buttons, which are 12px, because 12px is the smallest text in the product.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `type` | `"default" \| "checkbox" \| "radio"` | `"default"` | |
| `items` | `{ value, label, icon?, logo?, hint?, hintInfo?, submenu?, disabled? }[]` | `[]` | |
| `value` | `string \| string[] \| null` | | A string for radio, an array for checkbox. |
| `onSelect` | `function` | | Default type only. |
| `onChange` | `function` | | Every change without a footer; on Apply with one. |
| `searchable` | `boolean` | `false` | |
| `searchPlaceholder` | `string` | `"Search Item"` | |
| `footer` | `boolean` | `false` | |
| `onApply`, `onCancel`, `onReset` | `function` | | |
| `className` | `string` | `""` | For layout only. |

## Accessibility [#accessibility]

- Items are buttons with `menuitem`, `menuitemcheckbox` or `menuitemradio` roles and `aria-checked`.
- Down from the search field moves into the list. Up and Down move between items, and Up from the first item goes back to search.
- The search status line is a live region, so screen readers hear whether anything matched.


# Dropdown (/work/petavue-design-system/docs/components/dropdown)

```jsx
import { Dropdown } from "@/ui";
```

Dropdown is the form select. Its trigger looks like a [Text input](/work/petavue-design-system/docs/components/text-input), and its list is the product's [Dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu) (Base UI, in `src/components/shadcn/dropdown-menu.jsx`). Use it inside forms and settings. For a menu of actions on a button, use Dropdown menu directly.

## Usage [#usage]

Pass `options` as `{ value, label }` objects and keep the chosen `value` in state. Unlike Text input, `onChange` receives the option's `value`, not an event, so you can pass a state setter straight in.


```jsx
const FORM_TARGETS = [
  { value: "hubspot", label: "HubSpot · create or update the contact" },
  { value: "email", label: "Email the workspace owner" },
  { value: "both", label: "HubSpot and email" },
];

const [target, setTarget] = useState("hubspot");

<Dropdown
  label="Send form submissions to"
  options={FORM_TARGETS}
  value={target}
  onChange={setTarget}
/>
```

The chosen option shows a blue check (`--color-primary-500`) in the list. The trigger fills the width of its container, and the list is at least as wide as the trigger and at most 360px.

## No value yet [#no-value-yet]

When `value` is empty, or does not match any option, the trigger shows the `placeholder` in `--color-text-disabled`. Write the placeholder as an instruction: "Choose a channel". Lists taller than 280px scroll.


```jsx
const [channel, setChannel] = useState("");

<Dropdown
  label="Channel"
  placeholder="Choose a channel"
  options={CHANNELS}
  value={channel}
  onChange={setChannel}
/>
```

<Callout>

Always pass both `label` and `placeholder`. They default to the literal text "Form label" and "Placeholder".

</Callout>

There is no way to clear a choice once one is made. If "none" is a valid answer, add it as an option, such as `{ value: "none", label: "Don't send anywhere" }`.

## Validation [#validation]

`error` turns the trigger border red and `errorMessage` shows under it. Show the error after someone has tried to submit, not before they have had a chance to pick.


```jsx
<Dropdown
  label="Count pipeline from"
  placeholder="Choose a stage"
  options={STAGES}
  value={stage}
  onChange={setStage}
  error={!stage}
  errorMessage="Choose the stage that counts as pipeline."
/>
```

## States [#states]


```jsx
<Dropdown label="Placeholder" placeholder="Choose a period" options={periods} value="" />
<Dropdown label="Selected" options={periods} value="q4" />
<Dropdown label="Error" placeholder="Choose a period" options={periods} value="" error errorMessage="Choose a reporting period." />
<Dropdown label="Disabled" options={periods} value="q4" disabled />
```

| State | Trigger | Notes |
|---|---|---|
| Placeholder | `--border-thin` `--color-grey-200`, white | Placeholder text in `--color-text-disabled` |
| Selected | Same, value in 14px `--color-text-primary` | Long labels are cut with an ellipsis |
| Focus and open | 1px `--color-primary-500` and `--shadow-focus` | The caret turns 180° while the list is open |
| Error | 1px `--color-red`, focus ring `--shadow-error-focus` | Message 12px medium `--color-red` |
| Disabled | No border, `--color-grey-50` | Label, value and caret in `--color-text-disabled` / `--color-icon-disabled`. The list cannot open. |

The trigger is 44px tall with 10px by 16px padding and `--radius-md` corners, the same as Text input, so the two line up in a form. The list opens 4px below the trigger: a white panel with a 1px `--color-grey-200` border, 12px corners, 6px padding and a soft shadow. Options are 36px rows of 14px text, highlighted with `--color-primary-50` on hover or keyboard focus.

<Callout>

An errored Dropdown keeps its red border while open but gets the blue `--shadow-focus` ring around it, because the open style and the error style each set half of the look. It reads as a mix of the two states.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | `"Form label"` | Names the trigger through `aria-labelledby`. |
| `placeholder` | `string` | `"Placeholder"` | Shown when no option matches `value`. |
| `options` | `{ value: string, label: string }[]` | `[]` | Options cannot be disabled or grouped, and have no icon or description. |
| `value` | `string` | `""` | The selected option's `value`. |
| `onChange` | `(value: string) => void` | | Called with the picked option's `value`. Picking the current option calls it again. |
| `error` | `boolean` | `false` | Red border on the trigger. |
| `errorMessage` | `string` | `""` | Shown under the trigger only when `error` is true. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Added to the wrapper `<div>`. Use for layout only. |

Any other prop is spread onto the wrapper `<div>`, not the trigger button. An `aria-label` or `id` passed to Dropdown therefore does not name or identify the control.

## Accessibility [#accessibility]

- The trigger is a native `<button>` named by the visible label. Enter, Space or the Down arrow opens the list; arrow keys move between options; Enter picks; Escape closes and returns focus to the trigger. Typing a letter jumps to the first option starting with it.
- The list is a menu (`role="menu"` with `menuitem` options), not a `listbox`. Screen readers announce it as a menu, and the chosen option is shown with a check icon only, so the selection is not announced inside the list. The trigger text does say the current value.
- The label is a `<label>` element without `htmlFor`, so clicking the label does not focus or open the Dropdown.
- `error` does not set `aria-invalid` on the trigger, and the message is not linked to it. The message has `role="alert"`, so it is announced when it first appears, but not when someone later tabs back to the field.
- If the design has no visible label, there is currently no clean way to name the trigger, since `aria-label` lands on the wrapper. Keep a visible label.

## Do and don't [#do-and-dont]

- Do use a Dropdown for one choice from four or more options, or when the options are long.
- Do keep option labels short and parallel: "Q3 2026", "Q4 2026", not a sentence each.
- Don't use a Dropdown for two or three options that people should compare at a glance. Use [Radio](/work/petavue-design-system/docs/components/radio) so every option is visible.
- Don't use a Dropdown to trigger actions such as "Duplicate" or "Delete". Use [Dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu) on a button.
- Don't build a select from a TextInput and a popover. If Dropdown is missing something you need, such as search or multi-select, raise it so the component gains it once.


# Filters (/work/petavue-design-system/docs/components/filters)

```jsx
import { FilterChip, FilterMenu, OperatorList, describeFilterValue } from "@/ui";
```

These match the Figma **↪ Filters** page: Report Chips, Operators, Value Dropdown and Filter Menu. A report shows its filters and groupings as chips. Clicking a filter chip opens a FilterMenu under it, where people pick an operator and a value, then Apply.

## Try it [#try-it]

Click a chip to edit it, × to remove it, or add a filter. Apply updates the chip, and Cancel on a new filter drops it.


```jsx
<FilterChip
  field="Industry"
  operator={filter.operator}
  value={describeFilterValue(filter)}
  selected={open}
  onClick={toggle}
  onRemove={remove}
/>
{open && (
  <FilterMenu field="Industry" type="enum" options={industries} value={filter} onApply={save} onCancel={close} />
)}
```

## Chips [#chips]

A filter chip shows a funnel, the field, the operator's symbol and the value in grey. A group chip shows a stacked-cards icon and the field. Hover shows the whole filter in a tooltip, since long values are cut off. The remove button tints and says "Remove" on hover. `selected` draws a blue border while the chip's menu is open.


```jsx
<FilterChip field="Industry" operator="equals" value="Technology" onRemove={remove} />
<FilterChip type="group" field="Account Category" onRemove={remove} />
```

| Figma state | In code |
|---|---|
| Rest | White, 1px Grey 100 border |
| Hover | Primary 50 fill, tooltip with the whole filter |
| Remove | Primary 100 behind the ×, "Remove" tooltip |
| Selected | `selected`: white with a Primary 500 border |

## Operators [#operators]

Each data type has its own operators. The list shows a radio, the operator's symbol and its name, and scrolls after five rows.


| Type | Operators |
|---|---|
| `multipicklist` | all, any, not in, is null, is not null |
| `enum` | in, not in, contains, starts with, ends with, is null, is not null |
| `boolean` | equals, not equals, is null, is not null |
| `number` | equals, not equals, greater or equal, less or equal, greater than, less than, is null, is not null, in, not in, between |
| `string` | in, not in, contains, does not contain, starts with, ends with, is null, is not null |
| `date` | equals, not equals, is null, is not null, between |

The symbols are the SVGs from Figma, kept in `Filters/icons`. Our Phosphor version (2.0.15) does not have the math icons. Equals and is null use Phosphor's `Equals` and `NumberZero`.

<Callout>

Figma spells one operator "does not contains". Code says "does not contain".

</Callout>

## Filter menu [#filter-menu]

The field changes with the type and the operator. Pick a field below and try each operator.


| Operator takes | Value field |
|---|---|
| One value (text, number) | A text input, "Enter value". Enter applies. |
| Several (in, not in) | Type a value and press Enter to add it as a tag; Backspace removes the last one. This is Figma's Multivalue state. |
| Two (between) | From and To inputs, with a light blue underline on the one in focus. |
| A pick (enum, multipicklist) | "Select value" opens a list with All and a checkbox per option. All shows a dash when some are picked. |
| True or false (boolean) | "Select value" opens True and False as radios. |
| A date | "Select date" opens the date list, grouped into Custom, Calendar Year, Fiscal Year, Fiscal Quarter, Calendar Month, Calendar Week and Calendar Days. Date, Before (Date) and After (Date) open the [Date picker](/work/petavue-design-system/docs/components/date-picker). Equals also offers Before and After. |
| Two dates (between) | "Start date — End date" opens a two-month range picker. |
| Nothing (is null, is not null) | No value. Apply works straight away. |

Apply stays disabled until the filter is complete. For a number field, anything that is not a number turns the field red and shows "Invalid input. Please enter numbers only."

<Callout>

Figma does not show how to enter the N in presets like "Last N Days", or how to pick a year, quarter or month for Year, Quarter Year and Month Year. In code, these presets are saved by name only for now.

</Callout>

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Chip | 6px 10px padding, 8px radius, 4px gaps, 14px text. Icons 12px in 20px boxes |
| List | 220px for operators, 300px for values, 320px for dates. 46px rows, shadow 0 8px 24px at 10% |
| Menu | 500px, 8px radius, shadow 0 8px 12px at 10% |
| Title | `Modify {field}`, 16px medium, 6px 12px 0 padding |
| Field | 42px, 1px Grey 200 border (Primary 500 when open, red on error), 8px radius, 10px 16px padding including the border. 20px operator symbol and caret, a 20px divider, then the value in 14px |
| Tags | Primary 100, 2px 10px padding, 8px radius, 14px text, 12px × |
| Footer | "Include Empty Values" (12px, with a help icon) on the left, Cancel and Apply (`sm`) on the right, 12px apart |

<Callout>

Figma uses 10px for the date group labels and the footer buttons. Code uses 12px, because 12px is the smallest text in the product.

</Callout>

## Props [#props]

**FilterChip**

| Prop | Type | Default | Notes |
|---|---|---|---|
| `type` | `"filter" \| "group"` | `"filter"` | |
| `field` | `string` | | |
| `operator` | operator id | `"equals"` | Filter only. |
| `value` | `string` | | Use `describeFilterValue(filter)`. |
| `selected` | `boolean` | `false` | |
| `onClick`, `onRemove` | `function` | | No `onRemove`, no ×. |

**FilterMenu**

| Prop | Type | Default | Notes |
|---|---|---|---|
| `field` | `string` | | |
| `type` | `"string" \| "number" \| "enum" \| "multipicklist" \| "boolean" \| "date"` | `"string"` | |
| `options` | `string[]` | `[]` | For `enum` and `multipicklist`. |
| `value` | `{ operator, values, includeEmpty }` | | The applied filter. |
| `onApply` | `function` | | Gets `{ operator, values, includeEmpty }`. |
| `onCancel` | `function` | | |

**OperatorList**: `type`, `value`, `onChange`.

`describeFilterValue({ operator, values })` returns the chip text: one or two values joined, "Technology +2" for more, "10000 – 50000" for between, and nothing for is null.

## Accessibility [#accessibility]

- The chip is two buttons: the chip itself (`aria-expanded` while its menu is open) and Remove, labelled with the whole filter.
- The operator button is labelled with the current operator, such as "Operator: in". Lists are listboxes with `aria-selected`.
- Escape or a click outside closes an open list without closing the menu.
- The number error is announced as an alert.


# Integration card (/work/petavue-design-system/docs/components/integration-card)

```jsx
import { IntegrationCard } from "@/ui";
```

IntegrationCard matches the Figma **Integration Card** component. It is used on the standalone Settings page. The real Integrations page in `settings/integrations` still has its own card component, which reads `cardData` and runs the connect flow. Move it onto this one when you next work there.

## States [#states]

The state decides the action. Each card shows exactly one.


```jsx
<IntegrationCard name="Slack" logoSrc={slack} category="Database Management" status="not-connected" description="…" onConnect={connect} />
<IntegrationCard … status="connected" onConnect={openDetails} />
<IntegrationCard … status="coming-soon" onNotify={notifyMe} />
```

| `status` | Header | Action |
|---|---|---|
| `not-connected` | Name | `primary` Button, "Connect" |
| `connected` | Name and a green SealCheck | `secondary` Button, "View Details" |
| `coming-soon` | Name and a `blueGhost` "Notify Me" Button with a bell | Light blue "Coming Soon" label that cannot be clicked |

`onConnect` runs for both Connect and View Details. Check `status` in your handler to tell them apart.

## Categories [#categories]

Each category has its own tag tint, taken from Figma. Pass the category name and the tint follows. Use `categoryColor` with any [Tag](/work/petavue-design-system/docs/components/tag) colour name for a category Figma does not list.


| Category | Tint | Token |
|---|---|---|
| Database Management | #E0FDFF | `--color-tag-blue` |
| Customer Engagement | #E8FFE0 | `--color-tag-green` |
| Marketing Automation | #FCE9F4 | `--color-tag-pink` |
| Web Analytics | #FFEFE0 | `--color-tag-orange` |
| CRM | #EEE0FF | `--color-tag-purple` |
| Project Management Insights | #EBFFF3 | `--color-tag-success-green` |

<Callout>

Figma calls the Web Analytics tint "Tags/Yellow", but its hex (#FFEFE0) is our `--color-tag-orange`. Code goes by the hex.

</Callout>

## Try it [#try-it]

Click Connect, then View Details, to switch the state.


## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Card | 400px wide, 24px padding, 16px gaps, white, 8px radius, no border |
| Header | 32px tall. Logo 24px, 16px gap to the name (14px medium) |
| Category | 12px text on the category tint, 2px 12px padding, 12px radius |
| Description | 12px secondary text, three lines (56px) at most |
| Action | Medium Button, 32px |

The card has no border, so put it on a grey page (`--color-grey-50`), as Settings does.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `name` | `string` | `"Slack"` | |
| `logoSrc` | `string` | | Square logo, shown at 24px. Files are in `public/logos/integrations`. |
| `category` | `string` | `""` | Hidden when empty. |
| `categoryColor` | Tag colour name | from `category` | Falls back to `blue`. |
| `description` | `string` | `""` | Cut to three lines. |
| `status` | `"not-connected" \| "connected" \| "coming-soon"` | `"not-connected"` | |
| `onConnect` | `function` | | Connect and View Details. |
| `onNotify` | `function` | | Notify Me. |
| `className` | `string` | `""` | For layout only. |

## Do and don't [#do-and-dont]

- Do describe what the person gets from connecting, in one sentence.
- Do keep cards in a grid with a 16px gap.
- Don't add a second action. Settings for a connected source go behind View Details.


# List dropdown (/work/petavue-design-system/docs/components/list-dropdown)

```jsx
import { ListDropdown } from "@/ui";
```

ListDropdown is a small wrapper around the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu). The trigger is plain 12px text with a 12px caret and no border, so it can sit inside a header or a line of text without looking like a form field. The list is the product dropdown, with a blue check on the chosen option.

Use it for a quiet choice inside a panel header, such as which version of a plan you are looking at. For a choice in a form, use Dropdown. For a menu of actions, use the dropdown menu directly.

## Usage [#usage]

Pass the options, the current value and `onChange`. The trigger shows the label of the option whose `value` matches.


```jsx
const [version, setVersion] = useState(3);

<ListDropdown
  options={[
    { value: 1, label: "v1" },
    { value: 2, label: "v2" },
    { value: 3, label: "v3 · Latest" },
  ]}
  value={version}
  onChange={setVersion}
/>
```

## Custom trigger text [#custom-trigger-text]

`renderLabel` receives the selected option and returns what the trigger shows. Use it to name the setting next to its value. The option is `undefined` when nothing matches `value`, so handle that case.


```jsx
<ListDropdown
  options={sorts}
  value={sort}
  onChange={setSort}
  renderLabel={(o) => `Sort by: ${o?.label ?? "None"}`}
/>
```

## Long lists [#long-lists]

The list is capped at 280px and scrolls after that. If people need to search a list this long, use a field with search instead.


```jsx
<ListDropdown options={campaigns} value={campaign} onChange={setCampaign} />
```

## States [#states]


```jsx
<ListDropdown options={[{ value: 1, label: "v1 · Latest" }]} value={1} disabled />

<ListDropdown options={sorts} value={undefined} onChange={setSort} renderLabel={(o) => o?.label ?? "Choose a sort"} />
```

| State | Look |
|---|---|
| Default | 12px `--color-text-primary`, 6px by 12px padding, 8px corners, no background. |
| Hover | `--color-grey-50` background. |
| Open | The panel opens below, lined up with the trigger's left edge, 4px away. The chosen option has a bold 16px check in `--color-primary-500`. |
| Disabled | Text and caret in `--color-grey-300`. The trigger cannot be clicked or focused into opening. The workbook disables it while a plan has only one version. |
| No match | With no `renderLabel`, the trigger shows only the caret. Always give a `renderLabel` fallback when `value` can be empty. |
| No options | The trigger still renders, but nothing opens. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `options` | `Array<{ value: string \| number, label: string }>` | `[]` | `value` is compared with `===`. |
| `value` | `string \| number` | | The selected option's `value`. |
| `onChange` | `(value) => void` | | Called with the chosen option's `value`, also when it is already selected. |
| `renderLabel` | `(option \| undefined) => ReactNode` | | Replaces the trigger text. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Goes on the wrapper `<div>`, not the trigger. For layout only. |

No other props are passed on. In particular there is no `aria-label`, `align` or `placeholder` prop.

## Accessibility [#accessibility]

- The trigger is a native `<button>` and the list is the product dropdown, so Enter, Space and the arrow keys open it, the arrow keys move through options, Escape closes it and focus returns to the trigger. See the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu) for the full list.
- The trigger's accessible name is only the visible text, such as "v3 · Latest". Because there is no `aria-label` prop, use `renderLabel` to put the setting's name in the text ("Sort by: Pipeline") when the value alone does not explain itself.
- The chosen option is shown with a drawn check, not `aria-checked`, so a screen reader does not hear which option is selected. The trigger text is the only place it is announced.

<Callout>

The component's CSS still has rules for its own older menu (`.list-dropdown__menu`, `.list-dropdown__item`). They are no longer used since the list moved to the product dropdown, and can be deleted.

</Callout>

## Do and don't [#do-and-dont]

- Do keep it for short lists of plain text options, up to about ten.
- Do make the trigger text say what is being chosen, with `renderLabel` if needed.
- Don't use it in a form. Form fields need a visible label and a border; use Dropdown.
- Don't use it for actions. It shows a chosen value, so every option should be a value, not a verb.


# Modal (/work/petavue-design-system/docs/components/modal)

```jsx
import { Modal } from "@/ui";
```

## Modal or Dialog [#modal-or-dialog]

Modal and [Dialog](/work/petavue-design-system/docs/components/dialog) do the same job: a centred panel with a coloured top rail in blue, orange or red, a title and a close button. They grew up separately, so each has what the other lacks.

| | Modal | Dialog |
|---|---|---|
| Built on | MUI `Modal` | Plain markup and the design-system tokens |
| Backdrop, portal, scroll lock | Yes | No. The caller adds a backdrop. |
| Escape and click outside close it | Yes | No. The caller adds them. |
| Focus moved in, kept in, and returned | Yes | No |
| `role="dialog"` and a name | No | No. The caller adds them. |
| Sizes | One, 384px. Every caller overrides it, usually to 500px. | 460, 650 and 800px |
| Footer | None. Every caller builds Cancel and Confirm by hand. | Built in |
| Header | 16px title with 32px side padding. 9 of the 10 callers shrink it to a 14px title with 16px padding. | 16px title with 12px side padding |
| Rail | 3px | 4px |
| Used in | 10 files: integrations settings, sessions, dashboards, message deletion and the terms of service. 2 more in `_archive`. | 6 files, 7 dialogs: the library (page settings, publishing, filing, previews, brand import), workflow run review and the workbook. |

**Use Dialog for new work.** It is the design-system dialog: it has the sizes and the built-in footer, and the newer library, workflow review and workbook screens use it. Modal callers each restyle the width, header and title and hand-build the same footer, which is what Dialog already provides. Modal also pulls in MUI for one panel.

Modal does handle focus, Escape and the backdrop properly, and Dialog does not. That is a gap to close in Dialog, not a reason to start new screens on Modal. Until then, wrap Dialog as shown on its page. When you next work on a screen that uses Modal, move it to Dialog.

<Callout>

There is a third dialog, `Dialog` in `@/ui/components/OverlayDialog/OverlayDialog`, with `DialogHeader`, `DialogContent` and `DialogFooter`. It is not exported from `@/ui`. It does have a backdrop, Escape, a focus trap, scroll lock and `role="dialog"`, and the workflow, publish and schedule dialogs use it. Its name clashes with the Dialog on this site, so check the import path when you read existing code. Settings and the profile page also have three hand-written `Modal.jsx` files of their own.

</Callout>

## Usage [#usage]

Pass `isOpen` and `onClose`. Modal closes itself on Escape and on a click on the backdrop by calling `onClose`. Put the body and your own footer in `children`.


```jsx
<Modal
  isOpen={open}
  onClose={close}
  title="Delete session"
  variant="error"
  className="w-[500px]"
  headerClassName="py-3 px-4"
  titleClassName="text-[14px] font-medium"
>
  <div className="px-4 pb-4 flex flex-col gap-2">
    <p className="text-[14px] text-[var(--color-grey-600)]">
      Delete <b>Pipeline by channel, Q3 review</b>? The chat and its charts will be removed.
    </p>
    <p className="text-[12px] text-[var(--color-grey-500)]">This cannot be undone.</p>
  </div>
  <div className="flex justify-between items-center py-3 px-4 border-t border-[var(--color-grey-100)]">
    <Button variant="ghost" size="lg" label="Cancel" onClick={close} />
    <Button variant="red" size="lg" label="Delete" onClick={remove} />
  </div>
</Modal>
```

This is how the existing delete confirmations are built, and it is the one thing Modal can do today that Dialog cannot: a working red confirm button.

## With a field [#with-a-field]

Put `autoFocus` on the field so focus lands there when the modal opens. Without it, MUI focuses the panel itself.


```jsx
<Modal isOpen={open} onClose={close} title="Rename dashboard" className="w-[500px]" headerClassName="py-3 px-4" titleClassName="text-[14px] font-medium">
  <div className="px-4 pb-4">
    <TextInput label="Dashboard name" value={draft} onChange={(e) => setDraft(e.target.value)} onKeyDown={(e) => e.key === "Enter" && save()} autoFocus />
  </div>
  <div className="flex justify-between items-center py-3 px-4 border-t border-[var(--color-grey-100)]">
    <Button variant="ghost" size="lg" label="Cancel" onClick={close} />
    <Button variant="primary" size="lg" label="Rename" disabled={!draft.trim() || draft.trim() === name} onClick={save} />
  </div>
</Modal>
```

## Variants [#variants]

`variant` sets the 3px rail colour. Unlike Dialog, it does not disable anything.


```jsx
<Modal isOpen={open} onClose={close} title="Connect HubSpot" variant="primary">…</Modal>
<Modal isOpen={open} onClose={close} title="Unsaved changes" variant="warning">…</Modal>
<Modal isOpen={open} onClose={close} title="Disconnect Google Ads" variant="error">…</Modal>
```

| Variant | Rail |
|---|---|
| `primary` | `--color-primary-500` |
| `warning` | `--color-orange` |
| `error` | `--color-red` |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `isOpen` | `boolean` | | Required. |
| `onClose` | `(event, reason) => void` | | Called by the close button, Escape and a backdrop click. Pass a function that does nothing to make the modal impossible to dismiss, as the terms of service does. |
| `title` | `ReactNode` | | An `<h2>`, cut short at 80% of the header width with a tooltip showing the rest. |
| `variant` | `"primary" \| "warning" \| "error"` | `"primary"` | Rail colour. |
| `children` | `ReactNode` | | The body and any footer. |
| `showHeader` | `boolean` | `true` | `false` removes the title and the close button. |
| `showCloseBtn` | `boolean` | `true` | |
| `header` | `ReactNode` | | Extra content placed in the header before the title. |
| `className` | `string` | | On the panel. Merged with `tailwind-merge`, so `w-[500px]` replaces the default `w-96`. |
| `headerClassName` | `string` | | On the header row. Default padding is `px-8 pt-6 pb-4`. |
| `titleClassName` | `string` | | On the `<h2>`. Default is 16px semibold. |
| `closeClassName` | `string` | | On the close Button. |
| `childClassName` | `string` | | On the `<div>` around `children`. |
| `topBorderClassname` | `string` | `""` | Merged after the rail classes, so it can override them. The session modals use it for a 5px rail. |
| `containerClassname` | `string` | `""` | On the fixed wrapper that centres the panel. |
| `center` | `boolean` | `true` | `false` pushes the panel to `margin-left: 36%`. Nothing uses it. |
| `styles` | `{ modal?: object }` | `{}` | Inline styles for the panel. |
| `classes` | `object` | `{}` | Passed to MUI `Modal`. The backdrop is always `#44444466`. |
| `topStripClassName` | `string` | | Accepted but not used. Most callers pass `"hidden"`, which does nothing. |

## Accessibility [#accessibility]

- MUI renders the modal in a portal at the end of `<body>` and hides the rest of the page from screen readers while it is open.
- Focus moves into the modal on open, to the panel itself or to a field with `autoFocus`. Tab and Shift+Tab stay inside it.
- Escape and a click on the backdrop call `onClose`. Focus returns to the element that opened it.
- The page behind does not scroll while it is open.
- The panel has no `role="dialog"` and is not linked to its title, so screen readers do not announce it as a dialog. MUI leaves that to the content. If you must add a Modal, wrap the children in an element with `role="dialog"` and `aria-labelledby` pointing at an `id` you put on the title.
- The close button is a product Button with `aria-label="Close"`.

## Do and don't [#do-and-dont]

- Do use Dialog for new confirmations and forms.
- Do keep existing Modal screens working as they are until they are moved.
- Don't copy a Modal footer into new code. Dialog's footer already does it.
- Don't rely on `topStripClassName` or `center`. The first does nothing and the second is unused.


# Mode Text Box (/work/petavue-design-system/docs/components/mode-text-box)

```jsx
import { ModeTextBox } from "@/ui";
```

Mode Text Box matches the Figma **Mode Text Fields** component. It is the workbook chat's input: a text field, a mode button that says what the request will do, and a send button. Each mode has its own placeholder, so the field explains what to type.

## Default [#default]

Click the mode button to open the menu above it. The selected mode has a check. Type and press Enter or click send; Shift+Enter adds a new line.


```jsx
import { Note, ChartScatter, Path, Play, Compass } from "@phosphor-icons/react";

const groups = [
  {
    label: "Create from Analysis",
    modes: [
      { id: "generate-memo", label: "Generate Memo", icon: Note,
        placeholder: "Generate a memo summarizing the key findings from this analysis" },
      { id: "create-chart", label: "Create Chart", icon: ChartScatter,
        placeholder: "Create a chart from the results of this analysis" },
      { id: "save-as-definition", label: "Save as Definition", icon: Path,
        placeholder: "Save the logic from this analysis as a reusable definition" },
    ],
  },
  {
    label: "Start New",
    modes: [
      { id: "quick-analysis", label: "Quick Analysis", icon: Play,
        placeholder: "Run a quick analysis to answer the following question" },
      { id: "build-analysis", label: "Build an Analysis", icon: Compass,
        placeholder: "Build a multi-step analysis to answer the following question" },
    ],
  },
];

<ModeTextBox
  groups={groups}
  defaultMode="quick-analysis"
  onSubmit={(text, mode) => run(mode, text)}
/>
```

`onSubmit` gets the trimmed text and the mode id, and the field clears. Send stays grey until there is text.

## Modes that aren't available yet [#modes-that-arent-available-yet]

Set `disabled` on a mode to show it greyed out in the menu. The workbook chat does this for the "Create from Analysis" modes until every analysis step has run.


```jsx
{ id: "generate-memo", label: "Generate Memo", icon: Note, disabled: !analysisReady }
```

## States [#states]


| State | Box | Mode button | Send |
|---|---|---|---|
| Default | White, Grey 200 border | White, Primary 500 border and text | Grey 100, Grey 300 arrow |
| Mode (menu open) | Same | Primary 50 fill, Primary 100 border, Primary 300 text, caret up | Same |
| Typing | Primary 500 border while the field has focus | Same as Default | Primary 500, white arrow once there is text |
| Disabled | Grey 50 fill | Grey 100 fill, Grey 300 text | Grey 100 |

Pass `disabled` to lock the whole box, for example while a plan is still being built.

## Anatomy [#anatomy]

| Part | Size | Style |
|---|---|---|
| Box | Fills its container; 124px tall when empty | 8px top and bottom padding, 12px sides, 10px gap, 1px border, 8px radius, `0 8px 4px` shadow at 8% |
| Field | 14px / 22px, at least 64px tall | Grows with the text up to six lines, then scrolls. Placeholder in `--color-text-disabled` |
| Mode button | 32px tall, 20px radius, 12px sides | 12px text and icons, 6px gap |
| Send | 32 × 32px, 8px radius | 12px arrow |
| Menu | 200px wide, opens above the mode button | 4px padding, Grey 200 border, 8px radius, `0 8px 24px` shadow at 10% |
| Group label | 12px / 19px medium | `--color-text-disabled`, 2px × 6px padding. Groups after the first have a Grey 100 line above |
| Menu item | 14px / 22px, 6px × 12px padding | 16px icon, 8px gap, 4px radius, check on the right when selected |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `groups` | `{ label?, modes: Mode[] }[]` | `[]` | Menu sections, in order. |
| `mode` | `string` | | Selected mode id, if you control it. |
| `defaultMode` | `string` | First mode | Starting mode when uncontrolled. |
| `onModeChange` | `(id) => void` | | |
| `value` | `string` | | Text, if you control it. |
| `defaultValue` | `string` | `""` | |
| `onChange` | `(text) => void` | | |
| `onSubmit` | `(text, modeId) => void` | | Called on send or Enter. |
| `disabled` | `boolean` | `false` | Locks the field, the mode button and send. |
| `placeholder` | `string` | The mode's | Overrides every mode's placeholder. |
| `className` | `string` | | Other props are passed to the root too. |

Each `Mode` has `id`, `label`, and optionally `icon` (a Phosphor component), `placeholder` and `disabled`.

## Differences from Figma [#differences-from-figma]

- In Figma, the Default memo example's button says "Generate Memo" and the other states say "Create Memo". Here the button always shows the mode's label, so it matches the menu item.
- Figma has no hover states. Here the mode button and menu items turn light on hover, and send turns Primary 800.
- Figma shows "Typing" with text and a blue border together. Here the border is blue while the field has focus, and send turns blue once there is text, so the two can happen apart.

## Accessibility [#accessibility]

- The field's accessible name is the current placeholder. Pass `aria-label` to set your own.
- The mode button has `aria-haspopup="menu"` and `aria-expanded`. Up and Down arrows on it open the menu.
- Menu items are `menuitemradio` with `aria-checked`. Up, Down, Home and End move between them, skipping disabled ones; Escape closes the menu and returns focus to the button.
- Send is labelled "Send" and is disabled until there is text.

## Do and don't [#do-and-dont]

- Do write each placeholder as the start of the request, so the field reads like a sentence.
- Do keep mode labels to two or three words.
- Don't hide a mode that isn't available yet. Show it disabled, so people know it will be there.
- Don't use it for a plain message box with one kind of request. Use [Text Area](/work/petavue-design-system/docs/components/text-area) with a send button.


# Model mode menu (/work/petavue-design-system/docs/components/model-mode-menu)

```jsx
import { ModelModeMenu, SAGE_MODES, readSageMode, writeSageMode } from "@/ui";
```

The model mode menu is the pill next to the send button on the home page and in the session composer. It opens a "Choose your mode" list built on the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu). Each mode has an icon, a name, a one-line description and an info icon with more detail on hover.

It is used in three places: the harness home page, the older home page and the session composer. Use it only where someone is about to send a prompt to Sage.

## Usage [#usage]

Start the state from `readSageMode` so the choice carries over between the home page and a session. The menu saves the new mode itself when someone picks one, then calls `onChange`.


```jsx
const [mode, setMode] = useState(readSageMode);

<ModelModeMenu value={mode} onChange={setMode} placement="bottom" />
```

<Callout>

Choosing a mode on this page saves it in this browser, so the app will open in that mode too.

</Callout>

## Opening upwards [#opening-upwards]

Use `placement="top"` when the menu sits at the bottom of the screen, as in the session composer. The panel aligns to the pill's right edge in both placements, so keep the pill on the right of its row.


```jsx
<div className="composer-actions">
  <ModelModeMenu value={mode} onChange={setMode} placement="top" />
  <Button variant="primary" icon={ArrowUp} aria-label="Send" />
</div>
```

## Disabled [#disabled]

Disable it whenever the composer cannot send, as the session composer does. The pill drops to 60% opacity and does not open.


```jsx
<ModelModeMenu value={mode} onChange={setMode} disabled={composerDisabled} />
```

## The modes [#the-modes]

The list comes from `SAGE_MODES`. Each entry is `{ id, label, beta?, icon, description, tooltip }`.

| `id` | Label | Badge | Description |
|---|---|---|---|
| `pro` | Pro | Beta | Deepest reasoning for complex work. About twice the credits of Standard. |
| `standard` | Standard | | The default for everyday analysis. Other modes are priced against it. |
| `mini` | Mini | Beta | For quick lookups and simple questions. Fewer credits than Standard. |

To add or change a mode, edit `SAGE_MODES` in `ModelModeMenu.jsx`. Every menu and both helper functions read from it.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `value` | `"pro" \| "standard" \| "mini"` | `"standard"` | An unknown id shows "Standard" on the pill but no check in the list. |
| `onChange` | `(id) => void` | | Called only when the mode changes. The new mode is already saved when it runs. |
| `placement` | `"bottom" \| "top"` | `"bottom"` | Which side of the pill the panel opens on. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Goes on the wrapper `<div class="mm">`. For layout only. |

### Helpers [#helpers]

| Export | Returns | Notes |
|---|---|---|
| `readSageMode()` | `"pro" \| "standard" \| "mini"` | Reads `petavue:sage-mode` from `localStorage`. Returns `"standard"` if nothing valid is stored or storage is blocked. |
| `writeSageMode(id)` | | Saves `id` to the same key. It does not check that `id` is a known mode. The menu already calls it, so you only need it to set the mode from somewhere else. |
| `SAGE_MODES` | `Array` | The three modes, in display order. |

## Look [#look]

| Part | Style |
|---|---|
| Pill | 34px high, 1px `--color-neutral-200` border, `--radius-md` (8px) corners, white. On hover the border goes to `--color-neutral-300` and the fill to `--color-neutral-50`. |
| Pill content | A 14px sparkle in `--color-primary-500`, the mode name in 13px semibold, and a 14px caret in `--color-text-secondary`. |
| Panel | 328px wide, from the product dropdown. 8px from the pill. Aligned to the pill's right edge. |
| Item | 16px icon, the name in 14px, the description in 12px `--color-text-secondary`. The chosen mode has a bold blue check on the right. |
| Info tip | Dark `--color-neutral-900` box, 224px wide, opens above the info icon on hover or focus. |

<Callout>

A few things here do not follow the rest of the system yet. The icons come from `lucide-react` instead of Phosphor. The Beta badge uses `--color-tag-violet` and `--color-accent-400` (#643BCF), a purple outside the product palette. The pill name is 13px, the badge 10.5px and the tip 11px, off the 12px and 14px scale. The pill is 34px high while a medium Button is 32px. `ModelModeMenu.css` also still has rules for the menu it used before moving to the product dropdown (`.mm__menu`, `.mm__item`, `.mm__check`, `.mm__item-label`), which no longer apply.

</Callout>

## Accessibility [#accessibility]

- The pill is a native `<button>` named "Model mode: Standard" (or the current mode), with `aria-haspopup="menu"` and `aria-expanded`.
- Enter, Space or the down arrow opens the list on the first mode. The arrow keys, Home and End move through modes, Enter chooses one, and Escape closes the list. In both cases focus returns to the pill.
- The chosen mode is shown with a drawn check, not `aria-checked`. Screen readers hear the current mode from the pill's name, not from the list.
- Each mode's accessible name includes the full tooltip text, because the info icon carries it as an `aria-label`. That makes each option long to listen to.
- The info icons have `tabIndex={0}`, so Tab moves into them instead of closing the list as it does in every other menu. Clicking an info icon does not choose the mode.

## Do and don't [#do-and-dont]

- Do start state from `readSageMode` so the choice follows people between pages.
- Do disable the menu together with the composer it sits in.
- Don't call `writeSageMode` in your `onChange`. The menu has already saved it.
- Don't use this component for other choices. Its list is fixed to `SAGE_MODES`. For a general choice under the composer, use the dropdown menu with a Button trigger.


# Notification (/work/petavue-design-system/docs/components/notification)

```jsx
import { Notification } from "@/ui";
```

Notification is the static, in-page version of the [Toast](/work/petavue-design-system/docs/components/toast) bar. It does not float, animate or close on its own; you place it in the layout and decide when it goes away.

<Callout>

No screen uses Notification today. It is exported from `@/ui` and works, but check the contrast notes below before you adopt it.

</Callout>

## Variants [#variants]


```jsx
<Notification variant="success" message="Landing page published to petavue.com/q3-webinar." />
<Notification variant="info" message="Pipeline data refreshes every 6 hours." />
<Notification variant="warning" message="2 campaigns are missing UTM parameters." />
<Notification variant="error" message="HubSpot sync failed. Pipeline numbers are from yesterday." />
```

| Variant | Background | Use for |
|---|---|---|
| `success` (default) | `--color-green` #08BD50 | Confirming that something finished. |
| `info` | `--color-primary-500` #3661ED | A neutral fact about the page. |
| `warning` | `--color-orange` #FBBF24 | Something that needs attention but is not broken. |
| `error` | `--color-red` #F93D3D | Something failed and the data on the page is affected. |

The text is always white, 14px medium on a 22px line. The bar has 8px 16px padding, a 4px radius (`--radius-sm`) and a minimum width of 280px. It grows to fill its container.

<Callout>

The CSS gives each variant a 3px left border, but in the same colour as the background, so it is not visible.

</Callout>

<Callout>

White text only meets the 4.5:1 contrast minimum on `info` (about 5.1:1). It is about 3.7:1 on `error`, 2.5:1 on `success` and 1.7:1 on `warning`, which is hard to read. If you need a warning that people must read, put the detail in the page body as well.

</Callout>

## Dismissible [#dismissible]

Pass `onClose` to show a close button. Without it there is no way to dismiss the bar. Close the one below, then bring it back.


```jsx
const [open, setOpen] = useState(true);

{open && (
  <Notification
    variant="error"
    message="HubSpot sync failed. Pipeline numbers are from yesterday."
    onClose={() => setOpen(false)}
  />
)}
```

The component does not hide itself. `onClose` is only a callback, so you must remove it from the tree as above.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `variant` | `"success" \| "info" \| "warning" \| "error"` | `"success"` | |
| `message` | `ReactNode` | `"Notification"` | The text. `children` is ignored. |
| `onClose` | `() => void` | | Shows the close button when set. |
| `className` | `string` | | For layout only. |

Any other prop (`id`, `data-*`, `aria-*`) is passed to the outer `<div>`.

## Accessibility [#accessibility]

- The bar always has `role="alert"`, so a screen reader reads it out immediately when it appears, whatever the variant. That suits `error`, but it interrupts people for `success` and `info`. For those, pass `role="status"` to override it.
- When the bar is on the page from the first render, `role="alert"` is usually not announced. Rely on it only for bars you add after something happens.
- The close button is a native `<button>` with `aria-label="Close notification"` and a 1px white focus outline.

## Do and don't [#do-and-dont]

- Do write the message as what happened and what it means: "HubSpot sync failed. Pipeline numbers are from yesterday."
- Do keep it to one sentence or two short ones. There is no title or action slot.
- Don't use it for confirmations that only matter for a moment, such as "Saved". Use a toast.
- Don't use `warning` for anything people must read. The contrast is too low.
- Don't stack more than one or two on a page. If several things are wrong, list them in the page body.


# Radio (/work/petavue-design-system/docs/components/radio)

```jsx
import { Radio, RadioGroup } from "@/ui";
```

Use `RadioGroup` for a labelled, stacked list of options. Use `Radio` on its own only when the layout needs something RadioGroup cannot do, such as a row of options.

## Usage [#usage]

Pass `options` as `{ value, label }` objects, the selected `value`, and a `name` that is unique on the page. `onChange` receives the picked option's `value`, so a state setter can go straight in.


```jsx
const [model, setModel] = useState("first");

<RadioGroup
  label="Attribution model"
  name="attribution-model"
  value={model}
  onChange={setModel}
  options={[
    { value: "first", label: "First touch" },
    { value: "last", label: "Last touch" },
    { value: "linear", label: "Linear, equal credit to every touch" },
  ]}
/>
```

<Callout>

Always pass `name`. It defaults to `""`, and without it the browser does not treat the radios as one group: Tab stops on every option and the arrow keys do not move between them.

</Callout>

## Disabled options [#disabled-options]

Add `disabled: true` to an option to show it but stop people picking it. Say why in the label, or next to the group. `disabled` on the RadioGroup itself disables every option.


```jsx
<RadioGroup
  label="Domain"
  name="page-domain"
  value={domain}
  onChange={setDomain}
  options={[
    { value: "pages.petavue.com", label: "pages.petavue.com · Petavue's domain" },
    { value: "go.yourcompany.com", label: "go.yourcompany.com · connect a domain first", disabled: true },
  ]}
/>
```

## Options in a row [#options-in-a-row]

RadioGroup always stacks its options. For two or three short options side by side, lay out single `Radio`s yourself inside a `<fieldset>` with a `<legend>`, and give them the same `name`. Reset the browser's default `<fieldset>` border and padding, and style the legend 14px medium to match RadioGroup. Unlike RadioGroup, `Radio`'s `onChange` receives the native event.


```jsx
<fieldset>
  <legend>Compare spend over</legend>
  <div style={{ display: "flex", gap: 24 }}>
    {PERIODS.map((p) => (
      <Radio
        key={p.value}
        name="spend-period"
        value={p.value}
        label={p.label}
        checked={period === p.value}
        onChange={() => setPeriod(p.value)}
      />
    ))}
  </div>
</fieldset>
```

## States [#states]


```jsx
<Radio label="Unselected" checked={false} />
<Radio label="Selected" checked />
<Radio label="Unselected, disabled" checked={false} disabled />
<Radio label="Selected, disabled" checked disabled />
```

| State | Ring | Dot | Hover |
|---|---|---|---|
| Unselected | 1px `--color-grey-900` | none | `--color-primary-100` fill inside the ring |
| Selected | 1px `--color-primary-500` | `--color-primary-500` | `--color-primary-100` fill inside the ring |
| Focus (keyboard) | `--shadow-focus` ring | | |
| Disabled, unselected | 1px `--color-grey-300`, white fill | none | none |
| Disabled, selected | 1px `--color-primary-300` | `--color-primary-300` | none |

The control takes a 16px square; the visible ring is 12px across and the dot 6px. Option labels are 14px regular `--color-text-primary` (`--color-text-disabled` when disabled), 8px from the ring. In a RadioGroup the legend is 14px medium and options are 10px apart. The CSS sets a 12px gap on the group, but a `<legend>` is not laid out as a flex item, so in practice the legend sits directly on the first option with no space between them.

There is no error state. If a choice is required, pick a sensible default so the group is never empty.

## Props [#props]

### RadioGroup [#radiogroup]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | `""` | Rendered as the `<legend>`. Leave it empty only if a heading right above names the group. |
| `name` | `string` | `""` | Required in practice. Must be unique on the page. |
| `options` | `{ value: string, label: ReactNode, disabled?: boolean }[]` | `[]` | |
| `value` | `string` | `""` | The selected option's `value`. |
| `onChange` | `(value: string) => void` | | Called with the picked option's `value`. |
| `disabled` | `boolean` | `false` | Disables every option. |
| `className` | `string` | | Added to the `<fieldset>`. Use for layout only. |

RadioGroup does not pass any other props through, so `id`, `aria-describedby` and `data-*` are dropped.

### Radio [#radio]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | `""` | Text after the ring. When empty, pass `aria-label`. |
| `name` | `string` | `""` | Same value for every radio in a group. |
| `value` | `string` | `""` | |
| `checked` | `boolean` | `false` | Controlled. |
| `onChange` | `(event) => void` | | Receives the native change event. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Added to the wrapping `<label>`. |

Any other prop on `Radio` (`aria-*`, `ref`) is passed to the `<input type="radio">`.

## Accessibility [#accessibility]

- Each option is a native radio input, visually hidden, inside a `<label>`, so the label text is clickable and read out.
- RadioGroup renders a `<fieldset>` with `role="radiogroup"` and the label as its `<legend>`, so screen readers read the question before the options.
- With a shared `name`, Tab moves into the group once, landing on the selected option, and the arrow keys move and select within it.
- The focus ring shows on keyboard focus only (`:focus-visible`).

## Do and don't [#do-and-dont]

- Do use radios for two to five options that people should compare before choosing.
- Do order options in a logical sequence: shortest to longest period, or most to least common.
- Don't use a single radio on its own. For one yes or no option, use a [Checkbox](/work/petavue-design-system/docs/components/checkbox) or a [Toggle](/work/petavue-design-system/docs/components/toggle).
- Don't use radios for six or more options. Use a [Dropdown](/work/petavue-design-system/docs/components/dropdown).


# Skeleton (/work/petavue-design-system/docs/components/skeleton)

```jsx
import { Skeleton, SourcesSkeleton } from "@/ui";
```

Skeleton is a thin wrapper around MUI's `Skeleton` with the `pulse` animation: the block fades to 40% opacity and back every 2 seconds. You build a loading state by laying out several Skeletons in the shape of the content that will replace them.

## Basic shapes [#basic-shapes]

Set `width` and `height` on every Skeleton. Numbers are pixels; strings such as `"35%"` also work.


```jsx
<Skeleton width={160} height={20} />
<Skeleton variant="circular" width={32} height={32} />
<Skeleton width={94} height={32} className="rounded-lg" />
```

| `variant` | Shape | Used for |
|---|---|---|
| `rectangular` (default) | 4px radius (from the `rounded` class) | Text lines, buttons, images, table cells. |
| `circular` | Circle | Avatars and logos. |
| `rounded` | MUI's 4px radius | Same as the default here. |
| `text` | MUI text line, scaled to 60% of `height` | Avoid. The scaling makes heights hard to match. |

To match a button or card, change the radius with `className`, for example `rounded-lg`. In this app `rounded-lg` is 12px, not Tailwind's usual 8px, because the design tokens redefine `--radius-lg`.

<Callout>

The wrapper adds `bg-[var(--color-grey-200)]`, but MUI's own background wins, so every Skeleton actually renders `rgba(0, 0, 0, 0.11)`: a neutral grey of about #E3E3E3 on white, not the product's blue-grey. Passing a background class through `className` has the same problem.

</Callout>

## Composing a loading state [#composing-a-loading-state]

Copy the layout of the real content: the same padding, gaps and line lengths. Vary the widths of text lines so they read as text, not as a grid.


```jsx
// Integration card, from settings/integrations
<div className="flex flex-col gap-3 p-4 border rounded-xl">
  <div className="flex items-center gap-3">
    <Skeleton width={24} height={24} />
    <Skeleton width="35%" height={20} />
  </div>
  <Skeleton width="100%" height={16} />
  <Skeleton width="85%" height={16} />
  <Skeleton width={94} height={32} className="rounded-lg" />
</div>

// List row, from PageSkeleton
<div className="flex items-center gap-3">
  <Skeleton variant="circular" width={32} height={32} />
  <div className="flex flex-col gap-1.5">
    <Skeleton width={220} height={14} />
    <Skeleton width={140} height={10} />
  </div>
</div>
```

## Swapping in the content [#swapping-in-the-content]

When the data arrives, replace the Skeletons with the real content in the same container, so nothing around it moves. Use "Load again" to repeat it.


```jsx
<div className="integration-card" aria-busy={isLoading}>
  {isLoading ? <IntegrationCardSkeleton /> : <IntegrationCardContent integration={hubspot} />}
</div>
```

## SourcesSkeleton [#sourcesskeleton]

A ready-made loading state for a four-column table: a header row and three body rows.


```jsx
<SourcesSkeleton />
```

<Callout>

No screen uses SourcesSkeleton. Its body cells pass `style={{ backgroundColor: "#F8F9FC" }}` to Skeleton, but Skeleton does not accept `style`, so the lighter body colour is lost and every cell renders the same grey.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `width` | `number \| string` | | Pixels, or any CSS length such as `"35%"`. |
| `height` | `number \| string` | | |
| `variant` | `"rectangular" \| "circular" \| "rounded" \| "text"` | `"rectangular"` | |
| `className` | `string` | | Merged with `tailwind-merge`, so `rounded-lg` replaces `rounded`. |

No other prop is passed to MUI. `style`, `animation`, `aria-*` and `children` are ignored. Skeleton is a default export of its file and a named export from `@/ui`; import it from `@/ui`.

## Accessibility [#accessibility]

- Skeleton renders an empty `<span>` with no role or label, so screen readers skip it. That is right for the blocks themselves, but nothing tells a screen reader user that content is loading.
- Set `aria-busy="true"` on the container while it loads, and keep a heading or label outside the skeleton so people know what is coming.
- The pulse animation is not reduced for people who ask for reduced motion.

## Do and don't [#do-and-dont]

- Do use Skeleton when you know the shape of the result: a table, a list, a card grid, a settings form.
- Do keep the skeleton the same size as the content, so the page does not shift.
- Do import from `@/ui`. Three folders (`settings/integrations`, `settings/user-management` and `my-profile`) each have their own `components/Skeleton.jsx`, a hand-rolled `animate-pulse` div. Prefer the shared one in new code.
- Don't use a skeleton for a wait under about half a second. It flashes.
- Don't use one when you cannot predict the layout, such as a chat reply. Use a [Spinner](/work/petavue-design-system/docs/components/spinner).


# Spinner (/work/petavue-design-system/docs/components/spinner)

```jsx
import { Spinner } from "@/ui";
```

Spinner is the one loading indicator for the app. Its source asks that it replace lucide `Loader2` and Phosphor `CircleNotch`, but about 30 files outside `_archive` still use one of those, so you will see both for now.

<Callout>

Five Goals files (`GoalDetailPage`, `GoalQuickView`, `RecommendationDrawer`, `RunHistoryPage`, `SageWidget`) declare their own `const Spinner` that is a spinning `CircleNotch`, and `PublishView` imports Phosphor's `Spinner` icon. Those are not this component, even though the name matches. The real one is used in `RunsActivity` and the skills-v2 run screens.

</Callout>

## Default [#default]

Eight dots orbit a centre point and fade in turn, one cycle every 1.1 seconds. The default size is 20px.


```jsx
<Spinner />
```

## Sizes [#sizes]

`size` is the diameter in pixels. Any number works; these are the sizes the app uses.


```jsx
<Spinner size={13} />
<Spinner size={16} />
<Spinner size={20} />
<Spinner size={24} />
<Spinner size={28} />
```

| Size | Where it is used |
|---|---|
| 13px | Beside 12px text: running counts and step progress in `RunsActivity` and `ExecutionProgress`. |
| 16px | In place of a 16px status icon in a progress row. |
| 20px (default) | Inline before a sentence, such as "Loading plan…" in `PlanApprovalCard`. |
| 24px and 28px | Centred in an empty panel or a redirect dialog while the whole view loads. |

## Inline with text [#inline-with-text]

Put the spinner before a short label that says what is loading. Align them with flex and an 8px gap.


```jsx
<div className="flex items-center gap-2 text-[14px] text-[var(--color-text-secondary)]">
  <Spinner size={16} /> Loading campaigns…
</div>
<div className="flex items-center gap-2 text-[12px] text-[var(--color-text-secondary)]">
  <Spinner size={13} /> 3 workflows running
</div>
```

## In a button [#in-a-button]

Spinner accepts and ignores a `weight` prop, so you can pass the component itself as a Button `icon`. Button sizes it to match. Click to try it.


```jsx
<Button
  variant="primary"
  label={busy ? "Syncing HubSpot" : "Sync HubSpot"}
  icon={busy ? Spinner : undefined}
  disabled={busy}
  onClick={sync}
/>
```

This is how `BlockedCallout` shows "Starting…" on its run buttons. Keep the button `disabled` while it is busy: a disabled button turns grey (`--color-grey-100`), which is what makes the blue dots visible on a `primary` button. On an enabled `primary` button they would disappear into the blue fill.

## Colour [#colour]

The colours are fixed in `Spinner.css`: the leading dot is #3661ED (`--color-primary-500`) and the trail fades through 70%, 50% and 20% of it. They are hard-coded rather than tokens, and they ignore `color`, so classes such as `text-[var(--accent)]` have no effect.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `size` | `number` | `20` | Diameter in px. |
| `className` | `string` | `""` | For layout only (margins, alignment). |
| `style` | `CSSProperties` | | Merged after the computed width and height. |
| `weight` | any | | Ignored. It exists so Spinner can stand in for a Phosphor icon. |

Any other prop (`aria-label`, `data-*`) is passed to the outer `<span>`.

## Accessibility [#accessibility]

- The outer span has `role="status"` and `aria-label="Loading"`. Pass your own `aria-label` when the context is not obvious, such as "Loading campaigns".
- When visible text already says what is loading, the label is read twice. You can pass `aria-hidden` to the Spinner in that case.
- With reduced motion turned on, the animation slows to 2.2 seconds a cycle rather than stopping.

## Do and don't [#do-and-dont]

- Do use Spinner for waits under a few seconds, or when you do not know the shape of what is coming: a sync, a run, a chat reply.
- Do say what is loading next to it: "Loading campaigns…", not just a spinner.
- Do use a [Skeleton](/work/petavue-design-system/docs/components/skeleton) instead when you know the layout of the result, such as a table or a list of cards.
- Don't add `animate-spin` or colour classes.
- Don't name a local component `Spinner`. It hides the real one and confuses search.
- Don't put more than one spinner in view for the same wait.


# Stepper (/work/petavue-design-system/docs/components/stepper)

```jsx
import { Stepper } from "@/ui";
```

Stepper matches the Figma **Stepper - Horizontal**, **Stepper - Vertical** and **Step Selector** components. Use it for a setup flow with a few named steps that happen in order, like configuring a definition.

## Horizontal [#horizontal]

Use it across the top of a flow with three or four short step names. Click Next to move on. Finished steps are buttons that take you back.


```jsx
<Stepper steps={["Configure", "Verify", "Validate"]} current={step} onStepClick={setStep} />
```

## Vertical [#vertical]

Use it down the side of a flow when the step names are longer.


```jsx
<Stepper
  orientation="vertical"
  steps={["Configure Definition", "Verify Sources", "Verify Drill-Downs", "Validate Definition"]}
  current={step}
  onStepClick={setStep}
/>
```

## Progress [#progress]

`current` is the index of the step in progress. Steps before it are done, and the lines between done steps turn blue. Set `current` to the number of steps to show everything done.


| Figma state | Icon | Label | Line before it |
|---|---|---|---|
| isIdle (upcoming) | Grey 500 ring | Grey 500 | Grey 400 |
| isNext (current) | Primary 500 ring | Primary 500 | Primary 500 |
| isActive (done) | Primary 500 filled check | Primary 500 | Primary 500 |

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Step | 4px 8px padding, 4px gap, 16px Phosphor `Circle` or `CheckCircle` (fill), 14px medium label |
| Connector | 1px line, 40px long. Vertical lines sit under the centre of the icon. |
| Spacing | 4px between each step and line |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `steps` | `string[]` | `[]` | Step names, in order. |
| `current` | `number` | `0` | Index of the step in progress. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | |
| `onStepClick` | `(index) => void` | | Makes finished steps buttons, so people can go back. Upcoming steps are never clickable. |
| `className` | `string` | `""` | For layout only. |

## Accessibility [#accessibility]

- It is an ordered list, so screen readers say how many steps there are.
- The current step has `aria-current="step"`, and finished steps are announced as "done".

## Not using Stepper yet [#not-using-stepper-yet]

The Goals setup (`NewGoalPage`) and the skills-v2 run screens (`SetupProgress`, `RunProgressBar`) draw their own step indicators. Move them to Stepper when you next work on them.

## Do and don't [#do-and-dont]

- Do keep step names short: one or two words across, a short phrase down.
- Don't use a stepper for more than five or six steps, or for steps people can do in any order. Use [Tabs](/work/petavue-design-system/docs/components/tabs) for those.


# Tab toggle (/work/petavue-design-system/docs/components/tab-toggle)

```jsx
import { TabToggle } from "@/ui";
```

Each TabToggle is one button. There is no group component: you render two or more side by side, keep the selected one in state, and wrap them in an element with `role="tablist"`.

## Switching views [#switching-views]

This is the workbook's Output and Formula switch, the pattern the product uses today. Pass the icon as an element at 12px.


```jsx
import { ChartBar, GearSix } from "@phosphor-icons/react";

const [tab, setTab] = useState("output");

<div role="tablist" aria-label="Step view" style={{ display: "flex", gap: 4 }}>
  <TabToggle
    icon={<ChartBar size={12} />}
    label="Output"
    active={tab === "output"}
    onClick={() => setTab("output")}
  />
  <TabToggle
    icon={<GearSix size={12} />}
    label="Formula"
    active={tab === "formula"}
    onClick={() => setTab("formula")}
  />
</div>
```

## Text only [#text-only]

The icon is optional. Without one, TabToggle works as a compact segmented control, for example to pick a date range on a chart.


```jsx
const [range, setRange] = useState("30 days");

<div role="tablist" aria-label="Date range" style={{ display: "flex", gap: 4 }}>
  {["7 days", "30 days", "Quarter"].map((r) => (
    <TabToggle key={r} label={r} active={range === r} onClick={() => setRange(r)} />
  ))}
</div>
```

## States [#states]


```jsx
<TabToggle icon={<ChartBar size={12} />} label="Active" active />
<TabToggle icon={<Table size={12} />} label="Default" />
<TabToggle icon={<GearSix size={12} />} label="Disabled" disabled />
```

| State | Background | Border | Text |
|---|---|---|---|
| Default | `--color-grey-50` | transparent | `--color-grey-600` #52577A |
| Hover | `--color-grey-50` | transparent | `--color-grey-900` #1F212E |
| Active | `--color-white` | 1px `--color-grey-600` | `--color-grey-600` |
| Disabled | `--color-grey-50` | transparent | `--color-text-disabled` #ADB2CE |

All states use 10px medium text on a 16px line, 6px 12px padding, an 8px radius and a 6px gap between icon and label. The icon takes the text colour.

<Callout>

The active toggle keeps the same text colour as the default one. Only the white fill and the grey border mark the selection, so on a white background the difference is the border alone. Place groups on a grey or white surface and check the contrast before using it somewhere new.

</Callout>

<Callout>

The CSS sets `font-family: var(--font-family)`, a token that does not exist. The browser ignores it and the button inherits the page font, which is Poppins in the app.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `string` | | The text. |
| `icon` | `ReactNode` | | An element, not a component: `icon={<ChartBar size={12} />}`. |
| `active` | `boolean` | `false` | Sets the selected style and `aria-selected`. |
| `disabled` | `boolean` | `false` | Disables the button and drops `onClick`. |
| `onClick` | `() => void` | | |
| `className` | `string` | | For layout only. |

No other prop is passed to the `<button>`, so you cannot add `aria-label`, `aria-controls` or `id`.

## Accessibility [#accessibility]

- It renders a native `<button>` with `role="tab"` and `aria-selected`, so it is focusable and works with Enter and Space.
- The component does not add the `role="tablist"` parent. Add it yourself with an `aria-label`, as in the examples. `WorkbookChat`, the only screen that uses TabToggle, wraps the toggles in a plain `<div>`, so its tabs have no tablist.
- There is no arrow-key navigation between toggles and no link to the panel they control. Each toggle is a separate Tab stop.
- Icon-only toggles cannot be given an accessible name, because `aria-label` is not passed through. Always include a `label`.

## Do and don't [#do-and-dont]

- Do use TabToggle for two or three views of the same content inside a card, panel or chart: Output and Formula, Table and Chart, 7 days and 30 days.
- Do keep exactly one toggle `active` in a group.
- Do import from `@/ui`. `WorkbookChat` imports from `@/ui/components/TabToggle/TabToggle`, which works but bypasses the index.
- Don't use it for page-level sections. Use [Tabs](/work/petavue-design-system/docs/components/tabs).
- Don't use it as an on and off switch for a setting. Use a Toggle.


# Tabs (/work/petavue-design-system/docs/components/tabs)

```jsx
import { Tabs } from "@/ui";
```

Tabs matches the Figma **Tabs** component: three sizes, a regular and an extended length, and Default, Hover, Active and Disabled states. A tab can have an icon before or after its label, a count, or only an icon.

Unselected tabs have a 1px `--color-grey-100` underline and `--color-text-primary` text, and turn blue on hover. The selected tab has a 2px `--color-primary-500` underline and blue medium text. The underline is drawn inside the tab, so the height is the same in every state.

## Basic tabs [#basic-tabs]

Tabs are controlled. Keep `activeIndex` in state and update it in `onTabChange`; the event's `index` is the tab that was clicked. Only the selected tab's `content` is rendered, below the tab list.


```jsx
const [active, setActive] = useState(0);

<Tabs
  activeIndex={active}
  onTabChange={(e) => setActive(e.index)}
  tabData={[
    { label: "Overview", content: <CampaignOverview /> },
    { label: "Campaigns", content: <CampaignList /> },
    { label: "Pipeline", content: <PipelineSummary /> },
  ]}
/>
```

## Icons and counts [#icons-and-counts]

`prefixIcon` puts a Phosphor icon before the label and `count` adds a small count after it. The count is grey on unselected tabs and blue with white text on the selected tab. Icons take the text colour.


```jsx
import { ChartBar, Megaphone, Funnel, Table } from "@phosphor-icons/react";

tabData={[
  { label: "Summary", prefixIcon: ChartBar },
  { label: "Campaigns", prefixIcon: Megaphone, count: 14 },
  { label: "Funnel", prefixIcon: Funnel },
  { label: "Raw data", prefixIcon: Table, count: 3 },
]}
```

`suffixIcon` puts the icon after the label instead. Figma's examples show both at once, but use one icon per tab.


```jsx
tabData={[
  { label: "All accounts", suffixIcon: CaretDown },
  { label: "Saved views", suffixIcon: CaretDown, count: 4 },
]}
```

Pass icon components, not elements (`ChartBar`, not `<ChartBar />`). Tabs sets their size.

## Sizes [#sizes]


```jsx
<Tabs size="small" ... />
<Tabs size="medium" ... />
<Tabs size="large" ... />
```

| Size | Text | Icon | Height |
|---|---|---|---|
| `small` | 12px / 16px | 12px | 32px |
| `medium` (default) | 12px / 19px | 12px | 35px |
| `large` | 14px / 22px | 16px | 38px |

Every size has 8px top and bottom padding, 16px side padding and a 10px gap between the icon, label and count. The count is 16px tall with 12px text.

<Callout>

Figma's Small tabs and the count use 10px text. We use 12px, since no product text goes below 12px. Small tabs keep their 32px height.

</Callout>

## Extended [#extended]

`extended` doubles the side padding to 32px, for a short tab list that should take up more of the bar.


```jsx
<Tabs extended activeIndex={active} onTabChange={(e) => setActive(e.index)} tabData={tabData} />
```

## Icon only [#icon-only]

Set `iconOnly` on a tab to show its icon without the label. The `label` is still required: it becomes the tab's accessible name and its tooltip.


```jsx
tabData={[
  { label: "Chart", prefixIcon: ChartBar, iconOnly: true },
  { label: "Table", prefixIcon: Table, iconOnly: true },
  { label: "List", prefixIcon: ListBullets, iconOnly: true, count: 2 },
]}
```

An icon-only tab is 44px wide at small and medium and 48px at large. Use it only when the icons are unambiguous, like a chart and table switch.

## Disabled [#disabled]

Set `disabled` on one tab to stop it from being picked, or on `Tabs` to disable every tab. Disabled tabs have `--color-text-disabled` text and a grey-50 count, and can't be clicked or reached with the arrow keys. If the selected tab is disabled, its underline turns `--color-grey-300`.


```jsx
tabData={[
  { label: "Overview" },
  { label: "Campaigns", count: 14 },
  { label: "Settings", prefixIcon: Gear, disabled: true },
]}

<Tabs disabled ... />
```

## Navigation tabs [#navigation-tabs]

When the tabs switch routes rather than panels, leave out `content` and navigate in `onTabChange`, as in a page header.


```jsx
<Tabs
  activeIndex={isWorkstreams ? 1 : 0}
  onTabChange={(e) => navigate(e.index === 0 ? "/home" : "/home/workstreams")}
  tabData={[{ label: "Home" }, { label: "Workstreams" }]}
  size="large"
  navClassName="px-8 h-[52px]"
  showDefaultBottomBorder={false}
/>
```

`showDefaultBottomBorder={false}` removes the grey underline from unselected tabs, which suits a header that already has its own bottom border. Tabs stretch to the height of the tab list, so the underline sits on the header's edge.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `tabData` | `Tab[]` | `[]` | Nothing renders when it is empty. |
| `activeIndex` | `number \| null` | `0` | `null` selects no tab, for a page that belongs to none of them. |
| `onTabChange` | `(e: { originalEvent, index }) => void` | | |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | |
| `extended` | `boolean` | `false` | 32px side padding. |
| `disabled` | `boolean` | `false` | Disables every tab. |
| `showDefaultBottomBorder` | `boolean` | `true` | Grey underline on unselected tabs. |
| `navClassName` | `string` | | Classes for the tab list. |
| `headerClassName` | `string` | | Classes for each tab. |
| `className` | `string` | | Classes for the root. Other props are passed to the root too. |

Each `Tab`:

| Field | Type | Notes |
|---|---|---|
| `label` | `string` | Required, also for icon-only tabs. |
| `content` | `ReactNode` | Shown below the list when the tab is selected. |
| `prefixIcon` | `ElementType` | Icon before the label. |
| `suffixIcon` | `ElementType` | Icon after the label. |
| `count` | `number \| string` | Count after the label. |
| `iconOnly` | `boolean` | Hides the label. Needs `prefixIcon`. |
| `disabled` | `boolean` | |

## Differences from Figma [#differences-from-figma]

- Small tab and count text is 12px, not 10px.
- In Figma, the Hover and Disabled tabs have no grey underline. Here they keep it, so the line under a tab list doesn't break when you hover a tab.
- Figma's disabled Small tab without a count has 16px icons. Here every Small tab has 12px icons, as in the rest of the Small set.
- Figma has no disabled selected tab. Here its underline is grey-300.
- Icon-only Small and Medium tabs are 28px tall in Figma, shorter than the 32px and 35px text tabs. Don't mix icon-only and text tabs in one list.

## Accessibility [#accessibility]

- The list is `role="tablist"` and each tab is a `button` with `role="tab"` and `aria-selected`. When tabs have content, the panel is `role="tabpanel"` and labelled by its tab.
- Tab moves focus to the selected tab. Left and Right arrows move between tabs, Home and End jump to the first and last, and Enter or Space selects (manual activation, so arrowing through route tabs doesn't navigate).
- Disabled tabs use the `disabled` attribute, so they are skipped by the keyboard and announced as unavailable.
- Icon-only tabs use `label` as their `aria-label`.

## Do and don't [#do-and-dont]

- Do use Tabs for two to five peer sections of one page or one object, such as a campaign's Overview, Creatives and Pipeline.
- Do keep labels to one or two words in sentence case.
- Do use a count when it helps someone pick a tab, like the number of items in each.
- Don't use Tabs for a small switch inside a card or panel. Use [TabToggle](/work/petavue-design-system/docs/components/tab-toggle) there.
- Don't put actions such as "New campaign" in the tab list. Put them in the page header.


# Tag (/work/petavue-design-system/docs/components/tag)

```jsx
import { Tag, Badge, PlannerChip } from "@/ui";
```

Tag and PlannerChip match the Figma **Tag** and **Planner Tag** components.

## Status tags [#status-tags]

Most tags in the product show where something is in its life: a page, a creative, a sync. Use these four colours for status and nothing else.


```jsx
<Tag color="success-green">Published</Tag>
<Tag color="column">Draft</Tag>
<Tag color="warning-yellow">Unpublished changes</Tag>
<Tag color="error-red">Sync failed</Tag>
```

| Status | `color` | Background |
|---|---|---|
| Done, live, healthy | `success-green` | `--color-tag-success-green` #EBFFF3 |
| Draft, neutral, not started | `column` | `--color-primary-100` #E0EBFE |
| Needs attention, queued | `warning-yellow` | `--color-tag-warning-yellow` #FEF3D5 |
| Failed, disabled | `error-red` | `--color-tag-error-red` #FFF2F2 |

The text is `--color-text-primary` (#232532) on these. Only the background changes, so the label has to say the status on its own.

## All colours [#all-colours]

Tag has twelve colours. Most are a light tint with dark text; `orange`, `sea-green` and `violet` also colour the text and icons, as in Figma. Outside status, use them to tell categories apart, such as data source or block type in a workflow.


```jsx
<Tag color="column">column</Tag>
<Tag color="blue">blue</Tag>
<Tag color="orange">orange</Tag>
// …and the rest from the table below
```

| `color` | Background | Text |
|---|---|---|
| `column` | `--color-primary-100` #E0EBFE | Primary text |
| `success-green` | `--color-tag-success-green` #EBFFF3 | Primary text |
| `warning-yellow` | `--color-tag-warning-yellow` #FEF3D5 | Primary text |
| `error-red` | `--color-tag-error-red` #FFF2F2 | Primary text |
| `blue` | `--color-tag-blue` #E0FDFF | Primary text |
| `green` | `--color-tag-green` #E8FFE0 | Primary text |
| `sea-green` | `--color-tag-blue` #E0FDFF | `--color-misc-green` #0D787F |
| `yellow` | `--color-tag-orange` #FFEFE0 | Primary text |
| `orange` | `--color-tag-orange` #FFEFE0 | `--color-misc-orange` #F87F00 |
| `pink` | `--color-tag-pink` #FCE9F4 | Primary text |
| `purple` | `--color-tag-purple` #EEE0FF | Primary text |
| `violet` | `--color-tag-purple` #EEE0FF | `--color-misc-purple` #9747FF |

<Callout>

These follow Figma, which differs from the `--color-tag-*` tokens in four places: Column is Primary 100 (the token is grey #EEF0F7), Yellow is #FFEFE0 (the token is #FFFEE0), and Sea Green and Violet reuse the Blue and Purple fills. The tokens are unchanged, since other components use them.

</Callout>

<Callout>

`blue` is a cyan tint (#E0FDFF), not the primary blue family. `purple` and `violet` exist in the CSS but are outside the product palette and no screen uses them; do not start using them. In the app today only `column`, `success-green`, `warning-yellow`, `error-red`, `blue` and `orange` appear.

</Callout>

## Sizes [#sizes]

`sm` is the default and what every screen uses. Use `md` in filter bars where the tag can be removed, and `lg` only next to 14px body text.


```jsx
<Tag size="sm" color="success-green">Published</Tag>
<Tag size="md" color="success-green">Published</Tag>
<Tag size="lg" color="success-green">Published</Tag>
```

| Size | Height | Text | Line height | Padding | Icon |
|---|---|---|---|---|---|
| `sm` | 20px | 12px | 16px | 2px 8px | 10px |
| `md` | 23px | 12px | 19px | 2px 10px | 12px |
| `lg` | 26px | 14px | 22px | 2px 10px | 12px |

All sizes have an 8px radius (`--radius-md`) and a 6px gap between icon and label. Icons are `--color-grey-900`. Icon-only tags are 26px wide at `sm` and 32px at `md` and `lg`.

<Callout>

Figma sets `sm` at 10px. Code uses 12px, because 12px is the smallest text in the product.

</Callout>

## With an icon [#with-an-icon]

Pass a Phosphor icon component to `prefixIcon`, not an element. It is sized to match the tag.


```jsx
import { FolderPlus, Lightning, Timer } from "@phosphor-icons/react";

<Tag color="blue" prefixIcon={FolderPlus}>New workbook</Tag>
<Tag color="column" prefixIcon={Timer}>Runs every Monday</Tag>
<Tag color="orange" size="md" prefixIcon={Lightning}>Formula</Tag>
```

`iconOnly` hides the label and shows only the prefix icon. Tag cannot take an `aria-label`, so an icon-only tag has no accessible name. Avoid it, or put the meaning in nearby text.

## Removable [#removable]

Set `suffixIcon` to add a close button and handle `onRemove`. Try removing a filter below.


```jsx
const [filters, setFilters] = useState(["Paid search", "LinkedIn", "Q3 webinar", "EMEA"]);

{filters.map((f) => (
  <Tag
    key={f}
    color="column"
    size="md"
    suffixIcon
    onRemove={() => setFilters((xs) => xs.filter((x) => x !== f))}
  >
    {f}
  </Tag>
))}
```

`suffixIcon` is a boolean here, not an icon: the close icon is always an X.

## Badge [#badge]

Badge is a thin wrapper over Tag that maps five semantic names to Tag colours. Its source marks it as retired in favour of Tag, but 9 files outside `_archive` still import it (schedules, Slack settings, skills, the workflow modal and legacy dashboards). Use Tag in new code.


```jsx
<Badge variant="success">Connected</Badge>
<Badge variant="warning">Paused</Badge>
<Badge variant="danger">Email failed</Badge>
<Badge variant="muted">Not connected</Badge>
<Badge variant="accent">Shared</Badge>
```

| Badge `variant` | Renders as |
|---|---|
| `success` | `<Tag color="success-green">` |
| `warning` | `<Tag color="warning-yellow">` |
| `danger` | `<Tag color="error-red">` |
| `muted` (default) | `<Tag color="column">` |
| `accent` | `<Tag color="blue">` |

<Callout>

Badge always renders at `sm` and passes on only `variant`, `className` and `children`. Any other prop is dropped. `ScheduleRunHistory` passes `title={run.email_error}` to a Badge, so that error text never shows.

</Callout>

## PlannerChip [#plannerchip]

PlannerChip is a different idea that shares Tag's shape: a monospace chip for a table or column name inside workbook planner steps. It is only used in `WorkbookChat`.


```jsx
Join <PlannerChip size="lg" prefixIcon>hubspot_deals</PlannerChip> to{" "}
<PlannerChip size="lg" prefixIcon>google_ads_campaigns</PlannerChip> on{" "}
<PlannerChip size="lg">utm_campaign</PlannerChip>, then sum{" "}
<PlannerChip size="lg">amount</PlannerChip> by campaign.
```


```jsx
<PlannerChip size="sm">pipeline_amount</PlannerChip>
<PlannerChip size="md">pipeline_amount</PlannerChip>
<PlannerChip size="lg">pipeline_amount</PlannerChip>
<PlannerChip size="md" prefixIcon>hubspot_deals</PlannerChip>
<PlannerChip size="md" prefixIcon suffixIcon active>hubspot_deals</PlannerChip>
```

It uses JetBrains Mono (loaded from Google Fonts by its own CSS) on `--color-grey-50` with a `--color-grey-200` border and a 4px radius. Hover darkens the background to `--color-grey-100`, and `active` gives it a `--color-grey-300` border, matching Figma's Rest, Hover and Active states. Text sizes are 12px, 12px and 14px for `sm`, `md` and `lg`; Figma's `sm` is 10px.

<Callout>

The text colour is a hard-coded #B85300, not a token. `prefixIcon` is a boolean that always shows the Phosphor `Table` icon, unlike Tag where it takes an icon component. At `lg` the icon stays at 12px.

</Callout>

## Props [#props]

### Tag [#tag]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `children` | `ReactNode` | | The label. |
| `color` | `"column" \| "success-green" \| "warning-yellow" \| "error-red" \| "blue" \| "green" \| "sea-green" \| "yellow" \| "orange" \| "pink" \| "purple" \| "violet"` | `"blue"` | Always pass it. The default is rarely the right colour. |
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` | |
| `prefixIcon` | Phosphor icon component | `null` | |
| `iconOnly` | `boolean` | `false` | Hides the label. Needs `prefixIcon`. |
| `suffixIcon` | `boolean` | `false` | Shows the remove button. |
| `onRemove` | `() => void` | | Called when the remove button is clicked. |
| `className` | `string` | | For layout only. |

Tag does not pass any other prop through. `title`, `aria-*`, `data-*` and `onClick` are all ignored.

### Badge [#badge-1]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `variant` | `"success" \| "warning" \| "danger" \| "muted" \| "accent"` | `"muted"` | Unknown values fall back to `muted`. |
| `children` | `ReactNode` | | |
| `className` | `string` | | |

### PlannerChip [#plannerchip-1]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `children` | `ReactNode` | | The token, such as a table or column name. |
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` | |
| `prefixIcon` | `boolean` | `false` | Shows the `Table` icon. |
| `suffixIcon` | `boolean` | `false` | Shows a remove button. |
| `onRemove` | `() => void` | | |
| `active` | `boolean` | `false` | Grey 300 border, for the chip that is selected. |
| `className` | `string` | | |

## Accessibility [#accessibility]

- Tag, Badge and PlannerChip render a `<span>`. They are not focusable and have no role, so do not attach behaviour to them.
- Colour is not read out. The label must carry the meaning: write "Sync failed", not just a red tag with "Sync".
- The remove button is a real `<button>` with `aria-label="Remove"`. Every removable tag gets the same label, so a screen reader hears "Remove, button" with no name. If people will remove tags often, add a visually hidden list of the active filters nearby.

## Do and don't [#do-and-dont]

- Do use the four status colours consistently: green for done, grey `column` for draft, yellow for needs attention, red for failed.
- Do keep labels to one to three words: "Published", "Unpublished changes".
- Do import from `@/ui`. Some screens import from `@/ui/components/Tags/Tag/Tag`, which works but bypasses the index.
- Don't use Badge in new code.
- Don't use `purple` or `violet`.
- Don't make a tag clickable. If it needs to do something, use a Button or a TabToggle.


# Text area (/work/petavue-design-system/docs/components/text-area)

```jsx
import { TextArea } from "@/ui";
```

## Usage [#usage]

TextArea works like [Text input](/work/petavue-design-system/docs/components/text-input): it is controlled, and `onChange` receives the native change event.


```jsx
const [brief, setBrief] = useState("");

<TextArea
  label="Campaign brief"
  placeholder="Who the campaign is for, the offer, and the pipeline it should create"
  value={brief}
  onChange={(e) => setBrief(e.target.value)}
/>
```

It fills the width of its container. People can drag the bottom edge to make it taller; it cannot be resized sideways.

TextArea matches the Figma **Text Input** (Multi-Line) component.

<Callout>

Always pass a `placeholder`. It defaults to the literal text "Placeholder". `label` has no default: leave it out and no label renders.

</Callout>

## Height [#height]

`rows` sets the starting height and defaults to 3. Pick it from how much people usually write: 3 for a description, 5 or 6 for instructions or a brief. The field does not grow as people type; it scrolls.


```jsx
<TextArea
  label="Instructions for this workflow"
  placeholder="Every Monday, pull last week's paid media spend by channel and flag any campaign with cost per opportunity above $1,800."
  rows={6}
  value={notes}
  onChange={(e) => setNotes(e.target.value)}
/>
```

| `rows` | Height |
|---|---|
| 1 or 2 | 86px. A `min-height` of 86px stops it going lower, so these look almost the same as 3. |
| 3 (default) | 88px |
| 4 | 110px |
| 6 | 154px |

Each extra row adds 22px (one line at 14px text).

## Character limits [#character-limits]

There is no built-in counter or `maxLength` display. When a limit matters, such as a meta description, show the count yourself in a 12px `--color-text-secondary` line under the field, and switch to `error` once the text is over. Prefer this to `maxLength`, which cuts pasted text off without saying so.


```jsx
const LIMIT = 160;
const over = text.length > LIMIT;

<TextArea
  label="Meta description"
  placeholder="One or two sentences on what the page offers"
  value={text}
  onChange={(e) => setText(e.target.value)}
  error={over}
  errorMessage={`Search engines cut descriptions after ${LIMIT} characters. Remove ${text.length - LIMIT}.`}
/>
{!over && (
  <p style={{ margin: "6px 0 0", fontSize: 12, color: "var(--color-text-secondary)" }}>
    {text.length} of {LIMIT} characters
  </p>
)}
```

## States [#states]


```jsx
<TextArea label="Default" placeholder="Describe the audience" />
<TextArea label="Filled" value="Mid-market SaaS accounts that attended the September webinar…" />
<TextArea label="Error" error errorMessage="Add a description so Sage knows when to use this block." />
<TextArea label="Disabled" value="Book a 20-minute pipeline review with our team." disabled />
```

The states match [Text input](/work/petavue-design-system/docs/components/text-input) exactly, including the blue border once filled:

| Figma state | Border | Background | Text |
|---|---|---|---|
| Default | 1px `--color-grey-200` | `--color-white` | Placeholder in `--color-text-disabled` |
| Selected (focus) | 1px `--color-primary-500` | `--color-white` | |
| Filled (has a value) | 1px `--color-primary-500` | `--color-white` | 14px `--color-text-primary` |
| Error | 1px `--color-red` | `--color-white` | Message 12px medium `--color-red`, 4px below |
| Disabled | none | `--color-grey-50` | Label and value in `--color-text-disabled`. The resize handle is removed. |

The field is at least 86px tall. Padding is 10px by 16px (8px by 16px for `size="sm"`), the corner radius is `--radius-md` (8px), and the label is 14px medium, 6px above the field. Like Text input it takes `prefixIcon`, `suffixIcon` and `clearable`; icons sit at the top.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | | Rendered in a `<label>` tied to the textarea. Left out, there is no label. |
| `placeholder` | `string` | `"Placeholder"` | Pass your own, or `""` for none. |
| `value` | `string` | | Controlled value. |
| `onChange` | `(event) => void` | | Receives the native change event. |
| `rows` | `number` | `3` | Values under 3 barely change anything because of the 86px minimum height. |
| `error` | `boolean` | `false` | Red border and `aria-invalid`. |
| `errorMessage` | `string` | `""` | Shown under the field only when `error` is true. |
| `disabled` | `boolean` | `false` | |
| `size` | `"sm" \| "md"` | `"md"` | Padding only. |
| `prefixIcon`, `suffixIcon` | Phosphor icon | | 20px, top aligned. |
| `clearable`, `onClear` | | | As in Text input. |
| `className` | `string` | | Added to the wrapper `<div>`. Use for layout only. |

Any other prop (`onBlur`, `onKeyDown`, `name`, `maxLength`, `aria-*`, `ref`) is passed to the `<textarea>`.

## Accessibility [#accessibility]

- The `<label>` is linked to the textarea, so clicking it focuses the field and screen readers use it as the name.
- With `error`, the textarea gets `aria-invalid`, and the message is linked with `aria-describedby` and announced through `role="alert"`.
- A character count you add yourself is not linked to the field. If it matters, give the count an `id` and pass `aria-describedby` to the TextArea.
- Enter adds a new line. Do not make Enter submit the form from a TextArea; people expect to write more than one line.

## Do and don't [#do-and-dont]

- Do use a TextArea when the answer is a sentence or more: descriptions, briefs, instructions for a workflow.
- Do use the placeholder to show what a good answer looks like, in the reader's words.
- Don't use a TextArea for a name, ID or address. Use [Text input](/work/petavue-design-system/docs/components/text-input).
- Don't use this field for chat with Sage. The chat composer is `SageTextBox`.


# Text input (/work/petavue-design-system/docs/components/text-input)

```jsx
import { TextInput } from "@/ui";
```

## Usage [#usage]

TextInput is controlled: pass `value` and update it in `onChange`. `onChange` receives the native change event, so read `e.target.value`.


```jsx
const [name, setName] = useState("");

<TextInput
  label="Campaign name"
  placeholder="Q4 pipeline webinar"
  value={name}
  onChange={(e) => setName(e.target.value)}
/>
```

The field fills the width of its container. Set the width on the parent, not on the input.

TextInput matches the Figma **Text Input** (Single-Line) and **Form label** components.

<Callout>

Always pass a `placeholder`. It defaults to the literal text "Placeholder". `label` has no default: leave it out and no label renders.

</Callout>

## Sizes, icons and clearing [#sizes-icons-and-clearing]

`size="sm"` is 38px tall with 12px gaps; the default `md` is 42px with 16px gaps. `prefixIcon` and `suffixIcon` take a Phosphor icon, drawn at 20px. `clearable` shows a 20px × once the field has a value.


```jsx
<TextInput size="sm" placeholder="Search pages" prefixIcon={MagnifyingGlass} />
<TextInput placeholder="Search pages" prefixIcon={MagnifyingGlass} clearable value={q} onChange={(e) => setQ(e.target.value)} />
<TextInput label="Website" placeholder="yourcompany.com" suffixIcon={Globe} />
```

## Input types [#input-types]

`type` is passed straight to the `<input>`. Use `email`, `url` or `password` when the value is one of those, so browsers offer the right keyboard and autofill.


```jsx
<TextInput type="email" label="Send the weekly report to" placeholder="revops@yourcompany.com" … />
<TextInput type="password" label="Page password" placeholder="Shared with the people who should see it" … />
<TextInput type="url" label="Page canonical URL" placeholder="https://" … />
```

## Validation [#validation]

Set `error` to turn the border red, and `errorMessage` to say what to fix. The message only shows while `error` is true. Check the value on blur or on submit, not on every keystroke, so people are not told off while they are still typing.


```jsx
const [gtm, setGtm] = useState("GTM-");
const [touched, setTouched] = useState(false);
const invalid = touched && !/^GTM-[A-Z0-9]{4,}$/.test(gtm);

<TextInput
  label="Google Tag Manager ID"
  placeholder="GTM-XXXXXXX"
  value={gtm}
  onChange={(e) => setGtm(e.target.value.toUpperCase())}
  onBlur={() => setTouched(true)}
  error={invalid}
  errorMessage="Use the ID from your container, for example GTM-5KX2P7Q."
/>
```

Write the message as the fix, not the fault: "Give the page an address", not "Invalid input".

## States [#states]


```jsx
<TextInput label="Default" placeholder="Landing page name" value="" />
<TextInput label="Filled" value="Demo request, EMEA" />
<TextInput label="Error" placeholder="demo-request" error errorMessage="Give the page an address." />
<TextInput label="Disabled" value="Forecast revenue you can defend" disabled />
```

| Figma state | Border | Background | Text |
|---|---|---|---|
| Default | 1px `--color-grey-200` | `--color-white` | Placeholder in `--color-text-disabled` |
| Selected (focus) | 1px `--color-primary-500` | `--color-white` | |
| Filled (has a value) | 1px `--color-primary-500` | `--color-white` | 14px `--color-text-primary` |
| Error | 1px `--color-red` | `--color-white` | Message 12px medium `--color-red`, 4px below |
| Disabled | none | `--color-grey-50` | Label and value in `--color-text-disabled` |

The border stays blue once the field has a value, as Figma's Filled state shows, so people can tell filled fields from empty ones at a glance. The field is 10px by 16px padding (8px by 16px for `sm`), a 22px line, a 1px border and `--radius-md` (8px) corners. The label is 14px medium, 6px above the field.

<Callout>

There is no hint or helper text prop. For a hint, put a 12px `--color-text-secondary` paragraph under the field, as the page settings dialog does.

</Callout>

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | | Rendered in a `<label>` tied to the input. Left out, there is no label. |
| `placeholder` | `string` | `"Placeholder"` | Pass your own, or `""` for none. |
| `value` | `string` | | Controlled value. |
| `onChange` | `(event) => void` | | Receives the native change event. |
| `type` | `string` | `"text"` | Any HTML input type. |
| `error` | `boolean` | `false` | Red border and `aria-invalid`. |
| `errorMessage` | `string` | `""` | Shown under the field only when `error` is true. |
| `disabled` | `boolean` | `false` | |
| `size` | `"sm" \| "md"` | `"md"` | 38px or 42px tall. |
| `prefixIcon`, `suffixIcon` | Phosphor icon | | 20px, `--color-grey-900`. |
| `clearable` | `boolean` | `false` | × once filled. |
| `onClear` | `() => void` | | Defaults to calling `onChange` with an empty value. |
| `className` | `string` | | Added to the wrapper `<div>`, not the input. Use for layout only. |

Any other prop (`onBlur`, `onKeyDown`, `name`, `autoComplete`, `maxLength`, `aria-*`) is passed to the `<input>`. In React 19 `ref` is an ordinary prop, so it reaches the `<input>` the same way; use it to focus the field, for example when a dialog opens.

## Accessibility [#accessibility]

- The `<label>` is linked to the input with a generated id, so clicking the label focuses the field and screen readers read it as the field's name.
- With `error`, the input gets `aria-invalid`, and the message is linked with `aria-describedby` and announced through `role="alert"`.
- Focus turns the border Primary 500, as Figma's Selected state shows. There is no extra ring.
- If the design has no visible label, leave out `label` and pass an `aria-label`.
- The clear button is labelled "Clear" and puts focus back in the field.
- A required marker is not built in. If a field is required, say so in the label text ("Table name (required)") rather than with a red asterisk alone.

## Do and don't [#do-and-dont]

- Do write labels as a noun that names the value: "Page address", "Campaign name".
- Do use the placeholder for an example of the format, such as `GTM-XXXXXXX` or `yourcompany.com`, not for instructions that disappear once someone types.
- Don't use a TextInput for text longer than one line. Use [Text area](/work/petavue-design-system/docs/components/text-area).
- Don't use one to pick from a known list. Use [Dropdown](/work/petavue-design-system/docs/components/dropdown) or [Radio](/work/petavue-design-system/docs/components/radio).
- Don't restyle the field with `className`; it lands on the wrapper and the input keeps its own styles.


# Toast (/work/petavue-design-system/docs/components/toast)

The codebase has two toasts. The app's own screens almost all use `sonner`, called as `toast.success(...)`. The design system also exports a `Toast` component, a solid coloured bar, which only the workbook uses.

| | `sonner` | `Toast` from `@/ui` |
|---|---|---|
| How you call it | `toast.success("…")` from anywhere | Render `<Toast />` yourself and position it |
| Call sites outside `_archive` | 214 calls in 77 files | 2 renders, both in `WorkbookChat` |
| Look | White card, grey border, status icon | Solid green, orange or red bar, white text |
| Stacking, queueing, screen reader announcement | Built in | None |

**Use `sonner` in new code.** It is what people see everywhere else in the product and it handles placement, stacking and announcements for you.

```jsx
import { toast } from "sonner";
```

## Firing a toast [#firing-a-toast]

Call `toast.success`, `toast.error` or plain `toast` after the action finishes. Click the buttons to see the toasts in the bottom-left corner.


```jsx
import { toast } from "sonner";

<Button label="Publish page" onClick={() => toast.success("Landing page published")} />
<Button label="Sync HubSpot" onClick={() => toast.error("HubSpot sync failed. Try again in a few minutes.")} />
<Button label="Save workflow" onClick={() => toast("Workflow saved as a draft")} />
```

| Call | Calls in the app | Use for |
|---|---|---|
| `toast.error(message)` | 114 | An action failed. Say what failed and what to do. |
| `toast.success(message)` | 87 | An action finished: saved, published, synced, sent. |
| `toast(message)` | 7 | A neutral note with no status. |
| `toast.info(message)` | 3 | A fact that is useful now, such as when data next refreshes. |
| `toast.warning(message)` | 3 | The action ran but something needs a look. |

## Info, warning and duration [#info-warning-and-duration]

Toasts close after sonner's default of 4 seconds. Pass `duration` in milliseconds for a longer message. It is the only option the app passes today.


```jsx
toast.info("Pipeline data refreshes every 6 hours");

toast.warning(
  "No action blocks added. Add a Send email or Publish dashboard block, or save again to continue.",
  { duration: 8000 }
);
```

## Where the Toaster lives [#where-the-toaster-lives]

`toast()` only shows something if a `<Toaster>` is mounted. The app mounts one in `src/layouts/RootLayout.jsx`, so every screen inside the main layout already has it. Do not add another.

```jsx
// src/layouts/RootLayout.jsx
import { Toaster } from "sonner";

<Toaster
  position="bottom-left"
  toastOptions={{
    style: {
      background: "var(--bg-tertiary)",        // #FFFFFF
      border: "1px solid var(--border-primary)", // #D4D9EA
      color: "var(--text-primary)",           // #232532
    },
  }}
/>
```

Toasts appear in the bottom-left corner. Status comes from sonner's icon only: `richColors` is off, so every toast has the same white card.

<Callout>

Routes outside `RootLayout` need their own Toaster. `LoginPage` mounts a second one at `bottom-right` with `color: "var(--grey-900)"`, a variable that does not exist, so its text falls back to the inherited colour. This docs site also sits outside the layout; the examples above mount a copy of the RootLayout Toaster.

</Callout>

## The Toast component [#the-toast-component]

`Toast` from `@/ui` is a solid bar with white 14px medium text, a close button and an optional link. It slides up 16px and fades in over 350ms, and slides down and fades out over 250ms when it closes. Use it only if you are working in the workbook and need to match the existing bars there.

```jsx
import { Toast } from "@/ui";
```


```jsx
<Toast status="success" message="Widget added to Q3 pipeline dashboard" onClose={hide} />
<Toast status="warning" message="2 campaigns are missing UTM parameters" onClose={hide} />
<Toast status="error" message="Couldn't publish the landing page" onClose={hide} />
```

| `status` | Background |
|---|---|
| `success` (default) | `--color-green` #08BD50 |
| `warning` | `--color-orange` #FBBF24 |
| `error` | `--color-red` #F93D3D |

There is no info status. White text on these colours is below the 4.5:1 contrast minimum, most of all on `warning` (about 1.7:1).

### With a link [#with-a-link]

`variant="link-right"` or `"link-left"` adds an underlined 12px text button before or after the message.


```jsx
<Toast
  status="success"
  variant="link-right"
  message="Landing page published"
  link="View page"
  onLinkClick={openPage}
  onClose={hide}
/>
<Toast
  status="error"
  variant="link-left"
  message="HubSpot sync failed"
  link="Retry"
  onLinkClick={retrySync}
  onClose={hide}
/>
```

### Auto-dismiss [#auto-dismiss]

By default the bar closes itself after 3 seconds and then calls `onClose`. You own the visibility: render it when something happens and remove it in `onClose`.


```jsx
const [shown, setShown] = useState(false);

<Button label="Add to dashboard" onClick={() => setShown(true)} />
{shown && (
  <Toast
    status="success"
    message="Widget added to Q3 pipeline dashboard"
    onClose={() => setShown(false)}
  />
)}
```

The component does not position itself. `WorkbookChat` portals it into `document.body` inside a wrapper fixed 24px from the bottom and left.

<Callout>

`onClose` runs 250ms after the exit animation starts. If you do not unmount the toast then, it stays in the layout, invisible, because the animation holds it at opacity 0. The timer restarts whenever `onClose` changes, so an inline arrow function resets the 3 seconds on every parent re-render; wrap it in `useCallback` if the parent re-renders often. The message never wraps (`white-space: nowrap`), so long messages overflow.

</Callout>

### Toast props [#toast-props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `status` | `"success" \| "warning" \| "error"` | `"success"` | |
| `message` | `ReactNode` | `"Notification"` | |
| `variant` | `"default" \| "link-right" \| "link-left"` | `"default"` | `default` has no link. |
| `link` | `string` | `"View link"` | Link text. Only shown with a link variant. |
| `onLinkClick` | `() => void` | | |
| `onClose` | `() => void` | | Called after the close button or the timer. |
| `duration` | `number` | `3000` | Milliseconds. `0` or less turns auto-dismiss off. |
| `className` | `string` | | |

No other prop is passed through.

## Accessibility [#accessibility]

- sonner renders its toasts in a labelled `aria-live` region, so screen readers announce them without moving focus. People can pause the timer by hovering over the toasts.
- `Toast` from `@/ui` has no role and no live region, so screen readers do not announce it. Its close button has `aria-label="Close"`; the link is a native `<button>`.
- Do not put the only way to finish a task inside a toast. It disappears, and keyboard users may never reach it.

## Do and don't [#do-and-dont]

- Do use `toast.success` and `toast.error` from `sonner` in new code.
- Do write what happened in plain words: "Landing page published", "HubSpot sync failed. Try again in a few minutes."
- Do keep it to one line. Put detail on the page, not in the toast.
- Don't paste raw error messages. Many current calls end with `${e.message}`; prefer a sentence the person can act on.
- Don't toast things the person can already see change on screen, such as a toggle switching.
- Don't mount another `<Toaster>` inside the app layout. Every toast would show twice.
- Don't use `Toast` from `@/ui` outside the workbook.


# Toggle (/work/petavue-design-system/docs/components/toggle)

```jsx
import { Toggle } from "@/ui";
```

## Usage [#usage]

Toggle is controlled: pass `checked` and flip it in `onChange`. `onChange` receives the native change event; call sites ignore it and flip their own state.


```jsx
const [pixel, setPixel] = useState(true);

<Toggle
  label="Include the Petavue tracking pixel"
  checked={pixel}
  onChange={() => setPixel(!pixel)}
/>
```

The label always sits to the right of the switch, 8px away, and the whole row is clickable. Name the setting in the label, not the action: "Sitemap indexing", not "Turn on sitemap indexing".

## With a hint [#with-a-hint]

When the effect of a setting is not obvious, add a 12px `--color-text-secondary` line underneath that says what the current position means. Indent it 38px so it lines up with the label. Toggle has no hint prop, so this is your own markup.


```jsx
<Toggle label="Sitemap indexing" checked={sitemap} onChange={() => setSitemap(!sitemap)} />
<p style={{ margin: "4px 0 0 38px", fontSize: 12, color: "var(--color-text-secondary)" }}>
  {sitemap
    ? "Search engines can list this page."
    : "Hidden from search engines. Use for pages that only paid campaigns should reach."}
</p>
```

## In a settings row [#in-a-settings-row]

To put the switch at the right end of a row with the setting's name on the left, leave out `label` and pass an `aria-label` with the same words. Without it, the switch has no name.


```jsx
<div className="settings-row">
  <span>Sync HubSpot contacts daily</span>
  <Toggle
    aria-label="Sync HubSpot contacts daily"
    checked={sync.hubspot}
    onChange={() => setSync((s) => ({ ...s, hubspot: !s.hubspot }))}
  />
</div>
```

## States [#states]


```jsx
<Toggle label="Off" checked={false} />
<Toggle label="On" checked />
<Toggle label="Off, disabled" checked={false} disabled />
<Toggle label="On, disabled" checked disabled />
<Toggle label="Some on" indeterminate />
```

| State | Track | Thumb | Hover |
|---|---|---|---|
| Off | `--color-grey-300` | White, left | `--color-grey-500` track |
| On | `--color-primary-500` | White, right | `--color-primary-800` track |
| Focus (keyboard) | `--shadow-focus` ring | | |
| Off, disabled | `--color-grey-200` | `--color-grey-50` | none |
| On, disabled | `--color-primary-300` | `--color-grey-50` | none |
| Intermediate | `--color-primary-500` | A 12 by 4px white bar in the middle | `--color-primary-800` track |
| Intermediate, disabled | `--color-primary-300` | `--color-grey-50` bar | none |

Use `indeterminate` on a toggle that controls a group, such as "Sync all sources", when only some of the group are on. It matches Figma's **Intermediate** state, and screen readers hear "mixed".

The track is 30 by 16px with fully rounded ends, and the 14px thumb slides 14px in 0.2s. The label is 14px regular `--color-text-primary`, and `--color-text-disabled` when disabled.

There is one size. Some call sites pass `size="lg"`, but Toggle has no `size` prop: the value ends up as an attribute on the hidden input and changes nothing.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `ReactNode` | `""` | Text after the switch. When empty, nothing is rendered and you must pass `aria-label`. |
| `checked` | `boolean` | `false` | Controlled. |
| `indeterminate` | `boolean` | `false` | Shows the bar. Takes priority over `checked`. |
| `onChange` | `(event) => void` | | Receives the native change event. |
| `disabled` | `boolean` | `false` | |
| `className` | `string` | | Added to the wrapping `<label>`. Use for layout only. |

Any other prop (`aria-label`, `aria-describedby`, `name`, `ref`) is passed to the hidden `<input>`.

## Accessibility [#accessibility]

- It is a native checkbox with `role="switch"`, visually hidden inside a `<label>`. Space toggles it, and screen readers announce it as a switch that is on or off.
- The focus ring shows on keyboard focus only (`:focus-visible`).
- Several toggles in the product (Data hub status, column and table switches) have no `label` and no `aria-label`, so screen readers announce an unnamed switch. Always give one or the other.
- If you add a hint line, give it an `id` and pass `aria-describedby` so it is read with the switch.

## Do and don't [#do-and-dont]

- Do use a Toggle for a setting that is on or off, such as tracking, indexing or a sync, where the state is the point.
- Do keep the label the same in both positions. Say what changes in a hint line, not by rewriting the label.
- Don't use a Toggle to pick items from a list or to agree to terms. Use a [Checkbox](/work/petavue-design-system/docs/components/checkbox).
- Don't use a Toggle for a choice between two named options, such as "Monthly" and "Quarterly". Use [Radio](/work/petavue-design-system/docs/components/radio).


# Tooltip (/work/petavue-design-system/docs/components/tooltip)

```jsx
import { Tooltip } from "@/ui";
```

Tooltip wraps MUI's Tooltip in Petavue styling: a dark box with 12px white text that fades in over 180ms. Use it to name an icon-only control, to explain a control whose label cannot say everything, or to show text that has been cut short.

<Callout>

`InfoTooltip`, also exported from `@/ui`, is a different thing: a static label with an info icon that does not open or position itself. `src/components/Tooltip.jsx` is a third, hand-built tooltip that nothing imports. Use the default `Tooltip` export described here.

</Callout>

## Usage [#usage]

Wrap one element and give the text in `title`. Pass `describeChild` so the element keeps its own name and the tooltip is read as extra description.


```jsx
<Tooltip title="Pull the latest numbers from HubSpot and Google Ads" describeChild>
  <Button variant="secondaryGhost" label="Refresh data" icon={ArrowsClockwise} />
</Tooltip>
```

The child must accept a ref and pass on the event props it receives. Button, native elements and anything built with `forwardRef` do. A plain function component that drops unknown props does not, and the tooltip will never open.

## Icon-only buttons [#icon-only-buttons]

Give the button an `aria-label` and pass `describeChild`. A child's own `aria-label` always takes priority over the tooltip, and with `describeChild` the tooltip text is never used as the name, so the tooltip can later say more than the label without renaming the button.


```jsx
<Tooltip title="Delete page" describeChild>
  <Button variant="secondaryGhost" icon={Trash} aria-label="Delete page" />
</Tooltip>
```

## When the tooltip is the name [#when-the-tooltip-is-the-name]

Without `describeChild`, a text `title` is copied onto the child as its `aria-label`, unless the child passes an `aria-label` of its own. That is fine for an icon-only button with no label, where the tooltip text is the name.


```jsx
<Tooltip title="Download as CSV">
  <Button variant="secondaryGhost" icon={DownloadSimple} />
</Tooltip>
```

| | Without `describeChild` | With `describeChild` |
|---|---|---|
| Text `title` | Set as the child's `aria-label`. An `aria-label` passed on the child wins. | The child keeps its name. While open, the tooltip is linked with `aria-describedby`. While closed, the text is also set as the child's `title` attribute. |
| Element `title` | While open, the tooltip becomes the child's name through `aria-labelledby`. | While open, linked with `aria-describedby`. |

Any control with visible text needs `describeChild`. An `aria-label` overrides visible text, so without it "Refresh data" above would be announced as "Pull the latest numbers from HubSpot and Google Ads".

## Placement [#placement]

The default is `bottom`. Use `top` for most controls in the product so the tooltip does not cover what comes next. `left` and `right` suit narrow rails. Add `arrow` when the tooltip could be read as belonging to a neighbouring control. MUI flips the tooltip to the other side if there is no room.


```jsx
<Tooltip title="Opens above" placement="top">…</Tooltip>
<Tooltip title="Opens below" placement="bottom">…</Tooltip>
<Tooltip title="Opens to the left" placement="left">…</Tooltip>
<Tooltip title="Opens to the right" placement="right">…</Tooltip>
<Tooltip title="With an arrow" placement="top" arrow>…</Tooltip>
```

## Text that is cut short [#text-that-is-cut-short]

With `displayTooltipOnOverflow`, the tooltip only opens when its child is actually truncated. Hover both names: only the long one opens. The child must be the element that has the ellipsis, because that is the one measured. A ResizeObserver re-checks when the width changes.


```jsx
<Tooltip title={campaign.name} displayTooltipOnOverflow placement="top">
  <span className="block truncate max-w-[200px]">{campaign.name}</span>
</Tooltip>
```

## Rich content [#rich-content]

`title` can be any element, such as a small legend. Keep it to a few lines. Raise or lower the width cap with `maxWidth`. If people need to click inside it, use a popover instead.


```jsx
<Tooltip title={<SyncStatusLegend />} arrow placement="top" maxWidth="260px" describeChild>
  <span tabIndex={0} aria-label="What the sync colours mean"><Info size={16} /></span>
</Tooltip>
```

## On a disabled control [#on-a-disabled-control]

A disabled button does not fire the events the tooltip listens for, and MUI logs an error if you wrap one directly. Wrap it in a focusable `<span>` and put the tooltip on that. This is the right place to say why the action is not available.


```jsx
<Tooltip title="Connect a domain before you publish" placement="top">
  <span className="inline-flex" tabIndex={0}>
    <Button variant="primary" label="Publish page" disabled />
  </span>
</Tooltip>
```

## Look [#look]

| Part | Style |
|---|---|
| Box | `#424766` (`--color-neutral-700`) with a 1px `#EEF0F7` (`--color-neutral-100`) border, 6px corners, 4px by 12px padding. |
| Text | 12px Poppins, white. |
| Width | Up to `maxWidth`, 642px by default. |
| Arrow | Same colour as the box. |
| Gap | 6px from the child, plus MUI's 4px margin. |
| Motion | Fades in and out over 180ms. |

The colours are hard-coded in `Tooltip.jsx` rather than read from the tokens. They match the tokens named above.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `title` | `ReactNode` | | Required for the tooltip to show. An empty value shows nothing. |
| `children` | one element | | Must accept a ref and pass on event props. |
| `placement` | `"top" \| "bottom" \| "left" \| "right"`, plus `-start` and `-end` forms | `"bottom"` | |
| `arrow` | `boolean` | `false` | |
| `describeChild` | `boolean` | `false` | Keep the child's own name. See above. |
| `displayTooltipOnOverflow` | `boolean` | `false` | Only open when the child is truncated. |
| `maxWidth` | `string` | `"642px"` | |
| `tooltipActive` | `boolean` | `true` | `false` renders the child with no tooltip at all. |
| `disableHover` | `boolean` | `false` | Hover does nothing. Focus and touch still open it. |
| `open` | `boolean` | | Controls the open state from outside. |
| `disablePortal` | `boolean` | `false` | Render inside the parent instead of at the end of `<body>`. Rarely needed. |
| `styles` | `{ tooltip?, arrow? }` | `{}` | Style overrides for the box and the arrow. Avoid; the look should match everywhere. |
| `triggerResizeProps` | `array` | `[]` | Accepted but not used for anything except the memo comparison. |

Any other prop (`enterDelay`, `leaveDelay`, `onOpen`, `onClose`, `followCursor` and so on) is passed to MUI's Tooltip.

<Callout>

The component is wrapped in `memo` with a custom comparison that only looks at `children`, `title`, `placement`, `open`, `tooltipActive`, `displayTooltipOnOverflow`, `disableHover`, `disablePortal`, `maxWidth`, `styles` and `triggerResizeProps`. Changing any other prop on its own, such as `arrow` or `describeChild`, may not re-render the tooltip.

</Callout>

## Accessibility [#accessibility]

- The tooltip opens on mouse hover after 100ms, on keyboard focus, and on a long press on touch screens. It closes when the pointer or focus leaves, and on Escape.
- The tooltip itself has `role="tooltip"`.
- Do not put anything people need to read only in a tooltip. Touch users rarely see it. Put essential information on the page.
- Use `describeChild` whenever the child has visible text or a label of its own. See the table above.
- Make the child focusable. A tooltip on a plain `<span>` or icon needs `tabIndex={0}` and an `aria-label`, or keyboard users never see it.

## Do and don't [#do-and-dont]

- Do keep tooltip text short: a name, or one sentence.
- Do use a tooltip to say why a control is disabled.
- Do use `displayTooltipOnOverflow` for names that may be cut short in tables and cards.
- Don't put links, buttons or form fields inside a tooltip. It closes as the pointer moves towards them.
- Don't repeat the visible label in the tooltip. "Refresh data" does not need a tooltip saying "Refresh data".
- Don't restyle it with `styles`. Every tooltip in the product should look the same.


# Widget access dialog (/work/petavue-design-system/docs/components/widget-access-dialog)

```jsx
import { WidgetAccessDialog } from "@/ui";
```

WidgetAccessDialog matches the Figma **Widget Access** component. It opens from a dashboard widget's menu. It walks through four states: Generate, Generating, Copy Link and Copied. It is a Small [Dialog](/work/petavue-design-system/docs/components/dialog) with no icon and no footer.

## Try it [#try-it]

Generate a link, copy it, then open Additional information to see the API key. Copied changes back to Copy Link after two seconds.


```jsx
const [link, setLink] = useState(null);
const [generating, setGenerating] = useState(false);

<WidgetAccessDialog
  link={link}
  generating={generating}
  onGenerate={async () => { setGenerating(true); setLink(await createLink()); setGenerating(false); }}
  apiKey={user.apiKey}
  docsHref="/docs/widget-links"
  onOpenProfile={() => navigate("/profile")}
  onClose={close}
/>
```

## States [#states]


| Figma state | Props | Button |
|---|---|---|
| Generate | no `link` | `primary` "Generate Link" with a link icon |
| Generating | `generating` | Primary 300, "Generating Link" with a Spinner, not clickable |
| Copy Link | `link` | Link field, then `primary` "Copy Link" |
| Copied | after a click on Copy Link | "Copied" with a check, for two seconds |

Once there is a link, the Additional information box appears below it. Closed, it shows one line. Open, it explains the file formats and the API key, and shows the key masked, with buttons to reveal and copy it.

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Panel | Small Dialog, 460px, no icon, no footer |
| Body | 12px text, 0 12px 16px padding, 16px gaps |
| Link field | Grey 50 fill, 0.5px Grey 200 border, 8px radius, 12px Grey 600 text cut with an ellipsis |
| Buttons | Full-width Medium Buttons, 10px below the field |
| Additional information | 1px Grey 100 border, 6px radius, 8px padding, 12px Grey 600 text. File types in JetBrains Mono on Grey 50 |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `link` | `string \| null` | `null` | Set it once generated. |
| `generating` | `boolean` | `false` | |
| `onGenerate` | `function` | | |
| `apiKey` | `string` | | Shown masked. Leave it out to hide the key row. |
| `docsHref` | `string` | | "Know more" link. Leave it out to hide it. |
| `onOpenProfile` | `function` | | The Profile link. |
| `onClose` | `function` | | |

## Accessibility [#accessibility]

- The Additional information toggle is a button with `aria-expanded`.
- The reveal and copy buttons for the key are labelled "Show API key" and "Copy API key".
- The Copy Link button is `aria-live`, so screen readers hear "Copied".


# Colour (/work/petavue-design-system/docs/foundations/colour)

Colour tokens are defined once, in `src/ui/tokens/tokens.css`. The swatches on this page are read from that file, so they always show what ships.

Name tokens by role first and shade second: `--color-<group>-<step>`. Use the variable, never the hex.

## Primary [#primary]

The brand blue. Use it for the main action, links, focus rings and selected states. `--color-primary-500` is the brand colour; 50 and 100 are for tinted backgrounds such as a selected row or a hover.



## Grey [#grey]

Surfaces, borders, dividers, placeholder text and icons. Page backgrounds use 50, borders 100 or 200, and secondary text 500.



## Text [#text]

Use these for type rather than picking a grey by eye. `--color-text-secondary` is `#757A97`, the same as `--color-grey-500`.



<Callout>

`src/index.css` also defines older aliases such as `--text-secondary`, which resolves to `#383B55`, a darker grey. New code should use `--color-text-secondary`.

</Callout>

## Status [#status]

Each status has a solid colour for icons, dots and strong text, and a soft background for fills. Do not use status colours for decoration.



| Status | Use for |
|---|---|
| Green | Success, published, on track, positive change |
| Red | Errors, destructive actions, at risk, negative change |
| Orange | Warnings and anything that needs attention this week |

## Purple [#purple]

Reserved. It marks components in the Library and the Creative agent family. Do not use it as a general accent or for charts.



## Icon [#icon]

Icons take one of three greys by state, or the primary blue when they belong to an active or selected item.



## In use [#in-use]

A typical card: primary blue for the eyebrow and the link, text-primary for the title, text-secondary for the description, and a status pill.


```css
.pipeline-card__eyebrow { color: var(--color-primary-500); }
.pipeline-card__title   { color: var(--color-text-primary); }
.pipeline-card__text    { color: var(--color-text-secondary); }
.pipeline-card__status  { background: var(--color-green-bg); color: var(--color-green); }
```

## Contrast [#contrast]

- Body text on white uses `--color-text-primary` (`#232532`).
- `--color-text-secondary` (`#757A97`) is for supporting text at 12px or larger, never for long paragraphs.
- Do not put white text on `--color-orange`; use dark text on the soft background instead.


# Iconography (/work/petavue-design-system/docs/foundations/iconography)

Petavue uses [Phosphor](/work/petavue-design-system/docs/icons). Every icon is a React component.

```jsx
import { ChartBar, Funnel, Megaphone } from "@phosphor-icons/react";

<Megaphone size={16} />
```

<Callout>

Some older screens import from `lucide-react`. New code uses Phosphor only, so one screen never mixes two icon styles.

</Callout>

## Size [#size]

Match the icon to the text next to it.

| Text | Icon size |
|---|---|
| 12px (buttons, labels, pills) | 14px |
| 14px (body, menu items, inputs) | 16px |
| 16px and up (titles, empty states) | 18 to 24px |

## Weight [#weight]

- `regular` everywhere by default.
- `fill` for the active item in navigation, and for a selected toggle.
- `bold` only for tiny glyphs that disappear at regular weight, such as a 12px check.

## Colour [#colour]

Icons inherit the text colour unless they mean something on their own.

| State | Colour |
|---|---|
| Resting | `--color-icon-default` |
| Hover or active row | `--color-icon-active` |
| Disabled | `--color-icon-disabled` |
| Selected, or part of a primary action | `--color-primary-500` |
| Status | The status colour, such as `--color-green` |

## Rules [#rules]

- An icon on its own needs an accessible name: `aria-label` on the button, or a Tooltip with `describeChild`.
- An icon next to a label is decoration. Leave it out of the accessible name.
- One icon per idea across the product. If Library uses `Shapes`, nothing else uses `Shapes` for something different.


# Logos (/work/petavue-design-system/docs/foundations/logos)

Every file on this page comes from the "Petavue - Design System" Figma file, page "Logo". Click any logo to download it.

## Petavue logo [#petavue-logo]

Three layouts, each for a light and a dark background. On a light background the logo is the brand blue; on a dark background it is white on `--color-primary-500`.


| Layout | Use for | Files |
|---|---|---|
| Logo | Navigation rail, favicons, small spaces | `mark-light.svg`, `mark-dark.svg` |
| Logo and name, horizontal | Headers, sign-in, emails | `horizontal-light.svg`, `horizontal-dark.svg` |
| Logo and name, vertical | Splash and empty screens, centred layouts | `vertical-light.svg`, `vertical-dark.svg` |

The favicon is a separate 32px file: [`/logos/brand/favicon.svg`](/logos/brand/favicon.svg).

### In code [#in-code]

Use `BrandLogo` instead of an image file. It draws the same mark as an inline SVG, so it takes the brand colour from the tokens.


```jsx
import { BrandLogo } from "@/ui";

<BrandLogo variant="icon" size="md" />
<BrandLogo variant="full" size="md" />
<BrandLogo variant="full" size="md" mode="dark" />
```

| Prop | Values | Default |
|---|---|---|
| `variant` | `"icon"` (logo only) or `"full"` (logo and name) | `"full"` |
| `mode` | `"light"` or `"dark"` | `"light"` |
| `size` | `"sm"` (24px), `"md"` (32px), `"lg"` (40px) | `"md"` |

<Callout>

`BrandLogo` only has the horizontal layout. For the vertical layout, use `vertical-light.svg` or `vertical-dark.svg`.

</Callout>

### Rules [#rules]

- Do not recolour, stretch, rotate or add effects to the logo.
- Use the dark version only on the brand blue, never on grey or on photos.

## Integration logos [#integration-logos]

The 30 tools in the Figma file, in their own colours.


### Sizes [#sizes]

Figma has each logo at three sizes. The files here are the large version; they scale down cleanly.

```jsx
<img src="/logos/integrations/hubspot.svg" alt="" width={24} height={24} />
```

| Size | Pixels | Use for |
|---|---|---|
| Small | 16 | Inline with 12px or 14px text: table cells, menu items, recommendation cards |
| Medium | 24 | Lists of sources and integration rows |
| Large | 48 | Integration cards and connection screens |

### Rules [#rules-1]

- Show a vendor's logo only when you mean that product. When a label is a category, such as "CRM", use a neutral Phosphor icon instead, because the customer may run a different tool.
- A logo next to the tool's name is decoration: give it `alt=""`. A logo on its own needs the name as `alt` or a Tooltip.
- Never change a vendor's colours.

## In the product today [#in-the-product-today]

The app reads its integration logos from `src/assets/integrations` through `SourceIcon`. That folder and Figma only partly overlap.

| | Logos |
|---|---|
| In both | HubSpot, Salesforce, Snowflake, Gong, ZoomInfo, Marketo, Outreach, Segment, Google Analytics (`GA4.svg` in the app) |
| Only in Figma | Gainsight, Mixpanel, Zendesk, Slack, Amplitude, PostgreSQL, SingleStore, Mailchimp, Aircall, Freshdesk, Bombora, Clearbit, Oracle, Bullhorn, Pendo, Jira, BigQuery, Redshift, Elastic, SurveyMonkey, ServiceNow |
| Only in the app | Google Ads, LinkedIn, Meta Ads, 6sense, NetSuite, PartnerStack, Salesloft, Splash, Webflow, Apollo, lemlist |

The paid media logos the product leans on most (Google Ads, LinkedIn, Meta Ads) are not in the Figma file yet.


# Motion (/work/petavue-design-system/docs/foundations/motion)

Motion tells people where something came from or that their action worked. If it does neither, leave it out.

## Durations [#durations]

| What | Duration | Easing |
|---|---|---|
| Hover, focus and colour changes | 0.15s | `ease` |
| Menus and tooltips opening | 0.1 to 0.15s | `ease-out` |
| Content entering the page | 0.4s | `[0.16, 1, 0.3, 1]` |
| Dialogs and panels | 0.2s | `ease-out` |

These are the values the product already uses most: 0.15s CSS transitions on interactive elements, and a 0.4s fade-up for page content.

## CSS transitions [#css-transitions]

Transition only the properties that change. Never use `transition: all`.

```css
.campaign-row {
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
```

## Entering content [#entering-content]

Use `motion/react` for content that appears: a short fade with a small upward move. Stagger siblings by about 0.05s.

```jsx
import { motion } from "motion/react";

const fadeUp = (delay = 0) => ({
  initial: { opacity: 0, y: 8 },
  animate: { opacity: 1, y: 0 },
  transition: { duration: 0.4, delay, ease: [0.16, 1, 0.3, 1] },
});

<motion.div {...fadeUp(0.05)}>…</motion.div>
```

## Reduced motion [#reduced-motion]

Respect `prefers-reduced-motion`. Remove movement and keep only the fade, or show the end state at once.

```css
@media (prefers-reduced-motion: reduce) {
  .campaign-panel { animation: none; transition: none; }
}
```

## Don't [#dont]

- Don't animate layout on every hover.
- Don't add bounce or spring overshoot to product UI.
- Don't delay a result so an animation can finish.


# Radius and elevation (/work/petavue-design-system/docs/foundations/radius-and-elevation)

All three come from `src/ui/colorography/tokens.css`.

## Radius [#radius]



| Token | Use for |
|---|---|
| `--radius-sm` | Chips, inline code, small tags |
| `--radius-md` | Buttons, inputs, cards, menus, table containers |
| `--radius-lg` | Dialogs and large panels |
| `--radius-pill` | Pills, avatars and round icon buttons |

## Borders [#borders]



Use `--border-default` with `--color-grey-200` for card and input outlines, and `--color-grey-100` for dividers inside a card.

## Shadows [#shadows]

Petavue is flat. A surface that sits on the page uses a border, not a shadow. Shadows are for things that float above the page: menus, popovers, tooltips and dialogs.



| Token | Use for |
|---|---|
| `--shadow-sm`, `--shadow-md` | A card that lifts on hover |
| `--shadow-lg` | Menus and popovers |
| `--shadow-focus` | The focus ring on inputs and buttons |
| `--shadow-error-focus` | The focus ring on an input in an error state |

```css
.campaign-card:hover {
  border-color: var(--color-grey-300);
  box-shadow: var(--shadow-md);
}
```

## Shadow and overlay in Figma [#shadow-and-overlay-in-figma]

The Figma design system ("Shadows" frame) specifies one shadow for floating cards and one overlay colour behind dialogs.

```css
/* Figma: drop shadow, x 0, y 12, blur 12, spread 8, #7A7A7A at 8% */
box-shadow: 0 12px 12px 8px rgba(122, 122, 122, 0.08);
```

```css
/* Figma: overlay #444444 at 40% */
background: rgba(68, 68, 68, 0.4);
```

<Callout>

Neither value exists as a token in the code yet. The closest, `--shadow-lg`, is `0 4px 12px rgba(31, 33, 46, 0.1)`, and dialogs in the app each pick their own scrim colour. Until tokens are added, use the values above for anything new that floats or dims the page.

</Callout>


# Spacing (/work/petavue-design-system/docs/foundations/spacing)

Spacing tokens live in `src/ui/colorography/tokens.css`. Use them for padding, margins and gaps.



## How to choose [#how-to-choose]

| Space | Typical use |
|---|---|
| 4 to 8px | Between an icon and its label, inside chips and pills |
| 12px | Between related controls in a row |
| 16px | Card padding, gaps in a grid of cards |
| 24px | Between groups inside a page section |
| 32 to 48px | Between page sections |
| 64 to 80px | Above and below a page's hero area |

```css
.recommendation-card {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-12);
  padding: var(--spacing-16);
}
```

In Tailwind, use the default spacing utilities (`gap-3` is 12px, `p-4` is 16px). They follow the same 4px steps.

## Rules [#rules]

- Group related things by putting less space between them than between groups.
- Inside a component, keep padding the same on all sides unless the content is a single line of text.
- Avoid 6px and 10px for new layout. They exist for a few compact components.


# Typography (/work/petavue-design-system/docs/foundations/typography)

The source is the Typography board in the Figma design system. In code, sizes, line heights and classes live in `src/ui/typography/typography.css`.

## Typeface [#typeface]

Poppins, in three weights. Use weight for emphasis within a size; do not reach for a bigger size to make something stand out.



## Scale [#scale]

This is the scale in the Figma design system (page "Typography"). Each style comes in Semibold, Medium and Regular, and is published as a Figma text style such as `Body/H1/Medium`.


### Figma and code [#figma-and-code]

The code classes in `typography.css` mostly match, with three differences:

| Figma | Code | What to do |
|---|---|---|
| Display 1 (24/36) | `.text-display-2-*` | Use `.text-display-2-*`. The names are off by one. |
| Display 2 (20/32) | `.text-display-3-*` | Use `.text-display-3-*`. |
| Not in Figma | `.text-display-1-*` (28/40) | Avoid until it is added to Figma. |
| H3 (14/22) | No class | Use `.text-body-1-*`; the values are the same. |

<Callout>

Two files in the code define these classes: `src/ui/style/typography.css`, loaded once for the whole app, and `src/ui/typography/typography.css`, imported by components. Only the second has the 28px display size. Renaming the classes to Figma's names would make the two line up; until then, use the mapping above.

</Callout>

### As read from the code [#as-read-from-the-code]

The same scale as the code defines it, read from `src/ui/typography/typography.css`.


## Which size to use [#which-size-to-use]

| Text | Size | Class |
|---|---|---|
| Page title | 20 or 24px (Figma Display 2 or Display 1) | `.text-display-3-semibold` or `.text-display-2-semibold` |
| Section title, card title | 16px (H2) | `.text-h2-medium` |
| Body, table cells, inputs, menu items | 14px (B1) | `.text-body-1-regular` |
| Labels, buttons, captions, secondary text | 12px (B2) | `.text-body-2-regular` |

<Callout>

The scale includes a 10px `metadata` step. Do not use it in new screens: 12px is the smallest size Petavue shows.

</Callout>

## Rules [#rules]

- Use sentence case everywhere: titles, buttons, menu items and table headers. Capital letters are for names only.
- Uppercase is allowed only for very short labels such as table header captions, at 12px with a little letter spacing.
- Keep line length under about 75 characters for anything people read in full.
- Numbers in tables use `font-variant-numeric: tabular-nums` so columns line up.

```css
.campaign-table__value {
  font-size: 14px;
  font-variant-numeric: tabular-nums;
}
```


# Writing (/work/petavue-design-system/docs/foundations/writing)

The people using Petavue run campaigns, budgets and pipeline. They want to know what happened, why, and what to do next. Copy should get them there in as few words as possible.

## Voice [#voice]

- **Specific.** "Cost per lead rose 18% on LinkedIn this week" beats "Performance changed".
- **Calm.** No exclamation marks, no hype, no urgency that the data does not support.
- **Plain.** Use the words marketers use: campaign, pipeline, spend, lead, conversion. Avoid internal names and ids.

## Patterns to avoid [#patterns-to-avoid]

These read as machine-written and make the product feel generic.

| Avoid | Write instead |
|---|---|
| "Good evening, Alex! What should we make today?" | "Good evening, Alex." |
| "Dashboards, reports and more — all in one place." | Let the controls show what is possible. |
| "Powerful", "seamless", "effortless", "unlock" | Say what it does. |
| A dash used to join a slogan to a claim | Two short sentences, or one. |
| "Oops! Something went wrong." | "Could not publish the page. Try again." |

## Buttons and menu items [#buttons-and-menu-items]

A verb and, when needed, an object. Sentence case.

| Avoid | Write |
|---|---|
| OK | Publish page |
| Submit | Send request |
| Click here to view all recommendations | View all |

## Empty states [#empty-states]

Say what is missing and what to do about it, in one or two sentences, with one action.

<Callout>

**No pages yet.** Pages you build from Home appear here. **Build a page**

</Callout>

## Errors [#errors]

Say what failed and what to do. Do not blame the user, and do not apologise at length.

| Avoid | Write |
|---|---|
| Invalid input. | Enter a work email, such as alex@meridian.com. |
| Error 500. | Could not load campaigns. Refresh to try again. |

## Numbers and dates [#numbers-and-dates]

- Use the units people expect: `$12.4K`, `18%`, `2.4x`.
- Show the comparison with the change: "up 18% on last week".
- Dates: "Oct 6", or "Oct 6, 7:34 AM" when the time matters.


# Icons (/work/petavue-design-system/docs/icons)



## Using an icon [#using-an-icon]

```jsx
import { ChartLineUp } from "@phosphor-icons/react";

<ChartLineUp size={16} weight="regular" />
```

Sizes, weights and colours are covered in [Iconography](/work/petavue-design-system/docs/foundations/iconography).


# Getting started (/work/petavue-design-system/docs)

## The stack [#the-stack]

| Part | What we use |
|---|---|
| Framework | React 19, built with Vite 7 |
| Routing | React Router 7 (`src/router.jsx`) |
| Data | TanStack Query for server state, zustand for client state |
| Styling | CSS custom properties for tokens, plain CSS files with BEM class names, Tailwind 4 for page layout |
| Components | `@/ui` (`src/ui/components`), plus the dropdown menu in `@/components/shadcn/dropdown-menu` |
| Icons | Phosphor (`@phosphor-icons/react`) |
| Motion | `motion/react` for enter and exit, CSS transitions for hover and state |
| Toasts | `sonner`, mounted once in the app layout |

`@` is an alias for `src/`.

## Where things live [#where-things-live]

```text
src/
  ui/
    components/      the design system components, exported from @/ui
    tokens/          tokens.css: colour, the single source of truth
    colorography/    tokens.css: spacing, radius, borders, shadows
    typography/      typography.css: font, sizes, line heights, text classes
  components/
    shadcn/          the dropdown menu (Base UI), themed in Petavue colours
  pages/             one folder per area of the product
  mocks/             sample data for the prototype
```

Tokens and components are loaded once in `src/main.jsx`, so every page can use them without importing CSS.

## Using a component [#using-a-component]

Import from `@/ui`. Never import from a component's own folder.

```jsx
import { useState } from "react";
import { Button, TextInput } from "@/ui";

export function RenamePage({ page, onSave }) {
  const [name, setName] = useState(page.name);
  return (
    <form className="rename-page" onSubmit={(e) => { e.preventDefault(); onSave(name); }}>
      <TextInput label="Page name" value={name} onChange={(e) => setName(e.target.value)} />
      <Button type="submit" variant="primary" label="Save" />
    </form>
  );
}
```

## Using tokens [#using-tokens]

Use the CSS variables. Never paste a hex value into new code.

```css
.pipeline-card {
  padding: var(--spacing-16);
  border: var(--border-default) solid var(--color-grey-200);
  border-radius: var(--radius-md);
  color: var(--color-text-primary);
}
```

In Tailwind, the grey and primary ramps exist as utilities (`text-grey-500`, `bg-primary-50`). For everything else, use the variable in an arbitrary value: `text-[var(--color-text-secondary)]`.

## Rules every screen follows [#rules-every-screen-follows]

1. **Use the component, not a lookalike.** If `@/ui` has a Button, Dialog, Dropdown or Tooltip, use it. A `<div>` styled to look like a button is a bug.
2. **Tokens only.** Colour, spacing, radius and shadow come from tokens. If no token fits, raise it; do not add a one-off value.
3. **Product palette only.** Blue for actions and focus, greys for everything structural, green, red and orange for status. Purple is reserved for components and the Creative agent family.
4. **Two text sizes for most UI: 14px and 12px.** Bigger sizes are for page and section titles. Nothing below 12px.
5. **One primary action per area.** Every other action is quieter.
6. **Plain copy.** Short, specific, no exclamation marks, no taglines. See [Writing](/work/petavue-design-system/docs/foundations/writing).
7. **Class names say what a thing is.** Library code uses BEM (`lib-card__title`), never utility soup that hides meaning. Tailwind is fine for page layout.
8. **Change a shared component only when the change should apply everywhere.** For a one-off, style around it with a scoped class.

## Working with an AI coding agent [#working-with-an-ai-coding-agent]

Point the agent at [/llms.txt](/work/petavue-design-system/llms.txt) before it writes UI. Every page here is also available as Markdown: use "Copy Markdown" at the top of any page, or open `/llms.mdx/docs/<page>/content.md`. The rules agents follow are in [For AI & LLMs](/work/petavue-design-system/docs/ai).


# Chat composer (/work/petavue-design-system/docs/patterns/chat-composer)


```jsx
<div className="composer">                       {/* grey frame */}
  <div className="composer__box">                {/* white box */}
    <textarea placeholder="Ask anything…" />
    <div className="composer__row">
      <Button variant="ghost" icon={Paperclip} aria-label="Attach files" />
      <ComposerMenu label="Output" value={output} options={OUTPUTS} onChange={setOutput} />
      <ModelModeMenu value={mode} onChange={setMode} />
      <button className="composer__send" aria-label="Send" disabled={!text.trim()}>
        <ArrowUp size={18} weight="bold" />
      </button>
    </div>
  </div>
  <div className="composer__tray">               {/* build options */}
    <Button variant="ghost">Design system <b>Meridian</b></Button>
  </div>
</div>
```

## Anatomy [#anatomy]

- **White box:** the text field, attach, what to make (Output), the model, and send. Nothing else.
- **Grey tray:** options that shape what gets built, such as template, format, style and design system. It changes with the Output choice.
- **Send:** a round primary button, grey and disabled until there is text.

## Behaviour [#behaviour]

- Enter sends; Shift and Enter adds a new line.
- The placeholder describes the current Output ("Describe the page you want…").
- Attached files appear as chips above the text, each with a remove button.
- The model choice is remembered for the next visit.

## Prompts under the composer [#prompts-under-the-composer]

Starter prompts sit under the composer as pills, at most two rows. Each pill names a specific thing to build ("Demo page for the Q4 campaign"), with an icon for its type in the brand blue.


# Dialogs and confirmation (/work/petavue-design-system/docs/patterns/dialogs)

`Dialog` from `@/ui` is the panel only: title, body, and Cancel and Confirm buttons. The screen that opens it supplies the scrim, closes it on Escape and on a click outside, and gives it `role="dialog"`.


```jsx
{open && (
  <div className="page-dialog__scrim" onClick={close}>
    <div role="dialog" aria-modal="true" aria-label="Delete this page?" onClick={(e) => e.stopPropagation()}>
      <Dialog
        title="Delete this page?"
        confirmLabel="Delete page"
        onClose={close}
        onCancel={close}
        onConfirm={remove}
      >
        <p>“Demo page” is live at pages.petavue.com/demo. Deleting it takes it offline, and the LinkedIn demo ads that point to it will show an error page.</p>
      </Dialog>
    </div>
  </div>
)}
```

## When to use one [#when-to-use-one]

- To confirm an action that cannot be undone, or that affects other people (deleting, unpublishing, sending).
- For a short, focused task with a clear end, such as renaming or publishing.

Do not use a dialog for information people need to keep referring to, or for long multi-step work. Use a page or a side panel.

## Writing a confirmation [#writing-a-confirmation]

- The title is the question: "Delete this page?"
- The body says what will happen, with the specific thing named: which page, which campaign, how many people.
- The confirm button repeats the action: "Delete page", not "OK" or "Yes".

<Callout>

`Dialog`'s confirm button is always the primary blue, and its `warning` and `error` states disable it, so it cannot show a working red Delete button yet. Until it can, name the action clearly in the button and the body.

</Callout>

## Behaviour [#behaviour]

- Escape and a click on the scrim close the dialog without acting.
- Move focus into the dialog when it opens, and back to the button that opened it when it closes.
- Only one dialog at a time.


# Empty states (/work/petavue-design-system/docs/patterns/empty-states)


```jsx
<div className="page-empty">
  <span className="page-empty__icon"><FileText size={22} /></span>
  <p className="page-empty__title">No pages yet</p>
  <p className="page-empty__text">Pages you build from Home appear here. Each one is made from your published components.</p>
  <Button variant="primary" label="Build a page" icon={Plus} />
</div>
```

## Anatomy [#anatomy]

| Part | Spec |
|---|---|
| Icon tile | 48px square, `--radius-lg`, grey-50 fill and grey-100 border, a 22px icon in grey-400 |
| Title | 16px medium, what is missing |
| Text | 14px secondary text, at most two sentences, at most 380px wide |
| Action | One button, when there is something to do |

## Kinds of empty [#kinds-of-empty]

| Situation | Title | Action |
|---|---|---|
| Nothing created yet | "No pages yet" | Create the first one |
| A filter or search found nothing | "No pages match these filters" | Clear filters |
| Nothing to do | "You are up to date" | None |
| Something failed to load | "Could not load pages" | Try again |

Do not use illustrations or jokes. The icon is the same one the section uses in navigation.


# Forms (/work/petavue-design-system/docs/patterns/forms)


```jsx
<form onSubmit={save}>
  <TextInput label="Page name" value={name} onChange={(e) => setName(e.target.value)} />
  <TextInput
    label="Send a copy of each submission to"
    value={email}
    onChange={(e) => setEmail(e.target.value)}
    error={tried && !emailOk}
    errorMessage="Enter a work email, such as alex@meridian.com."
  />
  <Dropdown label="Send form submissions to" value={target} onChange={setTarget} options={targets} />
  <TextArea label="Meta description" rows={3} />
  <Toggle label="Search engines can list this page" checked={indexed} onChange={(e) => setIndexed(e.target.checked)} />
  <div className="form__actions">
    <Button variant="ghost" label="Cancel" onClick={onCancel} />
    <Button type="submit" variant="primary" label="Save settings" />
  </div>
</form>
```

Try submitting the example with an empty email to see the error.

## Layout [#layout]

- One column. Labels sit above their field, never beside it.
- 16px between fields, 24px between groups of fields.
- Group related fields under a short heading when a form has more than five or six.
- Actions sit at the bottom right: the primary action last, Cancel before it as a `ghost` button.

## Validation [#validation]

- Validate when the person submits, then again as they fix each field. Do not show errors while they are still typing for the first time.
- Put the error under the field it belongs to, in one sentence that says how to fix it.
- Keep the submit button enabled so people can find out what is missing. Disable it only while the form is saving.

## Labels and placeholders [#labels-and-placeholders]

- Every field has a visible label. A placeholder is a hint, such as an example value, never the label.
- Mark the optional fields, not the required ones, when most fields are required.

## Saving [#saving]

- Show progress on the button itself ("Saving…") and disable it while saving.
- Confirm success with a toast when the form closes, or inline when it stays open.


# Loading (/work/petavue-design-system/docs/patterns/loading)


```jsx
<div className="card">
  <Skeleton width="40%" height={14} />
  <Skeleton width="85%" height={20} className="mt-3" />
  <Skeleton width="70%" height={14} className="mt-2" />
</div>

<Spinner size={20} />
<span>Running step 3 of 5</span>

<Button variant="primary" label={busy ? "Publishing…" : "Publish"} disabled={busy} />
```

Click Publish in the example to see the button state.

## Which to use [#which-to-use]

| Situation | Use |
|---|---|
| A page or card whose shape is known | `Skeleton` blocks in the same layout |
| Work of unknown length, such as an agent running | `Spinner` with a line saying what is happening |
| An action someone just started | The button's own label ("Publishing…"), disabled until done |
| Something that takes more than a few seconds | Show steps ("Running step 3 of 5"), not only a spinner |

## Rules [#rules]

- Do not show a spinner for anything that finishes in under about 300ms.
- Keep what is already on screen while new data loads. Replace it, do not blank the page.
- When the work finishes, confirm it: the result appears, or a toast says it is done.


# Menus and filters (/work/petavue-design-system/docs/patterns/menus-and-filters)

All menus use the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu): a white panel, a light blue row on hover, and a blue tick on the selected item. Do not build a menu from scratch.

## Filters [#filters]

A filter button names what it filters and shows the current value. The list opens aligned to the button's right edge when the button sits at the right of the toolbar.


```jsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="secondaryGhost" size="md" />}>
    <Funnel size={16} />
    <span>Status</span>
    <span style={{ fontWeight: 500 }}>{current.label}</span>
    <CaretDown size={14} />
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    {STATUSES.map((s) => (
      <DropdownMenuItem key={s.id} onClick={() => setStatus(s.id)}>
        <span className="flex-1">{s.label}</span>
        <span>{s.count}</span>
        {s.id === status && <Check size={16} weight="bold" />}
      </DropdownMenuItem>
    ))}
  </DropdownMenuContent>
</DropdownMenu>
```

- Lead the toolbar with the scope (whose items, or which list), then filters on the right.
- Show counts in filter options when they help people choose.
- Keep a filter's value when people leave and come back to the page.

## Actions menus [#actions-menus]

Group a row's secondary actions in one menu. Put destructive actions last, after a separator, with the destructive variant.


```jsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="secondaryGhost" label="Page actions" icon={CaretDown} iconPosition="suffix" />} />
  <DropdownMenuContent>
    <DropdownMenuItem>Rename</DropdownMenuItem>
    <DropdownMenuItem>Duplicate</DropdownMenuItem>
    <DropdownMenuItem>Save as template</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive"><Trash size={16} /> Delete page</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Rules [#rules]

- Use the Petavue Button as the trigger, through `render`. Icon, label, value and caret share one colour.
- Menu items are 14px. A second line, when needed, is 12px secondary text.
- Fewer than three options, or options people should compare side by side, belong in a radio group or a segmented control, not a menu.


# Page header and tabs (/work/petavue-design-system/docs/patterns/page-layout)


```jsx
<header className="page__header">
  <h1 className="page__title">Library</h1>
  <Button variant="secondary" label="Import from website" />
</header>
<nav className="page__tabs" role="tablist">
  {TABS.map((t) => (
    <button key={t} role="tab" aria-selected={tab === t} onClick={() => setTab(t)}>{t}</button>
  ))}
</nav>
```

## Header [#header]

| Part | Spec |
|---|---|
| Height | 56px, with a grey-100 bottom border |
| Title | 16px medium, the section name only |
| Actions | Right-aligned. At most one primary and one secondary action |

The page title is the name from the navigation. Do not add a subtitle that explains the page.

## Tabs [#tabs]

| Part | Spec |
|---|---|
| Height | 48px, with a grey-100 bottom border |
| Tab text | 14px, grey-600, primary-500 when selected |
| Selected marker | A 2px primary-500 line under the tab |

- Use tabs to switch between lists of the same area, such as Components, Templates and Pages.
- Keep the selected tab when people return to the page.
- More than six tabs means the page needs restructuring, not a scrolling tab bar.


# Agent mark (/work/petavue-design-system/docs/product/agent-mark)

```jsx
import { AgentMark, agentIcon, AGENT_ICONS } from "@/components/AgentMark";
```

Every agent family in `AGENTS` (in `src/mocks/agentWorkflows.js`) has an icon name and a colour. This file turns the name into a Phosphor icon, so a family shows the same glyph on the Agents grid, the workflow graph and the Recommendations page. It has three exports:

- `AgentMark`, the icon drawn filled in the family's colour, with a tooltip that names it.
- `agentIcon(agentKey)`, which returns the icon component for a family, for when you draw it yourself.
- `AGENT_ICONS`, the map from icon name to component that `agentIcon` reads.

## The families [#the-families]


```jsx
{Object.values(AGENTS).map((a) => (
  <span key={a.key}>
    <AgentMark agentKey={a.key} /> {a.label}
  </span>
))}
```

| Key | Label | Icon | Colour | Tint |
|---|---|---|---|---|
| `measurement` | Measurement | `ChartLineUp` | `#3661ED` | `#E0EBFE` |
| `budget` | Budget | `Wallet` | `#0F7B6C` | `#E3F4F1` |
| `delivery` | Campaign | `Broadcast` | `#E0620D` | `#FDEEE2` |
| `demand` | Audience | `Target` | `#C4106A` | `#FCE7F1` |
| `creative` | Creative & message | `PaintBrush` | `#643BCF` | `#EBE3FA` |
| `conversion` | Conversion | `FunnelSimple` | `#8A5524` | `#F5EBE1` |
| `landing` | Landing page | `Browser` | `#1E3A8A` | `#E3E9F8` |

The colours and tints are set per family in `AGENTS`, not taken from the colour tokens. Only Measurement uses a token value (`--color-primary-500`). Keep these colours for agent families: do not reuse them for status, charts or anything else.

<Callout>

`listAgents()` leaves out `creative`, so the Agents page shows six families. The mark still works for it, because recommendations and workflow steps can name it.

</Callout>

## Sizes [#sizes]

`size` sets the icon's width and height in pixels. The default is 20. In the product the family icon is drawn at 11px in pills, 16px in lists, 18px on the workflow graph and 20px in page and drawer headers.


```jsx
<AgentMark agentKey="measurement" size={14} />
<AgentMark agentKey="measurement" size={16} />
<AgentMark agentKey="measurement" />
<AgentMark agentKey="measurement" size={24} />
```

## In a row [#in-a-row]

A workflow uses several families. Put their marks side by side with a 2px gap, next to the workflow's name. Each mark names its family on hover.


```jsx
<span className="inline-flex items-center gap-0.5">
  <AgentMark agentKey="measurement" size={16} />
  <AgentMark agentKey="demand" size={16} />
  <AgentMark agentKey="conversion" size={16} />
</span>
<span>LinkedIn buyer-title targeting</span>
```

## Drawing the icon yourself [#drawing-the-icon-yourself]

When the family's name is already printed, as in the pill the Recommendations page puts on each step of an analysis, take the icon from `agentIcon` and skip the tooltip. Draw it with `weight="fill"` so it matches the mark.


```jsx
const a = AGENTS[agentKey];
const Icon = agentIcon(agentKey);

<span className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded-md text-[12px] font-medium" style={{ background: a.tint, color: a.color }}>
  <Icon size={11} weight="fill" />
  {deckFamilyOf(agentKey)}
</span>
```

## Props [#props]

### AgentMark [#agentmark]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `agentKey` | `string` | | A key of `AGENTS`. An unknown key renders nothing. |
| `size` | `number` | `20` | Icon size in pixels. |

There is no `className` and no way to change the colour or weight: the mark is always filled, in the family's colour.

### agentIcon [#agenticon]

| | |
|---|---|
| Signature | `agentIcon(agentKey: string) => PhosphorIcon` |
| Returns | The icon component for the family. `Circle` when the key or its icon name is unknown. |

## Accessibility [#accessibility]

- The tooltip reads "Measurement agent" and so on: the family's label followed by "agent". It uses the [Tooltip](/work/petavue-design-system/docs/components/tooltip) from `@/ui`. The mark is a plain `<span>` that cannot take focus, so the tooltip opens on hover only and keyboard users never see it.
- The wrapper `<span>` carries the same text as `aria-label`, but it has no role, so most screen readers ignore that label. Where the family matters to someone using a screen reader, print its name next to the mark.
- `agentIcon` returns a bare icon with no label. Use it only next to visible text.

## Do and don't [#do-and-dont]

- Do use `AgentMark` or `agentIcon` for a family. Never pick a Phosphor icon for a family by hand, or two pages will disagree.
- Do print the family name beside the icon when there is room. The tooltip is for rows of marks where there is not.
- Don't use a family colour for anything that is not that family.
- Don't add a family by editing this file. Add it to `AGENTS`, and add its icon to `AGENT_ICONS` only if the icon is new.

## Where it is used [#where-it-is-used]

`AgentMark` itself has no callers in `src/` today. Every page below takes the icon from `agentIcon` and colours it by hand.

| File | What it draws |
|---|---|
| `src/pages/agents/index.jsx` | The 16px icon in each family's heading on the Agents page. |
| `src/pages/agents/AgentDetail.jsx` | The 20px icon in an agent's page header. |
| `src/pages/workflows/index.jsx` | A row of 16px icons for the families a workflow uses, with one tooltip that lists them. |
| `src/pages/workflows/WorkflowDetail.jsx` | The 18px icons on the workflow graph's family nodes and in the hand-off list, and the 20px icon in the agent drawer's header. |
| `src/pages/recommendations/index.jsx` | The 11px icon in `FamilyPill`, on each step of "How this was analyzed". |


# Chat pane (/work/petavue-design-system/docs/product/chat-pane)

```jsx
import ChatPane from "@/pages/library/ChatPane";
import "@/pages/library/library.css";
```

`ChatPane` is the left column of every library editor: the conversation that builds or changes what is on the canvas beside it. Its bubbles use the session chat's classes (`s-msg-*`), so it reads as the same chat as the rest of Petavue. An assistant reply can show the steps it took and what it was built from. A part picked on the canvas shows above the text box, and the next message applies to it. When the agent is asking a question, `footer` takes the place of the text box.

The column's right edge can be dragged. Its width is remembered in `localStorage` and shared by every editor.

<Callout>

When it mounts, `ChatPane` focuses its text box (`autoFocus`) and scrolls the end of its thread into view with `scrollIntoView`. Inside a page that scrolls, that moves the whole page. That is why the examples here open in a frame the size of the editor, instead of rendering in place.

</Callout>

## Building a page [#building-a-page]

A thread with a first build and a change to a picked part. The reply shows its steps, then the template and components it used. "Show the description the agent followed for each" opens the description of every component. A part is picked ("Button · Demo request form"), so the placeholder asks what should change there; clear it with the cross.


```jsx
<div className="lib-editor__body">
  <ChatPane
    greeting={BUILD_GREETING}
    thread={page.thread}
    busy={busy}
    placeholder={target ? "What should change here?" : "Describe the change you want…"}
    onSend={send}
    target={target ? { label: targetLabel(page, target) } : null}
    onClearTarget={() => setPicked(null)}
  />
  <section className="lib-stage" aria-label="Page">…</section>
</div>
```

## Asking before it builds [#asking-before-it-builds]

Before the first build, the page builder asks up to three questions. The question card goes in `footer`, which hides the text box and the picked part until it is answered.


```jsx
<ChatPane
  greeting={BUILD_GREETING}
  thread={thread}
  busy={busy}
  placeholder="Describe the page you want…"
  onSend={send}
  footer={asking && !busy && (
    <AskCard step={step} total={questions.length} question={questions[step].question} options={questions[step].options} onAnswer={answer} onSkip={() => answer(null)} onBack={back} />
  )}
/>
```

## Messages [#messages]

`thread` is an array. The greeting is drawn first as an assistant message and is not part of it.

| Message | Shape | Drawn as |
|---|---|---|
| From the person | `{ role: "user", text, target? }` | A right-aligned blue bubble (`--bg-user-msg`, #3661ED). `target` adds a small line above the text with a cursor icon. |
| From the agent | `{ role: "assistant", text, working?, used? }` | The Petavue logo at 20px beside Markdown text. |
| `working` | `string[]` | A list of steps above the text, each with a green filled tick (`--color-green`). 13px secondary text. |
| `used` | `{ title?, template?, components: string[], reasons?: { name, why }[] }` | A grey box under the text: the template as a blue chip, then one chip per component. With `reasons`, a toggle swaps the chips for a numbered list of the descriptions the agent followed. `title` defaults to "Built from your workspace". |

While `busy` is true, a "Thinking…" reply in the muted text colour is added at the end, and the send button is disabled.

## Resizing [#resizing]

| Behaviour | Detail |
|---|---|
| Starting width | 440px |
| Limits | At least 340px, at most 760px. |
| Room for the canvas | The canvas beside it keeps at least 600px, so the chat cannot be dragged past its parent's width minus 600px, and gives way when the window narrows. With a parent under 940px the chat stays at 340px. |
| Drag | Pointer down on the 8px strip along the right edge (`.lib-chat__resizer`). A 2px `--color-primary-300` line shows on hover, on focus and while dragging. While dragging, text selection and pointer events are turned off on the chat and everything after it. |
| Keyboard | Focus the edge with Tab. Left and Right arrows change the width by 24px; Home resets it. |
| Reset | Double-click the edge to go back to 440px. |
| Memory | Every change is saved as `lib-chat-width` in `localStorage` and read by the next editor that opens. If storage is blocked, the width still applies for the visit. |

The parent has to be a row the chat can size against. The editors use `.lib-editor__body`, a grid of `auto minmax(600px, 1fr)` that scrolls sideways when the window is too narrow.

## Anatomy [#anatomy]

| Part | Class | Style |
|---|---|---|
| Column | `.lib-chat` | White, a 1px `--color-grey-100` line on the right, its width set inline. |
| Thread | `.lib-chat__thread` | Scrolls. 24px padding at the top, 16px on the sides and bottom, a 16px gap between messages. |
| Picked part | `.lib-chat__target` | 12px medium `--color-primary-700` on `--color-primary-50`, 8px corners, with a 20px clear button. |
| Composer | `.lib-chat__composer` | A pill with 20px corners and a `--color-grey-200` border that turns `--color-primary-300` on hover and `--color-primary-500` on focus. 14px text. |
| Send | `.lib-chat__send` | A 40px circle in `--color-primary-500`, `--color-primary-600` on hover, grey when disabled. |
| Footer | `.lib-chat__footer` | 16px margin at the sides, 20px below, the same place as the composer. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `greeting` | `string` | | Markdown. The first assistant message. |
| `thread` | `Message[]` | | Required. See [Messages](#messages). |
| `busy` | `boolean` | | Shows "Thinking…" and disables sending. |
| `placeholder` | `string` | | For the text box. Change it with the state: "Describe the page you want…", "What should change here?". |
| `onSend` | `(text: string) => void` | | Called with the trimmed text on Enter or the send button. Empty text and sends while `busy` are ignored. The box is cleared before it is called. |
| `target` | `{ label: string } \| null` | | The part picked on the canvas. Hidden while `footer` is set. |
| `onClearTarget` | `() => void` | | The cross on the picked part. |
| `footer` | `ReactNode` | | Replaces the text box and the picked part. A falsy value shows the text box again. |

## Accessibility [#accessibility]

- The column is a `<section>` labelled "Chat".
- The resize edge has `role="separator"`, `aria-orientation="vertical"`, `aria-valuenow`, `aria-valuemin` and `aria-valuemax`, and the label "Resize the chat. Double-click to reset." It is focusable, and works with the arrow keys and Home. Double-click has no keyboard equivalent other than Home.
- The text box is a single-line `<input>` labelled "Message". Enter sends; there is no way to type a line break.
- The send button and the clear button have `aria-label`s ("Send", "Clear selection").
- New messages are not announced: the thread has no live region, so a screen reader user has to move to the reply to hear it.
- The avatar image has an empty `alt`, so it is skipped.

## Do and don't [#do-and-dont]

- Do put it first in a `.lib-editor__body` row, with the canvas second, so the resize rules work.
- Do set `busy` while a reply is on its way, so people cannot send twice.
- Do use `footer` for a question the agent is asking, instead of a dialog. The conversation stays the one place a request is shaped.
- Don't mount it inside a scrolling page or a small panel. It takes focus and scrolls itself into view.
- Don't use it for the main Petavue chat. That is the session chat, which has its own composer; see [Chat composer](/work/petavue-design-system/docs/patterns/chat-composer).

## When to use it [#when-to-use-it]

Use `ChatPane` for an editor where chat changes something drawn beside it. For a conversation on its own page, use the session chat and its composer, described in [Chat composer](/work/petavue-design-system/docs/patterns/chat-composer).

## Where it is used [#where-it-is-used]

| File | Greeting, `target` and `footer` |
|---|---|
| `src/pages/library/PageBuilderPage.jsx` | `BUILD_GREETING`. The picked section or part of the page. `AskCard` or `DirectionCard` while it asks before building. |
| `src/pages/library/CreativeEditorPage.jsx` | `CREATIVE_GREETING`. The picked layer of the creative. `AskCard` or `DirectionCard`. |
| `src/pages/library/ComponentEditorPage.jsx` | A greeting for the component. No `target` or `footer`. |


# Code view (/work/petavue-design-system/docs/product/code-view)

```jsx
import PageCode, { projectFor } from "@/pages/library/PageCode";
import "@/pages/library/library.css";
```

`PageCode` is what the page builder shows when someone switches the canvas from Preview to Code. It lays a landing page out as the files a developer would expect: one component per section, the page that orders them, the design system as tokens, the stylesheet the sections use, the page settings, and the `index.html` that is served.

The markup is read from the preview itself, by `projectFor`, so the code and the page can never disagree. `PageCode` only displays a list of files; `projectFor` makes that list.

## A page as a project [#a-page-as-a-project]

The page opens on `src/pages/…`, the file that puts the sections in order. Click a file to open it, a folder to fold it, or search by path. Copy puts the open file on the clipboard. Download .zip saves every file in a folder named after the page.


```jsx
// The page builder reads the project off the preview whenever the page or the design changes.
useEffect(() => {
  if (view !== "code" || !pageRef.current) return;
  setFiles(projectFor(pageRef.current, {
    title, description, vars: designVars(design), pixel, slug,
    sections: page.sections, settings, noindex, canonical, gtm, og,
  }));
}, [view, page, design]);

<div className="lib-browser">
  {view === "code" && <PageCode files={files} name={slug} />}
  <div ref={pageRef} className="lib-browser__page" hidden={view === "code"}>…</div>
</div>
```

The preview stays mounted while the code shows (`hidden`), because `projectFor` reads each `[data-key]` section's markup from it.

## Any list of files [#any-list-of-files]

`PageCode` does not care where the files come from. Pass `{ path, content }` objects; folders come from the slashes in `path`.


```jsx
<PageCode
  name="webinar-signup"
  files={[
    { path: "README.md", content: "# Webinar sign-up\n\n…" },
    { path: "src/pages/WebinarSignup.jsx", content: "…" },
    { path: "src/styles/tokens.css", content: ":root { … }" },
  ]}
/>
```

## The files projectFor makes [#the-files-projectfor-makes]

| File | What it holds |
|---|---|
| `README.md` | The page title and what each folder is for. |
| `index.html` | The page as served: meta tags from the page settings (description, `noindex`, canonical, Open Graph), Tag Manager and the tracking pixel when set, the design tokens in a `<style>` block, and each section's markup. |
| `package.json` | A Vite and React 19 project named after the page address. |
| `page.config.json` | The page settings as JSON: address, access, SEO, Open Graph, tracking and forms. The password and the image itself are left out. |
| `src/pages/<Page>.jsx` | Imports each section and renders them in order inside `<main className="lp">`. |
| `src/sections/<Section>.jsx` | One component per section, named from the section name ("Hero with demo form" becomes `HeroWithDemoForm`, with a number added for repeats). The markup is turned into JSX: `className`, `htmlFor`, style objects, self-closed `img` and `input`. |
| `src/styles/sections.css` | The section stylesheet, `src/pages/library/sections.css`, as it is. |
| `src/styles/tokens.css` | The design system as `--lp-*` custom properties. |
| `src/lib/tracking.js` | Only when the pixel is on: the script that loads it. |

Folders are listed before files, and both are sorted by name.

## States [#states]

| State | What shows |
|---|---|
| First open | The first file under `src/pages/`, or the first file. All folders open. |
| File picked | The row turns `--color-primary-100` with `--color-primary-500` text and icon, and has `aria-current`. |
| Folder folded | A right caret instead of a down caret. The fold is kept while the view is open. |
| Searching | Only paths that contain the text, case-insensitive, with every folder open. "No file matches." when nothing does. |
| Picked file gone | If the picked file is no longer in `files`, the page file opens instead. |
| No files | An empty `.lib-code` box. |
| Copied | A toast: "WebinarSignup.jsx copied.", or "Could not copy." |
| Downloaded | A toast: "13 files downloaded as a zip." |

## Anatomy [#anatomy]

| Part | Class | Style |
|---|---|---|
| Files column | `.lib-files` | 232px wide, `--color-grey-50`, a `--color-grey-100` line on the right. |
| Header | `.lib-files__head` | "Files" in 12px medium and the count in `--color-grey-400`. |
| Search | `.lib-files__search` | 30px tall, 8px corners, white, a `--color-grey-100` border that turns `--color-primary-300` on focus. 12px text. |
| Row | `.lib-files__row` | 28px tall, 12px text, 14px icons in `--color-grey-400`, indented 14px per level. `--color-grey-100` on hover. |
| Bar | `.lib-project__bar` | 40px tall: the path in 12px monospace, the line count in `--color-grey-400`, then Copy and Download .zip as small `secondaryGhost` Buttons (30px). |
| Code | `.lib-code` | 12px monospace on a 20px line. A sticky gutter of line numbers in `--color-grey-300` on `--color-grey-50`. |
| Colouring | `.lib-code__tag`, `__attr`, `__value`, `__word` | Tags and CSS properties in `--color-primary-500`, attributes and comments in `--color-grey-500`, strings in green (#0B7A3B), `import` and `return` in `--color-primary-800`. |

The component fills its parent (`flex: 1`), so give the parent a height and `display: flex`.

## Props [#props]

### PageCode [#pagecode]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `files` | `{ path: string, content: string }[]` | | Required. |
| `name` | `string` | `"landing-page"` | The zip's file name and the folder inside it. The page builder passes the page address. |

### projectFor(root, options) [#projectforroot-options]

| Argument | Notes |
|---|---|
| `root` | An element whose `[data-key]` children each hold one section. |
| `options.sections` | The page's sections, in the same order, for their names. |
| `options.title`, `description`, `slug` | Used in `index.html`, the README and the package name. |
| `options.vars` | The design system, from `designVars(design)`. |
| `options.settings` | Written to `page.config.json` as it is. |
| `options.pixel`, `noindex`, `canonical`, `gtm`, `og` | Optional head tags. |

`documentFor(root, options)` is also exported and returns only the `index.html` text.

## Accessibility [#accessibility]

- The files column is an `<aside>` labelled "Project files". Folders are buttons with `aria-expanded`; the open file has `aria-current`.
- The search field is labelled "Search files".
- The code area is focusable (`tabIndex={0}`) and labelled with the file path, so it can be scrolled with the keyboard. It shows a 2px `--color-primary-300` focus outline.
- The line numbers are `aria-hidden`, so a screen reader reads only the code.
- The colouring is decoration. Nothing depends on it.

## Do and don't [#do-and-dont]

- Do read the files from the rendered preview with `projectFor`, so the code always matches the page.
- Do keep the preview mounted while the code shows.
- Do put new page settings into `page.config.json` and, when they change the page's head, into `documentFor`.
- Don't use `PageCode` as a code editor. It only displays files.
- Don't use it for short code samples in the product. It needs a full panel.

## When to use it [#when-to-use-it]

Use it wherever a generated page or project needs to be shown as files. There is no code viewer in `@/ui`. For a short snippet, a `<pre>` with the `.lib-code` styles is enough.

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/PageBuilderPage.jsx` | The Code view of the page builder canvas, behind the Preview and Code switch in the header. `projectFor` runs whenever the view is Code and the page or the design system changes. |

<Callout>

Copy uses `navigator.clipboard?.writeText(…)`. Where the clipboard API is missing, such as a page served over plain HTTP, the call does nothing and no toast appears, not even "Could not copy."

</Callout>


# Composer menu (/work/petavue-design-system/docs/product/composer-menu)

```jsx
import ComposerMenu from "@/pages/harness/ComposerMenu";
```

ComposerMenu is a button that says what it sets and its current value, "Output Auto" or "Format LinkedIn · Square", and opens a list to change it. The button is the product [Button](/work/petavue-design-system/docs/components/button) and the list is the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu), so it looks and behaves like every other menu. It started under the Home composer and is now also the filter menu in the Library and the creative editor's toolbar.

## Usage [#usage]

Pass the label, the current `value`, the `options` and `onChange`. Each option has an `id` and a `label`, and can have a `description` and an `icon`. The icon of the chosen option also shows on the button.


```jsx
const OUTPUTS = [
  { id: "auto", label: "Auto", description: "Chat, dashboards and answers, from your request", icon: Sparkle },
  { id: "landing", label: "Landing page", description: "Built from your published components", icon: Layout },
  { id: "creative", label: "Ad creative", description: "For LinkedIn and Meta, in your design system", icon: ImageSquare },
];

const [output, setOutput] = useState("auto");

<ComposerMenu label="Output" value={output} options={OUTPUTS} onChange={setOutput} />
```

## In the composer tray [#in-the-composer-tray]

Under the white text box, the grey tray holds the options that shape what gets built. They use `variant="ghost"`, so they read as quieter than Output in the box above. Wrap them in `composer-tools composer-tools--wrap` (from `composerMenu.css`): a flex row with a 4px gap that wraps when the options do not fit.


```jsx
<div className="composer-tools composer-tools--wrap px-2.5 py-1.5">
  <ComposerMenu label="Type" value={kindId} options={KIND_OPTIONS} onChange={setKindId} variant="ghost" />
  <ComposerMenu label="Style" value={styleId} options={STYLE_OPTIONS} onChange={setStyleId} variant="ghost" />
  <ComposerMenu label="Format" value={formatId} options={FORMAT_OPTIONS} onChange={setFormatId} variant="ghost" />
</div>
```

The tray changes with Output: Ad creative shows Type, Style and Format, Landing page shows Template, and Auto shows none. For the whole composer, see [Chat composer](/work/petavue-design-system/docs/patterns/chat-composer).

## As a filter [#as-a-filter]

The Library uses it for its Folder, Status and Type filters, with the default `secondaryGhost` variant and the count in each label instead of a description.


```jsx
<ComposerMenu
  label="Status"
  value={filter}
  options={STATUS_FILTERS.map((f) => ({ id: f.id, label: `${f.label} ${count(f.id)}` }))}
  onChange={setFilter}
/>
```

## Alignment [#alignment]

The list opens below the button, 6px away, lined up with its left edge. Use `align="end"` when the button sits at the right of its row, so the list lines up with the right edge and stays on screen.


```jsx
<ComposerMenu label="Output" value={output} options={OUTPUTS} onChange={setOutput} align="end" />
```

## Anatomy [#anatomy]

| Part | Style |
|---|---|
| Button | Button at `size="md"`: 32px tall, 12px text. `secondaryGhost` has a border; `ghost` does not. |
| Button contents | The chosen option's icon (16px), the label, the value in weight 500 (`.composer-menu__value`), then a 14px `CaretDown`. |
| List | The dropdown menu panel: white, `--color-grey-200` border, 8px radius, 6px padding, at least as wide as the button and at most 360px. |
| Option | 14px label, an optional 12px description in `--color-grey-500`, the option's 16px icon on the left. |
| Badge | Optional, after the label: 12px medium text in `--color-grey-500` on `--color-grey-50`, with a `--color-grey-100` border and a 6px radius. |
| Selected | A 16px bold `Check` in `--color-primary-500`, 12px from the text. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `label` | `string` | | What the menu sets. Shown on the button and used as the list's `aria-label`. |
| `value` | `string` | | The `id` of the chosen option. |
| `options` | `Option[]` | | See below. Must have at least one option. |
| `onChange` | `(id) => void` | | Called with the option's `id` on every pick, including the one already chosen. |
| `variant` | Button `variant` | `"secondaryGhost"` | The product uses `secondaryGhost` and `ghost`. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Which edge of the button the list lines up with. |

| Option field | Type | Notes |
|---|---|---|
| `id` | `string` | Compared with `value`. |
| `label` | `string` | Shown in the list and, when chosen, on the button. |
| `description` | `string` | A second line. When present, the icon aligns to the top of the row. |
| `icon` | Phosphor icon component | Shown in the row and, when chosen, on the button. |
| `badge` | `string` | A small grey label after the name. No caller uses it today. |
| `disabled` | `boolean` | The row drops to 50% opacity and cannot be picked. No caller uses it today. |

There is no `disabled` prop for the whole menu and no `className`.

<Callout>

If `value` matches no option, the button shows the first option's label but the list shows no tick. Keep `value` in step with `options`, especially when the options are built from data such as templates or folders.

</Callout>

## Accessibility [#accessibility]

- The menu is Base UI's. The button gets `aria-haspopup` and `aria-expanded`; arrow keys move through the options, typing jumps to a match, Enter picks one, and Escape closes the list and returns focus to the button.
- The button's accessible name is its text, such as "Output Auto", so people hear the current value.
- The chosen option is marked with `aria-current`, not as a checked radio item, so screen readers may not say which option is chosen. If a menu needs that announced, build it with `DropdownMenuRadioGroup` and `DropdownMenuRadioItem` instead.

## When to use it [#when-to-use-it]

| Use | When |
|---|---|
| ComposerMenu | A short choice in a toolbar or under a composer, where the button should show both what it sets and the value. |
| [Dropdown](/work/petavue-design-system/docs/components/dropdown) | A field in a form, with a label above it. |
| [List dropdown](/work/petavue-design-system/docs/components/list-dropdown) | A borderless value in running text or a header. |
| [Model mode menu](/work/petavue-design-system/docs/components/model-mode-menu) | The Sage model choice. Do not rebuild it with ComposerMenu. |
| [Filter dropdown](/work/petavue-design-system/docs/product/filter-dropdown) | The Recommendations page's workflow filter, with counts on the right of each row. |

## Do and don't [#do-and-dont]

- Do keep `label` to one word that names the setting: Output, Format, Template, Status.
- Do put the count in the option label for filters, as the Library does.
- Don't use it for actions. Every option sets a value; for actions, use the [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu) directly.
- Don't use it to navigate. The "Design system" button in the Home tray looks like a ComposerMenu but is a plain ghost Button with `composer-menu__value`, because it opens the Library.

## Where it is used [#where-it-is-used]

| File | Menus |
|---|---|
| `src/pages/harness/HomePage.jsx` | Output in the composer. Type, Style, Format and Template in the tray, with `variant="ghost"`. |
| `src/pages/library/CreativeEditorPage.jsx` | Format, Type and Style in the creative editor's toolbar. |
| `src/pages/library/LibraryPage.jsx` | The Folder, Status and Type filters in the Library toolbars. |

The component is `src/pages/harness/ComposerMenu.jsx`, with its styles in `src/pages/harness/composerMenu.css`.


# Decision modal (/work/petavue-design-system/docs/product/decision-modal)

```jsx
import { DecisionModal } from "@/pages/recommendations/index";
```

DecisionModal is a centred modal for one decision on one recommendation. It says what will happen, asks for a note, and commits with one click. Hold and Reject need a note; the confirm button stays disabled until the note has text. There is no toast afterwards: the recommendation changing state is the confirmation.

## Usage [#usage]

Under an open recommendation, Hold and Reject open the modal. Render it inside `AnimatePresence` from `motion/react`, so the backdrop fades out when it closes.


```jsx
const [modal, setModal] = useState(null);

<Button variant="secondary" size="md" icon={PauseCircle} label="Hold" onClick={() => setModal("on-hold")} />
<Button variant="ghost" size="md" icon={Prohibit} label="Reject" onClick={() => setModal("rejected")} />

<AnimatePresence>
  {(modal === "on-hold" || modal === "rejected") && (
    <DecisionModal
      kind={modal}
      item={item}
      platform={platform}
      onCancel={() => setModal(null)}
      onConfirm={(note) => { setModal(null); onDecide(modal, note); }}
    />
  )}
</AnimatePresence>
```

## The three kinds [#the-three-kinds]

The wording for each kind is in the `MODAL` object above the component.

| `kind` | Title | What it says will happen | Note label | Confirm | Note |
|---|---|---|---|---|---|
| `"on-hold"` | Put this on hold | Nothing is applied. The recommendation stays in your queue as On hold until you decide. | What are you waiting on? (required) | Put on hold | Required |
| `"rejected"` | Reject this recommendation | Nothing is applied. Your reason is saved with this recommendation, and future runs work within it. | Why are you rejecting this? (required) | Reject | Required |
| `"accepted"` | Accept this recommendation | Depends on `item.type`. See below. | Add a note (optional) | Accept | Optional |

For `"accepted"`, the text names the platform: "Petavue applies the change to LinkedIn Ads and confirms the saved settings before reporting it as done." A `test` starts a capped test instead, and a `handoff` creates tasks in HubSpot.


```jsx
<DecisionModal kind="accepted" item={item} platform="LinkedIn Ads" onCancel={close} onConfirm={accept} />
```

<Callout>

Nothing opens the `"accepted"` kind today. Apply on the Recommendations page opens `ApplyModal`, which lists each change and lets people untick or edit them first. The Accept wording is kept in `MODAL` but is not shown in the product.

</Callout>

## Anatomy [#anatomy]

| Part | Style |
|---|---|
| Backdrop | Covers the window (`fixed inset-0`, `z-[80]`) in `rgba(15, 22, 36, 0.28)`. Fades in over 150ms. A click on it cancels. |
| Panel | White, 480px wide (at most 92% of the window), 12px radius, Tailwind `shadow-2xl`. Rises 8px into place over 180ms. |
| Body | 20px padding, 12px between parts. A 16px semibold title, then the consequence in 12px `--text-secondary`. |
| Note | A 12px semibold label in `--text-secondary`, over a three-row text area: 12px text, `--color-grey-200` border, 6px radius, `--color-primary-500` border on focus. |
| Footer | `--color-grey-50`, with a `--color-grey-100` rule above. Cancel (`ghost`) and the confirm button (`primary`), both `md`, on the right. |

The backdrop colour and the shadow are not tokens. The scrim in the [Dialog](/work/petavue-design-system/docs/components/dialog) examples is `rgba(31, 33, 46, 0.45)`.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `kind` | `"on-hold" \| "rejected" \| "accepted"` | | Picks the wording and whether the note is required. Any other value throws. |
| `item` | `object` | | The recommendation. Only `item.type` is read, for the `"accepted"` wording. |
| `platform` | `string` | | The channel name, such as "LinkedIn Ads", for the `"accepted"` wording. Falls back to "the platform". |
| `onCancel` | `() => void` | | Called by Cancel, a click on the backdrop and the Escape key. |
| `onConfirm` | `(note: string \| null) => void` | | Called by the confirm button with the trimmed note, or `null` when it is empty. The modal does not close itself. |

The note is kept inside the modal and starts empty each time it opens.

## Accessibility [#accessibility]

- The panel has `role="dialog"` and its title as `aria-label`. It has no `aria-modal`.
- The note field takes focus when the modal opens, and its label wraps it, so the question is read with the field.
- Escape cancels. The listener is on `window`, so it works wherever focus is.
- Focus is not kept inside the modal: Tab moves on to the page behind it. When the modal closes, focus is not returned to Hold or Reject.
- "(required)" is only in the label text. The field has no `required` or `aria-required`, and nothing says why the confirm button is disabled.

## When to use it [#when-to-use-it]

Use DecisionModal only for decisions on a recommendation. For other confirmations and short forms, use [Dialog](/work/petavue-design-system/docs/components/dialog), wrapped with a backdrop and focus handling as its page shows.

## Do and don't [#do-and-dont]

- Do ask for a note when the decision changes what Petavue does next. Hold and Reject do; the note is what future runs work within.
- Do write the consequence as plain fact: what is applied, what is saved, what happens next.
- Don't add a toast after confirming. Update the recommendation's status instead.
- Don't use it for Apply. Apply needs the list of changes, which is `ApplyModal`.

## Where it is used [#where-it-is-used]

| File | Use |
|---|---|
| `src/pages/recommendations/index.jsx` | In `Detail`, for Hold and Reject on an open recommendation, and for Reject on one that is on hold after "Decide now". |

The function is defined in that file and exported from it for these docs.


# Details dialog (/work/petavue-design-system/docs/product/details-dialog)

```jsx
import { DetailsDialog } from "@/pages/library/parts";
import "@/pages/library/library.css";
```

`DetailsDialog` is the form behind "Edit details, folder and tags" on a workspace card and behind "Save as template" in the page builder. Its fields are not only labels for people: the agent reads the name, description, folder and tags when it decides which component or template to build a page from. The hint under the fields says so.

It is a medium [Dialog](/work/petavue-design-system/docs/components/dialog) (650px) inside the library's scrim, with its own state for each field. It closes on Escape, on a click outside, on the close icon and on Cancel.

## Editing a component [#editing-a-component]

Everything can change. The folder buttons under the fields set the folder in one click, and the one that matches the folder field turns blue.


```jsx
{editing && (
  <DetailsDialog
    title="Component details"
    item={editing}
    folders={folders}
    onClose={() => setEditing(null)}
    onSave={(details) => { updateDetails(editing.uid, details); toast.success("Saved."); }}
  />
)}
```

`onSave` gets `{ name, description, folder, tags }`. Text is trimmed, and tags are split on commas, trimmed, lowercased and de-duplicated by `parseTags` in `src/mocks/library.js`. The dialog then calls `onClose` itself, so `onSave` does not have to close it.

## A template from the library [#a-template-from-the-library]

With `fixed`, the name and description are hidden. A template taken from the library keeps the library's wording, so only its folder and tags are the workspace's to change. `onSave` then gets only `{ folder, tags }`.


```jsx
<DetailsDialog
  title="Template details"
  noun="template"
  item={template}
  folders={folders}
  fixed={!template.saved}
  onClose={close}
  onSave={(details) => updateTemplate(template.id, details)}
/>
```

## Saving a page as a template [#saving-a-page-as-a-template]

The page builder reuses the dialog with its own confirm label and hint, and a name worked out from the page's name.


```jsx
<DetailsDialog
  title="Save as template"
  noun="template"
  confirmLabel="Save template"
  item={{ name: `${page.name.replace(/ page$/i, "")} template`, description: "", folder: "", tags: [] }}
  folders={folders}
  hint="The page is saved as it is now. Describe when to use it: the agent reads the name, description, folder and tags to pick a template."
  onClose={() => setSaving(false)}
  onSave={(details) => library.saveTemplate(details, page.sections)}
/>
```

## States [#states]

| State | What happens |
|---|---|
| Name empty | The Name field shows its error, "Give the component a name." (or "template"), as soon as it is empty. Save does nothing until a name is typed. |
| `fixed` | Name and description are hidden. Save always works. |
| No folders yet | With an empty `folders` list, the "Your folders" row is hidden. |
| Folder picked | The folder button that matches the Folder field, after trimming, gets `.lib-tag--on`. |

<Callout>

The error shows the moment the field is empty, before anyone has tried to save, and the Save button stays enabled and silently does nothing. The Dialog panel has no way to disable Confirm in its default state, which is why the check lives in `onConfirm`.

</Callout>

## Layout [#layout]

| Part | Style |
|---|---|
| Panel | `Dialog` at `md`, 650px, with `.lib-dialog .lib-dialog--form`: body fields stretch to full width with a 16px gap. |
| Name, Description | A `TextInput` and a three-row `TextArea`. Placeholders follow `noun`: "Component name", "When should this component be used?". |
| Folder and Tags | Two `TextInput`s side by side in `.lib-dialog__row`, a two-column grid with a 16px gap. Tags placeholder: "demo, webinar". |
| Your folders | `.lib-card__filing` with a 12px label and one `.lib-tag` button per folder. |
| Hint | `.lib-dialog__hint`, 12px in `--color-grey-500`. |
| Footer | Cancel and Save, both 32px tall. `.lib-dialog .dialog__footer .btn` brings them down from the Dialog's usual 36px at this size. |
| Scrim | `.lib-dialog__scrim`: fixed, `z-index: 80`, 16px padding, `rgba(31, 33, 46, 0.45)`. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `title` | `string` | | The dialog title and its accessible name. |
| `noun` | `string` | `"component"` | Used in placeholders, the error and the default hint. |
| `item` | `{ name?, description?, folder?, tags? }` | | Required. The starting values. Read once, when the dialog mounts. |
| `folders` | `string[]` | `[]` | Folder shortcuts. Hidden when empty. |
| `fixed` | `boolean` | `false` | Hides name and description. |
| `confirmLabel` | `string` | `"Save"` | |
| `hint` | `string` | | Replaces the default line about what the agent reads. |
| `onSave` | `(details) => void` | | Required. Gets `{ name, description, folder, tags }`, or `{ folder, tags }` when `fixed`. |
| `onClose` | `() => void` | | Required. Escape, scrim click, close icon, Cancel and after a save. |

## Accessibility [#accessibility]

- The wrapper has `role="dialog"`, `aria-modal="true"` and `aria-label` set to `title`.
- The Name field has `autoFocus`, so focus lands there when the dialog opens. With `fixed` nothing is focused, and focus stays on the button that opened it, behind the scrim.
- The name error is linked to the field with `aria-describedby` and announced with `role="alert"`.
- Escape closes it through a `keydown` listener on `window`.
- Focus is not kept inside the dialog and is not returned to the trigger on close. See [Dialog](/work/petavue-design-system/docs/components/dialog#accessibility) for the wrapper that does both.

## Do and don't [#do-and-dont]

- Do write the description as when to use the component ("Use when the only goal is a booked demo"). That sentence is what the agent follows.
- Do pass `folders` so people reuse folder names instead of typing near-duplicates.
- Do use `fixed` for anything whose wording belongs to the library.
- Don't use this dialog for page settings or publishing. Those have their own dialogs: [Page settings](/work/petavue-design-system/docs/product/page-settings-dialog) and [Publish](/work/petavue-design-system/docs/product/publish-dialog).

## When to use it [#when-to-use-it]

Use it for any library item the agent chooses from by description. For a plain rename or a single field elsewhere, use a small [Dialog](/work/petavue-design-system/docs/components/dialog) from `@/ui` with one `TextInput`.

## Where it is used [#where-it-is-used]

| File | Title | Notes |
|---|---|---|
| `src/pages/library/LibraryPage.jsx`, `WorkspaceComponents` | "Component details" | Saves through `updateDetails` in `useLibraryStore.js`. |
| `src/pages/library/LibraryPage.jsx`, `Templates` | "Template details" | `fixed` for library templates, editable for templates saved from a page. |
| `src/pages/library/PageBuilderPage.jsx` | "Save as template" | Custom `confirmLabel` and `hint`. Saves through `saveTemplate`. |


# Empty state (/work/petavue-design-system/docs/product/empty-state)

```jsx
import { Empty } from "@/pages/library/LibraryPage";
import "@/pages/library/library.css";
```

`Empty` is the library's empty state: an icon tile for what belongs here, a title that says what is missing, one line on how it gets here, and one action. It fills the space left in its card and centres in it, so an empty tab reads as a finished screen rather than a broken one.

It is the product version of the [empty states pattern](/work/petavue-design-system/docs/patterns/empty-states). The pattern describes the rules; this is the component the Library page renders.

## Nothing created yet [#nothing-created-yet]

The first time someone opens a tab, name what is missing and offer the step that adds the first one.


```jsx
import { Shapes } from "@phosphor-icons/react";

<Empty
  icon={Shapes}
  title="Your workspace has no components yet"
  text="Add components from the library, then publish the ones you want used."
  action={<Button variant="secondary" size="md" label="Browse the library" onClick={() => setScope("library")} />}
/>
```

## Filters found nothing [#filters-found-nothing]

When the list is not empty but the filters hide everything, say so and offer to clear them. Use the `FunnelSimple` icon so it cannot be mistaken for a first-use state.


```jsx
<Empty
  icon={FunnelSimple}
  title="No components match these filters"
  text="Nothing has this status, folder and tag together."
  action={<Button variant="secondary" size="md" label="Clear filters" onClick={clearFilters} />}
/>
```

## Without an icon [#without-an-icon]

`icon` is optional. The editors leave it out when the thing someone opened is gone, because there is no section icon that fits.


```jsx
<Empty
  title="This page no longer exists"
  text="It may have been removed, or the browser was reloaded."
  action={<Button variant="secondary" size="md" label="Back to the library" onClick={() => navigate("/library")} />}
/>
```

## Without an action [#without-an-action]

`action` is optional too. Leave it out only when the next step is somewhere else on the screen, such as the chat beside the page builder's canvas.


```jsx
<Empty
  title="Your page will appear here"
  text="It is built from the components you have published in the Library."
/>
```

## Anatomy [#anatomy]

| Part | Class | Style |
|---|---|---|
| Container | `.lib-empty` | A centred column, at least 360px tall, 48px by 24px padding. It has `flex: 1`, so it fills the rest of a flex column. |
| Icon tile | `.lib-empty__icon` | 48px square, 12px corners, `--color-grey-50` fill, 1px `--color-grey-100` border, 16px below. The icon is drawn at 22px in `--color-grey-400`. |
| Title | `.lib-empty__title` | 16px, 24px line height, medium. It sets no colour of its own and takes the text colour around it. |
| Text | `.lib-empty__text` | 14px, 20px line height, `--color-grey-500` (#757A97), at most 380px wide, 4px below the title. |
| Action | `.lib-empty__action` | 20px above. Whatever node you pass, normally one `secondary` Button at `md`. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `icon` | Phosphor icon component | | Pass the component, not an element. Rendered at 22px. Leave it out for a state with no fitting icon. |
| `title` | `ReactNode` | | What is missing, in one line. |
| `text` | `ReactNode` | | How things get here, in one or two sentences. |
| `action` | `ReactNode` | | Usually one Button. Leave it out when there is nothing to do here. |

There is no `className` or other prop. The component renders `<span>` elements for the title and text, not headings or paragraphs.

## Accessibility [#accessibility]

- The title and text are plain `<span>` elements. A screen reader reads them in order, but the title is not a heading, so it does not appear in a heading list. If the empty state is the only content of a page, the page's own `<h1>` has to carry the context.
- The icon is decorative and has no label, which is right: the title says the same thing.
- The action is a real Button, so it gets keyboard focus and the product focus ring.

## Do and don't [#do-and-dont]

- Do write the title as what is missing ("Your workspace has no components yet"), not as an instruction.
- Do give one action, and make it the step that fills the space: "Browse the library", "Clear filters", "Ask in chat".
- Do use `FunnelSimple` and "Clear filters" for a filtered list, so people know their data is still there.
- Don't put two buttons in `action`. If there are two ways in, pick the one most people need and mention the other in `text`.
- Don't use it inside a small panel or a menu. It is at least 360px tall and meant to fill a tab.

## When to use it [#when-to-use-it]

Use `Empty` inside a Library or editor card that has nothing to list. For a new screen outside the library, follow the [empty states pattern](/work/petavue-design-system/docs/patterns/empty-states) with the same parts. There is no empty state component in `@/ui` yet.

## Where it is used [#where-it-is-used]

| File | State |
|---|---|
| `src/pages/library/LibraryPage.jsx`, `WorkspaceComponents` | "Your workspace has no components yet" and "No components match these filters" |
| `src/pages/library/LibraryPage.jsx`, `Templates` | "Your workspace has no templates yet" and "No templates match these filters" |
| `src/pages/library/LibraryPage.jsx`, `PagesTab` | "No landing pages yet", with "Ask in chat" |
| `src/pages/library/LibraryPage.jsx`, `CreativesTab` | "No ad creatives yet", with "Make an ad creative" |

<Callout>

The page builder, the creative editor and the component editor (`PageBuilderPage.jsx`, `CreativeEditorPage.jsx`, `ComponentEditorPage.jsx`) write the `.lib-empty` classes by hand for their "no longer exists" states, and put `.lib-empty__title` and `.lib-empty__text` inside `.lib-browser__empty` for "Your page will appear here" and "Your creative will appear here". None of them use `Empty`, so a change to the component will not reach them.

</Callout>


# Filter dropdown (/work/petavue-design-system/docs/product/filter-dropdown)

```jsx
import { FilterDropdown } from "@/pages/recommendations/index";
```

FilterDropdown narrows a list to one option, such as one workflow, and shows how many items each option has. The button shows only the chosen option, with no label in front of it, so it fits a narrow header. The list is the product [dropdown menu](/work/petavue-design-system/docs/components/dropdown-menu).

## Usage [#usage]

It sits at the right of the Decision queue header on the Recommendations page. The counts are the open recommendations for each workflow, after the channel filter is applied.


```jsx
<FilterDropdown
  ariaLabel="Filter by workflow"
  size="sm"
  value={scope}
  onChange={pickScope}
  options={chips.map((c) => ({
    value: c.id,
    label: c.id === "all" ? "All workflows" : c.name,
    count: c.count,
  }))}
/>
```

## Sizes [#sizes]

`size` is passed to the [Button](/work/petavue-design-system/docs/components/button). `sm` is the default and the only size the product uses. Both sizes have 12px text, because FilterDropdown overrides the small button's 10px.


```jsx
<FilterDropdown ariaLabel="Filter by workflow" size="sm" align="left" value={scope} onChange={setScope} options={options} />
<FilterDropdown ariaLabel="Filter by workflow" size="md" align="left" value={scope} onChange={setScope} options={options} />
```

## Long names [#long-names]

The button is at most 180px wide and cuts a longer name short with an ellipsis. The list is at least 240px wide and shows the whole name, and both carry it as a `title`, so hovering shows it in the browser's own tooltip. The list scrolls after 320px.


```jsx
<FilterDropdown ariaLabel="Filter by workflow" value="delivery-leaks" onChange={setScope} options={options} align="left" />
```

## Anatomy [#anatomy]

| Part | Style |
|---|---|
| Button | Button `variant="secondary"`: white, `--color-primary-500` border and text. 12px text, `CaretDown` after the label, at most 180px wide. |
| List | The dropdown menu panel, at least 240px wide and at most 320px tall. It lines up with the button's right edge by default. |
| Option | The optional icon, then the name (14px, weight 500 when chosen), then the count in 12px `--text-muted` with tabular figures. |
| Selected | A 16px bold `Check` in `--color-primary-500` after the count. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `value` | `string` | | The `value` of the chosen option. If none matches, the button shows the first option. |
| `options` | `Option[]` | | See below. |
| `onChange` | `(value) => void` | | Called with the option's `value` on every pick, including the one already chosen. |
| `ariaLabel` | `string` | | Becomes the button's `aria-label`. See Accessibility. |
| `size` | `"sm" \| "md"` | `"sm"` | The Button size. |
| `align` | `"right" \| "left"` | `"right"` | Which edge of the button the list lines up with. Any value other than `"right"` lines it up on the left. |

| Option field | Type | Notes |
|---|---|---|
| `value` | `string` | Compared with `value`. |
| `label` | `string` | Shown on the button when chosen, and in the list. |
| `count` | `number` | Optional. Shown on the right of the row, including 0. |
| `icon` | React element | Optional, placed before the name. Pass an element (`<Flask size={16} />`), not a component. No caller uses it today. |

## Accessibility [#accessibility]

- The menu is Base UI's: arrow keys, typing to jump, Enter to pick, and Escape to close and return focus to the button.
- `ariaLabel` replaces the button's text as its accessible name. A screen reader hears "Filter by workflow" and not the chosen workflow, and someone using voice control cannot say the words they see on the button. Until this changes, include the value: `ariaLabel={"Filter by workflow: " + selected.label}`.
- The chosen option is shown only by its weight and the tick. It has no `aria-checked` or `aria-current`.
- The full name of a cut-short option is only in a `title`, which does not show on keyboard focus.

## When to use it [#when-to-use-it]

Use it only where it is used today. For a new filter, use a [Composer menu](/work/petavue-design-system/docs/product/composer-menu) or the filter in [Menus and filters](/work/petavue-design-system/docs/patterns/menus-and-filters): they name what they filter on the button, use the quieter `secondaryGhost` button, and are reached by keyboard and screen reader in the same way.

| | FilterDropdown | Composer menu |
|---|---|---|
| Button | Blue `secondary`, the value only | Grey `secondaryGhost` or `ghost`, label and value |
| Counts | Right-aligned in their own column | Written into the label |
| Second line | No | Optional description |
| Long names | Cut at 180px | Not cut |

## Do and don't [#do-and-dont]

- Do make the first option the unfiltered one, such as "All workflows", and give it the total.
- Do keep counts as the number of items the person still has to act on, so they add up.
- Don't use it for actions or navigation. Every option sets the filter.
- Don't put two FilterDropdowns side by side. Without a label on the button, people cannot tell them apart.

## Where it is used [#where-it-is-used]

| File | Use |
|---|---|
| `src/pages/recommendations/index.jsx` | The workflow filter in the Decision queue header. The choice is kept in the page's `scope` state, which starts from the `?workflow=` URL parameter. |

The function is defined in that file and exported from it for these docs.


# Import brand dialog (/work/petavue-design-system/docs/product/import-brand-dialog)

```jsx
import ImportBrandDialog from "@/pages/library/ImportBrandDialog";
import "@/pages/library/library.css";
```

`ImportBrandDialog` sets up a workspace's design system from its website, so pages and ad creatives match the brand from the first draft. It is one large dialog with three steps: where the site is, the reading of it, and what was found, shown on a sample section before anything changes. Nothing is applied until the last step is confirmed.

<Callout>

The reading is scripted, like the rest of the mock. No request is made to the site. Any address containing "petavue" returns Petavue's own brand; any other address is hashed to one of four sample brands, so the same address always gives the same result.

</Callout>

## The flow [#the-flow]

Type an address such as `meridian.com` and press Enter or "Read my website". The checklist ticks off one line at a time, then the review opens. "Apply to design system" writes the result to the workspace and closes the dialog. Use "Reset design system" to go back to the defaults.


```jsx
{importing && (
  <ImportBrandDialog
    onClose={() => setImporting(false)}
    onApplied={(brand, host) => {
      setImporting(false);
      setTab("design");
      toast.success(`${brand}'s design system imported from ${host}.`);
    }}
  />
)}
```

The dialog reads and writes the design store itself (`useDesignStore` in `src/pages/library/useDesignStore.js`). The caller only opens it and reacts once it is applied.

## Steps [#steps]

| Step | Body | Cancel | Confirm |
|---|---|---|---|
| Form | A lead sentence, Website address, Company name and a note: "Nothing changes until you have seen what was found and applied it." | Cancel: closes | Read my website |
| Reading | The address, then five lines that tick off every 620ms: opening the homepage, colours, fonts, corners and spacing, the logo, header and footer. The review opens 450ms after the last one. | Cancel: closes | Reading…, which does nothing |
| Review | On the left, what was found: five colours with their hex values, the heading and body fonts drawn in themselves, a sample button with its corner radius, and the Library components it was matched to. On the right, a hero and a call-to-action banner drawn in the new brand at 330px tall. | Back: returns to the form | Apply to design system |

### Form [#form]

- **Website address** is required. Once `https://`, `www.` and any path are removed, it must be letters, digits and hyphens in two or more parts separated by dots; `Meridian.com/pricing` reads as `meridian.com`. Otherwise the field shows "Enter an address like yourcompany.com." after the first try.
- **Company name** is optional. Its placeholder, and the name used when it is left empty, is the first part of the host with a capital letter: `meridian.com` gives "Meridian".
- Enter in either field starts the reading.

### What Apply changes [#what-apply-changes]

`setDesign({ brand, colors, headFont, bodyFont, radius })`. The logo and the heading and body sizes are kept. The two fonts are loaded from Google Fonts when the reading starts, so the review can draw them.

## States [#states]

| State | What shows |
|---|---|
| Address not valid | The address field's error, after "Read my website" or Enter. The reading does not start. |
| Reading, current line | Primary text with a spinning `CircleNotch` in `--color-primary-500`. With reduced motion, the spinner stops. |
| Reading, done line | Secondary text with a filled `CheckCircle` in `--color-green`. |
| Reading, waiting line | `--color-grey-300` text with a still `CircleNotch`. |

## Layout [#layout]

| Part | Style |
|---|---|
| Panel | `Dialog` at `lg`, 800px, with `.lib-import`. The body scrolls past `min(64vh, 620px)`. |
| Lead | 14px secondary text on a 21px line. |
| Checklist | 14px lines with a 14px gap and 16px icons, at least 250px tall so the dialog keeps its height. |
| Review | Two columns: 260px for what was found, the rest for the sample, 24px apart. |
| Section labels | 12px uppercase semibold secondary text. |
| Colour rows | A 22px chip with 6px corners, the role in 13px and the hex in 12px monospace `--color-grey-500`. |
| Fonts | The heading font at 22px semibold and the body font at 15px, each with a 12px label in `--color-grey-500`. |
| Sample | `ScaledPreview` at 330px inside a 1px `--color-grey-100` frame with 10px corners. |

The colours, fonts and button in the review are the imported brand's, not Petavue's. That is the point of the step.

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `onClose` | `() => void` | | Escape, scrim click, the close icon, and Cancel in the form and reading steps. |
| `onApplied` | `(brand: string, host: string) => void` | | Called after the design store is updated. It does not close the dialog, so close it here. |

## Accessibility [#accessibility]

- The wrapper has `role="dialog"`, `aria-modal="true"` and `aria-label="Import from your website"`.
- The address field has `autoFocus`, so typing can start at once. Its error is announced with `role="alert"`.
- The reading checklist is a plain list with no live region. A screen reader is not told as lines tick off or when the review opens.
- "Reading…" looks like an enabled primary button but does nothing while the site is read. The Dialog panel has no way to disable it.
- Escape closes the dialog at any step, including the review, and the reading is lost.
- Focus is not kept inside the dialog and is not returned to the button that opened it.

## Do and don't [#do-and-dont]

- Do let people see the result on a real section before anything changes. That is why the review comes before Apply.
- Do tell people after applying where the result went. The Library switches to the Design system tab and says which site it came from.
- Don't apply anything during the reading step.
- Don't use this dialog to edit single values. Colours, fonts and corners are changed one at a time on the Design system tab.

## When to use it [#when-to-use-it]

Use it wherever a workspace has no brand yet, or wants to start again from its website. It is self-contained: render it, and handle `onClose` and `onApplied`. For other multi-step setups, build on a large [Dialog](/work/petavue-design-system/docs/components/dialog) from `@/ui` in the same way: one dialog, the confirm label naming the next step, and Back in place of Cancel after the first step.

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/LibraryPage.jsx`, `LibraryPage` | Opened by "Import from website" in the Library header, and by the same button at the top of the Design system tab (`DesignSystemTab`). On apply, the Library switches to the Design system tab and shows a toast. |


# Library toolbar (/work/petavue-design-system/docs/product/library-toolbar)

```jsx
import { FolderFilter, Toolbar } from "@/pages/library/LibraryPage";
import ComposerMenu from "@/pages/harness/ComposerMenu";
import "@/pages/library/library.css";
```

The toolbar sits above every grid on the Components and Templates tabs of the Library. It says what is shown on the left (the scope switch, "My workspace" or "Library", with a count) and offers filters as menus on the right. It is made of three pieces:

- `Toolbar`, a row with a `lead` slot on the left and its children pushed to the right.
- The scope switch, which is markup the Library page builds and passes as `lead`. It is not a component.
- `FolderFilter`, a Folder menu plus a chip for the tag picked on a card. Other filters, such as Status and Type, are [composer menus](/work/petavue-design-system/docs/product/composer-menu).

## In use [#in-use]

The workspace scope has Folder and Status filters. Switch to Library and it has only Type, because library components have no folder or status yet.


```jsx
const lead = (
  <div className="lib-scope" role="group" aria-label="Show">
    {scopes.map((s) => (
      <button
        key={s.id}
        type="button"
        aria-pressed={scope === s.id}
        className={`lib-scope__option${scope === s.id ? " lib-scope__option--active" : ""}`}
        onClick={() => setScope(s.id)}
      >
        {s.label}
        <span className="lib-scope__count">{s.count}</span>
      </button>
    ))}
  </div>
);

<Toolbar lead={lead}>
  <FolderFilter folders={folders} list={items} folder={folder} onFolder={setFolder} tag={tag} onTag={setTag} />
  <ComposerMenu
    label="Status"
    value={filter}
    options={STATUS_FILTERS.map((f) => ({ id: f.id, label: `${f.label} ${count(f.id)}` }))}
    onChange={setFilter}
  />
</Toolbar>
```

Each menu option carries its count in the label ("Demo campaigns 4", "Draft 1"), and the "All" option counts everything in `list`.

## A tag picked on a card [#a-tag-picked-on-a-card]

Tags are picked by clicking one on a card (see [Filing](/work/petavue-design-system/docs/product/status-tag#filing)). While a tag is active, `FolderFilter` shows it as a blue chip before the Folder menu. Clicking the chip clears it.


```jsx
<FolderFilter folders={folders} list={items} folder={folder} onFolder={setFolder} tag="demo" onTag={setTag} />
```

## Scope only [#scope-only]

When the workspace is empty there is nothing to filter. The tab still renders the toolbar with just the scope switch, so people can move to Library from the same place.


```jsx
<Toolbar lead={lead} />
<Empty icon={Shapes} title="Your workspace has no components yet" … />
```

`FolderFilter` also renders nothing when `folders` is empty and no tag is picked.

## Other uses of the scope switch [#other-uses-of-the-scope-switch]

The same `.lib-scope` classes draw two more segmented controls:

- `.lib-scope--fill` stretches the options to the full width. Page settings uses it for "Public" and "Anyone with the password".
- `.lib-scope--view` puts the switch on a `--color-grey-100` track. The page builder uses it for Preview and Code, with `role="tablist"` and `role="tab"` instead of `aria-pressed`.


```jsx
<div className="lib-scope lib-scope--fill" role="group" aria-label="Restrict access">
  {[["public", "Public"], ["password", "Anyone with the password"]].map(([id, label]) => (
    <button key={id} type="button" aria-pressed={access === id} className={`lib-scope__option${access === id ? " lib-scope__option--active" : ""}`} onClick={() => setAccess(id)}>
      {label}
    </button>
  ))}
</div>
```

## Anatomy [#anatomy]

| Part | Class | Style |
|---|---|---|
| Row | `.lib-sort` | Flex row, items centred, space between, 12px gap. |
| Filters | `.lib-sort__filters` | Flex row with an 8px gap, pushed right with `margin-left: auto`. |
| Scope track | `.lib-scope` | 2px padding, 8px corners, `--color-grey-50` fill. |
| Scope option | `.lib-scope__option` | 12px text in `--color-grey-500`, 5px by 12px padding, 6px corners. Hover turns the text to the primary text colour. |
| Active option | `.lib-scope__option--active` | White fill, 1px `--color-grey-100` border, a 1px shadow, medium weight. |
| Count | `.lib-scope__count` | Tabular figures in the muted text colour (#8E93AF). |
| Tag chip | `.lib-tag.lib-tag--on` | 11px text on `--color-primary-50`, `--color-primary-300` border, `--color-primary-700` text, fully rounded. |
| Folder menu | `ComposerMenu` | A `secondaryGhost` Button at `md` (32px), label then value in medium weight, then a caret. |

## Props [#props]

### Toolbar [#toolbar]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `lead` | `ReactNode` | | Left side. The scope switch on the Library page. |
| `children` | `ReactNode` | | Right side. Filter menus and the tag chip. |

### FolderFilter [#folderfilter]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `folders` | `string[]` | | Folder names in use. The Library page gets them from `foldersOf(items)` in `useLibraryStore.js`. |
| `list` | `{ folder }[]` | | Everything that can be filtered, used for the counts in the menu. |
| `folder` | `string \| null` | | The picked folder. `null` shows "All". |
| `onFolder` | `(folder: string \| null) => void` | | Called with `null` when "All" is picked. |
| `tag` | `string \| null` | | The tag picked on a card. Shown as a chip when set. |
| `onTag` | `(tag: null) => void` | | Called with `null` when the chip is clicked. |

All six are needed. There are no defaults.

## Accessibility [#accessibility]

- The scope options are `<button>` elements with `aria-pressed`, grouped by `role="group"` and `aria-label="Show"`. Screen readers announce each as a toggle button.
- The focus ring on a scope option is a 2px `--color-primary-300` outline inset by 2px.
- The menus are product dropdown menus: arrow keys move through the options, Enter picks one, Escape closes.
- The tag chip reads "Tagged demo ×". The "×" is text, so some screen readers say "times". It has no `aria-label` that says it clears the tag.

## Do and don't [#do-and-dont]

- Do lead with the scope, then filters on the right, as in [menus and filters](/work/petavue-design-system/docs/patterns/menus-and-filters).
- Do put counts in the scope and in the menu options, so people can see what a filter will leave before they pick it.
- Do pair a filtered-out grid with the "No components match these filters" [empty state](/work/petavue-design-system/docs/product/empty-state) and a "Clear filters" action.
- Don't add a third scope option. If more than two lists are needed, they belong in tabs.
- Don't use the scope switch for settings that change data. It only changes what is shown. Page settings is the one exception, through `.lib-scope--fill`.

## When to use it [#when-to-use-it]

Use `Toolbar` and `FolderFilter` for grids of library items. For a two-option switch elsewhere in the product, use [TabToggle](/work/petavue-design-system/docs/components/tab-toggle) from `@/ui`; the `.lib-scope` classes are local to the library.

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/LibraryPage.jsx`, `LibraryPage` | Builds the scope switch with counts and passes it as `lead`. |
| `src/pages/library/LibraryPage.jsx`, `WorkspaceComponents` | `Toolbar` with `FolderFilter` and a Status menu. |
| `src/pages/library/LibraryPage.jsx`, `LibraryComponents` | `Toolbar` with a Type menu. |
| `src/pages/library/LibraryPage.jsx`, `Templates` | `Toolbar` with `FolderFilter` in the workspace scope, and nothing on the right in the library scope. |
| `src/pages/library/PageSettings.jsx` | `.lib-scope--fill` for access control. |
| `src/pages/library/PageBuilderPage.jsx` | `.lib-scope--view` for Preview and Code. |


# Page settings dialog (/work/petavue-design-system/docs/product/page-settings-dialog)

```jsx
import { PageSettingsDialog } from "@/pages/library/PageSettings";
import "@/pages/library/library.css";
```

`PageSettingsDialog` holds the settings that belong to the page itself, whether or not it is live. Where the page is published is the [publish dialog](/work/petavue-design-system/docs/product/publish-dialog)'s job. On a live page, saved settings are held back until the page is published again, like any other change, and the page builder's toast says so.

The dialog is large (800px) and its body scrolls, in six groups: General, Access control, SEO settings, Open Graph settings, Tracking and Forms. The search and share previews update as people type.

## A new draft [#a-new-draft]

Every setting starts from its default, filled in by `metaOf(page)`. The search title falls back to the page name, there is no description yet, and the Open Graph image is a snapshot of the page's first two sections.


```jsx
{settingsOpen && (
  <PageSettingsDialog
    page={page}
    address={live ? pageUrl(page) : `${PETAVUE_DOMAIN}/${page.settings?.slug || slugFor(page.name)}`}
    onClose={() => setSettingsOpen(false)}
    onSave={(name, meta) => {
      setMeta(page.id, name, meta);
      setSettingsOpen(false);
      toast.success(live ? "Settings saved. Publish the page again to put them live." : "Settings saved.");
    }}
  />
)}
```

## A page with settings filled in [#a-page-with-settings-filled-in]

Password access, a meta description, the page hidden from search, its own Open Graph description, a Tag Manager ID, and forms sent to HubSpot and email.


```jsx
const page = {
  name: "Q4 demo request page",
  meta: {
    title: "Book a Meridian demo",
    description: "See how Meridian forecasts your Q4 pipeline from CRM and ad data, and which deals will slip. …",
    sitemap: false,
    access: "password",
    password: "q4-partners",
    ogSameDescription: false,
    ogDescription: "A 30-minute demo of Meridian, with your own pipeline.",
    gtm: "GTM-5K2QX7P",
    forms: "both",
  },
  sections,
};
```

## The groups [#the-groups]

| Group | Fields | Notes |
|---|---|---|
| General | Page name | A `TextInput`. An empty name is saved as the old name. |
| Access control | Public, or Anyone with the password | A full-width `.lib-scope--fill` switch. Password shows a Password field and a note with a lock icon. |
| SEO settings | Search preview, Title tag, Meta description, Sitemap indexing, Page canonical URL | The title tag's placeholder is the page name. The toggle's hint changes with its state. |
| Open Graph settings | Share preview, title and description (each with "Same as SEO …"), image | The title and description fields are disabled while their checkbox is ticked and show the SEO values. |
| Tracking | Petavue tracking pixel, Google Tag Manager ID | The pixel is on by default. |
| Forms | Send form submissions to | A `Dropdown`: HubSpot, email to the workspace owner, or both. |

### Search preview [#search-preview]

`.lib-serp` draws the result as a search engine would: the title in 16px medium `--color-primary-800`, the address in 12px green (#0B7A3B), and the description in 12px secondary text. The title is cut at 60 characters and the description at 155, with " …" added. With no description it says "Add a meta description. Without one, search engines pick text from the page."

### Share preview [#share-preview]

`.lib-og` draws a link card: a 236px image area, the title in 14px medium, the description cut at 200 characters, and the host in `--color-grey-400`. The image area shows the uploaded image, or the page's first two sections through `ScaledPreview` until one is uploaded. An uploaded image is read into a data URL and listed with its name and size in kB, with Replace and Delete.

## What onSave gets [#what-onsave-gets]

`onSave(name, meta)` is called with the page name (trimmed, or the old name when empty) and every setting:

| Key | Default | Cleaned on save |
|---|---|---|
| `title` | the page name | trimmed |
| `description` | `""` | trimmed |
| `sitemap` | `true` | |
| `canonical` | `""` | trimmed, trailing slashes removed |
| `ogSameTitle`, `ogSameDescription` | `true` | |
| `ogTitle`, `ogDescription` | `""` | |
| `ogImage` | `null` | `{ src, name, kb }` once uploaded |
| `access` | `"public"` | |
| `password` | `""` | |
| `pixel` | `true` | |
| `gtm` | `""` | trimmed, uppercased |
| `forms` | `"hubspot"` | |

Nothing is validated. A password page can be saved with an empty password, and any text is accepted as a canonical URL or Tag Manager ID.

## Layout [#layout]

| Part | Style |
|---|---|
| Panel | `Dialog` at `lg`, 800px. The body scrolls past `min(70vh, 720px)`. |
| Group headings | 12px uppercase semibold secondary text, with a 12px hint under some, and a `--color-grey-100` line between groups. |
| Previews | `--color-grey-50` fill, 1px `--color-grey-100` border, 8px corners. |
| Notes | `.lib-publish__note--icon`: 12px text on `--color-grey-50` with a 15px icon. |
| Footer | Close and Save at 32px. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `page` | page object | | Required. Reads `name`, `meta` and `sections` (the first two draw the share image). |
| `address` | `string` | | Required. The address without `https://`, such as `go.meridian.com/q4-demo`. Shown in the search preview; its host is shown in the share preview. |
| `onSave` | `(name, meta) => void` | | Save. Does not close the dialog. |
| `onClose` | `() => void` | | Escape, scrim click, the close icon and Close. |

<Callout>

`address` has no fallback. Leaving it out throws, because the dialog calls `address.split("/")` to find the host.

</Callout>

## Accessibility [#accessibility]

- The wrapper has `role="dialog"`, `aria-modal="true"` and `aria-label="Page settings"`. The visible title is "Q4 demo request page settings".
- The access switch is two `aria-pressed` buttons in a group labelled "Restrict access".
- The search and share previews are `div`s with an `aria-label`, but no role, so most screen readers ignore the label. They repeat what is in the fields.
- The file input for the image is hidden and opened by the Upload button. It has `aria-label="Open Graph image file"`.
- Nothing is focused when the dialog opens. Focus is not kept inside and not returned to "Page settings" on close.

## Do and don't [#do-and-dont]

- Do add new page options here, in the group they belong to, and add a row to the publish dialog's "Goes live with" if people should see it before publishing.
- Do keep the previews next to the fields they reflect, so people see the effect while typing.
- Don't add where the page is published here. That is the publish dialog's decision.
- Don't save a live page's settings straight to the live page. They wait for the next publish.

## When to use it [#when-to-use-it]

Use it for landing pages from the page builder. For settings on other objects, such as a workflow or a dashboard, use a [Dialog](/work/petavue-design-system/docs/components/dialog) from `@/ui` with the same group layout, or a settings page if there are more than a few groups.

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/PageBuilderPage.jsx` | Opened by "Page settings" in the editor header, and by "Change in page settings" in the publish dialog. Saves through `setMeta` in `usePagesStore.js`. |
| `src/pages/library/PageCode.jsx` | Not a caller, but the code view writes these settings into `index.html` and `page.config.json`. See [Code view](/work/petavue-design-system/docs/product/code-view). |


# Publish dialog (/work/petavue-design-system/docs/product/publish-dialog)

```jsx
import { PublishDialog } from "@/pages/library/PageSettings";
import "@/pages/library/library.css";
```

`PublishDialog` is the short dialog behind the page builder's Publish button. It asks only where the page goes: a domain and an address. Confirming it is the approval, and the page goes live straight away. Everything else about the page lives in [Page settings](/work/petavue-design-system/docs/product/page-settings-dialog), and this dialog shows a summary of those settings so nothing is published blind.

The two dialogs are kept apart on purpose. Publishing is a decision people make often and quickly. Page settings change rarely and have many fields.

## A draft page [#a-draft-page]

The first publish. The address starts from the page's name: "Q4 demo request page" becomes `q4-demo-request`, through `slugFor` in `src/mocks/pageBuilder.js`. The full address is shown under the field as it is typed.


```jsx
{publishing && (
  <PublishDialog
    page={page}
    ownDomain="go.meridian.com"
    onClose={() => setPublishing(false)}
    onSettings={() => { setPublishing(false); setSettingsOpen(true); }}
    onUnpublish={() => { unpublish(page.id); setPublishing(false); }}
    onPublish={({ domain, slug }) => { publish(page.id, { domain, slug }); setPublishing(false); }}
  />
)}
```

The address field cleans what is typed as it goes: lowercase letters, digits and single hyphens only, with no hyphen at the start (`cleanSlug`). A trailing hyphen is removed when the page is published.

## A live page with changes [#a-live-page-with-changes]

Once a page is live, later edits are held back until it is published again (`page.unpublished`). The title becomes "Publishing", the confirm label "Publish changes", and a "Take offline" group appears with an Unpublish button.


```jsx
<PublishDialog page={{ ...page, status: "published", unpublished: true }} … />
```

## A live page with no changes [#a-live-page-with-no-changes]

With nothing waiting, the only thing confirming can change is the address, so the confirm label is "Update address". The domain and address start from where the page is live now.


```jsx
<PublishDialog page={{ ...page, status: "published", unpublished: false, settings: { domain: "go.meridian.com", slug: "q4-demo" } }} … />
```

## States [#states]

| Page | Title | Confirm label | Last group |
|---|---|---|---|
| `status: "draft"` | Publish page | Publish page | A note: "The page goes live at this address as soon as you publish." |
| `status: "published"`, `unpublished: true` | Publishing | Publish changes | Take offline, with Unpublish |
| `status: "published"`, `unpublished: false` | Publishing | Update address | Take offline, with Unpublish |

If the address is cleared, the field shows "Give the page an address." and confirming does nothing.

## What "Goes live with" shows [#what-goes-live-with-shows]

The summary reads the page's settings through `metaOf(page)`, which fills in the defaults.

| Row | From | Default |
|---|---|---|
| Search title | `meta.title`, or the page name | The page name |
| Access | `meta.access` | "Anyone on the internet" |
| Search engines | `meta.sitemap` | "Can list this page" |
| Tracking pixel | `meta.pixel` | "On" |

"Change in page settings" calls `onSettings`. The page builder closes this dialog and opens Page settings.

## Layout [#layout]

| Part | Style |
|---|---|
| Panel | `Dialog` at `md`, 650px, with `.lib-dialog--publish`: the body scrolls past `min(64vh, 620px)`. |
| Group | `.lib-publish__group`: a 12px uppercase heading (`.lib-publish__heading`, semibold, 0.05em tracking), 20px padding above and below, a `--color-grey-100` line between groups. |
| Address preview | `.lib-publish__url`: 12px monospace with a 14px `Globe` icon. |
| Summary | `.lib-publish__summary`: a bordered list with 8px corners, 12px text, labels in `--color-grey-500`, values in medium weight. |
| Note | `.lib-publish__note`: 12px text on `--color-grey-50`, 8px corners, 10px by 12px padding. |
| Footer | Cancel and the confirm action at 32px, as in all library dialogs. |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `page` | page object | | Required. Reads `name`, `status`, `unpublished`, `settings` (`{ domain, slug }`) and `meta`. |
| `ownDomain` | `string` | | Required. The workspace's connected domain, offered as the second radio option. The page builder makes it from the brand: `go.meridian.com`. |
| `onPublish` | `({ domain, slug }) => void` | | Called on confirm when the address is not empty. Does not close the dialog. |
| `onUnpublish` | `() => void` | | The Unpublish button on a live page. |
| `onSettings` | `() => void` | | "Change in page settings". |
| `onClose` | `() => void` | | Escape, scrim click, the close icon and Cancel. |

The domain options are `pages.petavue.com` (exported as `PETAVUE_DOMAIN`) and `ownDomain`.

## Accessibility [#accessibility]

- The wrapper has `role="dialog"`, `aria-modal="true"` and `aria-label` "Publish page" or "Publishing", matching the title.
- The domain choice is a `RadioGroup`, a `fieldset` with a "Domain" legend, so arrow keys move between the two domains.
- The address error is announced with `role="alert"` and linked to the field.
- Nothing is focused when the dialog opens, focus is not kept inside, and it is not returned to the Publish button on close.

## Do and don't [#do-and-dont]

- Do keep this dialog to where the page goes. Add new page options to Page settings, and a row to "Goes live with" if people should see it before publishing.
- Do say in the toast where the page went: "Published at go.meridian.com/q4-demo."
- Don't ask for confirmation again after this dialog. Confirming it is the approval.
- Don't hide Unpublish behind a menu. Taking a page offline should be as easy to find as publishing it.

## When to use it [#when-to-use-it]

Use it for landing pages built in the page builder. Publishing a set of changes from a workflow or a recommendation is a different decision; use a [Dialog](/work/petavue-design-system/docs/components/dialog) from `@/ui` that lists the changes, as in [Dialogs and confirmation](/work/petavue-design-system/docs/patterns/dialogs).

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/PageBuilderPage.jsx` | Opened by Publish, Publish changes and Publishing in the editor header. After a publish it shows a toast and, for a page drafted for a recommendation, marks the recommendation accepted. |


# Recommendation card (/work/petavue-design-system/docs/product/recommendation-card)

```jsx
import { RecCard, RecRow } from "@/pages/harness/HomePage";
```

Home shows the first six recommendations that are waiting for a decision, either as a grid of cards or as a list. `RecCard` and `RecRow` are the same recommendation in those two layouts. Both are a single button that opens the recommendation on the Recommendations page, and both show the same four parts:

1. **Type**: what the recommendation makes or changes, with an icon in `--color-primary-500`.
2. **Title and basis**: what it says, and the evidence in one or two lines.
3. **Urgency**: how soon to decide, as coloured text with an icon.
4. **Channel**: the ad platform it acts on, with its [source icon](/work/petavue-design-system/docs/product/source-icon). Left out when the recommendation has no platform.

## Card [#card]


```jsx
<div className="grid grid-cols-3 gap-4 items-stretch">
  {top.map((r) => (
    <RecCard key={r.id} rec={r} onOpen={() => navigate(`/recommendations?rec=${r.id}`)} />
  ))}
</div>
```

Home puts the cards in three columns, 16px apart. The example uses two to fit this page. `items-stretch` keeps cards in a row the same height, and the footer is pushed to the bottom of each one.

| Part | Style |
|---|---|
| Card | White, 16px padding, 12px between parts, 8px radius, `--color-grey-100` border. On hover the border turns `--color-grey-200` and a soft shadow appears. |
| Type | 12px medium, `--text-secondary`, 15px icon in `--color-primary-500`. |
| Title | 14px medium, `--text-primary`, one line. When it is cut short, hovering it shows the whole title. |
| Basis | 12px, `--text-secondary`, at most two lines. |
| Footer | 12px top padding above a `--color-grey-100` rule. Urgency on the left, channel on the right with a 13px icon. |

## List row [#list-row]

The list view is a table: a 36px header row and one 60px row per recommendation, with the same columns in both.


```jsx
const LIST_COLS = "168px minmax(0,1fr) 150px 116px 24px";

<div className="overflow-hidden rounded-lg border border-solid border-[var(--color-grey-100)] bg-white">
  <div
    className="grid items-center gap-4 h-9 px-4 bg-[var(--color-grey-50)] text-[12px] font-medium uppercase tracking-[0.04em] text-[var(--text-muted)]"
    style={{ gridTemplateColumns: LIST_COLS }}
  >
    <span>Type</span><span>Recommendation</span><span>Channel</span><span>When</span><span />
  </div>
  {top.map((r) => (
    <RecRow key={r.id} rec={r} onOpen={() => navigate(`/recommendations?rec=${r.id}`)} />
  ))}
</div>
```

The header row is not part of RecRow, and `LIST_COLS` is not exported from `HomePage.jsx`. If you use RecRow anywhere else, copy the column template exactly, or the header and the rows will not line up.

Each row is at least 60px tall, with 16px side padding and a `--color-grey-100` rule on top. Title and basis are one line each. On hover the row turns `--color-grey-50` and a 13px arrow appears in the last column.

## Urgency [#urgency]

| `rec.urgency` | Label | Icon | Colour |
|---|---|---|---|
| `"act-now"` | Act now | `Lightning` | `#E11D48` |
| `"this-week"` | This week | `Warning` | `#B45309` |
| `"monitor"`, or anything else | This month | `Eye` | `#1D4ED8` |

<Callout>

These three colours are written into `HomePage.jsx` as hex values and are not product tokens. The Recommendations page shows the same urgencies through its own `.rec-card-status` classes and calls `"monitor"` "Next run", and `src/mocks/recommendations.js` calls it "Monitor". One urgency has three names today.

</Callout>

## Type [#type]

The type comes from the recommendation's fields, checked in this order:

| Condition | Type | Icon |
|---|---|---|
| `rec.draftPage` is set | Landing page | `Layout` |
| `rec.draftCreative` is set | Ad creative | `ImageSquare` |
| `rec.workflowId === "paid-media-roi"` | Dashboard | `SquaresFour` |
| `rec.type === "handoff"` | Memo | `Note` |
| Anything else | Campaign change | `SlidersHorizontal` |

These are the icons the prompts under the Home composer use, so a "Landing page" card and the "Demo page for the Q4 campaign" prompt share a mark. The `MAKES` map also has Report (`FileText`), but no recommendation is given that type.


```jsx
<RecCard rec={{ ...rec, draftPage: { name: "Forecast review demo page" } }} onOpen={open} />
<RecCard rec={{ ...rec, draftCreative: { name: "Retargeting ad refresh" } }} onOpen={open} />
```

<Callout>

Every recommendation from the `paid-media-roi` workflow shows as Dashboard, including campaign changes such as `Raise weekly budget on "G_Search_Brand_Core"`, as in the grid above. The workflow builds a dashboard, but the recommendation itself is a campaign change.

</Callout>

## Long text [#long-text]

The title stays on one line and the basis stops at two. The card keeps its height, so a row of cards stays even.


```jsx
<RecCard rec={rec} onOpen={open} />
```

## Channel [#channel]

`rec.platform` is looked up with `platformOf` from `src/mocks/agentWorkflows.js`: `"google-search"` shows Google Ads, `"linkedin"` and `"linkedin-web"` show LinkedIn Ads, and `"meta"` shows Meta Ads. Any other id is shown as written. With no platform, the card leaves the right of the footer empty and the row leaves the Channel column empty.

## Props [#props]

Both components take the same props.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `rec` | `object` | | A recommendation as `/api/recommendations` returns it. Reads `title`, `basis`, `urgency`, `platform`, `type`, `workflowId`, `draftPage` and `draftCreative`. |
| `onOpen` | `() => void` | | Called on click. Home navigates to `/recommendations?rec=<id>`. |

## Accessibility [#accessibility]

- Each card and row is one native `<button type="button">`, so it is reachable with Tab and opens with Enter or Space. Its accessible name is all of its text: type, title, basis, urgency and channel.
- There is no focus style of its own; it relies on the browser's focus ring. The row's arrow appears on hover only, not on keyboard focus.
- The full-title tooltip on a card opens on hover of the title. Keyboard users get the full title from the button's name instead.
- Urgency is shown with a label as well as a colour, so it does not rely on colour alone.

## Do and don't [#do-and-dont]

- Do use these for a short list of recommendations that each open somewhere else. On the Recommendations page itself, the queue uses its own `QueueRow`.
- Do keep the order of parts. People compare cards by scanning the same place on each.
- Don't put buttons inside a card. The whole card is already a button, and a button inside a button is invalid HTML. Decisions are made on the Recommendations page.
- Don't use RecCard as a general card. For other content, use [Card](/work/petavue-design-system/docs/components/card).

## Where it is used [#where-it-is-used]

| File | Use |
|---|---|
| `src/pages/harness/HomePage.jsx` | The Recommendations section under the Home composer: up to six cards in a three-column grid, or the same six as list rows. The choice is saved in `localStorage` under `home-recs-view`. |

Both functions are defined in `HomePage.jsx` and exported from it for these docs. Nothing else imports them.


# Source icon (/work/petavue-design-system/docs/product/source-icon)

```jsx
import SourceIcon from "@/components/SourceIcon";
```

SourceIcon takes the name of a platform or source as it appears in the data, such as "LinkedIn Ads" or "CRM", and draws its mark. A named product gets its own logo from `src/assets/integrations`. A category, such as "CRM" or "Web", gets a neutral Phosphor glyph, because the customer may run a tool we cannot name. Anything it does not recognise gets a plug.

## Logos [#logos]

These names, in any letter case, show a vendor logo. Several spellings point at the same file, so "Google Search", "Google Search Ads" and "Google Ads" all show the Google Ads logo.


```jsx
<SourceIcon name="Google Ads" size={16} />
<SourceIcon name="LinkedIn Ads" size={16} />
<SourceIcon name="HubSpot" size={16} />
```

| Logo | Names that show it |
|---|---|
| Google Ads | `google ads`, `google search`, `google search ads` |
| LinkedIn | `linkedin`, `linkedin ads`, `linkedin + web`, `linkedin campaign manager` |
| Meta Ads | `meta`, `meta ads` |
| HubSpot | `hubspot` |
| Google Analytics | `ga4`, `google analytics` |
| Salesforce, Segment, Snowflake, Marketo, Outreach, Gong | Their names |

## Glyphs [#glyphs]

Categories get a Phosphor icon in `--text-muted` (`#8E93AF`). Every other name falls back to `Plug`.


```jsx
<SourceIcon name="Web" size={16} />        {/* Globe */}
<SourceIcon name="CRM" size={16} />        {/* Database */}
<SourceIcon name="Warehouse" size={16} />  {/* Database */}
<SourceIcon name="Pipeline" size={16} />   {/* Funnel */}
<SourceIcon name="Target account list" size={16} />  {/* ListChecks */}
<SourceIcon name="Webflow" size={16} />    {/* Plug: no mapping */}
```

| Glyph | Names |
|---|---|
| `Globe` | `web`, `website` |
| `Database` | `crm`, `warehouse`, `crm · sdr queue` |
| `Funnel` | `pipeline` |
| `ListChecks` | `target account list` |
| `Plug` | Anything else |

<Callout>

Webflow, ZoomInfo, 6sense, NetSuite, Salesloft, PartnerStack, Splash, Apollo and lemlist have logo files in `src/assets/integrations`, but no name maps to them, so they show the plug. To show a logo, add the name to `LOGO_FILE` in `SourceIcon.jsx`, keyed in lower case, with the file name in lower case.

</Callout>

## Next to its name [#next-to-its-name]

Most of the product prints the channel's name beside the icon. Leave `named` off there, so the name is not repeated on hover. The Home recommendation cards and the Recommendations page use 13px with 12px text.


```jsx
<span className="inline-flex items-center gap-1.5 text-[12px] text-[var(--text-secondary)]">
  <SourceIcon name="LinkedIn Ads" size={13} /> LinkedIn Ads
</span>
```

## On its own [#on-its-own]

When the icon stands alone, such as the channels a workflow reads from, pass `named`. The icon is then wrapped in a [Tooltip](/work/petavue-design-system/docs/components/tooltip) that shows the name, and a logo gets the name as its `alt`.


```jsx
<SourceIcon name="Google Ads" size={14} named />
<SourceIcon name="LinkedIn Ads" size={14} named />
<SourceIcon name="HubSpot" size={14} named />
```

## Sizes [#sizes]

`size` sets the width and height in pixels. The default is 14. The product uses 12 to 18.


```jsx
<SourceIcon name="HubSpot" size={12} />
<SourceIcon name="HubSpot" size={13} />
<SourceIcon name="HubSpot" />
<SourceIcon name="HubSpot" size={16} />
<SourceIcon name="HubSpot" size={18} />
```

| Size | Where |
|---|---|
| 12px | Data source lines on a campaign page |
| 13px | Channel on recommendation cards and rows, channel tabs, chat action destinations |
| 14px | Workflow lists, run review rows, change cards, the campaigns list |
| 15 to 16px | Campaign header, workflow detail sources |
| 18px | Agent detail, the platforms and tools an agent reads |

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `name` | `string` | | The platform or source name. Matched in lower case with spaces trimmed at both ends. |
| `size` | `number` | `14` | Width and height in pixels. |
| `named` | `boolean` | `false` | Adds a tooltip with the name. Use it when no text sits beside the icon. |
| `className` | `string` | | Added to the `<img>` or the glyph's `<svg>`. For spacing only. |

A logo is an `<img>` with `object-contain`, `shrink-0` and `loading="lazy"`. A glyph is the Phosphor icon with `shrink-0` and `text-[var(--text-muted)]`.

## Accessibility [#accessibility]

- Without `named`, a logo has `alt=""` and is skipped by screen readers. That is right only when the name is printed beside it.
- With `named`, the logo's `alt` is the name and the tooltip wrapper has the name as `aria-label`. The wrapper is not focusable, so the tooltip opens on hover only.
- A glyph has no text alternative in either case. Where "CRM" or "Web" stands alone, print the word.

## Do and don't [#do-and-dont]

- Do use SourceIcon for every platform or tool mark. Do not import a logo file directly.
- Do pass the name you would show people, such as "LinkedIn Ads", and let SourceIcon find the file.
- Don't give a category a vendor logo. "CRM" stays a database glyph, because the customer may not use Salesforce or HubSpot.
- Don't recolour a logo with `className`. The glyph colour can follow its context, the logos cannot.

For how logos are drawn and which ones Figma has, see [Logos](/work/petavue-design-system/docs/foundations/logos).

## Where it is used [#where-it-is-used]

| File | What it marks |
|---|---|
| `src/pages/harness/HomePage.jsx` | The channel on recommendation cards and rows (13px). |
| `src/pages/harness/HarnessChat.jsx` | Where an action in the chat is sent (13px). |
| `src/pages/harness/CampaignsPage.jsx` | The channel of each campaign (14px). |
| `src/pages/harness/CampaignDetail.jsx` | The campaign header and its data sources (12 and 15px). |
| `src/pages/recommendations/index.jsx` | The channel tabs, the recommendation's channel and each change card's system (13 and 14px). |
| `src/pages/workflows/index.jsx` | The workflow's platform, and its channels with `named` (14px). |
| `src/pages/workflows/WorkflowDetail.jsx` | What the workflow reads and writes to (16px). |
| `src/pages/workflows/Assessment.jsx` | The sources in an assessment (14px). |
| `src/pages/workflows/agents-run/parts.jsx`, `RunViews.jsx` | The system each change in a run goes to, with `named` (14px). |
| `src/pages/workflows/agents-run/WorkflowConfigPage.jsx` | The sources in a workflow's set-up (14px). |
| `src/pages/agents/AgentDetail.jsx` | The platforms and tools an agent reads (18px). |


# Status dot (/work/petavue-design-system/docs/product/status-dot)

```jsx
import StatusDot from "@/components/StatusDot";
```

StatusDot is a small round indicator for a live chat session. It takes the connection status and two busy flags and picks one of four colours. It has no text of its own.

<Callout>

Nothing in `src/` renders StatusDot today. Before you use it on a new screen, check whether a [Tag](/work/petavue-design-system/docs/components/tag) or a [Spinner](/work/petavue-design-system/docs/components/spinner) with a label says the state more clearly.

</Callout>

## States [#states]


```jsx
<StatusDot connectionStatus="connected" />
<StatusDot connectionStatus="disconnected" />
<StatusDot connectionStatus="connected" isThinking />
<StatusDot connectionStatus="connected" isCompacting />
```

The flags are checked in order, and the first match wins.

| State | When | Colour | Motion |
|---|---|---|---|
| Compacting | `isCompacting` is true | `--status-warning` (`#FBBF24`) | Tailwind `animate-pulse`: fades to 50% and back every 2s |
| Thinking | `isThinking` is true | `--status-warning` (`#FBBF24`) | `animate-thinking`: fades to 40% and back every 1.2s |
| Connected | `connectionStatus === "connected"` | `--status-success` (`#08BD50`) | None |
| Disconnected | Any other `connectionStatus`, including none | `--status-disconnected` (`#ADB2CE`) | None |

The three colours are the app's older status variables, set in `src/index.css`. They are not part of the `--color-*` tokens.

## With a label [#with-a-label]

Compacting and Thinking are the same yellow and differ only in how fast they pulse. Always write the state next to the dot.


```jsx
<span className="inline-flex items-center gap-2">
  <StatusDot connectionStatus="connected" isThinking />
  <span>Q4 pipeline review</span>
  <span className="text-[12px] text-[var(--color-grey-500)]">Sage is working</span>
</span>
```

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `connectionStatus` | `string` | | Only `"connected"` is treated as connected. Every other value shows the grey dot. |
| `isThinking` | `boolean` | | Yellow, with the 1.2s pulse. |
| `isCompacting` | `boolean` | | Yellow, with the 2s pulse. Wins over `isThinking`. |

It always renders an 8px by 8px `<span>` (`w-2 h-2 rounded-full inline-block`). There is no `size`, no `className` and no way to pass `aria-*` props.

## Accessibility [#accessibility]

- The dot is a bare `<span>` with no role and no text, so screen readers skip it. The state has to be in visible text next to it.
- Colour is the only difference between connected and disconnected, so do not rely on the dot alone for that either.
- Both pulses keep running when the person has asked for reduced motion.

## Do and don't [#do-and-dont]

- Do pair the dot with a word: "Connected", "Sage is working", "Reconnecting".
- Do use it only for the state of a live session. For the status of a page, a recommendation or a workflow run, use a [Tag](/work/petavue-design-system/docs/components/tag).
- Don't use it as a decoration or a bullet.

## Where it is used [#where-it-is-used]

Nowhere in `src/` at the moment. The component is `src/components/StatusDot.jsx`.


# Status tag and filing (/work/petavue-design-system/docs/product/status-tag)

```jsx
import { Filing, StatusTag } from "@/pages/library/parts";
import "@/pages/library/library.css"; // for Filing
```

Two small pieces that sit on every workspace card in the Library. `StatusTag` says whether the agent may use a component yet. `Filing` shows where the component is filed, and lets people filter the grid by a tag with one click.

## StatusTag [#statustag]

A component in the workspace is a draft until someone publishes it. Only published components are given to the agent, so this is the one thing a card has to say clearly.


```jsx
<StatusTag status="published" />
<StatusTag status="draft" />
```

| `status` | Renders | Colour |
|---|---|---|
| `"published"` | "Published" | `Tag` in `success-green`: `--color-tag-success-green` (#EBFFF3) fill |
| anything else | "Draft" | `Tag` in `column`: `--color-tag-column` (#EEF0F7) fill |

Both are the small [Tag](/work/petavue-design-system/docs/components/tag): 10px text on a 16px line, 2px by 8px padding, `--radius-md` corners, `--color-text-primary` text.

<Callout>

Any value other than `"published"`, including a typo or `undefined`, shows "Draft". There is no third state. The Pages tab needs one ("Unpublished changes", in `warning-yellow`) and the Creatives tab says "Approved", so both render a `Tag` directly instead of using `StatusTag`.

</Callout>

## Filing [#filing]

`Filing` shows a folder with a `FolderSimple` icon, then the tags. Pass `onTag` and each tag becomes a button that toggles a filter. The active tag turns blue.


```jsx
<Filing folder="Demo campaigns" tags={["demo", "product", "q4"]} activeTag={tag} onTag={setTag} />
```

`onTag` is called with the tag, or with `null` when the active tag is clicked again. The Library page passes the same `tag` state to the [toolbar](/work/petavue-design-system/docs/product/library-toolbar#a-tag-picked-on-a-card), which shows it as a chip.

### Read-only [#read-only]

Without `onTag` the tags are plain text. Either the folder or the tags can be missing. With neither, `Filing` renders nothing.


```jsx
<Filing folder="Shared" tags={["every page"]} />
<Filing folder="Launch" />
<Filing tags={["proof", "q4"]} />
```

## On a card [#on-a-card]

How the workspace card puts them together: the category and `StatusTag` on one line, then the name, the description and `Filing`.


```jsx
<div className="lib-card__body">
  <div className="lib-card__meta">
    <span className="lib-card__category lib-card__category--component"><DiamondsFour size={12} /> Hero</span>
    <StatusTag status={item.status} />
  </div>
  <h3 className="lib-card__name">{item.name}</h3>
  <p className="lib-card__text">{item.description}</p>
  <Filing folder={item.folder} tags={item.tags} activeTag={tag} onTag={setTag} />
</div>
```

## Anatomy of Filing [#anatomy-of-filing]

| Part | Class | Style |
|---|---|---|
| Row | `.lib-card__filing` | Wrapping flex row, 6px gap, at least 22px tall so cards line up whether or not they have tags. |
| Folder | `.lib-folder` | 12px secondary text with a 13px `FolderSimple` icon, 4px gap. |
| Tag | `.lib-tag` | 11px text on an 18px line, 1px by 8px padding, fully rounded, `--color-grey-50` fill, `--color-grey-100` border. Hover darkens the border to `--color-grey-200`. |
| Active tag | `.lib-tag--on` | `--color-primary-50` fill, `--color-primary-300` border, `--color-primary-700` text. |
| Read-only tag | `.lib-tag--static` | The same chip with the default cursor. |

## Props [#props]

### StatusTag [#statustag-1]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `status` | `"draft" \| "published"` | | Anything other than `"published"` shows "Draft". |

### Filing [#filing-1]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `folder` | `string` | | Shown first, with a folder icon. |
| `tags` | `string[]` | `[]` | Lowercase, as `parseTags` in `src/mocks/library.js` stores them. |
| `activeTag` | `string \| null` | | The tag currently filtering the grid. It gets `.lib-tag--on`. |
| `onTag` | `(tag: string \| null) => void` | | Makes the tags buttons. Leave it out for read-only tags. |

## Accessibility [#accessibility]

- `StatusTag` is text, so "Published" and "Draft" are read out. The colour only repeats what the word says.
- Clickable tags are `<button type="button">` elements, reachable with Tab. They do not set `aria-pressed`, so a screen reader cannot tell which tag is active. Only the colour shows it.
- The folder icon has no label. The folder name next to it carries the meaning.

## Do and don't [#do-and-dont]

- Do use `StatusTag` for anything with the library's draft and published lifecycle: workspace components and the component editor header.
- Do pass `onTag` on grids that can be filtered, and leave it out where clicking a tag would lead nowhere.
- Don't use `StatusTag` for page or creative status. It cannot show "Unpublished changes" or "Approved"; render a [Tag](/work/petavue-design-system/docs/components/tag) with the right colour instead.
- Don't write tags in title case. They are stored lowercase and compared exactly.

## When to use it [#when-to-use-it]

Use these inside the library. Everywhere else, use [Tag](/work/petavue-design-system/docs/components/tag) from `@/ui` directly. Note that `src/pages/workbook/list/WorkbookList.jsx` has its own, unrelated `StatusTag` for workbooks.

## Where it is used [#where-it-is-used]

| File | What |
|---|---|
| `src/pages/library/LibraryPage.jsx`, `WorkspaceCard` | `StatusTag` and a clickable `Filing` on each workspace component. |
| `src/pages/library/LibraryPage.jsx`, `TemplateCard` | A clickable `Filing` on workspace templates. Library templates show none. |
| `src/pages/library/ComponentEditorPage.jsx` | `StatusTag` in the editor header, next to the component's name. |


# Workflow glyph (/work/petavue-design-system/docs/product/workflow-glyph)

```jsx
import WorkflowGlyph from "@/components/WorkflowGlyph";
```

WorkflowGlyph draws the same path as the Workflows item in the menu bar, as an inline SVG filled with `currentColor`. Put it next to a workflow's name wherever the product refers to a workflow, so a workflow is marked the same way as the page it lives on.

## Sizes [#sizes]

`size` sets the width and height in pixels. The default is 14. The product uses 13px in a 12px link and 14px in a 12px list row.


```jsx
<WorkflowGlyph size={12} />
<WorkflowGlyph size={13} />
<WorkflowGlyph />
<WorkflowGlyph size={16} />
<WorkflowGlyph size={20} />
```

## In a link [#in-a-link]

The glyph has no colour of its own. Inside a link it takes the link's colour: here `--color-primary-600`, as on the Recommendations page, where the link names the workflow a recommendation came from and opens it.


```jsx
<button type="button" onClick={onOpenWorkflow} className="rec-card-link">
  <WorkflowGlyph size={13} />
  {workflow.name}
</button>
```

## In a row [#in-a-row]

To make it quieter than the text beside it, give it a colour class. The Assessment page lists workflows with a muted glyph (`--text-muted`, `#8E93AF`) before each name.


```jsx
<button type="button" className="flex items-center gap-2.5 …">
  <WorkflowGlyph size={14} className="shrink-0 text-[var(--text-muted)]" />
  <span className="flex-1 min-w-0 text-[12px]">{w.name}</span>
  <span className="text-[12px] text-[#757A97]">{w.pending} waiting</span>
  <CaretRight size={13} />
</button>
```

## Props [#props]

| Prop | Type | Default | Notes |
|---|---|---|---|
| `size` | `number` | `14` | Width and height in pixels. The view box is 256 by 256, the same grid as Phosphor icons. |
| `className` | `string` | | Goes on the `<svg>`. Use it for colour (`text-…`) and `shrink-0`. |

No other props are passed through.

## Accessibility [#accessibility]

- The SVG has `aria-hidden="true"`, so it is always decorative. Put it only next to text that names the workflow.
- When it sits inside a link or button, that element's text is its accessible name. Do not use the glyph on its own as an icon button.

## Do and don't [#do-and-dont]

- Do use it for references to a workflow: a link to it, a row in a list of workflows, a chip that says which workflow made something.
- Do let it inherit colour. Set a colour class only to make it quieter than its text.
- Don't use a Phosphor icon such as `TreeStructure` for workflows. This glyph matches the menu bar.
- Don't use it for agents or recommendations. Agents have their [agent mark](/work/petavue-design-system/docs/product/agent-mark).

## Where it is used [#where-it-is-used]

| File | What it marks |
|---|---|
| `src/pages/recommendations/index.jsx` | The workflow link in a recommendation's header (13px, link blue). |
| `src/pages/workflows/Assessment.jsx` | Each workflow in the list of workflows with recommendations waiting (14px, muted). |

`src/pages/workflows/index.jsx` imports it but does not render it.