burrow/evolution/proposals/BEP-0011-panel-icon-family-and-platform-assets.md

BEP-0011 - Panel Icon Family and Platform Assets

Status: Implemented
Proposal: BEP-0011
Authors: gpt-5.4
Coordinator: gpt-5.4
Reviewers: Pending
Constitution Sections: II, V
Implementation PRs: Pending
Decision Date: 2026-06-07

Summary

Burrow uses a locked six-panel burrowing owl icon family as the product icon language. The supplied panel sheet and its six cropped PNG masters are the canonical source; platform-specific PNGs are generated from those rasters.

Motivation

• Burrow needs one recognizable icon language across iOS, macOS, watchOS, Android, and Linux packaging.
• The iOS app should expose the six panel variants as local alternate app icons.
• Platform packages need exact launcher dimensions without hand-edited raster drift.

Detailed Design

• Scripts/generate-brand-icons.py owns the raster crop and platform exports.
• design/brand/panel-variants/source-sheet.png stores the locked panel sheet.
• The generator writes six 1024px PNG masters under design/brand/panel-variants/ when run with --extract-from.
• iOS uses panel-01-guardian as the primary icon and exposes the other five panel variants through native alternate app icon asset sets.
• macOS uses panel-05-stride as the primary app icon.
• watchOS uses panel-03-burrow as the primary app icon; exact watch icon sizes live in design/brand/watchos/AppIcon.appiconset until a watch target owns them directly.
• Android launcher mipmaps and Linux hicolor PNGs are generated from the same raster master as iOS primary.
• The Apple UI calls only UIApplication.setAlternateIconName; no daemon, control-plane, or network path is added for icon selection.

Security and Operational Considerations

• Icon selection is local presentation state and does not touch auth, routing, daemon IPC, or account material.
• Generated rasters are deterministic from checked-in raster masters.
• The rollback path is to revert the generator and regenerate assets.

Contributor Playbook

• Keep icon geometry in the raster panel masters; do not redraw it as SVG.
• Edit Scripts/generate-brand-icons.py only for crop boxes, package sizes, or platform picks.
• Run Scripts/generate-brand-icons.py.
• Review design/brand/panel-variants/preview-strip.png.
• Review design/brand/low-res/preview-strip.png and design/brand/low-res/pixel-preview-strip.png.
• Run Scripts/check-brand-icon-lowres.sh.
• Build the Apple app and Android app after asset changes.

Alternatives Considered

• Keep a single app icon. Rejected because the six panel variants are all valid product directions and iOS has a native alternate icon API.
• Redraw the sheet as SVG. Rejected because the supplied raster panel already carries the desired style, texture, and proportions.
• Let the daemon choose app icons. Rejected because icon selection is local presentation behavior and should not cross the daemon boundary.

Impact on Other Work

• Store metadata and packaging jobs should use generated platform assets.
• Future design changes should preserve the raster panel source and generated package outputs.

Decision

Implemented on 2026-06-07.

References

• Scripts/generate-brand-icons.py
• design/brand/panel-variants/
• Apple/UI/BurrowView.swift