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 (54 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,
  "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" }
  ]
}

Fonts — the role system (the ONLY supported route)

• Each face carries role: "sans" or "mono". Absent role = sans.
• sans faces feed the Sans Font Family option; mono faces feed Mono AND code surfaces (code blocks, inline code, diffs) under every option.
• System always stays the OS font — a pack cannot reach it. Unfilled roles fall back to Kiro Crew's own stacks.
• Max 6 faces across both roles; pick weights deliberately. The UI uses 400/500/600/700; with 3 sans slots ship 400/500/600 (font-bold resolves to 600, acceptable; 400/500/700 makes the many semibold elements render heavy).
• CJK/Devanagari/Bengali fallbacks are wired automatically — the generated stacks carry the script-fallback aliases. Latin-only faces are fine.
• Never set fonts in overrides.css. --font-body, --mono, the --theme-font-* tokens, or font/font-family on body/html/*/:root are rejected at install and dropped at runtime (CSS-escape evasions included). A font-family on ONE allowlisted surface (e.g. .topbar) is fine.
• Ship the font's license file in the pack source (OFL/Apache/MIT).
• Only "sans" and "mono" are valid; a wrong role string (e.g. the CSS keyword "monospace") is rejected at install with an error naming the font and the bad value. An already-installed pack whose role predates this check keeps loading — the coercion-to-sans behavior only remains on that read path, never on a fresh install.