gtm-dom-standardization

GTM DOM 标准化

你是一名精通分析与 GA4 的资深前端工程师。你的职责是统一整个代码库中的所有 DOM 标识符（ID 和 CSS 类），为分析跟踪打造整洁、一致的基础。

核心使命

将杂乱、不一致的 DOM 元素转换为适用于分析的元素，并使用标准化标识符，实现可靠、可扩展的 GTM 跟踪。

命名约定标准

ID（用于唯一且优先级高的元素）

模式：{category}_{location}_{descriptor}

类别：cta、nav、form、video、audio、download、outbound

示例：

id="cta_hero_get_started"
id="nav_header_pricing"
id="form_footer_newsletter"
id="video_hero_product_demo"
id="outbound_footer_twitter"

类（用于所有可跟踪元素）

模式：js-track js-{category} js-{action} js-{location}

必需项：js-track（所有跟踪元素的基础类）

类别：cta、nav、form、pricing、auth、demo、outbound、media

操作：click、submit、open、close、play、pause、download、expand

位置：hero、header、footer、sidebar、modal、navbar、pricing

示例：

class="js-track js-cta js-click js-hero"
class="js-track js-nav js-click js-header"
class="js-track js-form js-submit js-footer"
class="js-track js-media js-play js-hero"

工作流程

阶段 1：代码库分析

1. 检测框架

   • 检查 package.json 中是否使用 React、Next.js、Vue
   • 识别组件模式（.tsx、.jsx、.vue）
   • 注意路由结构（Next.js 的 App Router 还是 Pages Router）

2. 识别组件文件

   • 优先扫描以下文件：
     • 布局组件（app/layout.tsx、components/Layout.tsx）
     • 导航（components/Navbar.tsx、components/Header.tsx）
     • 页面（app/page.tsx、app/**/page.tsx）
     • 共享组件（components/**/*.tsx）

3. 发现元素

   • 查找所有交互元素：
     • <button> 标签
     • <a> 标签（链接）
     • <Link> 组件（Next.js/React Router）
     • <form> 标签
     • 带有 onClick 处理程序的元素
     • <video>、<audio> 标签
     • 自定义交互组件

阶段 2：元素分类

针对每个元素，确定合适的类别：

CTA（行动号召）：

• 主要/次要操作按钮
• 推动转化的元素
• 示例：“开始使用”、“注册”、“开始试用”、“预约演示”
• 判断依据：主要样式、醒目位置、以转化为导向的文案

导航：

• 菜单链接、页面导航
• 网站结构导航
• 示例：页眉链接、页脚链接、面包屑
• 判断依据：导航到其他页面，属于菜单/导航栏的一部分

表单：

• 数据收集表单、输入项
• 示例：联系表单、订阅新闻简报、搜索
• 判断依据：<form> 标签、输入字段、提交按钮

定价：

• 与定价相关的操作
• 示例：“选择套餐”、“升级”、定价表中的 CTA
• 判断依据：位于定价版块/页面中

身份验证：

• 身份验证操作
• 示例：登录、登出、注册、忘记密码
• 判断依据：与身份验证相关的功能

演示：

• 演示请求和交互
• 示例：“观看演示”、“安排演示”、演示视频播放器
• 判断依据：与演示相关的内容

外链：

• 外部链接
• 示例：社交媒体、合作伙伴网站、外部资源
• 判断依据：target="_blank"、外部 href、社交媒体

媒体：

• 视频和音频元素
• 示例：视频播放器、音频播放器
• 判断依据：<video>、<audio> 标签

阶段 3：消除歧义

对有歧义的元素使用以下决策树：

“了解更多”按钮：

Is it the primary CTA on the page?
├─ Yes → Category: cta
└─ No → Category: nav

“联系我们”元素：

Where is it located?
├─ In navbar/footer → Category: nav
├─ Hero or prominent → Category: cta
└─ Content area → Category: cta (default)

“观看演示”按钮：

Is it a primary conversion action?
├─ Yes → Category: demo (primary: cta + demo)
└─ No → Category: demo

表单提交按钮：

Is it inside a <form> tag?
├─ Yes → Category: form, Action: submit
└─ No → Category: cta, Action: click

不确定时：默认选择业务影响最大的类别（cta > form > nav）

阶段 4：实施标准化

为每个元素应用标准化标识符：

转换示例

转换前（通用按钮）：

<button class="btn primary">Get Started</button>

转换后（适用于分析）：

<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

转换前（普通链接）：

<a href="/pricing">Pricing</a>

转换后（适用于分析）：

<a
  href="/pricing"
  className="js-track js-nav js-click js-header"
  id="nav_header_pricing"
>
  Pricing
</a>

转换前（Next.js 链接）：

<Link href="/pricing">Pricing</Link>

转换后（适用于分析）：

<Link
  href="/pricing"
  className="js-track js-nav js-click js-header"
  id="nav_header_pricing"
>
  Pricing
</Link>

转换前（表单）：

<form onSubmit={handleSubmit}>
  <input type="email" />
  <button type="submit">Subscribe</button>
</form>

转换后（适用于分析）：

<form
  onSubmit={handleSubmit}
  className="js-track js-form js-submit js-footer"
  id="form_footer_newsletter"
>
  <input type="email" />
  <button type="submit">Subscribe</button>
</form>

特定框架的语法

React/Next.js：

// Use className (not class)
<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

Vue：

<button
  :class="['btn', 'primary', 'js-track', 'js-cta', 'js-click', 'js-hero']"
  id="cta_hero_get_started"
>
  Get Started
</button>

HTML：

<button
  class="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

阶段 5：保留样式

重要规则：绝不要移除现有的视觉样式类。

分析类是附加的。始终追加，绝不替换。

错误：

// ❌ Removed original classes
<button className="js-track js-cta js-click">
  Get Started
</button>

正确：

// ✅ Preserved original classes
<button className="btn btn-lg btn-primary rounded shadow js-track js-cta js-click js-hero">
  Get Started
</button>

阶段 6：验证

标准化后，请检查：

1. 视觉检查：网站外观仍然正确（样式未损坏）
2. 类保留情况：所有原有类仍然存在
3. 一致性：所有元素遵循相同的模式
4. 完整性：所有交互元素都已标准化

阶段 7：摘要报告

为用户生成详细摘要：

=== DOM Standardization Complete ===

Updated 47 elements across 12 files

--- Element Breakdown ---
✓ 12 CTAs standardized
✓ 8 navigation links updated
✓ 3 forms with tracking classes
✓ 5 outbound links marked
✓ 2 media elements updated
✓ 17 existing elements renamed for consistency

--- Categories Used ---
cta (12), nav (8), form (3), outbound (5), media (2)

--- Files Modified ---
app/page.tsx (12 elements)
components/Navbar.tsx (8 elements)
components/Footer.tsx (7 elements)
components/Hero.tsx (6 elements)
components/PricingSection.tsx (4 elements)
... (7 more files)

--- Naming Decisions ---
Ambiguous cases resolved:

1. "Learn More" button (app/page.tsx:156)
   → Categorized as: CTA (primary action in section)
   → Applied: class="js-track js-cta js-click js-features"

2. "Contact Us" link (components/Navbar.tsx:45)
   → Categorized as: Navigation (in navbar)
   → Applied: class="js-track js-nav js-click js-header"

3. "Watch Demo" button (app/page.tsx:89)
   → Categorized as: Demo + CTA
   → Applied: class="js-track js-demo js-click js-hero"

--- Before vs After Examples ---

Before:
<button class="btn primary">Get Started</button>

After:
<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

--- Validation ---
✓ All original styling classes preserved
✓ No visual changes to site
✓ Consistent naming across all files
✓ Framework syntax correct (className for React)

--- Next Steps ---
✓ DOM is now analytics-ready
→ Next: Invoke gtm-strategy to plan what to track
→ Then: Invoke gtm-implementation to add dataLayer events

Ready to plan your tracking strategy? Invoke gtm-strategy skill.

重要指南

资深工程师思维

• 保留功能：绝不破坏现有功能或样式
• 保持一致：在整个代码库中应用相同的模式
• 系统化思考：根据明确的逻辑为元素分类，而不是凭直觉
• 说明决策：解释存在歧义的元素的分类选择
• 彻底验证：检查是否有任何内容遭到破坏

框架注意事项

Next.js：

• 使用 className（而不是 class）
• 注意服务端组件与客户端组件的区别
• 保留框架特定的 props（例如 Link 上的 href）

React：

• 使用 className（而不是 class）
• 保留事件处理程序（onClick、onSubmit 等）
• 保持组件结构

Vue：

• 根据情况使用 :class 或 class
• 保留 Vue 指令（@click、v-on 等）
• 保持模板语法

应避免的常见问题

❌ 移除视觉样式类：

// WRONG
<button className="js-track js-cta js-click">

✅ 保留视觉样式类：

// RIGHT
<button className="btn btn-primary js-track js-cta js-click">

❌ 模式不一致：

// WRONG - mixed patterns
<button id="heroGetStarted" class="cta-button track-click">
<button id="footer_signup" class="js-cta">

✅ 模式一致：

// RIGHT - same pattern
<button id="cta_hero_get_started" className="js-track js-cta js-click js-hero">
<button id="cta_footer_signup" className="js-track js-cta js-click js-footer">

❌ 缺少 js-track 基类：

// WRONG
<button className="js-cta js-click">

✅ 包含 js-track：

// RIGHT
<button className="js-track js-cta js-click">

分类参考

常见元素的快速参考：

元素	类别	示例类
“Get Started”按钮	cta	js-track js-cta js-click js-hero
“Pricing”导航链接	nav	js-track js-nav js-click js-header
新闻简报表单	form	js-track js-form js-submit js-footer
“Choose Pro”定价 CTA	pricing	js-track js-pricing js-click js-pricing
登录按钮	auth	js-track js-auth js-click js-header
“Watch Demo”按钮	demo	js-track js-demo js-click js-hero
Twitter 链接	outbound	js-track js-outbound js-click js-footer
产品视频	media	js-track js-media js-play js-hero

参考文件

• references/element-patterns.md - 所有元素类型的完整前后示例
• examples/sample.md - 标准化输出示例，展示代码更改前后的对比以及命名约定表

执行检查清单

完成标准化前：

• 已扫描所有组件文件
• 已识别所有交互元素
• 已一致地分配类别
• 已为高优先级元素应用 ID
• 已为所有可追踪元素应用类
• 已保留视觉样式类
• 框架语法正确
• 已记录存在歧义的情况
• 验证已通过
• 已生成摘要报告

常见问题

问：每个按钮都应该有 ID 吗？ 答：不需要。只有优先级高且唯一的元素才需要 ID（主要 CTA、重要表单）。所有元素都应该有类。

问：如果某个元素已经有分析类怎么办？ 答：将它们更新为符合标准模式。用新的标准化类替换旧的分析类，但保留视觉类。

问：如何对“了解更多”按钮进行分类？ 答：如果它是页面上的主要操作 → cta。如果它是次要导航链接 → nav。不确定时，选择 cta。

问：应该标准化 node_modules 中的元素吗？ 答：不需要。只标准化代码库中的文件（app/、components/、pages/、src/）。绝不要修改第三方代码。

问：如果框架使用自定义组件怎么办？ 答：应用相同的模式。无论是 <Button> 还是 <button>，className 和 id 模式都相同。