# Contributing to ASK Design System

> Design system changes ripple. The hurdle to merge is intentionally non-trivial.

## Before you open a PR

1. **Read the brand guidelines.** Start with [`docs/brand/guidelines.md`](./docs/brand/guidelines.md). Understand the three brand pillars and the four mandatory compliance patterns before proposing a change that touches them.
2. **Open an issue.** Use the right template:
   - 🎨 [Token change](./.github/ISSUE_TEMPLATE/token_change.yml) — color, type, spacing, radius, motion
   - 🧩 [Component request](./.github/ISSUE_TEMPLATE/component_request.yml) — new or modified UI primitive
   - 🐛 [Bug report](./.github/ISSUE_TEMPLATE/bug_report.yml) — drift between Figma and code, or a broken artifact
3. **Get acceptance from the owner** (Matteo Rizzo) in the issue thread *before* writing code. We reject PRs that arrived without an aligned issue.

## How the source flows

```
   tokens.json (DTCG) ──Style Dictionary──▶ globals.css
                                         ├─▶ tailwind.preset.ts
                                         ├─▶ storybook/theme.ts
                                         └─▶ figma/tokens-studio.json
```

**`design-tokens/tokens.json` is the only file you edit by hand for token changes.** Run `pnpm run tokens:build` and commit the generated artifacts alongside.

CI (`tokens-build.yml`) will fail your PR if generated artifacts drift from `tokens.json`.

## Branching & commits

- Branch from `main`. Name: `feat/<short-slug>`, `fix/<slug>`, `docs/<slug>`, `tokens/<slug>`, `chore/<slug>`.
- Use [Conventional Commits](https://www.conventionalcommits.org/). Examples:
  - `feat(tokens): add state.processing intent for streaming agents`
  - `fix(button): align focus ring with --ring token`
  - `docs(patterns): clarify HITL slide-to-approve microcopy`
  - `chore(ci): bump chromatic action to v11`
- Sign your commits (`git commit -S`). Unsigned commits are blocked by branch protection.

## PR checklist

A PR is reviewable when **all** of:

- [ ] Linked issue exists and the owner has approved the direction.
- [ ] Changelog entry added to `CHANGELOG.md` under `## Unreleased`.
- [ ] If tokens changed: `pnpm run tokens:build` was run; generated artifacts are committed.
- [ ] If components changed: Figma component updated **before** code merges (link the Figma frame in the PR description).
- [ ] If brand voice / microcopy changed: the example in `docs/brand/voice-and-tone.md` is updated too.
- [ ] CI is green (`ci.yml`, `tokens-build.yml`, `chromatic.yml`).
- [ ] At least one CODEOWNER approval.

PR template: [`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md). Don't delete sections — strike through them with `~~ ~~` if not applicable.

## Versioning (semver)

| Bump | When |
|---|---|
| **Patch** | Bug fixes, doc updates, non-visual refactors. |
| **Minor** | New tokens, new components, additive variants. Backward compatible. |
| **Major** | Renames, removals, color shifts, type-ramp changes. Breaking. |

The owner bumps the version in `package.json` and tags `ask-design@x.y.z` on merge to `main`.

## What we won't accept

- Tokens added "because someone wanted them" — every token earns a justification tied to a brand pillar or a real surface.
- Components that don't match a Figma counterpart.
- Compliance pattern changes without security review (CC Matteo + security@).
- Hex values, magic numbers, or hand-tuned pixel sizes in code. Bind to tokens.
- Rounded corners larger than `radius.lg` (8 px) — ASK is a sharp brand.
- Emoji or stock illustrations in the brand surface.

## Local development

```bash
# Prereqs: Node 20+, pnpm 9+
pnpm install
pnpm run tokens:check    # CI parity
pnpm run tokens:build    # regenerate downstream
pnpm run brand-sheet     # serves the HTML brand sheet at localhost:4173
```

## Questions

- General: open a [Discussion](https://github.com/mirai-srl/project-ask-design-system/discussions) or ask in `#ask-design` on Slack.
- Brand: Matteo Rizzo · [matteo.rizzo@mir-ai.it](mailto:matteo.rizzo@mir-ai.it)
- Security & compliance: see [`SECURITY.md`](./SECURITY.md)

Thanks for keeping the system coherent.