rab-icon-grid-processing

RAB Icon Grid Processing

Outcome

Turn incoming icon artwork into usable Reading App Builder icon assets that are visually legible at app-icon size, stored in the layout Bloom expects, and validated before broad rollout.

When To Use

• You receive a grid, sprite sheet, or batch of candidate icon images for Reading App Builder.
• The icons are technically valid PNGs but look too small because of excessive transparent padding.
• The icons are stored one-per-folder and need to be flattened into a single bundled icon directory.
• Bloom's RAB icon discovery code needs to be updated to match an asset-layout change.
• You want to try one or two sample icons first before touching the entire set.

Default Assumptions

• Target icons should remain square PNGs with transparent backgrounds.
• A 512x512 master icon is the safest working size when repadding or regenerating icon art.
• Unless the user says otherwise, name outputs bloom-app-icon-<number>.
• In this repo, bundled App Builder icons live under DistFiles/appbuilder-icons.
• If the asset layout changes, update both the backend discovery path and the tests in the same pass.
• Prefer process tasks or direct scripts over bash-heavy image tooling if the shell environment is unstable.

Inputs To Confirm

• What is the incoming source: a grid image, sprite sheet, flat PNG batch, or folder-per-icon bundle?
• Is the task visual-only, layout-only, or both?
• Should the agent run a one-or-two-icon pilot first, or has the user already approved a full batch?
• Are filenames already the desired final IDs, or do they need renaming?
• Does Bloom code currently assume the old bundled layout?
• What is the narrowest validation available after the change?

Core Workflow

1. Inspect the incoming asset set. Determine whether the source is a single grid, a sprite sheet, flat PNG files, or a folder-per-icon layout.
2. Identify the controlling problem before editing. Decide whether the main issue is splitting, transparent padding, directory layout, naming, or code compatibility.
3. Start with a representative sample. Pick one or two icons that clearly show the problem and use them as a reversible pilot.
4. If the icons are already individual files but too padded, crop to visible alpha bounds. Measure visible pixels using alpha, trim the transparent border, then redraw onto a square transparent canvas with a consistent margin.
5. If the assets are stored one-per-folder, flatten them only after checking for filename collisions. Move the PNGs into the target root, remove emptied folders, and keep the filename-based identity stable.
6. If the source is a grid or sprite sheet, split it into individual transparent PNGs before any crop-and-repad pass. Use the grid cell geometry or visible bounds consistently across the full batch.
7. Validate the pilot visually before batch rollout. Open the updated sample icons and confirm they read better without clipping or awkward framing.
8. Only after the pilot succeeds, run the same transformation across the remaining icons.
9. If Bloom code depends on the old asset layout, update the code path and tests in the same change.
10. Finish with the narrowest executable validation available and note any unrelated blockers separately.