Studio UI Patterns

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.