Icons Studio

Manage your icon library and define semantic icon roles for consistent usage across your design system.

Getting started

Icons Studio opens in edit mode: a focused workspace without the sidebar. Access it from the sidebar menu under Icons.

Layout

Panel	Purpose
Left	Configuration: icon sources, roles summary, size tokens, weight
Right	Preview and management: browse icons, manage roles, export code
Bottom	Status, export, and save

Icon sources

Import icons from popular libraries:

Library	Icons	Weights
Phosphor Icons	1,248	6 (thin, light, regular, bold, fill, duotone)
Lucide Icons	1,400+	Customizable stroke
Heroicons	300+	Outline & solid
Custom SVG	Your own	Varies

Adding an icon library

1. Click Import existing dropdown
2. Select a library (e.g., Phosphor Icons)
3. Library loads instantly with full icon manifest
4. Icons appear in the Browse tab

You can import multiple libraries: useful when migrating or comparing options.

Icon roles

The core feature: map semantic action names to specific icons. This ensures:

• consistency across your codebase
• AI tools use the correct icons automatically
• clear vocabulary for your team

Example roles

Role	Icon	Description
delete	Trash	Permanently remove. Cannot be undone.
remove	MinusCircle	Remove from list. Can be re-added.
cancel	X	Stop operation, close dialog.
save	FloppyDisk	Save changes.
edit	PencilSimple	Edit content.

Categories

Roles are organized by category:

• Destructive: delete, remove, cancel, discard
• Save: save, submit, confirm
• Navigation: back, forward, menu, close
• Edit: edit, copy, paste, duplicate
• User: profile, settings, logout
• Status: success, error, warning, info

Managing roles

1. Click Manage roles in the left panel (or select Icon Roles tab)
2. Select a category from the sidebar
3. View existing roles as cards
4. Click + Add Role to create a new mapping
5. Edit role details: name, icon, description, severity

Severity levels

Each role has a severity that affects icon color:

Severity	Color	Use for
Permanent	Red	Destructive, irreversible actions
Reversible	Amber	Actions that can be undone
Neutral	Default	Standard actions

Size tokens

Define standard icon sizes:

Token	Default	Use case
xs	12px	Inline indicators, badges
sm	16px	Buttons, form inputs
md	20px	Default size
lg	24px	Headers, emphasis
xl	32px	Hero sections, empty states

Edit sizes in the left panel. Values export as CSS custom properties.

Default weight

Set the default weight for all icons:

Weight	Style
Thin	Lightest stroke
Light	Subtle
Regular	Balanced (recommended)
Bold	Emphasis
Fill	Solid shapes
Duotone	Two-tone effect

Individual roles can override the default weight.

Preview tabs

Tab	Purpose
Browse	Search and browse all icons in your library
Icon Roles	Manage semantic mappings by category
In Context	See icons in realistic UI patterns
Code	Export configurations

Exporting

Download icon configurations:

• CSS Variables: size tokens as custom properties
• JSON Tokens: full configuration in token format

Exports are available from the Export dropdown in the bottom toolbar.

AI integration

Icon roles automatically sync to your MCP server. AI coding tools (Claude Code, Cursor, Windsurf) will:

• use delete role → Trash icon
• use save role → FloppyDisk icon
• apply correct size tokens
• respect weight settings

No manual configuration needed in AI tools. See Agent resources for how this surfaces.

Tips

1. Start with one library: Phosphor is recommended for its 6 weights
2. Define roles early: establish vocabulary before building UI
3. Use categories: group related actions for easier management
4. Test in context: use "In Context" tab to see icons in real UI
5. Keep it simple: 20-30 roles cover most applications
6. Document severity: help your team understand when to use destructive styling