# Buzzvil patterns: design guidelines

This repo holds three open-contribution sub-galleries. Pick the one you're contributing to and follow its rules. Every PR is opened through an agent (Claude Code or similar), so the cross-cutting agent contract lives in [`AGENTS.md`](./AGENTS.md) at root — read that first if you're an agent.

| Sub-gallery | What it is | Per-type rules |
|---|---|---|
| [`patterns/`](./patterns/) | Animated SVG compositions that fill the Buzzvil mark and the morphing blob. Three-colour-token contract. | [`patterns/GUIDELINES.md`](./patterns/GUIDELINES.md) |
| [`heroes/`](./heroes/) | Page-specific hero visuals for buzzvil.com. Mark-with-pattern anchor + one focal motion. | [`heroes/GUIDELINES.md`](./heroes/GUIDELINES.md) |
| [`palettes/`](./palettes/) | Named triples of `--c-bg / --c-mid / --c-acc` in OKLCH. Drive every render. | [`palettes/GUIDELINES.md`](./palettes/GUIDELINES.md) |

## Shared foundation

All three sub-galleries share one primitive: **the Buzzvil mark masked with an animated pattern, painted by three colour tokens**.

- A **pattern** is the universal shape primitive. Lives in `patterns/`. Paints with `var(--c-bg)`, `var(--c-mid)`, `var(--c-acc)`.
- A **hero** composes that primitive into a page-specific story by adding one focal motion layer. Lives in `heroes/`.
- A **palette** is the named triple that drives `--c-bg / --c-mid / --c-acc` everywhere. Lives in `palettes/palettes.js`. The switcher at the top of every page applies the active palette to every visible composition simultaneously.

This means: **a hero PR that swaps in a new `comp-*` pattern should land in `patterns/`, not in `heroes/`.** The pattern gets its own card in the patterns gallery and becomes available to every hero. A hero PR is about the motion layer (orbit, cursor demo, swarm, etc.), not about the pattern beneath. Likewise, a hero or pattern PR that needs a new colour combination should land the palette in `palettes/palettes.js` first, then reference it.

## Shared rules

- **Three palette tokens, sourced per the chameleon rule.** `--c-bg`, `--c-mid`, `--c-acc`. On a solution page the palette comes from the top 3 partners in that solution; on landing / culture surfaces it comes from the Buzzvil brand palette; pillar pages use a single-anchor hue per pillar. Full rule in [`palettes/GUIDELINES.md`](./palettes/GUIDELINES.md).
- **OKLCH for palette values.** The design system enforces OKLCH. Hex equivalents go in a trailing comment for human reference, not as the actual value.
- **No hard-coded colours inside `comp-*` symbols.** Motion-layer decoration in heroes can use literal colours, but they must come from the same three-token palette the pattern is using, no fourth colour.
- **Animation runs on SVG SMIL or CSS keyframes.** JS is reserved for cases where neither expresses the motion (e.g. arc-length-parameterised traveler on `hero-landing-orbit`).
- **Honour `prefers-reduced-motion`.** Patterns stay (structural); focal hero motions freeze on a representative still frame.

## Contribution flow

Same shape for all three sub-galleries. Detailed per-type steps are in [`AGENTS.md`](./AGENTS.md).

1. Read this file + the sub-gallery's `GUIDELINES.md`.
2. Open `AGENTS.md` and follow the per-type "Adding a new …" section.
3. Open a PR. The template at `.github/PULL_REQUEST_TEMPLATE.md` pre-fills the per-type checklist.
4. Open a tracking issue with the right label (`pattern-vote` / `hero-vote` / `palette-vote`) for the vote counter.

Reviewer (Max) merges if the entry reads cleanly, follows the contract, and the deploy preview confirms it doesn't break the switcher or break adjacent cards.

## Credit

All sub-galleries credit every author on every card. When updating someone else's entry, **append yourself to the credit line**, don't replace. List every contributor in the chain. Full rule in each gallery's `GUIDELINES.md`.