theme-pack-authoring

Kiro Crew theme-pack authoring

House rules for building theme packs. The authoritative contract is website/docs/theming-contract.md; this skill is the self-contained task-oriented digest, plus the traps that cost real debugging time.

Pack anatomy

my-theme/
├── theme.json          # manifest: slug, name, emoji, level, formatVersion, fonts[]
├── variables.json      # dark + light palettes (56 allowlisted CSS vars)
├── readme.md           # optional; attribution and notes
├── styles/
│   ├── overrides.css   # optional; scoped structural CSS (see allowlist below)
│   └── fonts/          # .woff2 / .ttf files, max 6 faces, 512 KB each
└── LICENSE.txt         # validates as meta, is NOT copied into the install

Levels: 0 = colors only. 1 = + fonts, branding, overrides.css. 2 = + overlays/topbar/audio/persona. Declare the lowest level that covers the payload — a level-0 pack shipping a font is refused.

theme.json — complete working example

{
  "slug": "my-theme",
  "name": "My Theme",
  "emoji": "🎨",
  "level": 1,
  "formatVersion": 1,
  "loaderIcons": ["star", "sparkles", "moon", "cloud"],
  "fonts": [
    { "family": "My Sans", "file": "my-sans-400.woff2", "weight": 400, "role": "sans" },
    { "family": "My Sans", "file": "my-sans-500.woff2", "weight": 500, "role": "sans" },
    { "family": "My Sans", "file": "my-sans-600.woff2", "weight": 600, "role": "sans" },
    { "family": "My Mono", "file": "my-mono-400.woff2", "weight": 400, "role": "mono" }
  ]
}

loaderIcons is optional and requires Level 1 or 2. Supply 4–8 distinct names from: cloud, flower, heart, moon, sparkles, star, sun, zap. Kiro Crew maps these names to bundled Lucide symbols and keeps the stock cross-fading carousel; packs cannot inject loader code or SVG through this field. To ship your own loader art instead, put 1–8 .png/.webp/.gif/.svg files in loader/ (Level 1): one renders alone, 2–8 are cycled, and they win over loaderIcons. With neither, the default Kiro ghost poses remain.