# Contributing to the ShopConnect Design System

Everyone contributes the same way: **propose a change, a brand owner approves it.** No one edits the brand alone; nothing gets lost. You don't need to install anything — GitHub's website is enough.

## The three most common contributions

### 🎨 Add or change a color
1. Open `tokens.css` on GitHub → click the ✏️ (edit) button.
2. Add/adjust a variable (e.g. a new status color, or tweak a brand preset). Keep the two-layer rule: **structural neutrals are stable; brand is swappable.**
3. Add a one-line comment saying *why*.
4. "Propose changes" → this opens a Pull Request. A brand owner reviews and merges.

*Not sure about CSS? Use the **"Add a color"** issue template instead and describe it — we'll write the token for you.*

### 🔤 Add or change a font
1. Note the reasoning in `fonts.md` (pick, license, why).
2. If it's a paid/self-hosted face, add the woff2 and extend the right `--font-*` stack in `tokens.css`.
3. PR it. (Or use the **"Suggest a font"** issue template.)

### 🖼️ Add a photo / inspiration / asset
- **Reference/mood image** (something you like, to pull from later) → `reference-library/inspirations/`.
- **ShopConnect-owned asset** (our logo, our product screenshot, approved photography) → `brand/shopconnect/assets/`.
- Drag-and-drop upload works right in the GitHub web UI. Name it clearly. PR it. (Or use the **"Add an inspiration / asset"** issue template — attach the image and we'll place it.)

## The rules that keep it coherent

1. **Say why.** Every change gets a one-line reason in the PR. Taste accretes through recorded decisions.
2. **Respect the surface matrix.** New pattern? Name the surface it's for. Read `principles.md` + `surface-matrix.md` first.
3. **ShopConnect canonical vs reference library.** Don't promote Mitch's material into the root files (`tokens.css`, `principles.md`) without deciding it's genuinely ours — note that in the PR.
4. **Restraint wins.** When adding a loud move, the burden is on you to justify it against the anti-patterns.

## Who approves

Brand owners (see `CODEOWNERS`) review every PR touching the root brand files. Anyone can open PRs and comment.

## Previewing your change

Open `index.html` locally (double-click), or the published brand-book URL after merge. `reference-library/reference.html` has a live brand picker — set it to `shopconnect` to see tokens applied.