The short answer
Test each section at its limits, on one page that shows every variant. Add new sections through one short request process. Change live sections carefully, because saved content does not update itself when the schema changes. Retire sections in stages. Name one owner, and review the library on a regular rhythm.
The aim is a boring library: one that still makes sense to a new team member a year from now.
What to test on every section
Test the extremes. Average content rarely breaks anything. Run this for each variant.
| Test | What to try | Pass when |
|---|---|---|
| Longest content | Text at the validation limit, in your longest real words | No overflow or broken layout at phone width |
| Shortest content | Only required fields filled | No gaps or empty wrappers |
| Item counts | The fewest and most items a list allows | Grid still looks intended |
| Images | Tall, wide and small images, odd hotspots | Crops are fine, and no layout shift |
| Neighbours | Next to each other section, dark next to dark | Spacing holds |
| Screens | Phone to wide desktop | No sideways scroll |
| Keyboard and screen reader | Tab through it, check heading order | Everything can be reached, and headings make sense |
| No JavaScript, reduced motion | Turn each off | Content can still be read |
| Speed | Lighthouse on a page with the section | Meets your budget |
Build a kitchen sink page
Make one private page that holds every section in every variant, at both the longest and shortest content. Mark it noindex and leave it out of your sitemap. It becomes your test bench, and a living catalogue for editors.
Use it for:
- Screenshot tests. Compare before and after on each code change, so you see what really moved.
- Reviews. A designer can check the whole library in one scroll.
- Onboarding. A new editor can see what exists.
- AI checks. Compare what the AI built with what a section should look like.
Keep this page's content in code or in a seed file, if you can, so a stray edit cannot hide a bug.
Automatic checks
Run these in your CI on each pull request that touches sections, so problems stop before they reach an editor.
- Schema check:
sanity schemas validate. - Type check: TypeGen, then your type checker.
- Content check:
sanity documents validateagainst a copy of your dataset, to find saved content that no longer fits. - Build: every section type has a component.
- Pages: crawl the built site for errors, broken links and sideways scroll.
- Screenshots of the kitchen sink page.
- Speed and page weight budgets.
You do not need all of these on day one. Start with the build and the schema check, then add the rest as the library grows.
How a new section gets added
When adding is too easy, the library bloats. When it is too hard, people work around it. A short written request is enough.
- Request. Which page needs it? What job does it do? Which existing section came closest, and why does it fall short?
- Owner decides. One of four answers: use an existing section, add a variant, add a section, or make a one-off.
- Design. Every screen size, every variant, the longest content.
- Build. Schema, component, preview image, usage note, kitchen sink entry.
- Test. The table above, then watch an editor try it.
- Announce. Tell editors, and add it to the AI's library guide. If the AI's guide is not updated, it will not know the section exists, or when to use it.
Decision rule Add a section when at least two planned pages need it, or one page needs it and it earns real money. Otherwise, build a one-off page and look again if the need comes back. Writing down why you said no saves the same debate later.
Change sections without breaking pages
Sanity's migration docs are clear: changing a schema will not change or delete content already in your dataset. Old documents stay as they are, so they may no longer match. So sort every change by how risky it is.
| Change | Risk | How to handle it |
|---|---|---|
| New optional field | Low | Ship it, and make sure the component copes when it is empty |
| Tighter length limit | Medium | Check saved content first. Long text will start failing validation |
| Remove a variant | Medium | Move pages off it first, then remove |
| Rename a field | High | Add the new one, migrate content, ship the code, then remove the old one |
| Rename a section type | High | Avoid it if you can. Plan and test a migration on a copy first |
For high-risk changes, use the migration tool. sanity migrations create makes a script, and sanity migrations run <id> runs it. The docs say it always runs as a dry run unless you add --no-dry-run, so you can read the patches first. They also say to back up first with sanity datasets export. Do not keep two sections called hero and heroV2 for long. Parallel versions are fine during a move, but they should have an end date.
Retire sections in stages
Removing a section from of does not remove it from saved pages. So go in order:
- Find it. Use GROQ to list the pages that still use the section.
- Warn. Add a warning in the Studio, and tell editors and the AI's guide to stop using it. Sanity also has a
deprecatedproperty for document types and fields. Try it on your section fields, and check how it behaves there before relying on it. - Move. Replace it on each page, by hand or with a migration.
- Remove. Take it out of
of, then delete the schema, the component and its preview image. Only do this when your search returns no pages.
Who owns what
Write this down once, and put names in it. Titles are only examples.
| Job | Who | How often |
|---|---|---|
| Decide on section requests | Library owner | As they come in |
| Design and variant rules | Designer | Per change |
| Schemas, components, checks | Developer | Per change |
| Fact documents: prices, quotes, clients | Marketing lead | When facts change |
| AI skills and recipes | Library owner, with marketing | Each new section |
| Usage review | Library owner | Every few months |
In the usage review, count how often each section is used with a GROQ query, ask editors what they avoided, and read a few AI drafts. Merge or retire what nobody uses.
Done when A new person can find out what exists, how to request a section and who decides, without asking anyone.
If you want this built for you, an Astro and Sanity site starts at $2,000 and includes a section library, as our pricing page shows. Adding a library to an existing Sanity site gets a fixed quote after a 20 minute call. See section library.


