Mastra 前端界面开发指南基于 mastra/playground-ui 设计系统的组合式构建【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇技术指南以 Mastra 仓库中.claude/skills/mastra-frontend/SKILL.md为核心骨架系统讲解如何基于mastra/playground-ui设计系统构建 Mastra 应用界面。你将掌握「外观Look与布局Layout的职责边界」「theme.css 设计令牌Token与 Tailwind v4 工具类的映射规则」「组件/变体/工具类的选择阶梯」「主题契约与 Wiring 接入方式」以及「代码评审自查清单」从而在不改动设计系统的前提下用组合而非重写的方式搭建出风格统一的 Mastra 应用 UI。设计系统与 Skill 的适用范围Mastra 的每个应用界面都由mastra/playground-ui设计系统组装而成。该包在仓库中的源码位于 packages/playground-ui按 README 的说明它提供 Mastra Studio 所需的「可复用 React 组件、Hooks、域组件domains与设计令牌」覆盖日志logs、记忆memory、指标metrics、追踪traces与 Agent 管理agent management等界面模块。mastra-frontend 这个 Skill 的适用场景是在本仓库内或任何外部消费该设计系统的应用中创建或修改任意应用 UI——页面、组件、样式或令牌。但有两个明确边界文档站点docs site有自己的样式体系不在本 Skill 范围内修改设计系统本身令牌、ds/组件、变体是另一个需要明确批准的任务普通界面开发不得触及。一个核心心智模型构建一个界面是「组合工作」——挑选现有组件、用布局工具类排列它们、让设计系统负责外观。如果开始手写颜色、字号、阴影或圆角就说明已经偏离了「快乐路径happy path」。此外如果涉及 Tailwind v4 的机制性内容重命名、动态工具类、CSS-first API应另行参考tailwind-v4Skill。边界外观Look与布局Layout这是整个设计系统使用规则中最重要的分界线维度归属方内容消费者可否修改Look外观设计系统颜色、字体、圆角、阴影、边框、内部内边距禁止重写Layout布局消费者定位、flex/grid 排布、gap-*、外边距、尺寸约束w-*、max-w-*、min-h-*、shrink-0通过 Tailwind 工具类自由使用在 DS 组件上使用className时规则非常具体允许用于布局例如DialogContent classNamemax-w-100禁止用于外观覆盖例如Button classNamebg-red-500 text-xs。如果某个组件的观感不满足需求正确做法是使用它的变体variants和 props如果变体也不够用应当上报并申请新变体而不是通过className覆盖。先找现成组件绝不猜测、绝不重建组件目录原语组件primitivespackages/playground-ui/src/ds/components/包含Button、Dialog、Badge、Input、Select、Tabs、Table、DropdownMenu、Tooltip、Card、Notice、Avatar、Skeleton、Switch、Checkbox、RadioGroup、Slider、Textarea、CodeBlock、MarkdownRenderer、Combobox、Command、Popover、HoverCard、Drawer、ScrollArea、Collapsible等几十个基础构件域组件feature componentspackages/playground-ui/src/domains/目前包含memory/记忆、metrics/指标、traces/追踪三类面向业务功能的组件。在新建任何组件之前先浏览这两个目录并检查其导出与既有用法永远不要凭记忆猜测或重复造轮子——「新增一个与现有ds/或domains/组件重复的组件」本身就是评审环节要抓的坏味道。令牌Tokens的查找方式读取packages/playground-ui/theme.css中的theme块。令牌的命名空间决定了它生成的工具类令牌前缀生成的工具类示例--color-xbg-x/text-x/border-x--spacing-xp-x/gap-x/h-x--text-xtext-x--shadow-xshadow-x--radius-xrounded-x例如theme.css中的--color-surface4可写作bg-surface4、text-surface4或border-surface4--spacing-4可写作p-4、gap-4、h-4。令牌名称会漂移——务必在文件中确认绝不要凭记忆使用。选择一个类值的五级阶梯当需要某个类值时从最高档开始选择每往下一档都需要理由DS 组件或其变体——你需要的观感大概率已经存在由theme.css生成的theme工具类——例如bg-surface4、text-ui-md、shadow-card、rounded-lgTailwind v4 动态工具类——当值能映射到间距刻度时使用例如min-w-100、size-6、grid-cols-15这些由--spacing-*刻度驱动局部 CSS 自定义属性——用于限定在单个组件内的运行时值通过简写语法消费例如bg-(--row-bg)、text-(color:--agent-color-fg)方括号任意值square-bracket arbitrary value——仅限有充分理由的一次性用法例如max-h-[calc(100dvh-3rem)]。这条阶梯的本质是能由设计系统承担的就不要自己写。每降一级定制性增强但与设计系统的耦合度管理成本也随之上升。主题契约Theme Contracttheme.css的变量是公开 API新增一个变量会为每个消费者生成对应工具类因此存在强约束未经明确批准不得修改theme.css或packages/playground-ui/src/ds/tokens/*.ts。如需新增令牌流程是记录用例 → 说明为何局部 CSS 自定义属性不够用 → 等待设计团队决策仅运行时使用或单组件使用的值应当写成普通 CSS 自定义属性不会生成工具类并通过bg-(--var)方式消费而不是新增theme令牌当 JavaScript 需要读取主题值时应通过CSS 变量读取如var(--color-surface4)、getComputedStyle禁止使用resolveConfig或 JS 令牌导入来处理样式。从theme.css的源码头注释可以印证其设计意图该文件以未编译形态随包发布为mastra/playground-ui/theme.css让消费方的 Tailwind 通过theme读取并生成本地工具类而无需重新声明令牌同时文件内只放令牌不包含import tailwindcss、plugin、layer、apply否则会破坏原生导入。所有颜色保持oklch色彩空间。Wiring如何接入与消费设计系统全局样式入口packages/playground-ui/src/index.css是包的样式装配点import tailwindcss引入 Tailwindimport ../theme.css引入令牌即theme.css以原始形式单独发布的原因声明暗色变体custom-variant dark (:is(.dark *))。消费者侧见 packages/playground-ui/README.md的接入方式是在应用入口一次性导入样式然后使用显式的components/*、domains/*、hooks/*、icons/*、primitives/*、store/*、tokens、utils/*入口点而不是包根导入import mastra/playground-ui/style.css; import { Button } from mastra/playground-ui/components/Button; export function SaveButton() { return ButtonSave/Button; }主题翻转机制调色板在:root中默认为暗色html.light切换语义变量对应theme.css中:root与html.light两大块定义暗/亮主题下--surface*、--accent*、--neutral*、--badge-*、--chart-*、--brand-green-*等语义令牌成组翻转主题切换通过语义令牌自动完成——永远不要在语义令牌上写dark:颜色覆盖dark:仅保留给极少数的结构性差异。合并类名必须用 cn()构建条件类名或合并类名时使用cn()对外消费者从mastra/playground-ui导出包内部从packages/playground-ui/src/lib/utils.ts导出其实现为twMerge(clsx(inputs))关键点cn()内部的twMerge来自packages/playground-ui/src/lib/tw-merge-config.ts它通过extendTailwindMerge扩展了 DS 刻度颜色、间距、圆角、行高、阴影、字号及h-*/w-*/size-*/min-*/max-*尺寸组因此text-ui-md这类 DS 工具类才能正确合并直接从tailwind-merge导入twMerge会导致合并错乱手动字符串拼接同样不可取。包内部同样适用packages/playground-ui中位于ds/之外的代码例如src/domains/本身就是ds/原语的消费者上述所有规则对它同样生效——这意味着设计系统的内部实现也受同一套纪律约束。Review Smells评审时要抓的坏味道清单以下是代码评审阶段需要重点排查的问题清单可直接作为自查模板#坏味道正确做法1在 DS 组件上用className覆盖外观bg-*、文字颜色/字号、边框颜色、rounded-*、shadow-*、内边距使用组件的变体与 props或上报申请新变体2新建了与现有ds/或domains/组件重复的组件复用已有组件3bg-[#hex]、text-[15px]、p-[13px]存在对应令牌或刻度值改用theme工具类4令牌名在theme.css中不存在凭记忆猜的去theme.css确认5bg-[var(--x)]改用bg-(--x)简写语法6min-w-[400px]等能被 4px 整除的尺寸使用间距刻度如min-w-1007模板字符串类名片段bg-${tone}-500将 props 映射为完整类名字符串8为单个组件的局部状态新增--color-*或--animate-*令牌使用普通 CSS 自定义属性不生成工具类9在语义令牌上写dark:颜色覆盖调色板已通过html.light自动翻转10从tailwind-merge直接导入twMerge或手动拼接类名使用cn()内部扩展了 DS 刻度11装饰性动画未带motion-safe:/motion-reduce:动画必须尊重用户的减弱动态偏好总结一个可执行的界面构建流程将本 Skill 提炼为可落地的构建流程查找而非创建在packages/playground-ui/src/ds/components/与packages/playground-ui/src/domains/中寻找可用组件确认其导出与用法确认令牌打开packages/playground-ui/theme.css的theme块按命名空间映射工具类--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按五级阶梯选值DS 组件/变体 →theme工具类 → v4 动态工具类间距刻度可映射时→ 局部 CSS 自定义属性bg-(--var)→ 方括号任意值仅一次性特殊场景严守边界DS 组件上的className只做布局max-w-100外观交给变体与 props需要新令牌走审批流程JS 取主题值用 CSS 变量正确接入应用入口导入mastra/playground-ui/style.css类名合并一律走cn()暗/亮主题依赖语义令牌自动翻转评审自查对照上节 11 条 Review Smells 逐条检查确保没有外观覆盖、重复组件、凭记忆的令牌名、[var(--x)]写法、不可整除的任意值、模板字符串类名、裸twMerge导入等问题。遵循这套流程任何开发者都能以「组合」而非「重写」的方式在 Mastra 生态Studio、Playground、外部消费应用中构建出观感统一、可长期维护的前端界面。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考