tabler/CONTRIBUTING.md

# Contributing to Tabler

Thank you for wanting to contribute! This is a short overview — the full guide lives in the documentation: [How to Contribute](https://docs.tabler.io/ui/getting-started/how-to-contribute/).

## Ways to contribute

- **Pick a starter issue** — issues labeled [`good first issue`](https://github.com/tabler/tabler/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are small and well-scoped, and [`help wanted`](https://github.com/tabler/tabler/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issues welcome community help.
- **Report a bug** — use the [bug report template](https://github.com/tabler/tabler/issues/new?template=bug_report.yml). Include steps to reproduce and, if possible, a live example (for example a JSFiddle).
- **Suggest a feature** — use the [feature request template](https://github.com/tabler/tabler/issues/new?template=feature_request.yml) or start a [discussion](https://github.com/tabler/tabler/discussions) first if you are not sure.
- **Improve the documentation** — docs live in `docs/content/**/*.mdx` and follow the same pull request workflow as code.
- **Submit a pull request** — fixes and improvements are always welcome. For large changes, please open an issue or discussion first so we can align before you invest time.
- **Report a security issue** — do not open a public issue; follow the [security policy](SECURITY.md) instead.

## Quick start

Requirements: Node.js 22.12+ and [pnpm](https://pnpm.io/).

```sh
pnpm install
pnpm run dev
```

This starts the preview website at [http://localhost:3000](http://localhost:3000) and the documentation at [http://localhost:3010](http://localhost:3010), both with live reload.

You can also skip the local setup entirely: open the repository in [GitHub Codespaces](https://codespaces.new/tabler/tabler) or a VS Code Dev Container — the configuration in `.devcontainer/` installs Node.js, pnpm and all dependencies for you.

### Docker

If you prefer not to install Node.js, build and run the provided image from the repository root:

```sh
docker build -t tabler .
docker run -p 3000:3000 -p 3010:3010 -v $(pwd)/core:/app/core -v $(pwd)/preview:/app/preview -v $(pwd)/docs:/app/docs -v $(pwd)/shared:/app/shared tabler
```

This mounts the source directories into the container and exposes the preview on port 3000 and the documentation on port 3010. Edit anything in `core/`, `preview/`, `docs/` or `shared/` and the browser refreshes after the rebuild.

Or use Docker Compose, which applies the same mounts and ports:

```sh
docker compose up --build
```

## Where things live

- `core/` — the framework: SCSS (`core/scss/`) and JavaScript (`core/js/`)
- `preview/` — demo website (Astro, pages in `preview/pages/*.astro`)
- `docs/` — documentation website (Astro, pages in `docs/content/**/*.mdx`)
- `shared/` — components and layouts shared by preview and docs (`@shared` alias), plus `data/` and `static/`
- `shared/data/` — JSON data for demo pages (`@data` alias)

Do not edit `dist/` folders — they are generated by the build.

## Useful commands

| Command                       | What it does                                                 |
| ----------------------------- | ------------------------------------------------------------ |
| `pnpm run dev`                | Start preview and docs dev servers with live reload          |
| `pnpm run build`              | Production build of all packages                             |
| `pnpm run lint`               | Markdown, Prettier, SCSS variable and generated-token checks |
| `pnpm run lint:fix`           | Auto-fix lint issues where possible                          |
| `pnpm run test`               | Run the test suites                                          |
| `pnpm run check`              | Lint plus TypeScript type checks                             |
| `pnpm run html-diff:baseline` | Snapshot all rendered preview pages (needs the dev server)   |
| `pnpm run html-diff`          | Byte-compare rendered preview pages against the snapshot     |
| `pnpm run generate:tokens`    | Regenerate `shared/lib/tokens.ts` from the core SCSS maps    |

Two of these help with refactors:

- **`html-diff`** proves a refactor does not change the rendered demo HTML: run `html-diff:baseline` before your change, refactor, then `html-diff` — it reports the first differing line per page and marks whitespace-only differences.
- **`generate:tokens`** keeps the TS unions in `shared/lib/tokens.ts` in sync with the SCSS maps (colors, sizes, breakpoints, payment providers, flags). Edit the SCSS map, regenerate, commit both — a stale file fails `pnpm run lint`.

## Before you open a pull request

1. **Branch off `dev`** and use the branch naming convention: `<type>/<short-description>`, for example `feat/gh-123-add-stepper-component` or `fix/markdown-table-overflow`. Allowed types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert`.
2. **Build and test**: `pnpm run build` must pass. For docs changes, also run `pnpm run lint`.
3. **Add a changeset** if your change affects any package: `pnpm exec changeset`. Use one sentence starting with `Added`, `Updated`, `Fixed` or `Removed`, with backticks for code tokens (for example `` Added `.btn-ghost` variant for buttons. ``).
4. **Write the PR in English**: a concise title in present tense (max ~72 chars, no trailing period) and a short description that explains why the change is needed.
5. **Keep the scope small**: one logical change per pull request makes reviews faster and releases safer.

## Code style

- Use Bootstrap 5 conventions and Tabler's CSS custom properties pattern: `--component-property`. Write custom properties without a prefix — the build adds the public `--tblr-` prefix. Names owned by a third-party library you are theming must be listed in `cssVarIgnore` in `.build/css-var-prefix.ts` so they stay untouched.
- Write documentation in simple English: short sentences, common words, direct instructions.
- Ensure changes work in all supported browsers (see the [browser support docs](https://docs.tabler.io/ui/getting-started/browser-support/)).

## Code of conduct

By participating, you agree to follow our [Code of Conduct](.github/CODE_OF_CONDUCT.md).