Icons

Icons

Standard uses Phosphor Icons for its visual language. Icons provide visual context, improve scannability, and reinforce meaning throughout the interface.

Basic Usage

Include icons using the Phosphor icon font classes.

<i class="ph ph-house"></i>
<i class="ph ph-gear"></i>
<i class="ph ph-user"></i>

Icon Styles

Phosphor icons come in multiple styles: regular, bold, fill, and duotone.

Regular
Bold
Fill
Duotone
<i class="ph ph-heart"></i>         <!-- Regular -->
<i class="ph-bold ph-heart"></i>    <!-- Bold -->
<i class="ph-fill ph-heart"></i>    <!-- Fill -->
<i class="ph-duotone ph-heart"></i> <!-- Duotone -->

Icon Sizes

Control icon size using font-size or predefined classes.

<i class="ph ph-star Icon Icon--xs"></i>    <!-- 12px -->
<i class="ph ph-star Icon Icon--small"></i> <!-- 16px -->
<i class="ph ph-star Icon"></i>             <!-- 20px -->
<i class="ph ph-star Icon Icon--large"></i> <!-- 24px -->
<i class="ph ph-star Icon Icon--xl"></i>    <!-- 32px -->

<i class="ph ph-rocket" style="font-size: 2rem;"></i>

Icon Colors

Icons inherit the current text color. Override with CSS.

<i class="ph ph-check-circle" style="color: oklch(55% 0.15 150);"></i>
<i class="ph ph-warning" style="color: oklch(70% 0.15 80);"></i>

<i class="ph ph-check-circle Icon Icon--success"></i>
<i class="ph ph-warning Icon Icon--warning"></i>

Icons in Buttons

Common pattern for enhanced button clarity.

<button class="Button Button--primary">
    <i class="ph ph-plus Button-icon"></i>
    Create New
</button>

<button class="Button Button--primary">
    Continue
    <i class="ph ph-arrow-right Button-icon Button-icon--trailing"></i>
</button>

<button class="Button Button--icon" aria-label="Search">
    <i class="ph ph-magnifying-glass"></i>
</button>

Icons in Inputs

Add context to form inputs.

<div class="Input-wrapper">
    <i class="ph ph-magnifying-glass Input-icon"></i>
    <input type="text" class="Input Input--withIcon" placeholder="Search...">
</div>

Icons in Lists

Enhance list items with icons.

  • Feature included in plan
  • Unlimited storage space
  • Priority customer support
  • Advanced analytics 
<li style="display: flex; align-items: center; gap: var(--space-3);">
    <i class="ph ph-check-circle Icon Icon--success"></i>
    <span>Feature included</span>
</li>

Icons in Alerts

Add visual weight to alert messages.

This is an informational message.
Changes saved successfully.
Please review your settings.
An error occurred. Please try again.
<div class="Alert Alert--success">
    <i class="ph ph-check-circle Alert-icon"></i>
    <div>Changes saved successfully.</div>
</div>

Icon Backgrounds

Icons in circular or square backgrounds.

<span class="IconBg IconBg--primary">
    <i class="ph ph-gear"></i>
</span>

<span class="IconBg IconBg--small IconBg--primary">...</span>
<span class="IconBg IconBg--large IconBg--primary">...</span>

Animated Icons

Icons with loading or state animations.

<i class="ph ph-spinner Icon Icon--spin"></i>

<i class="ph ph-bell Icon Icon--pulse"></i>

Common Icons Reference

house
magnifying-glass
gear
bell
user
sign-out

Actions

plus
pencil
trash
download
upload
share

Status & Feedback

check
x
warning
info
question
spinner

Arrows & Chevrons

arrow-left
arrow-right
caret-down
caret-right
arrow-square-out
arrows-clockwise

Media & Files

image
file
folder
video
link
paperclip

Communication

envelope
chat
phone
paper-plane-tilt
at
users

Common Patterns

Empty State

No files yet

Upload your first file to get started.

Feature List

Pro Plan Features

  • Unlimited projects
  • Advanced analytics
  • Priority support
  • Custom integrations

Customization

Override icon styles using CSS custom properties:

/* Custom icon color scheme */
.Icon--brand {
  color: oklch(55% 0.2 280);
}

/* Custom icon background */
.IconBg--brand {
  background-color: oklch(55% 0.2 280 / 0.15);
  color: oklch(45% 0.2 280);
}

/* Square icon backgrounds */
.IconBg--square {
  border-radius: var(--r-s);
}

/* Custom animation speed */
.Icon--spin-slow {
  animation: spin 2s linear infinite;
}

/* Custom size scale */
.Icon--xxl {
  font-size: 3rem;
}

API Reference

Classes

ClassDescription
.IconBase icon styling
.Icon--xsExtra small (12px)
.Icon--smallSmall (16px)
.Icon--largeLarge (24px)
.Icon--xlExtra large (32px)
.Icon--successSuccess/green color
.Icon--warningWarning/yellow color
.Icon--errorError/red color
.Icon--infoInfo/primary color
.Icon--spinSpinning animation
.Icon--pulsePulsing animation
.IconBgIcon with circular background
.IconBg--smallSmall background (28px)
.IconBg--largeLarge background (56px)
.IconBg--primaryPrimary color background
.IconBg--successSuccess color background
.IconBg--warningWarning color background
.IconBg--errorError color background

Phosphor Icon Styles

Class PrefixDescription
phRegular weight
ph-boldBold weight
ph-fillFilled style
ph-duotoneTwo-tone style

Attributes

AttributeDescription
aria-hidden="true"For decorative icons (text provides meaning)
aria-labelFor meaningful icons without visible text
role="img"When icon conveys meaning

CSS Custom Properties

PropertyDefaultDescription
--text-secondary—Default icon color
--bg-secondary—IconBg background
--accent-primary—Info color

CSS Reference

/* Base Icon */
.Icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  font-size: 1.25rem;
  line-height: 1;
}

/* Sizes */
.Icon--xs { font-size: 0.75rem; }
.Icon--small { font-size: 1rem; }
.Icon--large { font-size: 1.5rem; }
.Icon--xl { font-size: 2rem; }

/* Colors */
.Icon--success { color: oklch(55% 0.15 150); }
.Icon--warning { color: oklch(70% 0.15 80); }
.Icon--error { color: oklch(55% 0.2 25); }
.Icon--info { color: var(--accent); }

/* Animations */
.Icon--spin {
  animation: spin 1s linear infinite;
}

.Icon--pulse {
  animation: pulse 2s ease-in-out infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}

/* Icon Background */
.IconBg {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background-color: var(--bg-s);
  color: var(--fg-3);
}

.IconBg--small {
  width: 28px;
  height: 28px;
  font-size: 0.875rem;
}

.IconBg--large {
  width: 56px;
  height: 56px;
  font-size: 1.5rem;
}

.IconBg--primary {
  background-color: oklch(60% 0.15 250 / 0.15);
  color: oklch(50% 0.15 250);
}

.IconBg--success {
  background-color: oklch(65% 0.15 150 / 0.15);
  color: oklch(45% 0.15 150);
}

.IconBg--warning {
  background-color: oklch(75% 0.15 80 / 0.15);
  color: oklch(50% 0.15 80);
}

.IconBg--error {
  background-color: oklch(55% 0.2 25 / 0.15);
  color: oklch(50% 0.2 25);
}

/* Screen reader only */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Accessibility

Icons require attention to ensure they’re accessible:

Decorative Icons

<!-- Icon is purely decorative, text provides meaning -->
<button class="Button Button--primary">
    <i class="ph ph-plus" aria-hidden="true"></i>
    Add Item
</button>

Meaningful Icons

<!-- Icon-only button needs aria-label -->
<button class="Button Button--icon" aria-label="Search">
    <i class="ph ph-magnifying-glass"></i>
</button>

<!-- Or use visually-hidden text -->
<button class="Button Button--icon">
    <i class="ph ph-magnifying-glass"></i>
    <span class="sr-only">Search</span>
</button>

Status Icons

<!-- Provide text alternative for status -->
<span>
    <i class="ph ph-check-circle Icon Icon--success" aria-hidden="true"></i>
    <span>Complete</span>
</span>

Weight Conventions

Standard uses a deliberate weight hierarchy across the interface. Use the right weight for the right context.

Context Weight Rationale
Navigation chrome (pill nav, section links) ph-bold Heavier weight anchors the nav bar visually
UI controls (toolbar buttons, search, copy) ph (regular) Lighter weight recedes behind content
Content icons (alerts, lists, form hints) ph (regular) Matches body text optical weight
Filled states (active stars, favorite hearts) ph-fill Solid fill communicates “selected” or “active”
Decorative showcase (icon grid, style demos) Any Documentation context; all weights available 
<!-- Navigation: bold -->
<i class="ph-bold ph-house"></i>

<!-- UI control: regular -->
<i class="ph ph-copy"></i>

<!-- Filled state: fill -->
<i class="ph-fill ph-star"></i>

<!-- Unfilled state: regular -->
<i class="ph ph-star"></i>

Rule of thumb: Use ph-bold only for persistent navigation. Everything else uses ph (regular) or ph-fill for active/selected states.

Best Practices

Do

  • ✓ Use consistent sizing — Match icon size to text size
  • ✓ Pair icons with text — When possible, provide labels
  • ✓ Use recognizable icons — Stick to common conventions
  • ✓ Provide aria-labels — Required for icon-only buttons
  • ✓ Follow weight conventions — Bold for nav, regular for content, fill for active states
  • ✓ Use semantic color classes — .Icon--success for positive states

Don’t

  • ✗ Overuse icons — Not everything needs an icon
  • ✗ Create visual noise — Too many icons reduce clarity
  • ✗ Use ambiguous icons — A hamburger menu isn’t a hamburger
  • ✗ Forget color contrast — Icons need sufficient contrast
  • ✗ Mix icon libraries — Stick to Phosphor for consistency
  • ✗ Mix weights arbitrarily — Don’t use ph-bold for content icons or ph for nav
  • ✗ Use icons without accessible names — Icon-only elements need aria-label