@3xhaust/oh-my-design 0.16.1

package/core/graphics/duotone-image-presets.md

@@ -0,0 +1,173 @@
+# Duotone / treated image presets
+
+A duotone treatment replaces an image's tonal range with two colours — one for the
+shadows, one for the highlights — using a CSS `filter` chain. The result reads as
+intentional art direction rather than stock photography: the same face or landscape
+in two hues aligned to the brand palette becomes a designed asset, not a found one.
+The technique unifies images from different sources under a single visual language.
+
+The CSS implementation uses `filter: grayscale(1) contrast() brightness() sepia() hue-rotate()` chained in a specific order to achieve the duotone effect without SVG
+feColorMatrix or Canvas manipulation. A secondary blend-mode approach using
+`mix-blend-mode: multiply` or `color` can achieve richer duotones when browser support
+allows for the stacking context requirements.
+
+## When it earns its place / When it does not
+
+Condition: when real images exist but come from varied sources — team photography at
+different times, stock imagery from multiple libraries, user-generated content — and
+visual unification is needed without re-photographing everything. A duotone treatment
+makes diverse source material read as a designed set. Also: when the brand palette is
+strong and the concept benefits from photographs that are unmistakably on-brand; the
+treatment removes the image's original colour story and replaces it with the brand's.
+
+`core/theory/layout.md` on similarity: "elements that look the same are read as
+belonging to the same category." A grid of duotone-treated images reads as a unified
+collection; the same grid with untreated photographs reads as a collection of separate
+images that happen to share space.
+
+Condition against: product photography where accurate colour matters — food, fashion,
+product hardware. Medical or scientific imagery where colour carries meaning. Any context
+where the user needs to see the actual colours of the subject. Documentation images where
+clarity outweighs aesthetic treatment.
+
+## Parameters
+
+```css
+:root {
+  /* The CSS filter duotone uses a grayscale base plus hue rotation and saturation.
+     Exact values depend on the target shadow and highlight colours.
+     The values below produce a warm amber shadow / cool blue highlight duotone.
+     Calibrate these against the brand palette — these are starting points. */
+
+  /* Step 1: desaturate completely. */
+  --dt-grayscale: grayscale(1);
+
+  /* Step 2: boost contrast so shadows and highlights are distinct zones. */
+  --dt-contrast: contrast(1.2);
+
+  /* Step 3: add the shadow tone via sepia (shifts greys to warm amber). */
+  --dt-sepia: sepia(0.8);
+
+  /* Step 4: rotate hue to place the image in the brand palette zone.
+     0deg: warm amber (sepia base).
+     60deg: warm yellow-green.
+     180deg: cyan-teal.
+     240deg: blue.
+     300deg: purple-pink.
+     Combine with saturation adjustment for exact colour targeting. */
+  --dt-hue: hue-rotate(200deg);
+
+  /* Step 5: saturation of the resulting toned image.
+     0.6–0.8: subtle colour wash — reads as toned, not fully coloured.
+     1.0–1.4: strong colour — reads as deliberately duotoned. */
+  --dt-saturate: saturate(1.2);
+
+  /* Final brightness correction: duotone often darkens; compensate here. */
+  --dt-brightness: brightness(1.05);
+}
+```
+
+## Implementation
+
+**CSS filter chain (single-colour tint approach)**
+
+```css
+/* The filter chain order matters. Changing the order changes the output. */
+.duotone {
+  filter:
+    var(--dt-grayscale)
+    var(--dt-contrast)
+    var(--dt-sepia)
+    var(--dt-hue)
+    var(--dt-saturate)
+    var(--dt-brightness);
+}
+
+/* Preset: brand blue duotone */
+.duotone--blue {
+  filter: grayscale(1) contrast(1.2) sepia(0.9) hue-rotate(180deg) saturate(1.3) brightness(1.0);
+}
+
+/* Preset: brand amber duotone */
+.duotone--amber {
+  filter: grayscale(1) contrast(1.15) sepia(1) hue-rotate(20deg) saturate(1.1) brightness(1.08);
+}
+
+/* Preset: monochrome (single tone, minimal saturation) */
+.duotone--mono {
+  filter: grayscale(1) contrast(1.1) brightness(1.05);
+}
+```
+
+**Mix-blend-mode approach (richer control, requires stacking context)**
+
+```html
+<!-- The image sits in a container. A pseudo-element with the brand colour overlays
+     it via mix-blend-mode: color, which replaces the image's hue while preserving
+     luminosity. This produces a true two-stop duotone. -->
+<div class="duotone-blend">
+  <img src="image.jpg" alt="[description]" class="duotone-blend__image">
+</div>
+```
+
+```css
+.duotone-blend {
+  position: relative;
+  isolation: isolate; /* required for mix-blend-mode to work correctly */
+  overflow: hidden;
+}
+
+.duotone-blend__image {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  filter: grayscale(1) contrast(1.1); /* desaturate first */
+}
+
+/* The colour overlay uses mix-blend-mode: color to apply the brand hue
+   to the greyscale image below. */
+.duotone-blend::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background-color: var(--color-brand-primary, #1a4d8f);
+  opacity: 0.6; /* lower = more greyscale visible; higher = more brand colour */
+  mix-blend-mode: color;
+  pointer-events: none;
+}
+```
+
+## Linter notes
+
+- Duotone treatments applied in the flagged SLOP-GRADIENT hue bands (hue-rotate values
+  that produce indigo/violet or purple/pink tones) carry the same `SLOP-GRADIENT` risk as
+  mesh gradients in those bands. The treatment is applied to an image rather than a
+  background, so the `SLOP-GRADIENT` rule does not fire directly — but the aesthetic
+  outcome (a purple-tinted image on a purple gradient background) reads as the same AI-
+  default visual language. Record the colour choice if it lands in those bands.
+
+- The `mix-blend-mode: color` approach requires the parent to have `isolation: isolate` set.
+  Without the stacking context, the blend mode may affect elements outside the intended
+  container. Always verify the containment before shipping.
+
+- Duotone treatments reduce effective contrast for users with colour vision deficiencies.
+  After applying a treatment, run `omd check` to verify that any text overlaid on the
+  duotone image still meets 4.5:1 contrast. The treatment changes the image's luminance
+  distribution; a dark duotone image may produce lower contrast than the untreated version.
+
+## Do not combine with
+
+**noise-grain-texture.md at opacity above 8%** — grain over a duotone image creates
+triple-layered processing (image → duotone filter → grain overlay) that produces an
+image that reads as heavily processed rather than treated. Light grain (3–5%) over a
+duotone can add material quality; heavy grain obscures the treatment.
+
+**css-illustration-primitives.md on the same visual zone** — a duotone image and a CSS
+blob in the same section compete for the decorative register. The treated image is itself
+the art-directed visual; a blob behind or over it dilutes its effect.
+
+**Accurate-colour product contexts** — if the image is a product photograph and the
+user needs to see the actual colour of the product, do not apply a duotone treatment.
+The treatment overrides the image's colour story with the brand's, which is correct
+for editorial and brand contexts and incorrect for product accuracy contexts.

package/core/graphics/gradient-mesh.md

@@ -0,0 +1,178 @@
+# Gradient mesh backgrounds
+
+A gradient mesh layers multiple `radial-gradient()` declarations on a single element,
+producing a soft, multi-source light field that reads as dimensional rather than flat.
+Unlike a simple two-stop linear gradient, a mesh gradient has no visible direction — it
+pools and diffuses, the way light fills a room through multiple windows. The technique
+is CSS-only: no SVG, no image file, no canvas.
+
+## When it earns its place / When it does not
+
+Condition: the page has large flat sections that read as too digital — blank backgrounds
+that feel like developer defaults rather than design decisions. A mesh gradient makes
+the surface a presence without adding visual weight that competes with the content.
+Showpiece and confident registers both benefit: the mesh adds depth to the hero or a
+full-bleed section background without introducing imagery or illustration overhead.
+`expressive.md` on grain texture (the natural companion to mesh): "Flat backgrounds or
+smooth gradients that read as too digital — noise adds the tactile quality that solid
+fills lack." A mesh gradient addresses the same problem at the colour level before grain
+addresses it at the texture level.
+
+Condition against: pages where the brand palette is already active and saturated — adding
+a mesh to a high-saturation layout creates a chromatic argument between the mesh and the
+content. Any dark section where the mesh's colour pools compete with text legibility;
+verify 4.5:1 contrast between every text element and the mesh behind it at every mesh
+position, not just the average. And for AI-generated-looking aesthetics: see the linter
+notes below — specific hue combinations trigger `SLOP-GRADIENT` because they are the
+statistical mean of AI design output, not a brand decision.
+
+## Parameters
+
+```css
+:root {
+  /* Each radial gradient defines one light source in the mesh.
+     Three to five sources produce a convincing mesh; more than six
+     tends toward muddiness rather than depth.
+     Position each source at a different corner or edge — distribute
+     them to avoid clustering. */
+
+  /* Source 1: warm anchor — primary brand hue */
+  --mesh-source-1-color: hsl(220deg 60% 70% / 0.8);
+  --mesh-source-1-pos: 0% 0%;
+  --mesh-source-1-size: 60% 60%;
+
+  /* Source 2: cool contrast — secondary or complementary hue */
+  --mesh-source-2-color: hsl(280deg 50% 60% / 0.6);
+  --mesh-source-2-pos: 100% 0%;
+  --mesh-source-2-size: 50% 50%;
+
+  /* Source 3: neutral or analogous midground */
+  --mesh-source-3-color: hsl(200deg 40% 80% / 0.5);
+  --mesh-source-3-pos: 50% 100%;
+  --mesh-source-3-size: 70% 50%;
+
+  /* Base fill colour: what shows where the gradients do not reach.
+     Should be the lightest or darkest value in the palette, never a mid-tone.
+     Mid-tone bases with mid-tone gradients produce uniform murk. */
+  --mesh-base: #f0f0ee;
+}
+```
+
+## Implementation
+
+```css
+/* ── CSS-only mesh gradient ──────────────────────────────────────────────── */
+.mesh-bg {
+  background-color: var(--mesh-base);
+  background-image:
+    radial-gradient(
+      ellipse var(--mesh-source-1-size) at var(--mesh-source-1-pos),
+      var(--mesh-source-1-color),
+      transparent
+    ),
+    radial-gradient(
+      ellipse var(--mesh-source-2-size) at var(--mesh-source-2-pos),
+      var(--mesh-source-2-color),
+      transparent
+    ),
+    radial-gradient(
+      ellipse var(--mesh-source-3-size) at var(--mesh-source-3-pos),
+      var(--mesh-source-3-color),
+      transparent
+    );
+  /* No background-blend-mode needed for basic mesh — the stacking of transparent
+     gradients handles the blending. background-blend-mode: multiply or screen can
+     intensify the effect but is harder to calibrate for legibility. */
+}
+
+/* ── Full-section mesh hero ──────────────────────────────────────────────── */
+.mesh-hero {
+  min-height: 100svh;
+  display: flex;
+  align-items: flex-end;
+  padding: var(--space-page-margin, 5vw);
+}
+
+/* ── Mesh as a positional decorative element (not full-bleed) ─────────────── */
+/* Place the mesh behind specific components without covering the entire background. */
+.mesh-spot {
+  position: relative;
+  isolation: isolate; /* creates stacking context for the pseudo-element mesh */
+}
+
+.mesh-spot::before {
+  content: '';
+  position: absolute;
+  inset: -20%;
+  z-index: -1;
+  border-radius: 50%; /* circular mesh pool reads as ambient light source */
+  background-image:
+    radial-gradient(
+      ellipse 80% 80% at 30% 40%,
+      var(--mesh-source-1-color),
+      transparent
+    ),
+    radial-gradient(
+      ellipse 60% 60% at 70% 60%,
+      var(--mesh-source-2-color),
+      transparent
+    );
+  filter: blur(40px); /* blur softens the ellipse edges for a true mesh feel */
+  pointer-events: none;
+}
+```
+
+```html
+<!-- Full-section mesh: -->
+<section class="mesh-bg mesh-hero">
+  <h1>Content over the mesh.</h1>
+</section>
+
+<!-- Spot mesh behind a card or feature: -->
+<div class="mesh-spot">
+  <div class="card">Content gains an ambient glow.</div>
+</div>
+```
+
+## Linter notes
+
+The `SLOP-GRADIENT` rule fires on the following hue combinations because they are the
+statistical signature of AI-generated design output — the default gradient every model
+reaches for when asked to "make it look good":
+
+- **Indigo → violet** (hue range 240–290deg): the single most overused gradient in AI
+  design. Any `background: linear-gradient` or `radial-gradient` whose two dominant
+  stops land in this band fires `SLOP-GRADIENT`. If the brand genuinely uses indigo and
+  violet, the decision must be recorded in `omd decision` with the brand's hex values
+  and the reference that supports the choice.
+
+- **Purple → pink** (hue range 280–330deg): a secondary AI-default combination.
+  Frequently appears in "premium" and "AI product" contexts. Same rule applies.
+
+- **Electric blue → teal** (hue range 190–240deg): common in tech startup contexts.
+  Fires `SLOP-GRADIENT` in these ranges at saturation above 70%.
+
+The mesh gradient technique is not itself flagged — layered radial gradients at lower
+saturation using the brand's actual hue values are expected and correct. The linter
+fires on the specific hue bands above, not on mesh gradients per se. A mesh using
+`hsl(30deg 40% 80%)` (warm sand) and `hsl(170deg 30% 75%)` (cool sage) is clean.
+A mesh using `hsl(260deg 80% 60%)` and `hsl(310deg 70% 60%)` fires the rule.
+
+**The test**: before committing a mesh gradient, read the HSL values of the dominant
+stops. If both stops land in the flagged hue bands, record the brand reason or choose
+a different hue combination. The mesh technique is sound; the hue selection is the risk.
+
+## Do not combine with
+
+**noise-grain-texture.md at opacity above 10%** — both techniques add depth signals to
+the background. Grain over a mesh is appropriate at 3–6% opacity; above that, the
+combined texture reads as a rendering artifact, not a design decision.
+
+**svg-geometric-patterns.md behind the same element** — a pattern and a mesh applied
+to the same background produce competing spatial readings (structured geometry and
+ambient light) that cancel each other's signal.
+
+**A mesh where text contrast cannot be verified at all mesh positions** — mesh gradients
+are not uniform; the lightest point and the darkest point may differ enough that text
+legible over one is illegible over the other. Always verify contrast at the gradient's
+lightest zone for dark text and its darkest zone for light text.

package/core/graphics/noise-grain-texture.md

@@ -0,0 +1,150 @@
+# Noise / grain texture
+
+A grain texture overlays a fine noise pattern — generated by an SVG `feTurbulence` filter
+embedded as a data URI — on a background at low opacity. The effect adds tactile quality
+that flat fills and smooth gradients lack: the surface reads as material rather than
+rendered, as though light is interacting with a slightly imperfect field. At the correct
+opacity (3–8%), the grain reads as depth. Above 15% it reads as a compression artifact
+or a low-resolution encoding error.
+
+The technique was documented by Lea Verou and CSS-Tricks: "Grainy Gradients" —
+`feTurbulence` as a composited texture layer, reducing gradient banding on smooth surfaces.
+`expressive.md` cites this directly: "The CSS-Tricks SVG filter technique (an feTurbulence
+filter composited at low opacity over a background) adds texture without weight."
+
+## When it earns its place / When it does not
+
+Condition: flat backgrounds or smooth mesh gradients that read as too digital. Grain most
+visibly earns its place over mesh gradients, where it reduces the banding that appears on
+smooth colour transitions on LCD displays. Single-colour sections that feel like developer
+backgrounds — white, off-white, near-black — also benefit: the grain makes the surface a
+material decision rather than a default. Showpiece and confident registers. Hero sections.
+Feature backgrounds. Sections where the surface itself should read as considered.
+
+Condition against: over photography or video — grain is redundant over natural image
+texture and reduces legibility. On text at any size — grain under type at small sizes
+degrades the contrast relationship and makes text harder to read. At high opacity on any
+element — above 15%, grain reads as an encoding problem. Any product context where
+surface cleanliness is a trust signal (healthcare, finance, enterprise tooling) — grain
+introduces noise that reads as imprecision.
+
+## Parameters
+
+```css
+:root {
+  /* Grain opacity.
+     3–5%: subtle, reads as material quality on close inspection.
+     6–8%: visible grain that reads as deliberate texture.
+     9–15%: strong texture, suitable for decorative elements only.
+     Above 15%: renders as compression artifact. Do not use. */
+  --grain-opacity: 0.05;
+
+  /* Turbulence frequency.
+     Low values (0.4–0.6): coarse grain, reads as film grain.
+     High values (0.7–0.9): fine grain, reads as paper texture.
+     Values above 1.0: noise too fine to read as texture — invisible. */
+  --grain-frequency: 0.65;
+
+  /* Number of octaves: detail layers in the noise function.
+     2: smooth, gentle grain.
+     4: more complex, film-like texture.
+     Values above 6: significant render cost; diminishing visual returns. */
+  --grain-octaves: 4;
+}
+```
+
+## Implementation
+
+The grain is an SVG filter rendered as a data URI and applied as a `::after` pseudo-element.
+This approach requires no external file, no JavaScript, and works in all modern browsers.
+
+```css
+/* ── Grain texture as a pseudo-element overlay ────────────────────────────── */
+.grain {
+  position: relative;
+  isolation: isolate; /* ensures the pseudo-element stacks correctly */
+}
+
+.grain::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 1; /* above the background, below the content */
+  pointer-events: none;
+  user-select: none;
+  opacity: var(--grain-opacity);
+
+  /* The SVG feTurbulence filter as a data URI.
+     fractalNoise: produces organic grain (vs turbulence which produces cloud-like noise).
+     seed: change this value to produce a different grain pattern on different sections. */
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='300'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='300' height='300' filter='url(%23noise)'/%3E%3C/svg%3E");
+  background-size: 300px 300px; /* tile size: smaller = finer visual grain */
+  background-repeat: repeat;
+}
+
+/* ── Content must sit above the grain pseudo-element ─────────────────────── */
+/* Any direct children of .grain that hold readable content need z-index: 2
+   to layer above the ::after grain overlay. */
+.grain > * {
+  position: relative;
+  z-index: 2;
+}
+```
+
+```html
+<!-- Apply .grain to a section to add texture to its background. -->
+<section class="mesh-bg grain">
+  <div class="section-content">
+    <h2>The surface is now material.</h2>
+  </div>
+</section>
+
+<!-- Or to a specific card: -->
+<div class="card grain">
+  <h3>Card with grain texture.</h3>
+</div>
+```
+
+**Adjusting the grain:** To change the frequency or octave count without editing the data
+URI, modify the SVG string in the background-image. The key parameters are `baseFrequency`
+(mapped to `--grain-frequency`) and `numOctaves` (mapped to `--grain-octaves`). The data
+URI must be regenerated when these values change — they are baked into the string, not
+CSS variables. Consider a small build step or a Sass function if multiple grain densities
+are needed.
+
+**Performance:** The `feTurbulence` filter renders in the browser at paint time. On modern
+hardware this is imperceptible. On older mobile hardware with large grain tiles, the
+initial render may take 10–20ms. Tile the grain at 300×300px rather than applying it as
+a full-viewport element to keep the painted area bounded. The `stitchTiles: stitch`
+parameter ensures the tile seams are invisible at any scale.
+
+## Linter notes
+
+- Grain opacity above 15% (`--grain-opacity > 0.15`) is a defect. At this level the
+  texture reads as a rendering error rather than a design decision. The `omd check`
+  system cannot detect opacity set inside a CSS variable directly, but a visual check
+  of any rendered surface should reject opacity this high.
+
+- Grain applied directly to text containers degrades legibility. The grain pseudo-element
+  must be layered below content (`z-index` of the pseudo-element below content children).
+  Verify by running `omd check` — the contrast checker measures effective contrast
+  between text and the painted background, including overlaid grain.
+
+- A grain-only texture on a white background with no other design decisions is not a
+  texture choice — it is an avoidance of a background decision. Grain earns its place
+  as a layer over a considered colour, not as a substitute for one.
+
+## Do not combine with
+
+**gradient-mesh.md at grain opacity above 8%** — grain at 3–6% over a mesh gradient is
+the canonical combination; it reduces banding and adds material quality. Above 8%, the
+two textures begin to fight: the mesh's smooth colour transition and the grain's random
+noise produce a muddy middle ground that reads as neither.
+
+**drop-shadow on the same element** — grain texture and heavy box shadows are competing
+depth signals. Both communicate material weight; using both says the element is both
+thick with grain texture and elevated with shadow, which is contradictory. Choose one.
+
+**photography or video backgrounds** — grain is a substitute for natural surface texture,
+not a complement. Real photographic grain and synthetic `feTurbulence` grain at the same
+opacity produce visual interference, not depth.

package/core/graphics/placeholder-policy.md

@@ -0,0 +1,185 @@
+# Placeholder policy
+
+A grey box is a design defect: it defers a decision the build must make before shipping,
+and it ships as an admission that nobody decided what belongs here. A placeholder that
+reaches production — as a grey rectangle, a "Coming soon" block, or a `background: #ccc`
+div — is not a placeholder anymore. It is content that says the design is unfinished.
+
+This recipe defines what to do instead. For every situation where a grey box would appear,
+there is a deliberate alternative: a typographic block, a pattern fill, or a generated
+gradient. Each carries more information about the intended content than a grey rectangle
+and requires the designer to make a decision — which is the point.
+
+## When it earns its place / When it does not
+
+Condition: any section where final imagery is not available at build time. Team photos
+not yet shot. Product screenshots not yet captured. User-generated content zones in an
+empty state. Hero sections awaiting final photography. The placeholder policy applies
+to all of these: each one must ship as a deliberate, designed alternative to the missing
+image, not as a grey box.
+
+The placeholder policy is a forcing function. Deciding what to use instead of the grey
+box requires answering: "What does this space communicate when the real content is
+absent?" A typographic block communicates the category and scale of the expected content.
+A pattern fill communicates that the space is structural, not content-bearing. A gradient
+communicates the colour register of the expected content.
+
+Condition against: this policy does not apply to actual content loading states (skeleton
+screens during data fetch are correct — see `core/theory/layout.md` on loading states).
+The policy targets design-time decisions, not runtime states.
+
+## Parameters
+
+```css
+:root {
+  /* Typography placeholder: the font size should approximate the heading or body
+     size of the expected content, so the layout holds its rhythm even without
+     the real content. */
+  --placeholder-type-size: var(--text-xl, 1.25rem);
+  --placeholder-type-color: var(--text-secondary, rgba(0,0,0,0.35));
+
+  /* Pattern placeholder: same parameters as svg-geometric-patterns.md.
+     Use the same pattern token so the placeholder and a deliberate pattern
+     application are visually consistent. */
+  --placeholder-pattern-opacity: 0.06;
+
+  /* Gradient placeholder: a single-hue gradient using the brand palette.
+     Not a generic grey → white; the brand colour in a light wash is more
+     informative and more finished than any grey value. */
+  --placeholder-gradient-start: hsl(var(--hue-brand, 220deg) 20% 95%);
+  --placeholder-gradient-end: hsl(var(--hue-brand, 220deg) 10% 88%);
+}
+```
+
+## Implementation
+
+**Option 1: Typographic block** — for content zones that will hold a heading, a body
+paragraph, or a feature statement. The typographic placeholder communicates scale and
+category without pretending to be real content.
+
+```html
+<!-- Instead of: <div class="hero-image" style="background:#ccc; height:400px;"></div> -->
+
+<!-- Use: a typographic placeholder that holds the layout and signals intent. -->
+<div class="placeholder placeholder--type" role="img" aria-label="Hero image: [brief description of intended content]">
+  <span class="placeholder__label">Hero image</span>
+  <span class="placeholder__detail">Photography: [subject or concept]</span>
+</div>
+```
+
+```css
+.placeholder--type {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* Match the dimensions of the expected content exactly.
+     If the hero image is 100vw × 60vh, this placeholder is too. */
+  min-height: 60vh;
+  background-color: var(--placeholder-gradient-start);
+  background-image: linear-gradient(
+    135deg,
+    var(--placeholder-gradient-start),
+    var(--placeholder-gradient-end)
+  );
+  border-radius: var(--radius-section, 0);
+  gap: var(--space-2, 0.5rem);
+}
+
+.placeholder__label {
+  font-size: var(--placeholder-type-size);
+  font-weight: var(--weight-medium, 500);
+  color: var(--placeholder-type-color);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.placeholder__detail {
+  font-size: var(--text-sm, 0.875rem);
+  color: var(--placeholder-type-color);
+  opacity: 0.7;
+}
+```
+
+**Option 2: Pattern fill** — for content zones that are structural (a card image slot,
+a sidebar graphic zone) where the space needs visual weight but no textual label.
+
+```html
+<div class="placeholder placeholder--pattern" role="img" aria-label="[describe intended content]"></div>
+```
+
+```css
+.placeholder--pattern {
+  /* Dimensions match the intended content zone. */
+  min-height: 200px;
+  background-color: var(--surface-subtle, #f5f5f3);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='1' fill='rgba(0%2C0%2C0%2C0.12)'/%3E%3C/svg%3E");
+  background-size: 24px 24px;
+  border-radius: var(--radius-card, 8px);
+}
+```
+
+**Option 3: Generated gradient** — for hero and full-bleed sections where the missing
+image is photographic and the gradient conveys the intended colour register.
+
+```html
+<section class="placeholder placeholder--gradient placeholder--hero" role="img" aria-label="[describe intended imagery]">
+  <div class="section-content">
+    <!-- Section content sits above the gradient placeholder background. -->
+  </div>
+</section>
+```
+
+```css
+.placeholder--gradient {
+  background-image: linear-gradient(
+    160deg,
+    var(--placeholder-gradient-start) 0%,
+    var(--placeholder-gradient-end) 100%
+  );
+}
+
+.placeholder--hero {
+  min-height: 100svh;
+}
+```
+
+**Decision rule:** choose by content type and visibility:
+- The expected content is a heading or copy block → **typographic block**.
+- The expected content is an image in a card, thumbnail, or secondary zone → **pattern fill**.
+- The expected content is a full-bleed hero or section background photo → **generated gradient**.
+- When in doubt between pattern and gradient: gradient, because it communicates the
+  colour register of the eventual photography.
+
+## Linter notes
+
+- A `background: #ccc`, `background: #d9d9d9`, `background: grey`, or any near-neutral
+  background on a container that has explicit height but no content is the signal the
+  `omd check` system identifies as a potential placeholder. The check looks for elements
+  with fixed-height, no semantic content, and a near-neutral background. If a legitimate
+  design element fires this check, record the reason with `omd decision`.
+
+- Generated gradient placeholders that land in the SLOP-GRADIENT hue bands (indigo–violet,
+  purple–pink) should use the brand's actual hue variable (`var(--hue-brand)`) rather than
+  a hardcoded hue. The placeholder inherits the brand palette, so if the brand changes,
+  the placeholders update automatically.
+
+- Every placeholder element must have a meaningful `aria-label` that describes the
+  intended content. A placeholder without an accessible description is both a design
+  defect and an accessibility failure — screen readers announce it as an unlabelled image.
+
+## Do not combine with
+
+**Actual content** — when the real image or content is available, use it. The placeholder
+policy does not mean "use a gradient everywhere instead of photography." Photography,
+illustration, or purposeful imagery always supersedes a placeholder when it exists.
+
+**Lorem ipsum text** — text placeholders are governed by the same principle: `hand.agent.yaml`
+states "Placeholder copy is a defect. 'Lorem ipsum' and 'Your content here' never ship."
+A typographic block that serves as an image placeholder is acceptable; a paragraph of
+lorem ipsum text is not. If body copy is absent, use structural whitespace or a typographic
+label indicating the content category, never placeholder prose.
+
+**More than one placeholder type in the same layout zone** — choosing between typographic,
+pattern, and gradient means choosing one. Stacking a pattern fill and a gradient on the
+same placeholder element produces a background system, not a placeholder decision.