@@ -31,7 +31,8 @@ The content base (counts are CI-enforced against README.md and the manifest):
   API contract with deterministic checks, exit non-zero on failure, and
   optionally render a still via `--output`. Each is executed headless on
   Blender 4.5 LTS and 5.1 by `blender-smoke.yml`; its render ships in the
-  site gallery. Anatomy and authoring rules: copy `examples/bmesh-gear/`.
+  site gallery. Anatomy and authoring rules: copy `examples/bmesh-gear/`;
+  the render look is specified in `docs/VISUAL-STYLE.md`.
 
 ## Repository structure
 
 
@@ -91,6 +91,7 @@ gallery's source of truth. When authoring a new one, copy the anatomy of
 wire all of: gallery.json entry, `.cursor-plugin/plugin.json` examples array (CI-gated),
 a `blender-smoke.yml` step, a README gallery row, hero webp (1280×720) in
 `docs/gallery/assets/` + preview webp (1200×675), then run `python scripts/build_gallery.py`.
+Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`.
 
 ## Development Workflow
 
 
@@ -53,7 +53,7 @@ that actually runs. Browse them in the
 <table>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/swatch-grid/"><img src="examples/swatch-grid/preview.webp" alt="Swatch grid: a row of six shaded spheres - gold and copper metals, red and blue plastics, an emissive orange, and a matte white - on a reflective studio floor, rendered with EEVEE" /></a>
+<a href="examples/swatch-grid/"><img src="examples/swatch-grid/preview.webp" alt="Swatch grid: a three-by-two grid of shaded spheres - polished gold and brushed copper metals, red and blue plastics, an emissive orange, and a matte white - against a dark studio backdrop, rendered with EEVEE" /></a>
 </td>
 <td valign="middle">
 
@@ -193,7 +193,7 @@ verts = 72, faces = 54, and `Set Material` carries the lime accent.
 </tr>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/shape-key-blend/"><img src="examples/shape-key-blend/preview.webp" alt="Shape-key blend: a violet truncated pyramid on a dark studio floor, lifted and flared by a relative Tall shape key at value 0.5" /></a>
+<a href="examples/shape-key-blend/"><img src="examples/shape-key-blend/preview.webp" alt="Shape-key blend: three violet blocks on a dark studio floor showing a relative Tall shape key at values 0, 0.25, and 0.5 - plain cube to lifted, flared truncated pyramid, left to right" /></a>
 </td>
 <td valign="middle">
 
 
@@ -0,0 +1,77 @@
+# Gallery Visual Style
+
+The spec for every example render that ships in the gallery. New examples must
+conform; deviations are defects. Calibration references: `armature-bend`,
+`color-attribute-wheel`, `grease-pencil-rosette`, `compositor-glare`,
+`damped-track-aim`, `parent-inverse-orrery`.
+
+## The look in one sentence
+
+A dark staged studio — near-black floor and back wall, one shaped warm key, a
+warm light pool raking the backdrop — with a saturated hero subject filling
+the frame.
+
+## Color management
+
+- `scene.view_settings.view_transform = 'Standard'`, always, with a comment.
+  AgX (the 4.x/5.x default) desaturates hero materials toward pastel and
+  lifts the stage toward grey — the washed look of the pre-audit gallery
+  traces to renders that never set a transform.
+- Standard does not compress highlights: tune light energies so nothing
+  clips. If a region reads pure white at full size, the key is too hot.
+
+## Stage
+
+- Floor: 30-unit `create_grid` plane. Wall: a copy at `y ≈ 7–9`, rotated 90°
+  about X. Both share one Principled material:
+  `Base Color (0.03, 0.032, 0.037)`, `Roughness 0.7`.
+- World background: `(0.02, 0.021, 0.025)`.
+- The floor/wall seam is acceptable only where it falls into shadow; never
+  let it cross the subject.
+
+## Lighting (all AREA lights)
+
+- **Key** — warm white `(1.0, 0.96, 0.9)`, upper left, ~`(-4, -5, 6)`,
+  size 4–6, 300–700 W depending on subject albedo. It must shape: visible
+  falloff across the subject, a readable cast shadow.
+- **Fill** — cool `(0.75, 0.85, 1.0)`, low right, size ~9, ~100 W. Just
+  enough that shadow sides stay legible; if the image looks flat, the fill
+  is too strong.
+- **Rim** — cool `(0.6, 0.78, 1.0)`, behind, 200–400 W, to lift silhouettes
+  off the backdrop.
+- **Wedge** — the signature: warm `(1.0, 0.76, 0.5)`, 200–500 W, size 5–7,
+  raking the back wall so a soft pool of light sits behind the subject.
+  Place it **between the subject and the wall**. A grazing area light draws
+  a hard terminator line across any flat surface it skims — if a stray
+  bright band crosses the subject, a light is grazing it.
+
+## Materials
+
+- Hero materials are designed, never Principled defaults: saturated base
+  colors, roughness chosen (0.3–0.6 glossy, 0.7+ matte), optional faint
+  emission (~0.1) when the subject carries color data that must read exactly.
+- Surfaces that display flat color data (attribute fills, pixel buffers) go
+  fully matte: `Specular IOR Level = 0`, otherwise the wall/floor horizon
+  reflects as a line across the face.
+
+## Framing
+
+- The subject fills roughly 70–90 % of the frame in at least one axis.
+  Nothing that matters may touch or cross the frame edge; no featureless
+  quadrant of empty wall or floor.
+- Camera: 45–55 mm lens, slightly above subject height, aimed with a
+  `TRACK_TO` constraint at an empty on the subject — a chosen angle, not the
+  default. Flat subjects present toward the camera (lean or tilt them);
+  progressions read left to right.
+- The image must still read in under a second at thumbnail scale, and it
+  must witness the API: if the contract failed, the render should visibly
+  break.
+
+## Output
+
+- Render 1280×720 PNG (`taa_render_samples`/`cycles.samples` 32–64).
+- Gallery assets: hero webp 1280×720 and preview webp 1200×675, quality 85
+  (load the PNG in Blender, `save(filepath=..., quality=85)`, `scale()` for
+  the preview — this preserves pixels without re-applying color management).
+- After touching any example: `python scripts/build_gallery.py`, and update
+  the README gallery-row alt text if the composition changed.