--- name: turbo-verify description: Verify that a theme implementation is complete and follows all project standards. Use after adding a new theme to turbo-themes. --- # Verify Theme Implementation Use this skill to verify that a theme implementation is complete and follows all turbo-themes standards. ## Usage When asked to verify a theme (e.g., `/turbo-verify rose-pine`), run through all checklist items below. --- ## 1. Core Implementation ### Theme Pack Definition - [ ] `src/themes/packs/.synced.ts` or `.ts` exists - [ ] Exports a `ThemePackage` object with: - `id` - theme family identifier (lowercase) - `name` - display name - `homepage` - theme homepage URL - `license` - (recommended) license metadata with `spdx`, `url`, `copyright` - `source` - (recommended for synced) source metadata with `package`, `version`, `repository` - `flavors` - array of theme variants - [ ] Each flavor has: - `id` - unique identifier (lowercase with hyphens) - `label` - full display name (e.g., "Catppuccin Mocha", "Gruvbox Dark Hard", "Solarized Light") - `vendor` - matches theme family - `appearance` - 'light' or 'dark' - `tokens` - complete token object with all required groups - [ ] No `iconUrl` in flavor definitions (icons resolved via `VENDOR_ICON_MAP` in theme-mapper.ts) ### 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 ### Theme Registry - [ ] Theme imported in `src/themes/registry.ts` - [ ] Theme flavors spread into `allFlavors` array ### W3C Design Token Files - [ ] JSON file exists for each variant in `schema/tokens/themes/.tokens.json` - [ ] Files use W3C Design Tokens format (`$value`, `$type`) - [ ] `$schema` points to `../../turbo-themes.schema.json#/$defs/ThemeFile` ### Theme Icons - [ ] PNG icon exists for each variant in `assets/img/.png` - [ ] Icons are appropriately sized (typically 24x24) --- ## 2. Theme Selector Package ### Types (`packages/theme-selector/src/types.ts`) - [ ] Theme family added to `ThemeFamily` type union ### Constants (`packages/theme-selector/src/constants.ts`) - [ ] Theme added to `THEME_FAMILIES` with: - `name` - display name - `description` - short description ### Theme Mapper (`packages/theme-selector/src/theme-mapper.ts`) - [ ] Theme added to `VENDOR_FAMILY_MAP` - [ ] Theme added to `VENDOR_ICON_MAP` (string or AppearanceIcons object) - [ ] Optionally: descriptions added to `FLAVOR_DESCRIPTIONS` --- ## 3. Site Integration ### Theme Metadata (`apps/site/src/data/theme-meta.ts`) This is the **single source of truth** for the site. Both `ThemeDropdown.astro` and `BaseLayout.astro` are data-driven from this file. - [ ] Theme group added to `themeGroups` array with `id`, `displayName`, and `flavors` - [ ] All variants added to `themeNames` with short display labels (e.g., "Mocha", "Dark Hard" — shorter than the token `label` field) - [ ] All variants added to `themeIcons` with icon filenames - [ ] `validThemeIds` is auto-derived (verify count matches expected total) ### Theme Dropdown (`apps/site/src/components/ThemeDropdown.astro`) - [ ] Imports from `theme-meta.ts` (data-driven, no hardcoded theme buttons) - [ ] Theme appears in dropdown under correct group when rendered ### Theme Explorer (`apps/site/src/pages/themes.astro`) - [ ] Theme family added to sidebar with: - Family header with icon, name, and count - Button for each variant with color dot - [ ] Theme variants added to JavaScript `themeNames` object ### Base Layout (`apps/site/src/layouts/BaseLayout.astro`) - [ ] Imports `validThemeIds` from `theme-meta.ts` (data-driven, no hardcoded VALID_THEMES) - [ ] Uses `define:vars` to pass `validThemeIds` to inline script ### Index Page (`apps/site/src/pages/index.astro`) - [ ] Theme added to hero preview strip buttons (alongside Bulma, Catppuccin, etc.) --- ## 4. Build Verification Run these commands and verify success: ```bash # Linting passes (run first for fast failure) uv run lintro chk # Expected: 0 issues # Core build passes bun run build # Expected: "Build complete!" with theme count including new themes # Example projects build bun run examples:build # Expected: All example projects (react, vue, bootstrap, tailwind) build successfully # Unit tests pass bun run test # Expected: All tests pass (no failures) # Example E2E tests pass bun run examples:test # Expected: All example E2E tests pass # Site builds cd apps/site && bun run build # Expected: No errors ``` **Note on Visual Regression Tests**: If E2E visual regression tests fail after adding themes to the hero preview strip, this is expected. Visual snapshots are generated on Linux CI. Use the `maintenance-generate-snapshots.yml` workflow to regenerate them: Actions → Maintenance: Generate Playwright Snapshots → Run workflow --- ## 4.5 Build Pipeline Verification ### Sync Script Integration (if using sync script) - [ ] Sync script added to `theme:sync` in package.json - [ ] Sync script output path is `src/themes/packs/` (NOT `packages/core/src/themes/packs/`) - [ ] Sync script reads version from `node_modules//package.json` - [ ] `source.version` field is populated in generated ThemePackage - [ ] Build succeeds from clean state (test: delete `.synced.ts` file and run build) - [ ] Generated `.synced.ts` file is created during build ### Style Dictionary Metadata (`scripts/prepare-style-dictionary.mjs`) - [ ] Theme added to `vendorMeta` object with correct `name` and `homepage` - [ ] Generated `tokens.json` files show correct metadata for theme ### Generated Assets After all changes, verify these files are committed: - [ ] `assets/js/theme-selector.js` - bundled with new theme support - [ ] `assets/js/theme-selector.js.map` - [ ] `assets/js/theme-selector.min.js` - [ ] `packages/core/src/themes/tokens.json` - [ ] `python/src/turbo_themes/tokens.json` - [ ] `swift/Sources/TurboThemes/Resources/tokens.json` ### Flavor Descriptions - [ ] All variants have entries in `FLAVOR_DESCRIPTIONS` in theme-mapper.ts --- ## 4.6 Example Files Verification ### Web Examples (hardcoded theme lists) - [ ] `examples/html-vanilla/index.html` - ``, `VALID_THEMES`, and `lightThemes` - [ ] `examples/react/index.html` - `VALID_THEMES` in FOUC script - [ ] `examples/vue/index.html` - `VALID_THEMES` in FOUC script - [ ] `examples/tailwind/index.html` - ``, FOUC `VALID_THEMES`, main `VALID_THEMES` - [ ] `examples/stackblitz/html-vanilla/index.html` - `` options - [ ] `examples/stackblitz/bootstrap/src/main.js` - `VALID_THEMES` and `LIGHT_THEMES` - [ ] `examples/stackblitz/tailwind/index.html` - `