experience-lwc-design-generate

根据设计创建 LWC 组件

根据设计输入（Figma、PRD、Aura 源代码或用户描述），协调新 Lightning Web Component 的端到端创建流程。这是顶层工作流技能，负责按顺序调用各个阶段对应的专用同级技能。组织相关数据（LDS 架构自省、设计画面检查）通过移交给 experience-lds-data-requirements-generate，或使用用户提供的设计工具 URL 来解析。

使用场景

• 根据 Figma 画面、PRD 或书面规格构建全新的 LWC。
• 将 Aura 组件迁移到 LWC，作为全新构建（原地 Aura → LWC 移植不在此技能的范围内）。
• 创建需求仍部分隐含、需要在编码前提炼为 PRD 的组件。

请勿在以下场景使用此技能：

• 重构现有 LWC（使用 experience-lwc-generate）。
• 原地迁移 Aura → LWC（不在此技能的范围内）。
• 纯样式或数据层工作（直接使用相应的专用技能）。

前提条件

• 至少提供一种设计输入：Figma URL、PRD Markdown、Aura 组件源代码或文本规格。
• 新 LWC 的目标路径（模块文件夹）。
• 对于由数据驱动的组件：能够访问组织，以便 experience-lds-data-requirements-generate 和 experience-lds-best-practices-apply 解析架构和适配器结构。

知识库

• references/prd-analysis-template.md — PRD 章节框架（生成 PRD 时请原样复制）。
• references/figma-to-prd-blueprint.md — 将设计画面转换为 PRD 章节的 Figma 专用指南（componentName/tagName、contentRequirements、dataRequirements、interactions、componentCommunication、states、accessibility/responsiveness/styling/localization/security）。当输入为 Figma 设计时，请在阶段 1.2 之前阅读。

工作流（必须执行的五个阶段）

阶段 1 — 收集 PRD 和需求

**目标：**产出一份后续每个阶段都会使用的整合版 PRD。

1. 获取原始需求 — 收集 PRD、设计规范、Figma URL、Aura 源代码或用户文本。

2. Figma → PRD（如适用）：按照 references/figma-to-prd-blueprint.md 中的完整 Figma 画面分析和 PRD 章节指南进行操作。需要用户提供的输入：Figma URL、目标画面的截图，以及（如果可使用 Dev Mode）该节点的元数据导出文件。按照 blueprint 中的逐章节指南，将内容整理到 references/prd-analysis-template.md 的 PRD 模板中。

3. Aura → PRD（如需迁移）：列出必须保留的 Aura 组件功能 — 标记、控制器/辅助程序操作、事件、属性和已连线的数据，并将清单作为明确需求纳入 PRD。（不在范围内的是原位 Aura → LWC 移植；此步骤仅记录新建组件所需的行为。）

4. 数据需求（如果组件会读取/写入数据）：交由 experience-lds-data-requirements-generate 处理。该技能会生成经过验证的数据规范（对象/字段 API 名称、推荐的 LDS API、实现方式）。将其输出原样粘贴到 PRD 中。

5. 适配器探索：交由 experience-lds-best-practices-apply 处理适配器选择规则（UI API、GraphQL 或 Apex）以及所选方案的推荐连线方式。

6. 命名：componentName 必须采用 camelCase（例如 productCard），tagName 必须是其 kebab-case 形式（例如 product-card）。使用随附脚本验证两者 — 不要凭目测判断：

   "<skill_dir>/scripts/check-component-name.sh" <componentName> <tagName>
   

   如果任一名称格式错误，或 componentName 的 kebab-case 形式与 tagName 不一致，脚本会以非零状态码退出，并输出可采取相应操作的 stderr 消息。

**交付物：**一份完整的 PRD，涵盖用途、内容、数据、交互、状态、a11y、响应式设计、样式方向、本地化和安全性。将其保存在工作区中并纳入版本控制（例如 packages/skills/<skill>-workspace/<iteration>/PRD.md）。

阶段 2 — 生成组件代码

**目标：**生成严格符合 PRD 的初始 .html、.js、.css、.js-meta.xml。

1. 将 PRD 内容作为规范交给 experience-lwc-generate。该技能负责将 PRD 转换为代码（事件、getter、@api、.js-meta.xml、AI 元数据），并作为编写代码的唯一事实来源。
2. 使用 design-systems-slds-apply 中的 SLDS 决策层级：
   1. 优先使用匹配的 Lightning 基础组件（experience-lwc-base-components-integrate）。
   2. 否则，选择 SLDS Blueprint 或实用工具类（按照 design-systems-slds-apply）。
   3. 否则，使用 SLDS 样式钩子编写自定义 CSS（design-systems-slds-apply 中也有说明）。
3. 继续之前，按照 experience-lwc-generate 检查清单逐项检查，重新确认编写代码的基准。
4. 将每项 PRD 数据需求映射到 wire 适配器（UIAPI / GraphQL）或明确的 TODO。
5. 严格遵循 PRD：
   • 只包含 PRD 描述的功能和行为。
   • 对不确定的部分添加 // TODO: 注释，并引用引发歧义的 PRD 原文。
   • 添加详尽的代码注释，解释设计意图。
   • 不要将组件拆分成超出 PRD 暗示范围的更多子组件。

**交付物：**目标路径中的首个 LWC 包。

阶段 3 — 优化组件

目标： 应用性能、可维护性和最佳实践方面的改进。

1. 在进行任何其他审查之前，先逐项检查以下优化清单：
   • 单一职责、封装、可复用性。
   • 尽量减少 DOM 操作；通过属性批量更新。
   • 审查事件处理程序和生命周期钩子的用法（renderedCallback 防护）。
   • 考虑对较重的子组件进行延迟加载。
2. 将任务交给 experience-lwc-generate，进行 LWC 最佳实践审查（反模式、响应性、组合）。
3. 将任务交给合规套件进行发布前审查 — experience-accessibility-validate（a11y）、experience-lwc-security-validate（LWS + Product Security）和 experience-lwc-rtl-validate（RTL i18n）。一起运行这些工具，完成全面质量检查。
4. 如果组件涉及数据，将任务交给 experience-lds-best-practices-apply，检查缓存、一致性和引用完整性。
5. 应用所有已接受的发现。以 PRD 为准 — 不要以优化为名增加范围。

阶段 4 — Lint、格式化、编译检查

条件：仅运行项目中已配置工具对应的步骤。

1. 检测项目工具 — 从项目根目录调用随附的检测脚本，并读取其 <tool>=yes|no 行。不要仅凭阅读 package.json / 点文件来判断：

   "<skill_dir>/scripts/detect-project-tools.sh" <projectRoot>
   

   输出示例：

   eslint=yes
   prettier=yes
   cursor-rules=no
   lwc-compiler=yes
   

   仅对报告为 yes 的工具运行以下子步骤；其余跳过。

2. ESLint（如果 eslint=yes）— 运行并修复所有违规项。

3. Prettier（如果 prettier=yes）— 运行以统一格式。

4. Cursor 规则（如果 cursor-rules=yes）— 应用项目提供的所有规则。

5. LWC 编译器（如果 lwc-compiler=yes）— 通过本地开发服务器或 SFDX 运行；在继续之前解决所有语法/模板错误。

交付物： 干净且通过验证的组件代码。

阶段 5 — 创建测试

将任务交给 experience-lwc-accessibility-jest-run，进行自动化无障碍 Jest 覆盖；在同一轮中，按照 experience-lwc-generate 的测试指南添加通用 Jest 覆盖，并根据团队要求生成 UTAM 页面对象。

交付物： LWC 包含通过的测试套件，覆盖率达到或超过项目阈值。

完成定义

只有当以下所有条目都满足时，通过此工作流构建的新组件才算“完成”。请将此清单作为标准就绪检查表，并复制到 PR 描述中，以便审核者逐项确认。

代码完成 — 不存在实现缺漏：

1. 每项 PRD 要求都已实现，或明确标注了 TODO: 并附上关联的跟踪事项。不得有未说明的缺漏。
2. 生产路径中不得遗留 TODO、FIXME 或 console.log / console.table / alert()。
3. 不得存在注释掉的代码块、空函数体、占位值、虚拟数据或未引用的导入项。
4. 不得存在未附注释说明为何未使用原生 LWC 模式的 lwc:dom="manual" 区域或第三方库变通方案。

合规性与质量：

5. .js-meta.xml AI 元数据通过 experience-lwc-generate 审计（组件级 <ai><description> 已设置；且每个通过 <targetConfig> 暴露的 @api 成员都有对应的 <ai><property name="…" aiDescription="…"/></ai> 条目；不得使用营销用语）。
6. SLDS 样式通过 design-systems-slds-apply 验证 — 不得使用原始十六进制值 / px 值，只能使用样式钩子和 SLDS 工具类。
7. 已完成无障碍检查：源代码审查使用 experience-accessibility-validate，自动化测试使用 experience-lwc-accessibility-jest-run，两项均通过。
8. 已完成安全性与 RTL 检查：experience-lwc-security-validate 和 experience-lwc-rtl-validate 均通过。

数据与测试：

9. 已根据所引用的 LDS 适配器验证数据层（每个 wire / 命令式调用都记录在 PRD 的数据部分中，并与 experience-lds-best-practices-apply 或 experience-lds-data-requirements-generate 中的某个适配器相符）。
10. Jest 测试达到项目要求的覆盖率且全部通过。新增测试覆盖每个 @api 接口、每个已派发事件以及每条错误路径（wire 失败、apex 失败、验证拒绝）。
11. 对需要跨组件浏览器级测试的 UI 流程生成 UTAM 页面对象（如不需要则跳过）。

交叉引用

• 此工作流按阶段顺序串联的技能：
  • experience-lds-data-requirements-generate — 阶段 1.4 数据规范（以及阶段 1.5 中与 experience-lds-best-practices-apply 并行进行的适配器探索）。
  • design-systems-slds-apply、experience-lwc-base-components-integrate — 阶段 2 样式决策。
  • experience-lwc-generate — 阶段 2 编写基准 + 阶段 3 最佳实践审查 + 阶段 5 AI 元数据审计。
  • experience-lds-best-practices-apply — 阶段 2/3 数据层适配器选择与一致性审查。
  • experience-accessibility-validate、experience-lwc-security-validate、experience-lwc-rtl-validate — 阶段 3 无障碍/安全性/RTL 审查。
  • experience-lwc-accessibility-jest-run — 阶段 5 自动化无障碍测试生成。
  • 可选：组件稳定后，单独添加 o11y 埋点。
  • experience-lwc-typescript-migrate — 可选，在 JS 全部通过后执行。
  • 新组件通过功能标志控制发布时，在发布过程中使用功能标志进行门控。
  • 公共 API 稳定后生成 API 接口文档（目前尚无专用技能）。
• 此工作流使用的组织感知型输入：
  • Figma URL + 截图（如果开发者提供，还包括 Dev Mode 元数据导出）— 阶段 1.2 Figma 输入。
  • 当组件需要组织支持的数据时，experience-lds-data-requirements-generate 负责阶段 1 中使用的组织架构内省和数据规范验证 — 请将工作交由该技能处理，而不要在此重复。

示例

阶段 1 PRD 骨架（根据 Figma/PRD/Aura 输入填写）

Component: productCard (<product-card>)
Purpose: Render a compact summary of a product with quick actions.

Content requirements
- Hero image (Product.HeroImage__c)
- Title (Product.Name)
- Subtitle (Product.Tagline__c)
- Primary CTA button ("Add to cart")
- Secondary CTA icon button ("Favorite")

Data requirements
- Input: @api recordId (Product Id)
- Adapter: getRecord (UIAPI) with fields Name, Tagline__c, HeroImage__c
- Events out: addtocart{detail.recordId}, favorite{detail.recordId, detail.value}

States
- Loading (data not yet resolved)
- Error (adapter error)
- Empty (no record found)
- Default

Accessibility
- Title uses <h3>
- Icon-only button carries aria-label="Favorite"
- Card is a labelled region (role="group", aria-labelledby)

Responsiveness
- Full width < 480px
- Side-by-side image + text >= 480px

Styling
- Uses lightning-card wrapper
- Surface color: --slds-g-color-surface-container-1
- Shadow: --slds-g-shadow-1

阶段 2 骨架

import { LightningElement, api, wire } from 'lwc';
import { getRecord } from 'lightning/uiRecordApi';
import NAME from '@salesforce/schema/Product__c.Name';
import TAGLINE from '@salesforce/schema/Product__c.Tagline__c';
import HERO from '@salesforce/schema/Product__c.HeroImage__c';

const FIELDS = [NAME, TAGLINE, HERO];

export default class ProductCard extends LightningElement {
    @api recordId;

    @wire(getRecord, { recordId: '$recordId', fields: FIELDS })
    record;

    get hasRecord() { return this.record?.data != null; }
    get isLoading() { return !this.record; }
    get hasError()  { return !!this.record?.error; }
    get name()      { return this.record?.data?.fields?.Name?.value ?? ''; }
    get tagline()   { return this.record?.data?.fields?.Tagline__c?.value ?? ''; }
    get heroUrl()   { return this.record?.data?.fields?.HeroImage__c?.value ?? ''; }

    handleAddToCart() {
        this.dispatchEvent(new CustomEvent('addtocart', { detail: { recordId: this.recordId }, bubbles: true, composed: true }));
    }
    handleFavorite(event) {
        this.dispatchEvent(new CustomEvent('favorite', { detail: { recordId: this.recordId, value: event.detail.value }, bubbles: true, composed: true }));
    }
}

验证

• 每个 PRD 章节都能追溯到至少一个代码块或明确的 TODO。
• 阶段 1–5 按顺序执行；没有跳过任何步骤。
• 无障碍、SLDS、数据层和 AI 元数据审查均已通过。
• 覆盖率达到或超过项目阈值。
• 该组件在 experience-lwc-runtime-observe 中的渲染正确，并覆盖 PRD 中列出的响应式断点。