@ryanyahya/opendoc 0.4.0

package/starter/documents/welcome-presentation/media/studio-rhythm/data.json

@@ -0,0 +1,234 @@
+{
+  "basis": "Synthetic data for a design demonstration; not observed work or product performance.",
+  "units": {
+    "pages": "pages",
+    "research": "hours",
+    "drafting": "hours",
+    "design": "hours",
+    "review": "hours"
+  },
+  "stages": [
+    "research",
+    "drafting",
+    "design",
+    "review"
+  ],
+  "documents": [
+    {
+      "id": "document-01-1",
+      "week": 1,
+      "pages": 7,
+      "research": 7,
+      "drafting": 11,
+      "design": 4,
+      "review": 5
+    },
+    {
+      "id": "document-01-2",
+      "week": 1,
+      "pages": 14,
+      "research": 10,
+      "drafting": 16,
+      "design": 8,
+      "review": 7
+    },
+    {
+      "id": "document-02-1",
+      "week": 2,
+      "pages": 10,
+      "research": 9,
+      "drafting": 14,
+      "design": 5,
+      "review": 7
+    },
+    {
+      "id": "document-02-2",
+      "week": 2,
+      "pages": 17,
+      "research": 12,
+      "drafting": 19,
+      "design": 9,
+      "review": 9
+    },
+    {
+      "id": "document-03-1",
+      "week": 3,
+      "pages": 13,
+      "research": 11,
+      "drafting": 17,
+      "design": 6,
+      "review": 9
+    },
+    {
+      "id": "document-03-2",
+      "week": 3,
+      "pages": 20,
+      "research": 14,
+      "drafting": 22,
+      "design": 10,
+      "review": 11
+    },
+    {
+      "id": "document-04-1",
+      "week": 4,
+      "pages": 16,
+      "research": 13,
+      "drafting": 20,
+      "design": 7,
+      "review": 11
+    },
+    {
+      "id": "document-04-2",
+      "week": 4,
+      "pages": 6,
+      "research": 5,
+      "drafting": 10,
+      "design": 11,
+      "review": 3
+    },
+    {
+      "id": "document-05-1",
+      "week": 5,
+      "pages": 19,
+      "research": 15,
+      "drafting": 8,
+      "design": 8,
+      "review": 3
+    },
+    {
+      "id": "document-05-2",
+      "week": 5,
+      "pages": 9,
+      "research": 7,
+      "drafting": 13,
+      "design": 3,
+      "review": 5
+    },
+    {
+      "id": "document-06-1",
+      "week": 6,
+      "pages": 5,
+      "research": 6,
+      "drafting": 11,
+      "design": 9,
+      "review": 5
+    },
+    {
+      "id": "document-06-2",
+      "week": 6,
+      "pages": 12,
+      "research": 9,
+      "drafting": 16,
+      "design": 4,
+      "review": 7
+    },
+    {
+      "id": "document-07-1",
+      "week": 7,
+      "pages": 8,
+      "research": 8,
+      "drafting": 14,
+      "design": 10,
+      "review": 7
+    },
+    {
+      "id": "document-07-2",
+      "week": 7,
+      "pages": 15,
+      "research": 11,
+      "drafting": 19,
+      "design": 5,
+      "review": 9
+    },
+    {
+      "id": "document-08-1",
+      "week": 8,
+      "pages": 11,
+      "research": 10,
+      "drafting": 17,
+      "design": 11,
+      "review": 9
+    },
+    {
+      "id": "document-08-2",
+      "week": 8,
+      "pages": 18,
+      "research": 13,
+      "drafting": 22,
+      "design": 6,
+      "review": 11
+    },
+    {
+      "id": "document-09-1",
+      "week": 9,
+      "pages": 14,
+      "research": 12,
+      "drafting": 20,
+      "design": 3,
+      "review": 11
+    },
+    {
+      "id": "document-09-2",
+      "week": 9,
+      "pages": 4,
+      "research": 15,
+      "drafting": 10,
+      "design": 7,
+      "review": 3
+    },
+    {
+      "id": "document-10-1",
+      "week": 10,
+      "pages": 17,
+      "research": 14,
+      "drafting": 8,
+      "design": 4,
+      "review": 3
+    },
+    {
+      "id": "document-10-2",
+      "week": 10,
+      "pages": 7,
+      "research": 6,
+      "drafting": 13,
+      "design": 8,
+      "review": 5
+    },
+    {
+      "id": "document-11-1",
+      "week": 11,
+      "pages": 20,
+      "research": 5,
+      "drafting": 11,
+      "design": 5,
+      "review": 5
+    },
+    {
+      "id": "document-11-2",
+      "week": 11,
+      "pages": 10,
+      "research": 8,
+      "drafting": 16,
+      "design": 9,
+      "review": 7
+    },
+    {
+      "id": "document-12-1",
+      "week": 12,
+      "pages": 6,
+      "research": 7,
+      "drafting": 14,
+      "design": 6,
+      "review": 7
+    },
+    {
+      "id": "document-12-2",
+      "week": 12,
+      "pages": 13,
+      "research": 10,
+      "drafting": 19,
+      "design": 10,
+      "review": 9
+    }
+  ]
+}

package/starter/documents/welcome-presentation/media/studio-rhythm/generation.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "imageHash": "d8c368888bade3f7324c803f41d6b8f0ef42d3a25d42462f78a3f9d3a2bca522",
+  "inputs": {
+    "media/studio-rhythm/data.json": "f307dc1c2cf822755899b4dc2393e55d66188150dd06d9fedd1f99c8b0a40c97",
+    "media/studio-rhythm/recipe.py": "3cd480d879eeffdac2a459b4326431d72d62755999d5f3dfd23cc0ec287d75d1"
+  },
+  "recordedAt": "2026-09-11T13:32:10.127Z"
+}

package/starter/documents/welcome-presentation/media/studio-rhythm/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "The shape of a working season",
+  "description": "Weekly hours by workstream across twelve weeks and twenty-four fictional documents. One stacked area chart, adapted for a presentation from the welcome guide’s synthetic dataset.",
+  "file": "image.png",
+  "kind": "chart",
+  "alt": "A single stacked area chart shows hours per week for research, drafting, design, and review across twelve weeks. Total effort peaks at 100 hours in week three.",
+  "sources": [
+    "Original synthetic demonstration dataset authored for the OpenDoc welcome document, 11 September 2026. No project activity or product performance was measured."
+  ],
+  "data": "data.json",
+  "recipe": "recipe.py",
+  "attribution": "Illustrative data only. This is not an OpenDoc productivity benchmark."
+}

package/starter/documents/welcome-presentation/media/studio-rhythm/recipe.py

@@ -0,0 +1,49 @@
+"""Render one slide-sized chart from the welcome guide's synthetic dataset.
+Run: uv run --with matplotlib python documents/welcome-presentation/media/studio-rhythm/recipe.py
+The prepared data remain unchanged. No actual activity is represented.
+"""
+from pathlib import Path
+import json
+import numpy as np
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from matplotlib.font_manager import FontProperties, fontManager
+from matplotlib.patches import Patch
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[3]
+data = json.loads((HERE / 'data.json').read_text())
+for face in ['Regular', 'Semibold']:
+    fontManager.addfont(str(ROOT / 'assets/fonts' / f'OpenDocSans-{face}.ttf'))
+regular = FontProperties(fname=ROOT / 'assets/fonts/OpenDocSans-Regular.ttf')
+plt.rcParams.update({'font.family': regular.get_name(), 'font.size': 16,
+    'text.color': '#171A1D', 'axes.labelcolor': '#62686D',
+    'xtick.color': '#62686D', 'ytick.color': '#62686D',
+    'axes.edgecolor': '#D7D7D2', 'axes.linewidth': .7, 'svg.fonttype': 'path'})
+stages = data['stages']
+weeks = np.arange(1, 13)
+values = np.array([[sum(row[stage] for row in data['documents'] if row['week'] == week)
+                   for week in weeks] for stage in stages])
+palette = ['#D4D0C7', '#969DA5', '#30363C', '#3758F9']
+fig = plt.figure(figsize=(14.4, 5), facecolor='white')
+ax = fig.add_axes([.058, .22, .922, .64])
+ax.stackplot(weeks, values, colors=palette, linewidth=.8, edgecolor='white')
+ax.set_xlim(1, 12)
+ax.set_ylim(0, 110)
+ax.set_yticks([0, 25, 50, 75, 100])
+ax.set_xticks(weeks, [f'W{i:02}' for i in weeks])
+ax.tick_params(length=0, pad=9, labelsize=15)
+ax.grid(axis='y', color='#D7D7D2', linewidth=.6)
+ax.set_axisbelow(True)
+for side in ['top', 'right', 'left']:
+    ax.spines[side].set_visible(False)
+fig.text(.058, .936, 'Hours per week', fontsize=16, color='#62686D')
+fig.legend(handles=[Patch(facecolor=color, label=stage.capitalize()) for stage, color in zip(stages, palette)],
+    loc='lower center', bbox_to_anchor=(.52, .012), ncol=4, frameon=False,
+    fontsize=16, handlelength=1.1, handleheight=.7, columnspacing=3)
+fig.savefig(HERE / 'image.png', dpi=300, facecolor='white')
+fig.savefig(HERE / 'chart.svg', facecolor='white')
+plt.close(fig)
+print(json.dumps({'documents':len(data['documents']), 'weeks':len(weeks),
+    'hours':int(values.sum()), 'workstreams':dict(zip(stages,map(int,values.sum(axis=1))))},indent=2))

package/starter/documents/welcome-presentation/theme.tsx

@@ -0,0 +1,5 @@
+import { theme as base } from '../../themes/opendoc-neutral';
+import { withDocumentAssets, type DocumentAssets } from 'opendoc/assets';
+import assets from './assets.json';
+
+export const theme = withDocumentAssets(base, assets as DocumentAssets);

package/starter/projects.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "projects": [
+    {
+      "id": "getting-started",
+      "name": "Getting started",
+      "defaultTheme": "neutral"
+    }
+  ],
+  "assignments": {
+    "welcome": "getting-started",
+    "welcome-presentation": "getting-started"
+  },
+  "formats": {
+    "welcome-presentation": "presentation"
+  }
+}

package/starter/templates/AGENTS.md

@@ -0,0 +1,9 @@
+# Working with templates
+
+Treat every template as a soft foundation for the document being created. It offers a useful starting composition and design intent, with room for variation and creativity. Let the actual content, reader, and purpose guide the result; use judgment rather than trying to reproduce the specimen exactly.
+
+Typography, spacing, margins, image proportions, and placement are starting values. For example, reduce the title size when a long headline overwhelms the opening; rebalance its surrounding space, or adjust the reading measure when the material benefits. Optional elements can be omitted, moved, or adapted. Preserve a coherent hierarchy and readable flow, not every original measurement. Routine design adjustments within the user's brief do not need additional approval.
+
+Keep document-specific adaptations local to that document or a local layout variant. If a small shared option is useful, preserve existing defaults so other documents do not change accidentally. Do not add a generalized layout engine or automatic fitting machinery for a simple design adjustment.
+
+Distinguish design guidance from functional requirements. Native Forme flow, stable block IDs, accurate evidence, validated data contracts where applicable, and preservation of unrelated documents remain requirements. Review the rendered result after adapting it. Each template's guidance should explain its character and useful defaults while making this freedom explicit.

package/starter/templates/_shared/BusinessLogo.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { Block } from 'opendoc';
+import type { DocTheme } from 'opendoc/themes';
+
+/** Replace the placeholder with supplied artwork, or pass null to omit the slot. */
+export function BusinessLogo({ id, theme, children }: { id: string; theme: DocTheme; children?: ReactNode }) {
+  if (children === null || children === false) return null;
+  return <Block id={id} style={{ width: 88, alignItems: 'flex-end' }}>
+    {children === undefined ? <F.View wrap={false} style={{ width: 88, height: 28, borderWidth: 0.6, borderColor: theme.line, alignItems: 'center', justifyContent: 'center' }}>
+      <F.Text style={{ fontSize: 8, letterSpacing: 1.2, color: theme.muted }}>YOUR LOGO</F.Text>
+    </F.View> : children}
+  </Block>;
+}

package/starter/templates/_shared/Pricing.tsx

@@ -0,0 +1,40 @@
+import * as F from '@formepdf/react';
+import { TextSlot, Block, DataTable } from 'opendoc';
+import type { DocTheme } from 'opendoc/themes';
+import { calculatePricing, money, unitPriceMinor, type PricingData } from './commerce';
+
+export function Pricing({ id = 'pricing', data, theme, totalLabel = 'Total', paymentReceived }: { id?: string; data: PricingData; theme: DocTheme; totalLabel?: string; paymentReceived?: bigint }) {
+  const totals = calculatePricing(data);
+  if (paymentReceived !== undefined && (paymentReceived < 0n || paymentReceived > totals.totalMinor)) throw new Error('Received payment must be between zero and the total.');
+  const amounts = [
+    ['Subtotal', totals.subtotalMinor],
+    ...(data.discount === undefined ? [] : [['Discount', -totals.discountMinor] as const]),
+    ...(data.tax ? [[`${data.tax.label} (${data.tax.ratePercent}%)`, totals.taxMinor] as const] : []),
+    [totalLabel, totals.totalMinor],
+    ...(paymentReceived === undefined ? [] : [['Payments received', -paymentReceived], ['Amount due', totals.totalMinor - paymentReceived]] as const),
+  ] as const;
+  return <>
+    <DataTable id={`${id}-items`} columns={[
+      { label: 'Description', width: 3.2 }, { label: 'Qty / unit', width: 1.1, align: 'right' },
+      { label: `Unit price (${data.currency.code})`, width: 1.6, align: 'right' }, { label: `Amount (${data.currency.code})`, width: 1.7, align: 'right' },
+    ]} rowIds={totals.items.map(item => item.id)} rows={totals.items.map(item => [
+      <TextSlot slot={`item-${item.id.length}-${item.id}-description`} field={['pricing', 'items', { id: item.id }, 'description']}>{item.description}</TextSlot>,
+      <TextSlot slot={`item-${item.id.length}-${item.id}-quantity-unit`}><TextSlot slot="quantity" reason="Calculated input—ask your agent to change quantities.">{item.quantity}</TextSlot>{item.unit ? <> <TextSlot slot="unit" field={['pricing', 'items', { id: item.id }, 'unit']}>{item.unit}</TextSlot></> : ''}</TextSlot>,
+      money(unitPriceMinor(item, data.currency), data.currency, false), money(item.amountMinor, data.currency, false),
+    ])} />
+    <Block id={`${id}-totals`} style={{ flexDirection: 'row', justifyContent: 'flex-end', marginBottom: 18 }}><F.View wrap={false} style={{ width: 260 }}>
+      {amounts.map(([label, amount], index) => {
+        const final = index === amounts.length - 1;
+        const taxRow = data.tax && index === 1 + (data.discount === undefined ? 0 : 1);
+        const textStyle: F.Style = {
+          fontSize: final ? 12 : 10, fontWeight: final ? 600 : 400,
+          ...theme.design?.table?.text, ...(final ? theme.design?.table?.headerText : undefined),
+        };
+        return <F.View key={label} style={{ paddingTop: 8, paddingBottom: 8, borderTopWidth: final ? 0.8 : 0, borderColor: theme.line, ...theme.design?.table?.cell, ...(final ? theme.design?.table?.header : undefined), flexDirection: 'row', gap: 12 }}>
+          <F.Text style={{ ...textStyle, flex: 1 }}>{taxRow ? <><TextSlot slot="tax-label" field={['pricing', 'tax', 'label']}>{data.tax!.label}</TextSlot> ({data.tax!.ratePercent}%)</> : label}</F.Text>
+          <F.Text style={{ ...textStyle, textAlign: 'right' }}><TextSlot slot={`amount-${index}`} reason="Calculated value—ask your agent to change its inputs.">{amount < 0n ? '−' : ''}{money(amount < 0n ? -amount : amount, data.currency)}</TextSlot></F.Text>
+        </F.View>;
+      })}
+    </F.View></Block>
+  </>;
+}

package/starter/templates/_shared/commerce.ts

@@ -0,0 +1,93 @@
+export function object(value: unknown, allowed: string[], path: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path}: expected an object.`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${path}.${key}: unknown field.`);
+  return value as Record<string, unknown>;
+}
+export function text(value: unknown, path: string, max = 5000, maxLines = Infinity): string {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > max) throw new Error(`${path}: use nonempty text of at most ${max} characters.`);
+  if (value.trim().split(/\r\n|\r|\n/).length > maxLines) throw new Error(`${path}: use at most ${maxLines} supplied lines so this field fits its layout.`);
+  return value.trim();
+}
+export function optionalText(value: unknown, path: string, max = 5000, maxLines = Infinity) {
+  return value === undefined || value === null ? undefined : text(value, path, max, maxLines);
+}
+export function date(value: unknown, path: string): string {
+  const input = text(value, path, 10);
+  const parsed = new Date(`${input}T00:00:00Z`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(input) || input.startsWith('0000') || !Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== input) throw new Error(`${path}: use a real date in YYYY-MM-DD format.`);
+  return input;
+}
+function decimal(value: unknown, places: number, path: string, positive = false, integerDigits = 9): string {
+  if (typeof value !== 'string' || !new RegExp(`^(0|[1-9][0-9]{0,${integerDigits - 1}})${places ? `(\\.[0-9]{1,${places}})?` : ''}$`).test(value)) throw new Error(`${path}: use a nonnegative decimal string with at most ${integerDigits} integer digits and ${places} decimal places.`);
+  if (positive && scaled(value, places) === 0n) throw new Error(`${path}: must be greater than zero.`);
+  return value;
+}
+function scaled(value: string, places: number): bigint {
+  const [whole, fraction = ''] = value.split('.');
+  return BigInt(whole) * 10n ** BigInt(places) + BigInt(fraction.padEnd(places, '0') || '0');
+}
+const roundHalfUp = (value: bigint, divisor: bigint) => (value + divisor / 2n) / divisor;
+export interface PricingData {
+  currency: { code: string; decimals: number };
+  items: { id: string; description: string; quantity: string; unit?: string; unitPrice: string }[];
+  discount?: string;
+  tax?: { label: string; ratePercent: string };
+}
+
+export function parsePricing(input: unknown): PricingData {
+  const value = object(input, ['currency', 'items', 'discount', 'tax'], 'pricing');
+  const currency = object(value.currency, ['code', 'decimals'], 'pricing.currency');
+  if (typeof currency.code !== 'string' || !/^[A-Z]{3}$/.test(currency.code)) throw new Error('pricing.currency.code: supply a three-letter uppercase currency code.');
+  if (typeof currency.decimals !== 'number' || !Number.isInteger(currency.decimals) || currency.decimals < 0 || currency.decimals > 3) throw new Error('pricing.currency.decimals: supply 0, 1, 2, or 3 explicitly.');
+  const places = currency.decimals;
+  if (!Array.isArray(value.items) || !value.items.length || value.items.length > 500) throw new Error('pricing.items: supply 1–500 line items.');
+  const seen = new Set<string>();
+  const items = value.items.map((raw, i) => {
+    const path = `pricing.items[${i}]`;
+    const item = object(raw, ['id', 'description', 'quantity', 'unit', 'unitPrice'], path);
+    const id = text(item.id, `${path}.id`, 100);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || seen.has(id)) throw new Error(`${path}.id: supply a unique stable ID with letters, numbers, dots, underscores, or hyphens.`);
+    seen.add(id);
+    return { id, description: text(item.description, `${path}.description`, 600, 8), quantity: decimal(item.quantity, 3, `${path}.quantity`, true), unit: optionalText(item.unit, `${path}.unit`, 24, 1), unitPrice: decimal(item.unitPrice, places, `${path}.unitPrice`) };
+  });
+  let tax: PricingData['tax'];
+  if (value.tax !== undefined && value.tax !== null) {
+    const rate = object(value.tax, ['label', 'ratePercent'], 'pricing.tax');
+    const ratePercent = decimal(rate.ratePercent, 2, 'pricing.tax.ratePercent');
+    if (scaled(ratePercent, 2) > 10000n) throw new Error('pricing.tax.ratePercent: use a rate from 0 to 100.');
+    tax = { label: text(rate.label, 'pricing.tax.label', 60, 1), ratePercent };
+  }
+  const result: PricingData = { currency: { code: currency.code, decimals: places }, items, discount: value.discount === undefined || value.discount === null ? undefined : decimal(value.discount, places, 'pricing.discount'), tax };
+  calculatePricing(result);
+  return result;
+}
+
+/** Integer arithmetic: round each line, then tax the discounted subtotal, half up. */
+export function calculatePricing(data: PricingData) {
+  const items = data.items.map(item => ({ ...item, amountMinor: roundHalfUp(scaled(item.quantity, 3) * scaled(item.unitPrice, data.currency.decimals), 1000n) }));
+  const subtotalMinor = items.reduce((sum, item) => sum + item.amountMinor, 0n);
+  const discountMinor = scaled(data.discount ?? '0', data.currency.decimals);
+  if (discountMinor > subtotalMinor) throw new Error('pricing.discount: cannot exceed the subtotal.');
+  const netMinor = subtotalMinor - discountMinor;
+  const taxMinor = data.tax ? roundHalfUp(netMinor * scaled(data.tax.ratePercent, 2), 10000n) : 0n;
+  const totalMinor = netMinor + taxMinor;
+  if (subtotalMinor > BigInt(Number.MAX_SAFE_INTEGER) || totalMinor > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('pricing: total exceeds the supported amount range.');
+  return { items, subtotalMinor, discountMinor, netMinor, taxMinor, totalMinor };
+}
+
+export function money(minor: bigint, currency: PricingData['currency'], includeCode = true) {
+  const scale = 10n ** BigInt(currency.decimals);
+  const whole = (minor / scale).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  const fraction = currency.decimals ? `.${(minor % scale).toString().padStart(currency.decimals, '0')}` : '';
+  return `${includeCode ? `${currency.code} ` : ''}${whole}${fraction}`;
+}
+export function unitPriceMinor(item: PricingData['items'][number], currency: PricingData['currency']) {
+  return scaled(item.unitPrice, currency.decimals);
+}
+
+/** A supplied payment may cover the complete calculated total, not just one unit price. */
+export function paymentMinor(input: unknown, currency: PricingData['currency'], path: string): bigint {
+  const value = scaled(decimal(input, currency.decimals, path, false, 16), currency.decimals);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`${path}: amount exceeds the supported range.`);
+  return value;
+}

package/starter/templates/brand-guidelines/AGENTS.md

@@ -0,0 +1,32 @@
+# Brand guidelines
+
+An identity handbook with the rhythm of a design presentation: oversized type, generous image fields, opposing mark variants, annotated specimens, contact sheets, and application galleries. Neutral is the catalog appearance, not a proposed brand. Every bracketed text or artwork area is a replaceable placeholder. Never turn these prompts into invented company facts, approved rules, or licensing claims.
+
+## Structure and useful variations
+
+The eighteen-slide starter moves from purpose, voice, and visual world to marks, measured usage, color, accessibility, typography, imagery, graphic language, applications, and ownership. This is an adaptable collection, not a required outline. A small identity may omit motion, physical applications, or alternate marks. A complex one may add subbrands, partnerships, multilingual specimens, packaging, data visualization, or motion sequences as separate slides.
+
+Show real examples beside rules. A clear-space page needs an approved annotated diagram and actual measurements, not a decorative grid mistaken for a specification. The sample swatch widths are a composition, not palette ratios. Display the verified color values for every medium the brand uses. Record actual tested text/background combinations, their sizes and target standard; a dark/light specimen is not an accessibility certification. Use written labels or other cues alongside color.
+
+The image-rich spreads should do different jobs: the expression board communicates a world; photography defines the point of view; crop variants preserve the subject across formats; application galleries show the system operating. Replace image briefs with meaning-bearing artwork and retain concise captions explaining the choices. The graphics slide supports icons, illustration, pattern, or a static motion storyboard only when relevant.
+
+Typography and geometry are starting values. A long title receives an explicit smaller opening size; shorten further or adapt its field when needed. Rebalance an image or omit an optional caption when the material benefits. Each slide remains one 960 × 540 page; preserve stable slide and component IDs when reordering. `BrandText` binds its caller's `children` through `TextSlot`, so edits belong to the instance. All visible starter copy is local; the shared layout has no brand argument or rule set.
+
+## Artwork and appearance
+
+`BrandImage` accepts `image={{item:'document-media-id',fit:'cover',position:{x:0.5,y:0.5}}}` for managed `MediaFrame` artwork. Use `fit:'contain'` for a diagram or mark that must remain complete. A missing image is intentional; a supplied missing media item must fail. Import and review document-owned images according to [Media](../../docs/MEDIA.md), keeping provenance and original source records.
+
+Reusable logos belong in the shared [asset library](../../docs/ASSETS.md). After binding the intended family/version, use `logo={{variation:'approved-variation'}}` or `logo={{name:'partner',variation:'approved-variation'}}`. Bind the correct light/dark variation for the actual PDF surface. The template does not recolor, distort, or fabricate a logo. Choose either `image` or `logo` for a slot. Saved fonts come from the instance's generated theme adapter; retain that import and `assets.json`.
+
+The starter passes its caller's theme into every slide and specimen. Its presentation sizes are deliberately local, while font family, semantic title styling, paper, line, and ink follow the theme. Catalog imagery remains empty because a generic brand manual should not imply ownership of stock pictures or resemble an existing brand.
+
+## Research and rationale
+
+Reviewed official sources on 11 September 2026. These sources inform the categories and the usefulness of the skeleton; their own brand-specific aesthetic rules are not imposed on another brand.
+
+- [Adobe Express: How to create brand guidelines](https://www.adobe.com/uk/express/discover/examples/brand-guidelines) covers brand foundations, approved logo variations, color specifications, typography, image/icon guidance, and voice. This informed the foundation-to-application coverage and the paired voice example. Its mood-board and contextual-example guidance informed the expression board.
+- [IBM Design Language: Color](https://www.ibm.com/design/language/color/) treats colors as roles and discusses contrast, background variations, and avoiding reliance on color alone. This informed the role-based palette specimen and a separate evidence-oriented pairing page, without claiming the placeholders meet a specific standard.
+- [IBM Design Language: Photography tips and techniques](https://www.ibm.com/design/language/photography/tips-and-techniques/) explains perspective, framing, focal points, aspect ratio, lighting, and purposeful imagery. This informed separate art-direction and crop compositions. IBM's specific lens, lighting, and filter preferences remain IBM's rules; authors supply the rules for their own identity.
+- [IBM Design Language: Resources](https://www.ibm.com/design/language/resources/) connects identity components to source tools, font repositories, logo permissions, photography, and motion resources. This informed a practical handoff slide with asset access, ownership, permissions, versions, and a review path.
+
+Review every native PDF slide, including labels and the final ownership slide, after replacing copy or images. Check actual crop visibility, text extraction, image contrast, and the intended variant on its background. Keep catalog specimens and acceptance fixtures outside the user document library.

package/starter/templates/brand-guidelines/index.tsx

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { Block, Logo, MediaFrame, Presentation, Slide, TextSlot, type ImageFrameOptions } from 'opendoc';
+import { themeType, type DocTheme } from 'opendoc/themes';
+
+export type BrandImageSource = Pick<ImageFrameOptions, 'fit' | 'position' | 'radius'> & { item: string; alt?: string };
+export type BrandBox = { x: number; y: number; w: number; h: number };
+const position = ({ x, y, w, h }: BrandBox): F.Style => ({ position: 'absolute', left: x, top: y, width: w, height: h });
+
+/** A presentation made from independent, reorderable brand-system compositions. */
+export function BrandGuidelines(props: Parameters<typeof Presentation>[0]) { return <Presentation {...props}/>; }
+
+export function BrandSlide({ id, theme, section, folio, dark = false, children }: {
+  id: string; theme: DocTheme; section: ReactNode; folio: ReactNode; dark?: boolean; children: ReactNode;
+}) {
+  return <Slide id={id} padding={0} style={{ backgroundColor: dark ? theme.ink : theme.paper, lineBreaking: 'greedy' }}>
+    <Block id={`${id}-section`} style={{...position({x:40,y:26,w:800,h:25}),overflow:'hidden'}}><F.Text style={{...themeType(theme,'label'),fontSize:11,fontWeight:400,color:dark?theme.paper:theme.muted,lineHeight:1.2,margin:0}}><TextSlot slot="section" from="section">{section}</TextSlot></F.Text></Block>
+    <Block id={`${id}-folio`} style={{...position({x:870,y:26,w:50,h:25}),overflow:'hidden'}}><F.Text style={{fontFamily:theme.body,fontSize:11,fontWeight:400,color:dark?theme.paper:theme.muted,lineHeight:1.2,margin:0,textAlign:'right'}}><TextSlot slot="folio" from="folio">{folio}</TextSlot></F.Text></Block>
+    {children}
+  </Slide>;
+}
+
+/** Text stays native and binds to the instance's children, including direct JSX text. */
+export function BrandText({ id, theme, x, y, w, h, children, size = 18, role = 'body', color, align = 'left', weight, leading = 1.2 }: BrandBox & {
+  id: string; theme: DocTheme; children: ReactNode; size?: number; role?: 'body' | 'title' | 'label';
+  color?: string; align?: 'left' | 'center' | 'right'; weight?: 400 | 600 | 700; leading?: number;
+}) {
+  const type = role === 'title' ? themeType(theme, 'h1') : role === 'label' ? themeType(theme, 'label') : { fontFamily: theme.body };
+  return <Block id={id} style={{...position({ x, y, w, h }), overflow:'hidden'}}>
+    <F.Text style={{ ...type, fontSize: size, fontWeight: weight ?? (role === 'title' ? 600 : 400), color: color ?? theme.ink, lineHeight: leading, margin: 0, textAlign: align }}>
+      <TextSlot slot="text" from="children">{children}</TextSlot>
+    </F.Text>
+  </Block>;
+}
+
+/** Supplied artwork must be valid managed media. No image means an intentional visual brief. */
+export function BrandImage({ id, theme, x, y, w, h, image, logo, label, detail, dark = false }: BrandBox & {
+  id: string; theme: DocTheme; image?: BrandImageSource; logo?: { name?: string; variation?: string; alt?: string };
+  label: ReactNode; detail?: ReactNode; dark?: boolean;
+}) {
+  if (image && logo) throw new Error(`Brand image ${id}: choose managed media or a bound logo, not both.`);
+  const background = dark ? theme.ink : theme.line;
+  const foreground = dark ? theme.paper : theme.ink;
+  return <Block id={id} style={position({ x, y, w, h })}>
+    {image ? <MediaFrame {...image} width={w} height={h}/> : logo ? <F.View style={{ width:w, height:h, backgroundColor:background, alignItems:'center', justifyContent:'center', padding:24 }}><Logo {...logo} width={w-48} height={h-48}/></F.View> : <F.View style={{width:w,height:h,backgroundColor:background,borderWidth:0.5,borderColor:dark?theme.muted:theme.line}}>
+      <F.View style={{position:'absolute',left:16,top:16,width:18,height:18,borderLeftWidth:1,borderTopWidth:1,borderColor:foreground}}/>
+      <F.View style={{position:'absolute',left:w-34,top:h-34,width:18,height:18,borderRightWidth:1,borderBottomWidth:1,borderColor:foreground}}/>
+      <F.View style={{position:'absolute',left:24,top:h/2-25,width:w-48,height:50,justifyContent:'center',overflow:'hidden'}}>
+        <F.Text style={{fontFamily:theme.heading,fontSize:w<190?16:22,fontWeight:400,color:foreground,textAlign:'center',lineHeight:1.15}}><TextSlot slot="label" from="label">{label}</TextSlot></F.Text>
+      </F.View>
+      {detail && <F.View style={{position:'absolute',left:20,top:h-43,width:w-40,height:30,overflow:'hidden'}}><F.Text style={{fontFamily:theme.body,fontSize:10,color:foreground,textAlign:'center',lineHeight:1.2}}><TextSlot slot="detail" from="detail">{detail}</TextSlot></F.Text></F.View>}
+    </F.View>}
+  </Block>;
+}
+
+export function BrandPanel({ theme, x, y, w, h, color, outline = false }: BrandBox & { theme: DocTheme; color?: string; outline?: boolean }) {
+  return <F.View style={{...position({x,y,w,h}),backgroundColor:color ?? theme.paper,...(outline?{borderWidth:1,borderColor:theme.muted}:{})}}/>;
+}
+
+export function BrandRule({ theme, x, y, w, color }: { theme: DocTheme; x:number; y:number; w:number; color?:string }) {
+  return <F.View style={{position:'absolute',left:x,top:y,width:w,height:1,backgroundColor:color??theme.line}}/>;
+}