Building Frontend Interfaces

Every Mastra application UI is assembled from the @mastra/playground-ui design system. Building a screen is composition work: pick existing components, arrange them with layout utilities, and let the design system provide the look. Writing colors, font sizes, shadows, or radii by hand means you have left the happy path. Changing the design system itself (tokens, ds/ components, variants) is a separate, explicitly-approved task. For Tailwind v4 mechanics (renames, dynamic utilities, CSS-first APIs), read the tailwind-v4 skill.

The boundary: look vs layout

• Look — colors, typography, radius, shadows, borders, internal padding — belongs to the design system. Consumers never restyle it.
• Layout — positioning, flex/grid placement, gap-*, margins, size constraints (w-*, max-w-*, min-h-*, shrink-0) — belongs to the consumer, through Tailwind utilities on your own wrappers and, when needed, directly on DS components.

className on a DS component is fine for layout (<DialogContent className="max-w-100">) and forbidden for look (<Button className="bg-red-500 text-xs">). If a component's look doesn't fit, use its variants and props; if none fit, escalate for a new variant instead of overriding.

Find what exists — never guess, never rebuild

• Components: browse packages/playground-ui/src/ds/components/ (primitives) and src/domains/ (feature components). Check the exports and existing usage before building anything new.
• Tokens: read the @theme block in packages/playground-ui/theme.css. The namespace tells you the generated utility: --color-x → bg-x/text-x/border-x, --spacing-x → p-x/gap-x/h-x, --text-x → text-x, --shadow-x → shadow-x, --radius-x → rounded-x. Token names drift — confirm them in the file, never use them from memory.

Choosing a class value

Pick the highest rung that fits; each step down needs a reason: