Studio UI Patterns Agent Skill

Studio UI Patterns

The Design System docs and demos are the source of truth. Always check the relevant

demo file before composing new UI.

Layout

Docs: apps/design-system/content/docs/ui-patterns/layout.mdx

Build pages with PageContainer, PageHeader, and PageSection.

| Content type | size |

| ----------------- | ----------- |

| Settings / config | "default" |

| Lists / tables | "large" |

| Full-screen views | "full" |

• If filters/search exist on a list page, align table actions with the filters (don't use PageHeaderAside/PageSectionAside for those actions)
• If no filters, actions can go in PageHeaderAside or PageSectionAside

Demos: page-layout-settings.tsx, page-layout-list.tsx, page-layout-list-simple.tsx, page-layout-detail.tsx

(all in apps/design-system/registry/default/example/)

Forms

Docs: apps/design-system/content/docs/ui-patterns/forms.mdx

• Use react-hook-form + zod
• Use FormItemLayout instead of manually composing FormItem/FormLabel/FormMessage/FormDescription
• Wrap inputs with FormControl; import primitives from ui

Layout selection:

| Context | Layout | Container |

| ------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------- |

| Page (settings/config) | FormItemLayout layout="flex-row-reverse" | Card (CardContent per field; CardFooter for actions) |

| Side panel — wide | FormItemLayout layout="horizontal" | SheetSection |

| Side panel — narrow (size="sm" or below) | FormItemLayout layout="vertical" | SheetSection |

Dirty state / submit:

• Destructure isDirty from form.formState to show Cancel and disable Save
• Show loading on submit button via loading prop
• If submit button is outside <form>, set a stable formId and use form prop on the button

Demos: form-patterns-pagelayout.tsx, form-patterns-sidepanel.tsx

Tables

Docs: apps/design-system/content/docs/ui-patterns/tables.mdx

| Pattern | Use when |

| ---------- | ----------------------------------------------------------------------- |

| Table | Simple, static, semantic display |

| Data Table | TanStack-powered; sorting, filtering, pagination; composed per use-case |

| Data Grid | Virtualization, column resizing, or complex cell editing |

• Actions: above the table, aligned right
• Search/filters: above the table, aligned left
• If table is primary content with no filters, actions can live in the page's primary/secondary actions area

Demos: table-demo.tsx, data-table-demo.tsx, data-grid-demo.tsx

Charts

Docs: apps/design-system/content/docs/ui-patterns/charts.mdx

• Use provided chart building blocks; avoid passing raw Recharts components to ChartContent
• Use useChart context flags for loading/disabled states
• Keep composition straightforward — avoid over-abstraction

Demos (in apps/design-system/__registry__/default/block/): chart-composed-demo.tsx, chart-composed-basic.tsx, chart-composed-states.tsx, chart-composed-metrics.tsx, chart-composed-actions.tsx, chart-composed-table.tsx

Empty States

Docs: apps/design-system/content/docs/ui-patterns/empty-states.mdx

| Scenario | Pattern |

| ------------------------ | ------------------------------------------------------------------- |

| Initial / onboarding | Presentational empty state with value prop + clear next action |

| Data-heavy lists | Informational empty state matching the list/table layout |

| Zero results from search | Keep layout consistent with data state to avoid jarring transitions |

| Missing route | Centered Admonition |

Demos: empty-state-presentational-icon.tsx, empty-state-initial-state-informational.tsx, empty-state-zero-items-table.tsx, data-grid-empty-state.tsx, empty-state-missing-route.tsx

Navigation

Docs: apps/design-system/content/docs/ui-patterns/navigation.mdx

• Use NavMenu for a horizontal list of related views within a consistent page layout
• Activating an item must trigger a URL change — no local-only tab state

Cards

• Group related information in cards
• CardContent for sections, CardFooter for actions
• Only use CardHeader/CardTitle when context isn't already provided by surrounding content
• Use headers/titles when multiple cards represent distinct groups (e.g. multiple settings sections)

Alerts

• Use Admonition to call out important actions, restrictions, or critical context
• Place at the top of a page's content (below page title) or top of the relevant section (below section title)
• Use sparingly

Sheets (Side Panels)

Use a Sheet when switching pages would be disruptive and the user needs to maintain context (e.g. selecting a row from a list to edit).

Structure:

• SheetContent with size="lg" for forms needing horizontal layout
• Use SheetHeader, SheetTitle, SheetSection, SheetFooter
• Submit/cancel actions go in SheetFooter

Forms in sheets:

• layout="horizontal" for wider sheets
• layout="vertical" for narrow sheets (size="sm" or below)
• When the sheet contains a form, wire dirty dismissal with useConfirmOnClose +

DiscardChangesConfirmationDialog (Cancel, Escape, and backdrop). Source of

truth: apps/design-system/content/docs/ui-patterns/modality.mdx (Dirty form

dismissal). Also see the react-hook-form skill for isDirty destructuring.

Copy

Source of truth: apps/design-system/content/docs/copywriting.mdx — sentence case, title case, proper nouns, voice and tone.

When changing visible copy, grep e2e/studio/ for the old string.