sgds-workflow

SGDS 技能工作流

本技能梳理了可用的 SGDS 技能及其使用顺序。不确定该使用哪项技能，或想了解各项技能如何配合使用时，请从这里开始。

---

你是在开发新应用，还是在现有应用上工作？

---

新应用

按顺序完成以下阶段。在每个阶段中，按需阅读所引用的技能。

阶段 1 — 项目设置（始终首先进行）

→ 阅读 sgds-getting-started

涵盖内容：Inter 字体、CSS 导入顺序（themes/day.css → css/sgds.css → css/utility.css）、组件注册，以及两种应用布局模板（简单应用与侧边栏应用）。

在编写任何组件或页面代码之前，请完成此技能中的全部四个步骤。

---

阶段 2 — 构建 UI（按需同时阅读）

构建过程中，这些技能是日常参考资料。你会经常在它们之间切换——根据当前构建内容，阅读相关技能即可。

→ sgds-components — 所有 <sgds-*> Web 组件（从 accordion 到 tooltip）。在使用纯 HTML 构建任何内容之前，先查看这里。如果有适合需求的 SGDS 组件，请使用它。

→ sgds-utilities — 所有 sgds: Tailwind 工具类：间距、布局网格、排版、颜色、边框、不透明度。用于设置组件之间及周围的布局、间距和样式。

→ 应用外壳 — 必需的页面框架和布局模板（简单应用与侧边栏应用），包括粘性页眉、侧边栏列宽设置和容器类参考。当 sgds-getting-started 的第 4 步不够详细时，请阅读此文档。

→ sgds-theming（可选）— 品牌颜色覆盖、夜间／深色模式和字体自定义。当应用需要超出默认 SGDS 样式的视觉自定义时，请与上述技能一起阅读。如果默认样式可以接受，则跳过。

---

阶段 3 — 组装页面和区块（构建完整页面或页面区域时）

→ sgds-blocks — 用于页面区域和布局的可复用 UI 区块。包括：主视觉区域、CTA、功能区块、卡片网格、统计信息展示、页面页眉、筛选器、表单、详情卡片、应用外壳和自定义区块。当用户要求构建着陆页、仪表板、特定页面区域（例如“我需要一个行动号召”）或任何页面布局时，请从这里开始。

→ sgds-patterns — 用于统一文本样式的排版和文本模式：标题、展示文本、内容标题、列表和段落。设置内容文本样式、创建文本层次结构，或用户提到“做一个漂亮的标题”或“设置页面文本样式”时，请使用此技能。

→ sgds-templates — 可直接使用的完整页面布局：仪表板、登录页、表单页、列表页、设置页。用户要求构建完整页面时，请从这里开始。

→ sgds-forms — 表单提交、约束验证、hasFeedback、setInvalid 和 FormData。涉及使用 SGDS 组件的任何 <form> 时，请阅读此技能。

---

阶段 4 — 数据可视化（需要图表或仪表板时）

→ 阅读 sgds-data-visualisation

涵盖 ECharts 设置，以及如何将 SGDS 调色板应用于图表。只有当应用包含图表、图形或数据仪表板时才需要。

---

现有应用

无需重新阅读设置技能。直接前往涵盖当前任务的技能。

快速检查 — 如果工具类或组件看起来无法正常工作，请先确认设置已完成：

• 在主 CSS 文件中按此顺序导入 themes/day.css → css/sgds.css → css/utility.css
• utility.css 由 Tailwind 处理（而非作为普通 JS 导入）
• JS 入口文件中包含 import "@govtechsg/sgds-web-component"

确认设置无误后，请使用下表查找对应技能。

---

技能地图 — 每项任务应阅读的内容

你需要做什么	应阅读的技能
从头开始搭建新的 SGDS 项目	sgds-getting-started
使用任何 <sgds-*> 组件	sgds-components
应用间距、颜色、排版和布局工具类	sgds-utilities
构建应用外壳（masthead、mainnav、页脚、容器）	应用外壳
更改品牌颜色、启用深色模式、更改字体	sgds-theming
构建页面区块：hero、CTA、卡片、功能、统计、筛选器、表单或自定义区块	sgds-blocks
设置文本样式：标题、展示文本、列表、段落	sgds-patterns
构建完整页面（仪表板、登录、列表、表单、设置）	sgds-templates
添加表单验证、读取 FormData、使用 setInvalid	sgds-forms
添加图表、图形或数据仪表板	sgds-data-visualisation

---

面向 AI Agent

1. 当用户说“我正在构建新的 SGDS 应用”或“我该从哪里开始”时，务必先从 sgds-getting-started（第 1 阶段）开始，再阅读其他技能。
2. 在第 2 阶段，不要一开始就阅读全部三项技能——需要组件时阅读 sgds-components，需要样式或布局时阅读 sgds-utilities。它们是参考资料，无须按顺序阅读。
3. sgds-theming 属于第 2 阶段——需要品牌设置、深色模式或字体自定义时，与组件和工具类文档同时阅读。不要将其视为单独的顺序步骤。
4. sgds-blocks 和 sgds-patterns 是第 3 阶段可并行使用的技能——根据用户请求按需阅读（页面区块使用 blocks，文本样式使用 patterns）。
5. sgds-templates 和 sgds-blocks 可以单独使用，也可以配合使用——用户可能需要其中一项、两项或都不需要，具体取决于项目进展。
6. 只有涉及 <form> 元素时才需要 sgds-forms。不要主动为非表单 UI 阅读它。
7. 只有在明确提出图表或图形需求时才需要 sgds-data-visualisation。
8. 对于现有应用，请使用技能地图表直接定位。除非遇到设置问题，否则不要重新阅读 sgds-getting-started。
9. 如果用户的请求与任何技能都不明显匹配，请先阅读此工作流技能以了解方向，然后再转到合适的技能。
10. 绝不要使用 style 属性或内联 CSS。 所有样式都必须通过 class 属性，使用 sgds-utilities 中的 sgds: 工具类来应用。如果存在 sgds:mt-4，却编写 style="margin-top: 16px"，则违反此规定。