Design or refine original application icons, crafted layered artwork, icon sets and host-specific exports. Integrates Apple HIG, the iOS/iPadOS/watchOS 27 App Icon Template, Icon Composer guidance and bundled Figma canvas, component and shader workflows. Use for icon concepts, reference-based refinement and identical-artwork light/dark background previews; preserve the application's UI and runtime.
Instructions
---
name: icon-design
description: Design or refine original application icons, crafted layered artwork, icon sets and host-specific exports. Integrates Apple HIG, the iOS/iPadOS/watchOS 27 App Icon Template, Icon Composer guidance and bundled Figma canvas, component and shader workflows. Use for icon concepts, reference-based refinement and identical-artwork light/dark background previews; preserve the application's UI and runtime.
metadata:
version: "1.0.8"
---
# Icon Design
Create application artwork that is simple and recognizable at first glance, with purposeful construction, material and optical balance. This is one integrated skill: the relevant Apple references and Figma workflows are bundled. Installing separate Apple or Figma skills is not required to obtain these instructions. This package designs app identities; interface controls and full screens use the UI Design package.
For substantive icon design, briefly remind the user about Figma and follow [Figma access and fallback](references/design-access.md): prefer the Figma connection, then an authorized Chrome Figma session, then complete editable artwork and exports locally if neither is available. Respect code-only and no-computer-control instructions. Do not stall an icon task solely because a cloud connection is missing.
## Establish the identity and destination
For a PiscesOS app or tool, read [PiscesOS app family](references/piscesos-app-style.md). Match the accepted craft and appearance while keeping the app's own recognizable identity. The PiscesOS and native Server product logos are not default artwork for every app. The portable `piscesos-app-design` package provides approved assets and UI/Icon evidence for another Codex.
When refining an existing PiscesOS identity, read [Current artwork decisions](references/piscesos-current-artwork.md) before selecting a saved export or older study. Preserve current user-selected artwork and avoid resurrecting retired icons.
Use the application's purpose, existing identity, target host and the user's references to choose a visual metaphor and finish. Identify whether the deliverable is a concept set, a refinement, a production master, appearance variants or a preview comparison. Deliver the requested number of meaningful concepts; palette swaps alone are not different designs unless requested. When the user asks for more designs in an accepted style, preserve the accepted identity and vary useful proportions, silhouette or material treatment. Do not introduce unrelated metaphors merely to make the set different.
Read [Clarity, color and restrained material](references/clarity-color-material.md) and [Artwork workflow](references/icon-design.md). For a crafted reference or a result that lacks depth, read [Reference construction and craft](references/reference-craft.md) before drawing more variations. Inspect actual editable layers when available. Distinguish visible screenshot observations from inferred geometry or renderer settings.
For the current PiscesOS direction, read [iPhone form and material restraint](references/iphone-restraint.md). The latest user review preserves the earlier quiet proportions and corrects exaggerated glass: prioritize a clear identifier, broad calm color, narrow edge light and slight contact depth. Foreground glass does not require thick lenses, swollen bevels or stronger shine on every shape. A requested redesign changes composition before finish.
App artwork can coexist with another UI system. The user's separate explicit UI request selects the [Apple iOS 27 community design system](references/apple-ios27-community.md) for PiscesOS interfaces and icons, retaining Material 3 as a supplementary reference. Preserve native Windows behavior. An icon request alone does not migrate an unrelated product's UI, replace interface symbols or change functions, runtimes, authentication or packaging.
## Compose before adding effects
Resolve one clear primary identifier, its silhouette, dominant masses, negative space, optical scale and overlap order before adding effects. More gears, rings, spokes, micro-teeth or layers do not make an icon better. Remove secondary construction that competes with recognition. Simplicity can retain a crafted filled shape, a subtly raised edge and a light contact shadow; it does not require replacing the artwork with a generic thin UI glyph.
Give each material a role. Separate the visible face, bevel, sidewall, contact shadow and cast shadow when the requested finish needs those surfaces. Keep highlights local and shadows slight enough that edges and negative spaces stay clear at small sizes. Light should follow geometry; repeated gradients or decorative rings do not create convincing volume by themselves.
Preserve recognizable opaque information when using glass. Use color deliberately: “neutral” means balanced in context and does not require black, white, grayscale or near-invisible transparency. Creative freedom remains bounded by the requested design guidance, app identity and references. For Apple-directed artwork, read current app-icon, color and material guidance before selecting the palette; evaluate foreground/background separation and the actual template or renderer. Do not invent a fixed “Apple palette” or present custom artwork colors as official system-color constants. Match the reference's degree of realism while retaining recognition at launcher and taskbar sizes.
A Windows/web icon can use its own silhouette, object chassis or a useful container. The current user-selected PiscesOS artwork direction uses a rounded protective glass shell and glass material on the primary foreground content itself, including Browser 02/04's colored shapes and the selected Settings gear. Read [Glass shell and foreground construction](references/glass-shell.md) for this direction. Preserve selected contours and palette identity; give each foreground glass shape its own transmission, curved edge response and gentle contact depth. When a body already exists, refine that body as the shell instead of nesting another tile. Other products or later briefs can choose another material or an unframed silhouette. Actual Apple app icons follow their current native template and mask; a static Windows/web shell is a separate delivery.
## Apple template and material references
Read [Current icon resources](references/official-resources.md) and [Community HIG app-icon summary](references/apple/app-icons.md) when relevant. Verify exact specifications against current official sources and the actual template.
Read the [selected community system and icon application workflow](references/apple-ios27-community.md) for the user's new reference. Study its light/dark colors and layered material relationships while preserving the accepted original identity. Use the official App Icon Template for production canvas and mask requirements. The UI Kit, community design system and App Icon Template serve distinct purposes; none supplies access to hidden Figma agent instructions.
- [Apple Design Resources](https://developer.apple.com/design/resources/): official resource and version index.
- [App Icon Template: iOS, iPadOS and watchOS 27](https://www.figma.com/community/file/1645923469870515372/app-icon-template-ios-ipados-and-watchos-27): native app-artwork canvas, guides and layer workflow.
- [App icons HIG](https://developer.apple.com/design/human-interface-guidelines/app-icons) and [Icon Composer](https://developer.apple.com/icon-composer/): composition, appearances and native material authoring.
- [Materials and color](references/apple/materials-color.md): supplementary community orientation.
Prepare clean source layers for native Icon Composer materials. A static Windows/web compositor can bake supported highlights, refraction approximations and shadows into separate exports. A PNG/SVG with gradients is not a validated native dynamic Liquid Glass icon. Choose a renderer capable of the requested finish; retain editable geometry or a useful layered composition rather than flattening merely to avoid tuning it.
## Keep background viewing separate from appearance variants
| User request | Deliver |
| --- | --- |
| View an icon on light and dark backgrounds | The **same complete artwork**, with identical colors, opacity, lighting and designed base, on two different external surfaces |
| Design native/default/dark/tinted appearances | Deliberate coordinated variants, separately labeled and reviewed |
For a viewing comparison, change only the external background. Do not recolor, invert, lighten, darken or remove the icon's own base. Check light edges on a bright surface and dark edges on a dark surface; include relevant small-size samples.
Use [compare_icon_backgrounds.py](scripts/compare_icon_backgrounds.py) for a deterministic comparison:
```text
python scripts/compare_icon_backgrounds.py icon-a.png icon-b.png --labels "Alloy Dial" "Ceramic Gear" --output comparison.png
```
The helper preserves artwork colors and writes source/render hashes to a sidecar JSON. PNG input needs Pillow; SVG input also needs CairoSVG. This creates previews, not appearance variants.
## Bundled Figma workflows
Read [Assets and file workflow](references/figma-assets.md) when using a template or an existing Figma file. Reuse its canvas structure when suitable, keep the user's examples and source artwork, and place new studies in the requested destination or clear canvas space.
- Before every `use_figma` call, read [Canvas/API workflow](references/figma/figma-use/workflow.md) and the API references required for the actual operations.
- For an icon delivered as reusable components or appearance variants, also read [Component workflow](references/figma/figma-generate-library/workflow.md). Ordinary grouped artwork does not require a whole component library.
- For a requested custom effect/fill shader, read [Shader workflow](references/figma/figma-shaders/workflow.md) before `create_shader` or `update_shader`. Normal geometry and effects may already express the required finish.
Follow the enabled tool's current schema and any environment prerequisite. Original Figma `skillNames` labels in bundled modules are usage logging, not extra installations. Read [Sources and integration](references/sources.md) for provenance. A kit in Assets, a downloaded skill, a connected MCP service and the on-canvas agent are separate capabilities; report actual access limits without inventing a permanent block.
## Inspect and export
Review immediate recognition first, then apparent size, optical centering, silhouette, clean alpha edges, layer relationships and material restraint at intended small sizes on both external backgrounds. Remove detail that collapses. Inspect the rendered result, fix demonstrated issues and stop when the requested set passes.
For a standalone website/upload PNG requested to fit the visible icon, use the main silhouette to determine the artwork bounds. Nearly transparent exterior shadows and resampling fringes must not act as invisible padding. Remove unwanted exterior shadow/glow layers from editable source, retaining rounded corners, proper antialiasing and internal contact shadows. Preserve explicitly requested output dimensions: render the clean tight vector bounds to that pixel size rather than delivering a smaller crop or restoring a blank margin. A nonzero-alpha bounding box alone is insufficient. Read [Raster bounds and upload fit](references/raster-export.md) and use [trim_transparent_png.py](scripts/trim_transparent_png.py) with a suitable visible-alpha threshold when needed. Reopen the final PNG and inspect dimensions, visible bounds and middle-edge samples on checkerboard, bright and dark surfaces. Preserve aspect ratio. Keep intentional exterior shadows, aligned native layers and required host padding as separate labeled outputs when the task needs them.
Read [Host delivery](references/host-delivery.md) when producing release artwork. Preserve the host's actual file contract, app identity and custom user artwork. Keep the editable master separate from exported PNG/ICO or native Apple layers; exporting paired art does not implement automatic theme switching.
Deliver the actual requested concepts, editable source, preview and exports or affected Figma nodes. State whether artwork is a study, imported into Figma or applied to the application. Use English for new deliverables unless requested otherwise, while preserving existing localization.
