archy/.claude/skills/iso-branding/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
iso-branding	Design and implement Archipelago boot visuals — GRUB theme, Plymouth splash, ISOLINUX menu, console banners. Handles pixel-art cyberpunk aesthetic with Bitcoin orange accents. Use when working on boot screen design, splash animations, GRUB backgrounds, or installer UI appearance.	Bash, Read, Write, Edit, Grep, Glob, Agent

ISO Boot Branding — Archipelago

Design and build the visual boot experience from USB power-on to web UI.

Brand Identity

Archipelago = self-sovereign Bitcoin node OS. Floating islands in the sky.

Element	Value
Primary accent	#fb923c (Bitcoin orange)
Secondary accent	#f7931a (deeper orange)
Success	#4ade80 (green)
Background	#0a0a0a → #050505 (near-black)
Text	#ffffff (white), #aaaaaa (dim), #555555 (subtle)
Glass	rgba(255,255,255,0.06) frost overlay
Style	Pixel art cyberpunk, dark glass morphism, CRT scanlines
Logo	Pixel-art lowercase "a" (from SVG favicon)

Boot Stages & What's Customizable

1. GRUB Menu (UEFI boot)

• Background: branding/grub-theme/background.png — any PNG, GRUB scales it
• Theme: branding/grub-theme/theme.txt — colors, layout, labels
• Fonts: Generated with grub-mkfont during build, .pf2 format
• Config: Written by build script in Step 5 (grub.cfg heredoc)

GRUB theme.txt properties that work:

desktop-color: "#rrggbb"       # Fallback if no background
desktop-image: "background.png" # Background image
title-text: ""                  # Empty = no title

+ boot_menu {
    left/top/width/height = N%
    item_color = "#rrggbb"
    selected_item_color = "#rrggbb"
    item_height = N
    item_spacing = N
    scrollbar = false
}

+ label {
    left/top/width = N%
    text = "string"
    color = "#rrggbb"
    align = "center"
}

IMPORTANT: Do NOT reference font names in theme.txt unless you know the exact internal name from grub-mkfont output. GRUB falls back to default if a font reference fails, which causes the ENTIRE theme to not load.

2. ISOLINUX Menu (BIOS boot)

• Config: Written by build script in Step 5 (isolinux.cfg heredoc)
• Colors: ANSI-style color codes in MENU COLOR directives
• Title: MENU TITLE string
• Text-only — no background image (use vesamenu.c32 for graphical, but menu.c32 is more compatible)

3. Plymouth Splash (kernel boot → login)

• Theme: branding/plymouth-theme/archipelago.script
• Logo: branding/plymouth-theme/logo.png (PNG with transparency)
• Config: branding/plymouth-theme/archipelago.plymouth
• Supports: animated progress bar, logo sprites, LUKS password prompt
• Kernel param splash must be present (added to GRUB_CMDLINE_LINUX_DEFAULT)

Plymouth script language:

Window.SetBackgroundTopColor(r, g, b);  // 0.0-1.0
logo = Image("logo.png");
sprite = Sprite(logo);
sprite.SetX(x); sprite.SetY(y);
Plymouth.SetRefreshFunction(callback);
Plymouth.SetBootProgressFunction(callback);
Plymouth.SetDisplayPasswordFunction(callback);

4. Console Banner (TTY login)

• ASCII art + system info in /etc/profile.d/archipelago.sh
• Generated in auto-install.sh (Step 4, the INSTALLER_SCRIPT heredoc)
• Uses ANSI escape codes for color

5. Installer Prompt

• "ARCHIPELAGO BITCOIN NODE OS / Automatic Installer"
• In the systemd service wrapper: /usr/local/bin/archipelago-start-installer
• Built inside the debootstrap container in Step 2

Dev Workflow

Quick preview (no ISO needed)

# Edit background, see it instantly:
open image-recipe/branding/grub-theme/background.png

# Generate procedural background:
python3 image-recipe/branding/generate-grub-background.py /tmp/bg.png && open /tmp/bg.png

# Generate Plymouth logo:
python3 image-recipe/branding/generate-plymouth-logo.py /tmp/logo.png && open /tmp/logo.png

Full boot test (needs base ISO)

./image-recipe/dev-branding.sh [path-to-iso]
# Or via dev-start.sh option 0

Extracts ISO → patches branding → repackages → boots QEMU. ~30 seconds.

What to edit

File	Affects
branding/grub-theme/background.png	GRUB boot screen image
branding/grub-theme/theme.txt	GRUB menu colors, layout
branding/plymouth-theme/logo.png	Plymouth boot logo
branding/plymouth-theme/archipelago.script	Plymouth animation/progress
branding/generate-grub-background.py	Procedural background generator
branding/generate-plymouth-logo.py	Procedural logo generator

Image Specs

Asset	Format	Size	Notes
GRUB background	PNG	1024x768 recommended	GRUB scales any size, but large images slow boot
Plymouth logo	PNG (RGBA)	256x256 recommended	Transparent background
GRUB fonts	.pf2	Generated	grub-mkfont -s SIZE -o out.pf2 input.ttf

Build Integration

GRUB theme is installed in Step 2 (after artifacts placed):

• Static background.png copied from branding/grub-theme/
• Falls back to Python generator if static file missing
• Fonts generated in debootstrap container with grub-mkfont

Plymouth theme installed in Step 3 (component copy) + Step 4 (auto-install.sh):

• Files copied to $ARCH_DIR/plymouth-theme/ in ISO
• Auto-install.sh copies to target at /usr/share/plymouth/themes/archipelago/
• Sets as default via plymouth-set-default-theme

GRUB theme also installed on TARGET system (not just installer):

• Auto-install.sh copies theme to /mnt/target/boot/grub/themes/archipelago/
• Adds GRUB_THEME= to /mnt/target/etc/default/grub