create-theme-style-guide

name	create-theme-style-guide
description	Creates a new theme aesthetic for the Y1 music player. Use this when asked to create a new theme, define a new aesthetic, start a new Y1 theme, change the theme look and feel, or replace the current style. Generates style-guide.md, updates the icon catalog design intents, and updates config.json.

Creating a New Y1 Theme

This skill produces a complete, coherent aesthetic spec for a new Y1 theme. It touches exactly three things in the repo: _theme-system/style-guide.md, the theme-specific fields in _theme-system/icon-catalog.json, and colour/name fields in config.json. All structural catalog data (asset IDs, dimensions, config keys, reference descriptions) is permanent and untouched.

---

Step 1: Gather the Aesthetic

Ask the user the following. They can answer all at once or one at a time:

1. What is the theme name? (PascalCase, no spaces — this becomes the device folder name, e.g. NeonCity, WashiInk, Abyssal)
2. Describe the mood and visual references. What should this theme feel like? Name specific things: places, eras, genres, films, subcultures, colour associations, lighting conditions.
3. Do you have specific colours in mind? If not, you will derive them from the mood.

From their answers, derive and confirm with the user:

• A 7-colour palette with clear roles:
  • background — the darkest colour, fills every icon
  • primary — default text/stroke colour
  • accent1 — the dominant accent (used for glow, active states)
  • accent2 — secondary accent (used for contrast, paired elements)
  • warning — error/power/danger states
  • warm — warm highlight or earthy tone
  • dim — the OFF/inactive colour (always muted, low contrast against background)
• 3–5 sentences describing the visual language: stroke weight (thin/medium/bold), iconography style (flat symbolic / outlined / filled / illustrative / geometric), glow usage (selective or pervasive), texture references (smooth, sandy, neon, organic, mechanical…)
• Per-category style notes: how main menu icons differ from small status icons; what wallpapers should show; what the cover should composite

Confirm the palette and mood with the user before proceeding. If they approve, continue.

---

Step 3: Write <theme-dir>/style-guide.md

Determine the output directory:

• If creating a user theme: themes/<theme-slug>/
• If creating an example/sample: examples/<theme-slug>/
• Create the directory if it doesn't exist, along with svg/ and png/ subdirectories

Write a complete style guide at <theme-dir>/style-guide.md covering:

# [Theme Name] — Style Guide

## Mood
[2–3 sentence evocation of the theme's atmosphere]

## Palette
| Role       | Hex       | Usage                              |
|---|---|---|
| Background | #______   | All icon backgrounds               |
| Primary    | #______   | Default strokes/text               |
| [Accent1]  | #______   | Active states, primary glow        |
| [Accent2]  | #______   | Secondary accent, contrasts        |
| Warning    | #______   | Power off, errors, danger          |
| Warm       | #______   | Earthy/warm highlights             |
| Dim        | #______   | OFF/inactive states only           |

## Visual Language
[Stroke weight, iconography style, glow rules, texture notes]

## Per-Category Rules
### Main Menu Icons (166×166)
### Settings Icons (146×146)
### Status Icons (64×64)
### Battery Icons (64×32)
### Wallpapers (320×240)
### Cover (200×200)

## ON/OFF State Rule
OFF state: all strokes and fills use [dim colour], no filter attributes. Shape identical to ON.

## Sequential Set Rule
[How battery levels, backlight steps, and timer states should progress visually]

## Forbidden List
[What to avoid — styles, motifs, colours that would break the aesthetic]

---

Step 4: Write <theme-dir>/config.json

Copy the structure from any existing examples/*/config.json as a template. Make these updates:

• themeName → the theme name (PascalCase, no spaces)
• playerConfig.progressColor → accent1 hex
• playerConfig.progressBackgroundColor → a dark variant of the background
• statusConfig.statusBarColor → background hex

Do not change any other config fields — asset filenames, config keys, and section structure are unchanged.

---

Step 5: Write <theme-dir>/icon-catalog.json

Start from _theme-system/icon-catalog-base.json (copy it to <theme-dir>/icon-catalog.json). Then update:

• version, referenceTheme — do not touch
• theme — update to the new theme slug (lowercase-with-hyphens)
• palette — update with the new 7 colour roles and hex values
• assets — array of 86 entries; update only the designIntent field on each entry

For each asset entry, write a new designIntent that:

• Is 1–3 sentences describing exactly what to draw
• References specific shapes, symbols, or motifs fitting the new aesthetic
• Names the specific palette colour(s) to use (by role name, e.g. "accent1 glow")
• Respects the category style weight (menu = rich/layered, status = minimal silhouette)
• Is concrete enough that another agent could generate the SVG from it alone, without reading the style guide

Apply the ON/OFF rule in designIntent descriptions:

• For -on assets: describe the active, glowing state
• For -off assets: simply state "Identical shape to [on-variant], all strokes and fills in dim colour, no glow"

Apply sequential set rules:

• For battery/backlight/timer sets: describe the full progression in the first entry, then describe each step's delta in subsequent entries

Work through all 86 entries without stopping.

---

Step 6: Report

When complete, summarise:

• Theme name and one-line mood description
• Palette (7 colours with hex values)
• Count of designIntents updated (should be 86)
• Files written: <theme-dir>/style-guide.md, <theme-dir>/icon-catalog.json, <theme-dir>/config.json
• Next step: "Run /generate-y1-theme to generate all SVG assets for your new theme"

---

Notes for the Agent

• The catalog's structural fields (id, filename, svgFilename, category, dimensions, configSection, configKey, melodyMuncherFile, melodyMuncherDescription, description) are permanent Y1 device spec data — never modify them.
• designIntent is the only per-asset field that is theme-specific.
• Start from _theme-system/icon-catalog-base.json — copy it to <theme-dir>/icon-catalog.json and fill in from there.
• Do not delete any catalog entries or change the array order.
• If <theme-dir>/svg/ or <theme-dir>/png/ contain files from a previous theme, note to the user that running node deploy.js --theme=<theme-dir> will overwrite them.