Contributing
Contributions are welcome, and there are three things worth knowing before you open a pull request: the agreement, the toolchain, and what actually helps most right now.
The agreement (CLA)
Today every line has a single copyright holder, and that keeps doors open: fixing a defect in the licence, publishing a commercial edition, dual-licensing, handing the project to a foundation. The first contribution arriving without an agreement closes them — nobody can relicense someone else’s code, and finding a contributor two years later to ask is, in practice, impossible.
It is deliberately narrow: you keep every right you have in your contribution. You grant a licence, you do not hand over ownership.
Signing is a line you add yourself, in your own pull request, to .github/cla-signatures.json. The commit is authenticated by your GitHub account, dated and kept in history — which is exactly what a record of consent should be. A gate checks the signature on every pull request; there is no bot with write access to the repository.
The toolchain
Node 22 or newer, and Yarn 1.22 Classic — that exact version, because the lockfile is only compatible with it. CI runs on Node 22 and 24.
This is a rule of the monorepo, not of the package. Installing Granularity into your application works with npm, pnpm, yarn or bun — the install page shows all four. Confusing the two costs an afternoon, so it is spelled out here. Installation
The workflow
- Branch from
main - make the change and cover it with tests
- run lint, tests and the build locally
- open a pull request against
main— CI repeats all three for the package and the showcase
Style
ESLint with @antfu/eslint-config, types emitted by vue-tsc during the build with no errors allowed, and Conventional Commits — the last one is a recommendation rather than a rule, and it makes the changelog easier to assemble.
Releases
The version is bumped in the package manifest and a vX.Y.Z tag is pushed to main; the tag triggers publication to npm with provenance. The changelog of the package being released is updated in the same pull request — there is no changelog at the repository root, every package keeps its own.
What your contribution is licensed under
Apache-2.0 with an Additional Ethical Use Clause. The clause adds a use restriction on top of Apache-2.0, which makes the project source-available rather than OSI-approved open source; it binds contributions exactly as it binds the rest of the code.
What helps most right now
Not a wish list. These are gaps the portal ran into while it was being built, and each one is visible on the site today.
- The per-component keyboard contract covers 48 of the 108 catalogue entries, and lives in 3 of the 8 packages that ship components. On the pages of the rest there is no accessibility section at all: the portal will not write one on the author's behalf.where it shows
- The English documentation is machine-translated and waiting for a native speaker to read it. Every such page says so at the top.where it shows
- Components have no status metadata — stable, new, experimental — so the catalogue has no filter by it. Adding a table of statuses to the site instead of the library would be the wrong fix.where it shows
- The sort buttons in the
GrDataTableheader measure 52×16 and 70×16 — below the 24×24 minimum of WCAG 2.5.8. On a phone they are hard to hit.where it shows
Tell people you use it
A badge for your README. There is a dark variant at /badge/built-with-dark.svg, and two more badges — version.svg and components.svg — whose numbers are computed on every build rather than typed, so they do not go stale in your file.
[](https://granularity.tech)A live component fits into an article too: the «Embed» button under any example on a component page copies a ready <iframe>, and a link to a component page pasted into Notion, Ghost or WordPress turns into the same demo by itself.
Rules of behaviour
There is no code of conduct file yet, and pretending otherwise would be worse than saying so. The ethical clause in the licence is a different thing: it governs how the product may be used, not how people talk to each other.