UI Asset Sourcing

UI asset sourcing

A design direction with no assets becomes a wireframe with lorem ipsum and grey boxes. Filling those boxes is where two specific, very visible failures happen:

1. Invented SVG path data. A model asked for "a Stripe logo" or "a calendar icon" will confidently emit a <path d="M12 2L2 7..."> that renders as an unrecognizable blob. Path data cannot be recalled correctly.
2. Emoji standing in for icons. 🚀 in a feature card is the single fastest tell of generated UI, and it breaks cross-platform (rendering differs per OS) and for screen readers.

Both are avoidable by fetching rather than recalling. That is most of what this skill is.

Icons

Pick one set and stay in it. Mixing sets is visible immediately — stroke weights and corner radii will not match, and the interface reads as assembled rather than designed.

How to get the actual SVG — never write path data from memory:

• Ask the user to install the package (lucide-react, @heroicons/react, @phosphor-icons/react, …) and import icons by name. This is the right answer for almost every real project: the names are memorable and correct, the path data comes from the package.
• If a raw SVG file is genuinely needed and you have network access, scripts/fetch_icon.py pulls it from the registry's actual published source (Lucide/Heroicons/Tabler/Phosphor/Simple Icons — see Automated Fetching below) instead of hand-writing it — this is what closes the loop asset_lint.py's invented_svg_path check can otherwise only catch after the fact.
• If you do not have network access, say so and give the import line instead — a stated limitation is better than a plausible-looking wrong path.

Automated Fetching

python scripts/fetch_icon.py --library lucide --name arrow-right          # prints real SVG to stdout
python scripts/fetch_icon.py --library lucide --name arrow-right --out a.svg
python scripts/fetch_icon.py --list-libraries
python scripts/fetch_icon.py --demo                                       # offline, no network needed

Fetches from each registry's real published URL (unpkg.com/raw.githubusercontent.com for Lucide/Heroicons/Tabler/Phosphor/Simple Icons — see the script header for the exact templates) and validates the response actually parses as SVG with a real shape element before accepting it — several of these CDNs return HTTP 200 with an HTML or plain-text error body for a bad name, so status code alone isn't proof. Fails loud with the resolved URL on a miss rather than writing garbage to disk. --demo proves the fetch/validate logic offline by injecting fixed responses (valid SVG, a disguised 404 page, an empty body) — it does not require network access, but real usage does; --list-libraries shows every registry's URL template without fetching anything.

Deliberately does not vendor icon files into this repository — a copy here would silently go stale the moment the upstream registry updates, the same "quietly wrong forever" failure this catalog's other data-integrity gates exist to catch. Fetch at generation time instead of storing a copy.

Consistency rules that matter more than the set you picked:

• One nominal size (usually 24×24) with a fixed stroke width across the whole UI; scale via the container, not by redrawing at another weight.
• Icons that carry meaning need an accessible name (aria-label, or adjacent text). Decorative icons get aria-hidden="true" so they are not announced.
• An icon alone is rarely enough for a primary action — pair with a label unless the metaphor is universally understood (close, search, back).
• Match the icon style to the aesthetic: outline icons for minimal/Swiss, filled/duotone for playful/claymorphic, sharp geometric for brutalist. A rounded friendly icon set inside a brutalist layout fights the direction.

Imagery

Decide first what kind of imagery the direction calls for — see references/imagery_direction.md for the per-category guidance (photography, illustration, abstract/gradient, 3D, or deliberately none). The wrong kind is a bigger error than a mediocre execution of the right kind.

When to generate rather than source stock:

Generate when the image must sit inside the palette you already chose, when the subject is specific to this product, or when stock would read as generic-corporate (the smiling-team-around-a-laptop problem). Aria Code has two backends, both MCP-exposed:

• aria.report.generate_image_local — self-hosted SDXL-Turbo. No API key, no per-call cost. Good for texture, abstract backgrounds, and light restyling. Weak at aggressive restyling and cannot render legible text — do not ask it for anything with words in the image.
• aria.report.generate_image — OpenAI gpt-image-1. Real per-call cost, so it requires confirmed: true; call aria.report.estimate_image_cost first. Markedly better at instruction-following, flat/graphic styles, and legible text.

Put the palette's hex values in the prompt. An image generated without them will land near-but-not-on your colors, which reads worse than an obviously different image.

Source stock instead when you need real people, real places, or photojournalistic credibility — generated humans still fail on hands, teeth, and crowd scenes, and a generated "customer photo" on a testimonial is a misrepresentation, not a style choice. Point the user at Unsplash/Pexels (free, permissive) and have them confirm the licence for commercial use themselves.

Logos and brand marks

• Real company logos: Simple Icons only. Do not draw them — scripts/fetch_icon.py --library simple-icons --name "<brand>" pulls the real mark. Note Simple Icons slugs are NOT kebab-case like the other four registries (americanexpress, nodedotjs, cplusplus, not hyphenated) — the script handles this, a manual URL guess likely won't.
• The user's own logo: ask for the file. Do not generate a substitute and present it as theirs.
• A new logo for a new brand is a real design engagement, not an asset-fetch task — say that plainly rather than generating something disposable.

Placeholder content

Grey boxes and lorem ipsum hide layout problems until they are expensive to fix. Use realistic content: plausible names, real-length copy, and images at the aspect ratio the real ones will use. A card designed against a 3-word title breaks the moment a 14-word title arrives.

Workflow

1. Confirm the design direction exists (style, palette, type). If not, stop — that is industry-design-direction's job, and assets chosen before a direction will not match it.
2. Pick one icon set from the table, matched to the aesthetic, and state the install/import method.
3. Decide the imagery kind from references/imagery_direction.md.
4. For generated imagery: build prompts that carry the palette hex values, estimate cost if using the paid backend, and generate.
5. For stock or real logos: point at the correct source; do not fabricate.
6. Run the quality gate — prefer scripts/asset_lint.py over eyeballing the three mechanically-checkable items (see Automated Checks below).

Automated Checks

Three of the Quality gate items below are mechanical, not judgment calls, so scripts/asset_lint.py checks them by grepping the actual generated code instead of relying on the gate being applied by eye:

python scripts/asset_lint.py path/to/src            # scan real files/dirs
python scripts/asset_lint.py --demo                 # no data needed

• emoji_icon (error) — an emoji character standing in for an interface icon.
• invented_svg_path (warn) — a long inline <path d="..."> with no nearby source citation (an import, a // source: ... comment). Can't prove the path data was hand-recalled rather than fetched, but this is exactly the shape that failure takes — a "logo" with no cited source renders as a blob.
• mixed_icon_set (warn) — imports from more than one known icon library (Lucide, Heroicons, Phosphor, Tabler, react-icons) across the scanned paths.

The remaining Quality gate items (accessible names, palette hex values in generated-image prompts, no fabricated people/places/brands, realistic placeholder length) stay judgment calls this script doesn't attempt — automating those would launder a guess as a verified fact, which is worse than leaving them as prose. Note this script is intentionally separate from ui-design-system's design_lint.py: that one enforces code against the user's own declared design-tokens.json, a different, tokens-shaped concern from universal icon/asset hygiene, which applies whether or not a design system has been frozen yet.

Quality gate

• Zero emoji used as interface icons?
• Zero hand-written SVG path data — every icon and logo either imported by name, fetched from a real source, or explicitly flagged as needing the user to fetch it?
• One icon set throughout, at one nominal size and stroke width?
• Meaningful icons have accessible names; decorative ones are aria-hidden?
• Generated imagery carries the actual palette hex values in its prompt?
• Nothing generated that misrepresents a real person, place, or company — no synthetic "customer photos", no drawn-from-memory brand marks?
• Placeholder text at realistic length, not lorem ipsum at convenient length?

References

• references/imagery_direction.md — which kind of imagery suits which design direction, prompt patterns that keep generated images on-palette, and the cases where generating is the wrong call