---
name: "convention-sanity"
type: convention
description: Conventions for Sanity CMS in Aled's system — projects in scope, the Studio version baseline and what the current major changed, schema setup, naming standards, field UX, and deployment. Read before any operation that involves Sanity content models or the Studio, and before upgrading a Studio across a major version. Grown as the conventions solidify.
license: CC BY-NC-SA 4.0
---

# convention-sanity

How Sanity is used in Aled's system. Stub — grown as the conventions solidify.

## Role

Sanity is the headless CMS. Content editors (Aled, clients) use Sanity Studio; delivery code fetches content via GROQ queries. The schema and Studio live inside the delivery repo; agents only modify schema files, never the Sanity dataset directly.

## Projects in scope

| Sanity project | Delivery repo | Studio path |
| -- | -- | -- |
| aledpritchard-com | assoc-one/aledpritchard-com | /studio |
| meirionpritchard-com | assoc-one/meirionpritchard-com | /studio |

## Studio version — the baseline, and what v6 changed

**Baseline: Sanity Studio v6**, released 11 June 2026. APIs, components, and configuration differ significantly across majors, so a v3-era pattern carried into a v6 config is not a style difference — it is a defect. Read the Studio's own `package.json` before assuming a version; this file states the baseline, the repo states the fact.

The v6 changes that alter how an agent works, rather than what a changelog would list:

- **Node 22.12 is the minimum** — Node 20 reached EOL in April 2026. This bites at local dev and CI/build only; a deployed Studio is unaffected. The failure lands at install or build time, so check the runtime version before diagnosing a broken build as a schema fault.
- **`auth.providers` now replaces the built-in providers by default.** `mode: 'replace'` is removed and `mode: 'append'` is gone. Listing a provider in `sanity.config.ts` therefore *drops* the built-ins rather than adding to them, which locks editors out of a Studio that still builds and deploys cleanly. Use the callback form to append. Treat any change to `auth.providers` as consequential — confirm it with Aled before it ships, the same way a field removal is confirmed.
- **The default search strategy moved from `groqLegacy` to `groq2024`** — full Portable Text search, wildcards, phrases, and negation. Results and ordering shift as a consequence. A changed result set after an upgrade is the new strategy working, not a data problem; do not go looking for corruption in the dataset.
- **React strict mode is on by default in development.** Effects double-invoke in dev where they did not before, surfacing real re-entrancy bugs that were previously masked. `reactStrictMode: false` in `sanity.cli` opts out — use it to unblock a diagnosis, never to quieten a fault it exposed.
- **A plugin must declare `^6.0.0` in its peer deps or `npm install` fails.** `--legacy-peer-deps` is a stopgap that makes the install pass while leaving the incompatibility live — reach for it to keep moving, never to close the ticket. Check plugin readiness at `are-we-v6-yet.sanity.dev` *before* starting an upgrade, not after the install breaks.
- **An auto-updating Studio still needs a manual bump to `^6.0.0`.** Auto-updates do not cross a major that carries runtime behaviour changes, so a Studio left alone sits on the old major indefinitely while reading, to anyone who knows it auto-updates, as current. "It auto-updates" is not evidence of the version.

Builds are 2–9× faster on Vite 8, with smaller bundles from improved tree shaking — no agent action follows from it.

## A version reference goes stale silently

This file said "Sanity Studio v3 — not v2" while v6 was live, and sat two majors behind for weeks. Every agent reading it in that window worked from a baseline that had been wrong since release, and nothing anywhere reported it (APP-416).

That is the general shape, not a Sanity quirk: **a version claim in a convention is the one kind of statement that becomes false without anybody touching it.** A wrong rule gets caught the moment it is followed; a stale version reference is followed successfully, right up until it isn't.

There is no self-check to add here, and adding one would be theatre — a file cannot notice the world moved. The mechanism already exists: **`skill-optimisation-review` Pass 1, the docs-driven tooling pass**, reads each tool's current documentation and changelog and compares it against our `convention-*` files precisely to catch this drift. So the obligation runs outward, not inward — every version claim in this file is that pass's to catch, and this is the worked case for why the pass has to actually run against live docs rather than be skipped or degraded when a run lacks web access. Two habits follow for anyone editing here:

- **Date a version baseline when you set it**, so the next reader can weigh how old the claim is rather than trust it.
- **Say what the version governs**, not just what it is — a bare number gives a reader nothing to check against the repo.

## Schema setup — adding a new document type or field

1. Create a schema file in `src/sanity/schemas/` (one file per document type, named to match the type, e.g. `project.ts`).
2. Add the schema to the index at `src/sanity/schemas/index.ts` (or `schema.ts` — check the project).
3. Test the schema locally by running the Studio (`npm run dev` and navigating to `/studio`).
4. Commit and push; the Studio auto-deploys on merge to main via Vercel.

**Adding or changing a field on a block — the fixed downstream order.** The four steps above cover registering a schema. A new or changed *field* on an existing block touches seven places downstream of the schema, and they are done in this order rather than in whatever order the files happen to be opened:

1. **Schema** — the field on the block's schema type.
2. **GROQ projection** — add the field to every projection that reads the block. Omit this and the field exists in the Studio, is editable, saves, and is simply absent at runtime.
3. **Types** — the generated types *and* any hand-written type for the block. Both, not whichever one the compiler complains about.
4. **Mapper** (`mapProject.ts`, or the project's equivalent) — including **a default for content authored before the field existed.** The default preserves the current rendered behaviour of pre-existing content, so adding a field never restyles already-published content. That is the decided answer, not a per-field judgement; do not re-open it.
5. **Component** — the render.
6. **Storybook `argType`** — the control, so the new state is reachable in isolation (`convention-storybook`).
7. **`npm run typegen`** — run it, and **commit the regenerated files** in the same change.

The order is worth stating because skipping a step does not fail loudly. A missing projection reads to an editor as a field that "doesn't work". A missing mapper default silently changes how live content renders. Uncommitted typegen output breaks the next person's build rather than this one's. None of the three surfaces as an error at the point it is made.

(Worked instances: `split` block caption on/off and label bar — A1-472, A1-474; image-asset and text blocks' label bars mirroring `split` — A1-489, A1-490. Surfaced 2026-09-22 on `meirionpritchard-com` — APP-1663.)

## Naming

- **Document types:** camelCase — e.g. `project`, `caseStudy`.
- **Field names:** camelCase — e.g. `title`, `defaultRepsOrTime`.
- **Slugs** (when the type is a page): kebab-case, generated from the title field.
- **Dataset:** `production` (the default). Never reference another dataset in production code.
- **Document ids:** kebab-case, and **never with a dot in them** — `show-hackney-central`, not `show.hackney-central`. Where a brief or a ticket specifies an id shape, the dot is the character to change before anything is written, because a dotted id does not fail a token-free read, it empties it: a public dataset's unauthenticated query returns no such document and reports no error, so a site that reads without a token renders blank and healthy. A type-ish prefix is fine — a hyphen separates it as readably as a dot does. **Unverified premise, and only this one:** that Sanity treats any dotted id as private is **reported** (the builder's read during the migration, not checked against Sanity's own documentation from this surface), so the rule stated here is the **shape** — do not put a dot in a document id — rather than the mechanism, and it holds whichever way the mechanism turns out. (Worked case, **reported**: the A1-750 migration script for the Hackney Showroom CMS test, 2026-10-21 — the brief and the ticket both specified `show.<slug>`; the ids were changed to `show-<slug>` during the build and the change logged in `a1-hackneyshowroom.log-decisions.2026-W43`. The site in that test reads without a token by design, so the dotted ids would have produced an empty site with no error. One instance, caught at build time only because the builder already knew the rule. APP-2531.)

## Field UX — input type and copy

Which input type a field uses, and how its description and label read, drift per editor and per block unless stated. These rules keep blocks consistent and give copy a canonical home.

**Input-type picker.** Choose the control by the shape of the value:

| Input type | Use when |
| -- | -- |
| **Radio** | 2–5 fixed, mutually exclusive options, all worth showing at once |
| **Dropdown** | 6+ options, or a set that will grow |
| **Toggle** | a single true on/off with unnamed states (on vs off) |
| **Array + list** | multi-select — the value is several options at once |
| **Reference** | the value is another document |
| **Custom** | last resort, when none of the above fits |

- **Fixed crossover:** radio up to 5 options; dropdown at 6+.
- **Radio direction:** horizontal for 2–3 short labels; vertical for 4–5.
- **Two named states are a radio, not a toggle.** A toggle is only for a single unnamed on/off; the moment both states have names (e.g. `Fixed` / `Fluid`), it is a two-option radio.

**Pattern — a per-block toggle gating a `hidden` field.** Named here so it is cited rather than reinvented. Where a block gains optional content, the shape is a **boolean toggle field paired with the content field it controls**, the content field `hidden` unless the toggle is on. Three properties make it the pattern and not a local choice:

- **Declared per block, not DRY'd into a shared schema type.** Sanity has no type inheritance here, so a shared type buys nothing and costs a layer of indirection between the editor's block and the field definition. Repeating the pair on each block is correct, not duplication to be cleaned up.
- **The toggle is named for what it turns on**, matching its content field — `showLabel` / `label`, `captionEnabled` / `caption`. A reader of the schema can see the pair without reading the `hidden` predicate.
- **The mapper defaults it to the behaviour pre-existing content already has** (step 4 of the downstream order under *Schema setup*), so shipping the schema change does not restyle live content.

**Cite the most recent shipped precedent rather than re-deriving the pattern** — from first principles, or from decision-log prose. The precedent is `split`'s `showLabel` / `label` pair, **decision D053** (A1-474). Instances: `split` caption on/off and label bar (A1-472, A1-474); image-asset and text blocks' label bars, built to mirror `split` (A1-489, A1-490). A new pair points at the latest of these; it does not restate the reasoning. (APP-1663.)

**Copy.** Write field text at the right level:

- **Description** says what the field is *for*, not what its values are (the input already shows the values).
- **Label** is self-explanatory on its own — `Aspect ratio`, not `Ratio`.
- **Help text** is asset- or content-level guidance, not block-specific instructions.

## Dataset and permissions

- Dataset writes go through Sanity Studio (by Aled or clients) or via the Sanity API with a write token. Agents do not write to the dataset.
- Read queries in the delivery code use a public (no-auth) or read-only token.
- Studio auth: see *Studio version* above — `auth.providers` replaces the built-ins by default from v6, so a provider change can lock editors out without failing a build.

## Gotchas

- Schema changes are safe: adding optional fields is non-breaking. Removing or renaming fields leaves orphaned data in the dataset — flag to Aled and confirm before doing either.
- Always test schema changes in local Studio (`npm run dev`) before pushing. A broken schema can crash the Studio.
- GROQ queries are not validated at build time — test them in the Sanity Vision plugin or locally.
- The `sanity.config.ts` (or `.js`) file wires the schema to the Studio; missing a schema registration here means it won't appear in the Studio even if the file exists.
- **The delivery sandbox cannot reach `*.sanity.io` — every Sanity-backed repo hits this once per run unless its `CLAUDE.md` says so.** The sandbox's egress proxy refuses CONNECT to `api.sanity.io`, `apicdn.sanity.io` and `cdn.sanity.io` (`curl: (56) CONNECT tunnel failed, response 403`), so in-sandbox nothing can fetch a document, prerender a page that fetches at build time, or curl a live Sanity-backed render. Two consequences for delivery code: fetch at **request time** (`export const dynamic = "force-dynamic"`, or a request-time GROQ call) rather than at build time, so `npm run build` and CI do not depend on egress the sandbox lacks — a `siteSettings` fetch inside `generateMetadata` at prerender breaks every route; and verify a Sanity-backed render in-sandbox against a stubbed client or fixture data, leaving the live render to CI or the deployment. The general environmental-vs-real gate rule is `skill-build-ticket` step 4; each Sanity-backed repo records the block in its own `CLAUDE.md` so the next run does not rediscover it. Adding the three hosts to the sandbox's egress allowlist is an Owner config action, not canon. (Instances: `meirionpritchard-com`, 2026-07-29 — APP-712; `assoc-one`, 2026-09-03 — APP-1112.) **But the sandbox is not the only surface: the Sanity MCP connector reaches the live dataset read-only, and it is how a Studio write is confirmed during an Owner-run preview test.** The egress block is the sandbox's, not the system's. Where a ticket's acceptance depends on the Owner doing something in the preview Studio — an upload, a reference, a publish — query the dataset through the connector after each of his actions and establish the fact rather than relying on his description: was the `mux.videoAsset` record created, is it `ready`, was the reference written, which external IDs are in use. On two consecutive tickets this turned reports like "it didn't show" into settled facts inside about a minute each, and it is the difference between diagnosing a Studio interaction and guessing at it. **Reads only** — the no-dataset-writes rule above is untouched, and the connector is not a way around it. **And project fields by their real names when you report a dataset read to the Owner.** A read quoted back to him is evidence he will act on, and an aliased projection makes a wrong figure look like a measurement: one query aliased `data.duration` as a size and an 18.5 MB file was reported to him as 1.8 MB, corrected by him rather than by the run. Name the field, or name what you computed and from which field. (Instances: A1-499 and A1-504, `meirionpritchard-com`, both 2026-09-23 — the first found four real defects in about an hour of live preview testing that a green CI, a fixture-based GROQ spec and a full Playwright suite had all passed — APP-1697.)

- **An egress-blocked route is not an undrivable route — stub `sanityFetch` identically on base and head, and the real route becomes both buildable and comparable.** The bullet above says to verify against a stub; this says what the stub is worth once it is applied to **both trees**, and why a workaround route is not a substitute for the route under test. Stub the Studio fetch helper (on `meirionpritchard-com`, `src/sanity/live.ts`'s `sanityFetch`) to return empty data per tag — `workProject` → `[]`, `navItem` → `{left:[],right:[]}`, else `null` — and apply the **identical** stub to the base and head worktrees. Four things follow that no workaround route can give: both trees build; `/` renders on `next start`; the two `next build` **route tables compare directly**, which is the only way to answer *did this change the route's render mode?*; and Chromium's `--host-resolver-rules` drives host-gated behaviour on `/` with a real `Host` header. The cost of the workaround is specific and has been paid: a production-host gate verified on `/work-test` plus a throwaway route, never on `/` itself, hid the public homepage moving from ISR (`○ /`, revalidate 1m) to per-request dynamic rendering (`ƒ /`) when the fix added `headers()` to `src/app/page.tsx` — and `npm run build` exiting 0 was read as a happy side effect. So read a render-mode symbol change in the route table as a finding in its own right, and a green build as evidence about the build only (`convention-vercel`, *Gotchas*). The general principle is `skill-review-pr`'s *Reproduce the runtime* — a substitute route is a fixture, and a fixture's green is worse than no harness where the subject is the real route — and a repo naming `/` as undrivable in its own `CLAUDE.md` is recording the egress block, never ruling that the route cannot be driven. (Worked case: A1-586 QA round 2, `assoc-one/meirionpritchard-com` PR #220 head `8878c92`, 2026-10-03 — the stub, both builds, the 29 seed rows rendering on `/`, and the `○ 1m` versus `ƒ` route-table comparison were all run in that leg; the repo's CLAUDE.md wording is as read at `origin/main` `5fef90e`. Premise unverified from the refine surface, which can read no repo — the file paths, the tag names, the route-table symbols and the seed-row count are that leg's report; the egress block itself is this file's own standing gotcha, APP-712. APP-2018.)

- **Where the data dependency sits in the root layout, or the env module throws on an unset variable, no route renders at all — stub at the client or env module, and commit the stub.** The two bullets above prescribe a stub for a page-level fetch and leave the live render to CI; two shapes defeat that recipe and need naming. Where the fetch is awaited in the **root layout**, or in any module every route loads, there is no narrower route to scope the check down to — the whole surface fails together, so "check another route" is not available. And where the **env module throws** on an unset variable rather than returning empty, the failure precedes the fetch entirely: the import raises before the stubbed helper is ever reached, so the stub belongs one level down, at the **client or env module**, as a development fallback that yields empty data instead of raising. Applied there, the render check is recoverable; applied only at the fetch helper, nothing renders and the stub reads as ineffective when it was merely too high up. **The stub is then committed**, as a documented development fallback named in the repo's own `CLAUDE.md` beside the egress block — never carried as an uncommitted local change. A render verified behind an uncommitted patch is evidence about the patch, not about the tree: the committed tree is still the one that does not render, nobody else can reproduce the check, and the next run rediscovers the block from zero. The precedent is exact and recent — an exec leg proved a render pipeline with a replica script rather than the committed entry point, and the proof did not transfer (`APP-3110`, closed 2026-11-16). Where a decision has parked the CMS while a root-level module still depends on it, the dependency is the thing to stub and commit, not a reason to defer the render check. (Instance as reported from a delivery leg and unverified from the refine surface, which can read no repo: on `assoc-one/aledpritchard-com` a root layout awaited a site-settings fetch and the env module threw on an unset dataset variable, so with no environment every route rendered the development error overlay and with placeholder values every route rendered the site's error page; the UI change was checked only behind an uncommitted local catch, and neither the repo's `CLAUDE.md` nor its `AGENTS.md` carried a local-render recipe — `APP-3166`.)

- **Duplicate, Publish, Unpublish, Delete, Discard and Restore are predefined document actions — do not build one, and do not conclude one is absent from the menu you happened to open.** The Studio ships these six as predefined document actions, reached from the **footer ⋯ menu** on an open document, so a custom `documentActions` implementation of any of them is a rebuild of something already installed. The **pane-header ⋯ is a different menu**: it holds clipboard *pane* actions, not duplicate — so a session that checks only the pane header concludes duplicate is missing, and is wrong about the Studio while being right about that menu. What is genuinely absent is bulk: **there is no native multi-select or bulk action in the Structure document list**, at either version read. The bulk toolbar visible in 6.16.0 belongs to **Releases and Variants**, not to the Structure list, so it does not answer a "bulk delete these documents" ask. **The versions these were read at: sanity 5.30.0 and npm 6.16.0, source read 2026-09-29** — stated as the versions of the read, not as a claim about what is installed now. This file's baseline is v6 while the delivery repo is reported on 5.30.0; `package.json` settles that, not this bullet. **Reachability, where the question needs the real Studio rather than the docs:** the embedded Studio boots in-sandbox under Playwright by stubbing `*.api.sanity.io` — `/users/me` returning a user, `/keyvalue` returning `[]`, `/query` returning empty, and `/listen` aborted — with an auth token seeded into `localStorage`. **Stated limit:** the mock user carries no publish permission, so fields render **read-only**; the recipe answers "does this action exist, and where does it live", not "does editing work". (Instance: A1-561, `meirionpritchard-com`, 2026-09-28 — a custom duplicate action built and its PR closed unmerged against a predefined action that already shipped — APP-1854.)

- **Sanity UI's `Select` always renders its own chevron, and no prop or inline style can remove it — replace it with one scoped rule on the sibling, under a project-specific class.** `Select` renders the native `select` and the chevron as *siblings* inside a `div[data-ui="Select"]` wrapper, the chevron in its own absolutely-positioned, `pointer-events: none` box. There is no prop that suppresses it, and `appearance: none` / `-webkit-appearance` / `background-image: none` on the `select` cannot reach a sibling element — so the three attempts this invites all fail, in this order: a leading icon in a sibling `Flex` (yields a second, detached chevron), inline appearance resets (no effect at all, because the chevron is not a background image on the `select`), an absolutely-positioned overlay icon (still two marks). What works is hiding the chevron box directly — `div[data-ui="Select"] > div { display: none !important; }` — scoped inside a project-specific class so it never reaches another `Select` elsewhere in the Studio, with the meaningful icon then placed by the caller. Reach for this whenever the ask is "one meaningful icon instead of the dropdown chevron" (a filter or sort control is the usual case) rather than hunting for a prop: Sanity documents neither the structure nor a way to turn it off, so this bullet is the only statement of it. **Unverified premise — the component's internal DOM:** the sibling structure was read from the compiled `@sanity/ui` bundle in the delivery repo's `node_modules` during A1-529 and is not re-readable from the ops surface; confirm that the chevron box renders as a sibling of `select` inside `div[data-ui="Select"]` against the installed `@sanity/ui` before restating it as a version-pinned fact (expected: sibling, and no disabling prop). The documentation gap *is* verified: two searches of Sanity's docs through the Sanity connector on 2026-09-25 returned no article covering the `Select` chevron or its suppression. (Instance: A1-529, `meirionpritchard-com` Assets tool filter/sort controls, 2026-09-24 — three rounds to land, root-caused only by reading the compiled source — APP-1757.)
