title: "@stnd/icon" aliases: [] created: 2026-07-05 07:53 modified: 2026-07-05 19:22 last_audited: 2026-07-14 audit_interval_days: 90 next_audit: 2026-10-12 audit_priority: 3 maturity: sprout mode: read publish: false status: active tags:

• package
• stnd theme: kernel type: package visibility: private

@stnd/icon

Unified icon system for the Standard Ecosystem.

ELI5

One <Icon icon="…" /> component, two very different things happen behind it depending on which one you use:

• Icon.astro (“inline” mode): at build time, the SVG gets fetched (from a local file, or a live call to api.iconify.design if it’s not local) and inlined straight into the page’s HTML. Zero client-side JS, works even for icons not in the local library — as long as the build machine has internet access when it builds.
• Icon.svelte (and Icon.astro‘s “file” mode): serves the SVG as a static file from /icons/<prefix>/<name>.svg at runtime. That folder is populated only from the local library (packages/icon/icons/) during the build — an icon that isn’t local won’t be there, and the request 404s. That’s what the build log’s "N missing from local library" warning means: those icons work fine in Icon.astro (inline) but will 404 as static files.

Use it:

---
import Icon from "@stnd/icon/Icon.astro";
---
<Icon icon="ph:house" />
<Icon icon="home" /> <!-- alias, see tokens.js -->

Overview

@stnd/icon provides a consistent API for using icons across different frameworks (Astro and Svelte) and libraries (Phosphor, MingCute). It supports static SVG inlining, local file serving, and animated Lottie icons.

Key Components

• Icon.astro: Build-time SSR icon component. Inlines SVGs for zero client-side JS.
• Icon.svelte: Runtime icon component. Serves SVGs as static files.
• Lottie.astro / Lottie.svelte: Components for rendering animated Lottie icons.

Features

• Multi-Library: Native support for Phosphor (ph:) and MingCute (mingcute:).
• Short Tokens: Use aliases like search instead of ph:magnifying-glass.
• Zero Config: Icons are bundled and resolved automatically.
• Resolution Order (resolve.server.js):
  1. Local SVG file (packages/icon/icons/<prefix>/<name>.svg).
  2. Live fetch from api.iconify.design (no installed-package step exists — the resolver goes straight from local file to network).

Usage

In Astro

---
import Icon from "@stnd/icon/Icon.astro";
---
<Icon icon="ph:house" />
<Icon icon="search" /> <!-- alias -->

In Svelte

<script>
  import Icon from "@stnd/icon/Icon.svelte";
</script>
<Icon icon="ph:rocket" width="2em" />

Tokens

Commonly used icons have short aliases defined in tokens.js. You can extend this mapping in your module configuration.

• search → ph:magnifying-glass
• settings → ph:sliders
• home → ph:house
• plant → ph:plant

Notes / Observations

• The build log’s icon-copy warning ("N missing from local library") only matters for file-mode icons (Icon.svelte, or Icon.astro’s file mode) — inline-mode Icon.astro resolves those same icons fine via the live API at build time. Don’t read the warning as “these icons are broken” across the board; check which mode is actually being used.

Todo

• [ ] Finish the icon system (WIP) — per the build logs tonight, ~87-270 [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework] icons are consistently missing from the local library across apps. Either backfill packages/icon/icons/ with the ones actually in use, or confirm the live-API fallback is an acceptable production dependency (a Cloudflare Worker relying on api.iconify.design being up, at build time only — not per-request — but still an external dependency worth being deliberate about).