Imported from lqdev/y1-ai-theme-generator (AGENTS.md). Install upstream with npx skills add lqdev/y1-ai-theme-generator. Copyright stays with the author.

AGENTS.md — Y1 Theme Generator

This repo generates AI-designed themes for the Innioasis Y1 portable music player. The pipeline is: define an aesthetic (style-guide) → describe assets (catalog) → generate SVGs (LLM) → convert to PNG → bundle for device.

Build & Run

npm install                                      # once — installs @resvg/resvg-js

node convert.js --theme=examples/synthwave       # SVG → PNG for one theme
node deploy.js  --theme=examples/synthwave       # full pipeline: convert + bundle + zip → dist/

--theme is required and must point to a directory containing config.json, svg/, and png/. Works for any theme under examples/ or themes/.

Validating a run

After deploy, confirm:

• 86 converted, 0 failed in convert output
• dist/<themeName>/ contains exactly 87 files (86 PNGs + config.json)
• dist/<themeName>.zip is present and non-zero

Directory Structure

y1-theme/
├── _theme-system/
│   └── icon-catalog-base.json   ← permanent Y1 device spec (blank designIntents — template)
├── themes/                      ← user workspace, all contents gitignored
│   └── README.md                ← committed placeholder explaining the workspace
├── examples/                    ← 5 committed sample themes (full assets, diverse art styles)
│   ├── synthwave/
│   ├── washi-ink/
│   ├── abyssal/
│   ├── constructivist/
│   └── solarpunk/
├── .github/skills/              ← Copilot agent skills (4 skills)
├── convert.js                   ← SVG → PNG (--theme required)
├── deploy.js                    ← full pipeline (--theme required)
├── AGENTS.md
└── README.md

Each theme directory has this self-contained structure:

<theme-dir>/
├── style-guide.md       ← aesthetic spec (palette, mood, visual language)
├── config.json          ← Y1 device config (themeName, colour fields, all asset filenames)
├── icon-catalog.json    ← base spec + designIntents + palette for this theme
├── svg/                 ← 86 SVG source files
└── png/                 ← 86 PNG rendered files (generated from svg/)

Asset Dimensions (quick reference)

SVG Generation Rules

Every SVG must open with this exact structure:

<svg xmlns="http://www.w3.org/2000/svg" width="W" height="H" viewBox="0 0 W H">
  <defs>
    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
      <feGaussianBlur stdDeviation="2.5" result="blur"/>
      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
    </filter>
    <filter id="glow-strong" x="-50%" y="-50%" width="200%" height="200%">
      <feGaussianBlur stdDeviation="5" result="blur"/>
      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
    </filter>
  </defs>
  <rect width="W" height="H" fill="[background colour]"/>
  <!-- content -->
</svg>

• stroke-linecap="round" and stroke-linejoin="round" on all path/line elements
• ON/OFF state pairs: OFF = identical shape, all strokes/fills in dim colour, no filter attributes
• Background fill comes from the theme's palette.background
• Always read the theme's style-guide.md and icon-catalog.json before generating

Icon Catalog Field Layers

icon-catalog.json (per theme) has two layers:

Permanent — never change between themes (also in _theme-system/icon-catalog-base.json):

• Top-level: version, referenceTheme
• Per-asset: id, filename, svgFilename, category, dimensions, configSection, configKey, melodyMuncherFile, melodyMuncherDescription, description

Theme-specific — set per theme:

• Top-level: theme (slug), palette (7-colour object: background, primary, accent1, accent2, warning, warm, dim)
• Per-asset: designIntent (what to draw for this specific theme — 86 entries)

The base template is _theme-system/icon-catalog-base.json (all designIntent fields are empty strings).

config.json Structure (per theme)

Lives at <theme-dir>/config.json. Key fields:

• themeName — device folder name (PascalCase, no spaces), used by deploy.js
• homePageConfig — 12 main menu icon filenames
• settingConfig — 40+ settings icon filenames, includes settingMask
• statusConfig — status icons + battery array (4) + batteryCharging array (4)
• itemConfig / dialogConfig — dialog row background images
• desktopWallpaper, globalWallpaper, desktopMask, themeCover — top-level keys
• playerConfig — progressColor, progressBackgroundColor

Skills

.github/skills/ contains three Copilot agent skills:

Do Not

• Do not edit files in png/ or dist/ — always regenerated
• Do not edit node_modules/
• Do not change SVG width/height/viewBox — must match dimensions in the catalog
• Do not commit dist/ — gitignored
• Do not commit anything under themes/ (except themes/README.md) — gitignored, user workspace
• Do not add font.ttf unless explicitly requested — Y1 requires .ttf format only

Creating a New Theme

1. /create-theme-style-guide  ->  creates themes/<name>/{style-guide.md, config.json, icon-catalog.json}
2. /generate-y1-theme         ->  writes 86 SVGs to themes/<name>/svg/
3. /validate-y1-theme         ->  checks completeness, dimensions, palette, ON/OFF rules
4. node deploy.js --theme=themes/<name>   ->  dist/<themeName>.zip ready for SD card