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 an icon specification and Lucide glyph mappings in tooling/generate-icon-library.mjs

Run npm run generate to create definitions, React components, exports, and website entries

For a new category, update core types, CLI labels, and the generator's category descriptions

Update count expectations and add tests for the new states

Run npm run format and the required verification commands

Add a changeset describing the user-visible addition

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. The shared renderer observes prefers-reduced-motion and cancels active animations.

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.