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
<i className="modus-icons">save_disk</i>
<i className="modus-icons">arrow_left</i>
<i className="modus-icons">add_circle</i>
<i className="modus-icons">user_permissions</i>

// ❌ WRONG: Don't use hyphens
<i className="modus-icons">save-disk</i>
<i className="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 className="modus-icons text-lg" aria-hidden="true">
  user_add
</i>

// Informational icon
<i
  className="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:149-206 for icon rendering logic

Icon Sizing

Tailwind Text Classes

Use Tailwind text utilities for sizing:

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

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

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

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

Modus Font Size Scale

Button Icon Sizing

Icons in buttons automatically scale based on button size:

// Icons scale with button size
<ModusButton size="xs" icon="star" iconPosition="left">Extra Small</ModusButton>
<ModusButton size="sm" icon="star" iconPosition="left">Small</ModusButton>
<ModusButton size="md" icon="star" iconPosition="left">Medium</ModusButton>
<ModusButton size="lg" icon="star" iconPosition="left">Large</ModusButton>

// Icon-only buttons use larger icons
<ModusButton size="md" icon="settings" iconPosition="only" ariaLabel="Settings" />

Automatic sizing rules:

• Icons with text: Scale with button size (text-xs for xs, text-lg for md)
• Icon-only buttons: Get larger icons (text-sm for xs, text-xl for md)

Reference: src/components/ModusButton.tsx:98-134

Icon Colors

Use design system colors:

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

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

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

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

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

Accessibility

Decorative Icons

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

<button>
  <i className="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 className="modus-icons" role="img" aria-label="Warning">
  warning
</i>

// Using aria-label on parent element
<button aria-label="Delete item">
  <i className="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

Testing Icons

Visual Verification

Icons should display as glyphs, not text. If you see text like "save_disk" instead of an icon:

1. Check font CSS is loaded in index.html
2. Verify icon name uses underscores
3. Confirm modus-icons class is applied
4. Check network tab for font file download

Browser DevTools Check

// Check if font is loaded
const testElement = document.createElement('span');
testElement.className = 'modus-icons';
document.body.appendChild(testElement);
const fontFamily = window.getComputedStyle(testElement).fontFamily;
console.log('Font loaded:', fontFamily.includes('modus-icons'));
document.body.removeChild(testElement);

Common Mistakes

1. Wrong naming: Using hyphens instead of underscores
2. Wrong sizing: Using pixel values instead of Tailwind classes
3. Missing accessibility: Not providing aria-label for informational icons
4. Wrong icon name: Not checking against valid icon list
5. Font not loaded: Missing CSS import for Modus icons

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
• .cursor/rules/modus-icons-react.mdc - Detailed icon documentation