# Leo generation pattern

How any surface looks and behaves while **Leo (AI) is creating data or components**. One lifecycle, one Stop, one parent/child model. Tables, cards, charts, forms, and sections consume it; none define their own loading state for Leo work.

**See it live:** `/design-os/design-system/leo-generation` (Lifecycle and Stop · Parent and child · Split rows · Row types · Parts without a section). Row examples also on `/design-os/design-system/data-table` → **Row types**.

## Lifecycle

```
inited ──▶ thinking ──▶ completed ──▶ (placeholder leaves, data appears)
              └──── Stop (until completed) ──▶ discarded
```

| State | Look |
| --- | --- |
| `inited` | Leo was asked. Mark plays its one-shot **invited** gesture. No skeleton yet. |
| `thinking` | Brand blob + dot backdrop, shimmering label, pulsing skeleton, working mark. |
| `completed` | A brand **check** with "Leo is done". Held ~0.9s, then the placeholder is removed and the real data renders. |

State is **owned by the consumer** (stream / mutation). `useLeoGeneration` is the default owner for one run; `useLeoGenerationGroup` for a parent with children.

## Parts

| Part | Use |
| --- | --- |
| `useLeoGeneration` | One run: `state`, `delivered`, `stopped`, `run`, `stop`, `set`. |
| `useLeoGenerationGroup(ids)` | Parent over child ids; derives parent state; `stop`, `stopChild`. |
| `LeoGenerationSurface` | Wrap **any** component. Status bar, backdrop, skeleton, Stop. |
| `LeoGenerationSection` | **Parent** section whose header shows Leo working while its children stay visible. `useLeoGenerationScope()` for children. |
| `LeoGenerationStatus` / `LeoStopButton` | Status line and icon-only Stop (`Button` ghost `icon-xs`, name "Stop"). |
| `LeoBrandBackdrop` | Single-brand drifting blobs + dots. Decorative. |
| `DataTable leoLoading` / `LeoLoadingRow` | The table consumer. `{ rows: [{ id, state, label, onStop, splitCount }] }`. |

Sources: `packages/ui/src/lib/leo-generation.ts`, `components/ui/leo-generation-surface.tsx`, `components/ui/leo-brand-backdrop.tsx`, `components/data-table/leo-loading-row.tsx`.

## Parent and child

A **section** (parent) holds a **table** (child). Rows inside the table are never parent or child of each other: no parent row, no indentation, no connector arrows. Asking Leo to add data: the section header shows Leo working with Stop for the whole run; the table adds rows one at a time, each with its own Stop and its own state. Parent state is derived: any child thinking → thinking; else any waiting/inited → inited; else completed. Stop on the parent stops every undelivered child; Stop on a child leaves siblings running.

## Split rows

A row type where one column stacks grouped sub-rows inside the same row (`ColumnDef.split`). The Leo loading row takes the same shape (`splitCount`). Rules: `.cursor/rules/exxat-split-rows.mdc`.

## Rules

`.cursor/rules/exxat-leo-generation.mdc` · `.cursor/rules/exxat-split-rows.mdc` · `exxat-leo-icon-motion` · `exxat-accessibility`.

## Catalog registration (new consumers)

A new Leo consumer needs: an example on `/design-os/design-system/leo-generation` in all three states; a **Row types** entry if it is a table row; the `ui-leo-generation` catalog entry already lists the group (`lib/mock/catalog-entries.ts`, `lib/catalog-list-structure.ts`, `registry-entries.ts` with `catalogId`).
