# Wine Chips — Brand Contract

This file is the machine-readable brand contract for **Wine Chips**. An agent that builds anything for this brand — a page, a deck, a PDF, an email, a component — applies it exactly.

| Field | Value |
|---|---|
| Brand | `winechips` |
| Brand name | Wine Chips |
| Company | `winechips` |
| Website | https://winechips.com |
| Theme | `editorial` |
| Channel | `stable` |
| Version | 1 |
| Pointer seq | 1 |
| Manifest sha256 | `c41cd892512feab624e0c1ae662071062092f9b2bff55f510692e43cb0232db1` |
| Signing key id | `winechips-20262108` |
| Guide schema | 2 |
| Generated at | 2026-09-07T21:52:11Z |
| Canonical URL | https://brandguide.winechips.com/api/public/v1/agent.md |

**Machine-readable siblings**

| File | URL |
|---|---|
| Discovery | https://brandguide.winechips.com/api/public/v1/.well-known/styleguide.json |
| This contract | https://brandguide.winechips.com/api/public/v1/agent.md |
| This contract (llms.txt) | https://brandguide.winechips.com/api/public/v1/llms.txt |
| Effective guide | https://brandguide.winechips.com/api/public/v1/effective.json |
| Signed manifest | https://brandguide.winechips.com/api/public/v1/manifest.json |
| Stylesheet (normative) | https://brandguide.winechips.com/api/public/v1/brand.css |
| Stylesheet (descriptive) | https://brandguide.winechips.com/api/public/v1/brand.descriptive.css |
| Tailwind v4 theme | https://brandguide.winechips.com/api/public/v1/tokens.tailwind.css |
| Design tokens (DTCG) | https://brandguide.winechips.com/api/public/v1/tokens.dtcg.json |
| Brand book (PDF) | https://brandguide.winechips.com/api/public/v1/guide.pdf |
| Asset bytes | `https://brandguide.winechips.com/api/public/v1/assets/<sha256>` |
| Logo redirect | `https://brandguide.winechips.com/api/public/v1/logo/<asset id>` |

## 1. Protocol

1. **Fetch this file** from `https://brandguide.winechips.com/api/public/v1/agent.md` at the start of the work. Do not rely on a copy in your context, in a cached repo, or in your memory.
2. **Pin the version you built against.** This contract is Wine Chips **v1**, manifest `c41cd892512feab624e0c1ae662071062092f9b2bff55f510692e43cb0232db1`. Record both in your output.
3. **Apply §2–§9 exactly.** They are not suggestions and not defaults; they are the brand.
4. **Never invent a value.** No colour, size, face, duration, radius, easing, spacing step or asset that is not listed in this file exists for this brand.
5. **If a value you need is missing, STOP and request it.** Ask the brand owner, or raise an overlay request against this master. Never approximate, never pick "something close", never sample a colour out of a screenshot.
6. **Report the manifest sha you built against** in your final message (see §10).
7. **Run the verification in §10 before declaring the work done.** "It looks right" is not a result.
8. **This tier is read-only.** There is no write path here. Changes to the brand happen only in the style-guide master, by a human.

**Other non-negotiables declared by this brand**

| Category | Rule |
|---|---|
| Voice | The founder story keeps its jokes. Product copy does not make health, diet or wellness claims, and the press strip names only real placements. |
| Governance | This guide is DESCRIPTIVE and PROVISIONAL: it documents what the live storefront and the internal tools ship today. Nothing here is ratified brand law until the owner closes gate D-WC1. |
| Governance | Rally, the Private Reserve Club and DaVinci are not yet decided sub-brands. Until D-WC2 is ruled they are consumers of this brand, not brands of their own. |
| Governance | Print builds are unspecified. No Pantone, CMYK or RAL value exists anywhere in the fleet for any Wine Chips colour, and none has been invented here. |

## 2. Identity and voice

**Positioning.** Wine Chips is a premium lattice-cut potato chip engineered for one job: to be eaten with wine. Invented in 2017 in Paw Paw, Michigan by people who wanted cheese and wine in the same hand, it is sold direct on winechips.com, through the Private Reserve Club subscription, through the Rally fundraising programme, and through wholesale and partner channels.

**Emotion.** Simply delicious, paired perfection.

**Customer.** Wine drinkers who entertain — home hosts, club members, tasting rooms, gift buyers, and the fundraising organisers and sellers who move the product through Rally. They are buying a moment with a bottle open, not a nutrition panel.

**The tension**

| Pole | Traits |
|---|---|
| Vinous | premium, considered, cellar-dark, grown-up |
| Snackable | bold, cheesy, loud, unserious |

**Personality**

- Warm and unpretentious — a wine brand that refuses to be precious about wine
- Bold in flavour language: boldest, cheesiest, most satisfying
- Founder-voiced — the story is told in the first person plural, with the joke left in
- Appetite-first: the product is food before it is a lifestyle
- Generous — clubs, fundraisers and partners are all invitations, not funnels
- Confident about craft (lattice-cut, small batch) without a tasting-note vocabulary

**Signature moves**

| Name | What it is |
|---|---|
| The wine rail | A full-bleed wine-red (#A6192E) announcement bar at the top of every page, white 16px Arvo, that carries the current flavour or offer. It is the only place the brand shouts. |
| The wine-to-plum gradient | linear-gradient(90deg, rgba(166,25,46,1) 0%, rgba(81,42,68,1) 100%) — the horizontal band behind a club, testimonial or partner section. Wine on the left, plum on the right, always 90deg, never reversed. |
| The cream band | A #FBF3DA section ground used for logo lists, press strips and 'as seen on' rails — the only warm ground in the system and the only alternative to white. |
| Caps with air | Section headings are Arvo 400 in uppercase at 0.1em tracking; nav and buttons are Montserrat with 1px letter-spacing. Nothing in the brand is set in sentence case above body size. |
| The plum ink | Body copy, links, footer text and the wordmark are all one colour — plum #512A44. The brand reads as a single ink, not as a grey ramp. |
| The 2px corner | Buttons, inputs and cards carry a 2px radius — almost square. Roundness in this brand is a 25px pill or a full circle, never a soft 8px corner. |

**Visual references**

- The plum wordmark on white — a single-ink lettering mark, never recoloured outside the two shipped cuts
- A white page with a plum-tinted wash and one cream band, punctuated by a wine-red announcement rail
- The wine → plum horizontal gradient behind a testimonial or club band
- Arvo slab headings in caps over Montserrat body copy — the storefront's own pairing
- Product photography of tubes and lattice chips against warm neutral grounds

**Feels / never feels**

| Always feels | Never feels |
|---|---|
| Appetising | Clinical |
| Warm | Corporate-beige |
| Convivial | Sommelier-snobbish |
| Premium but relaxed | Cold or minimal for its own sake |
| Handmade | Diet-food |
| Bold | Like a generic Shopify theme with a logo dropped in |
| Celebratory | — |
| Midwestern-direct | — |

**Voice principles**

- Lead with appetite. Flavour and occasion come before provenance, and provenance before process.
- Favour: bold · cheesy · satisfying · lattice-cut · paired · snackable · dip-able · designed exclusively for wine · try every bold flavour.
- Avoid: tasting-note vocabulary, sommelier register, diet and wellness claims, and any health or nutrition claim the label does not carry.
- Keep the joke in. The founder story is funny on purpose and the copy does not edit the humour out.
- Second person for the shopper, first person plural for the company. 'We made Wine Chips because we love wine and we love cheese.'
- Never imply an award, rating or press mention the brand does not hold; the press strip names only real placements.
- American spelling throughout — the storefront, the labels and the fundraising platform are all US.

**Capitalization**

- Section headings (h2–h6) are UPPERCASE with 0.1em tracking — that is a type rule, not a copy rule, and the copy is written in sentence case in the CMS.
- The hero headline is typed in caps in the source and stays that way.
- Buttons and navigation are uppercase with 1px letter-spacing.
- Product and flavour names are Title Case: Hawaiian Luau, Private Reserve Club.
- The brand is two words with a capital C: Wine Chips. Never WineChips outside a file name, a handle (@winechips) or a domain.
- Body copy is sentence case. h1 is the one heading level that is NOT transformed to uppercase by the stylesheet.

**Microcopy — copy these registers, do not invent new ones**

| Context | Example |
|---|---|
| Home hero headline | THE BOLDEST, CHEESIEST, EASIEST, MOST SATISFYING WINE SNACK YOU'LL EVER HAVE |
| Meta description / search snippet | The Boldest, Easiest, Most Satisfying Potato Chip You'll Ever Have. Wine Chips are the Only Chip Designed Exclusively for Wine. Try Every Bold Flavor! |
| Announcement rail | ⏰ OUR NEW FLAVOR: HAWAIIAN LUAU 🏝️ |
| Product category heading | PREMIUM LATTICE-CUT CHIPS |
| Merchandising heading | TODAY'S POPULAR ITEMS & GIFTABLES |
| Collections heading | COLLECTIONS |
| Press / event band | THE ASPEN FOOD & WINE CLASSIC |
| Our Story eyebrow | SIMPLY DELICIOUS, PAIRED PERFECTION. |
| Our Story heading | MADE WITH LOVE, WHILE DRINKING WINE |
| Our Story heading (second) | BOLD, CHEESY & SATISFYING! |
| Founder story, opening | We made Wine Chips because we love wine and we love cheese (who doesn't?) but realized that putting the cheese IN the wine was a bad idea for both. |
| Founder story, the wish | So one evening in 2017, over a glass of wine (ok maybe two), we wished for something simple, portable, dip-able, endlessly snack-able, cheese-ladened and delicious. |
| Founder story, the payoff | And just like that (ok, it took a lot of work, a lot of samples, a lot of wine and the dedication of more than a few passionate oenophiles, exuberant chip connoisseurs and mildly lazy party guests) the wine chip was born. |
| Primary CTA | SHOP NOW |
| Secondary CTA | OUR STORY |
| Newsletter heading | JOIN THE COMMUNITY |
| Newsletter submit | Subscribe |
| Primary navigation | OUR STORY · PARTNERS · SHOP · PRIVATE RESERVE CLUB |
| Cart drawer heading | Just added to your cart |
| Cart drawer actions | View cart · Continue shopping |
| Support address | hello@winechips.com |
| Registered address | Wine Chips, Inc. · 61675 M 40 · Paw Paw, MI 49079 |
| Rally fundraising tagline (wc-fundraiser-platform email templates) | Premium snacks. Real fundraising. |
| Slideshow assistive text | Use left/right arrows to navigate the slideshow or swipe left/right if using a mobile device |
| Variant select assistive text | Choosing a selection results in a full page refresh. Press the space key then arrow keys to make a selection. |

**Registers**

| Register | Principles |
|---|---|
| Storefront and campaign | Appetite first, then occasion, then provenance.; Caps headings, generous air, one wine-red signal per screen.; The founder voice is allowed to be funny; product copy is not. |
| Internal tools | Terse and literal. A row label is a noun; an action is a verb.; Never uppercase a data value, an order number, an email address or a customer's name.; State the count and the unit: '12 open', not 'several tickets'.; Destructive actions name what will be lost before they ask. |


## 3. Colour

### Storefront

The white page the shop, the story, the club and the campaign pages are built on: one plum ink, one wine-red signal, a plum-tinted wash and a cream band.

Ground token: `--wc-surface`.

| Token | Role | Storefront (light) | Print build |
|---|---|---|---|
| `--wc-plum` | The brand ink and the wordmark colour | #512A44 | — |
| `--wc-wine` | The single signal accent | #A6192E | — |
| `--wc-wine-bright` | The wine at hover | #DA213C | — |
| `--wc-plum-light` | Plum at focus | #83446E | — |
| `--wc-cream` | The warm ground | #FBF3DA | — |
| `--wc-white` | Paper | #FFFFFF | — |
| `--wc-graphite` | The shipped neutral action fill | #3A3A3A | — |
| `--wc-graphite-deep` | Graphite pressed | #212121 | — |
| `--wc-surface` | The page | #FFFFFF | — |
| `--wc-surface-alt` | The wash — feature rows, the footer, alternating sections | #F6F4F5 | — |
| `--wc-surface-warm` | The cream band — logo lists, press strips, 'as seen on' | #FBF3DA | — |
| `--wc-ink` | Body copy, headings, links, the wordmark | #512A44 | — |
| `--wc-ink-muted` | The footer's secondary ink | #333232 | — |
| `--wc-ink-dim` | Footer link hover, meta text | #5A5858 | — |
| `--wc-on-ink` | Ink on a plum or graphite fill | #FFFFFF | — |
| `--wc-accent` | The signal — announcement rail, primary button, active nav | #A6192E | — |
| `--wc-accent-hover` | The signal at hover | #DA213C | — |
| `--wc-on-accent` | Label on the signal | #FFFFFF | — |
| `--wc-link` | A link at rest — the same plum as body copy | #512A44 | — |
| `--wc-link-hover` | A link at hover and focus | #83446E | — |
| `--wc-action` | The neutral button fill the theme still ships | #3A3A3A | — |
| `--wc-action-hover` | The neutral button at hover | #606060 | — |
| `--wc-on-action` | Label on the neutral fill | #FFFFFF | — |
| `--wc-border` | The default hairline | #EBEBEB | — |
| `--wc-border-form` | A control edge | #CCCCCC | — |
| `--wc-border-strong` | A control edge, emphasised | #B3B3B3 | — |
| `--wc-hairline-footer` | The footer rule | #DFD8DC | — |
| `--wc-fill-subtle` | The lightest plum wash | rgba(81, 42, 68, 0.05) | — |
| `--wc-fill-soft` | A plum wash — empty states, chips | rgba(81, 42, 68, 0.10) | — |
| `--wc-fill-strong` | A plum wash, emphasised | rgba(81, 42, 68, 0.20) | — |
| `--wc-focus-ring` | The focus halo | rgba(81, 42, 68, 0.25) | — |
| `--wc-positive` | Success fill and rule | #1F873D | — |
| `--wc-positive-ink` | Success as small text | #1D7E39 | — |
| `--wc-positive-bg` | Success message ground | #F8FFF9 | — |
| `--wc-negative` | Error fill, rule and ink | #D20000 | — |
| `--wc-negative-ink` | Error message body copy | #651818 | — |
| `--wc-negative-bg` | Error message ground | #FFF8F8 | — |
| `--wc-sale` | The sale price | #EA0606 | — |
| `--wc-sale-ink` | The sale price as small text | #DD0606 | — |
| `--wc-in-stock` | The in-stock mark | #00730B | — |
| `--font-display` | The heading face — Arvo | Arvo, Rockwell, 'Roboto Slab', Georgia, serif | — |
| `--font-sans` | The UI and body face — Montserrat | Montserrat, 'Helvetica Neue', Helvetica, Arial, sans-serif | — |

### Plum block

A section that deliberately runs dark on a light site: the plum ground, the wine band and the wine-to-plum gradient the club, testimonial and partner sections are built on. Mount .wc-on-plum and every role token remaps; no component is recoloured by hand.

Ground token: `--wc-surface`.

| Token | Role | Storefront (light) | Print build |
|---|---|---|---|
| `--wc-surface` | The plum block | #512A44 | — |
| `--wc-surface-alt` | One step out of the block | #5E314F | — |
| `--wc-surface-warm` | The wine band — the right-hand stop of the signature gradient | #A6192E | — |
| `--wc-ink` | Body copy and headings on a plum block | #FAF6F9 | — |
| `--wc-ink-muted` | Secondary ink on a plum block | #E2D4DE | — |
| `--wc-ink-dim` | Meta ink on a plum block | #DAC8D4 | — |
| `--wc-on-ink` | Ink on a light fill inside a plum block | #512A44 | — |
| `--wc-accent` | The signal on a plum block — the cream, not the wine | #FBF3DA | — |
| `--wc-accent-hover` | The signal at hover | #FFFFFF | — |
| `--wc-on-accent` | Label on the cream signal | #512A44 | — |
| `--wc-link` | A link on a plum block | #FAF6F9 | — |
| `--wc-link-hover` | A link at hover on a plum block | #FBF3DA | — |
| `--wc-action` | The outline button the storefront ships on dark art | #FFFFFF | — |
| `--wc-action-hover` | That outline at hover | #FBF3DA | — |
| `--wc-on-action` | Ink inside a knocked-out button once it fills | #512A44 | — |
| `--wc-border` | Hairline on a plum block | rgba(250, 246, 249, 0.16) | — |
| `--wc-border-form` | Control edge on a plum block | rgba(250, 246, 249, 0.32) | — |
| `--wc-border-strong` | Emphasised edge on a plum block | rgba(250, 246, 249, 0.55) | — |
| `--wc-hairline-footer` | Rule on a plum block | rgba(250, 246, 249, 0.20) | — |
| `--wc-fill-subtle` | Lightest wash on a plum block | rgba(250, 246, 249, 0.05) | — |
| `--wc-fill-soft` | Wash on a plum block | rgba(250, 246, 249, 0.10) | — |
| `--wc-fill-strong` | Emphasised wash on a plum block | rgba(250, 246, 249, 0.20) | — |
| `--wc-focus-ring` | The focus halo on a plum block | rgba(251, 243, 218, 0.55) | — |
| `--wc-positive-ink` | Success as text on a plum block | #8FE6A8 | — |
| `--wc-negative` | Error on a plum block | #FFBDBD | — |
| `--wc-negative-ink` | Error body copy on a plum block | #FFE1E1 | — |
| `--wc-negative-bg` | Error ground on a plum block | #531313 | — |
| `--wc-sale-ink` | The sale price on a plum block | #FFBEBE | — |
| `--wc-in-stock` | The in-stock mark on a plum block | #8FE6A8 | — |

### Contrast pairs (mandatory)

Algorithm: `wcag21`. Every pair below must meet its minimum in every mode. A combination that misses is a defect, not a judgement call.

| Ink | Grounds | Min ratio | Warn floor |
|---|---|---|---|
| `--wc-ink` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 7 | — |
| `--wc-ink-muted` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-ink-dim` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-on-ink` | `--wc-ink` | 7 | — |
| `--wc-accent` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-on-accent` | `--wc-accent`, `--wc-accent-hover` | 4.5 | — |
| `--wc-link-hover` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-on-action` | `--wc-action` | 4.5 | — |
| `--wc-positive-ink` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-negative` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-negative-ink` | `--wc-negative-bg` | 4.5 | — |
| `--wc-sale-ink` | `--wc-surface`, `--wc-surface-alt`, `--wc-surface-warm` | 4.5 | — |
| `--wc-in-stock` | `--wc-surface`, `--wc-surface-alt` | 4.5 | — |

### Banned values

| Id | Severity | Kind | Match | Why |
|---|---|---|---|---|
| offpalette-neutral | warn | neutral-grey | lightnessRange=[0.15, 0.9] maxChannelSpread=10 | The storefront ships eight near-neutrals that were never derived from the plum. They are declared as tokens here so the set is CLOSED; a ninth grey anywhere is off-palette, and the plum-tinted washes (--wc-fill-*, --border) are the right reach instead. |
| legacy-tailwind-neutral | warn | regex | #(?:[eE]5[eE]5[eE]5\|[fF]5[fF]5[fF]5\|[fF][aA][fF][aA][fF][aA]\|[dD]4[dD]4[dD]4\|[aA]3[aA]3[aA]3\|737373\|525252\|404040\|262626\|171717\|[fF]8[fF][aA][fF][cC]\|[fF]1[fF]5[fF]9\|[eE]2[eE]8[fF]0\|[cC][bB][dD]5[eE]1\|94[aA]3[bB]8\|475569\|0[fF]172[aA])\b | The stock Tailwind and slate ramps. They are the template scaffold and the wc-gorgias reskin, not Wine Chips; the operator register replaces them role for role. |
| foreign-wine | warn | regex | #(?:7[cC]2[dD]3[eE]\|722[fF]37\|7[fF]1[dD]1[dD]\|5[eE]1[fF]2[eE]\|3[cC]121[cC]\|1[aA]0[dD]12\|2[aA]0[eE]16\|4[aA]1[cC]22\|9[bB]4[dD]54\|[bB]5485[eE]\|502[cC]2[dD]\|522[aA]44)\b | The five burgundies and the two off-by-one plums that internal tools invented independently (Rally #7c2d3e and its four hardcoded darks, PRC #722F37, wc-eos #7f1d1d, the print system's #502c2d, and the Rally logo export's #522A44). None is a Wine Chips colour; the brand plum is #512A44 (decision W-1). |
| foreign-gold | warn | regex | #(?:[cC]5943[aA]\|[cC]9[aA]84[cC]\|[eE]8[dD]5[aA]3\|[fF]5[cC]84[cC]\|[dD]4[aA]849\|[eE]8[cC]468)\b | Gold is not a Wine Chips colour. It exists only inside Rally and the Private Reserve Club and has no storefront, packaging or artwork source (decision W-1). |
| foreign-accent | warn | property-value | ^(?!#(?:[Aa]6192[Ee]\|[Ee]44[Ee]64\|[Ff][Bb][Ff]3[Dd][Aa])$).*$ | Wine is the single signal. The only values this slot may carry are #A6192E (light), #E44E64 (the operator register's dark cut) and #FBF3DA (the cream, which is the signal on a plum ground). A second accent hue is a fork of the brand, not a theme. |

### Colour rules

- Plum #512A44 is the brand's single ink. Body copy, links, footer text, social marks and the wordmark are all plum; the brand does not run a grey text ramp.
- Wine red #A6192E is the ONE signal accent: the announcement rail, the primary button, the newsletter submit, the active nav item. There is never a second accent hue.
- Cream #FBF3DA is a GROUND, never an ink and never a fill on a control. It is the section band for logo lists, press strips and 'as seen on' rails.
- Burgundy #7C2D3E, #722F37 and #7F1D1D are NOT Wine Chips. Three internal tools independently invented them; no artwork, no packaging and no live storefront surface uses any of the three (decision W-1).
- Gold #C5943A / #C9A84C is not a Wine Chips brand colour. It appears only inside two internal tools and has no storefront or packaging source (decision W-1).
- A dark region is entered by mounting .wc-on-plum (or the operator register's dark mode), which remaps every role token. Components are never recoloured by hand for a plum ground.
- On a plum or wine ground the signal is CREAM, not wine — wine on plum is 1.9:1 and cannot carry meaning. --wc-accent resolves to #FBF3DA on the inverted surface for exactly this reason.
- Status colour is never the only channel. A success, a warning or an error carries an icon or a word as well as its hue.


## 4. Typography

### Faces

| Role token | Family | Weights | Italics | Used for | Licence | Redistributable | File |
|---|---|---|---|---|---|---|---|
| `--font-display` | Arvo | 400 only on the storefront (arvo_n4). The packaging toolchain also loads a 700 cut, which the web does not. | no | Every heading level, the announcement rail, and nothing else. Arvo is the brand's voice at size; it never sets body copy, UI labels or a data value. | Anton Koovit — The binary's own name table records 'Copyright (c) 2010 Anton Koovit.' and a licence URL of http://www.korkork.com/license/arvo/; the upstream Google Fonts distribution of Arvo is SIL Open Font License 1.1, and OS/2 fsType is 0 (installable embedding, no restriction). Confirm the licence line with the owner — D-WC1, item 5. | yes | https://brandguide.winechips.com/api/public/v1/assets/af9a85531f3f742a38ed066e50591a98a8a36b952e9ccb6b8117dcc42713a777 |
| `--font-sans` | Montserrat | 400 and 700. --font-weight-body is 400; --font-weight-body--bold and --font-weight-body--bolder are both 700, so the storefront has no 500 or 600 cut loaded and the nav's font-weight: 600 renders as a synthesised weight. | yes | Body copy, product copy, buttons, navigation, form fields, prices, legal text, and every word of the operator register. | The Montserrat Project Authors — SIL Open Font License 1.1, declared in the binary's own name table; OS/2 fsType is 0. Free to use, embed and redistribute with the licence. | yes | https://brandguide.winechips.com/api/public/v1/assets/c0ec39d77c456f49c6434f667679bbfcbf75ca15bc70adb159bbf54c8ce5d7ec |

A face whose licence is **not** redistributable is never bundled and never self-hosted by a consumer: license it yourself or fall back to the next family in the stack.

**Font stacks — use verbatim**

| Role token | font-family |
|---|---|
| `--font-display` | `Arvo, Rockwell, 'Roboto Slab', Georgia, serif` |
| `--font-sans` | `Montserrat, 'Helvetica Neue', Helvetica, Arial, sans-serif` |

### Scale

`pt` is `px × 0.75` — use it for print and decks.

| Token | Size | Used by |
|---|---|---|
| `--wc-text-base` | 14px · 0.875rem · 10.5pt | body, button, input, select, textarea — the storefront's --font-size-base, at line-height 1.5 |
| `--wc-text-h1` | 48px / 45px | h1 and .h1 — desktop / below 750px. Arvo 400, line-height 1.2, letter-spacing 0, case untransformed |
| `--wc-text-h2` | 28px / 25px | h2 and .h2 — the section heading. Arvo 400 UPPERCASE, 0.1em tracking, line-height 1.2 |
| `--wc-text-h3` | 36px / 28px | h3 — --font-size-header desktop, --font-h3-mobile below 750px |
| `--wc-text-h4` | 24px / 22px | h4 — the newsletter and footer column headings |
| `--wc-text-h5` | 20px / 18px | h5 |
| `--wc-text-h6` | 19px / 17px | h6 — the smallest heading in the system, and the type floor for Arvo |
| `--wc-text-mega` | 90px · 5.625rem · 67.5pt | --font-mega-title-large-desktop — the slideshow's largest headline cut, desktop only |
| `--wc-text-lead` | 16px · 1rem · 12pt | --font-rich-text-large, and the announcement rail message |
| `--wc-text-small` | 12px · 0.75rem · 9pt | --font-rich-text-small, legal and meta copy — the type floor |
| `--wc-text-pagination` | 15px · 0.9375rem · 11.25pt | .pagination |
| `--wc-tracking-heading` | 0.1em | h2–h6 uppercase headings |
| `--wc-tracking-ui` | 1px · 0.0625rem · 0.75pt | .btn, #SiteNav — uppercase buttons and navigation |
| `--wc-leading-body` | 1.5 | body, input, textarea, select |
| `--wc-leading-heading` | 1.2 | h1–h6 |
| `--wc-space-heading` | 17.5px · 1.0938rem · 13.125pt | the bottom margin of every heading |
| `--wc-space-paragraph` | 19.444px · 1.2152rem · 14.583pt | the bottom margin of a paragraph |

### Specimens

| Name | Spec | Voice | Sample |
|---|---|---|---|
| Hero headline | Arvo 400 · 48px desktop / 45px mobile · line-height 1.2 · tracking 0 · case untransformed (the copy is typed in caps) | display | THE BOLDEST, CHEESIEST, EASIEST, MOST SATISFYING WINE SNACK YOU'LL EVER HAVE |
| Mega slideshow headline | Arvo 400 · 90px · desktop only · the slideshow's largest cut | display | SIMPLY DELICIOUS |
| Section heading | Arvo 400 · 28px desktop / 25px mobile · UPPERCASE · tracking 0.1em · line-height 1.2 | caps | PREMIUM LATTICE-CUT CHIPS |
| Sub-section heading | Arvo 400 · 36px desktop / 28px mobile · UPPERCASE · tracking 0.1em | caps | MADE WITH LOVE, WHILE DRINKING WINE |
| Column heading | Arvo 400 · 24px desktop / 22px mobile · UPPERCASE · tracking 0.1em | caps | JOIN THE COMMUNITY |
| Smallest heading | Arvo 400 · 19px desktop / 17px mobile · UPPERCASE · tracking 0.1em — the heading floor | caps | COLLECTIONS |
| Announcement rail | Arvo 400 · 16px · white on wine · padding 11px 22px (55px inline above 750px) | caps | OUR NEW FLAVOR: HAWAIIAN LUAU |
| Body copy | Montserrat 400 · 14px · line-height 1.5 · plum · 19.444px bottom margin | prose | We made Wine Chips because we love wine and we love cheese (who doesn't?) but realized that putting the cheese IN the wine was a bad idea for both. |
| Lead / rich text large | Montserrat 400 · 16px · line-height 1.5 | prose | So one evening in 2017, over a glass of wine (ok maybe two), we wished for something simple, portable, dip-able, endlessly snack-able, cheese-ladened and delicious. |
| Button label | Montserrat 700 · 14px · UPPERCASE · tracking 1px · padding 10px 18px · radius 2px | caps | SHOP NOW |
| Navigation | Montserrat · 14px · UPPERCASE · tracking 1px · padding 4px 15px 5px. The theme asks for weight 600, which is not a loaded cut — see drift. | caps | OUR STORY · PARTNERS · SHOP · PRIVATE RESERVE CLUB |
| Price | Montserrat 400 · 14px · plum; a sale price is --wc-sale-ink and the regular price is struck through | prose | $14.00 |
| Meta and legal | Montserrat 400 · 12px · --wc-ink-dim — the type floor | prose | Wine Chips, Inc. · 61675 M 40 · Paw Paw, MI 49079 |
| Form message | Montserrat 400 · 14px · --wc-negative-ink on --wc-negative-bg inside a 1px --wc-negative rule, padding 1rem 1.3rem | prose | Please enter a valid email address. |

### Typography rules

- Two families, two jobs. Arvo sets every heading; Montserrat sets every other word. There is no third face and no display alternate.
- Type floor is 12px in both registers; the heading floor is 17px.
- Uppercase is the default for headings h2–h6, for buttons and for navigation — with tracking (0.1em on headings, 1px on buttons and nav). Uppercase without tracking is never correct.
- h1 is the only heading the stylesheet leaves untransformed; the hero copy is typed in caps instead.
- Body copy is Montserrat 400 at 14px / 1.5 in plum; a paragraph's bottom margin is 19.444px and a heading's is 17.5px.
- Numerals in the operator register are tabular; a price in the editorial register is not.
- Never set an order number, a SKU, an email address or a customer name in uppercase.

- Minimum rendered size: 12px.
- At most 2 weights per family.
- `--font-display` never renders below 17px.
- `--font-sans` never renders below 12px.

- Arvo sets every heading and nothing else. Montserrat sets every other word in both registers.
- Headings h2–h6 are uppercase at 0.1em tracking; buttons and navigation are uppercase at 1px. Uppercase without tracking is never correct.
- Type floor 12px, heading floor 17px, in both registers.
- Only Montserrat 400 and 700 are loaded. Declaring 500 or 600 produces a synthesised weight, which is a bug, not a style.

### Iconography

| Field | Value |
|---|---|
| Style | One weight, one metaphor per concept, no duotone and no filled-and-outlined pairs of the same glyph. An icon carries a label unless the control is one of the six the whole web already knows (search, cart, account, close, back, menu); an icon alone is never the only carrier of an action's meaning. |
| Library | Editorial: the Shopify Debut icon sprite (a small closed set drawn to a 20 × 20 box, filled with currentColor). Operator: Lucide, the icon set the wc-gorgias design system installs alongside shadcn/ui. |
| Grid | Editorial 20 × 20 (.icon is width: 20px; height: 20px). Operator 24 × 24 on a 2px keyline, rendered at 16px in a table row and 20px in a toolbar. |
| Stroke width | Editorial icons are FILLED (fill: currentColor) and carry no stroke. Operator icons are stroked at 1.5px with round caps and joins, and are never filled. |
| Corner radius | 2px on a stroked terminal in the operator set, matching the brand's 2px corner; nothing in either set is drawn with a radius above 2px except a true circle. |

| Token | Size | Use |
|---|---|---|
| — | 20px · 1.25rem · 15pt | Editorial — the storefront default (.icon) |
| — | 16px · 1rem · 12pt | Operator — inside a table row, a chip or a dense button |
| — | 20px · 1.25rem · 15pt | Operator — toolbar, sidebar rail and empty-state |
| — | 24px · 1.5rem · 18pt | Operator — the drawing grid, and an empty-state or error illustration |

- Colour comes from currentColor. An icon is never given a colour of its own; it inherits the ink of the thing it labels.
- The two sets are never mixed on one surface: a storefront page uses the Debut sprite, an operator screen uses Lucide.
- A social platform's own mark keeps that platform's colour and is exempt from currentColor (.icon--full-color).
- No brand mark is ever redrawn as an icon; the wordmark is an asset, not a glyph.
- An icon-only control carries a visually-hidden label (.icon__fallback-text) — the storefront already ships the pattern.


## 5. Shape, layout, elevation

### Radius

- Maximum corner radius: **0.75rem**.
- Exempt selectors: `\brounded-full\b`, `\bwc-pill\b`, `\bwc-priority-dot\b`, `\bsocial-icons__link\b`.

### Spacing scale

| Token | Value | Role |
|---|---|---|
| `--wc-space-gutter` | 55px · 3.4375rem · 41.25pt | — |
| `--wc-space-gutter-sm` | 22px · 1.375rem · 16.5pt | — |
| `--wc-space-grid` | 30px · 1.875rem · 22.5pt | — |
| `--wc-space-grid-sm` | 22px · 1.375rem · 16.5pt | — |
| `--wc-space-block` | 35px · 2.1875rem · 26.25pt | — |
| `--wc-space-control` | 10px 18px | — |
| `--wc-space-field` | 8px 15px | — |

### Structure

| Token | Value | Role |
|---|---|---|
| `--wc-page-max` | 1200px · 75rem · 900pt | .page-width — the only content measure in the system |
| `--wc-header-logo-max` | 250px · 15.625rem · 187.5pt | .site-header__logo-image, the shop's own setting |
| `--wc-header-pad` | 0 55px | .site-header above 750px |
| `--wc-announce-pad` | 11px 22px | .announcement-bar__message (55px inline above 750px) |
| `--wc-field-min-height` | 42px / 46px | .input-group__field — below / above 750px |
| `--wc-footer-pad` | 45px 0 55px | .site-footer (35px bottom below 750px) |
| `--wc-radius` | 2px · 0.125rem · 1.5pt | Buttons, inputs, cards, the input group's outer corners |
| `--wc-radius-pill` | 25px · 1.5625rem · 18.75pt | The one pill in the system |
| `--wc-radius-circle` | 50% | Avatars, dots, the cart count, the scroll-to-top control |
| `--wc-border-width` | 1px · 0.0625rem · 0.75pt | Every hairline; a knockout button on dark art is 2px |
| `--wc-focus-width` | 4px · 0.25rem · 3pt | The focus halo (3px on dense controls) |

### Breakpoints

| Value | Meaning | Note |
|---|---|---|
| 749px | Small — the single-column phone layout | @media only screen and (max-width: 749px) — 90 rules |
| 750px | Medium — the page opens to 55px gutters and the 30px grid | @media only screen and (min-width: 750px) — 133 rules, the system's real hinge |
| 990px | Large — the desktop navigation and multi-column feature rows | @media only screen and (min-width: 990px) — 11 rules |
| 1400px | Widescreen — one slideshow refinement only | @media only screen and (min-width: 1400px) — 1 rule |

### Max widths

| Value | Used by |
|---|---|
| 1200px | .page-width — every page |
| 500px | A feature-row image |
| 400px | The cart popup and the predictive-search panel |
| 300px | A drawer column |
| 160px | A payment-icon row |

### z-index

| Value | Used by |
|---|---|
| 1–5 | In-flow content: slideshow layers, product media, overlay captions |
| 8 | Drawer contents |
| 9 | The drawer itself |
| 10 | The announcement bar |
| 11 | The sticky site header |
| 999–1000 | The cart popup and the predictive-search overlay |
| 9999–10000 | Third-party app layers (scroll-to-top, review widgets). Not the brand's own scale — see drift. |

### Layout policies

- One measure: 1200px. There is no second container width and no full-bleed exception except a slideshow, a feature row's image and the announcement rail.
- The gutter is 55px above 750px and 22px below. The grid gutter is 30px / 22px on the same hinge.
- 750px is the layout's only real hinge; 990px and 1400px are refinements, not layouts.
- Sections stack at a 55px rhythm. A section never sets its own top and bottom margin independently.
- The brand's own z-index scale ends at 11. Anything above 999 is a third-party layer the brand does not own.
- Nothing is sticky except the header. There is no sticky CTA, no sticky filter bar and no sticky footer.

### Elevation

- Policy: **tokens-only**.
- The only shadow tokens permitted: `--wc-shadow-overlay`, `--wc-shadow-lift`.
- Exempt scopes: `.cart-popup`.

### Shape and layout rules

- The brand corner is 2px. A pill is 25px, a circle is 50%, and nothing else is rounded in the editorial register.
- The operator register's corner is 0.5rem (8px), inherited from the wc-gorgias design system, and it is a register difference rather than a drift — a dense tool needs a softer corner than a 14px storefront (decision W-5).
- Structure comes from hairlines, not from shadow. The only two shadows in the system are the overlay pair; a card, a row, a panel and a table never carry one.
- The editorial page is 1200px maximum with 55px gutters above 750px and 22px below; the grid gutter is 30px desktop / 22px mobile.
- The operator shell is three panels — 288px sidebar, fluid main, 384px context — above 1280px, and the context panel becomes a sheet below it.


## 6. Motion

### Easings

| Token | Value | Use |
|---|---|---|
| `--wc-ease` | `cubic-bezier(0.29, 0.63, 0.44, 1)` | The storefront's default — every hover, reveal and slideshow transition |
| `--wc-ease-quick` | `cubic-bezier(0.44, 0.13, 0.48, 0.87)` | A dense control: the quantity stepper, a disclosure toggle |
| `--wc-ease-inout` | `ease-in-out` | A background-colour change on a button or a rail |
| `--wc-ease-linear` | `linear` | The loading spinner only |

### Durations

| Token | Value | Use |
|---|---|---|
| `--wc-duration-instant` | 100ms | A background-colour change (button, announcement rail) |
| `--wc-duration-quick` | 200ms | A small hover: icon, chip, nav item |
| `--wc-duration-base` | 450ms | The default — image reveals, slideshow slides, drawer open |
| `--wc-duration-spin` | 500ms | One rotation of the loading spinner |

### Choreography

| Name | How it moves |
|---|---|
| Reveal | An image or a section fades and lifts into place once, over 450ms on --wc-ease. It never replays on scroll-back. |
| Hover lift | A product card raises its border to --wc-border-strong and its image scales to at most 1.04 over 450ms. It never translates more than 2px and it never adds a shadow. |
| Rail hover | The announcement rail crossfades wine to --wc-accent-hover over 100ms. Nothing moves. |
| Drawer | The cart and mobile-nav drawers slide in over 450ms on --wc-ease, dimming the page behind them. Focus moves into the drawer and returns to the trigger on close. |

### Caps and bans

- No transition or animation exceeds 450ms.
- Banned keywords: `bounce`, `elastic`, `spring`, `overshoot`, `shimmer`, `blink`, `wobble`, `parallax`.
- Never: Bounce and elastic easing.
- Never: Spring overshoot.
- Never: Parallax on a product image.
- Never: Auto-playing video with sound.
- Never: Carousels that advance without the reader asking.
- Never: Blinking or flashing text.
- Never: Motion that is the only carrier of a state change.
- Never: Decorative loops inside a cart, a checkout, a form or an operator table.

### Reduced motion

- `prefers-reduced-motion: reduce` **must** be honoured — a build that omits it fails the check.
- Under prefers-reduced-motion: reduce, the image-loader pulse and the button spinner stop; the slideshow does not auto-advance and exposes its arrows and dots; hover lifts do not translate and keep only their colour and border transitions; the cart drawer and the search overlay appear at their final position rather than sliding. Nothing in either register is communicated by motion alone (decision W-7).

### Motion rules

- Meaningful motion is 450ms or less; the storefront's own easing is cubic-bezier(0.29, 0.63, 0.44, 1). The operator register caps at 250ms.


## 7. Assets

Every asset below is content-addressed and immutable. Fetch it by URL; never redraw, retrace, recolour or regenerate a mark.

| Asset | Kind | Role | Colorway | Background | Mode | Format | Purpose | Platform | Label | URL |
|---|---|---|---|---|---|---|---|---|---|---|
| `logo.wordmark` | logo | wordmark | one-color | --wc-surface | light | png | — | web | Plum on light — the highest-resolution cut in the fleet | https://brandguide.winechips.com/api/public/v1/assets/594a90e197add1f837b7730198f2bcb923deb61b0792c93bab38b829c34bb82e |
| `logo.wordmark` | logo | inverse | inverse | --wc-plum | dark | png | — | web | White knockout — for a plum block, the wine rail, a photograph or a dark email | https://brandguide.winechips.com/api/public/v1/assets/e58cfc39f891b7cef3f4ec2174667443c81c35a4ac8bb79faaed74b686a70f18 |
| `logo.wordmark` | logo | wordmark | one-color | --wc-surface | light | png | — | web | Plum on light, 313 px — the exact file the storefront header serves today | https://brandguide.winechips.com/api/public/v1/assets/b6ca1c68caf6609d5e0160ed816de41cc7b9fff9648099b1c56b143ba3246a07 |
| `appicon.favicon` | appicon | favicon | one-color | --wc-white | any | png | any | web | 32 x 32 — the only icon the live site serves | https://brandguide.winechips.com/api/public/v1/assets/a3d80a524426be27c0c6c87b70dcd788c7c246dc6b52d3ed89f30539b3801bf1 |
| `og.social` | og | og | — | — | any | jpg | — | social | The og:image and twitter:image the storefront serves — a seasonal product photograph, not a designed card | https://brandguide.winechips.com/api/public/v1/assets/479ee7100685561a3435a01b4aea182250e10dded1fb0885e2227bc59691a6e2 |
| `font.display` | font | font | — | — | any | woff2 | — | web | Arvo Regular 400 — the exact WOFF2 the storefront serves (arvo_n4) | https://brandguide.winechips.com/api/public/v1/assets/af9a85531f3f742a38ed066e50591a98a8a36b952e9ccb6b8117dcc42713a777 |
| `font.sans` | font | font | — | — | any | woff2 | — | web | Montserrat Regular 400 — the exact WOFF2 the storefront serves (montserrat_n4) | https://brandguide.winechips.com/api/public/v1/assets/c0ec39d77c456f49c6434f667679bbfcbf75ca15bc70adb159bbf54c8ce5d7ec |
| `font.sans-bold` | font | font | — | — | any | woff2 | — | web | Montserrat Bold 700 (montserrat_n7). Declared under its own family name because the master's emitter writes one weightless @font-face per font asset — see drift. | https://brandguide.winechips.com/api/public/v1/assets/2ede5e0c613d16828b40e64c06898484080f909ac09a4567a1d5929e01a686db |
| `font.sans-italic` | font | font | — | — | any | woff2 | — | web | Montserrat Italic 400 (montserrat_i4), italic angle -11.3 degrees | https://brandguide.winechips.com/api/public/v1/assets/ef5d0ee539ba1931161ad8ab978464644893d2e9c5dab04d770ec551e66fa287 |
| `font.sans-bold-italic` | font | font | — | — | any | woff2 | — | web | Montserrat Bold Italic 700 (montserrat_i7) | https://brandguide.winechips.com/api/public/v1/assets/50062f6aa45cb51f8a8d2ba3d676f17503467f03f8f246ef8ecd36ca286ba19c |

### Clear space, minimum size, misuse

| Asset | Clear space | Minimum size | Never |
|---|---|---|---|
| `logo.wordmark` | — | 120px on screen. The lockup is a raster, so it is never scaled above its natural width — 2489px for the Rally cut, 313px for the storefront cut. | Never recolour. Plum on light and white on dark are the only two cuts that exist.; Never outline, emboss, add a shadow or place it on a busy photograph without a plum scrim.; Never stretch, condense, rotate or set at an angle.; Never rebuild it in live type — it is custom lettering, and no font in this guide draws it.; Never scale a raster above its natural width; ask for the vector master instead (D-WC1). |
| `appicon.favicon` | — | — | Never the only icon a platform is given: 32px is below every modern requirement.; Never upscaled to fill a 180px or 512px slot. |
| `og.social` | — | — | Never treated as a designed social card: it carries no wordmark and its 1.66:1 ratio crops unpredictably at 1.91:1. |

### Choosing a cut

`GET https://brandguide.winechips.com/api/public/v1/logo/<asset id>` answers with a 302 to the right variant. It accepts `?mode=light|dark`, `?colorway=`, `?format=svg|png` and ranks role > colorway > background/mode > format, degrading to the closest cut rather than returning nothing. `pdf` print masters and `woff2` faces are never redirected to — fetch those by their asset URL above.

### Asset and imagery rules

- The wordmark ships in exactly two colourways — plum on light, white on dark. It is never recoloured, never outlined, never given a shadow and never set in live type.
- No vector master exists. Every shipped mark is a raster, so a lockup is never scaled above its natural width (2489px for the Rally cut, 313px for the storefront cut) — the gap is decision W-4 and gate D-WC1.


## 8. Components

### Announcement rail — `announcement-bar`

| Field | Value |
|---|---|
| Group | Chrome |
| Selectors | `.announcement-bar`, `.announcement-bar__message`, `.announcement-bar__link` |
| Spec | The full-bleed wine rail at the very top of every page. One line, Arvo 400 at 16px, white on --wc-accent, optionally a link. |

| State | Spec |
|---|---|
| Rest | --wc-accent ground, --wc-on-accent ink, padding 11px 22px (55px inline above 750px), 1px transparent bottom border, z-index 10 |
| Hover (link) | ground crossfades to --wc-accent-hover over 100ms ease-in-out; the ink does not change |
| Dismissed | the rail is removed from flow; nothing collapses under it |

- One message at a time. The rail never stacks and never scrolls its content.
- It is the only element in the system allowed to be a full-bleed field of --wc-accent.
- Never set below 16px and never in Montserrat — this is Arvo's one non-heading job.

Tokens consumed: `--wc-accent`, `--wc-accent-hover`, `--wc-on-accent`.

### Site header — `site-header`

| Field | Value |
|---|---|
| Group | Chrome |
| Selectors | `.site-header`, `.site-header__logo`, `.site-header__logo-image`, `.logo-align--center` |
| Spec | A white header with the wordmark centred, 250px maximum, over a navigation row. |

| State | Spec |
|---|---|
| Rest | --wc-surface ground, padding 0 55px above 750px, logo margin 15px 0, z-index 11 |
| Small | below 750px a 1px --wc-border bottom rule appears and the padding drops to the 22px gutter |

- The wordmark is an image asset, never live type.
- The header carries no shadow — a hairline is the whole separation.
- The logo never exceeds 250px wide on the storefront, and never scales above the shipped asset's natural width.

Tokens consumed: `--wc-border`, `--wc-surface`.

### Primary navigation — `site-nav`

| Field | Value |
|---|---|
| Group | Chrome |
| Selectors | `#SiteNav`, `.site-nav__link` |
| Spec | Four uppercase Montserrat items with 1px tracking; the third (Private Reserve Club) carries a wine ground as a permanent highlight. |

| State | Spec |
|---|---|
| Rest | --wc-ink, padding 4px 15px 5px, uppercase, tracking 1px |
| Hover / focus | --wc-link-hover with a 1px underline |
| Highlighted item | --wc-accent ground with --wc-on-accent ink — the club item only |
| Focus-visible | a 4px --wc-focus-ring halo |

- At most one highlighted item. A second wine ground in the nav is a second accent.
- The theme asks for font-weight 600, which is not a loaded Montserrat cut; use 700 (drift).

Tokens consumed: `--wc-accent`, `--wc-focus-ring`, `--wc-ink`, `--wc-link-hover`, `--wc-on-accent`.

### Button — primary — `btn-primary`

| Field | Value |
|---|---|
| Group | Actions |
| Selectors | `.btn` |
| Spec | The wine action. Montserrat 700 uppercase with 1px tracking on a 2px corner. |

| State | Spec |
|---|---|
| Rest | --wc-accent ground, --wc-on-accent label, 1px transparent border, radius 2px, padding 10px 18px (8px 15px below 750px) |
| Hover / focus | ground --wc-accent-hover over 100ms ease-in-out |
| Focus-visible | a 4px --wc-focus-ring halo outside the border |
| Disabled | --wc-fill-strong ground, --wc-ink-dim label, cursor default, no hover |
| Busy | the label is replaced by the spin keyframe at 500ms linear; the button keeps its width |

- White on wine measures 7.50:1 — the primary button is the brand's most accessible surface and should not be softened.
- Never full-width above 750px except inside an input group.
- One primary button per view. A second wine fill competes with the rail.

Tokens consumed: `--wc-accent`, `--wc-accent-hover`, `--wc-fill-strong`, `--wc-focus-ring`, `--wc-ink-dim`, `--wc-on-accent`.

### Button — secondary — `btn-secondary`

| Field | Value |
|---|---|
| Group | Actions |
| Selectors | `.btn--secondary`, `.btn--secondary-accent` |
| Spec | A transparent button with a --wc-action border and label. The theme's neutral action, still shipped alongside the wine primary. |

| State | Spec |
|---|---|
| Rest | transparent ground, --wc-action border and label, radius 2px |
| Hover / focus | border and label move to --wc-action-hover; the ground stays transparent |
| On an image | .btn--secondary-accent swaps the ground to --wc-surface so the label stays readable |

- Secondary never fills on hover — it is a border button in every state.
- The neutral graphite here is the storefront's shipped value, not a brand colour (decision W-8).

Tokens consumed: `--wc-action`, `--wc-action-hover`, `--wc-surface`.

### Button — knockout — `btn-outline-dark`

| Field | Value |
|---|---|
| Group | Actions |
| Selectors | `.btn.slideshow__btn`, `.wc-on-plum .btn` |
| Spec | The button the storefront ships on a hero image or a plum block: transparent, 2px white border, white uppercase label. |

| State | Spec |
|---|---|
| Rest | transparent ground, 2px --wc-action border, --wc-action label |
| Hover / focus | fills to --wc-action with a --wc-on-action label |
| Focus-visible | a cream --wc-focus-ring halo |

- The border is 2px here and 1px everywhere else — a knockout needs the weight against photography.
- Never place a wine fill on a plum block; the knockout is the dark-ground primary.

Tokens consumed: `--wc-action`, `--wc-focus-ring`, `--wc-on-action`.

### Hero / slideshow — `hero`

| Field | Value |
|---|---|
| Group | Editorial |
| Selectors | `.slideshow`, `.slideshow__image`, `.slideshow__text-box`, `.slideshow__text-content` |
| Spec | A full-bleed image with a left-aligned text box, a headline and up to two buttons. Separate desktop and mobile art. |

| State | Spec |
|---|---|
| Rest | text-align left, an image overlay at 0.17 opacity (0.57 on hover) over --wc-image-overlay |
| Small | the mobile image replaces the desktop image below 750px |
| Advancing | 450ms on --wc-ease; arrows and dots are always present |

- Art direction: keep focal subjects right of centre — the left is where the headline lands.
- The slideshow never auto-advances under prefers-reduced-motion.
- A headline over photography is always --wc-on-ink over the overlay, never plum.

Tokens consumed: `--wc-ease`, `--wc-on-ink`.

### Feature row — `feature-row`

| Field | Value |
|---|---|
| Group | Editorial |
| Selectors | `.feature-row`, `.feature-row__text`, `.feature-row__image` |
| Spec | A two-column image-and-text band, alternating side, on white or --wc-surface-alt. |

| State | Spec |
|---|---|
| Rest | text padding 35px block, 35px inline on the inner edge; image max-width 500px |
| Small | stacks, image first, text padding-bottom 0 |

- Alternate the image side down the page; never two rows the same way running.
- The band's ground alternates white / --wc-surface-alt and never uses the cream — the cream is for logo and press strips.

Tokens consumed: `--wc-surface-alt`.

### Cream band — `cream-band`

| Field | Value |
|---|---|
| Group | Editorial |
| Selectors | `#shopify-section-lander-logo-list`, `#shopify-section-lander-as-seen-on` |
| Spec | The one warm section ground: a --wc-surface-warm band carrying a logo list, a press strip or an 'as seen on' rail. |

| State | Spec |
|---|---|
| Rest | --wc-surface-warm ground, --wc-ink copy, 30px block padding |

- Only for third-party marks and press. Never a product band, never a CTA band.
- Third-party logos keep their own colour; they are not knocked back to plum.
- At most one cream band per page.

Tokens consumed: `--wc-ink`, `--wc-surface-warm`.

### Wine-to-plum band — `plum-band`

| Field | Value |
|---|---|
| Group | Editorial |
| Selectors | `.wc-on-plum` |
| Spec | The signature dark band: linear-gradient(90deg, rgba(166,25,46,1) 0%, rgba(81,42,68,1) 100%), carrying a testimonial, a club pitch or a partner message. |

| State | Spec |
|---|---|
| Rest | mount .wc-on-plum; every role token remaps, the accent becomes the cream and the button becomes a knockout |
| Flat variant | a solid --wc-surface-warm (#A6192E) band where the gradient would fight the content |

- The gradient is always 90deg and always wine on the left. It is never rotated, reversed or animated.
- One dark band per page. Two turn a light brand into a dark one.
- Never place cream type on the wine end or wine type on the plum end — use --wc-ink.

Tokens consumed: `--wc-ink`, `--wc-surface-warm`.

### Product card — `product-card`

| Field | Value |
|---|---|
| Group | Commerce |
| Selectors | `.grid-view-item`, `.grid-view-item__title`, `.grid-view-item__image` |
| Spec | An image, a plum title and a price in a 30px grid. No card ground, no border, no shadow. |

| State | Spec |
|---|---|
| Rest | transparent ground, --wc-ink title, 35px bottom margin |
| Hover | the image scales to at most 1.04 over 450ms on --wc-ease; the title takes --wc-link-hover |
| Sold out | a --wc-fill-soft badge with --wc-ink-muted label; the image drops to 60% opacity |
| On sale | the regular price is struck through in --wc-ink-dim and the sale price is --wc-sale-ink |

- The card is the image. No panel, no border, no shadow.
- The title is never uppercase — a product name is Title Case.

Tokens consumed: `--wc-ease`, `--wc-fill-soft`, `--wc-ink`, `--wc-ink-dim`, `--wc-ink-muted`, `--wc-link-hover`, `--wc-sale-ink`.

### Price — `price`

| Field | Value |
|---|---|
| Group | Commerce |
| Selectors | `.price`, `.price--on-sale`, `.price-item--sale`, `.price-item--regular` |
| Spec | Montserrat 400 at 14px in plum; on sale the regular price is struck and the sale price takes the sale ink. |

| State | Spec |
|---|---|
| Rest | --wc-ink |
| On sale | .price--on-sale hides the regular price row and shows .price__sale; .price-item--sale is --wc-sale-ink |
| Unit price | --wc-ink-dim at 12px beneath the price |

- A sale price is small text, so it uses --wc-sale-ink (5.12:1), not the shipped --wc-sale (4.64:1) — decision W-9.
- Never colour a regular price. Only a sale price carries a hue.

Tokens consumed: `--wc-ink`, `--wc-ink-dim`, `--wc-sale`, `--wc-sale-ink`.

### Input and textarea — `input`

| Field | Value |
|---|---|
| Group | Forms |
| Selectors | `input`, `textarea`, `select`, `.disclosure__toggle`, `.input--error` |
| Spec | Montserrat 400 at 14px, 8px 15px padding, a 1px --wc-border-form edge and a 2px corner. |

| State | Spec |
|---|---|
| Rest | --wc-surface ground, --wc-ink text, 1px --wc-border-form edge |
| Hover | edge to --wc-border-strong |
| Focus | a 3px --wc-focus-ring halo; the edge stays |
| Error | --wc-negative edge and text on a --wc-negative-bg ground; the placeholder is --wc-negative at 0.5 opacity |
| Disabled | --wc-fill-subtle ground, --wc-ink-dim text, no halo |

- Font-size is 16px on touch to stop iOS zooming; 14px above 750px.
- An error state always carries a message as well as the colour.
- Placeholder text is never the label.

Tokens consumed: `--wc-border-form`, `--wc-border-strong`, `--wc-fill-subtle`, `--wc-focus-ring`, `--wc-ink`, `--wc-ink-dim`, `--wc-negative`, `--wc-negative-bg`, `--wc-surface`.

### Input group — `input-group`

| Field | Value |
|---|---|
| Group | Forms |
| Selectors | `.input-group`, `.input-group__field`, `.input-group__btn` |
| Spec | A field and a button welded into one control: the field takes the left 2px corners, the button the right. |

| State | Spec |
|---|---|
| Rest | min-height 42px below 750px, 46px above; field radius 2px 0 0 2px, button radius 0 2px 2px 0 |
| Small | the pair stacks and each half regains all four corners |

- The button inside an input group is always the primary wine.
- The field's flex-basis is 15rem and it grows; the button never does.

### Form message — `form-message`

| Field | Value |
|---|---|
| Group | Forms |
| Selectors | `.form-message`, `.form-message--success`, `.form-message--error` |
| Spec | A full-width message block above a form: a 1px rule, a tinted ground and a matching ink. |

| State | Spec |
|---|---|
| Success | 1px --wc-positive rule, --wc-positive-bg ground, --wc-positive-ink text, padding 10px |
| Error | 1px --wc-negative rule, --wc-negative-bg ground, --wc-negative-ink text, padding 1rem 1.3rem |

- A link inside an error message is underlined and stays --wc-negative-ink.
- The message names what to do next, not only what went wrong.

Tokens consumed: `--wc-negative`, `--wc-negative-bg`, `--wc-negative-ink`, `--wc-positive`, `--wc-positive-bg`, `--wc-positive-ink`.

### Newsletter — `newsletter`

| Field | Value |
|---|---|
| Group | Forms |
| Selectors | `.site-footer__item-inner--newsletter`, `.btn.newsletter__submit` |
| Spec | An email field and a wine Subscribe button under a JOIN THE COMMUNITY heading, inside the footer. |

| State | Spec |
|---|---|
| Rest | an input group on --wc-surface-alt; the submit is --wc-accent |
| Submitted | the group is replaced by a success form-message |

- The consent line sits under the field, at 12px in --wc-ink-dim, and is never hidden behind a link.

Tokens consumed: `--wc-accent`, `--wc-ink-dim`, `--wc-surface-alt`.

### Site footer — `footer`

| Field | Value |
|---|---|
| Group | Chrome |
| Selectors | `.site-footer`, `.site-footer__hr`, `.site-footer__linklist`, `.site-footer__copyright-content` |
| Spec | A --wc-surface-alt block with link columns, a newsletter, social marks and the registered address. |

| State | Spec |
|---|---|
| Rest | --wc-surface-alt ground, --wc-ink-muted default ink, padding 45px 0 55px, 55px top margin |
| Links | --wc-ink at rest, --wc-ink-dim on hover with a 1px underline |
| Rule | a 1px --wc-hairline-footer border-bottom |

- The footer is the one region where the ink is a neutral rather than the plum — a shipped inconsistency recorded as drift, not a licence to add greys elsewhere.
- Social marks are --wc-ink, not the platforms' own colours, in the footer row.

Tokens consumed: `--wc-hairline-footer`, `--wc-ink`, `--wc-ink-dim`, `--wc-ink-muted`, `--wc-surface-alt`.

### Social marks — `social-icons`

| Field | Value |
|---|---|
| Group | Chrome |
| Selectors | `.social-icons__link`, `.icon--full-color` |
| Spec | A row of platform marks at 20px, filled with currentColor. |

| State | Spec |
|---|---|
| Rest | --wc-ink |
| Hover | --wc-ink-dim |
| Share buttons | .btn--share keeps each platform's own brand colour and is exempt from currentColor |

- A footer social row is monochrome. A share button is not.

Tokens consumed: `--wc-ink`, `--wc-ink-dim`.

### Cart drawer and popup — `cart-drawer`

| Field | Value |
|---|---|
| Group | Commerce |
| Selectors | `.drawer`, `.cart-popup` |
| Spec | A right-hand drawer (z-index 9, contents at 8) and a lighter 400px popup confirming an add-to-cart. |

| State | Spec |
|---|---|
| Opening | slides in over 450ms on --wc-ease; the page behind dims |
| Rest | --wc-surface ground, 1px --wc-border hairlines, padding 0.2rem 1.5rem 1rem in the popup |
| Reduced motion | appears at its final position with no slide |

- Focus moves into the drawer on open and returns to the trigger on close.
- Escape closes. The dim behind is a click target that also closes.
- The popup heading is 'Just added to your cart' and the two actions are 'View cart' and 'Continue shopping'.

Tokens consumed: `--wc-border`, `--wc-ease`, `--wc-surface`.

### Pagination — `pagination`

| Field | Value |
|---|---|
| Group | Navigation |
| Selectors | `.pagination` |
| Spec | Centred inline page numbers at 15px with 55px of space above. |

| State | Spec |
|---|---|
| Rest | --wc-ink numbers |
| Current | --wc-ink at 700, not a fill |
| Hover | --wc-link-hover |
| Disabled | --wc-ink-dim, no pointer |

- The current page is a weight change, not a wine chip. Wine is reserved for actions.

Tokens consumed: `--wc-ink`, `--wc-ink-dim`, `--wc-link-hover`.

### Rich text — `rte`

| Field | Value |
|---|---|
| Group | Editorial |
| Selectors | `.rte`, `.rte-setting` |
| Spec | CMS-authored prose: paragraphs at 14px, large at 16px, small at 12px, headings on the Arvo scale. |

| State | Spec |
|---|---|
| Rest | --wc-ink at line-height 1.5; a link is --wc-ink with a 1px underline |
| Link hover | --wc-link-hover |

- A rich-text block never introduces a colour. Everything it can render is already a role token.
- Lists and blockquotes stay inside the 1200px measure; a blockquote is a 2px --wc-accent left rule.

Tokens consumed: `--wc-accent`, `--wc-ink`, `--wc-link-hover`.

### Empty, error and loading — `empty-error-loading`

| Field | Value |
|---|---|
| Group | States |
| Selectors | `.blankstate`, `.image-loader`, `.btn .icon-spinner` |
| Spec | The three states every commerce surface owes a shopper. |

| State | Spec |
|---|---|
| Empty | --wc-fill-soft ground, 1px --wc-fill-strong rule, --wc-ink-muted copy, and one primary action |
| Loading | a --wc-fill-subtle placeholder block for an image; a 500ms linear spinner inside a busy button. No shimmer. |
| Error | a form-message error block, or a page-level message with a way back to the shop |

- An empty state always offers the next action.
- A loading state never blocks the whole page.
- No skeleton shimmer anywhere in the editorial register.

Tokens consumed: `--wc-fill-soft`, `--wc-fill-strong`, `--wc-fill-subtle`, `--wc-ink-muted`.


## 9. How to apply, by target

Three targets, three recipes. Pick the one that matches what you are building; do not improvise a fourth.

### A. An Ada-fleet web app (Next.js + FastAPI)

1. Install the consumer package `ada-pip-styleguide` (and its kit `@stritz/styleguide-kit`) into the project.
2. Ask the brand owner for a **subscription endpoint issued at this master** — the credential block carries `STYLEGUIDE_API_URL=https://brandguide.winechips.com`, a project-scoped `STYLEGUIDE_API_TOKEN`, `STYLEGUIDE_BRAND=winechips` and `STYLEGUIDE_CHANNEL=stable`. The public tier you are reading is for tools OUTSIDE the fleet; a fleet app subscribes and gets signature verification, overlays and push updates.
3. Render `<BrandStyles/>` in the root layout and `<BrandLogo/>` wherever a mark appears. Never hand-write a logo `<img>`.
4. Mount the kit's `/styleguide` viewer route so the project can show the brand it is actually serving.
5. Add `styleguide-check --strict` to CI. A FAIL is a broken build.

### B. Any other web project (no Ada, no wheel)

1. Vendor `https://brandguide.winechips.com/api/public/v1/brand.css` and `https://brandguide.winechips.com/api/public/v1/tokens.tailwind.css` into the repository, plus every asset from §7 the project actually uses.
2. Link the stylesheet in the document head, before your own CSS. If you use Tailwind v4, `@import` the theme file after `@import "tailwindcss";`.
3. Use the token names from §3–§6. Do not restate their values in your own CSS; reference the custom properties.
4. Re-vendor whenever the version at `https://brandguide.winechips.com/api/public/v1/.well-known/styleguide.json` changes.
5. Verify:

```
npx styleguide-check --effective https://brandguide.winechips.com/api/public/v1/effective.json \
  --css <your css glob> --strict
```

### C. A document — PDF, deck, proposal, report, email

- Page ground: `#FFFFFF`.
- Footer ink: `#5A5858`.
- Footer line: 'Wine Chips — The Style Guide'.
- Document UI face: `Montserrat, 'Helvetica Neue', Helvetica, Arial, sans-serif`.
- Slide/page ground: `--wc-surface` (#FFFFFF).
- Headings: Arvo — Every heading level, the announcement rail, and nothing else. Arvo is the brand's voice at size; it never sets body copy, UI labels or a data value.
- Labels, captions, tables: Montserrat.
- Type sizes: use the `pt` column in §4 — it is the px scale × 0.75, already computed.
- Logos: take the `pdf` print master from §7 where one exists, otherwise the `svg`; respect the clear space and minimum size in §7.
- Colour: the print builds (Pantone/CMYK) in §3 where the brand declares them.

Use `https://brandguide.winechips.com/api/public/v1/guide.pdf` as the visual reference — it is this exact version's brand book, rendered by the master.


## 10. Verify

Run this before you say the work is done:

```
npx styleguide-check --effective https://brandguide.winechips.com/api/public/v1/effective.json \
  --css <your css glob> --strict --json
```

A clean result is: exit code `0`, `totals.FAIL == 0`, and every family (`contrast`, `banned-values`, `token-liveness`, `demo-safety`, `drift`, `lock-violations`, `asset-integrity`, `literals`) reporting PASS or INFO. A WARN is a thing to explain, not a thing to ignore. A FAIL is not done.

Then report exactly this sentence:

```
Built against Wine Chips v1 manifest c41cd892512feab624e0c1ae662071062092f9b2bff55f510692e43cb0232db1; styleguide-check: 0 FAIL
```


## 11. Governance

**Locked** — Never change these. A delta on a locked path is dropped by the resolver and recorded as a violation — it does not silently apply.

`assets`, `assets.appicon.favicon`, `assets.font.display`, `assets.font.sans`, `assets.font.sans-bold`, `assets.font.sans-bold-italic`, `assets.font.sans-italic`, `assets.logo.wordmark`, `identity`, `motion`, `rules`, `tokens.editorial.--wc-accent`, `tokens.editorial.--wc-cream`, `tokens.editorial.--wc-ink`, `tokens.editorial.--wc-on-accent`, `tokens.editorial.--wc-on-ink`, `tokens.editorial.--wc-plum`, `tokens.editorial.--wc-surface`, `tokens.editorial.--wc-white`, `tokens.editorial.--wc-wine`, `tokens.inverted.--wc-accent`, `tokens.inverted.--wc-ink`, `tokens.inverted.--wc-on-accent`, `tokens.inverted.--wc-surface`, `tokens.inverted.--wc-surface-warm`, `typography`, `voice`

**Tunable** — A project may change these through an APPROVED overlay, never by overriding CSS locally.

`assets.og.social`, `layout`, `tokens`, `tokens.editorial.--font-display`, `tokens.editorial.--font-sans`, `tokens.editorial.--wc-accent-hover`, `tokens.editorial.--wc-action`, `tokens.editorial.--wc-action-hover`, `tokens.editorial.--wc-border`, `tokens.editorial.--wc-border-form`, `tokens.editorial.--wc-border-strong`, `tokens.editorial.--wc-fill-soft`, `tokens.editorial.--wc-fill-strong`, `tokens.editorial.--wc-fill-subtle`, `tokens.editorial.--wc-focus-ring`, `tokens.editorial.--wc-graphite`, `tokens.editorial.--wc-graphite-deep`, `tokens.editorial.--wc-hairline-footer`, `tokens.editorial.--wc-in-stock`, `tokens.editorial.--wc-ink-dim`, `tokens.editorial.--wc-ink-muted`, `tokens.editorial.--wc-link`, `tokens.editorial.--wc-link-hover`, `tokens.editorial.--wc-negative`, `tokens.editorial.--wc-negative-bg`, `tokens.editorial.--wc-negative-ink`, `tokens.editorial.--wc-on-action`, `tokens.editorial.--wc-plum-light`, `tokens.editorial.--wc-positive`, `tokens.editorial.--wc-positive-bg`, `tokens.editorial.--wc-positive-ink`, `tokens.editorial.--wc-sale`, `tokens.editorial.--wc-sale-ink`, `tokens.editorial.--wc-surface-alt`, `tokens.editorial.--wc-surface-warm`, `tokens.editorial.--wc-wine-bright`, `tokens.inverted.--wc-accent-hover`, `tokens.inverted.--wc-action`, `tokens.inverted.--wc-action-hover`, `tokens.inverted.--wc-border`, `tokens.inverted.--wc-border-form`, `tokens.inverted.--wc-border-strong`, `tokens.inverted.--wc-fill-soft`, `tokens.inverted.--wc-fill-strong`, `tokens.inverted.--wc-fill-subtle`, `tokens.inverted.--wc-focus-ring`, `tokens.inverted.--wc-hairline-footer`, `tokens.inverted.--wc-in-stock`, `tokens.inverted.--wc-ink-dim`, `tokens.inverted.--wc-ink-muted`, `tokens.inverted.--wc-link`, `tokens.inverted.--wc-link-hover`, `tokens.inverted.--wc-negative`, `tokens.inverted.--wc-negative-bg`, `tokens.inverted.--wc-negative-ink`, `tokens.inverted.--wc-on-action`, `tokens.inverted.--wc-on-ink`, `tokens.inverted.--wc-positive-ink`, `tokens.inverted.--wc-sale-ink`, `tokens.inverted.--wc-surface-alt`

**Requesting an exception.** Ask the brand owner to raise an overlay request on this master (https://brandguide.winechips.com). An overlay is per-project, is reviewed by a human, and only then reaches your build. Publishing, promoting, rolling back, yanking and issuing a subscription all require a human administrator with MFA — no agent, no service account and no automation can perform any of them.

**What needs a human:** any change to a locked path; any new asset; any new token; any change to the contrast pairs, the banned values or the governance map; and every publish.