Integrate Modus Icons

Integrate Modus Icons

Help with correct Modus icon usage patterns including naming conventions, sizing, and accessibility.

When to Use

Use this skill when:

• Adding icons to components or buttons
• Choosing the right icon name
• Sizing icons correctly
• Ensuring proper accessibility
• Integrating icons with Modus components

Icon Naming Convention

CRITICAL: Modus icons use UNDERSCORES (_), not hyphens (-)

Correct Icon Names

// ✅ CORRECT: Use underscores (SolidJS uses class)
<i class="modus-icons">save_disk</i>
<i class="modus-icons">arrow_left</i>
<i class="modus-icons">add_circle</i>
<i class="modus-icons">user_permissions</i>

// ❌ WRONG: Don't use hyphens
<i class="modus-icons">save-disk</i>
<i class="modus-icons">arrow-left</i>

Usage Patterns

Pattern 1: Using ModusIcon Component

import ModusIcon from "./components/ModusIcon";

// Informational icon (announced by screen reader)
<ModusIcon
  name="user_add"
  size="lg"
  decorative={false}
  ariaLabel="Add user"
/>

// Decorative icon (not announced)
<ModusIcon
  name="chevron_right"
  size="md"
  decorative={true}
/>

Reference: src/components/ModusIcon.tsx

Pattern 2: Using Bare <i> Element

// Decorative icon
<i class="modus-icons text-lg" aria-hidden="true">
  user_add
</i>

// Informational icon
<i
  class="modus-icons text-md"
  role="img"
  aria-label="Settings"
>
  settings
</i>

Pattern 3: Icons in Buttons

import ModusButton from "./components/ModusButton";

// Icon with text (left position)
<ModusButton
  icon="save_disk"
  iconPosition="left"
>
  Save File
</ModusButton>

// Icon with text (right position)
<ModusButton
  icon="download"
  iconPosition="right"
>
  Download
</ModusButton>

// Icon only (requires aria-label)
<ModusButton
  icon="settings"
  iconPosition="only"
  ariaLabel="Open settings"
/>

Reference: src/components/ModusButton.tsx for icon rendering logic

Icon Sizing

Tailwind Text Classes

Use Tailwind text utilities for sizing:

// Small icon
<i class="modus-icons text-sm">info</i>

// Base icon (Modus default 14px)
<i class="modus-icons text-base">warning</i>

// Large icon (16px)
<i class="modus-icons text-lg">error</i>

// Extra large icon (18px)
<i class="modus-icons text-xl">success</i>

Modus Font Size Scale

Icon Colors

Use design system colors:

// Primary color
<i class="modus-icons text-primary">info</i>

// Success color
<i class="modus-icons text-success">check_circle</i>

// Warning color
<i class="modus-icons text-warning">warning</i>

// Error color
<i class="modus-icons text-error">error</i>

// Muted text
<i class="modus-icons text-muted-foreground">help</i>

Accessibility

Decorative Icons

For purely decorative icons, use aria-hidden="true":

<button>
  <i class="modus-icons mr-2" aria-hidden="true">save_disk</i>
  Save Document
</button>

Informational Icons

For icons that convey meaning, provide proper labels:

// Using role="img" and aria-label
<i class="modus-icons" role="img" aria-label="Warning">
  warning
</i>

// Using aria-label on parent element
<button aria-label="Delete item">
  <i class="modus-icons" aria-hidden="true">delete</i>
</button>

Icon-Only Buttons

Always provide accessible labels:

<ModusButton
  icon="settings"
  iconPosition="only"
  ariaLabel="Open settings menu"
/>

Common Icon Names

Navigation & UI

• arrow_left, arrow_right, arrow_up, arrow_down
• chevron_left, chevron_right
• menu, close, home, settings, search

Actions & Operations

• add, remove, edit_combination, delete
• save_disk, download, upload, copy_content

Status & Feedback

• check, check_circle, error, warning, alert, info, help

Files & Documents

• file, file_upload, file_download
• folder_open, folder_closed, document, image, video

User & Account

• person, people_group, user_account, user_add
• key, lock, lock_open

Validating Icon Names

Check icon names against the complete list in:

• .cursor/rules/modus-icon-names.mdc - Complete list of 700+ valid icon names

Common mistakes:

• Using hyphens instead of underscores
• Wrong capitalization (all lowercase)
• Typos in icon names

SolidJS Note

In SolidJS, use class instead of className for icon elements.

Related Files

• src/components/ModusIcon.tsx - Icon component wrapper
• src/components/ModusButton.tsx - Button icon integration
• .cursor/rules/modus-icon-names.mdc - Complete icon name list