Iconography — VirtualLife Design System

Icon System

VirtualLife products use Lucide (@lucide/svelte) as its exclusive icon library. Lucide is an open-source fork of Feather Icons with broader coverage, consistent geometry, and an active community.

Property	Value
Library	`@lucide/svelte` (Svelte-native tree-shakeable components)
Viewbox	24 × 24
Default stroke-width	2
Default size	24px (renders to 16px inline with text at base font)
Fill	`none` — outlined style always (never filled)
License	ISC (open source, free for commercial use)

Import Pattern

<!-- Tree-shaking: import only what you use -->
import { Sparkles, Settings, Download } from '@lucide/svelte';

<!-- Usage -->
<Sparkles size={16} strokeWidth={2} />
<Settings class="size-4" />
<Download size={20} class="text-muted-foreground" />

Never mix icon libraries. If Lucide doesn't have an icon you need, request it from the Lucide project or create a custom SVG following their geometry constraints (24×24 viewbox, 2px stroke, rounded joins, 2px minimum padding from edges).

Size Scale

Icons scale across five levels depending on context. Smaller for dense UI, larger for focal points and onboarding.

✦

2xs 10px

✦

xs 14px

✦

sm 16px

✦

md 20px

✦

lg 24px

✦

xl 32px

✦

2xl 64px

Size	Pixels	Tailwind	Usage
2xs	10px	size-2.5	Badge icons, status dots
xs	14px	size-3.5	Inline with small text (text-xs), compact buttons
sm	16px	size-4	Default inline icon, form fields, toolbar buttons
md	20px	size-5	Sidebar navigation, standalone buttons, card headers
lg	24px	size-6	Primary action buttons, page section icons
xl	32px	size-8	Onboarding steps, empty states, startup screen
2xl	64px	size-16	Hero icons, media overlay play buttons, app bar mark

Stroke Width

Stroke width affects visual weight. The default is 2, but we adjust for specific contexts.

1

strokeWidth: 1

1.5

strokeWidth: 1.5

2

strokeWidth: 2 ★

2.5

strokeWidth: 2.5

Stroke Width	When to Use
`1.5`	Large icons (32px+) — lighter weight prevents visual heaviness at scale. Used on startup screen.
`2` (default)	Standard — all regular UI icons (14–24px). Matches Lucide default weight.
`2.5`	Small icons (10–12px) where extra weight improves readability at tiny sizes. Rare.

Consistency rule: Within a single component or region, all icons must use the same stroke width. Never mix stroke widths in a toolbar, card, or menu.

Icon Catalog

Icons used throughout the app, organized by function. Each icon has a single semantic meaning — the same icon is never used for two different purposes.

Navigation

Icon	Component	Meaning
	`Sparkles`	Generate
	`PenLine`	Edit
	`LayoutGrid`	Gallery
	`ArrowUpDown`	Quick Sort
	`Store`	Model Catalog
	`GitCompareArrows`	Model Compare
	`Settings`	Settings page
	`BrainCircuit`	House mark

Actions

Icon	Component	Meaning
	`Download`	Save / download image
	`Share2`	Share image
	`Copy`	Copy to clipboard
	`Trash2`	Delete
	`Heart`	Favorite / like
	`Star`	Best / starred
	`RefreshCw`	Rerun / regenerate
	`RotateCcw`	Undo / revert
	`ZoomIn`	Zoom in / enlarge
	`Maximize2`	Fullscreen

Status & Indicators

Icon	Component	Meaning
	`Check`	Success / confirmed
	`X`	Close / dismiss / error
	`AlertTriangle`	Warning
	`Info`	Information
	`Loader2`	Loading (animated spin)
	`CircleDot`	Online / connected status
	`CircleOff`	Offline / disconnected

Media & Content

Icon	Component	Meaning
	`Image`	Image file
	`Video`	Video file
	`Wand2`	AI enhancement / magic
	`Eraser`	Remove background
	`ArrowUpFromLine`	Upscale
	`SlidersHorizontal`	Parameters / settings
	`Palette`	Theme / appearance
	`FolderOpen`	Open folder / browse
	`Search`	Search
	`Filter`	Filter options

Auth & User

Icon	Component	Meaning
	`User`	User account (signed in)
	`LogIn`	Sign in prompt (signed out)
	`LogOut`	Sign out
	`Shield`	Security / auth

Pairing Rules

How icons combine with text, buttons, and other UI elements.

Context	Icon Size	Gap	Position
Button with label	sm (16px)	gap-2 (8px)	Leading (before text). Trailing only for directional arrows.
Icon-only button	sm (16px)	—	Centered. Must have `aria-label` or tooltip.
Sidebar nav item	md (20px)	—	Centered in 40×40px hit area. Tooltip on hover.
Input prefix	sm (16px)	gap-2 (8px)	Leading inside input field (absolute positioned).
Badge	2xs (10px)	gap-1 (4px)	Leading, vertically centered.
Card header	sm–md (16–20px)	gap-2 (8px)	Leading the title text.
Toast	sm (16px)	gap-2 (8px)	Leading, vertically aligned to first line of text.
Radial menu item	sm (16px)	—	Centered in 40×40px circle. Label on hover.

Color Rules

State	Icon Color	Tailwind Class
Default	Matches text color	text-foreground (inherits)
Secondary / muted	Reduced emphasis	text-muted-foreground
Destructive action	Error red	text-destructive
Success indicator	Status green	text-green-500
Warning indicator	Status amber	text-yellow-500
Disabled	Very low contrast	text-muted-foreground opacity-50

Accessibility: Icons are always decorative when paired with text (add aria-hidden="true"). When used alone (icon-only buttons), they must have aria-label describing the action, and a visible tooltip on hover for sighted users.

Custom Marks

Beyond Lucide icons, the app uses two custom visual marks that carry special meaning.

1. Sparkle Mark (✦)

✦

The four-pointed star (Unicode ✦ or Lucide Sparkles) is the signature mark of the app. It appears on the primary action, in the rail, and as a decorative element on the startup screen. It represents the moment of AI creation — the spark where imagination becomes image.

2. Brain Circuit (App Icon)

🧠

BrainCircuit from Lucide is the VirtualLife house mark, rendered at 24px beside the wordmark in the app bar. The brain is the human half (Life); the circuit traces are the machine half (Virtual). Products may carry their own mark in the app bar instead — the house mark is the fallback and the family resemblance.

App bar icons

The app bar's right side carries three icons only: Monitor / Smartphone for the viewport toggle, Sun / Moon for the theme toggle, and the avatar. All 16px, stroke-width 2. The shell draws no window controls — a product that needs them keeps them in its own window frame, outside the app bar.