# Pattern design guidelines Every pattern in this repo follows the same structural contract. This document is the rule sheet, a PR that breaks one of these is going to ask for changes. ## The contract Each pattern is an SVG `` with: - **`viewBox="0 0 100 100"`**, fixed. The pattern is a 100-unit square. It will be scaled to fit whatever container it lands in. - **`preserveAspectRatio="xMidYMid slice"`**, the pattern is intended to fill (cover) its target, not letterbox. - **An `id` starting with `comp-`**, `comp-squares`, `comp-hex`, etc. Pick a single English word that describes the visual. The pattern is referenced via `` from the gallery, and from buzzvil.com pages. Same symbol drives every surface. ## The three palette tokens A pattern must paint with exactly three colour tokens, named: | Token | Role | Where it typically lands | |---|---|---| | `var(--c-bg)` | **Background.** Largest area, lowest visual energy. | The 100×100 backing rect. | | `var(--c-mid)` | **Mid.** The pattern's bulk, the shape that carries the form. | Largest or secondary shapes. | | `var(--c-acc)` | **Accent.** The detail / focal, small but distinctive. | Smallest shapes, brightest hits. | Hard-coded colour values are **not allowed**. Every fill must be one of the three tokens (or use `opacity` on a token). The reason: a single pattern needs to render in many palettes, swapped at the call site. ### Where the colours come from (the chameleon rule) The same pattern lives on many surfaces, and the surface decides the colours: - **On a solution page or category surface**, colours are pulled from (or *inspired by*) the **major partners we have in that area**. - Drive Sales → Naver Shopping green, Olive Young olive, Musinsa black. - Acquire Users → NetMarble purple, Krafton gold, NCSoft red. - Build Brand → Samsung blue, Hyundai navy, LG red. - Boost Engagement → Toss blue, KakaoBank dark, Kakao yellow. - Monetize → Buzzvil red palette (publisher-side, anchored to our own brand). - **On the homepage, the culture page, or any brand-anchor surface**, colours come from **Buzzvil's brand palette** (cherry / warm orange / hot pink today, but the brand-anchor palette is the source of truth, not the values I just listed). - **The brand palette is not fully defined yet at this stage.** It follows the **chameleon logic** in [design.buzzvil.com](https://design.buzzvil.com)'s brand guidelines, Buzzvil adapts its hue to context while keeping the same structural rhythm. When in doubt, check there. When still in doubt, ask Max. What this means for pattern design: design with **structure first**. If the composition only works in the original palette, it's colour-dependent rather than structural, refine. A good pattern should hold its visual logic in any 3-colour split. Example fill snippets that are **OK**: ```svg ``` **Not OK** (rejection target): ```svg ``` ## Composition Each pattern should compose **2-4 shapes** that read as a unit. Avoid: - Single-shape patterns (boring at logo scale) - Heavy detail (>5 shapes, pattern loses identity when masked) - Solid horizontal/vertical fills (looks like a colour bar, not a pattern) The pattern needs to read on **two very different shapes**: 1. The **Buzzvil mark**, thin letterforms, lots of negative space. Pattern must hold up when sliced through 9-12px text strokes. 2. The **morphing blob**, a large, soft, slowly changing organic shape. Pattern fills most of the space. Test both before submitting. If the pattern only reads on one, it's not ready. ## Animation Every pattern animates. The motion should feel calm, deliberate, and continuous, not flashy. - **Slow durations.** Each animated shape should loop in **24-120 seconds**. Three concurrent animations at 24s, 60s, 120s create a non-repeating feel without being twitchy. - **`repeatCount="indefinite"`**, patterns loop forever. - **Pure SVG SMIL animations preferred.** ``, ``. Keep CSS animations out, they don't compose cleanly when the same symbol renders in multiple places. - **No motion blur, filters, or gradients-of-gradients.** Performance budget is roughly "renders smoothly on a 2018 phone with the pattern repeated 4× on a page." Stick to fills + transforms. Acceptable animation primitives: - `transform="rotate"` on individual shapes (most common) - `transform="translate"` for drift effects - `animate` on `r` (radius), `d` (path), `x/y/cx/cy` - `animateMotion` for path-following, rare for patterns, fine if it stays calm If you need a ``, you're probably overbuilding. ## Reads A good pattern test, in this order: 1. **Identity test.** Cover the pattern's name. Can you describe what it is in one word? (Squares. Stripes. Hex. Circles.) If not, it's not a pattern, it's a composition. 2. **Mark test.** Render through `mask="url(#m-logo)"`. Does the pattern still read? Letters shouldn't disappear into noise. 3. **Blob test.** Render through `mask="url(#m-blob)"`. Does the pattern feel alive in the breathing shape? Does it complement the blob's morphing, or fight it? 4. **Palette test.** Swap to three completely different colours (e.g. Samsung blue + Hyundai navy + LG red). Does the visual logic still work? If only the original colours look good, the composition is colour-dependent rather than structural, refine. 5. **Pause test.** Pause the animation (DevTools). Is the still frame interesting? Patterns shouldn't lean entirely on motion to justify themselves. ## What counts as a new entry **Shape AND animation together define an entry.** Two patterns that share the same shape composition but animate differently are two separate entries, not one. A new pulse on existing hexagons is a new pattern. A rotating-vs-translating variant of the same triangle composition is two patterns. This means contributing isn't limited to inventing new shapes, finding a fresh motion on an existing shape family is just as valid a contribution. Name accordingly so it's clear what changed. ## Naming - `comp-` prefix on the symbol id. - For a brand-new shape: one word, lowercase, no hyphens inside the word, `comp-waves`, `comp-grid`, `comp-petals`. Pick a noun that describes the shape, not the feeling. `comp-waves` ✓. `comp-calm` ✗. - For a motion variant of an existing shape: `comp-{shape}-{motion}`, e.g. `comp-hex-pulse` for hexagons that pulse instead of rotate, `comp-stripes-scroll` for stripes that translate continuously instead of drifting in place. - The first version of each shape family doesn't need the motion suffix; later variants add it. `comp-circles` is the breathing original; if you ship a rotating variant, name it `comp-circles-rotate`. ## Credit Every pattern card carries its author. When you add a gallery card, include yourself in the head section: ```html by @your-handle ``` That's how credit shows up next to the comp-id on the gallery. Use your GitHub handle so the link lands on your profile. ### Updates to an existing pattern keep every contributor's name If you refine someone else's pattern (animation timing, shape proportions, motion variant), **don't replace the original author**. Append yourself to the credit line so both names show: ```html by @mmaxence, updated by @your-handle ``` If a third or fourth update lands, **list every author**, don't collapse to "and others" or use ellipses. Original creator first, then each updater in the order their changes landed: ```html by @mmaxence, updated by @joy, @mido and @elle ``` Comma-separate everyone in the update chain, with "and" before the last one. Each person who shaped the pattern gets visible credit on the gallery, regardless of how long the chain grows. If your change is so different in shape AND motion that it's effectively a new pattern (see [What counts as a new entry](#what-counts-as-a-new-entry)), don't update, open a new entry with its own author line. ## What we're looking for Good additions to the existing six: - **Geometric**, grids, ribbons, blocks, segments - **Organic**, petals, leaves, droplets, ribbons of varying width - **Structural**, lines, weaves, nets, bridges - **Cellular**, cells, modules, packed shapes (Voronoi-ish without the math) Avoid: - Anything tied to a specific brand (would fail palette test) - Anything photorealistic (won't read masked) - Anything reliant on >3 colours - Anything with heavy filters / blends / gradients ## The PR When you open a PR, the template will pre-fill a checklist. Before merging, the pattern lives on a deploy preview. Reviewer (Max) walks it, gives notes if any, or merges. Once merged, the pattern is available to use across buzzvil.com surfaces.