Icons Package

Scalable icon primitives for Solara docs and component packages.

Exports

• Icon: runtime SVG renderer with accessibility defaults
• icons / iconNames: typed icon ID list
• iconMetadata: rich metadata used by docs/search UI
• iconCatalog: metadata list optimized for grid rendering
• animations.css: predefined keyframes for icon presets

Example

import { Icon } from "@solara/icons";

export function Example() {
  return <Icon name="search" aria-label="Search" size={24} />;
}

Package Goals

This package is designed to scale from a handful of icons to thousands while keeping:

• icon definition ownership localized per icon file
• rendering and animation behavior centralized in one runtime component
• docs website consumption package-backed (no deep imports into package internals)
• local sync workflow fast and predictable in apps/website

Source Of Truth And File Layout

Current architecture is source-driven and generated-in-place (no external build script yet).

packages/icons/
├── src/
│   ├── components/
│   │   └── Icon.tsx                # Runtime renderer and behavior logic
│   ├── generated/
│   │   ├── types.ts                # Shared icon types/contracts
│   │   └── icons/
│   │       ├── <icon-id>.ts        # One icon definition per file
│   │       └── index.ts            # Central registry + derived maps
│   ├── styles/
│   │   └── animations.css          # Keyframes used by presets
│   └── index.tsx                   # Public package API
└── README.md

Where Logic Lives

• src/generated/icons/<icon-id>.ts
  • owns one icon's SVG path markup (svg)
  • owns metadata (name, description, keywords, sizes, optional animation)
  • owns optional icon-specific motion rules (motion) for path-level behavior
• src/generated/icons/index.ts
  • imports all icon definition modules
  • builds iconDefinitions, iconData, and iconMetadata registries
• src/components/Icon.tsx
  • runtime rendering (<svg dangerouslySetInnerHTML />)
  • accessibility behavior (aria-hidden defaults, role="img" when labeled)
  • size/variant/stroke width handling
  • animation behavior resolution (global preset or icon path-level motion)
• src/index.tsx
  • stable public exports for package consumers (Icon, catalog, names, metadata)

Data Model

The core contract is SolaraIconDefinition in src/generated/types.ts.

• id: icon identifier (SolaraIconName)
• svg: inner SVG markup (paths/groups/etc; no wrapping <svg>)
• metadata: documentation and discovery data
• defaults (optional): icon rendering defaults such as strokeWidth
• motion (optional): per-path animation rules with trigger and timing controls

Important: path-level motion depends on data-part attributes in the icon's svg markup.
If a motion.paths[].part value is missing in SVG markup, that path rule cannot apply.

Icon Component API

Icon accepts all standard SVGAttributes<SVGSVGElement> except name, plus:

• name: SolaraIconName (required)
• size?: SolaraIconSize | number | string
  • undefined defaults to 1em
  • number converts to pixel string (for example 24 -> "24px")
• strokeWidth?: number
  • applied on the root <svg>
  • falls back to icon-level default when available
• variant?: "default" | "primary" | "secondary" | "accent" | "error" | "warning"
  • mapped to theme token color variables
• animated?: boolean
  • enables metadata/motion-based animation behavior
• animation?: "spin-clockwise" | "pulse" | "bounce"
  • explicit override preset for root-level animation

Animation Behavior Rules

Animation resolution order:

1. Explicit animation prop (root-level preset override)
2. Icon motion rules (path-level behavior via data-part)
3. Icon metadata animation (metadata.animation) when animated=true
4. No animation

Trigger behavior:

• motion.trigger = "hover": path rules apply only when the icon is hovered
• motion.trigger = "manual": path rules apply whenever animated=true

Accessibility Defaults

• Without a label:
  • aria-hidden="true"
  • focusable="false"
• With aria-label or aria-labelledby:
  • role="img"
  • icon is treated as semantic content

Use labels for meaningful icons in content; keep unlabeled icons decorative.

How To Add A New Icon

Additions should be atomic and centered around one icon definition file.

1. Pick an ID in kebab-case (example: arrow-circle-left).
2. Create src/generated/icons/arrow-circle-left.ts.
3. Export a SolaraIconDefinition object with:
   • id
   • svg path markup (use currentColor; add data-part markers if motion is needed)
   • metadata with name, description, keywords, sizes, optional animation
   • optional defaults and optional motion
4. Register the icon in src/generated/icons/index.ts:
   • import the new module
   • add it to iconDefinitionList
5. Verify package consumers:
   • iconNames/icons/iconCatalog include the new icon automatically
6. Validate with typecheck:
   • pnpm --filter @solara/website typecheck

Minimal icon module template:

import type { SolaraIconDefinition } from "../types";

export const myIcon: SolaraIconDefinition = {
  id: "my-icon",
  svg: '<path data-part="main" d="..." stroke="currentColor" vector-effect="non-scaling-stroke" />',
  metadata: {
    name: "My Icon",
    description: "One-line purpose.",
    keywords: ["my", "icon"],
    sizes: [16, 20, 24, 32]
  }
};

Pipeline To Website

Current flow from icon file to docs explorer:

1. Icon definition is added under packages/icons/src/generated/icons/*
2. Registry in src/generated/icons/index.ts derives package maps
3. Public API in src/index.tsx exports iconCatalog, Icon, and names
4. Website route apps/website/app/(main)/icons/page.tsx imports iconCatalog from @solara/icons
5. Client grid apps/website/app/components/IconGrid.tsx renders searchable/filterable previews using package Icon

Because website imports use @solara/icons, this stays aligned with local sync mode and package contracts.

Local Dev And Real-Time Updates

For near-instant package edits in the website:

1. run pnpm dev:local (or pnpm dev:local:icons)
2. edit files under packages/icons/src/...
3. refresh/check /icons for updated data and preview behavior

If updates do not appear, verify the mode badge shows Local Sync and that imports stay package-based.

Notes For Large Icon Sets

• Keep each icon in its own file to reduce merge conflicts and keep ownership clear.
• Maintain iconDefinitionList ordering intentionally (for deterministic docs ordering).
• Keep metadata quality high (keywords and description) since docs search depends on it.
• Prefer path-level motion for icon-specific behavior and reserve root-level presets for broad overrides.