Back to Details

turbo-verify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verify Theme Implementation

验证主题实现

Verify that a theme implementation is complete and follows all turbo-themes standards. When asked to verify a theme (e.g., 
/turbo-verify rose-pine
), run through the sections below. The 
turbo-add
skill holds the full add-time file map and discovery approach — this skill checks the result.
验证主题实现是否完整且符合所有turbo-themes标准。当需要验证某个主题（例如：
/turbo-verify rose-pine
）时，按照以下章节执行检查。
turbo-add
技能包含完整的添加时文件映射和发现方法——本技能用于检查最终结果。

1. Discover Touchpoints (do this first)

1. 排查主题关联文件（首先执行此步骤）

Do not trust a memorized file inventory. Compare the new theme's footprint against a known-complete theme's footprint:
bash
undefined
不要依赖记忆中的文件清单。将新主题的文件足迹与已知完整主题的文件足迹进行对比：
bash
undefined

Pick a known-good variant id from src/themes/registry.ts (e.g. rose-pine-moon)

从src/themes/registry.ts中选择一个已知正确的变体ID（例如rose-pine-moon）

rg -l 'rose-pine-moon' --hidden -g '!node_modules' -g '!dist' | sort > /tmp/ref.txt rg -l '<new-variant-id>' --hidden -g '!node_modules' -g '!dist' | sort > /tmp/new.txt diff /tmp/ref.txt /tmp/new.txt
rg -l 'rose-pine-moon' --hidden -g '!node_modules' -g '!dist' | sort > /tmp/ref.txt rg -l '<new-variant-id>' --hidden -g '!node_modules' -g '!dist' | sort > /tmp/new.txt diff /tmp/ref.txt /tmp/new.txt

Family-level touchpoints (type unions, family maps, vendor metadata)

家族级关联点（类型联合、家族映射、供应商元数据）

diff <(rg -l 'rose-pine' src/ packages/ apps/ scripts/ | sort)
<(rg -l '<theme>' src/ packages/ apps/ scripts/ | sort)

Also verify root-level registrations the greps can miss because they do not
mention variant ids:

- [ ] `theme:sync` script wiring in `package.json`
- [ ] Size limits in `test/integration/bundle-size.test.ts`

Every file present only in the reference list is a likely missing touchpoint.
Exclude files that auto-derive from core (imports from
`@lgtm-hq/turbo-themes-core/tokens`) and generated artifacts (rebuild instead).
diff <(rg -l 'rose-pine' src/ packages/ apps/ scripts/ | sort)
<(rg -l '<theme>' src/ packages/ apps/ scripts/ | sort)

同时验证grep可能遗漏的根级注册信息，因为这些信息未提及变体ID：

- [ ] `package.json` 中的 `theme:sync` 脚本配置
- [ ] `test/integration/bundle-size.test.ts` 中的大小限制

仅在参考列表中存在的文件很可能是新主题缺失的关联点。排除从核心自动派生的文件（从`@lgtm-hq/turbo-themes-core/tokens`导入的文件）和生成的产物（重新构建即可）。

2. Core Implementation

2. 核心实现

Theme Pack (
src/themes/packs/<theme>.synced.ts
or 
<theme>.ts
)

主题包（
src/themes/packs/<theme>.synced.ts
或 
<theme>.ts
）

  • Exports a 
    ThemePackage
    with 
    id
    , 
    name
    , 
    homepage
    , 
    license
    (spdx/url/copyright, recommended), 
    source
    (package/version/repository, recommended for synced), and 
    flavors
  • Each flavor has 
    id
    (lowercase-hyphenated), 
    label
    (full display name, e.g. "Gruvbox Dark Hard"), 
    vendor
    (matches family), 
    appearance
    (
    light
    /
    dark
    ), and complete 
    tokens
  • No 
    iconUrl
    in flavor definitions (icons resolve via 
    VENDOR_ICON_MAP
    )
  • 导出包含
    id
    、
    name
    、
    homepage
    、
    license
    （推荐使用spdx/url/copyright格式）、
    source
    （对于同步主题推荐包含package/version/repository）和
    flavors
    的
    ThemePackage
  • 每个flavor包含
    id
    （小写连字符格式）、
    label
    （完整显示名称，例如“Gruvbox Dark Hard”）、
    vendor
    （匹配家族）、
    appearance
    （
    light
    /
    dark
    ）和完整的
    tokens
  • flavor定义中没有
    iconUrl
    （图标通过
    VENDOR_ICON_MAP
    解析）

Required Token Groups

必填令牌组

  • background
    — base, surface, overlay
  • text
    — primary, secondary, inverse
  • brand
    — primary
  • state
    — info, success, warning, danger
  • border
    — default
  • accent
    — link
  • typography
    — fonts (sans, mono), webFonts
  • content
    — heading (h1-h6), body, link, selection, blockquote, codeInline, codeBlock, table
  • background
    —— base、surface、overlay
  • text
    —— primary、secondary、inverse
  • brand
    —— primary
  • state
    —— info、success、warning、danger
  • border
    —— default
  • accent
    —— link
  • typography
    —— fonts（sans、mono）、webFonts
  • content
    —— heading（h1-h6）、body、link、selection、blockquote、codeInline、codeBlock、table

Registry, Tokens, Icons

注册表、令牌、图标

  • Theme imported in 
    src/themes/registry.ts
    , flavors spread into 
    allFlavors
  • W3C token JSON per variant in 
    schema/tokens/themes/<variant-id>.tokens.json
    (
    $value
    /
    $type
    format, 
    $schema
    → 
    ../../turbo-themes.schema.json#/$defs/ThemeFile
    )
  • PNG icon per variant in 
    assets/img/<variant-id>.png
    (typically 24x24)
  • 主题已导入
    src/themes/registry.ts
    ，flavors已展开到
    allFlavors
    中
  • 每个变体对应schema/tokens/themes/<variant-id>.tokens.json中的W3C令牌JSON（
    $value
    /
    $type
    格式，
    $schema
    指向
    ../../turbo-themes.schema.json#/$defs/ThemeFile
    ）
  • 每个变体对应assets/img/<variant-id>.png中的PNG图标（通常为24x24尺寸）

3. Theme Selector Package

3. 主题选择器包

  • ThemeFamily
    type union includes the family (
    packages/theme-selector/src/types.ts
    )
  • THEME_FAMILIES
    has name + description (
    packages/theme-selector/src/constants.ts
    )
  • VENDOR_FAMILY_MAP
    and 
    VENDOR_ICON_MAP
    updated; 
    FLAVOR_DESCRIPTIONS
    has an entry per variant (
    packages/theme-selector/src/theme-mapper.ts
    )
  • ThemeFamily
    类型联合中包含该主题家族（
    packages/theme-selector/src/types.ts
    ）
  • THEME_FAMILIES
    中包含名称和描述（
    packages/theme-selector/src/constants.ts
    ）
  • VENDOR_FAMILY_MAP
    和
    VENDOR_ICON_MAP
    已更新；
    FLAVOR_DESCRIPTIONS
    中每个变体都有对应条目（
    packages/theme-selector/src/theme-mapper.ts
    ）

4. Site Integration

4. 站点集成

apps/site/src/data/theme-meta.ts
is the single source of truth for the site. 
BaseLayout.astro
and 
ThemeDropdown.astro
are data-driven from it — never hand-edit theme lists in those files.
  • Theme group in 
    themeGroups
    (id, displayName, flavors)
  • All variants in 
    themeNames
    with short labels (e.g., "Mocha" — shorter than the token 
    label
    )
  • All variants in 
    themeIcons
    with icon filenames
  • validThemeIds
    auto-derives — verify the count matches the expected total
  • ThemeDropdown.astro
    and 
    BaseLayout.astro
    still import from 
    theme-meta.ts
    (no hardcoded theme arrays crept back in)
  • Theme family in the 
    themes.astro
    sidebar (header with icon/name/count, button per variant) and in its JS 
    themeNames
    object
  • Hero preview strip buttons added in 
    index.astro
apps/site/src/data/theme-meta.ts
是站点的唯一数据源。
BaseLayout.astro
和
ThemeDropdown.astro
由该文件驱动——切勿手动编辑这些文件中的主题列表。
  • themeGroups
    中包含主题组（id、displayName、flavors）
  • themeNames
    中包含所有变体的短标签（例如“Mocha”——比令牌中的
    label
    更短）
  • themeIcons
    中包含所有变体的图标文件名
  • validThemeIds
    自动派生——验证其数量与预期总数一致
  • ThemeDropdown.astro
    和
    BaseLayout.astro
    仍从
    theme-meta.ts
    导入（没有硬编码的主题数组被重新加入）
  • 主题家族出现在
    themes.astro
    侧边栏中（带有图标/名称/数量的标题，每个变体对应一个按钮）及其JS
    themeNames
    对象中
  • index.astro
    中添加了Hero预览条按钮

5. Build Pipeline

5. 构建流水线

  • If synced: script in 
    theme:sync
    (package.json), output path is 
    src/themes/packs/
    (NOT 
    packages/core/...
    ), version read from 
    node_modules/<pkg>/package.json
    into 
    source.version
    , and the build succeeds from a clean state (delete the 
    .synced.ts
    file, run 
    bun run build
    , confirm it regenerates)
  • vendorMeta
    in 
    scripts/prepare-style-dictionary.mjs
    has correct name/homepage; generated 
    tokens.json
    files show them
  • Generated assets rebuilt and committed — discover them with 
    git status
    after 
    bun run build
    (theme-selector JS bundles, 
    tokens.json
    in core/python/swift trees)
  • 如果是同步主题：
    package.json
    的
    theme:sync
    中有对应脚本，输出路径为
    src/themes/packs/
    （而非
    packages/core/...
    ），版本从
    node_modules/<pkg>/package.json
    读取并写入
    source.version
    ，且从干净状态构建成功（删除
    .synced.ts
    文件，运行
    bun run build
    ，确认文件已重新生成）
  • scripts/prepare-style-dictionary.mjs
    中的
    vendorMeta
    包含正确的名称/主页；生成的
    tokens.json
    文件中显示这些信息
  • 重新构建并提交生成的资源——运行
    bun run build
    后通过
    git status
    查看（theme-selector JS包、core/python/swift目录下的
    tokens.json
    ）

6. Examples

6. 示例验证

Use the section-1 diff to enumerate example files. Then confirm, per hit:
  • Web examples: new variants in 
    <select>
    options and 
    VALID_THEMES
    /
    LIGHT_THEMES
    /
    THEMES
    arrays (FOUC and main scripts)
  • Files that import from 
    @lgtm-hq/turbo-themes-core/tokens
    were NOT hand-edited (they auto-update)
  • Swift example: 
    ThemeId.swift
    enum cases, 
    ThemeRegistry.swift
    ThemeDefinition
    palettes, 
    ThemeRegistryTests.swift
    counts, labels, and raw values
使用第1步的diff结果枚举示例文件。然后针对每个匹配项确认：
  • Web示例：
    <select>
    选项和
    VALID_THEMES
    /
    LIGHT_THEMES
    /
    THEMES
    数组中包含新变体（FOUC和主脚本）
  • 从
    @lgtm-hq/turbo-themes-core/tokens
    导入的文件未被手动编辑（它们会自动更新）
  • Swift示例：
    ThemeId.swift
    枚举案例、
    ThemeRegistry.swift
    中的
    ThemeDefinition
    调色板、
    ThemeRegistryTests.swift
    中的数量、标签和原始值

7. Build Verification

7. 构建验证

bash
uv run lintro chk          # Expected: 0 issues (run first for fast failure)
bun run build              # Expected: "Build complete!" with new theme count
bun run examples:build     # Expected: all example projects build
bun run test               # Expected: all unit tests pass
bun run examples:test      # Expected: all example E2E tests pass
cd apps/site && bun run build   # Expected: no errors
Visual regression note: if E2E visual tests fail after adding themes to the hero strip, that is expected — snapshots are generated on Linux CI. Run the 
maintenance-generate-snapshots.yml
workflow (Actions → Maintenance: Generate Playwright Snapshots → Run workflow).
bash
uv run lintro chk          # 预期结果：0个问题（先运行此命令快速排查错误）
bun run build              # 预期结果：显示“Build complete!”且包含新主题数量
bun run examples:build     # 预期结果：所有示例项目构建成功
bun run test               # 预期结果：所有单元测试通过
bun run examples:test      # 预期结果：所有示例E2E测试通过
cd apps/site && bun run build   # 预期结果：无错误
视觉回归说明：如果在Hero条添加主题后E2E视觉测试失败，这是正常现象——快照是在Linux CI上生成的。运行
maintenance-generate-snapshots.yml
工作流（Actions → Maintenance: Generate Playwright Snapshots → Run workflow）即可。

8. Functional Testing

8. 功能测试

  • Theme appears in the header dropdown under the correct family group
  • Selecting it updates page styling; header shows the correct icon and short label (not the id or full name)
  • Theme persists across refresh and page navigation (no revert to default)
  • Explorer page: family in sidebar, all variants selectable, palette and live preview render per variant
  • CSS file generated per variant; CSS variables set when applied
  • 主题出现在顶部下拉菜单中的对应家族分组下
  • 选择主题后页面样式更新；顶部显示正确的图标和短标签（而非ID或全名）
  • 主题在刷新和页面跳转后仍保持生效（不会恢复为默认主题）
  • 探索页面：侧边栏中显示主题家族，所有变体均可选择，每个变体的调色板和实时预览正常渲染
  • 每个变体都生成了对应的CSS文件；应用主题时CSS变量已正确设置

Quick Fix Reference

快速修复参考

IssueSolution
Theme reverts on navigationAdd variants to 
themeGroups
in theme-meta.ts
Wrong/missing header labelFix 
themeNames
in theme-meta.ts
Missing iconFix 
themeIcons
in theme-meta.ts + add PNG
Theme in wrong groupFix 
VENDOR_FAMILY_MAP
in theme-mapper.ts
Theme not appearingCheck 
ThemeFamily
type, 
THEME_FAMILIES
constant
Tests fail on theme orderUse 
data-theme-id
lookups, not array indices
Bundle too largeReview asset diff; raise bundle budget if intentional
CI "Cannot find module"Add sync script to 
theme:sync
in package.json
tokens.json wrong metadataAdd to 
vendorMeta
in prepare-style-dictionary.mjs
Generated assets outdatedRun 
bun run build
and commit generated files
Missing descriptionsAdd to 
FLAVOR_DESCRIPTIONS
in theme-mapper.ts
Sync writes to wrong pathChange outPath to 
src/themes/packs/
Visual regression failsRun 
maintenance-generate-snapshots.yml
workflow
Missing from examples/SwiftRe-run the section-1 diff and fill the gaps
问题解决方案
主题在页面跳转后恢复默认在theme-meta.ts的
themeGroups
中添加该主题变体
顶部标签错误/缺失修复theme-meta.ts中的
themeNames
图标缺失修复theme-meta.ts中的
themeIcons
并添加PNG图标
主题分组错误修复theme-mapper.ts中的
VENDOR_FAMILY_MAP
主题未显示检查
ThemeFamily
类型、
THEME_FAMILIES
常量
测试因主题顺序失败使用
data-theme-id
查找，而非数组索引
包体积过大检查资源差异；若为有意调整则提高包体积预算
CI提示“Cannot find module”在package.json的
theme:sync
中添加同步脚本
tokens.json元数据错误在prepare-style-dictionary.mjs中添加到
vendorMeta
生成的资源过时运行
bun run build
并提交生成的文件
描述缺失在theme-mapper.ts中添加到
FLAVOR_DESCRIPTIONS
同步脚本写入错误路径将outPath改为
src/themes/packs/
视觉回归测试失败运行
maintenance-generate-snapshots.yml
工作流
Swift示例中缺失重新执行第1步的diff并填补缺失内容

Review Output Format

评审输出格式

text
undefined
text
undefined

Theme Review: <theme_name>

主题评审：<theme_name>

Status: PASS / FAIL / PARTIAL

状态：通过 / 失败 / 部分通过

Checklist Summary

检查清单摘要

  • Discovery diff: clean / N missing files
  • Core Implementation: X/Y items
  • Theme Selector Package: X/Y items
  • Site Integration: X/Y items
  • Build Pipeline & Examples: X/Y items
  • Build Verification: X/Y items
  • Functional Testing: X/Y items
  • 关联文件对比：无差异 / 缺失N个文件
  • 核心实现：完成X/Y项
  • 主题选择器包：完成X/Y项
  • 站点集成：完成X/Y项
  • 构建流水线与示例：完成X/Y项
  • 构建验证：完成X/Y项
  • 功能测试：完成X/Y项

Missing Items

缺失项

  1. [item]
  1. [具体项]

Recommendations

建议

  1. [recommendation]
undefined
  1. [具体建议]
undefined