Theme Troubleshooting
Testing & Qualitytheme-troubleshootingTheme Troubleshooting is an Agent Skill for testing & quality published in the winblues/blue95 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Diagnose and fix visual/theming issues in Blue95 (XFCE, Chicago95 GTK theme, icon themes, xfconf defaults) and wire fixes into the build pipeline
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/winblues/blue95/blob/HEAD/.opencode/skills/theme-troubleshooting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/theme-troubleshooting, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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) infiles/scripts/20-chicago95.sh. - Patches to Chicago95 live as
.difffiles infiles/scripts/and are applied in20-chicago95.shwithpatch -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 byrun_after_01-xfconf-profile.shvia chezmoi on every login)
- New users:
- 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
/usrover/etcfor system-wide changes; use chezmoi only for true$HOME-only settings.
Diagnosis Workflow
-
Identify the GTK widget and CSS node.
-
Identify the icon lookup path (if icon-related).
- Check
/usr/share/themes/Chicago95/ and/usr/share/icons/Chicago95/`.
- Check
-
Identify the xfconf key (if a runtime value issue).
xfconf-query -c <channel> -lvlists 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)
-
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>.
- GTK/CSS: copy the relevant file from
Fix Pipeline
GTK / CSS fix
- Edit the file in
~/Projects/winblues/Chicago95/(the pinned upstream clone). - Generate the diff:
cd ~/Projects/winblues/Chicago95 git diff > ~/Projects/winblues/blue95/files/scripts/20-chicago95-<name>.diff - Add an
apply_patchcall infiles/scripts/20-chicago95.sh(follow the existing pattern for20-chicago95-xfwm4.diff/20-chicago95-notifyd.diff). - Verify the patch applies cleanly with
patch --dry-run -p1.
xfconf defaults fix
- Edit
files/system/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/<channel>.xml(new users). - Edit
files/system/usr/share/xfconf-profile/default.json(existing users). Format:"<channel>/<key>": "<value>". - 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
.difffile instead.
Upstream PR
After confirming the fix works locally:
- Commit the change in
~/Projects/winblues/Chicago95on a branch. - Draft language for a PR against
grassmunk/Chicago95with:- 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.
- Title: concise, imperative, e.g.
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. -symbolicicons are always monochrome in GTK3 unless you force-gtk-icon-style: regularin CSS or provide a non-symbolic fallback.- xfconf keys not in
default.jsonfall 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.