validate-y1-theme - SKILL.md Agent Skill

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:

Read the file
Extract the width, height, and viewBox attributes from the opening <svg> tag
Look up the expected dimensions from the catalog entry (e.g. "166x166" → width=166, height=166)
Confirm width and height match the expected dimensions
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:

<filter id="glow" is present in <defs>
<filter id="glow-strong" is present in <defs>
A <rect element with fill attribute is the first element after </defs> (the background)
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:

Confirm the corresponding -on.svg exists (same name with -off replaced by -on)
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>