motif-design 0.1.0 → 0.2.0

package/README.md

@@ -20,7 +20,7 @@ This auto-detects your AI runtime (Claude Code for v1), installs design intellig
 |---------|-------------|
 | `/motif:init` | Interview, vertical detection, design brief |
 | `/motif:research` | 4-agent parallel research, locked design decisions |
-| `/motif:system` | Generate tokens + component specs + visual showcase |
+| `/motif:system` | Generate tokens + component specs + icon catalog + visual showcase |
 | `/motif:compose [screen]` | Build screen with fresh agent context |
 | `/motif:review [screen\|all]` | 4-lens heuristic evaluation, scored /100 |
 | `/motif:fix [screen]` | Fix review findings systematically |
@@ -41,13 +41,15 @@ This auto-detects your AI runtime (Claude Code for v1), installs design intellig
 
 ## How It Works
 
-Three things make Motif different from generic UI generation:
+Four things make Motif different from generic UI generation:
 
 **Domain intelligence.** Vertical databases contain domain-specific color palettes, typography scales, component patterns, layout conventions, and anti-patterns. When you tell Motif you are building a fintech app, every design decision draws from established fintech patterns -- not random defaults.
 
 **Fresh context per screen.** Each screen is composed by a fresh subagent with a full 200K token context window loaded with your design system, research decisions, and domain knowledge. There is no context degradation over time. The tenth screen gets the same quality as the first.
 
-**Design system enforcement.** Hooks run during composition to catch hardcoded color values, banned fonts, spacing violations, and accessibility issues before they ship. The design system is not advisory -- it is enforced.
+**Icon library integration.** The system architect selects icons from curated libraries (Phosphor, Lucide, Heroicons) based on your domain vertical, generates an `ICON-CATALOG.md` with CDN links and usage syntax, and the composer consumes it -- so every screen uses real, consistent icons instead of placeholder text or hallucinated class names.
+
+**Design system enforcement.** Hooks and validators run during composition to catch hardcoded color values, banned fonts, spacing violations, import cycles, naming conflicts, and accessibility issues before they ship. The design system is not advisory -- it is enforced.
 
 ## Architecture
 
@@ -64,14 +66,15 @@ User runs /motif:compose login
          |
          v
   Fresh Subagent (200K context)
-  loads tokens.css + COMPONENT-SPECS.md + vertical DB
-  builds screen -> commits atomically
+  loads tokens.css + COMPONENT-SPECS.md + ICON-CATALOG.md + vertical DB
+  builds screen -> validates -> commits atomically
 ```
 
 Motif uses a **core + adapters** architecture:
 
 - **Core** (`core/`) -- shared workflows, references, templates, vertical databases. Runtime-agnostic.
 - **Runtimes** (`runtimes/`) -- thin adapters per AI tool. v1 ships Claude Code; others follow with zero core changes.
+- **Scripts** (`scripts/`) -- validation and analysis tools (compose-validator, token-extractor, gap-analyzer, contrast-checker).
 
 Installed file layout (Claude Code):
 
@@ -81,11 +84,87 @@ Installed file layout (Claude Code):
 .planning/design/           Generated design artifacts (tokens, specs, screens)
 ```
 
+## Verticals
+
+Motif ships with domain intelligence for:
+
+| Vertical | File |
+|----------|------|
+| Fintech | `core/references/verticals/fintech.md` |
+| Health | `core/references/verticals/health.md` |
+| SaaS | `core/references/verticals/saas.md` |
+| E-commerce | `core/references/verticals/ecommerce.md` |
+
+Each vertical contains color palettes, typography guidance, component patterns, layout conventions, icon recommendations, and anti-patterns specific to that domain. New verticals can be added using `core/templates/VERTICAL-TEMPLATE.md`.
+
 ## Requirements
 
 - Node.js >= 22.0.0
 - Claude Code (v1.0 -- more runtimes coming)
 
+## Contributing
+
+Contributions are welcome. Here's how to get started.
+
+### Setup
+
+```bash
+git clone https://github.com/Austine3000/motif.git
+cd motif
+npm install
+```
+
+### Project Structure
+
+```
+bin/              Installer (npx entry point)
+core/             Runtime-agnostic workflows, references, templates, verticals
+runtimes/         Runtime-specific adapters (claude-code for v1)
+scripts/          Validation and analysis tools
+test/             E2E and validation tests
+```
+
+### Running Tests
+
+```bash
+# Run the full validation suite against a test project
+bash test/validation/run-all-validations.sh --controlled /path/to/test-project
+
+# Run the compose validator on a screen
+node scripts/compose-validator.js --screen login --files src/login.html
+```
+
+### Adding a Vertical
+
+1. Copy `core/templates/VERTICAL-TEMPLATE.md` to `core/references/verticals/<name>.md`
+2. Fill in domain-specific palettes, typography, component patterns, and anti-patterns
+3. Add the vertical to the installer's detection logic in `bin/install.js`
+
+### Adding a Runtime Adapter
+
+1. Create a new directory under `runtimes/<runtime-name>/`
+2. Implement thin command files that load core workflows
+3. Document the adapter in `core/references/runtime-adapters.md`
+
+### Commit Convention
+
+This project uses scoped prefixes:
+
+```
+feat(scope):     New feature
+fix(scope):      Bug fix
+docs(scope):     Documentation
+chore(scope):    Maintenance
+design(scope):   Design system work (init, research, system, compose, review, fix, evolve, quick)
+```
+
+### Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes with clear, atomic commits
+3. Ensure validation passes on any modified workflows or templates
+4. Open a PR with a summary of what changed and why
+
 ## License
 
 [MIT](LICENSE)

package/core/references/context-engine.md

@@ -33,6 +33,7 @@ Every planning/design file has a maximum token budget. If a file exceeds its bud
 | COMPONENT-SPECS.md | 5,000 | Component XML specs |
 | [screen]-SUMMARY.md | 500 each | Per-screen summary |
 | [screen]-REVIEW.md | 1,000 each | Per-screen review |
+| ICON-CATALOG.md | 1,000 | Per-project icon name lookup for composer |
 
 **Total context budget for a fully-loaded subagent**: ~15,000 tokens of context files, leaving ~185,000 tokens for the actual work.
 
@@ -48,7 +49,7 @@ Different commands need different slices of context. These profiles define exact
     .planning/design/DESIGN-BRIEF.md
   </always_load>
   <load_if_exists>
-    .claude/get-motif/verticals/{vertical}.md
+    .claude/get-motif/references/verticals/{vertical}.md
   </load_if_exists>
   <never_load>
     tokens.css
@@ -69,7 +70,8 @@ Different commands need different slices of context. These profiles define exact
   <load_if_exists>
     .planning/design/research/02-visual-language.md
     .planning/design/research/03-accessibility.md
-    .claude/get-motif/verticals/{vertical}.md
+    .claude/get-motif/references/verticals/{vertical}.md
+    .claude/get-motif/references/icon-libraries.md
   </load_if_exists>
   <never_load>
     research/01-vertical-patterns.md (already synthesized in DESIGN-RESEARCH.md)
@@ -86,6 +88,7 @@ Different commands need different slices of context. These profiles define exact
     .planning/design/PROJECT.md
     .planning/design/system/tokens.css
     .planning/design/system/COMPONENT-SPECS.md
+    .planning/design/system/ICON-CATALOG.md
   </always_load>
   <load_if_exists>
     .planning/design/DESIGN-RESEARCH.md
@@ -96,6 +99,7 @@ Different commands need different slices of context. These profiles define exact
     Raw research files (already synthesized)
     Other screen source code (only summaries)
     DESIGN-SYSTEM.md (tokens.css + COMPONENT-SPECS.md are sufficient)
+    icon-libraries.md (already distilled into ICON-CATALOG.md)
   </never_load>
 </context_profile>
 ```
@@ -112,6 +116,7 @@ Different commands need different slices of context. These profiles define exact
   <load_if_exists>
     .planning/design/PROJECT.md
     .planning/design/screens/{screen}-SUMMARY.md
+    .planning/design/system/ICON-CATALOG.md
   </load_if_exists>
   <never_load>
     DESIGN-BRIEF.md

package/core/references/icon-libraries.md

@@ -0,0 +1,333 @@
+# Icon Library Reference
+
+Single source of truth for icon library metadata, domain affinity, and the selection algorithm. All downstream phases (vertical vocabularies, pipeline integration, enforcement) read from this file.
+
+---
+
+## Curated Libraries
+
+### Phosphor Icons
+
+| Property | Value |
+|----------|-------|
+| Version | @phosphor-icons/web@2.1.2 |
+| CDN (per-weight) | `https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/{weight}/style.css` |
+| Usage Syntax | `<i class="ph ph-{name}"></i>` (regular) / `<i class="ph-{weight} ph-{name}"></i>` (other weights) |
+| Icon Count | ~1,248 base icons (x6 weights = ~7,488 variants) |
+| Weights/Variants | thin, light, regular, bold, fill, duotone (6 weights) |
+| License | MIT |
+| Requires JS | No |
+| Last Verified | 2026-03-04 |
+
+**Weight class mapping:** `ph` (regular), `ph-thin`, `ph-light`, `ph-bold`, `ph-fill`, `ph-duotone`
+
+**Duotone note:** Secondary layer renders at 20% opacity by default. Detailed duotone styling is deferred to v1.2+ (REQUIREMENTS.md ICON-02). This phase documents duotone as a weight option only.
+
+---
+
+### Lucide
+
+| Property | Value |
+|----------|-------|
+| Version | lucide@0.576.0 |
+| CDN | `https://unpkg.com/lucide@0.576.0` |
+| Usage Syntax | `<i data-lucide="{name}"></i>` + `lucide.createIcons()` |
+| Icon Count | ~1,702 icons |
+| Weights/Variants | Single outline style only (stroke width adjustable via attribute) |
+| License | ISC |
+| Requires JS | **Yes** -- must call `lucide.createIcons()` after DOM load |
+| Last Verified | 2026-03-04 |
+
+**IMPORTANT:** Lucide is the only library in the curated set that requires JavaScript initialization. The CDN script exposes a global `lucide` object; call `lucide.createIcons()` after the DOM is ready to render all `[data-lucide]` elements as inline SVGs.
+
+**Version caveat:** Lucide is pre-1.0 (v0.576.0). Icon names may change between minor versions. Pin to this version and review quarterly. When Lucide reaches 1.0, update the pin and document the migration.
+
+---
+
+### Material Symbols
+
+| Property | Value |
+|----------|-------|
+| Version | Google Fonts CDN (evergreen -- no version pin) |
+| npm Version (self-hosting) | material-symbols@0.40.2 |
+| CDN (Outlined) | `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined` |
+| CDN (Rounded) | `https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded` |
+| CDN (Sharp) | `https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp` |
+| Usage Syntax | `<span class="material-symbols-{style}">{icon_name}</span>` |
+| Icon Count | ~2,500+ icons |
+| Weights/Variants | 3 style families (Outlined, Rounded, Sharp) x variable font axes (FILL 0-1, wght 100-700, GRAD -50 to 200, opsz 20-48) |
+| License | Apache 2.0 |
+| Requires JS | No |
+| Last Verified | 2026-03-04 |
+
+**Version-pinning exception:** Material Symbols via Google Fonts is evergreen -- there is no `@0.40.2` in the Google Fonts URL. The font family name ("Material+Symbols+Outlined") is the stable identifier. For self-hosting with a pinned version, use the npm package `material-symbols@0.40.2`. This is the ONE exception to the CDN version-pinning rule.
+
+**Naming convention:** Material Symbols uses underscores (`shopping_cart`), not hyphens. This is the most common source of icon name errors.
+
+**Critical CSS requirement:** Always set explicit `font-size` AND matching `opsz` value. Default optical size is 48px, which renders icons oversized if not overridden.
+
+---
+
+### Tabler Icons
+
+| Property | Value |
+|----------|-------|
+| Version | @tabler/icons-webfont@3.36.1 |
+| CDN | `https://cdn.jsdelivr.net/npm/@tabler/icons-webfont@3.36.1/dist/tabler-icons.min.css` |
+| Usage Syntax | `<i class="ti ti-{name}"></i>` |
+| Icon Count | ~6,038 total (4,985 outline + 1,053 filled) |
+| Weights/Variants | Outline only via webfont (filled webfont has known bug -- see below) |
+| License | MIT |
+| Requires JS | No |
+| Last Verified | 2026-03-04 |
+
+**Known bug:** The filled variant webfont has a conflict where outline and filled icons cannot be used simultaneously via CDN. The filled webfont replaces outline classes rather than adding new ones (GitHub issue #1452, verified January 2026). **Use outline only for webfont/CDN usage.** The SVG package works fine for filled icons.
+
+---
+
+## Domain Affinity Matrix
+
+| Vertical | Primary Library | Secondary Library | Default Weight | Emphasis Weight | Rationale |
+|----------|----------------|-------------------|----------------|-----------------|-----------|
+| Fintech | Phosphor Icons | Lucide | regular | bold | Weight variation for data-dense dashboards; duotone for hierarchy |
+| Health | Material Symbols (Rounded) | Phosphor Icons | regular (wght:400) | filled (FILL:1) | Broadest medical icon coverage; Rounded style is warm, not clinical |
+| SaaS | Lucide | Phosphor Icons | default (2px stroke) | default (2px stroke) | Feather-derived SaaS standard; single style means no weight variation |
+| E-commerce | Material Symbols (Rounded) | Tabler Icons | regular (wght:400) | filled (FILL:1) | Action-oriented icons with fill for CTAs; Tabler for niche categories |
+
+**Key rules:**
+- One library per project -- no mixing libraries in the same output
+- Secondary library = personality override pool, NOT a gap fallback
+- Weight is a system-level decision applied consistently across all composed screens
+
+---
+
+## Selection Algorithm
+
+Deterministic lookup: vertical + brand personality seed produces library + weight with zero ambiguity. Mirrors how Color and Typography Decision Algorithms work in `generate-system.md`.
+
+**Inputs:**
+- `vertical` (string): fintech | health | saas | ecommerce
+- `personality` (integer, 1-10): from Differentiation Seed in DESIGN-BRIEF.md (see `core/references/design-inputs.md`)
+- `formality` (integer, 1-10): from Differentiation Seed in DESIGN-BRIEF.md
+- `user_library_override` (string, optional): explicit library choice from DESIGN-BRIEF.md
+
+**Algorithm:**
+
+```
+STEP 1 -- User override check
+  IF user_library_override IS SET in DESIGN-BRIEF.md:
+    selected_library = user_library_override
+    GOTO STEP 2 (still apply weight rules)
+  ELSE:
+    selected_library = AFFINITY_MATRIX[vertical].primary
+
+STEP 2 -- Base weight assignment
+  default_weight = AFFINITY_MATRIX[vertical].default_weight
+  emphasis_weight = AFFINITY_MATRIX[vertical].emphasis_weight
+
+STEP 3 -- Personality-based weight selection
+  IF selected_library supports weights (Phosphor Icons OR Material Symbols):
+    IF personality >= 7 (bold/rebellious):
+      Phosphor:          default_weight = bold,     emphasis_weight = fill
+      Material Symbols:  default_weight = wght:600, emphasis_weight = FILL:1,wght:700
+    ELIF personality <= 3 (corporate/conservative):
+      Phosphor:          default_weight = light,    emphasis_weight = regular
+      Material Symbols:  default_weight = wght:300, emphasis_weight = wght:400
+    ELSE (personality 4-6, balanced):
+      Phosphor:          default_weight = regular,  emphasis_weight = bold
+      Material Symbols:  default_weight = wght:400, emphasis_weight = FILL:1
+  ELSE (Lucide OR Tabler -- no weight variants):
+    default_weight = default
+    emphasis_weight = default
+
+STEP 4 -- Extreme personality library switch
+  IF personality >= 8 AND NOT user_library_override:
+    selected_library = AFFINITY_MATRIX[vertical].secondary
+    Recalculate weights for new library (repeat STEP 3 logic)
+  IF personality <= 2 AND NOT user_library_override:
+    selected_library = AFFINITY_MATRIX[vertical].secondary
+    Recalculate weights for new library (repeat STEP 3 logic)
+
+STEP 5 -- Material Symbols style family selection
+  IF selected_library = Material Symbols:
+    IF formality <= 4 (casual/approachable):
+      style_family = Rounded
+    ELIF formality >= 7 (formal/institutional):
+      style_family = Sharp
+    ELSE (formality 5-6):
+      style_family = Outlined
+
+STEP 6 -- Emit output
+  OUTPUT: {
+    library: selected_library,
+    default_weight: default_weight,
+    emphasis_weight: emphasis_weight,
+    style_family: style_family (Material Symbols only, omit otherwise),
+    cdn_url: look up in Curated Libraries section above,
+    usage_syntax: look up in Curated Libraries section above
+  }
+```
+
+**Boundary values (inclusive):**
+- `personality >= 7` triggers bold weights (7, 8, 9, 10 are all bold)
+- `personality <= 3` triggers light weights (1, 2, 3 are all light)
+- `personality >= 8` triggers library switch (8, 9, 10 switch to secondary)
+- `personality <= 2` triggers library switch (1, 2 switch to secondary)
+- `formality <= 4` selects Rounded (1, 2, 3, 4)
+- `formality >= 7` selects Sharp (7, 8, 9, 10)
+- Personality 4-6 are balanced (default weights, primary library)
+- Formality 5-6 selects Outlined
+
+---
+
+## Icon Color
+
+Icons use `currentColor` inheritance. No `--icon-color-*` tokens are needed.
+
+Apply color via `color: var(--text-secondary)` on the parent or icon element. Icons inherit via CSS `currentColor`. For semantic colors, use existing tokens: `var(--color-success)`, `var(--color-error)`, `var(--color-warning)`.
+
+```css
+/* Example: icon inherits color from parent */
+.nav-item {
+  color: var(--text-secondary);
+}
+.nav-item.active {
+  color: var(--color-primary-500);
+}
+/* The icon inside inherits automatically via currentColor */
+```
+
+---
+
+## Icon Name Conventions
+
+Common UI concepts mapped across all four libraries. Use these verified names to prevent hallucination.
+
+| Concept | Phosphor | Lucide | Material Symbols | Tabler |
+|---------|----------|--------|-----------------|--------|
+| Home | ph-house | house | home | ti-home |
+| Search | ph-magnifying-glass | search | search | ti-search |
+| Settings | ph-gear | settings | settings | ti-settings |
+| User/Profile | ph-user | user | person | ti-user |
+| Cart | ph-shopping-cart | shopping-cart | shopping_cart | ti-shopping-cart |
+| Heart/Favorite | ph-heart | heart | favorite | ti-heart |
+| Arrow Right | ph-arrow-right | arrow-right | arrow_forward | ti-arrow-right |
+| Chart/Analytics | ph-chart-line | bar-chart-2 | bar_chart | ti-chart-line |
+| Notification | ph-bell | bell | notifications | ti-bell |
+| Close | ph-x | x | close | ti-x |
+| Check/Done | ph-check | check | check | ti-check |
+| Mail | ph-envelope | mail | mail | ti-mail |
+| Calendar | ph-calendar | calendar | calendar_month | ti-calendar |
+| Lock/Security | ph-lock | lock | lock | ti-lock |
+| Credit Card | ph-credit-card | credit-card | credit_card | ti-credit-card |
+
+**Note:** Material Symbols uses underscores (`shopping_cart`, `arrow_forward`, `calendar_month`), not hyphens. Phosphor prefixes with `ph-`. Tabler prefixes with `ti-`. Lucide uses bare kebab-case names.
+
+**This table covers common UI concepts only.** Curated per-vertical icon name vocabularies (e.g., fintech-specific icons like "bank", "transfer", "wallet") are defined in Phase 10.
+
+---
+
+## CDN Reference
+
+Copy-paste-ready HTML snippets for each library.
+
+### Phosphor Icons
+
+```html
+<!-- Regular weight (recommended starting point) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/regular/style.css" />
+
+<!-- Additional weights (load only what the design needs) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/thin/style.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/light/style.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/bold/style.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/fill/style.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/duotone/style.css" />
+
+<!-- Usage -->
+<i class="ph ph-house"></i>           <!-- Regular -->
+<i class="ph-bold ph-house"></i>      <!-- Bold -->
+<i class="ph-light ph-house"></i>     <!-- Light -->
+<i class="ph-thin ph-house"></i>      <!-- Thin -->
+<i class="ph-fill ph-house"></i>      <!-- Fill -->
+<i class="ph-duotone ph-house"></i>   <!-- Duotone -->
+```
+
+### Lucide
+
+```html
+<!-- JS mode (recommended -- renders only icons present in DOM) -->
+<script src="https://unpkg.com/lucide@0.576.0"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', () => {
+    lucide.createIcons();
+  });
+</script>
+
+<!-- Usage -->
+<i data-lucide="house"></i>
+<i data-lucide="settings"></i>
+<i data-lucide="search"></i>
+```
+
+**Lucide requires JS initialization.** Unlike Phosphor, Material Symbols, and Tabler, the icons will not render without calling `lucide.createIcons()`. This is the only library in the curated set with this requirement.
+
+### Material Symbols
+
+```html
+<!-- Load one style family -->
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet" />
+<!-- OR Rounded -->
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded" rel="stylesheet" />
+<!-- OR Sharp -->
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp" rel="stylesheet" />
+
+<!-- Usage -->
+<span class="material-symbols-outlined">home</span>
+<span class="material-symbols-rounded">settings</span>
+<span class="material-symbols-sharp">search</span>
+```
+
+**Required CSS setup for Material Symbols:**
+
+```css
+/* CRITICAL: Always set explicit font-size AND matching opsz to prevent oversized rendering */
+.material-symbols-outlined,
+.material-symbols-rounded,
+.material-symbols-sharp {
+  font-size: var(--icon-lg);  /* Default 24px */
+  font-variation-settings:
+    'FILL' 0,
+    'wght' 400,
+    'GRAD' 0,
+    'opsz' 24;
+}
+
+/* Filled variant (emphasis weight) */
+.material-symbols-outlined.filled,
+.material-symbols-rounded.filled,
+.material-symbols-sharp.filled {
+  font-variation-settings:
+    'FILL' 1,
+    'wght' 400,
+    'GRAD' 0,
+    'opsz' 24;
+}
+```
+
+### Tabler Icons
+
+```html
+<!-- Outline only -- filled webfont has known bug (GitHub #1452) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tabler/icons-webfont@3.36.1/dist/tabler-icons.min.css" />
+
+<!-- Usage -->
+<i class="ti ti-home"></i>
+<i class="ti ti-settings"></i>
+<i class="ti ti-search"></i>
+```
+
+---
+
+*Icon Library Reference for Motif Design System Pipeline*
+*Created: 2026-03-04*

package/core/references/verticals/ecommerce.md

@@ -240,6 +240,52 @@ Product browsing needs breathing room for imagery. Cart and checkout need densit
 | shadow-lg | 0 12px 24px -4px rgba(0,0,0,0.10), 0 4px 8px -4px rgba(0,0,0,0.05) | Modals, cart drawer, mega-menu |
 | shadow-xl | 0 20px 40px -8px rgba(0,0,0,0.12), 0 8px 16px -8px rgba(0,0,0,0.06) | Lightbox overlay, elevated popovers |
 
+<!-- Verified against Material Symbols via GitHub google/material-design-icons/symbols/web/ -->
+
+## Icon Vocabulary
+
+Primary library: Material Symbols Rounded (from icon-libraries.md domain affinity matrix)
+
+Note: Material Symbols uses underscores, not hyphens. Double-check every name.
+
+### Navigation
+| Semantic Role | Material Symbols | Phosphor | Lucide | Tabler |
+|---------------|-----------------|----------|--------|--------|
+| home | home | ph-house | house | ti-home |
+| search | search | ph-magnifying-glass | search | ti-search |
+| cart | shopping_cart | ph-shopping-cart | shopping-cart | ti-shopping-cart |
+| profile | person | ph-user | user | ti-user |
+| menu | menu | ph-list | menu | ti-menu-2 |
+
+### Commerce
+| Semantic Role | Material Symbols | Phosphor | Lucide | Tabler |
+|---------------|-----------------|----------|--------|--------|
+| storefront | storefront | ph-storefront | store | ti-building-store |
+| favorite | favorite | ph-heart | heart | ti-heart |
+| star-rating | star | ph-star | star | ti-star |
+| shipping | local_shipping | ph-truck | truck | ti-truck |
+| payments | payments | ph-credit-card | credit-card | ti-credit-card |
+| discount | sell | ph-tag | tag | ti-tag |
+| package | package_2 | ph-package | package | ti-package |
+| receipt | receipt_long | ph-receipt | receipt | ti-receipt |
+
+### Status & Feedback
+| Semantic Role | Material Symbols | Phosphor | Lucide | Tabler |
+|---------------|-----------------|----------|--------|--------|
+| success | check_circle | ph-check-circle | check-circle | ti-circle-check |
+| error | cancel | ph-x-circle | x-circle | ti-circle-x |
+| warning | warning | ph-warning | alert-triangle | ti-alert-triangle |
+| inventory-low | inventory | ph-warehouse | warehouse | ti-building-warehouse |
+
+### Actions
+| Semantic Role | Material Symbols | Phosphor | Lucide | Tabler |
+|---------------|-----------------|----------|--------|--------|
+| add-to-cart | add_shopping_cart | ph-shopping-cart-simple | shopping-cart | ti-shopping-cart-plus |
+| remove | close | ph-x | x | ti-x |
+| share | share | ph-share-network | share-2 | ti-share |
+| filter | filter_list | ph-funnel | filter | ti-filter |
+| sort | sort | ph-arrows-down-up | arrow-up-down | ti-arrows-sort |
+
 ## E-commerce-Specific Additions
 - **Product image gallery:** Thumbnail strip below main image (desktop), swipe carousel with dot indicators (mobile), pinch-to-zoom, fullscreen lightbox with arrow navigation
 - **Size/variant selectors:** Chip group layout, selected chip gets primary border + fill, out-of-stock chips show diagonal strike-through and reduced opacity, size guide link adjacent

package/core/references/verticals/fintech.md

@@ -120,7 +120,7 @@ Users need enough data to make decisions without excessive scrolling, but not so
 <component name="TransactionRow" category="data-display">
   <description>Single transaction in a list. Most-viewed component in any fintech app.</description>
   <structure>
-    Row: [MerchantIcon 40×40] [Description + Subtitle stack] [Amount right-aligned]
+    Row: [icon: merchant category --icon-lg in 40x40 --radius-full container] [Description + Subtitle stack] [Amount right-aligned]
     Description: --font-body --text-sm --weight-medium --text-primary
     Subtitle: --font-body --text-xs --text-secondary (date, category, reference)
     Amount: --font-mono --text-sm --weight-semibold, right-aligned
@@ -216,6 +216,51 @@ Users need enough data to make decisions without excessive scrolling, but not so
 | shadow-md | 0 4px 6px -1px rgba(0,0,0,0.07), 0 2px 4px -2px rgba(0,0,0,0.05) | Elevated cards, dropdowns |
 | shadow-lg | 0 10px 15px -3px rgba(0,0,0,0.08), 0 4px 6px -4px rgba(0,0,0,0.04) | Modals, popovers |
 
+<!-- Verified against Phosphor Icons @phosphor-icons/web@2.1.2 via GitHub phosphor-icons/core/assets/regular/ -->
+
+## Icon Vocabulary
+
+Primary library: Phosphor Icons (from icon-libraries.md domain affinity matrix)
+
+### Navigation
+| Semantic Role | Phosphor | Lucide | Material Symbols | Tabler |
+|---------------|----------|--------|-----------------|--------|
+| home | ph-house | house | home | ti-home |
+| search | ph-magnifying-glass | search | search | ti-search |
+| settings | ph-gear | settings | settings | ti-settings |
+| profile | ph-user | user | person | ti-user |
+| notifications | ph-bell | bell | notifications | ti-bell |
+
+### Finance
+| Semantic Role | Phosphor | Lucide | Material Symbols | Tabler |
+|---------------|----------|--------|-----------------|--------|
+| bank | ph-bank | landmark | account_balance | ti-building-bank |
+| wallet | ph-wallet | wallet | account_balance_wallet | ti-wallet |
+| credit-card | ph-credit-card | credit-card | credit_card | ti-credit-card |
+| money | ph-currency-dollar | dollar-sign | payments | ti-currency-dollar |
+| transfer | ph-arrows-left-right | arrow-left-right | swap_horiz | ti-transfer |
+| chart | ph-chart-line-up | trending-up | trending_up | ti-trending-up |
+| receipt | ph-receipt | receipt | receipt_long | ti-receipt |
+| coins | ph-coins | coins | toll | ti-coins |
+
+### Status & Feedback
+| Semantic Role | Phosphor | Lucide | Material Symbols | Tabler |
+|---------------|----------|--------|-----------------|--------|
+| success | ph-check-circle | check-circle | check_circle | ti-circle-check |
+| error | ph-x-circle | x-circle | cancel | ti-circle-x |
+| warning | ph-warning | alert-triangle | warning | ti-alert-triangle |
+| pending | ph-clock | clock | schedule | ti-clock |
+
+### Actions
+| Semantic Role | Phosphor | Lucide | Material Symbols | Tabler |
+|---------------|----------|--------|-----------------|--------|
+| send | ph-paper-plane-tilt | send | send | ti-send |
+| scan-qr | ph-qr-code | qr-code | qr_code_scanner | ti-qr-code |
+| security | ph-shield-check | shield-check | verified_user | ti-shield-check |
+| biometric | ph-fingerprint | fingerprint | fingerprint | ti-fingerprint |
+| copy | ph-copy | copy | content_copy | ti-copy |
+| close | ph-x | x | close | ti-x |
+
 ## Crypto-Specific Additions
 - Always show BOTH crypto amount AND fiat equivalent
 - Network/chain indicator on all addresses (tiny chip: "TRC-20", "ERC-20", "SOL")