xertica-ui 2.8.0 → 2.9.7

package/components/brand/isotype/IsotypeMini.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { cn } from '../../shared/utils';
+import { ISOTYPE_COLORS } from './patterns';
+import {
+  getIsotypeMiniVariant,
+  ISOTYPE_MINI_PATTERNS,
+  type IsotypeMiniPatternId,
+} from './mini-patterns';
+
+export interface IsotypeMiniProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Which registered pattern to render. */
+  pattern?: IsotypeMiniPatternId;
+  /**
+   * Deterministic seed selecting one cell to render as blank. Omit to render
+   * the pure, fully-filled base pattern — the correct choice for canonical
+   * brand-mark placements.
+   */
+  variantSeed?: number;
+  /** Accessible label. Omit for purely decorative use. */
+  'aria-label'?: string;
+}
+
+/**
+ * A 3x3 grid brand mark — the third in the Xertica "isotipos" series, a
+ * compact sibling of the 4x4 `Isotype`. Cells render flush against each
+ * other so the grid reads as a single composed image.
+ *
+ * @ai-rules
+ * 1. Colors are fixed brand hex values (see `patterns.ts`), not theme tokens — never make them theme-reactive.
+ * 2. Never add a `gap-*` utility or per-cell border between cells — it breaks the "single image" look.
+ * 3. Add new patterns via `ISOTYPE_MINI_PATTERNS`/`IsotypeMiniPatternId` in `mini-patterns.ts`; this component never needs to change.
+ * 4. Only pass `variantSeed` for decorative/repeated placements — canonical brand-mark spots should use the pure base pattern.
+ */
+export function IsotypeMini({
+  pattern = 'core',
+  variantSeed,
+  className,
+  'aria-label': ariaLabel,
+  ...props
+}: IsotypeMiniProps) {
+  const cells =
+    variantSeed === undefined
+      ? ISOTYPE_MINI_PATTERNS[pattern]
+      : getIsotypeMiniVariant(pattern, variantSeed);
+
+  return (
+    <div
+      role={ariaLabel ? 'img' : undefined}
+      aria-label={ariaLabel}
+      aria-hidden={ariaLabel ? undefined : true}
+      className={cn(
+        'grid aspect-square grid-cols-3 grid-rows-3',
+        className
+      )}
+      {...props}
+    >
+      {cells.map((cell, index) => (
+        <div
+          key={index}
+          style={{ backgroundColor: cell === 'blank' ? undefined : ISOTYPE_COLORS[cell] }}
+        />
+      ))}
+    </div>
+  );
+}

package/components/brand/isotype/IsotypeTwist.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { cn } from '../../shared/utils';
+import { ISOTYPE_COLORS } from './patterns';
+import { ISOTYPE_TWIST_VARIANTS, type IsotypeTwistVariantId } from './twist-variants';
+
+export interface IsotypeTwistProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Which registered color-pair variant to render. */
+  variant?: IsotypeTwistVariantId;
+  /** Accessible label. Omit for purely decorative use. */
+  'aria-label'?: string;
+}
+
+const VIEW_WIDTH = 800;
+const VIEW_HEIGHT = 694;
+/** CSS blend mode used to combine the two shapes — the intersection color is whatever this mode produces, not a fixed value. */
+const TWIST_BLEND_MODE: React.CSSProperties['mixBlendMode'] = 'multiply';
+
+/** Back shape of the pair — one fixed hand-derived composition, not data-driven. */
+const BACK_SHAPE_PATH =
+  'M218.149 0L344.167 230.665L470.185 0H681.981L467.008 344.092L687.805 693.902H473.892L344.167 458.948L214.443 693.902H0L221.326 344.092L5.82437 0H218.149Z';
+/** Front shape of the pair — overlaps the back shape; dominates the intersection blend. */
+const FRONT_SHAPE_PATH =
+  'M486.064 230.488L570.299 384.535L654.535 230.488H796.107L652.411 460.285L800 693.902H657.012L570.299 536.991L483.586 693.902H340.244L488.187 460.285L344.137 230.488H486.064Z';
+
+/**
+ * Two overlapping angular ribbon shapes — the fifth mark in the Xertica
+ * "isotipos" series. Both shapes render fully opaque; their intersection
+ * blends into a third color via a CSS mix-blend-mode, not transparency.
+ *
+ * @ai-rules
+ * 1. Colors are fixed brand hex values (see `patterns.ts`), not theme tokens — never make them theme-reactive.
+ * 2. The intersection color is a rendering side-effect of `TWIST_BLEND_MODE`, not data — never hardcode a third color per variant.
+ * 3. Add new color pairs via `ISOTYPE_TWIST_VARIANTS` in `twist-variants.ts`; this component never needs to change.
+ * 4. Pair order is `[back, front]` — the front (second) color dominates the intersection blend.
+ * 5. The root `isolate` class scopes the blend to these two shapes — removing it would let the front shape blend against whatever sits behind this component on the page.
+ * 6. The viewBox is not square (800x694) — the root uses `aspect-[800/694]`, not `aspect-square`.
+ */
+export function IsotypeTwist({
+  variant = 'magenta-blue',
+  className,
+  'aria-label': ariaLabel,
+  ...props
+}: IsotypeTwistProps) {
+  const [backKey, frontKey] = ISOTYPE_TWIST_VARIANTS[variant];
+
+  return (
+    <div
+      role={ariaLabel ? 'img' : undefined}
+      aria-label={ariaLabel}
+      aria-hidden={ariaLabel ? undefined : true}
+      className={cn('isolate aspect-[800/694]', className)}
+      {...props}
+    >
+      <svg
+        viewBox={`0 0 ${VIEW_WIDTH} ${VIEW_HEIGHT}`}
+        className="h-full w-full"
+        aria-hidden="true"
+      >
+        <path d={BACK_SHAPE_PATH} fill={ISOTYPE_COLORS[backKey]} />
+        <path
+          d={FRONT_SHAPE_PATH}
+          fill={ISOTYPE_COLORS[frontKey]}
+          style={{ mixBlendMode: TWIST_BLEND_MODE }}
+        />
+      </svg>
+    </div>
+  );
+}

package/components/brand/isotype/frame-variants.ts

@@ -0,0 +1,20 @@
+import type { IsotypeColorKey } from './patterns';
+
+/**
+ * Ordered `[back, front]` color pair for `IsotypeFrames`. The front (second)
+ * color is painted on top and dominates the intersection blend produced by
+ * stroke opacity — the blended color is never hardcoded, only derived.
+ */
+export type IsotypeFramePair = readonly [IsotypeColorKey, IsotypeColorKey];
+
+/** Only these two brand color pairs are in rotation — widen deliberately, not speculatively. */
+export type IsotypeFrameVariantId = 'blue-magenta' | 'blue-yellow';
+
+export const ISOTYPE_FRAME_VARIANTS: Record<IsotypeFrameVariantId, IsotypeFramePair> = {
+  'blue-magenta': ['blue', 'magenta'],
+  'blue-yellow': ['blue', 'yellow'],
+};
+
+export const ISOTYPE_FRAME_VARIANT_IDS = Object.keys(
+  ISOTYPE_FRAME_VARIANTS
+) as IsotypeFrameVariantId[];

package/components/brand/isotype/index.ts

@@ -0,0 +1,9 @@
+export * from './Isotype';
+export * from './patterns';
+export * from './IsotypeFrames';
+export * from './frame-variants';
+export * from './IsotypeMini';
+export * from './mini-patterns';
+export * from './IsotypeDiagonal';
+export * from './IsotypeTwist';
+export * from './twist-variants';

package/components/brand/isotype/isotype-diagonal.mdx

@@ -0,0 +1,52 @@
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/Isotype/Diagonal" />
+
+<Title>Isotype — Diagonal</Title>
+<Subtitle>Third mark in the Xertica isotipos series: a diagonal-cut variation of the core grid.</Subtitle>
+
+---
+
+## Overview
+
+`IsotypeDiagonal` renders a fixed diagonal-cut variation of the "core" grid isotype. Instead of flat rectangular cells, three color-pair boundaries are cut so they form triangular tips — no props change the geometry or colors, it's a single fixed composition.
+
+```tsx
+import { IsotypeDiagonal } from 'xertica-ui/brand';
+
+<IsotypeDiagonal className="w-64" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Additional classes on the root — 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. |
+
+---
+
+## Geometria
+
+The composition fills a `0 0 100 100` viewBox with 8 shapes (4 rects + 4 polygons). Three color-pair boundaries all lie on the same corner-to-corner diagonal of the square:
+
+- The **blue/green** tip, at `(100,0)`–`(75,25)`
+- The **magenta/red** tip, at `(0,100)`–`(25,75)`
+- The **yellow** hypotenuse, at `(75,25)`–`(25,75)`
+
+Every vertex on these three edges satisfies `x + y = 100` — the same line, which is what produces the single continuous diagonal across the mark. Unlike the grid `Isotype`/`IsotypeMini`, this geometry is not data-driven: it's one fixed hand-derived composition, so there is no pattern/variant prop.
+
+`blue` and `red` are not the small triangles they appear to be — they're full-width backing rectangles (`blue` spans the whole top row, `red` the whole bottom row), painted first. `purple` and `green` are painted on top of `blue`; `magenta` and `brown` are painted on top of `red`. What reads as a blue or red triangle is just whatever of that backing rectangle the shapes on top don't cover. This layering exists to close a rendering seam — see AI Best Practices below.
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Colors are fixed brand hex values, not theme tokens** — same rule as the grid `Isotype`: never replace `ISOTYPE_COLORS` with CSS custom properties.
+> - **All 8 shapes are geometrically interdependent** — never move one vertex/rect without re-checking every seam it backs or is backed by.
+> - **This is one fixed composition, not a data-driven pattern** — there is no variant/pattern prop, and none should be added speculatively.
+> - **The blank polygon's `fill="none"` is required, not cosmetic** — an SVG shape with no `fill` renders solid black, unlike a CSS `background-color` left unset.
+> - **`blue`/`red` are oversized backing rectangles that `purple`/`green`/`magenta`/`brown` deliberately overlap, in that paint order** — this closes the hairline anti-aliasing seam browsers otherwise render between two adjacent shapes even when their edges match exactly. The seam is only visible where a shape's edge borders empty space; painting the tip shapes over a same-color rectangle means any imperfect edge coverage reveals more of the matching color instead of the page background. Two earlier techniques were tried and rejected for this: a same-color `stroke` on every shape (fixed the gap but left visible miter-join artifacts where 3–4 shapes meet at one vertex), and a per-shape `transform: scale(...)` from each shape's bounding-box center (broke alignment entirely, since different shapes have different bounding-box centers). Don't reintroduce either — don't shrink `blue`/`red` back to their visible triangle, and don't move `purple`/`green`/`magenta`/`brown` earlier than `blue`/`red` in paint order.

package/components/brand/isotype/isotype-diagonal.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { IsotypeDiagonal } from './IsotypeDiagonal';
+import React from 'react';
+
+const meta: Meta<typeof IsotypeDiagonal> = {
+  title: 'Brand/Isotype/Diagonal',
+  component: IsotypeDiagonal,
+  parameters: {
+    layout: 'centered',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof IsotypeDiagonal>;
+
+export const Base: Story = {
+  args: {
+    className: 'w-64',
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col items-start gap-6 p-6">
+      <IsotypeDiagonal className="w-16" />
+      <IsotypeDiagonal className="w-32" />
+      <IsotypeDiagonal className="w-64" />
+      <IsotypeDiagonal className="w-96" />
+    </div>
+  ),
+};
+
+export const OnDark: Story = {
+  args: {
+    className: 'w-64',
+  },
+  decorators: [
+    Story => (
+      <div className="rounded-xl bg-slate-950 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/components/brand/isotype/isotype-diagonal.test.tsx

@@ -0,0 +1,180 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { IsotypeDiagonal } from './IsotypeDiagonal';
+import { ISOTYPE_COLORS } from './patterns';
+import React from 'react';
+
+type Point = [number, number];
+
+function shapeWithFill(container: HTMLElement, fill: string) {
+  return container.querySelector(`[fill="${fill}"]`)!;
+}
+
+function rectCorners(rect: Element): Point[] {
+  const x = Number(rect.getAttribute('x'));
+  const y = Number(rect.getAttribute('y'));
+  const width = Number(rect.getAttribute('width'));
+  const height = Number(rect.getAttribute('height'));
+  return [
+    [x, y],
+    [x + width, y],
+    [x + width, y + height],
+    [x, y + height],
+  ];
+}
+
+function polygonPoints(polygon: Element): Point[] {
+  return polygon
+    .getAttribute('points')!
+    .trim()
+    .split(/\s+/)
+    .map(pair => pair.split(',').map(Number) as Point);
+}
+
+function shapePoints(shape: Element): Point[] {
+  return shape.tagName === 'rect' ? rectCorners(shape) : polygonPoints(shape);
+}
+
+function shapeEdges(shape: Element): [Point, Point][] {
+  const points = shapePoints(shape);
+  return points.map((point, i) => [point, points[(i + 1) % points.length]]);
+}
+
+/** True if `shape` has an edge between `a` and `b`, in either direction. */
+function hasEdge(shape: Element, a: Point, b: Point): boolean {
+  return shapeEdges(shape).some(
+    ([p, q]) =>
+      (p[0] === a[0] && p[1] === a[1] && q[0] === b[0] && q[1] === b[1]) ||
+      (p[0] === b[0] && p[1] === b[1] && q[0] === a[0] && q[1] === a[1])
+  );
+}
+
+describe('IsotypeDiagonal', () => {
+  it('renders 4 rects (blue, red, purple, brown) and 4 polygons (green, magenta, yellow, blank)', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    expect(container.querySelectorAll('rect')).toHaveLength(4);
+    expect(container.querySelectorAll('polygon')).toHaveLength(4);
+  });
+
+  it('uses every ISOTYPE_COLORS value exactly once as a fill', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    Object.values(ISOTYPE_COLORS).forEach(color => {
+      expect(container.querySelectorAll(`[fill="${color}"]`)).toHaveLength(1);
+    });
+  });
+
+  it('renders exactly one shape with fill="none"', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    expect(container.querySelectorAll('[fill="none"]')).toHaveLength(1);
+  });
+
+  it('renders no shape with a stroke', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    container.querySelectorAll('rect, polygon').forEach(shape => {
+      expect(shape.getAttribute('stroke')).toBeNull();
+    });
+  });
+
+  it('passes className through to the root', () => {
+    const { container } = render(<IsotypeDiagonal className="w-64" />);
+    expect((container.firstChild as HTMLElement).className).toContain('w-64');
+  });
+
+  it('is decorative by default (aria-hidden, no role)', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.getAttribute('aria-hidden')).toBe('true');
+    expect(root.getAttribute('role')).toBeNull();
+  });
+
+  it('renders as an image with a label when aria-label is set', () => {
+    const { container } = render(<IsotypeDiagonal aria-label="Xertica isotype" />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.getAttribute('role')).toBe('img');
+    expect(root.getAttribute('aria-label')).toBe('Xertica isotype');
+    expect(root.getAttribute('aria-hidden')).toBeNull();
+  });
+
+  it('uses a 0 0 100 100 viewBox', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    expect(container.querySelector('svg')!.getAttribute('viewBox')).toBe('0 0 100 100');
+  });
+
+  it('backs blue and red with full-width rectangles, wider than the triangular area they end up showing', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    const blue = shapeWithFill(container, ISOTYPE_COLORS.blue);
+    const red = shapeWithFill(container, ISOTYPE_COLORS.red);
+
+    expect(blue.tagName).toBe('rect');
+    expect(red.tagName).toBe('rect');
+    expect(rectCorners(blue)).toEqual([
+      [0, 0],
+      [100, 0],
+      [100, 25],
+      [0, 25],
+    ]);
+    expect(rectCorners(red)).toEqual([
+      [0, 75],
+      [100, 75],
+      [100, 100],
+      [0, 100],
+    ]);
+  });
+
+  it('paints purple/green after blue, and magenta/brown after red, so they overlap their backing rectangle instead of abutting it', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    const shapes = Array.from(container.querySelectorAll('rect, polygon'));
+    const indexOf = (color: string) => shapes.indexOf(shapeWithFill(container, color));
+
+    expect(indexOf(ISOTYPE_COLORS.blue)).toBeLessThan(indexOf(ISOTYPE_COLORS.purple));
+    expect(indexOf(ISOTYPE_COLORS.blue)).toBeLessThan(indexOf(ISOTYPE_COLORS.green));
+    expect(indexOf(ISOTYPE_COLORS.red)).toBeLessThan(indexOf(ISOTYPE_COLORS.magenta));
+    expect(indexOf(ISOTYPE_COLORS.red)).toBeLessThan(indexOf(ISOTYPE_COLORS.brown));
+  });
+
+  it('keeps purple and brown fully within the blue/red rectangles they sit on top of', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    const purple = shapeWithFill(container, ISOTYPE_COLORS.purple);
+    const brown = shapeWithFill(container, ISOTYPE_COLORS.brown);
+
+    expect(Number(purple.getAttribute('y'))).toBeGreaterThanOrEqual(0);
+    expect(Number(purple.getAttribute('y')) + Number(purple.getAttribute('height'))).toBeLessThanOrEqual(25);
+
+    expect(Number(brown.getAttribute('y'))).toBeGreaterThanOrEqual(75);
+    expect(Number(brown.getAttribute('y')) + Number(brown.getAttribute('height'))).toBeLessThanOrEqual(100);
+  });
+
+  it('keeps the untouched seams — purple/magenta, magenta/blank, yellow/green, and brown/green — matching exactly', () => {
+    const { container } = render(<IsotypeDiagonal />);
+    const purple = shapeWithFill(container, ISOTYPE_COLORS.purple);
+    const magenta = shapeWithFill(container, ISOTYPE_COLORS.magenta);
+    const blank = shapeWithFill(container, 'none');
+    const yellow = shapeWithFill(container, ISOTYPE_COLORS.yellow);
+    const green = shapeWithFill(container, ISOTYPE_COLORS.green);
+    const brown = shapeWithFill(container, ISOTYPE_COLORS.brown);
+
+    expect(hasEdge(purple, [0, 25], [25, 25])).toBe(true);
+    expect(hasEdge(magenta, [0, 25], [25, 25])).toBe(true);
+
+    expect(hasEdge(magenta, [25, 25], [25, 75])).toBe(true);
+    expect(hasEdge(blank, [25, 25], [25, 75])).toBe(true);
+
+    expect(hasEdge(yellow, [75, 25], [75, 75])).toBe(true);
+    expect(hasEdge(green, [75, 25], [75, 75])).toBe(true);
+
+    expect(hasEdge(brown, [75, 75], [100, 75])).toBe(true);
+    expect(hasEdge(green, [75, 75], [100, 75])).toBe(true);
+  });
+
+  it('traces a single continuous diagonal through the blue/green tip, the magenta/red tip, and the yellow hypotenuse', () => {
+    const diagonalVertices: Point[] = [
+      [100, 0],
+      [0, 100],
+      [75, 25],
+      [25, 75],
+    ];
+    diagonalVertices.forEach(([x, y]) => {
+      expect(x + y).toBe(100);
+    });
+  });
+});

package/components/brand/isotype/isotype-frames.mdx

@@ -0,0 +1,50 @@
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/Isotype/Frames" />
+
+<Title>Isotype — Frames</Title>
+<Subtitle>Second mark in the Xertica isotipos series: two overlapping hollow squares.</Subtitle>
+
+---
+
+## Overview
+
+`IsotypeFrames` renders two overlapping hollow square frames in fixed brand colors. Their intersection blends into a third color purely from SVG stroke opacity — no third color is ever hardcoded, it's a rendering side-effect.
+
+```tsx
+import { IsotypeFrames } from 'xertica-ui/brand';
+
+<IsotypeFrames variant="blue-magenta" className="w-64" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `IsotypeFrameVariantId` | `'blue-magenta'` | Which registered color pair to render. |
+| `className` | `string` | — | Additional classes on the root — 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. |
+
+---
+
+## Variants
+
+The registry (`ISOTYPE_FRAME_VARIANTS` in `frame-variants.ts`) holds ordered `[back, front]` color pairs — the front (second) color is painted on top and dominates the intersection blend. Add a new color combination by adding an entry there and widening `IsotypeFrameVariantId`; `IsotypeFrames.tsx` itself never needs to change.
+
+```tsx
+import { ISOTYPE_FRAME_VARIANT_IDS, IsotypeFrames } from 'xertica-ui/brand';
+
+ISOTYPE_FRAME_VARIANT_IDS.map(variant => <IsotypeFrames key={variant} variant={variant} />);
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Colors are fixed brand hex values, not theme tokens** — same rule as the grid `Isotype`: never replace `ISOTYPE_COLORS` with CSS custom properties.
+> - **The intersection color is derived, not data** — it comes from stroke opacity compositing; never hardcode a third color per variant.
+> - **New color pairs are data, not components** — add variants via `ISOTYPE_FRAME_VARIANTS`/`IsotypeFrameVariantId` in `frame-variants.ts`.
+> - **Pair order controls the blend** — `[back, front]`, the front color dominates the intersection.

package/components/brand/isotype/isotype-frames.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { IsotypeFrames } from './IsotypeFrames';
+import { ISOTYPE_FRAME_VARIANT_IDS } from './frame-variants';
+import React from 'react';
+
+const meta: Meta<typeof IsotypeFrames> = {
+  title: 'Brand/Isotype/Frames',
+  component: IsotypeFrames,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ISOTYPE_FRAME_VARIANT_IDS,
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof IsotypeFrames>;
+
+export const Base: Story = {
+  args: {
+    variant: 'blue-magenta',
+    className: 'w-64',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-8 p-6">
+      {ISOTYPE_FRAME_VARIANT_IDS.map(variant => (
+        <IsotypeFrames key={variant} variant={variant} className="w-40" />
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col items-start gap-6 p-6">
+      <IsotypeFrames className="w-16" />
+      <IsotypeFrames className="w-32" />
+      <IsotypeFrames className="w-64" />
+      <IsotypeFrames className="w-96" />
+    </div>
+  ),
+};
+
+export const OnDark: Story = {
+  args: {
+    variant: 'blue-magenta',
+    className: 'w-64',
+  },
+  decorators: [
+    Story => (
+      <div className="rounded-xl bg-slate-950 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/components/brand/isotype/isotype-frames.test.tsx

@@ -0,0 +1,92 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { IsotypeFrames } from './IsotypeFrames';
+import { ISOTYPE_FRAME_VARIANTS, ISOTYPE_FRAME_VARIANT_IDS } from './frame-variants';
+import { ISOTYPE_COLORS } from './patterns';
+import React from 'react';
+
+describe('IsotypeFrames', () => {
+  it('renders two overlapping rects', () => {
+    const { container } = render(<IsotypeFrames />);
+    expect(container.querySelectorAll('rect')).toHaveLength(2);
+  });
+
+  it('defaults to the blue-magenta variant', () => {
+    const { container } = render(<IsotypeFrames />);
+    const rects = container.querySelectorAll('rect');
+    const [backKey, frontKey] = ISOTYPE_FRAME_VARIANTS['blue-magenta'];
+    expect(rects[0].getAttribute('stroke')).toBe(ISOTYPE_COLORS[backKey]);
+    expect(rects[1].getAttribute('stroke')).toBe(ISOTYPE_COLORS[frontKey]);
+  });
+
+  it('renders every registered variant with the right stroke colors', () => {
+    for (const variant of ISOTYPE_FRAME_VARIANT_IDS) {
+      const { container } = render(<IsotypeFrames variant={variant} />);
+      const rects = container.querySelectorAll('rect');
+      const [backKey, frontKey] = ISOTYPE_FRAME_VARIANTS[variant];
+      expect(rects[0].getAttribute('stroke')).toBe(ISOTYPE_COLORS[backKey]);
+      expect(rects[1].getAttribute('stroke')).toBe(ISOTYPE_COLORS[frontKey]);
+    }
+  });
+
+  it('renders each rect hollow (fill="none")', () => {
+    const { container } = render(<IsotypeFrames />);
+    container.querySelectorAll('rect').forEach(rect => {
+      expect(rect.getAttribute('fill')).toBe('none');
+    });
+  });
+
+  it('passes className through to the root', () => {
+    const { container } = render(<IsotypeFrames className="w-64" />);
+    expect((container.firstChild as HTMLElement).className).toContain('w-64');
+  });
+
+  it('offsets the front frame diagonally from the back frame by a sixth of the shared size', () => {
+    const { container } = render(<IsotypeFrames />);
+    const [back, front] = Array.from(container.querySelectorAll('rect'));
+
+    const backX = Number(back.getAttribute('x'));
+    const backY = Number(back.getAttribute('y'));
+    const backSize = Number(back.getAttribute('width'));
+    const frontX = Number(front.getAttribute('x'));
+    const frontY = Number(front.getAttribute('y'));
+    const frontSize = Number(front.getAttribute('width'));
+
+    expect(backSize).toBe(frontSize);
+    expect(frontX - backX).toBeCloseTo(backSize / 6);
+    expect(frontY - backY).toBeCloseTo(backSize / 6);
+  });
+
+  it('renders both frames fully opaque and blends their intersection via mix-blend-mode on the front frame', () => {
+    const { container } = render(<IsotypeFrames />);
+    const [back, front] = Array.from(container.querySelectorAll('rect'));
+
+    expect(back.getAttribute('opacity')).toBeNull();
+    expect(front.getAttribute('opacity')).toBeNull();
+    expect(front.style.mixBlendMode).toBeTruthy();
+    expect(front.style.mixBlendMode).not.toBe('normal');
+  });
+
+  it('isolates the blend mode to the two frames via the root isolate class', () => {
+    const { container } = render(<IsotypeFrames />);
+    expect((container.firstChild as HTMLElement).className).toContain('isolate');
+  });
+
+  it('expands the viewBox so no edge of the stroked frames is clipped', () => {
+    const { container } = render(<IsotypeFrames />);
+    const svg = container.querySelector('svg')!;
+    const [minX, minY, width, height] = svg.getAttribute('viewBox')!.split(' ').map(Number);
+
+    container.querySelectorAll('rect').forEach(rect => {
+      const x = Number(rect.getAttribute('x'));
+      const y = Number(rect.getAttribute('y'));
+      const size = Number(rect.getAttribute('width'));
+      const half = Number(rect.getAttribute('stroke-width')) / 2;
+
+      expect(x - half).toBeGreaterThanOrEqual(minX);
+      expect(y - half).toBeGreaterThanOrEqual(minY);
+      expect(x + size + half).toBeLessThanOrEqual(minX + width);
+      expect(y + size + half).toBeLessThanOrEqual(minY + height);
+    });
+  });
+});