Phosix

A lightweight, customizable React icon package built with TypeScript and SVG.

Phosix provides reusable icons based on the Phosphor Icons collection with a consistent React API and built-in CLI tooling for importing, validating, generating, inspecting, and managing icons.

Phosix supports all six Phosphor icon weights:

• Thin
• Light
• Regular
• Bold
• Fill
• Duotone

The SVG files remain the source of truth, while Phosix automatically generates optimized React/TypeScript components, exports, and metadata.

Features

• ⚛️ Built for React
• 🔷 Written in TypeScript
• 🎨 Customizable color
• 📏 Customizable size
• 🪶 Six Phosphor weights
• 🧩 Standard React SVG props
• 🌳 Tree-shakeable
• 📦 Available as an npm package
• 🪶 Lightweight and dependency-friendly
• 🔄 Automated SVG → TSX generation
• 🧪 Automated SVG validation
• 🗂️ Automatic icon metadata generation
• 🛠️ CLI tools for importing, generating, deleting, validating, and inspecting icons
• 🔁 Consistent API across all six weights

Installation

Install Phosix using npm:

npm install phosix

Or using Yarn:

yarn add phosix

Or using pnpm:

pnpm add phosix

Usage

Import an icon from Phosix:

import { Search } from "phosix";

Use it in a React component:

<Search />

The default weight is:

regular

Icon Weights

Phosix supports all six Phosphor icon weights.

import { Heart } from "phosix";

Thin

<Heart weight="thin" />

Light

<Heart weight="light" />

Regular

<Heart weight="regular" />

Bold

<Heart weight="bold" />

Fill

<Heart weight="fill" />

Duotone

<Heart weight="duotone" />

The default is:

<Heart />

which is equivalent to:

<Heart weight="regular" />

Customization

Size

<Search size={24} />

<Search size={48} />

Color

<Search color="red" />

<Search color="#0f95" />

You can also use CSS classes:

<Search className="text-red-500" />

Combining Props

<Search
  size={48}
  color="#0f95"
  weight="bold"
/>

Changing Weight

The weight can be changed independently from the size and color:

<Search
  size={32}
  color="blue"
  weight="thin"
/>

Or:

<Search
  size={32}
  color="blue"
  weight="duotone"
/>

SVG Props

Phosix icons support standard React SVG properties and event handlers where supported by React.

<Search
  size={32}
  className="my-icon"
  aria-label="Search"
  role="img"
  onClick={handleClick}
/>

Common supported props include:

• id
• style
• className
• role
• aria-label
• onClick
• Standard React SVG attributes

TypeScript

Phosix includes TypeScript declarations for type safety and editor autocomplete.

import {
  Search,
  type IconProps,
} from "phosix";

IconProps includes the Phosphor weight type:

type PhosphorWeight =
  | "thin"
  | "light"
  | "regular"
  | "bold"
  | "fill"
  | "duotone";

Example:

<Search
  size={32}
  weight="bold"
/>

Icon Source and Generation

Phosix uses SVG files as the source of truth.

The source collection is organized by Phosphor weight:

icons/
├── thin/
├── light/
├── regular/
├── bold/
├── fill/
└── duotone/

The generation pipeline is:

Phosphor SVG sources
        │
        ▼
npm run validate
        │
        ▼
npm run generate
        │
        ├── TSX icons
        ├── index.ts
        └── metadata
        │
        ▼
npm run check
        │
        ├── SVG validation
        ├── typecheck
        ├── tests
        └── production build
        │
        ▼
Phosix

Generated files should normally not be edited manually.

Changes should be made to the SVG source files and then regenerated.

Importing Phosphor Icons

Phosix includes a CLI command for importing and deriving SVG icons from the Phosphor Icons source repository.

npm run import:phosphor

The command imports the Phosphor SVG sources into the six weight directories:

icons/
├── thin/
├── light/
├── regular/
├── bold/
├── fill/
└── duotone/

It does not directly create the final React components.

Phosphor Import Workflow

npm run import:phosphor

npm run validate

npm run generate

npm run check

The responsibilities are:

| Command | Responsibility | |---|---| | npm run import:phosphor | Import Phosphor SVG sources into Phosix | | npm run validate | Validate all six Phosphor SVG collections | | npm run generate | Convert SVG sources into React/TypeScript components | | npm run check | Run validation, type checking, tests, and production build |

This keeps external icon acquisition separate from Phosix's React component generation.

Adding Icons

Add the SVG sources to the appropriate Phosphor weight directories.

For example:

icons/

├── thin/
│   ├── search-thin.svg
│   └── heart-thin.svg
│
├── light/
│   ├── search-light.svg
│   └── heart-light.svg
│
├── regular/
│   ├── search-regular.svg
│   └── heart-regular.svg
│
├── bold/
│   ├── search-bold.svg
│   └── heart-bold.svg
│
├── fill/
│   ├── search-fill.svg
│   └── heart-fill.svg
│
└── duotone/
    ├── search-duotone.svg
    └── heart-duotone.svg

Each icon should have all six weights.

For example:

search-thin.svg
search-light.svg
search-regular.svg
search-bold.svg
search-fill.svg
search-duotone.svg

These are treated as one icon family:

Search

Icon Naming

The filename determines the generated component name.

Examples:

search-regular.svg        → Search

x-regular.svg             → X

home-regular.svg          → Home

arrow-left-regular.svg    → ArrowLeft

chevron-down-regular.svg → ChevronDown

The weight suffix is not included in the generated component name.

For example:

heart-thin.svg
heart-light.svg
heart-regular.svg
heart-bold.svg
heart-fill.svg
heart-duotone.svg

all generate:

Heart

with the weight selected using the weight prop.

1. Validate

Run:

npm run validate

The validator checks:

• All six weight directories
• Valid XML/SVG syntax
• 256 × 256 Phosphor viewBox
• Supported SVG elements
• Forbidden SVG elements
• Forbidden attributes
• Duplicate icon names
• Matching icon families
• Missing weights

For example:

Checking thin...
✓ thin

Checking light...
✓ light

Checking regular...
✓ regular

Checking bold...
✓ bold

Checking fill...
✓ fill

Checking duotone...
✓ duotone

✓ All icons contain all six weights

2. Generate

Run:

npm run generate

This generates the corresponding React/TypeScript components and updates:

src/icons/
src/index.ts
src/metadata/icons.json

For example:

icons/
├── thin/search-thin.svg
├── light/search-light.svg
├── regular/search-regular.svg
├── bold/search-bold.svg
├── fill/search-fill.svg
└── duotone/search-duotone.svg

generates:

src/icons/Search.tsx

The generated component supports:

<Search weight="thin" />

<Search weight="regular" />

<Search weight="fill" />

<Search weight="duotone" />

3. Verify

Run:

npm run check

The check command runs the complete project verification pipeline:

npm run validate
npm run typecheck
npm run test:run
npm run build

Do not manually edit generated files:

src/icons/
src/index.ts
src/metadata/icons.json

If an icon needs to change, update its SVG source and run:

npm run generate

again.

Icon Metadata

Phosix provides metadata inspection through the getMetadata CLI.

Metadata is generated automatically from the SVG collection.

Single Icon

npm run getMetadata -- Search

Icon names are case-insensitive:

npm run getMetadata -- Search

npm run getMetadata -- search

npm run getMetadata -- SEARCH

You can also search using the icon filename:

npm run getMetadata -- search.svg

Multiple Icons

npm run getMetadata -- Search X Home

You can also use:

npm run getMetadata -- --Search --X --Home

All Icons

npm run getMetadata -- --all

Metadata is read from:

src/metadata/icons.json

The command is read-only and does not modify the icon collection.

Metadata includes information such as:

• Icon name
• Icon slug
• Source
• Tags
• ViewBox
• Available weights

Removing Icons

Remove an Icon Completely

npm run delete -- Search

This removes the icon's:

• Six Phosphor SVG sources
• Generated React component
• Public export
• Metadata entry

Icon names are case-insensitive.

Selective Deletion

Delete only the SVG sources:

npm run delete -- --Search svg

Delete only the generated TSX:

npm run delete -- --Search tsx

Delete only metadata:

npm run delete -- --Search metadata

Delete multiple parts:

npm run delete -- --Search svg tsx

Selective deletion can leave generated files out of sync.

For normal icon removal, use the full deletion command:

npm run delete -- Search

Development

Clone the repository:

git clone <repository-url>

cd phosix

Install dependencies:

npm install

Development Commands

Import Phosphor Icons

npm run import:phosphor

Validate Icons

npm run validate

Generate Icons

npm run generate

Delete an Icon

npm run delete -- IconName

Get Icon Metadata

npm run getMetadata -- IconName

Run Full Project Check

npm run check

Typecheck

npm run typecheck

Run Tests Once

npm run test:run

Run Tests in Development Mode

npm run test

Run Tests in Watch Mode

npm run test:watch

Build the Package

npm run build

For detailed command documentation, see:

docs/commands.md

Project Structure

phosix/

├── icons/
│   ├── thin/
│   │   ├── search-thin.svg
│   │   └── heart-thin.svg
│   │
│   ├── light/
│   │   ├── search-light.svg
│   │   └── heart-light.svg
│   │
│   ├── regular/
│   │   ├── search-regular.svg
│   │   └── heart-regular.svg
│   │
│   ├── bold/
│   │   ├── search-bold.svg
│   │   └── heart-bold.svg
│   │
│   ├── fill/
│   │   ├── search-fill.svg
│   │   └── heart-fill.svg
│   │
│   └── duotone/
│       ├── search-duotone.svg
│       └── heart-duotone.svg
│
├── src/
│   ├── components/
│   │   └── IconBase.tsx
│   │
│   ├── icons/
│   │   ├── Search.tsx
│   │   └── Heart.tsx
│   │
│   ├── metadata/
│   │   ├── icons.json
│   │   └── types.ts
│   │
│   ├── types.ts
│   └── index.ts
│
├── scripts/
│   ├── check.ts
│   ├── delete-icons.ts
│   ├── generate-icons.ts
│   ├── get-metadata.ts
│   ├── import-phosphor.ts
│   └── validate-icons.ts
│
├── tests/
│   ├── icons.test.tsx
│   └── setup.ts
│
├── docs/
│   └── commands.md
│
├── .gitignore
├── LICENSE
├── README.md
├── package.json
├── package-lock.json
├── tsconfig.json
└── tsup.config.ts

Production Verification

Before publishing a new version:

npm run validate

npm run generate

npm run check

All commands should complete successfully before publishing.

A successful verification should confirm:

✓ Six Phosphor weight collections are valid
✓ All icon families are complete
✓ React components compile
✓ All icon variants render
✓ TypeScript passes
✓ Tests pass
✓ Production build succeeds

Roadmap

• [x] Initial npm package setup
• [x] TypeScript support
• [x] React support
• [x] SVG icon architecture
• [x] Phosphor six-weight architecture
• [x] Initial icons
• [x] Local package testing
• [x] Automated SVG validation
• [x] Automated SVG → TSX generation
• [x] Automatic icon exports
• [x] Automatic icon metadata generation
• [x] Aggregated icon tests
• [x] Type checking
• [x] ESM build
• [x] CommonJS build
• [x] Type declaration generation
• [x] Icon deletion CLI
• [x] Metadata inspection CLI
• [x] Project verification CLI
• [x] Command documentation
• [ ] Expand icon collection
• [ ] Add continuous integration
• [ ] Improve package tooling
• [ ] Expand documentation
• [ ] Build Phosix documentation website

Contributing

Contributions, suggestions, bug reports, and new icon ideas are welcome.

To contribute a new icon family:

1. Add all six SVG weights to their respective directories.
2. Run npm run validate.
3. Run npm run generate.
4. Run npm run check.
5. Submit your changes.

Example:

icons/
├── thin/my-icon-thin.svg
├── light/my-icon-light.svg
├── regular/my-icon-regular.svg
├── bold/my-icon-bold.svg
├── fill/my-icon-fill.svg
└── duotone/my-icon-duotone.svg

Please do not manually edit generated icon files unless you are working on the generation system itself.

Documentation

Detailed CLI documentation is available in:

docs/commands.md

It covers:

• Phosphor SVG import
• SVG validation
• Icon generation
• Icon deletion
• Metadata generation
• Metadata inspection
• Project verification
• Type checking
• Testing
• Test watch mode
• Production builds
• Development workflows

License

Phosix is released under the MIT License.

See the LICENSE file for the complete license text.

External Sources

Phosix derives its icon sources from the open-source Phosphor Icons project.

Phosphor icon assets and their respective licensing and attribution requirements remain subject to the terms of the upstream project.

Phosix is an independent package and is not the official Phosphor Icons package.

Made with ❤️ for React developers.

Phosix — Six weights. One React API.