import { Meta, Title, Subtitle, Description } from '@storybook/addon-docs/blocks';

<Meta title="Brand/Isotype" />

<Title>Isotype</Title>
<Subtitle>First mark in a growing series of modular 4x4 Xertica isotypes.</Subtitle>

---

## Overview

`Isotype` renders a 4x4 grid of fixed brand colors that reads as a single composed image — a reusable visual mark for use standalone or alongside other Design System elements. It's built as one generic renderer over a pattern registry, so new isotypes join the series as pure data, not new components.

```tsx
import { Isotype } from 'xertica-ui/brand';

<Isotype className="w-64" />
```

---

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `pattern` | `IsotypePatternId` | `'core'` | Which registered pattern to render. |
| `variantSeed` | `number` | — | Deterministically blanks one extra cell (beyond the pattern's own blank cell) for decorative variation. Omit for the pure base pattern. |
| `className` | `string` | — | Additional classes on the root grid container — use for sizing (`w-64`, `max-w-md`, etc). `aspect-square` is built in. |
| `aria-label` | `string` | — | Omit for decorative use (root gets `aria-hidden`); set it to render as `role="img"` instead. |

---

## Patterns

Today the registry (`ISOTYPE_PATTERNS` in `patterns.ts`) has one entry, `'core'`. Add new isotypes to the series by adding a new entry there and widening `IsotypePatternId` — `Isotype.tsx` itself never needs to change.

## Variants

Passing `variantSeed` calls the pure, deterministic `getIsotypeVariant(pattern, seed)` internally — the same `(pattern, seed)` pair always blanks the same extra cell, so it's safe across server/client renders. Use it for decorative, repeated placements (e.g. a gallery of instances); canonical brand-mark spots should use the plain base pattern with no seed.

```tsx
// Canonical brand-mark placement — pure base pattern
<Isotype />

// Decorative variation
<Isotype variantSeed={3} />

// Precomputing a batch of variants (e.g. a thumbnail sheet)
import { getIsotypeVariant } from 'xertica-ui/brand';
const variants = Array.from({ length: 8 }, (_, seed) => getIsotypeVariant('core', seed));
```

---

## AI Best Practices

> [!IMPORTANT]
> - **Colors are fixed brand hex values, not theme tokens** — the isotype is a brand identity mark and must not reskin when the active color theme changes. Never replace `ISOTYPE_COLORS` with CSS custom properties.
> - **No gaps or per-cell borders** — cells must render flush against each other so the grid reads as a single composed image.
> - **New isotypes are data, not components** — add patterns via `ISOTYPE_PATTERNS`/`IsotypePatternId` in `patterns.ts`.
> - **`variantSeed` is for decorative use only** — canonical placements (Hero, nav, etc.) should render the base pattern.