From 8b00d0710ceaa102770a53dd752ab660cbc57559 Mon Sep 17 00:00:00 2001
From: Noah Gentile <noah.gentile@gmail.com>
Date: Mon, 15 Dec 2025 16:36:52 -0800
Subject: [PATCH] feat: add `sanity-ui` skill

---
 AGENTS.md                               |   1 +
 README.md                               |   2 +
 rules/sanity-ui.mdc                     | 518 ++++++++++++++++++++++++
 sanity-plugin/skills/sanity-ui/SKILL.md | 158 ++++++++
 4 files changed, 679 insertions(+)
 create mode 100644 rules/sanity-ui.mdc
 create mode 100644 sanity-plugin/skills/sanity-ui/SKILL.md

diff --git a/AGENTS.md b/AGENTS.md
index bf461df..a93b4e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,6 +49,7 @@ If the Sanity MCP server (`https://mcp.sanity.io`) is available, use `list_sanit
 | **Shopify/Hydrogen** | `shopify`, `hydrogen`, `e-commerce`, `storefront`, `sanity connect` | `rules/sanity-hydrogen.mdc` |
 | **GROQ** | `groq`, `query`, `defineQuery`, `projection`, `filter`, `order` | `rules/sanity-groq.mdc` |
 | **TypeGen** | `typegen`, `typescript`, `types`, `infer`, `satisfies`, `type generation` | `rules/sanity-typegen.mdc` |
+| **Sanity UI** | `ui`, `component`, `theme`, `design system`, `studio plugin`, `custom tool`, `@sanity/ui` | `rules/sanity-ui.mdc` |
 
 ### Using the Knowledge Router
 
diff --git a/README.md b/README.md
index 0d4dc57..39a3102 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,7 @@ Skills guide the AI through multi-step workflows in your codebase.
 | **Schema Manager** | Handles the full lifecycle: scaffolding, safe deprecation, and migrations. | "Deprecate the 'body' field" |
 | **GROQ Assistant** | Writes optimized queries using `defineQuery` and proper projections. | "Write a query for recent posts" |
 | **TypeGen Fixer** | Diagnoses and fixes TypeScript generation issues. | "Why are my types missing?" |
+| **Sanity UI Builder** | Guide for building React UIs with Sanity's design system and component library. | "Build a custom Studio tool UI" |
 | **Install Rules** | Copies context rules to your project for local agent guidance. | "Install Sanity rules locally" |
 
 ### Getting started flow
@@ -172,6 +173,7 @@ These files provide passive knowledge to the AI, ensuring generated code follows
 - **`sanity-typegen.mdc`**: TypeScript type generation from schema.
 - **`sanity-project-structure.mdc`**: File organization for Studio and monorepos.
 - **`sanity-get-started.mdc`**: Interactive 3-phase onboarding guide.
+- **`sanity-ui.mdc`**: Complete component reference for building with @sanity/ui design system.
 </details>
 
 <details>
diff --git a/rules/sanity-ui.mdc b/rules/sanity-ui.mdc
new file mode 100644
index 0000000..eb27840
--- /dev/null
+++ b/rules/sanity-ui.mdc
@@ -0,0 +1,518 @@
+---
+description: Guide for building React interfaces with @sanity/ui, Sanity's official design system. Focuses on design system fundamentals, component selection, and Sanity-specific patterns.
+globs: **/*.tsx, **/*.ts
+alwaysApply: false
+---
+
+# Sanity UI Component Library & Design System
+
+Guide for building React interfaces with Sanity UI (@sanity/ui).
+
+**For detailed component API reference, see:** https://www.sanity.io/ui
+
+## Quick Start
+
+Install Sanity UI:
+
+```bash
+npm install @sanity/ui styled-components
+```
+
+### ThemeProvider Setup
+
+**Important:** ThemeProvider is only needed for standalone apps, NOT for Studio plugins/tools.
+
+#### Building Studio Plugins or Tools? (No Setup Needed)
+
+Studio automatically provides ThemeProvider. Just import and use components directly:
+
+```tsx
+import {Stack, Card, Text, Button} from '@sanity/ui'
+
+// No ThemeProvider needed - Studio provides it
+export function MyStudioTool() {
+  return (
+    <Stack space={4} padding={4}>
+      <Card padding={4} radius={2} shadow={1}>
+        <Text>Content</Text>
+      </Card>
+    </Stack>
+  )
+}
+```
+
+#### Building Standalone Apps? (ThemeProvider Required)
+
+For apps using App SDK (`@sanity/sdk-react`) without full Studio, wrap with ThemeProvider:
+
+```tsx
+import {ThemeProvider, studioTheme} from '@sanity/ui'
+import {SanityApp} from '@sanity/sdk-react'
+
+function App() {
+  return (
+    <ThemeProvider theme={studioTheme}>
+      <SanityApp config={sanityConfigs}>
+        {/* Your app UI */}
+      </SanityApp>
+    </ThemeProvider>
+  )
+}
+```
+
+#### Embedded Studio (Optional Outer ThemeProvider)
+
+When embedding Studio in a larger app, Studio provides its own ThemeProvider internally. You may optionally add an outer ThemeProvider for UI outside the Studio boundary:
+
+```tsx
+import {ThemeProvider, studioTheme} from '@sanity/ui'
+import {Studio} from 'sanity'
+
+function App() {
+  return (
+    <ThemeProvider theme={studioTheme}>  {/* Optional: for app UI outside Studio */}
+      <CustomHeader />  {/* Uses outer ThemeProvider */}
+      <Studio config={config} />  {/* Has its own ThemeProvider internally */}
+    </ThemeProvider>
+  )
+}
+```
+
+## Design System Fundamentals
+
+### Spacing Scale (0-7)
+
+Uses 4px base unit:
+
+| Value | Pixels | Usage |
+|-------|--------|-------|
+| 0 | 0px | No spacing |
+| 1 | 4px | Extra tight |
+| 2 | 8px | Tight |
+| 3 | 12px | Compact |
+| 4 | 16px | Default/comfortable |
+| 5 | 24px | Spacious |
+| 6 | 48px | Very spacious |
+| 7 | 96px | Extra spacious |
+
+```tsx
+<Box padding={4}>  {/* 16px padding */}
+<Stack space={3}>  {/* 12px between items */}
+<Grid gap={2}>     {/* 8px grid gap */}
+```
+
+### Semantic Tones
+
+Use tones to communicate state and intent:
+
+- `default` - Standard neutral appearance
+- `primary` - Primary brand color
+- `positive` - Success states (green)
+- `caution` - Warning states (yellow)
+- `critical` - Error/danger states (red)
+- `transparent` - Transparent background
+- `inherit` - Inherit from parent
+
+```tsx
+<Button tone="positive" text="Save" />
+<Button tone="critical" text="Delete" />
+<Card tone="caution"><Text>Warning</Text></Card>
+```
+
+### Responsive Props
+
+Many props accept responsive arrays (mobile-first):
+
+```tsx
+<Box
+  padding={[3, 4, 5]}           // Mobile: 3, Tablet: 4, Desktop: 5
+  display={['block', 'flex']}   // Mobile: block, Tablet+: flex
+/>
+
+<Grid columns={[1, 2, 3]} gap={[2, 3, 4]}>
+  {/* 1 column mobile, 2 tablet, 3+ desktop */}
+</Grid>
+```
+
+### Other Design Tokens
+
+**Font Sizes:**
+- Text: 0-4 (0=smallest, 4=largest)
+- Heading: 0-6 (0=smallest, 6=largest)
+
+**Border Radius (0-6):** 0px, 1px, 2px, 4px, 8px, 16px, 32px
+
+**Shadows (0-5):** None, subtle, light, medium, high, maximum elevation
+
+## Component Quick Reference
+
+### Layout Components
+
+**When you need layout:**
+- `Box` - Base layout with margin, padding, flex/grid props
+- `Stack` - Vertical layout with spacing
+- `Inline` - Horizontal inline layout with wrapping
+- `Flex` - Flexbox layout
+- `Grid` - CSS Grid layout
+- `Container` - Max-width centered container
+
+```tsx
+<Stack space={4}>
+  <Box padding={3}>Item 1</Box>
+  <Box padding={3}>Item 2</Box>
+</Stack>
+
+<Flex align="center" justify="space-between" gap={3}>
+  <Button text="Left" />
+  <Button text="Right" />
+</Flex>
+
+<Grid columns={[1, 2, 3]} gap={4}>
+  <Card>Cell 1</Card>
+  <Card>Cell 2</Card>
+</Grid>
+```
+
+### UI Components
+
+**When you need:**
+- **Container/card** → `Card` (with padding, radius, shadow, tone)
+- **Button** → `Button` (modes: default, ghost, bleed)
+- **Text** → `Text`, `Heading`, `Label`
+- **Form inputs** → `TextInput`, `TextArea`, `Select`, `Checkbox`, `Radio`, `Switch`
+- **User avatar** → `Avatar`
+- **Badge/pill** → `Badge`
+- **Code display** → `Code`, `Kbd`
+- **Loading indicator** → `Spinner`
+
+**Interactive/overlay components:**
+- `Dialog` - Modal dialogs
+- `Popover` - Dropdown overlays
+- `Menu` / `MenuButton` / `MenuItem` - Dropdown menus
+- `Tooltip` - Hover tooltips
+
+**Notifications:**
+- `useToast()` hook - Toast notifications
+
+```tsx
+// Basic components
+<Card padding={4} radius={2} shadow={1} tone="primary">
+  <Text size={2} weight="semibold">Card content</Text>
+</Card>
+
+<Button text="Save" icon={CheckIcon} tone="primary" onClick={handleSave} />
+
+// Form inputs
+<Stack space={3}>
+  <Label>Email</Label>
+  <TextInput type="email" value={email} onChange={e => setEmail(e.currentTarget.value)} />
+</Stack>
+
+// Toast notifications
+const toast = useToast()
+toast.push({
+  status: 'success',
+  title: 'Saved',
+  description: 'Changes saved successfully'
+})
+```
+
+## Sanity-Specific Patterns
+
+### Document Panel Layout
+
+Standard document editing layout with fixed header/footer and scrollable content:
+
+```tsx
+function DocumentPanel({header, banners, content, inspector, footer}) {
+  return (
+    <Flex direction="column" height="fill">
+      {/* Fixed header */}
+      {header}
+
+      {/* Scrollable content area */}
+      <Flex flex={1} overflow="auto">
+        <Box flex={1}>
+          {/* Contextual banners */}
+          {banners && (
+            <Stack space={2} paddingX={4} paddingY={3}>
+              {banners}
+            </Stack>
+          )}
+
+          {/* Main content */}
+          <Box padding={4}>{content}</Box>
+        </Box>
+
+        {/* Side inspector (responsive - hides on mobile) */}
+        {inspector && (
+          <Box flex={1} borderLeft display={['none', 'none', 'block']}>
+            {inspector}
+          </Box>
+        )}
+      </Flex>
+
+      {/* Fixed footer */}
+      {footer}
+    </Flex>
+  )
+}
+```
+
+### Form Field Pattern
+
+Standard field wrapper with label, description, and validation:
+
+```tsx
+function FormField({title, description, validation, children}) {
+  return (
+    <Stack space={2}>
+      {title && <Label size={1} weight="semibold">{title}</Label>}
+      {description && <Text size={1} muted>{description}</Text>}
+
+      {validation?.length > 0 && (
+        <Stack space={2}>
+          {validation.map((item, i) => (
+            <Alert key={i} status={item.level} title={item.message} />
+          ))}
+        </Stack>
+      )}
+
+      {children}
+    </Stack>
+  )
+}
+```
+
+### Custom Input Component
+
+Building custom inputs for Sanity schemas:
+
+```tsx
+import {Stack, TextInput} from '@sanity/ui'
+import {set, unset} from 'sanity'
+
+export function CustomStringInput(props) {
+  const {elementProps, onChange, value = ''} = props
+
+  return (
+    <Stack space={2}>
+      <TextInput
+        {...elementProps}
+        value={value}
+        onChange={(event) => {
+          const nextValue = event.currentTarget.value
+          onChange(nextValue ? set(nextValue) : unset())
+        }}
+      />
+    </Stack>
+  )
+}
+```
+
+### Banner Pattern
+
+Contextual messages at top of content areas:
+
+```tsx
+function Banner({tone = 'caution', message, action}) {
+  return (
+    <Box padding={1}>
+      <Card radius={3} paddingX={2} paddingY={2} tone={tone}>
+        <Flex align="center" gap={3} paddingX={2}>
+          <Text size={0}><WarningOutlineIcon /></Text>
+          <Flex align="center" flex={1} paddingY={2}>
+            <Text size={1}>{message}</Text>
+          </Flex>
+          {action && <Button {...action} mode="ghost" />}
+        </Flex>
+      </Card>
+    </Box>
+  )
+}
+```
+
+### Loading States
+
+Always provide feedback during async operations:
+
+```tsx
+function LoadingPane({message = 'Loading...'}) {
+  return (
+    <Flex align="center" direction="column" height="fill" justify="center">
+      <Stack space={3} align="center">
+        <Spinner />
+        <Text size={1} muted>{message}</Text>
+      </Stack>
+    </Flex>
+  )
+}
+```
+
+### Empty States
+
+Standard empty state pattern:
+
+```tsx
+function EmptyState({heading, description, onCreate}) {
+  return (
+    <Flex align="center" direction="column" height="fill" justify="center">
+      <Container width={1}>
+        <Box paddingX={4} paddingY={5}>
+          <Stack space={4} align="center">
+            <Text size={1} weight="semibold" align="center">{heading}</Text>
+            <Text size={1} muted align="center">{description}</Text>
+            {onCreate && (
+              <Button icon={AddIcon} text="Create new" onClick={onCreate} tone="primary" />
+            )}
+          </Stack>
+        </Box>
+      </Container>
+    </Flex>
+  )
+}
+```
+
+### Responsive Layout
+
+Collapse based on available space using `useElementRect`:
+
+```tsx
+import {useElementRect} from '@sanity/ui'
+
+function ResponsiveLayout({minWidth = 768}) {
+  const [rootElement, setRootElement] = useState(null)
+  const rootRect = useElementRect(rootElement)
+  const isCompact = (rootRect?.width || 0) < minWidth
+
+  return (
+    <div ref={setRootElement}>
+      {isCompact ? <CompactView /> : <FullView />}
+    </div>
+  )
+}
+```
+
+### Portal Management
+
+For dialogs, popovers, and tooltips:
+
+```tsx
+import {PortalProvider} from '@sanity/ui'
+
+function PluginRoot() {
+  const [portalElement, setPortalElement] = useState(null)
+
+  return (
+    <PortalProvider element={portalElement}>
+      {/* Dialogs, tooltips, popovers render here */}
+      <YourContent />
+      <div ref={setPortalElement} />
+    </PortalProvider>
+  )
+}
+```
+
+## Useful Hooks
+
+- `useTheme()` - Access theme tokens programmatically
+- `usePrefersDark()` - Detect user's dark mode preference
+- `useMediaIndex()` - Get current responsive breakpoint index (0-4)
+- `useToast()` - Toast notification system
+- `useElementRect()` - Track element dimensions with resize observer
+
+```tsx
+import {useTheme, usePrefersDark, useMediaIndex} from '@sanity/ui'
+
+function MyComponent() {
+  const theme = useTheme()
+  const prefersDark = usePrefersDark()
+  const mediaIndex = useMediaIndex()
+
+  const spacing = theme.space[4] // 16px
+  const isMobile = mediaIndex === 0
+
+  return (
+    <Card scheme={prefersDark ? 'dark' : 'light'}>
+      {isMobile ? 'Mobile' : 'Desktop'}
+    </Card>
+  )
+}
+```
+
+## Building Custom Themes
+
+Use `buildTheme()` to customize the design system:
+
+```tsx
+import {buildTheme} from '@sanity/ui/theme'
+import {studioTheme} from '@sanity/ui'
+
+const customTheme = buildTheme({
+  base: studioTheme, // Extend existing theme
+  fonts: {
+    text: {
+      family: 'Inter, sans-serif',
+    }
+  },
+  space: [0, 4, 8, 12, 16, 24, 48, 96], // Custom spacing scale
+  radius: [0, 1, 2, 4, 8, 16, 32],      // Custom radius scale
+})
+```
+
+## Best Practices
+
+### 1. Use Design Tokens
+
+```tsx
+// Good: Using spacing scale
+<Stack space={4}>
+  <Box padding={3}>Content</Box>
+</Stack>
+
+// Avoid: Custom pixel values
+<div style={{padding: '14px'}}>Content</div>
+```
+
+### 2. Semantic Tones
+
+```tsx
+// Good: Semantic usage
+<Button tone="positive" text="Save" />
+<Button tone="critical" text="Delete" />
+
+// Avoid: Mismatched semantics
+<Button tone="critical" text="Save" /> // Red save button
+```
+
+### 3. Responsive Design
+
+```tsx
+// Good: Mobile-first responsive
+<Grid columns={[1, 2, 3]} gap={[2, 3, 4]}>
+  {/* Responsive grid */}
+</Grid>
+```
+
+### 4. Portal for Overlays
+
+Always wrap dialogs/popovers in PortalProvider when building plugins.
+
+### 5. Loading States
+
+Always provide feedback during async operations - never leave users wondering if something is happening.
+
+## Common Pitfalls
+
+1. **Don't add ThemeProvider in Studio plugins** - Studio already provides it
+2. **Don't mix spacing systems** - Always use @sanity/ui's scale
+3. **Don't use custom colors** - Use semantic tones instead
+4. **Don't forget portal providers** - Required for dialogs/popovers in plugins
+5. **Don't skip loading states** - Always provide feedback
+6. **Don't ignore responsive breakpoints** - Test on multiple screen sizes
+
+## Additional Resources
+
+- **Component API reference:** https://www.sanity.io/ui
+- **Source code:** https://github.com/sanity-io/ui
+- **Storybook:** Component examples and interactive demos
diff --git a/sanity-plugin/skills/sanity-ui/SKILL.md b/sanity-plugin/skills/sanity-ui/SKILL.md
new file mode 100644
index 0000000..e6a9262
--- /dev/null
+++ b/sanity-plugin/skills/sanity-ui/SKILL.md
@@ -0,0 +1,158 @@
+---
+name: sanity-ui
+description: Build React UIs with Sanity's design system. Use when creating custom Studio plugins, Tool interfaces, or content editing UIs.
+allowed-tools: WebFetch, Read, Glob, Grep
+---
+
+# Sanity UI
+
+Build React interfaces using Sanity UI's component library and theme system.
+
+## Procedure
+
+1. **Setup Check**
+   * Check if `@sanity/ui` is installed in package.json
+   * If missing: `npm install @sanity/ui styled-components`
+   * **Important:** Check context:
+     * **Building Studio plugins/tools?** → ThemeProvider already provided by Studio - no setup needed
+     * **Building standalone apps (App SDK)?** → Must wrap with `<ThemeProvider theme={studioTheme}>`
+   * **Rule:** ThemeProvider is auto-provided in Studio context (plugins, tools, Studio components)
+
+2. **Identify Component Needs**
+   * **Layout?** → Use Box, Stack, Flex, Grid, Container, Inline
+   * **Forms?** → Use TextInput, TextArea, Select, Checkbox, Radio, Switch, Label
+   * **Interactive?** → Use Button, Card (as="button"), Dialog, Popover, Menu
+   * **Feedback?** → Use Toast (via useToast hook), Spinner, Badge
+   * **Typography?** → Use Text, Heading, Code, Kbd
+   * **Media?** → Use Avatar
+
+3. **Apply Design System**
+   * **Rule:** Always use spacing scale (0-7) where 1=4px, 2=8px, 3=12px, 4=16px, 5=24px, 6=48px, 7=96px
+   * **Rule:** Use semantic tones: `default`, `primary`, `positive` (green), `caution` (yellow), `critical` (red), `transparent`, `inherit`
+   * **Rule:** Apply responsive props as arrays: `padding={[3, 4, 5]}` for [mobile, tablet, desktop]
+   * **Action:** Use `studioTheme` for consistent styling with Sanity Studio
+
+4. **Common Patterns**
+   * **Document Panel:** Fixed header/footer, scrollable content area, optional side inspector
+   * **Form Field:** Stack with space={2}, Label + description + validation + input
+   * **Banner:** Card with tone, padding={1}, radius={3} for contextual messages
+   * **Empty State:** Centered Container with Stack of Text + Button
+   * **Loading:** Centered Flex with Spinner + Text
+   * **Portal Management:** Use PortalProvider for dialogs, popovers, tooltips
+
+5. **Reference Lookup**
+   * **Action:** For comprehensive component props → Load `sanity://rules/sanity-ui.mdc`
+   * **Action:** For theme customization → Check buildTheme() in rule file
+   * **Action:** For advanced patterns → Check rule file content editing patterns
+   * **Official docs:** https://www.sanity.io/ui
+
+## Examples
+
+### Studio Plugin/Tool (ThemeProvider Already Provided)
+
+```tsx
+import {Stack, Card, Text} from '@sanity/ui'
+
+// No ThemeProvider needed - Studio provides it
+export function MyStudioTool() {
+  return (
+    <Stack space={4} padding={4}>
+      <Card padding={4} radius={2} shadow={1}>
+        <Text size={2}>Content</Text>
+      </Card>
+    </Stack>
+  )
+}
+```
+
+### Standalone App (ThemeProvider Required)
+
+```tsx
+import {ThemeProvider, studioTheme, Stack, Card, Text} from '@sanity/ui'
+
+// ThemeProvider required for standalone apps
+export function MyApp() {
+  return (
+    <ThemeProvider theme={studioTheme}>
+      <Stack space={4} padding={4}>
+        <Card padding={4} radius={2} shadow={1}>
+          <Text size={2}>Content</Text>
+        </Card>
+      </Stack>
+    </ThemeProvider>
+  )
+}
+```
+
+### Form with Validation
+
+```tsx
+import {Stack, Label, Text, TextInput, Button} from '@sanity/ui'
+import {useState} from 'react'
+
+export function MyForm() {
+  const [name, setName] = useState('')
+  const [error, setError] = useState('')
+
+  return (
+    <Stack space={4}>
+      <Stack space={2}>
+        <Label size={1} weight="semibold">Name</Label>
+        <Text size={1} muted>Enter your full name</Text>
+        <TextInput
+          value={name}
+          onChange={(e) => setName(e.currentTarget.value)}
+        />
+        {error && (
+          <Text size={1} style={{color: 'var(--card-fg-color)'}}>
+            {error}
+          </Text>
+        )}
+      </Stack>
+      <Button text="Submit" tone="primary" />
+    </Stack>
+  )
+}
+```
+
+### Document Panel Layout
+
+```tsx
+import {Flex, Box, Card, Text} from '@sanity/ui'
+
+export function DocumentPanel({header, content, footer}) {
+  return (
+    <Flex direction="column" height="fill">
+      {/* Fixed header */}
+      {header}
+
+      {/* Scrollable content */}
+      <Box flex={1} overflow="auto">
+        <Box padding={4}>
+          {content}
+        </Box>
+      </Box>
+
+      {/* Fixed footer */}
+      {footer}
+    </Flex>
+  )
+}
+```
+
+### Loading State
+
+```tsx
+import {Flex, Spinner, Text, Stack} from '@sanity/ui'
+
+export function LoadingPane({message = 'Loading...'}) {
+  return (
+    <Flex align="center" direction="column" height="fill" justify="center">
+      <Stack space={3} align="center">
+        <Spinner />
+        <Text size={1} muted>{message}</Text>
+      </Stack>
+    </Flex>
+  )
+}
+```