Create Retro OS Icons

Treat an icon set as a small visual system, not a collection of unrelated pictures. Preserve recognizable subjects while making canvas, silhouette, scale, transparency, rendering, and validation consistent.

Read references/visual-system.md before choosing or generating the visual direction.

Workflow

1. Inspect the real usage

Find every icon asset and consumer before editing. Record:

• file format, dimensions, color mode, and corner alpha;
• rendered sizes in desktop, Dock, menus, mobile, and browser tabs;
• the best existing icon to use as the composition reference;
• whether a visible square is a CSS container or baked image pixels;
• whether the repository already has icon, favicon, or image-generation conventions.

Do not claim CSS can fix black or white corners when the source file is RGB or has opaque corner pixels.

Run an audit without changing files:

python3 scripts/normalize_icon_set.py path/to/icons --audit-only --report /tmp/icon-audit.json --contact-sheet /tmp/icon-audit.png

Use a Python runtime with Pillow installed. In Codex desktop workspaces, call codex_app__load_workspace_dependencies when the default Python lacks Pillow.

2. Define one icon system

Choose one reference icon and lock these invariants before generating or processing assets:

• transparent exterior with no rectangular tile or corner fill;
• one square canvas size, normally 256x256;
• consistent maximum visual mass and padding;
• recognizable silhouette at 16, 32, and 72 pixels;
• restrained late-1990s or early-2000s material rendering;
• no text, watermark, logo, modern app-store tile, or decorative scene;
• no cast shadow that requires an opaque floor or background.

The subject may contain its own plate, device, folder, paper, or frame when that object is the icon. The image canvas itself must remain transparent.

3. Generate or edit deliberately

Use the available raster image-generation skill for genuinely new subjects. Generate distinct icons with separate calls so each subject can be corrected independently. For transparent delivery, follow that skill's chroma-key and background-removal workflow; never assume a generated PNG has useful alpha.

Prefer repairing strong existing subjects when the set already has coherent semantics and materials. Preserve user-owned originals until the processed set passes visual QA.

4. Normalize deterministically

Use the bundled script to remove only background pixels connected to the canvas edge, preserve interior dark or light details, normalize the alpha bounding box, and apply restrained color stepping:

python3 scripts/normalize_icon_set.py path/to/source \
  --output path/to/final \
  --max-side 226 \
  --background-threshold 55 \
  --palette-step 8 \
  --saturation 0.9 \
  --report /tmp/icon-report.json \
  --contact-sheet /tmp/icon-contact-sheet.png

Tune thresholds on copies. If the flood mask eats into the subject, lower --background-threshold. If a white or black halo remains, raise it gradually and inspect the full-size alpha edge after every change. Do not compensate for a failed mask by hiding it against the current wallpaper.

5. Validate pixels and perception

Require all of the following:

• every final asset is RGBA;
• all four corner alpha values are zero;
• the subject fits within the agreed visual mass;
• no white, black, or chroma-key fringe appears on a checkerboard;
• the icon remains readable at 16, 32, and 72 pixels;
• repeated icons do not jump in size between desktop and Dock;
• light and dark wallpapers do not erase the silhouette;
• the favicon is declared by the framework and fetched by the browser.

Inspect a contact sheet first, then verify the real application in desktop and mobile viewports. Visual correctness cannot be proven from file mode or DOM presence alone.

6. Integrate narrowly

Replace only approved assets and required favicon declarations. Keep generated contact sheets, rejected variants, and temporary chroma-key sources outside the repository unless the user asks to retain them.

Run repository-required tests and production build. Preserve unrelated worktree changes. Commit or push only when the repository instructions or user authorization require it.

Deliverables

Report:

• the final visual direction;
• generated or edited asset paths;
• the processing command and important non-default thresholds;
• alpha/contact-sheet/browser verification evidence;
• tests and build results;
• any generator fallback or visual limitation.