@3xhaust/oh-my-design 0.16.1

package/core/frame/check-ux.ts

@@ -0,0 +1,180 @@
+import type { Violation } from '../types.ts';
+import { readFrame } from './index.ts';
+
+export type UxSurface = 'marketing' | 'product' | 'editorial' | 'mixed';
+
+const UX_SURFACES = new Set<UxSurface>(['marketing', 'product', 'editorial', 'mixed']);
+const TASK_COVERAGE_VIEWPORTS = new Set(['desktop', 'mobile']);
+const TASK_COVERAGE_REQUIREMENTS = new Set(['invalid-submit', 'transient']);
+const TASK_COVERAGE_FIELDS = ['goal', 'start', 'actions', 'success', 'recovery', 'viewports', 'requirements'] as const;
+const TASK_COVERAGE_MATRIX_HEADING = /^## Task coverage matrix[ \t]*$/gm;
+
+/** Return the normalized supported UX surface, or null for a missing or invalid value. */
+export function normalizeUxSurface(value: unknown): UxSurface | null {
+  if (typeof value !== 'string') return null;
+
+  const surface = value.trim().toLowerCase();
+  return UX_SURFACES.has(surface as UxSurface) ? surface as UxSurface : null;
+}
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+function validateUniqueCsvSubset(
+  id: string,
+  field: 'viewports' | 'requirements',
+  value: string,
+  allowed: ReadonlySet<string>,
+  allowsNone: boolean,
+): string | null {
+  const values = value.split(',').map((item) => item.trim());
+  if (values.some((item) => !item)) {
+    return `${id} ${field} must be a comma-separated list`;
+  }
+  if (allowsNone && values.includes('none')) {
+    return values.length === 1 ? null : `${id} requirements none cannot be combined with other values`;
+  }
+
+  const seen = new Set<string>();
+  for (const item of values) {
+    if (!allowed.has(item)) return `${id} ${field} contains unknown value: ${item}`;
+    if (seen.has(item)) return `${id} ${field} contains duplicate value: ${item}`;
+    seen.add(item);
+  }
+  return null;
+}
+
+
+
+/**
+ * `T1 | goal: … | start: … | actions: … | success: … | recovery: … | viewports: … | requirements: …`
+ *
+ * IDs must be unique. Every field must be non-empty. Only recovery may use
+ * `N/A: <reason>` or `N/A — <reason>`. Viewports are a unique subset of
+ * `desktop,mobile`; requirements are `none` or a unique subset of
+ * `invalid-submit,transient`.
+ */
+export function validateTaskCoverageMatrix(matrix: string): string[] {
+  const rows = matrix.split('\n').map((row) => row.trim()).filter(Boolean);
+  const errors: string[] = [];
+  const ids = new Set<string>();
+
+  if (rows.length === 0) return ['task coverage matrix has no rows'];
+
+  for (const row of rows) {
+    const columns = row.split('|').map((column) => column.trim());
+    const id = columns.shift();
+    if (!id || !/^T[1-9]\d*$/.test(id)) {
+      errors.push(`malformed task coverage row: ${row}`);
+      continue;
+    }
+    if (ids.has(id)) {
+      errors.push(`duplicate task coverage id: ${id}`);
+      continue;
+    }
+    ids.add(id);
+
+    if (columns.length !== TASK_COVERAGE_FIELDS.length) {
+      errors.push(`malformed task coverage row: ${row}`);
+      continue;
+    }
+
+    for (const [index, field] of TASK_COVERAGE_FIELDS.entries()) {
+      const column = columns[index] ?? '';
+      const match = new RegExp(`^${field}:\\s*(.+)$`).exec(column);
+      const value = match?.[1]?.trim() ?? '';
+      if (!value) {
+        errors.push(`${id} is missing ${field}`);
+      } else if (/^N\/A\b/i.test(value)) {
+        if (field !== 'recovery') {
+          errors.push(`${id} ${field} must not be N/A`);
+        } else if (!/^N\/A\s*(?::|—)\s*\S/.test(value)) {
+          errors.push(`${id} recovery N/A requires a reason`);
+        }
+      } else if (field === 'viewports') {
+        const error = validateUniqueCsvSubset(id, field, value, TASK_COVERAGE_VIEWPORTS, false);
+        if (error) errors.push(error);
+      } else if (field === 'requirements') {
+        const error = validateUniqueCsvSubset(id, field, value, TASK_COVERAGE_REQUIREMENTS, true);
+        if (error) errors.push(error);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function taskCoverageMatrixSections(body: string): string[] {
+  return body
+    .split(TASK_COVERAGE_MATRIX_HEADING)
+    .slice(1)
+    .map((section) => section.split(/^## /m)[0] ?? '');
+}
+
+/**
+ * Validate that the frame artifact has answered the UX anchor questions.
+ *
+ * `uxSurface` is one of marketing, product, editorial, or mixed. Product and mixed
+ * frames require exactly one valid `## Task coverage matrix`; marketing and editorial
+ * frames reject task coverage matrix contamination. Unsupported non-empty surfaces fail closed.
+ */
+export function checkFrameUx(cwd: string): Violation[] {
+  const frame = readFrame(cwd);
+  if (!frame) return [];
+
+  const missing: string[] = [];
+
+  if (!isNonEmptyString(frame.uxTask)) missing.push('uxTask (--task)');
+  if (!isNonEmptyString(frame.uxFrequentAction)) {
+    missing.push('uxFrequentAction (--frequent-action)');
+  }
+  if (!isNonEmptyString(frame.uxCostliestError)) {
+    missing.push('uxCostliestError (--costliest-error)');
+  }
+
+  const rawSurface = frame.uxSurface;
+  const surface = normalizeUxSurface(rawSurface);
+  const hasSurface = typeof rawSurface === 'string' && rawSurface.trim().length > 0;
+  if (rawSurface === undefined || (typeof rawSurface === 'string' && !hasSurface)) {
+    missing.push('uxSurface (--surface)');
+  } else if (!surface) {
+    missing.push('uxSurface (--surface: marketing|product|editorial|mixed)');
+  }
+
+  const matrixSections = taskCoverageMatrixSections(frame.body);
+  const requiresTaskCoverageMatrix = surface === 'product' || surface === 'mixed'
+    || (hasSurface && !surface)
+    || (rawSurface !== undefined && typeof rawSurface !== 'string');
+  if (requiresTaskCoverageMatrix) {
+    if (matrixSections.length !== 1) {
+      missing.push(`taskCoverageMatrix (--task-matrix: requires exactly one section; found ${matrixSections.length})`);
+    } else {
+      const matrixErrors = validateTaskCoverageMatrix(matrixSections[0] ?? '');
+      if (matrixErrors.length > 0) {
+        missing.push(`taskCoverageMatrix (--task-matrix: ${matrixErrors.join('; ')})`);
+      }
+    }
+  } else if ((surface === 'marketing' || surface === 'editorial') && matrixSections.length > 0) {
+    missing.push('taskCoverageMatrix (--task-matrix: not allowed for marketing or editorial surfaces)');
+  }
+
+  if (missing.length === 0) return [];
+
+  return [
+    {
+      id: 'FRAME-UX-INCOMPLETE',
+      severity: 'warn',
+      layer: 1,
+      category: 'ux',
+      nodeId: 'page',
+      path: 'frame',
+      value: missing.join(', '),
+      message:
+        `The frame exists but the following UX anchor question${missing.length === 1 ? ' is' : 's are'} unanswered: `
+        + `${missing.join('; ')}. `
+        + 'A frame that cannot name the costliest error has not been interrogated. '
+        + 'Run `omd frame set --task "..." --frequent-action "..." --costliest-error "..." --surface "..."'
+        + `${requiresTaskCoverageMatrix ? ' --task-matrix "T1 | goal: … | start: … | actions: … | success: … | recovery: … | viewports: … | requirements: …"' : ''}`
+        + '` to complete it. See theory/ux.md §Task-first framing and §Surface types.',
+    },
+  ];
+}

package/core/frame/index.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import type { Frame } from '../types.ts';
+
+const framePath = (cwd: string): string => join(cwd, '.omd', 'frame.md');
+
+const isEnoent = (err: unknown): boolean =>
+  typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOENT';
+
+/**
+ * The frame is a record, not a gate. Nothing blocks on it.
+ *
+ * An earlier version made a human sign the reframing before any file could be written.
+ * That solved the wrong problem: a wrong reframing is caught by building something,
+ * rendering it, and looking — not by a signature. Worse, it made the loop impossible,
+ * since nothing could be built while approval was pending, so there was nothing to look
+ * at, so nothing could reveal the reframing was wrong.
+ */
+export function readFrame(cwd: string): Frame | null {
+  let text: string;
+  try {
+    text = readFileSync(framePath(cwd), 'utf8');
+  } catch (err) {
+    if (isEnoent(err)) return null;
+    throw err;
+  }
+
+  if (!text.startsWith('---\n')) return { body: text };
+
+  const closeIndex = text.indexOf('\n---', 3);
+  if (closeIndex === -1) return { body: text };
+
+  const frontmatter = (parse(text.slice(4, closeIndex)) ?? {}) as Partial<Frame>;
+  const rest = text.slice(closeIndex + 4);
+  const body = rest.startsWith('\n') ? rest.slice(1) : rest;
+
+  return { ...frontmatter, body };
+}

package/core/frame/write.ts

@@ -0,0 +1,168 @@
+import { mkdirSync, writeFileSync, appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+import { readFrame } from './index.ts';
+import { normalizeUxSurface, validateTaskCoverageMatrix } from './check-ux.ts';
+import type { Choice } from '../types.ts';
+
+const designDir = (cwd: string): string => join(cwd, '.omd');
+
+export function writeFrame(cwd: string, frontmatter: Record<string, unknown>, body: string): void {
+  mkdirSync(designDir(cwd), { recursive: true });
+  writeFileSync(join(designDir(cwd), 'frame.md'), `---\n${stringify(frontmatter).trimEnd()}\n---\n\n${body.trim()}\n`);
+}
+
+/**
+ * Nobody signs this. The `--why` requirement is not a gate on the human — it is a gate on
+ * the agent, which will otherwise reframe a brief on a hunch and call the hunch insight.
+ *
+ * UX fields remain optional for backward compatibility. When a surface or matrix is
+ * supplied, this writer validates it before writing: surfaces are normalized to the four
+ * supported values; product or mixed surfaces require a valid seven-field task coverage
+ * matrix, while marketing and editorial surfaces reject one.
+ */
+export function writeFrameRecord(cwd: string, opts: {
+  problem: string;
+  reframe: string;
+  why?: string;
+  uxTask?: string;
+  uxFrequentAction?: string;
+  uxCostliestError?: string;
+  uxSurface?: unknown;
+  taskCoverageMatrix?: unknown;
+}): string {
+  if (!opts.why || opts.why.trim().length < 10) {
+    throw new Error(
+      'A reframing without a cited observation is a guess. Pass --why with the review, '
+      + 'ticket, datum, or user sentence it rests on.',
+    );
+  }
+  const normalizedSurface = opts.uxSurface === undefined ? undefined : normalizeUxSurface(opts.uxSurface);
+  if (opts.uxSurface !== undefined && !normalizedSurface) {
+    throw new Error('uxSurface must be marketing, product, editorial, or mixed.');
+  }
+
+  if (opts.taskCoverageMatrix !== undefined && typeof opts.taskCoverageMatrix !== 'string') {
+    throw new Error('taskCoverageMatrix must be a string.');
+  }
+  const taskCoverageMatrix = opts.taskCoverageMatrix === undefined
+    ? undefined
+    : opts.taskCoverageMatrix.replace(/^## Task coverage matrix[ \t]*$/gm, '').trim();
+  if (taskCoverageMatrix !== undefined) {
+    const matrixErrors = validateTaskCoverageMatrix(taskCoverageMatrix);
+    if (matrixErrors.length > 0) {
+      throw new Error(`Invalid task coverage matrix: ${matrixErrors.join('; ')}`);
+    }
+  }
+  if ((normalizedSurface === 'marketing' || normalizedSurface === 'editorial') && taskCoverageMatrix !== undefined) {
+    throw new Error('Marketing and editorial surfaces must not include a task coverage matrix.');
+  }
+  if ((normalizedSurface === 'product' || normalizedSurface === 'mixed') && taskCoverageMatrix === undefined) {
+    throw new Error('Product and mixed surfaces require a valid task coverage matrix.');
+  }
+  const body = [
+    '## The given problem', '', opts.problem.trim(), '',
+    '## The reframing', '', opts.reframe.trim(), '',
+    '## Evidence', '', opts.why.trim(),
+    ...(taskCoverageMatrix ? ['', '', '## Task coverage matrix', '', taskCoverageMatrix] : []),
+  ].join('\n');
+
+  const frontmatter: Record<string, unknown> = { why: opts.why.trim(), writtenAt: new Date().toISOString() };
+  if (opts.uxTask?.trim()) frontmatter['uxTask'] = opts.uxTask.trim();
+  if (opts.uxFrequentAction?.trim()) frontmatter['uxFrequentAction'] = opts.uxFrequentAction.trim();
+  if (opts.uxCostliestError?.trim()) frontmatter['uxCostliestError'] = opts.uxCostliestError.trim();
+  if (normalizedSurface) frontmatter['uxSurface'] = normalizedSurface;
+
+  writeFrame(cwd, frontmatter, body);
+  return join(designDir(cwd), 'frame.md');
+}
+
+/**
+ * What the loop does when a rendered candidate reveals the problem was misunderstood.
+ * The old framing is kept, not overwritten: a frame that changed twice is the most
+ * interesting thing in the repository six months later.
+ */
+export function reframe(cwd: string, opts: { to: string; because: string }): string {
+  const frame = readFrame(cwd);
+  if (!frame) throw new Error('No frame yet. Run `omd frame set` first.');
+
+  const { body, ...frontmatter } = frame;
+  const revision = (typeof frontmatter['revision'] === 'number' ? frontmatter['revision'] : 0) + 1;
+  const appended = [
+    body.trimEnd(),
+    '',
+    `## Reframing ${revision}`,
+    '',
+    `**Now:** ${opts.to.trim()}`,
+    '',
+    `**Because:** ${opts.because.trim()}`,
+  ].join('\n');
+
+  writeFrame(cwd, { ...frontmatter, revision, reframedAt: new Date().toISOString() }, appended);
+  return join(designDir(cwd), 'frame.md');
+}
+
+export function setGenerator(cwd: string, generator: string): void {
+  const frame = readFrame(cwd);
+  const { body = '', ...frontmatter } = frame ?? {};
+  writeFrame(cwd, { ...frontmatter, generator }, body);
+}
+
+export function logDecision(cwd: string, what: string, why: string): string {
+  mkdirSync(designDir(cwd), { recursive: true });
+  const path = join(designDir(cwd), 'decisions.md');
+  if (!existsSync(path)) {
+    writeFileSync(path, '# Decisions\n\nWhat was built is in the code. Why it was built that way is only here.\n');
+  }
+  const generator = readFrame(cwd)?.generator ?? '(none set)';
+  appendFileSync(path, `\n## ${what}\n\n- When: ${new Date().toISOString()}\n- Point of view: ${generator}\n- Why: ${why}\n`);
+  return path;
+}
+
+export function logChoice(cwd: string, opts: { among: string[]; chose: string; why?: string }): string {
+  if (!opts.among.includes(opts.chose)) throw new Error(`${opts.chose} is not among ${opts.among.join(', ')}`);
+  mkdirSync(join(designDir(cwd), 'taste'), { recursive: true });
+  const path = join(designDir(cwd), 'taste', 'preferences.jsonl');
+
+  const record: Choice = {
+    ts: new Date().toISOString(),
+    actor: 'agent',
+    kind: 'selection',
+    subject: opts.chose,
+    evidence: opts.why ?? '',
+    among: opts.among,
+    chose: opts.chose,
+    why: opts.why ?? null,
+    generator: readFrame(cwd)?.generator ?? null,
+  };
+  appendFileSync(path, `${JSON.stringify(record)}\n`);
+  return path;
+}
+
+export function logTaste(cwd: string, opts: {
+  subject: string;
+  kind: 'selection' | 'praise' | 'rejection' | 'overrule';
+  evidence: string;
+  fromUser: boolean;
+}): string {
+  if (!opts.fromUser) throw new Error('Taste records require --from-user; inferred preference is not user evidence.');
+  if (!opts.subject.trim() || !opts.evidence.trim()) throw new Error('Taste subject and verbatim --evidence are required.');
+  mkdirSync(join(designDir(cwd), 'taste'), { recursive: true });
+  const path = join(designDir(cwd), 'taste', 'preferences.jsonl');
+  const record: Choice = {
+    ts: new Date().toISOString(), actor: 'user', kind: opts.kind,
+    subject: opts.subject.trim(), evidence: opts.evidence.trim(),
+  };
+  appendFileSync(path, `${JSON.stringify(record)}\n`);
+  return path;
+}
+
+export function tasteProfile(cwd: string, all = false): { n: number; records: Choice[] } {
+  const path = join(designDir(cwd), 'taste', 'preferences.jsonl');
+  if (!existsSync(path)) return { n: 0, records: [] };
+  const records = readFileSync(path, 'utf8').trim().split('\n').filter(Boolean).map((l) => {
+    const raw = JSON.parse(l) as Choice;
+    return { ...raw, actor: raw.actor ?? 'unknown' as const, kind: raw.kind ?? 'selection' as const };
+  }).filter((r) => all || r.actor === 'user');
+  return { n: records.length, records };
+}

package/core/graphics/css-illustration-primitives.md

@@ -0,0 +1,189 @@
+# CSS-only decorative illustration primitives
+
+CSS shapes — blobs via `border-radius`, layered circles, rotated rectangles, clipped
+polygons — that create abstract decorative elements without photography or SVG files.
+These primitives soften flat backgrounds, frame content sections, and add a spatial
+quality to otherwise bare layouts. The technique produces elements that read as
+decorative fields rather than illustrations: they have presence without narrative.
+
+The primitives are pure CSS: no image files, no JavaScript, no external dependencies.
+They scale perfectly at any resolution and can be themed by changing custom properties.
+
+## When it earns its place / When it does not
+
+Condition: sections that need visual weight without photography or purposeful illustration.
+A hero background that should feel organic rather than grid-based, a feature highlight
+where an abstract shape frames the text without competing with it, a footer that needs
+warmth without adding content. Useful when the budget or timeline prohibits custom
+illustration and stock photography would introduce a mismatched register.
+
+The organic blob specifically earns its place when the concept's governing metaphor is
+biological, human, or flowing — a health product, a creative tool, an emotional brand —
+where geometric shapes would read as cold. `core/theory/layout.md` closure principle:
+implied shapes created by border-radius have the same grouping effect as borders, with
+less visual weight.
+
+Condition against: when purposeful illustration exists and the CSS primitive would
+compete with it. When the brand register is technical or precise — geometric CSS shapes
+read as approximations of geometry; an actual SVG or canvas-drawn shape is more precise.
+Also: avoid when the shapes are purely filling space with no compositional purpose. A
+blob in the corner of a hero section that does not frame, separate, or accent anything
+is a shape placed to fill space, and `core/theory/layout.md`'s restraint applies: space
+is structural, not dead air to be decorated.
+
+## Parameters
+
+```css
+:root {
+  /* Blob colour: typically a low-saturation tint of the brand palette.
+     At 20–40% opacity the blob reads as ambient colour, not a shape.
+     At 60–80% opacity it reads as a distinct coloured element — use intentionally. */
+  --blob-color: hsl(220deg 50% 70% / 0.25);
+  --blob-secondary: hsl(280deg 40% 65% / 0.18);
+
+  /* Blob size: relative to the container.
+     60–80% produces an organic field that covers but does not dominate.
+     100%+ (bleeding beyond the container) reads as a background wash. */
+  --blob-size: 70%;
+
+  /* Blur on the blob: softens edges for ambient quality.
+     0: hard-edged shape — more deliberate, less ambient.
+     40–80px: fully soft — reads as ambient colour field, not a shape. */
+  --blob-blur: 60px;
+}
+```
+
+## Implementation
+
+**Organic blob (single, border-radius)**
+
+```css
+/* Applied to a pseudo-element so no extra HTML is needed. */
+.blob-bg {
+  position: relative;
+  isolation: isolate;
+  overflow: hidden;
+}
+
+.blob-bg::before {
+  content: '';
+  position: absolute;
+  /* Off-center placement creates visual interest without symmetry. */
+  top: -20%;
+  right: -10%;
+  width: var(--blob-size);
+  aspect-ratio: 1 / 1.1; /* slightly non-square for organic quality */
+  background: var(--blob-color);
+  /* The border-radius blob: a high, uneven border-radius on all corners.
+     No two adjacent values identical — this produces the organic shape. */
+  border-radius: 62% 38% 46% 54% / 60% 44% 56% 40%;
+  filter: blur(var(--blob-blur));
+  z-index: -1;
+  pointer-events: none;
+}
+
+/* Second blob for depth — offset from the first. */
+.blob-bg::after {
+  content: '';
+  position: absolute;
+  bottom: -15%;
+  left: -5%;
+  width: calc(var(--blob-size) * 0.7);
+  aspect-ratio: 1.2 / 1;
+  background: var(--blob-secondary);
+  border-radius: 40% 60% 70% 30% / 50% 60% 40% 50%;
+  filter: blur(calc(var(--blob-blur) * 1.2));
+  z-index: -1;
+  pointer-events: none;
+}
+```
+
+**Layered circle stack (explicit HTML elements for more control)**
+
+```html
+<!-- Decorative circles: aria-hidden, pointer-events: none. -->
+<div class="circle-stack" aria-hidden="true">
+  <div class="circle-stack__ring circle-stack__ring--1"></div>
+  <div class="circle-stack__ring circle-stack__ring--2"></div>
+  <div class="circle-stack__ring circle-stack__ring--3"></div>
+</div>
+```
+
+```css
+.circle-stack {
+  position: relative;
+  width: 400px;
+  height: 400px;
+  pointer-events: none;
+  user-select: none;
+}
+
+.circle-stack__ring {
+  position: absolute;
+  border-radius: 50%;
+  border: 1px solid currentColor;
+  opacity: 0.12;
+}
+
+.circle-stack__ring--1 {
+  inset: 0;
+  /* Full size ring */
+}
+
+.circle-stack__ring--2 {
+  inset: 15%;
+  /* Inset ring — concentric */
+}
+
+.circle-stack__ring--3 {
+  inset: 30%;
+  /* Innermost ring — the system reads as depth through concentric structure */
+}
+```
+
+**Clipped geometric accent (clip-path)**
+
+```css
+/* A rotated square clipped to a diamond — reads as a geometric accent mark. */
+.diamond-accent {
+  width: 120px;
+  height: 120px;
+  background: var(--color-accent);
+  clip-path: polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%);
+  opacity: 0.15;
+  position: absolute;
+  pointer-events: none;
+}
+```
+
+## Linter notes
+
+- CSS illustration primitives composed in the flagged SLOP-GRADIENT hue bands (indigo–violet,
+  purple–pink) read as the same AI-default aesthetic as gradient meshes in those bands.
+  The `SLOP-GRADIENT` rule does not fire on border-radius shapes directly, but shapes in
+  these hue ranges without a brand justification carry the same compositional risk. Record
+  the colour choice with a brand citation if it lands in those bands.
+
+- Blobs with `filter: blur()` applied to large elements are paint-intensive. A blob
+  covering 70% of a 1280px section requires the browser to blur a ~900px region. Set
+  `will-change: transform` only if the blob animates; for static blobs, `will-change`
+  adds GPU memory cost without benefit.
+
+- CSS shapes are decorative. Every shape element must carry `pointer-events: none` and
+  `aria-hidden="true"` when implemented as standalone HTML elements. Content must never
+  be inside a decorative shape element; it must be a sibling above it in z-order.
+
+## Do not combine with
+
+**svg-geometric-patterns.md behind the same element** — organic blobs and geometric
+patterns are opposite registers (organic randomness vs deliberate order). Combining both
+on the same background surface produces visual incoherence.
+
+**gradient-mesh.md at full opacity on the same surface** — a mesh gradient and a blob
+both create ambient colour fields. Two ambient fields on the same surface merge into a
+single muddied background rather than two distinct spatial signals. Use the blob or the
+mesh, not both; or confine one to a small spot and the other to the full background.
+
+**Purposeful photography or illustration** — CSS illustration primitives are a substitute
+for imagery when none exists. When real photography or illustration is present, CSS
+shapes compete with it for compositional attention.