---
title: "Contributing"
description: "Why Tanrei does not accept outside contributions, how to report a bug or ask a question, and where the rules live."
url: "https://tanrei.chnotchy.com/project/contributing/"
last_updated: 2026-10-18T00:51:38.000Z
---

# Contributing

> Why Tanrei does not accept outside contributions, how to report a bug or ask a question, and where the rules live.

> [!NOTE]
> **Outside contributions are not accepted**
>
> The repository is public at [github.com/chnotchy/tanrei](https://github.com/chnotchy/tanrei), so that anyone can read how Tanrei is made. Every change is made by the maintainers: pull requests from outside are closed unmerged, and proposals for new components or tokens are not taken. The reason is the supply chain: Tanrei runs inside other people’s products, every change from outside is a way for code its maintainers did not write to reach them, and the current security climate makes that a risk the project does not take. To report a bug or ask a question, [open an issue](https://github.com/chnotchy/tanrei/issues). Report a security problem privately, as the repository’s `SECURITY.md` describes, never in an issue.

## Where the rules live

The repository’s root `AGENTS.md` is the authoritative guide for whoever changes the repository, human or AI. It is short, and reading it first will save time. Each package and source directory may add a nested `AGENTS.md` with local rules; the nearest file applies, and none of them may weaken the root. `CONTRIBUTING.md` at the root is the long form.

Longer-form material lives under the repository’s `docs/` directory: the architecture overview, and the governance, which says who decides what.

## Shape of a change

Every change follows these steps, whoever makes it.

1. **Start from the source of truth.** Changes to a component’s public surface begin in `specs/`. Changes to a design value begin in `tokens/`. Platform code follows.
2. **Run the checks locally.** `pnpm validate`, `pnpm generate`, then `pnpm check`. If the drift check fails, regenerate; do not edit the generated file.
3. **Keep platforms honest.** If you cannot finish a platform, leave its status as it truly is. The matrix is generated from the repository and must not claim more than exists.
4. **Add a changeset** for anything users can see, and use Conventional Commits (`feat(web): …`, `fix(tokens): …`, `docs: …`).

## What no change may contain

- Hardcoded colors, radii, type, spacing, motion or opacity inside a component.
- Snapshot baselines updated to make a test pass.
- Loosened contrast or accessibility thresholds.
- Documentation text copied from another design system. All prose in Tanrei is original.

## Documentation changes

This site lives in `apps/docs/`. Prose is hand-written MDX: English is the source, and each page is translated into the site’s other languages (`apps/docs/i18n/README.md` lists them, and says how a translation records what it was made from). Tables that a spec, token file or the status matrix can supply are rendered from that data and are never typed by hand. See `apps/docs/AGENTS.md` for the local rules.