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:

What is the theme name? (PascalCase, no spaces — this becomes the device folder name, e.g. NeonCity, WashiInk, Abyssal)
Describe the mood and visual references. What should this theme feel like? Name specific things: places, eras, genres, films, subcultures, colour associations, lighting conditions.
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.