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:

• Use isDirty to show Cancel and disable Save. Destructure it from form.formState only in the component that owns useForm; anywhere else subscribe with useFormState({ control }) (see the react-hook-form skill)
• 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.