specsfy-specialist-design-system

Specsfy 专家设计系统

适用场景

此技能用于管理使用方项目的 DESIGNSYSTEM.MD 文档。它定义视觉语言、外壳、界面层组合、状态，以及界面中呈现的业务规则。该文档为 UX、UI、界面体验和 React 组件提供指导。

在创建或审查屏幕、CRUD 流程、导航、表单或全局组件之前使用。文档不存在、已过时或与已设计的屏幕冲突时，也应使用此技能。

请勿使用此技能来编目组件、props 或本地文件。此类记录应归入 INTERFACE.md，其中应指向宏观设计选择，而非重复这些内容。

必需来源

按以下顺序阅读：

1. 使用方项目根目录中的 DESIGNSYSTEM.MD（如果存在）。
2. .specsfy/templates/DESIGNSYSTEM.MD，用于创建缺失的来源文档。
3. INTERFACE.md，了解已记录的组件和屏幕。
4. 与交付内容相关的 .specsfy/STACK.md、清单文件、路由、屏幕、权限和领域规则。

如果来源文档不存在，请将受管理的模板复制到 DESIGNSYSTEM.MD，并仅填写已确认的上下文。不要用泛泛的文字掩盖信息缺口。

流程

1. 确认产品、模块、界面和受影响的流程。
2. 将需求与 DESIGNSYSTEM.MD 进行比较，并保留现行规则。
3. 如果对方未说明视觉方向，请应用文档中的默认设置，并将其记录为本次交付的默认方向。
4. 如果对方提出不同的方向，请记录例外、适用范围以及被替代的规则。单个屏幕的例外不会改变整个产品。
5. 仅在规则属于宏观范围时更新文档。具体组件和屏幕应记录在 INTERFACE.md 中。
6. 在提供 UX、UI 或实现指导之前，梳理该界面的规范场景。
7. 返回已阅读的文件、应用的规则、记录的例外和涵盖的场景。

每次视觉交付都应在开发过程中进行审查，即使对方没有提出要求。请在相关视口和状态下检查边框、间距、边距、内边距以及系统字体。将审查方法、结果和调整记录在任务的 VISUAL 项中。

标准

SaaS 必备默认规范

没有相反的视觉设计要求时，请采用以下布局：

• CRUD 列表：PageHeader + 实用摘要 + DataGrid。根据数据量或业务领域的需要，使用搜索、筛选、排序、分页、选择和行级操作。
• 详情：PageHeader + DetailLists；根据业务领域的需要，显示状态、下一步操作以及关联信息或活动。
• 创建和编辑：PageHeader + 响应式双栏表单分区，包含上下文栏和字段面板。
• 表单：字段上方显示标签，提供上下文帮助，保留已填写的值并显示提交状态。
• 字段错误：使用红色边框、背景或语义图标，在字段下方显示错误消息，建立语义关联，并将焦点移至第一个错误处。
• 多个错误：在顶部显示摘要，并提供指向受影响字段的链接。
• 页面：根据工作流支持的状态，涵盖 loading、空状态、错误、成功、无权限、部分内容和未保存状态。
• 面包屑：应用中的每个页面都必须显示面包屑，并在模块和当前标题之前显示当前团队名称。在 Laravel 中，复用布局中已有的 Breadcrumb 或 Breadcrumbs 及其路由类型。
• DataGrid：整行可点击以打开详情，同时提供等效的键盘操作，并通过 TableRowAction 或等效机制保护内部控件。
• CRUD：所有页面复用同一个组件化的 PageHeader；列表使用全宽 DataGrid，显示 ID 列，并在行内提供编辑和删除按钮。点击行链接可前往详情，但不能拦截按钮操作。
• 常用的标题、表格、行、操作、表单、状态和反馈组件都应记录在 INTERFACE.md 中，并在新建实现前优先复用。

这些默认规范并不意味着界面应当千篇一律。个性体现在数据层级、领域用语、排版、设计令牌、节奏、状态、对比度和外壳的使用上。布局应当提供信息并引导用户完成任务。

仪表板和常用模块

如果交付内容包含仪表板，请使用 PageHeader、时间段或范围选择器、筛选器、简短的 KPI 指标栏（包含数值、单位、时间段、对比和数据来源），然后展示主要趋势或分布，以及用于调查的详细列表或 DataGrid。每项指标和可视化都应声明加载、空状态、错误和更新状态，并为图表提供文本或表格替代方案。

基础控件使用 shadcn/ui primitives；如果免费的 ReUI 模块适用于任务，则用于组合 CRUD 和仪表板布局。根据产品调整设计令牌、数据、权限、无障碍性和用语。在 INTERFACE.md 中记录来源、状态和使用方。

创建和编辑表单

将创建和编辑表单组织成独立分区。每个分区左侧呈现上下文，右侧呈现字段面板。在面板中，相关字段在宽屏断点下使用两列布局，在移动端使用单列布局；较长的字段、上传控件和错误信息可以占满整行。页脚应将取消和保存按钮放在操作结果附近。

面包屑和外壳

每个页面都应在全局外壳中渲染 Breadcrumb。路径应显示当前团队、模块和当前页面，并为之前的项目使用真实标签和有效链接。在 Laravel 应用中，找到并复用布局中已有的 Breadcrumb 或 Breadcrumbs 组件及其条目类型；只调整必要的布局以加入团队信息，不要重复实现基础组件。在移动端也应显示团队和当前页面。

每项交付都必须覆盖的场景

请参阅模板中的 Cenários canônicos 部分，并在 DESIGNSYSTEM.MD 或交付规格中记录适用范围：

• 包含记录的列表；
• 空列表；
• 包含状态和操作的详情；
• 有效创建；
• 有效编辑；
• 创建或编辑时出现字段错误；
• 无权限；
• 加载失败；
• 未保存的更改（适用于编辑场景）；
• 破坏性操作的结果（适用于删除或取消场景）。

对于每个场景，请说明前置条件、操作、响应、视觉状态、焦点、消息和下一步。

边界与交接

• UX 根据此来源定义流程、信息架构和任务用语。
• UI 根据此来源定义设计令牌、层级、视觉构成和状态。
• React 组件在阅读此来源和 INTERFACE.md 后，选择兼容的基础组件和组合方式。
• 界面体验技能负责协调交付；启动界面前必须先加载 DESIGNSYSTEM.MD。

反模式

• 用户需要比较记录时，使用卡片墙。
• 领域包含不同信息组时，使用没有分区的表单。
• 在移动端使用两列布局，或使用将字段、帮助信息和错误分开的网格。
• 仅使用占位符作为标签。
• 错误仅通过图标、颜色或远离字段的 Toast 提示。
• 页面缺少 PageHeader、空状态或恢复路径。
• 仪表板显示数字，却没有问题、时间范围、单位或后续操作。
• 仪表板使用没有层级或探索路径的卡片墙。
• 使用 ReUI 区块或 shadcn/ui 基础组件时，未根据产品的数据、状态、权限和设计令牌进行调整。
• 创建新设计令牌或组件前，未检查文档和 INTERFACE.md。
• 将局部视觉例外登记为全局规则，却未明确适用范围。
• CRUD 页面存在重复表头、狭窄的 DataGrid、隐藏的 ID，或行内缺少编辑和删除操作。

验证

交接前，请检查：

• 消费项目的根目录中存在 DESIGNSYSTEM.MD，并且包含分类、策略、默认值、状态、场景和历史记录。
• 列表使用 DataGrid 和 PageHeader。
• 每个页面都有 Breadcrumb，其中包含当前团队名称、模块和当前页面。
• Laravel 复用布局中已有的 Breadcrumb 或 Breadcrumbs。
• 详情页使用 DetailLists 和 PageHeader。
• 创建和编辑页面使用分区和上下文列；在较宽的断点下，字段面板采用两列布局，在移动端采用单列布局。
• 字段错误以红色显示在字段下方，并具有语义关联。
• 默认方向或例外情况已注明适用范围。
• INTERFACE.md 仅包含此交付的本地记录。
• 规格和任务涵盖状态、权限、焦点、消息和返回路径。
• 如果存在仪表板，则应包含筛选器、指标上下文、可视化的无障碍替代方案和详细探索路径。
• shadcn/ui 基础组件和 ReUI 区块的来源、状态和使用方已记录在 INTERFACE.md 中。
• 每项任务都在 EVIDENCE 之前完成 VISUAL 项，并检查边框、间距、外边距、内边距和排版；若不存在界面，则提供具体理由。

如已实现，请运行技术栈对应的测试和验证工具。对于 Specsfy 技能，请运行 quick_validate.py 和 monorepo 测试套件。

相关技能

• references/standards.md
• skills/templates/DESIGNSYSTEM.MD
• skills/templates/Interface.md
• specsfy-specialist-interface-experience
• specsfy-specialist-ux-design
• specsfy-specialist-ui-design
• specsfy-specialist-react-ui-components