• Date: 2026-06-06
• Status: Accepted
• Phase / Feature: Foundation v1/v2 · icon library scope + sequencing
• Closes: ADR 0036 Q7 — "Icon set v2 → 300+"
• Builds on: ADR 0036 §4 (100 custom-designed icons, Solid/Line, RTL-aware), T7.4 (per-icon exports + sprite, ADR 0040 RTL flag), ADR 0041 (user-uploaded brand icons fill the gap before our coverage catches up)

Context

v1 ships 7 essentials (check / x / chevron-down / person / alert / info / error). ADR 0036 §4 promised 100 custom-designed icons across categories (Navigation, Position, Actions, Files, Communication, Media, User, Time, Tools, Shapes, Tech, Money, Location, Misc). The remaining 93 are deferred to a design pass that hasn't happened yet — explicitly parked until we can do it properly.

Q7 asked the next question: what about v2's growth past 100? Industry libraries (Heroicons, Phosphor, Lucide, Carbon) ship 300–800 icons. Designers have a baseline expectation from those tools.

This ADR doesn't dictate "draw 300 icons" — it sequences the work, scopes each milestone, and fixes the delivery shape so v2 doesn't drag the schema into another redesign.

Decision

§1 — Three milestones

The order is fixed: v1.x precedes v2.0 by design. Shipping 300 icons before validating the 100-icon scope is the classic icon-pack mistake — coverage breadth without weight balance + style consistency.

§2 — Per-milestone delivery shape

Each milestone ships through the same pipeline (T7.4):

• One <NameIcon> React component per icon × variant (Solid + Line) = 2× the icon count in tree-shakeable files.
• The sprite (dist/icons-sprite.svg) auto-grows from build-icons.mjs. RTL flag (ADR 0040) set per icon at design-pass review.
• Storybook icon catalog updates from the same source.

No schema change required to grow from 7 to 300. This is the design intent of T7.4 + ADR 0040: the pipeline is the same shape at any scale, the design effort is the variable. ADR 0041 (user-uploaded brand icons) absorbs the gap while the in-house set grows — designers don't wait for v2 to ship the rest, they upload what they need.

§3 — Category priorities for v1.x → v2.0

The 100-icon target hits the meaningful productivity threshold per industry data (Carbon, Material, Lucide). The 300-icon target is where coverage feels "complete" to a designer accustomed to current libraries. The growth from 100 to 200 (v1.x → v2.0 first batch) should hit the action verbs and status indicators first — those have the highest re-use per icon. Surface decorations and metaphorical icons (the long tail of pack libraries) come last because the brand-import upload flow already absorbs them.

Priority order (descending coverage impact):

1. Action verbs (~80 icons across v1.x + v2.0): copy/paste/edit/save/delete/duplicate/move/upload/download/share/print/lock/unlock/pin/star/bookmark + their state variants.
2. Navigation directionals (~30): all chevrons / arrows / corner arrows × 4 directions. ADR 0040's rtl: 'flip' flag carries semantic weight here.
3. Status + feedback (~25): check / x / warning / info / error variants + dot/badge counterparts + loading / spinning / paused. Heavily reused.
4. File / format glyphs (~35): generic doc / image / video / audio / archive / code / spreadsheet / pdf / link / cloud + their state overlays.
5. Communication (~25): email / chat / call / video-call / mention / reply / forward / send + read/unread states.
6. User + identity (~20): person variants / group / role badges (admin/star/etc) / avatar placeholders.
7. Time (~15): calendar / clock / timer / history / schedule + relative-time arrows.
8. Layout + structure (~25): grid / list / table / sidebar / fullscreen / split / sort / filter.
9. Long tail (~45 in v2.0): currency / weather / transport / health / education / accessibility / brand-style misc.

Total: ~300 at v2.0. This priority list is intentionally not constraints-as-code (the icon catalog is design source) — it's a sequencing recipe for the design pass.

§4 — Cadence + version bumps

• v1.1: +20 icons (top of priority list). Minor bump per ADR 0039.
• v1.2: +20 more.
• ... continuing in 20-icon batches up to 100 ≈ 5 minor releases.
• v2.0: jump to 300 with the new categories + 4 vertical-specific groups. Major bump per ADR 0039 §2/§3 ritual.

Each minor release runs the standard ADR 0040 reviewer checklist per icon (RTL flag, variant pair consistency, line weight match against existing siblings). No icon ships without both Solid and Line variants. No icon ships without an RTL decision recorded.

§5 — Brand-import fills the gap

Until v1.x lands, ADR 0041 brand_icon upload absorbs every project-specific need: a designer who wants a microscope icon for a healthcare product uploads it via the brand-icon flow, ships the project, and the next time Foundation grows that icon they can Re-bind to Foundation. The interim isn't blocking — it's user-resolvable.

§6 — Drawing standards (locked)

Foundation icons follow a single style guide so v2's 300 don't look like a different pack from v1's 100:

• 24×24 viewbox at all sizes; smaller usage downscales, never re-traces.
• Stroke weight 1.5px for Line variants. Solid variants fill with currentColor.
• Square / round line caps + line joins consistent per category (round = soft, square = technical).
• Optical alignment over geometric — letters and dot-style accents sit on the design grid the eye reads, not the math grid.
• RTL flag decided at draw time, not retro-fitted (ADR 0040 §"Open questions" reviewer checklist).

The standards file lives in packages/foundation/icons/_index.md and updates with v2 when accessibility tooling necessitates an extra rule (e.g. minimum contrast against a 1px gridline).

Anti-patterns explicit

• Do not import from a public icon pack as a shortcut. ADR 0036 §4 explicitly chose custom-designed for visual identity; backing out trades short-term speed for permanent style debt.
• Do not ship Solid without Line (or vice versa). Pair consistency is the contract.
• Do not ship icons without RTL flag set. ADR 0040 default is keep; making it explicit per icon catches missed directional intent at review.
• Do not grow past 300 by importing user-uploaded brand icons into the package. Those are project-scoped; the Foundation set stays curated.
• Do not retro-fit a per-icon visual change after release. Once an icon ships in a minor, the only edit path is a major upgrade with explicit migration (ADR 0039 ritual).

Open questions / parking

• Animation / motion variants (spinning loader, animated checkmark). Out of v2 scope; designers compose motion at the component layer (Skeleton, Progress) using existing motion tokens.
• Multi-color icons (status badges with two distinct fill colors). Parked in ADR 0041 §"Open questions"; same answer applies here.
• Iconography licensing if Foundation is ever extracted as a separately distributable package. Currently bundled with ARNO; if external distribution becomes a thing, the icon set ships under the same OFL/MIT-class license — out of scope until then.
• Per-project icon overrides (a designer wants Foundation's check to look different in their project). Use ADR 0041 brand_icon upload with the same name; rendering precedence in the eventual editor surface picks brand over Foundation when both exist.