Sanity Editor Ux

Sanity Editor UX

Make Sanity Studio usable for non-technical editors in any editorial language.

Prefer this skill over ad-hoc label tweaks. Follow the workflow end-to-end.

Skill vs prompt

| Deliverable | When to use | |-------------|-------------| | This skill (SKILL.md) | Cursor / Claude Code / Copilot agents — auto-discovered, repeatable | | PROMPT.md | Paste into any chat model that cannot load skills | | Code starter | Optional TypeScript helpers under sanity/starters/sanity-editor-ux (or installed package) |

Verdict: Ship a skill as the public artifact. Include PROMPT.md for portability.

Before you start — ask the user

Collect (do not guess):

1. Editorial language for Studio labels + help panel: any BCP-47 / short code (en, fr, es, de, pt-BR, …). Built-in packs are only examples — register any language via registerEditorUxLocalePartial (see locales.md).
2. Brand / studio title
3. Greenfield vs existing Sanity project
4. Document types + which are singletons
5. Whether they need generic managed page copy (pageContent) or only classic documents
6. Where fallback / hardcoded copy lives today
7. Sanity project id / dataset / write token availability (names only)

Never tell the user that only English/French/Spanish are supported. If a pack is missing, create one by merging translations onto English and install the matching @sanity/locale-* chrome plugin.

Non-negotiable principles

1. Technical name, human title — never show camelCase to editors
2. Lock what can break the site — readOnly / hidden for keys / ids
3. One editable affordance for managed copy — only Content (EN) / Contenu (FR) / Contenido (ES)
4. Describe placement — every field says where it appears on the site
5. Publish is sacred — help panel + badges reinforce Publish vs Save
6. Daily work first in the desk — help → numbered lists → singletons → settings
7. Fallbacks + safe bootstrap — empty CMS must not blank the site; bootstrap must not wipe editors (setIfMissing)
8. Never rename technical field names on existing projects (breaks GROQ, types, seeds)
9. Match Studio chrome language to content language (locale plugin + labels)
10. Do not require .agents — install skill to .cursor/skills/ or project .agents/skills/

Workflow (execute in order)

0. Inventory (existing repos)

1. List schema document types and field names
2. Find fallbacks / hardcoded UI strings / seeds
3. Note dual Studio configs (Next embedded + standalone) — wire both if present
4. Propose desk map + bootstrap scope

1. Install skill / starter files

• Skill: already installed if user ran npx skills add … or the package installer
• Optional code kit: copy sanity/starters/sanity-editor-ux → project sanity/editor-ux/

2. Dependencies

npm install sanity @sanity/icons @sanity/ui @sanity/client
npm install -D tsx
# Locale plugin for editorial language (skip for English):
npm install @sanity/locale-fr-fr    # French
npm install @sanity/locale-es-es    # Spanish
# See locales.md for de, it, pt, pt-BR, nl, …

3. Copy pack + locale plugin

import {
  createEditorUxCopy,
  registerEditorUxLocalePartial,
  resolveSanityLocalePlugin,
} from "./editor-ux/src";

// Any language — register if not built-in:
registerEditorUxLocalePartial({
  locale: "de",
  studioTitle: "Redaktionsbereich {BRAND}",
  labels: { placement: "Platzierung", content: "Inhalt" },
  // …translate help/ui as needed (untranslated keys stay English)
});

const copy = createEditorUxCopy("de", {
  studioTitle: "Redaktion {BRAND}",
});

const chrome = resolveSanityLocalePlugin("de");
// npm i @sanity/locale-de-de → deDELocale({ title: "Deutsch" })

Built-ins en/fr/es are pre-registered examples only.

4. Desk structure

Help panel (item 0) → numbered daily document lists with @sanity/icons → singletons → taxonomies/settings. Customize type names to the real schema — do not force LEGALI type names.

5. Relabel schemas

Rewrite every title / description in the editorial language. Prefer helpers:

• humanString / humanText / humanSlug
• imageWithAlt / ctaFields / seoObjectField
• definePageContentType when managed page copy is needed
• sectionPrefixedFields for long singletons

6. Bootstrap (mandatory for client handoff)

1. Code-owned fallbacks (managed-pages definitions and/or fallback* objects)
2. Script using ensureDocument + setIfMissing + seedManagedPages
3. --dry-run support + deterministic ids
4. Runtime fetchOrFallback / merge so empty CMS cannot blank pages
5. npm scripts: sanity:bootstrap / sanity:bootstrap:dry

If the project already has a safe seed script, extend it instead of creating a parallel one.

7. Verify

• [ ] Studio opens without schema errors
• [ ] Sidebar: help + icons + numbered groups
• [ ] Locale plugin active when language ≠ English
• [ ] Managed copy (if used): Placement read-only + Content editable
• [ ] Badges show Draft / Published in the editorial language
• [ ] No camelCase titles for editors
• [ ] Bootstrap dry-run is safe; live run does not overwrite editors
• [ ] Site still renders with Sanity empty

Anti-patterns (refuse these)

• Requiring .agents to proceed
• Renaming schema names “to look nicer”
• Editable pageKey / internal keys
• Bootstrap with createOrReplace that wipes fields
• Empty CMS with no fallbacks on production
• English Studio chrome with Spanish/French content labels (or the reverse) without approval
• Adding generic pageContent when dedicated page types already exist and work

Read next

• locales.md — language packs + Sanity locale plugins
• reference.md — patterns, desk, bootstrap, dual-config pitfalls
• examples.md — paste prompts for en/fr/es and existing projects
• PROMPT.md — single paste block for agents without skill support

Deliverable summary (always reply with)

1. Language + locale plugin used
2. Files touched
3. Desk map (0…n)
4. Bootstrap dry-run / live summary
5. Anything left for the human (token, roles, first Publish checklist)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AIEngKenn
• Source: AIEngKenn/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.