mast-sanity: Instructions file for Claude Code

Claude Code Project Instructions

This document contains project-specific instructions and context for Claude Code when working on this codebase.

Project Overview

This is a Mast design system implementation using:

• Frontend: Next.js 16 with App Router
• CMS: Sanity Studio v6 with Visual Editing/Presentation mode
• Styling: Tailwind CSS v4 with CSS-first configuration

Development Environment

• Dev servers: frontend on port 3001 (npm run dev:next), Studio on port 3334 (npm run dev:studio), or both with npm run dev. Docker/OrbStack setups may map these to other host ports.
• Verify changes with npm run type-check and npm run lint; npm run build in each workspace for full verification.
• Seed scripts live in /scripts as .mjs ES modules and run with plain node (see "Creating Pages via Script" below).
• Machine-specific overrides belong in CLAUDE.local.md (gitignored), not this file.

Sanity Content Architecture

Page Structure Hierarchy

Page
└── pageBuilder (array)
    └── section
        └── rows (array)
            └── row
                └── columns (array)
                    └── column
                        └── content (array of blocks)

Sanity API Nesting Limit

CRITICAL: Sanity has a maximum attribute depth of 20 levels. When creating pages programmatically, you must carefully track nesting depth to avoid hitting this limit.

Depth Calculation Reference

Here's how nesting depth accumulates in this page builder:

Level 1:  page
Level 2:  └── pageBuilder (array)
Level 3:      └── section
Level 4:          └── rows (array)
Level 5:              └── row
Level 6:                  └── columns (array)
Level 7:                      └── column
Level 8:                          └── content (array)
Level 9:                              └── [block]

Base path to a simple block: 9 levels

Block types add additional depth based on their internal structure:

Block Type	Additional Depth	Total from Page	Notes
headingBlock	+1 (text field)	10	Safe
richTextBlock	+4 (content→block→children→text)	13	Safe
buttonBlock	+3 (link→href/page/post)	12	Safe
imageBlock	+3 (image→asset→_ref)	12	Safe
cardBlock	+2 (content array + block)	11+	⚠️ Adds nesting
tabsBlock	+4 (tabs→tab→content→block)	13+	⚠️ Risky
accordionBlock	+3 (items→item→content)	12+	⚠️ Adds nesting
sliderBlock	+3 (slides→slide→image)	12	Safe