validate-y1-theme

name	validate-y1-theme
description	Validates a Y1 theme directory before deployment. Use this after generating SVG assets and before deploying, or when asked to check, validate, or verify a theme.

Y1 Theme Validation

Validate a theme directory before deployment. This skill catches errors silently introduced during generation — wrong dimensions, missing files, palette drift, broken ON/OFF pairs — before they reach the device.

Identify the Theme Directory

The theme will be under themes/<name>/ or examples/<name>/. If not specified, ask.

---

Preferred: run validate.js (10 automated checks, fast)

node validate.js --theme=<theme-path>

This covers all 10 checks in seconds. Interpret the output:

• Exit 0, 0 warnings → theme is valid, offer to run /deploy-y1-theme
• Exit 0, N warnings → valid but some SVGs missing glow defs (acceptable for no-glow styles like constructivist). Safe to deploy.
• Exit 1 → one or more hard failures. See the error repair guide below.

Error repair guide

Error output	Fix
Missing N SVG file(s)	Re-invoke /generate-y1-theme for just those filenames
expected WxH, got AxB	Edit the SVG <svg> tag — set width, height, viewBox to match catalog
missing background <rect>	Add <rect width="W" height="H" fill="[bg colour]"/> after </defs>
OFF state has filter= on content element	Remove filter="url(#...)" from all elements outside <defs> in that file
N/86 designIntents are empty	Fill in the empty designIntent fields in icon-catalog.json, then regenerate those icons
Missing config sections	Add missing sections to config.json — use examples/synthwave/config.json as reference
Orphaned PNG references	Remove the stale PNG key from config.json, or add the missing SVG
parse error: Unexpected token '∩╗┐'	File has UTF-8 BOM — re-save as UTF-8 without BOM

After fixing errors, re-run node validate.js --theme=<path> until exit 0.

---

Fallback: manual checklist (when script cannot run)

All checks below run against <theme-dir>/.

---

Check 1 — Catalog completeness

Read <theme-dir>/icon-catalog.json.

• Confirm catalog.theme is not empty
• Confirm catalog.palette has all 7 keys: background, primary, accent1, accent2, warning, warm, dim — none empty
• Confirm no asset entry has an empty designIntent — empty strings indicate the catalog was not fully populated

Report: count of empty designIntents (should be 0).

---

Check 2 — SVG file completeness

From the catalog, extract the list of all 86 svgFilename values.

For each, check that <theme-dir>/svg/<svgFilename> exists.

Report: list of any missing SVG files (should be empty).

---

Check 3 — SVG dimensions

For each SVG file:

1. Read the file
2. Extract the width, height, and viewBox attributes from the opening <svg> tag
3. Look up the expected dimensions from the catalog entry (e.g. "166x166" → width=166, height=166)
4. Confirm width and height match the expected dimensions
5. Confirm viewBox is "0 0 W H" matching width and height

Report: any files with incorrect dimensions.

---

Check 4 — SVG structure

For each SVG file, check:

1. <filter id="glow" is present in <defs>
2. <filter id="glow-strong" is present in <defs>
3. A <rect element with fill attribute is the first element after </defs> (the background)
4. The background fill matches catalog.palette.background

Report: any files missing filters, background rect, or with wrong background color.

---

Check 5 — ON/OFF state pairs

From the catalog, find all assets where svgFilename ends in -off.svg. For each:

1. Confirm the corresponding -on.svg exists (same name with -off replaced by -on)
2. Read the -off.svg file and confirm:
   • No filter="url(#glow)" or filter="url(#glow-strong)" attribute appears anywhere
   • The dim colour (catalog.palette.dim) is used on content elements
   • None of accent1, accent2, warning, warm, or primary colours appear as fill or stroke values

Report: any OFF-state violations.

---

Check 6 — Palette compliance (spot check)

For a sample of 10 random SVG files (spread across categories), check that no hex color values appear that are not in the palette. Acceptable values: the 7 palette colors, reasonable dark variants of background, #ffffff, #000000, none, transparent.

Report: any unexpected colors found and which files contain them.

---

Check 7 — config.json completeness

Read <theme-dir>/config.json. Confirm:

• themeName is set and not empty
• All required top-level keys are present: themeCover, desktopWallpaper, globalWallpaper, desktopMask
• homePageConfig has 12 entries, none empty
• settingConfig has settingMask and all required keys, none empty
• statusConfig has battery array of 4 items and batteryCharging array of 4 items
• playerConfig has progressColor and progressBackgroundColor

Report: any missing or empty keys.

---

Check 8 — PNG/SVG count parity

Count files in <theme-dir>/svg/ ending in .svg. Count files in <theme-dir>/png/ ending in .png.

If counts differ, node convert.js --theme=<path> has not been run or failed.

Report: SVG count, PNG count, and whether they match.

---

Final Report

Present a summary table:

Check	Status	Issues
Catalog completeness	✅ / ❌	N empty designIntents
SVG file completeness	✅ / ❌	N missing files
SVG dimensions	✅ / ❌	N wrong dimensions
SVG structure	✅ / ❌	N malformed files
ON/OFF pairs	✅ / ❌	N violations
Palette compliance	✅ / ❌	N unexpected colors
config.json	✅ / ❌	N missing keys
PNG/SVG parity	✅ / ❌	SVG=N, PNG=M

If all checks pass: "Theme is valid and ready to deploy. Run: node deploy.js --theme=<path>"

If any checks fail: list all issues with specific filenames and what to fix. Do not proceed to deployment until issues are resolved.

---

Auto-fix Guidance (suggest, do not apply silently)

• Missing SVG: regenerate with /generate-y1-theme for that specific asset
• Wrong dimensions: correct SVG width/height/viewBox to match catalog dimensions field
• Missing defs/background: add the standard <defs> block and background <rect> to the file
• OFF-state violation: replace all non-dim colors with catalog.palette.dim and remove all filter attributes
• Wrong background color: replace background rect fill with catalog.palette.background
• Empty designIntent: run /create-theme-style-guide to repopulate, or fill manually
• PNG count mismatch: run node convert.js --theme=<path>