frontend-design

前端设计

这是一项视觉设计规范技能，而非领域工作流技能。领域技能负责规定产品结构、术语、工作流和输出视图。本技能负责视觉质量，必须在该结构内应用。

必须阅读的参考资料

在进行视觉规划或实施之前，必须阅读这两个文件。跳过任一文件都违反技能要求。

• .agents/skills/frontend-design/references/visual-style-references.md
• .agents/skills/frontend-design/references/shadcn-setup-and-theming.md

必需的工作流

1. 阅读当前任务、领域背景和已选领域技能。
2. 如果 .tasks/domain.md 存在，则阅读它。提取品牌颜色、公司名称、领域语气、术语、工作流、实体、状态、角色和约束。
3. 阅读两份前端设计参考资料。
4. 编码前完成设计规划：
   • 愿景：明确领域专属的产品和视觉方向。拒绝通用的 SaaS 紫色、卡片堆叠式仪表板和通用管理后台外壳。
   • 首版功能：包含可用的屏幕、控件、路由、对话框和由 localStorage 支持的状态。
   • 设计令牌：包括主色、次要色／强调色、背景、画布、焦点对比处理、文本、边框、圆角、接触阴影、状态颜色、排版、宽松的间距和无卡片方案。
   • 设计方向：确保品牌颜色的使用、实际 Logo 的使用、宽松的间距、宽松的内部布局密度、圆角控件、强对比的输入框、柔和／紧凑的阴影、尽量减少视觉噪声、默认无卡片，以及精心设计的构图。如果所选领域技能未指定结构，则采用更鲜明的视觉创意，例如不对称构图、有意留白、醒目的强调色层级、动效和富有氛围的背景细节。
5. 通过设计合规检查。
6. 在构建屏幕细节之前，配置 CSS 变量、Tailwind/shadcn 主题令牌和相关 shadcn 组件样式。
7. 使用这些令牌构建 UI。合适时使用 Tailwind；如果 Tailwind 有局限，则编写自定义 CSS 类。自定义 CSS 必须复用全局 CSS 变量、圆角、颜色和阴影令牌。
8. 运行完成前审查，并在结束前进行修改。

不可妥协的要求

• 品牌优先：如果 .tasks/domain.md 提供了品牌颜色，请使用这些颜色。将品牌主色／强调色映射到主要操作、活动导航、选中状态、焦点和链接。根据兼容的色调推导中性色表面、边框、弱化文本和状态色。不要默认使用通用的紫色／蓝色。
• 始终保证前景内容可读：将品牌颜色用于主要、次要、强调、活动和焦点角色，但要单独选择前景／文本颜色以确保易读性。品牌调色板通常不会提供所有文本颜色。所有文本、图标、标签、占位符、徽章、按钮、禁用状态和数据值，都必须与其实际背景有足够高的对比度。当品牌色作为背景时，应为其推导出可读的前景色，而不是重复使用其他品牌色。最低标准优先采用 WCAG AA：普通文本对比度为 4.5:1，大号文本／图标为 3:1。
• 兼容领域技能：如果应用符合选定的业务／领域技能（例如 CPQ、CRM、行业类业务等），请遵循该技能要求的工作流、术语和布局结构。对于领域技能未指定的内容，请采用本技能的视觉规则和构图指导，而不是退回通用管理后台布局。
• 精心设计的构图：每个应用都应体现出有意识的设计。采用统一协调的美学风格，始终一致地使用 CSS 变量；与其采用谨慎、均匀分布的调色板，不如使用鲜明的主色搭配醒目的强调色；在影响显著的时刻运用动效；在不影响工作流清晰度的前提下，偏好不对称或出人意料的构图；通过与品牌兼容的背景和视觉细节营造氛围。
• 使用真实 Logo：首先查看 public/brand/logos/。如果该文件夹中有可用的 Logo 文件，请在页眉或应用主要框架中使用对应的真实 Logo。只有当 public/brand/logos/ 不存在或其中没有可用的 Logo 文件时，才创建或虚构 Logo。
• 默认不使用卡片：尽量完全不用卡片。如果 UI 不用卡片也能正常工作，就不允许使用卡片。占据页面主要区域的带边框圆角表面，即使没有导入 Card，也属于卡片。卡片仅可用于对话框／弹出框／抽屉的内容容纳、简短通知，或在行、分隔线、色调区分无法满足需求时承载真正需要重复呈现的条目。
• 顶层不使用卡片：切勿用大型并列卡片、一组圆角面板，或大型带边框的主视觉／详情容器来构建主页面。顶层结构应采用开放式分区、色调区块、行、分隔线、工作区，或一个开放式核心工作区。
• 默认不使用侧边栏：只有用户明确要求，或选定的领域技能明确要求时，才使用侧边栏。不要仅仅因为应用具有操作性、业务属性、管理后台风格、多步骤流程或多个分区，就添加侧边栏。
• 宽松的间距：采用宽裕的间隔、页边距、行距和分区间距。间距略大可以接受；拥挤、密集或压缩的 UI 则不可接受。
• 内部布局也要宽松：宽松感应延续到行、表格、列表、卡片和复合组件中。当一行中的列过多时，应采用更清晰、层次更丰富的布局，让内容更舒展。内部内容的子项、元数据、操作和标签之间都应留出宽裕的间隔。
• 表格节奏：使用有表面承载的表格时，为表格添加 shadow-xs，并为表头和行设置宽裕的内边距以及更舒展的行高。表格不应显得紧凑、扁平或像密密麻麻的电子表格。
• 默认采用圆角：如果选定的领域技能没有明确要求更锐利或特定的圆角风格，请优先采用明显圆润、现代的设计系统。默认避免使用拘谨的 4px／6px／8px 管理后台圆角。控件、标签、选项卡和关键表面通常应采用明显圆润或胶囊形外观。
• 有个性的字体排印：选择美观、独特、有趣的字体。避免 Arial 和 Inter 等通用默认字体。如果产品支持，应优先将有个性的展示字体与精致的正文字体搭配使用。字体排印应提升 UI 质感，而不是让它看起来像默认的入门模板应用。
• 一个主导工作区：首屏应聚焦于一个明确的操作对象或工作区。不要试图一次展示整个产品。
• 主要区域不使用带边框的容器：不要将主工作区、主视觉、检查器或详情栏变成大型带边框的圆角面板。优先采用开放式布局、分栏、色调区块、分隔线，或使用抽屉／底部弹层呈现次要详情。
• 优先使用 Token 配置 shadcn 和 CSS：在编写组件前，先配置 app.css／全局 CSS 变量、Tailwind 主题值以及相关的 shadcn 组件样式。不要接受 shadcn 的默认颜色或组件样式作为最终设计。shadcn 组件只是基础构件；始终根据应用的 Token、间距、对比度、圆角、阴影和交互规则自定义其类名／样式。并非所有视觉决策都必须使用 Tailwind；如果自定义 CSS 能打造更具特色、更简洁、更精致的 UI，就应使用，同时沿用同一套 CSS 变量和主题 Token。
• 明确且柔和的对比度：如果存在表面，它首先应通过色调与画布区分，其次通过边框，最后才是阴影。白色或近白色表面搭配浅淡边框不合格。
• 交互表面的对比度：所有可编辑控件都必须一目了然。普通文本输入框、下拉选择框、多行文本框、组合框、日期字段、搜索字段、命令栏控件和 shadcn 表单控件，在浅色模式下都必须使用近白色或很浅的有色背景，在深色模式下都必须使用近黑色背景。不要只调整下拉选择框，却让普通输入框与页面同色。控件不得使用 bg-transparent、bg-background、bg-muted，也不得与页面／面板使用相同的填充色。浅色模式下的 --input 必须明显比 --background 更亮；深色模式下则必须明显比画布更暗。搜索／筛选控件应是屏幕上最清晰的输入表面之一。
• 必要时的面板／卡片对比度：如果确实无法避免卡片式表面，包括摘要面板、实时摘要卡片、检查器、通知和重复条目容器，在浅色模式下必须使用明显对比的近白色或很浅的有色背景，在深色模式下则必须使用近黑色背景。有色页面上使用相同填充色的面板不合格，即使边框清晰可见也不例外。
• 存在页眉时的样式：如果应用有页眉／顶栏，浅色模式下优先使用半透明的近白色或很浅的有色表面；深色模式下优先使用近黑色表面，并搭配 backdrop-blur-md 和约 70-80% 的不透明度。页眉仍必须与页面保持足够的对比度，并在 Logo 可用时使用真实 Logo。
• 必须使用侧边栏时的色调和空间：如果选定的领域技能要求使用侧边栏，请用由主色推导出的更深色调作为侧边栏背景或关键侧边栏表面。侧边栏必须足够宽，以容纳标签、徽章和活动状态；不要裁切文本或将操作挤到边缘。为条目设置宽裕的内边距和清晰的垂直节奏，仅对次要描述进行有意截断。
• 阴影仅用于表现接触深度：不要将 shadow-sm、shadow-md 和 shadow-lg 作为普通布局表面的默认阴影。按钮和其他小型交互元素优先使用 shadow-2xs，卡片／表格等同类容器表面使用 shadow-xs，弹出框和横幅使用 shadow-xl，对话框使用 shadow-2xl。仅在需要时使用柔和、紧贴边缘的深度效果。柔和不意味着阴影范围难以察觉；为增强对比度，阴影仍可使用清晰的灰色。深度应表现为边缘接触，而非悬浮感。
• 领域特异性：如果替换领域名称和标签后，UI 看起来依然完全不变，则不符合要求。

设计合规检查

所有回答都符合要求后，再开始编写代码。

• 我是否阅读了 .tasks/domain.md，并在其中提供品牌颜色时进行了总结？
• 我是否检查了 public/brand/logos/，并计划在其中存在实际 Logo 文件时使用该文件？
• 我是否阅读了两篇前端设计参考文档？
• 我是否定义了具体的全局 CSS 变量、Tailwind/shadcn 令牌和 shadcn 组件样式更新？
• 我是否遵循了必需的领域技能结构，并在领域技能留有空间时采用自主设计的视觉构图？
• 我是否为颜色、动态效果、空间构图和背景氛围选择了明确的设计方向，而非通用外壳？
• 这个 UI 能否完全不用卡片来构建？如果不能，剩下的卡片是否都属于允许的狭义情况，且确实不可避免？
• 我是否没有使用顶层卡片？
• 除非有明确要求或所选领域技能要求，我是否避免使用侧边栏？
• 首屏是否聚焦于一个主要工作区域，而非标题 + 筛选器 + KPI 条 + 卡片网格 + 表格？
• 我是否避免了大型带框的主视觉、详情或检查器区域？
• 布局是否通透、留白充足，而非拥挤？
• 内部内容是否也疏朗通透：行、表格、卡片和元数据块没有过于拥挤或列数过多？
• 如果没有领域技能覆盖圆角要求，UI 是否明显采用圆润的风格，而非含糊的企业级 4/6/8 圆角？
• 字体排版是否独特且经过精心设计，而非默认或流于一般？
• 页面背景、画布、导航栏界面和任何焦点区域在缩略图大小下是否有清晰区分？
• 所有前景色在其背景上是否都清晰易读，包括品牌色区域、禁用状态、标签、占位符、徽章、按钮、图标和弱化文本？
• 输入框、搜索/筛选控件、表格和页眉/导航栏界面与页面背景之间是否有足够的色调区分？
• 在浅色模式下，所有可编辑控件（包括普通文本输入框和选择框）是否都实际使用了接近白色或非常浅的着色背景，而非与页面同色的填充？
• 可编辑控件是否没有使用 bg-transparent、bg-background、bg-muted 或与页面/面板同令牌的填充？
• 摘要/检查器/实时摘要面板是否使用了清晰的近白色或浅色表面，而非与背景融为一体？
• 如果有页眉/顶栏，是否使用了清晰的半透明效果、背景模糊，并具备足够的对比度？
• 如果展示了表格，是否使用 shadow-xs，并为表头和行设置了充足的内边距？
• 如果需要侧边栏，是否采用了源自主色的较深色调，并有足够的宽度、内边距、行高和溢出处理？
• 阴影是否仅用于表现边缘接触处的层次？
• 设计是否体现了该领域和任务的特点？

实现规则

• 优先使用顶栏、标签页、分段控件、面包屑、命令行、分步流程、抽屉、底部弹出面板、对话框或详情路由，而不是侧边栏。
• 添加任何卡片式容器之前，先尝试使用开放式间距、字体排版、分隔线、行、色调区块、表格、抽屉、底部弹出面板、对话框或详情路由。
• 在表格和基于行的视图中，如果这样能让 UI 更通透、易读，应优先减少列数、丰富行内容、加大行间距，并采用更清晰的纵向堆叠布局。
• 展示型表格通常应使用 shadow-xs，并为表头和表体行留出充足内边距，而不是仅依赖边框。
• 详情视图应优先采用内嵌分栏布局、选中行、分隔线、色调区块、抽屉或底部弹出面板，然后才考虑使用带边框的面板。
• 如果导入了 Card 组件，或仍保留卡片式容器，请在附近添加内联说明，解释为何在允许的情况下无法避免使用它。
• 使用易读的 UI 字体。除非领域明确需要这类风格，否则避免使用打字机风格或博客风格的字体。
• 在不影响必要工作流结构或操作清晰度的情况下，采用更有表现力的构图、更鲜明的强调层级，以及更具氛围感的背景。
• 通过色调、间距和层级区分界面区域，而不是到处都用边框和方框。
• 优先确保前景色和文本颜色的对比度。除非品牌主色、次色或强调色在对应表面上清晰易读，否则不要将其用作正文颜色。
• 为输入框、选择框、文本区域和搜索框设置明确且有对比度的填充色；不要让它们透明或与页面同色。
• 为摘要、检查器和实时摘要面板设置明确且有对比度的填充色，前提是这些面板确实无法避免。
• 如果存在标题栏或顶栏，应使用由设计令牌驱动的半透明背景、backdrop-blur-md 和清晰的对比度，而不是使用纯色条带。
• 对于必需的侧边栏，应设置足够的宽度和项目高度，以便标签易读、活动状态清晰，且徽章和操作项不会被裁切。
• 如果确实无法避免使用卡片，应使其色调与画布有明显区别，并添加柔和但清晰可见的边框。同样是白色的弱对比卡片不合格。
• 只添加实际工作流所需的 shadcn 组件。
• 始终自定义 shadcn 组件的类和样式，使输入框、按钮、表格、标签页、对话框、底部弹出面板、弹出层和导航符合此应用的视觉规则，而不是沿用默认组件样式。
• 当 Tailwind 工具类无法满足布局、背景、间距和组件样式需求时，使用自定义 CSS 类；通过全局主题中的 var(...) 颜色、圆角、边框和阴影令牌驱动这些类。
• 确保所有按钮、链接、菜单、对话框、标签页、表单、路由和由 localStorage 支持的状态都能正常使用。

完成前审查

在实现中搜索 Card、card、bg-card、shadow-md、shadow-lg、shadow-xl、重复的 rounded-* border 包装器，以及较大的 rounded-* border p-* 区块。

如有以下情况，请拒绝并修改：

• 存在任何顶层卡片。
• 存在任何可以避免的卡片。
• 任何较大的圆角边框区域看起来像主视觉卡片、检查器卡片或详情卡片。
• 存在侧边栏，但用户未明确要求，且所选领域技能也未要求。
• 首屏大部分由面板、卡片、KPI 区块、辅助框或权重相同的模块构成。
• 表面的区分主要依赖边框，而非色调。
• 大面积使用相同或近似白色的面板，导致主要表面彼此混为一体。
• 任何文字、图标、标签、占位符、禁用状态文本、徽章、按钮文本、表格文本或数据值与背景的对比度不足，难以阅读。
• 使用品牌色时，未根据实际背景推导出高对比度的前景色／文本颜色。
• 输入框、搜索／筛选控件、数据行或页眉／导航栏与页面背景融为一体。
• 浅色模式下的可编辑控件不是近白色或非常浅的色调，因此无法清晰辨认。
• 下拉框有足够对比度，但普通文本输入框仍与页面同色或颜色暗淡。
• 可编辑控件使用 bg-transparent、bg-background、bg-muted，或与页面或面板相同的设计令牌／填充色。
• 摘要／检查器／实时摘要卡片或面板使用与页面相同的填充色，而非近白色／浅色调的对比表面。
• 存在页眉／顶栏，但没有明显的半透明 backdrop-blur-md 样式，或与页面融为一体。
• 行／表格内容拥挤、列过多，或首列和元数据区块内间距过紧。
• 已呈现的表格缺少 shadow-xs，或表头／行的内边距过小。
• public/brand/logos/ 中存在可用的徽标文件，但页眉仍使用占位徽标，或无理由地不使用徽标。
• .tasks/domain.md 中的品牌色未体现在主要／活动／焦点状态样式中。
• 在工作流允许的情况下，UI 默认采用通用管理后台框架，而非经过设计的布局。
• 必需的侧边栏使用了浅淡、薄弱的表面色，而非基于较深主色推导出的色调。
• 必需的侧边栏会裁切标签、徽章、图标或操作按钮，或条目内边距／行高过于紧凑。
• UI 使用了模糊的企业风格中等圆角控件，而领域技能并未要求这种设计。
• 字体采用通用配置，或产品适合使用有特色的标题／正文字体组合，却未采用。
• 未在组件样式设计之前配置主题变量。
• shadcn 组件未经应用专属的类名／样式定制便直接使用。
• 自定义 CSS 使用硬编码的一次性颜色／圆角／阴影，而非全局主题变量。
• 界面显得拥挤，或所有模块的视觉权重都相同。
• UI 看起来像入门级管理模板、Bootstrap 仪表盘或通用 AI／SaaS 应用。