Icon Library Integration — Scope Explainer

What it means & why it matters

What SessDev includes

• Selection between supported maintained libraries (Lucide as default, Heroicons as alternative) with a lightweight recommendation based on category coverage and bundle size.
• Ingestion of client-supplied SVG icons through a structured handoff: optimized via SVGO, validated for stroke/fill consistency, organized in a single folder.
• Tree-shaken imports so only the icons actually rendered ship to the client; verified bundle delta per icon added.
• A sizing token set (xs, sm, md, lg, xl) wired into the Icon component so every consumer references sizes by intent, not raw pixel values.
• Color binding through currentColor and the color tokens already in scope, so icons inherit foreground color and respect dark/light variants automatically.
• Accessibility wiring: aria-hidden by default for decorative icons, aria-label or title for meaningful icons, role=img where required, focus-visible behavior for interactive icons.
• A single Icon component as the only entry point, with TypeScript-typed icon names so unsupported icons fail at build time, not runtime.
• 1 validation pass: Lighthouse a11y check on icon-bearing components, bundle-size verification, license-compatibility check for the selected library.
• Handoff document listing the selected library (with version pin), the supplied-icons folder structure, the sizing/color token contract and the procedure to add a new icon without touching component code.

What is excluded

• Custom-icon illustration — drawing bespoke icons, designing pictograms specific to product features, or extending an existing library with custom glyphs.
• Icon-system design — defining stroke widths, corner radii, grid systems, optical-correction rules or the visual language an icon family follows.
• Iconography research, competitive icon-set audits, category-icon analysis or cultural-meaning reviews.
• Authorship of brand iconography — signature icons that double as brand marks, hero icons for marketing pages, app-icon variants beyond the favicon bundle covered in brand-asset injection.
• Mascot design, character illustration or any anthropomorphic-mark authorship.
• Illustration work — spot illustrations, empty-state illustrations, hero illustrations or any non-icon visual asset.
• Authorship of animated icons or Lottie files; wiring of an existing animated-icon asset is covered by the UI-animation scope.
• Audit of the supplied icon set, gap analysis against product needs or recommendations to add or remove icons.
• Multilingual pictogram research — verifying icon meaning across cultures, sourcing locale-specific symbols, or RTL-mirroring guidance for directional icons.
• Expansion of the supplied icon set — commissioning missing icons from an illustrator, requesting variants from the library author, or backfilling categories the library does not cover.
• Authorship of the brand-iconography system documentation — usage rules, do/don't grids, brand-guidelines sections on iconography.

Risks if this is mis-configured

• Icon sprawl across multiple libraries

  Mixing Lucide with Heroicons with one-off SVGs from various sources produces visually inconsistent UI and inflates the bundle. The scope enforces one primary library plus a single supplied-icons folder; ongoing discipline as new components ship is what the Care retainer enforces.

• Missing accessibility labels on meaningful icons

  An icon-only button without aria-label is invisible to assistive technology, breaking WCAG 4.1.2 and exposing the product to accessibility-compliance claims. The Icon component in scope enforces explicit decorative vs meaningful intent; bypassing it re-introduces the risk.

• Payload bloat from non-tree-shaken imports

  Importing an entire icon library as a single default export ships hundreds of unused icons to every user. The wiring in scope uses per-icon imports verified for tree-shaking; a future refactor that breaks the import pattern can re-introduce the bloat silently.

• Brand drift from mixed-library iconography

  Lucide and Heroicons follow different stroke and corner philosophies. Mixing them inside a single screen produces a visual inconsistency users perceive without being able to name. The handoff documents the single-library rule; enforcing it long-term is a Care-retainer responsibility.

• Inconsistent sizing across consumers

  Hardcoded pixel values on individual icons (size=20, size=18, size=22) defeat the sizing-token system and produce optically uneven UI. The Icon component in scope only accepts token values; replacing it with raw library imports re-opens the risk.

• SVG-vulnerability exposure from un-sanitized icons

  Client-supplied SVGs that retain inline scripts, foreign objects or remote references can execute in the browser when inlined. The ingestion step in scope runs SVGO with a strict sanitization config; bypassing it for a single icon re-opens the vulnerability vector.

• Icon-license violations

  Lucide ships under ISC and Heroicons under MIT, but client-supplied icons may carry restrictive licenses (paid sets, royalty-required marks, CC-NC-only). The validation step checks license compatibility for the supplied folder; adding paid-set icons later without a license check is the most common drift cause after launch.

Related scope items

• brand_asset_injectionApp icons and favicons live in brand-asset injection; product-level glyph icons live here. Same exclusion principle: integration, not authorship.
• color_token_setupIcons inherit foreground color through the color tokens defined in the color-token scope; dark/light variants flow automatically.
• typography_integrationIcon-font libraries can ship as fonts; wiring an existing icon font is covered here, authoring one is not.
• ui_animation_implementationAnimated icons (Lottie, motion variants) are wired through the UI-animation scope using the supplied animation files.
• media_infrastructureInlined SVGs use the same delivery primitives as images for caching and CSP rules.
• technical_seoIcon payload size feeds Core Web Vitals (LCP) which is wired through the technical-SEO scope.

Frequently asked questions

Which icon library do you use by default?

Lucide is the default for new builds (ISC license, broad coverage, active maintenance). Heroicons is the supported alternative when the design team prefers its style. Other libraries can be wired but become a client-led decision and may carry license implications.

Can SessDev draw custom icons for us?

No. Custom-icon illustration is an illustration-discipline deliverable and is explicitly out of scope. SessDev integrates SVG icons your design team or external illustrator supplies, ingested through a structured handoff.

Can you design an icon system for our brand?

No. Icon-system design — stroke widths, grid systems, optical-correction rules, brand-iconography rules — is a brand-system deliverable and is out of scope. SessDev integrates the system your design team delivers.

How do you handle icon accessibility?

The Icon component in scope enforces an explicit decorative vs meaningful choice at the API level: decorative icons receive aria-hidden, meaningful icons require an aria-label. Interactive icon-only buttons require a label at build time, not runtime.

Will the icon layer be tree-shaken?

Yes. The wiring uses per-icon imports verified for tree-shaking, and the validation step confirms the per-icon bundle delta. Only icons actually rendered are shipped to the client.