31 lines
4.7 KiB
Markdown
31 lines
4.7 KiB
Markdown
# Icon production
|
|
|
|
Use suitable template icons first. For new icons, prefer directly authored SVG/native shapes for simple forms, ImageGen for complex imagery, and external ready icons as a supplement. Choose a recognizable information meaning and keep stroke weight, corners, perspective, optical scale and detail consistent at the intended size. An icon should remain understandable without nearby explanatory prose, or deliberately reuse the same established icon as its counterpart.
|
|
|
|
For an approved mockup, preserve the accepted icon identity and styling rather than substituting a different icon from that priority list. If native components/SVG are impractical for faithful reproduction, [C28 requires ImageGen](visual-design.md#elements-that-need-imagegen) for the element. Deliver the project-local picture with a transparent background and one color or a few simple semantic colors, retaining alpha masks/layers, adjustable/fixed palette bindings and actual recoloring evidence. Keep its reference, generation provenance and usable asset in the project. It remains a disclosed picture with color adjustability, not editable internal geometry or an SVG paint-contract icon. The reusable SVG contract below still applies before publishing it as that template/library icon type or using the paint helper.
|
|
|
|
## One deliverable contract for all sources
|
|
|
|
For reusable adjustable icons, all routes must support approved whole or partial palette recoloring. Deliver original source, normalized SVG, a paint contract, palette bindings, provenance and preview evidence together. Use stable IDs for semantic parts, explicit fill/stroke attributes and per-channel rules. `palette` permits a semantic token to bind an index; `fixed` preserves an exact literal; `structural` preserves `none`. Unlisted channels preserve their source paint. Shared tokens express shared roles; separate tokens permit independent colors.
|
|
|
|
Whole-icon coloring means binding every intended adjustable part to one palette index. It never means replacing every matching color in a bitmap. Keep fixed details, white details, opacity, holes, masks, geometry and paint order intact. Validate IDs, explicit source paint, duplicate/missing bindings and palette indices. See [the exact schema](template-interface.md#svg-paint-contract).
|
|
|
|
For ImageGen or external assets, first separate the semantic parts in the production source. Reconstruct the final icon as compliant SVG/native geometry when necessary. A flat raster with several apparent colors does not identify recoloring permissions. If using a layered/masked intermediate, retain reviewed per-role masks; do not infer them from matching source colors. The bundled paint helper handles explicit SVG fill/stroke, not raster segmentation or gradient-stop recoloring. A fixed-color PNG alone is not a completed adjustable icon.
|
|
|
|
Keep an exact official mark or evidence image as its original asset when that is its assigned role; do not relabel it as a newly generated icon to bypass source fidelity. Use only the template/user's explicitly permitted identity derivatives.
|
|
|
|
## Project-local icons
|
|
|
|
Keep new materials under the caller's project, outside a locked template snapshot. For an SVG icon consumed by the paint helper, a local material descriptor contains `schema_version: 1`, `id`, project-relative `path` and `paint_contract`, and a `bindings` array of `{selector, channel, palette_index}`. Paths resolve beside the descriptor. The bindings must cover exactly the contract's palette pairs, and at least one pair must be adjustable. This lets an author add an SVG icon without publishing a new template or modifying vendor files. C28 bitmap materials retain their alpha/semantic masks and verified recoloring inputs separately; this SVG descriptor and `--material` route do not automatically support PNG recoloring.
|
|
|
|
```sh
|
|
python /path/to/skill/scripts/paint_asset.py \
|
|
--manifest /absolute/template/manifest.json --theme selected-theme \
|
|
--material /absolute/project/assets/new-icon/material.json \
|
|
--output /absolute/project/assets/derived/new-icon.svg
|
|
```
|
|
|
|
For a supplied template icon use `--asset <role>` instead of `--material`. Both modes preserve fixed/structural/unlisted channels and protect existing output. The local descriptor supplies bindings to the selected theme's palette; it cannot change that palette. Retain the descriptor and original with the project.
|
|
|
|
Render the original and derivative on their intended backgrounds at actual use size. Check recognition, consistent optical scale, stroke visibility, fixed details and transparent openings. XML/paint validation is separate from this visual check. Insert resulting geometry into the page's native source when native editing is required; a selectable image alone does not prove native icon objects.
|