用途:本技能用于在创建或修改 Mastra 应用 UI 时,按照 @mastra/playground-ui 设计系统搭建前端界面。核心理念是“组合”:选用已有组件,用布局工具类排列,外观交给设计系统;手写颜色、字号、阴影、圆角即偏离推荐做法。修改设计系统本身(tokens、ds/ 组件、variants)属于需明确批准的独立任务。Tailwind v4 机制问题应查阅 tailwind-v4 技能。
边界——外观与布局:颜色、排版、圆角、阴影、边框、内部内边距属于设计系统,使用方不应重新设置样式。定位、flex/grid 摆放、gap-、外边距、尺寸约束(w-、max-w-、min-h-、shrink-0)属于使用方。DS 组件的 className 可用于布局(如 <DialogContent size="xl" className="h-[80vh]">),不可用于外观(如 <Button className="bg-red-500 text-xs">);外观不合适时使用其 variants 与 props,仍不满足则应申请新 variant。
查找现有资源:组件位于 packages/playground-ui/src/ds/components/(基础组件)和 src/domains/(功能组件),新建前先查看导出与既有用法。Tokens 见 packages/playground-ui/theme/ 下的 @theme 块,语义别名在 theme.css;命名空间决定生成的工具类,但名称会变动,须在文件中确认。
类值选择优先级:DS 组件或 variant → theme.css 生成的工具类 → 对应间距比例的 v4 动态工具类(如 min-w-100)→ 局部 CSS 自定义属性(如 bg-(--row-bg))→ 仅在合理的一次性场景使用方括号任意值(如 max-h-[calc(100dvh-3rem)])。
主题契约:theme.css 变量即 API,未经明确批准不得修改 theme.css、其下的 theme/ 分层或 ds/tokens/*.ts。运行时或单组件值使用普通 CSS 自定义属性,不用新 @theme token。JS 需要主题值时读取 CSS 变量,不要用 resolveConfig 或 JS token 导入。
接线:src/index.css 引入 Tailwind 与 theme.css 并声明暗色变体;调色板在 :root 默认暗色,html.light 翻转语义变量,主题通过语义 token 自动切换,不要对语义 token 写 dark: 颜色覆盖。条件或合并类名用 cn(),其 twMerge 已扩展 DS 比例;不要直接从 tailwind-merge 导入 twMerge。
代码气味与限制:DS 组件上的外观覆盖、重复组件、hex/px 任意值、猜造的 token 名、bg-[var(--x)](应写 bg-(--x))、可用 4px 比例却用 min-w-[400px]、模板字符串拼类名、为单组件新增 token、语义 token 的 dark: 覆盖、未用 cn() 的合并、无 motion-safe:/motion-reduce: 的装饰动画,以及 mono 字体的误用(标识符、时间戳、时长用 <Txt font="mono">,代码用 InlineCode/CodeBlock,其他数字用正文加 tabular-nums)。具体命令与安装步骤资料中暂未提供。