Contributing

Thank you for helping improve StateGlyph. This guide covers everything from local setup to submitting your first pull request.

Contribution workflow

Set up the repository

You need Node.js 22.19 or newer and npm 10.9 or newer. Clone the repo and install dependencies.

Terminal

git clone https://github.com/kamalhara/StateGlyph.gitcd StateGlyphnpm installnpm run dev

Make your change

Keep each pull request focused on one improvement. Use existing Lucide icons when adding or changing an icon state. Include accessible labels and respect reduced-motion preferences.

Verify your work

Run the full verification suite before submitting. All checks must pass.

Terminal

npm run lintnpm run typechecknpm testnpm run build

Create a changeset

If your change affects a published package, create a changeset. Choose the affected package and explain the user-visible change. Do not edit package versions manually.

Terminal

npm run changeset

Adding a new icon

An icon needs changes across several packages. Follow this checklist:

Add a typed icon definition in packages/core/src/icons/

Export the definition from packages/core/src/index.ts

Create a React component in packages/react/src/icons/

Export the component from packages/react/src/index.ts

Add Lucide icon mapping in packages/react/src/lucide/

Add documentation entry in apps/docs/src/data/icon-catalog.tsx

Write tests for metadata and state mappings

Guidelines

One PR per improvement

Keep pull requests focused. Don't bundle unrelated changes together.

Use existing Lucide icons

StateGlyph builds on the Lucide icon set. Use existing Lucide glyphs when adding states.

Include accessible labels

Every state must have a human-readable label. These are used for ARIA attributes.

Respect reduced motion

Mark continuous states appropriately. CSS handles the rest via prefers-reduced-motion.

Search before opening issues

Check existing issues and PRs before opening a duplicate.

Project structure

StateGlyph is an npm workspace monorepo using TypeScript, Next.js, Tailwind CSS, tsup, and Vitest.

StateGlyph/
├── apps/
│   └── docs/          # Next.js documentation site
├── packages/
│   ├── core/          # Icon definitions & types
│   ├── react/         # React components
│   ├── cli/           # Copy-and-own CLI
│   └── transitions/   # Animation utilities
├── tests/             # Shared test utilities
└── tooling/           # Build tooling

License

By contributing, you agree that your contribution is licensed under the MIT License used by this repository. The underlying Lucide icons are available under the ISC License.