# Theme Troubleshooting

> Diagnose and fix visual/theming issues in Blue95 (XFCE, Chicago95 GTK theme, icon themes, xfconf defaults) and wire fixes into the build pipeline

- Skill: `winblues/theme-troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add winblues/theme-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winblues/theme-troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: winblues (https://skillmd.com/u/winblues)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/winblues/theme-troubleshooting

---


## What I Do

Guide the full workflow for diagnosing visual or styling bugs in Blue95,
applying fixes, wiring them into the build pipeline and drafting upstream PRs.

## Theme Architecture

- **Chicago95** is pinned by SHA (`CHICAGO95_SHA`) in `files/scripts/20-chicago95.sh`.
- Patches to Chicago95 live as `.diff` files in `files/scripts/` and are applied in
  `20-chicago95.sh` with `patch -p1`.  Reference: `20-chicago95-xfwm4.diff` (xfwm4 theme),
  `20-chicago95-notifyd.diff` (xfce4-notifyd CSS icon fix).
- **xfconf** defaults:
  - New users: `files/system/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/<channel>.xml`
  - Existing users: `files/system/usr/share/xfconf-profile/default.json`
    (applied by `run_after_01-xfconf-profile.sh` via chezmoi on every login)
- **Static files** in `files/system/` map verbatim onto `/` in the image.
- **chezmoi dotfiles** live in `files/system/usr/share/winblues/chezmoi/` and are applied
  per-user on first login (gate: `~/.local/state/winblues/chezmoi-blue95`).
- Prefer `/usr` over `/etc` for system-wide changes; use chezmoi only for true `$HOME`-only
  settings.

## Diagnosis Workflow

1. **Identify the GTK widget and CSS node.**

2. **Identify the icon lookup path (if icon-related).**
   - Check `/usr/share/themes/Chicago95/ and `/usr/share/icons/Chicago95/`.

3. **Identify the xfconf key (if a runtime value issue).**
   - `xfconf-query -c <channel> -lv` lists all keys.
   - Cross-reference with the daemon source in `~/Projects/winblues/xfce-mirror/<daemon>/`
     to find the compiled-in default that xfconf will fall back to if the key is absent.
     If the relevant project is not there, clone it (e.g., from https://github.com/xfce-mirror/xfce4-panel.git)

4. **Live-test the fix.**
   - GTK/CSS: copy the relevant file from `/usr/share/themes/Chicago95/` to
     `~/.themes/Chicago95/` (same relative path), edit there, then restart the relevant
     daemon (e.g. `pkill xfce4-notifyd`).
   - xfconf: `xfconf-query -c <channel> -p <key> -s <value> --create -t <type>`.

## Fix Pipeline

### GTK / CSS fix

1. Edit the file in `~/Projects/winblues/Chicago95/` (the pinned upstream clone).
2. Generate the diff:
   ```
   cd ~/Projects/winblues/Chicago95
   git diff > ~/Projects/winblues/blue95/files/scripts/20-chicago95-<name>.diff
   ```
3. Add an `apply_patch` call in `files/scripts/20-chicago95.sh` (follow the existing
   pattern for `20-chicago95-xfwm4.diff` / `20-chicago95-notifyd.diff`).
4. Verify the patch applies cleanly with `patch --dry-run -p1`.

### xfconf defaults fix

1. Edit `files/system/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/<channel>.xml`
   (new users).
2. Edit `files/system/usr/share/xfconf-profile/default.json` (existing users).
   Format: `"<channel>/<key>": "<value>"`.
3. Both files must stay in sync — same key, same value.

### Icon theme fix

- Place new/corrected icons under `files/system/usr/share/icons/Chicago95/` at the
  correct category/size path.
- If this is a Chicago95 upstream issue, include it in the `.diff` file instead.

## Upstream PR

After confirming the fix works locally:

1. Commit the change in `~/Projects/winblues/Chicago95` on a branch.
2. Draft language for a PR against `grassmunk/Chicago95` with:
   - **Title**: concise, imperative, e.g. `xfce-notify: force regular icon rendering to prevent symbolic monochrome`
   - **Body**: what was broken, root cause, fix approach, and (if possible) before/after screenshots.

## Key Files Quick Reference

| File | Purpose |
|---|---|
| `files/scripts/20-chicago95.sh` | Builds/patches Chicago95; set `CHICAGO95_SHA` here |
| `files/scripts/20-chicago95-*.diff` | Patch files applied against the Chicago95 clone |
| `files/system/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/` | xfconf XML defaults for new users |
| `files/system/usr/share/xfconf-profile/default.json` | xfconf-profile defaults for existing users |
| `files/system/usr/share/winblues/chezmoi/` | Per-user dotfiles (chezmoi, first-login only) |
| `~/.themes/Chicago95/` | Live user override for testing before committing |
| `vendor/Chicago95/` | Pinned Chicago95 clone edit here, then diff. May not exist. |
| `vendor/xfce-mirror/` | XFCE source. May need to clone correct components. |

---

## Common Pitfalls

- **Don't use modern app icon names** (e.g. `org.mozilla.firefox`) — Chicago95 maps
  legacy names (`firefox` → Netscape globe). Using modern names breaks theming.
- **`-symbolic` icons are always monochrome in GTK3** unless you force
  `-gtk-icon-style: regular` in CSS or provide a non-symbolic fallback.
- **xfconf keys not in `default.json` fall back to daemon compiled-in defaults**, which
  may differ from what you expect — always check the source.
- **Patches must be idempotent** — build scripts run in a fresh container with no state.