Skip to content

ADR 0025 — Shared UI Icon System

  • Status: ACCEPTED FOR NS3-114
  • Date: 2026-09-07
  • Scope: @ctc/ui icon owner, workspace sidebar navigation and named shared actions
  • Authority: direct user approval after the NS3-114 icon proposal

Context

The workspace sidebar and several shared actions used text-only controls or local inline SVGs. The attached icon prompt requires a consistent library while preserving labels, routes, access checks, sidebar geometry and tenant theme colors. The repository has no existing icon dependency.

Options

  1. Keep local inline SVGs and add more one-off icons. This has no dependency delta, but preserves inconsistent geometry and makes the approved navigation mapping difficult to maintain.
  2. Add lucide-react to the existing @ctc/ui owner and expose a bounded @ctc/ui/icons export. Individual named imports remain tree-shakeable, icons use currentColor, and the Web app does not own a second icon dependency.
  3. Add an icon font or a new internal SVG registry. Either option creates a new rendering/asset convention, adds maintenance surface and provides no immediate advantage over the existing React UI package.

Decision

Choose option 2. Add lucide-react only to @ctc/ui, expose only the icons required by this Task, and consume them by named export. Icon size is controlled by shared design tokens; color remains currentColor so Cobalt and Indigo themes continue to own the visual color.

The approved navigation mapping is the NS3-114 proposal, including CircleDot for unknown leaf URLs. The approved shared action mapping is Plus, Pencil, Trash2, RefreshCw and ListFilter for Create, Edit, Delete, Retry and Filter respectively. No label, route, access decision, menu projection, action handler or sidebar width changes.

Consequences

Positive:

  • Sidebar and named shared actions have one icon source and one size convention.
  • The dependency is owned by the existing UI package rather than duplicated in the Web app.
  • Icons inherit tenant theme colors and remain accessible decorative content beside existing labels.

Negative:

  • @ctc/ui gains one runtime dependency and one bounded public subpath export.
  • The selected Lucide names must be maintained when the menu mapping grows.

Rollback and revisit

Rollback removes the bounded icon export, dependency and icon markup while preserving the existing labels and action handlers. Revisit if the UI package needs a second icon source, if bundle evidence shows the bounded imports are not tree-shaken, or if a future design decision requires a different icon vocabulary.

---

Source: new-system/docs/decisions/0025-shared-icon-system.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.