rsc-universal 0.1.1

package/skills/brand-identity/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: brand-identity
+description: "Use when defining a project's visual identity foundation from scratch or consolidating ad-hoc brand assets into one system: a logo brief, a color system, a type system, usage rules, and an exported design-tokens.json that downstream skills consume. Use when there is no visual foundation yet, or a rebrand must unify scattered colors/fonts. Triggers: 'build our brand identity', 'create a brand book / brand guidelines', 'logo brief', 'pick our color palette', 'define our type system', 'consolidate our random fonts and hex codes scattered across files into one system', 'necesito una identidad de marca', 'crea la guia de marca amb les normes d'us del logo'. NOT the applied UI/pixels (that is design), NOT the words/tone (that is brand-voice), NOT a journalist asset pack (that is press-kit)."
+tags: [brand, identity, logo, color, typography]
+recommends: [design, brand-voice, press-kit, presentations]
+origin: risco
+---
+
+# Brand Identity — Define the Foundation, Not the Pixels
+
+*This skill emits the brand book — logo brief, color system, type system, usage rules — and a machine-readable `design-tokens.json` that `design` consumes. You write the rules every later pixel must obey; you do not paint the live UI.*
+
+A brand identity with nothing checkable behind it is a mood board. The bar here is a **brand book that compiles**: roles named, every color carrying four channels, contrast pairs proven against WCAG, and a tokens file that `scripts/verify.sh` can validate. Hit that bar or it is not done.
+
+## When to use / When NOT to use
+
+Use when:
+
+- A new product/company has no visual foundation and needs one defined.
+- A rebrand must consolidate ad-hoc colors, fonts, and one-off logos into a single system.
+- `design` is about to build the site and STOPS because no brand study exists — you produce that study's visual half.
+- The user asks for a logo brief, a palette with documented values, or a type system.
+
+Do NOT use — route instead:
+
+| Request | Route to | Why |
+| --- | --- | --- |
+| "Write our tone of voice, tagline, naming, messaging pillars" | `../brand-voice/SKILL.md` | Verbal identity — the words, not the pixels. |
+| "Make this landing page look premium / pick layout + motion / ship the Tailwind" | `../design/SKILL.md` | The applied UI layer — it consumes this foundation, it is not it. |
+| "Write the hero headline, value prop, CTA copy" | `../marketing/SKILL.md` | Page words, not the visual system. |
+| "Assemble a press kit — boilerplate, logos-for-press, fact sheet" | `../press-kit/SKILL.md` | Media packaging of finished assets, not system definition. |
+| "Build the investor pitch deck visuals" | `../presentations/SKILL.md` | Deck composition, not the brand foundation. |
+
+**The one-line test:** "define what our brand looks like everywhere" → here. "make *this surface* look premium" → `design`.
+
+## The deliverable contract (four parts)
+
+Every brand-identity engagement ships all four. Each has a MUST-contain bar; a part missing its bar is incomplete, not "lite".
+
+1. **Logo brief** — MUST define the variation set (primary / stacked / mark-only / mono), the clear-space rule, minimum sizes, and the file + favicon export matrix. *Why:* a logo that only works in one context is not a system; it breaks the first time someone needs a favicon or a one-color print.
+2. **Color system** — MUST give every color a role (primary / secondary / neutral / accent) and four channels (HEX + RGB + CMYK + OKLCH), document AA contrast pairs, and define light/dark roles. *Why:* HEX alone fails print (no CMYK) and wide-gamut screens (no OKLCH); undocumented contrast ships inaccessible.
+3. **Type system** — MUST name 2–3 typefaces max with a scale, weights, and a one-line pairing rationale. *Why:* more than three families reads as chaos; an undocumented scale gets re-guessed on every screen.
+4. **Usage guidelines** — MUST give do/don't rules, a misuse table, and an exported W3C-format `design-tokens.json`. *Why:* the tokens file is the hand-off contract; without it `design` re-derives your palette by eye and drifts.
+
+## Logo brief
+
+Specify a system, not a single picture. The mark must survive from favicon to billboard, in color and in one ink.
+
+- **Variation set** — primary (horizontal lockup), stacked (vertical, for square/tight slots), mark-only (the symbol alone, for avatars/favicons), monochrome (single-ink: black, white-knockout). A logo that has no mono version fails the moment it lands on a colored background or a fax.
+- **Clear space** — define it relative to the mark, not in fixed px, so it scales: clear space = the cap-height (or x-height of the mark) on all four sides. Nothing intrudes inside it.
+- **Minimum size** — below this, detail collapses. Defaults: 24px wide digital, 10mm wide print for the full lockup; the mark-only may go smaller (favicon).
+- **Color + mono requirement** — every variation must be reproducible in full color AND in a single ink. Test the mono version first; if it dies in one color, the design is too fragile.
+- **File + favicon matrix** — ship the formats below. SVG is the digital primary (scales, tiny); PNG carries transparency; JPEG is print-safe; 72 DPI digital / 300 DPI print.
+
+| Asset | Format | Notes |
+| --- | --- | --- |
+| Logo (digital primary) | SVG | Vector, scales infinitely, smallest |
+| Logo (raster, transparency) | PNG | @1x/@2x, transparent bg |
+| Logo (print) | JPEG/PDF | 300 DPI, CMYK |
+| Favicon (modern) | `favicon.svg` | <1KB, can embed `prefers-color-scheme` for dark mode |
+| Favicon (legacy fallback) | `favicon.ico` | At site root |
+| Favicon PNG | `favicon-16.png`, `favicon-32.png` | Tab/bookmark |
+| Apple touch | `apple-touch-icon.png` 180×180 | iOS home screen |
+| Android | `android-chrome-192.png`, `-512.png` | PWA/manifest |
+| Manifest | `site.webmanifest` | Declares the icon set |
+
+Full variation grid, clear-space/min-size formulas, and the favicon HTML markup + `prefers-color-scheme` SVG snippet → `references/logo-and-assets.md`.
+
+## Color system
+
+Assign roles first, values second. A color with no role is decoration waiting to be misused.
+
+- **Role taxonomy** — 2–3 primary (the brand's signature), 2–3 secondary (support), a neutral ramp (text, surfaces, borders), and exactly **one accent** reserved for CTAs/highlights. One accent keeps "click here" unambiguous.
+- **Four channels, every color** — HEX (web), RGB (screen math), CMYK (print), OKLCH (perceptual + wide-gamut). The W3C Design Tokens Color Module (2025.10) supports CSS Color 4 spaces including OKLCH and Display P3, so wide-gamut color lives in the token file natively — author in OKLCH and let HEX be the fallback.
+- **AA contrast pairing rule** — every text-on-background pair you document must clear WCAG 2 AA: **4.5:1 for normal text, 3:1 for large text** (≥18.66px bold or ≥24px). AAA is 7:1 / 4.5:1 — reach for it on body text where you can. Pair colors explicitly ("`fg` on `bg`: 12.4:1 ✓"); do not leave it to chance.
+- **Logo-text exemption caveat** — WCAG 1.4.3 exempts logos and brand-name text from the contrast minimums. But a *typed* sub-brand or tagline that is plain text (not a graphical logo) IS subject to text-contrast rules. Mark logo-only tokens exempt; hold everything else to 4.5:1.
+- **Light/dark roles** — define the role in both schemes from day one (`bg`/`fg` invert, brand stays anchored). Retrofitting dark mode onto a light-only palette produces muddy, low-contrast surfaces.
+
+Full role taxonomy, a fully worked palette in HEX/RGB/CMYK/OKLCH, the contrast-pair matrix with computed ratios, and the dark-mode token strategy → `references/color-and-tokens.md`.
+
+## Type system
+
+Two to three typefaces, no more. Most brands need exactly two: one display (headlines, personality) and one text (body, ≤16px legibility); a third is justified only for monospace/data.
+
+- **Scale** — pick a modular ratio (1.2 minor third for dense UI, 1.25 major third for marketing) and ladder the sizes from it. Document the ladder; do not re-guess sizes per screen.
+- **Weights** — name which weights ship (e.g. 400 body, 500 UI, 600/700 display) and which are banned (no faux-bold, no faux-italic).
+- **Pairing rationale** — one line on *why* the pair works (contrast in structure: a geometric sans display over a humanist text face; or a serif display over a neutral sans body). "They both look nice" is not a rationale.
+- **Variable-font note** — prefer a variable font where available: one file spans the weight axis, cuts requests, and removes the faux-bold temptation. Pin the named instances you use.
+
+## Emit the tokens (the hand-off contract)
+
+The `design-tokens.json` is what makes this skill's output machine-readable and the reason `design` does not re-derive your palette by eye. Use the **W3C Design Tokens format**, which reached its first stable version (2025.10) on 2025-10-28 — a vendor-neutral JSON for sharing design decisions, with light/dark and multi-brand themes via group inheritance / `$extends`.
+
+```json
+{
+  "$schema": "https://tokens.designtokens.org/2025.10/schema.json",
+  "color": {
+    "brand": {
+      "$type": "color",
+      "primary": {
+        "$value": { "colorSpace": "oklch", "components": [0.55, 0.19, 256], "hex": "#3b5bdb" }
+      },
+      "accent": {
+        "$value": { "colorSpace": "oklch", "components": [0.72, 0.17, 50], "hex": "#f08c00" }
+      }
+    },
+    "bg": { "$type": "color", "$value": { "colorSpace": "oklch", "components": [0.99, 0, 0], "hex": "#fcfcfc" } },
+    "fg": { "$type": "color", "$value": { "colorSpace": "oklch", "components": [0.21, 0.01, 256], "hex": "#1f2430" } }
+  }
+}
+```
+
+Map the tokens to CSS custom properties (and, if the consumer is Tailwind v4, an `@theme` block) so the values flow into utilities — author once, consume everywhere:
+
+```css
+/* design consumes these — generated from design-tokens.json, never hand-edited */
+:root {
+  --color-brand-primary: oklch(0.55 0.19 256);
+  --color-brand-accent:  oklch(0.72 0.17 50);
+  --color-bg:            oklch(0.99 0 0);
+  --color-fg:            oklch(0.21 0.01 256);
+}
+```
+
+Full tokens file with light/dark via `$extends`, the Tailwind v4 `@theme` mapping, and the dark-mode strategy → `references/color-and-tokens.md`.
+
+## Usage guidelines + anti-patterns
+
+State the misuse rules explicitly — the gap a brand book exists to close is the well-meaning teammate who stretches the logo to fit. Bad → Good:
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "Stretch the logo to fill the space" | Non-uniform scaling distorts the mark. Lock aspect ratio; pick the variation that fits (stacked vs primary). |
+| "This blue is close enough" | Off-palette colors fracture recognition. Use the token; if a need is unmet, add a role, don't eyeball one. |
+| "HEX is enough, we're a web brand" | Print and wide-gamut break. Every color carries HEX + RGB + CMYK + OKLCH or it is not in the system. |
+| "Four fonts give us range" | Reads as chaos and bloats load. Cap at 2–3; get range from weights + scale. |
+| "We'll add dark mode later" | Light-only palettes go muddy when inverted. Define light/dark roles from day one. |
+| "Contrast is a design detail" | It is a WCAG requirement. Document each text/bg pair at ≥4.5:1 before shipping. |
+| "Drop the logo on any background" | Color/photo backgrounds kill legibility. Provide and require the mono/knockout variation with clear space. |
+| "The tokens file is optional, the PDF is the brand" | A PDF can't be consumed by code; `design` will drift. The `design-tokens.json` is the contract. |
+
+Do/don't rules, the full misuse grid with examples, and lockup rules → `references/logo-and-assets.md`.
+
+## Verify
+
+The skill emits a checkable artifact, so verify it before claiming done. Run against your tokens file:
+
+```bash
+./scripts/verify.sh path/to/design-tokens.json
+```
+
+It checks: the file parses as JSON; required color roles are present (primary, neutral, accent at minimum); every color token carries a HEX value; and, for each documented text/background pair (declared via `$extensions["com.risco.contrast"]` pairs), it computes the WCAG relative-luminance contrast ratio and **fails any normal-text pair below 4.5:1**. Logo-only tokens are exempt. On an empty or clean target it exits 0 — no false failures.
+
+## Hand-off
+
+Once the brand book and tokens exist, point the next skill at them:
+
+- `../design/SKILL.md` — **applies** this foundation: reads `design-tokens.json`, builds the accessible, fast UI. This skill produces the brand study's visual half that `design` STOPS without.
+- `../brand-voice/SKILL.md` — owns the **words/tone**; pair it with this so copy and visuals agree.
+- `../press-kit/SKILL.md` — **packages** the finished logos/colors for journalists and media.
+- `../presentations/SKILL.md` — consumes the tokens for on-brand decks.

package/skills/brand-identity/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — brand-identity
+
+`cases.yaml` is read by the harness eval runner. The `should_trigger` and
+`should_not_trigger` blocks check routing precision: that brand-foundation requests
+(logo brief, color/type system, tokens export, the Catalan/Spanish phrasings, and the
+non-obvious "consolidate scattered fonts/hex" rebrand case) select this skill, while
+adjacent asks correctly route to the real siblings — `design` (applied UI), `brand-voice`
+(words/tone), `marketing` (page copy), `press-kit` (media pack), `presentations` (deck).
+The `capability` block is a rubric scored against a real generation: the "Ledgerly" prompt
+must produce all four deliverable parts (logo brief, four-channel color roles, an AA-proven
+contrast pair, a 2-3 typeface system, a W3C `design-tokens.json` with light/dark) plus
+usage rules and the hand-off to `design`. Run it via the repo's eval command; no network is
+required. To sanity-check the verify gate by hand, run
+`scripts/verify.sh path/to/design-tokens.json` against a generated tokens file.

package/skills/brand-identity/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: brand-identity
+
+should_trigger:
+  - prompt: "Build our brand identity — logo brief, colors, fonts, the whole brand book."
+    why: "The core ask: all four deliverable parts (logo, color, type, usage) named explicitly. Exact center of the skill."
+  - prompt: "Pick a color palette and document the hex, rgb, and cmyk values for our brand."
+    why: "Color-system core; the four-channel value requirement (HEX/RGB/CMYK/OKLCH) is the skill's contract for colors."
+  - prompt: "Define our type system: primary and secondary typefaces with a scale and weights."
+    why: "Type-system core — 2-3 typefaces, scale, weights, pairing rationale are exactly this skill's bar."
+  - prompt: "We've got random fonts and hex codes scattered across files — consolidate them into one system."
+    why: "Non-obvious rebrand/consolidation trigger: no 'brand book' wording, but unifying ad-hoc colors/fonts into a system is precisely the rebrand path."
+  - prompt: "Necesito una identidad de marca y la guia de marca con normas de uso del logo."
+    why: "Spanish/Catalan trigger naming brand identity, brand guidelines, and logo usage rules — all owned here."
+  - prompt: "Export a design-tokens.json with our brand colors so the dev team stops eyeballing the palette."
+    why: "Non-obvious: phrased as a tokens export, but emitting the W3C design-tokens.json hand-off contract is this skill's machine-readable deliverable."
+
+should_not_trigger:
+  - prompt: "Make this landing page look premium — pick the layout, motion, and ship the Tailwind."
+    route_to: design
+    why: "Applied UI layer (layout, motion, real code) consumes the brand foundation; it is not the foundation itself."
+  - prompt: "Write our tone of voice and a tagline for the homepage."
+    route_to: brand-voice
+    why: "Verbal identity — words and tone — not the visual system."
+  - prompt: "Write the hero headline and the CTA copy for our pricing page."
+    route_to: marketing
+    why: "Page words / conversion copy, not the logo/color/type system."
+  - prompt: "Put together a press kit with our logos and boilerplate for journalists."
+    route_to: press-kit
+    why: "Media packaging of finished assets, not defining the brand system."
+  - prompt: "Design the investor pitch deck slides for our seed round."
+    route_to: presentations
+    why: "Deck composition/visuals, not the brand foundation the deck would draw from."
+
+capability:
+  - scenario: "We're a fintech startup 'Ledgerly'. Create our brand identity foundation."
+    must_include:
+      - "A logo brief with the full variation set (primary / stacked / mark-only / monochrome), a clear-space rule tied to the mark's cap/x-height, minimum sizes (e.g. ~24px digital / ~10mm print), and a file + favicon export matrix (SVG primary, PNG/ICO fallbacks, apple-touch 180, android 192/512, site.webmanifest)."
+      - "Color roles assigned (2-3 primary, 2-3 secondary, a neutral ramp, exactly one accent), each color carrying HEX + RGB + CMYK + OKLCH — not HEX alone."
+      - "At least one documented text-on-background pair meeting WCAG 2 AA (>= 4.5:1 normal text / 3:1 large), stated as an explicit pair (fg on bg with the ratio), and a note that logo/brand-name text is exempt under WCAG 1.4.3 while typed taglines are not."
+      - "A type system of 2-3 typefaces max with a modular scale, named weights, and a one-line pairing rationale (plus a variable-font note)."
+      - "A W3C-format design-tokens.json (2025.10) emitted with light/dark roles via group inheritance / $extends and OKLCH values, mapped to CSS custom properties / Tailwind v4 @theme."
+      - "Usage/misuse rules (no stretching, no off-palette color, require the mono variation on busy backgrounds) plus an explicit hand-off note to design as the skill that applies the tokens."
+      - "A pointer to run scripts/verify.sh on the emitted design-tokens.json to confirm roles, hex coverage, and AA contrast before claiming done."

package/skills/brand-identity/references/color-and-tokens.md

@@ -0,0 +1,129 @@
+# Color system & design tokens
+
+Depth offloaded from SKILL.md: the full role taxonomy, a worked palette in all four
+channels, the contrast-pair matrix, the complete W3C `design-tokens.json` with light/dark,
+the Tailwind v4 `@theme` mapping, and the dark-mode strategy.
+
+## Role taxonomy (assign roles before values)
+
+| Role | Count | Job | Example token |
+| --- | --- | --- | --- |
+| Primary | 2–3 | The brand's signature; the color people recall | `color.brand.primary` |
+| Secondary | 2–3 | Support; section accents, illustration | `color.brand.secondary` |
+| Neutral | a ramp (50→900) | Text, surfaces, borders, dividers | `color.neutral.*` |
+| Accent | exactly 1 | CTAs, highlights, the "click here" color | `color.brand.accent` |
+| Semantic | as needed | success / warning / danger / info states | `color.status.*` |
+
+One accent only. The moment a palette has two "primary action" colors, every button
+becomes a judgment call and the interface loses its one unambiguous next step.
+
+## Worked palette — all four channels
+
+A color is not in the system until it carries HEX (web), RGB (screen), CMYK (print),
+and OKLCH (perceptual + wide-gamut). Author in OKLCH; let HEX be the fallback.
+
+| Token | HEX | RGB | CMYK | OKLCH |
+| --- | --- | --- | --- | --- |
+| brand.primary | `#3b5bdb` | 59, 91, 219 | 73, 58, 0, 14 | `oklch(0.55 0.19 256)` |
+| brand.accent | `#f08c00` | 240, 140, 0 | 0, 42, 100, 6 | `oklch(0.72 0.17 50)` |
+| bg (light) | `#fcfcfc` | 252, 252, 252 | 0, 0, 0, 1 | `oklch(0.99 0 0)` |
+| fg (light) | `#1f2430` | 31, 36, 48 | 35, 25, 0, 81 | `oklch(0.21 0.01 256)` |
+| bg (dark) | `#15171c` | 21, 23, 28 | 25, 18, 0, 89 | `oklch(0.18 0.01 256)` |
+| fg (dark) | `#e9ebf0` | 233, 235, 240 | 3, 2, 0, 6 | `oklch(0.93 0.005 256)` |
+
+CMYK is approximate — final print values come from the press profile (e.g. coated vs
+uncoated stock). Document the intent; let the printer's profile resolve the exact ink mix.
+
+## Contrast-pair matrix (WCAG 2)
+
+Thresholds: AA 4.5:1 normal / 3:1 large (≥18.66px bold or ≥24px); AAA 7:1 / 4.5:1.
+Document every pair you ship as text-on-background.
+
+| Foreground | Background | Ratio | Normal AA | Large AA | AAA |
+| --- | --- | --- | --- | --- | --- |
+| fg `#1f2430` | bg `#fcfcfc` | ~12.4:1 | ✓ | ✓ | ✓ |
+| brand.primary `#3b5bdb` | bg `#fcfcfc` | ~5.0:1 | ✓ | ✓ | ✗ |
+| white `#ffffff` | brand.primary `#3b5bdb` | ~4.9:1 | ✓ | ✓ | ✗ |
+| brand.accent `#f08c00` | bg `#fcfcfc` | ~2.1:1 | ✗ | ✗ | ✗ |
+| fg(dark) `#e9ebf0` | bg(dark) `#15171c` | ~13.6:1 | ✓ | ✓ | ✓ |
+
+The accent on white fails — that is expected. An accent earns its saturation by being
+*reserved*; use it as a fill behind white/dark text or as a non-text highlight, never as
+body text on the page background. Verify each pair with a checker, not by eye.
+
+**Logo-text caveat:** WCAG 1.4.3 exempts logos and brand-name graphics from these minimums.
+A *typed* tagline or sub-brand that is plain text (not a graphical logo) is NOT exempt — hold
+it to 4.5:1. Mark only logo tokens exempt.
+
+## Complete `design-tokens.json` (W3C 2025.10, light/dark via group inheritance)
+
+W3C Design Tokens reached first stable (2025.10) on 2025-10-28. The Color Module supports
+CSS Color 4 spaces (OKLCH, Display P3). Themes share a base and override via group
+inheritance / `$extends`.
+
+```json
+{
+  "$schema": "https://tokens.designtokens.org/2025.10/schema.json",
+  "$description": "Brand tokens — single source consumed by the design skill.",
+  "color": {
+    "$type": "color",
+    "brand": {
+      "primary":   { "$value": { "colorSpace": "oklch", "components": [0.55, 0.19, 256], "hex": "#3b5bdb" } },
+      "secondary": { "$value": { "colorSpace": "oklch", "components": [0.62, 0.12, 200], "hex": "#1c8ab0" } },
+      "accent":    { "$value": { "colorSpace": "oklch", "components": [0.72, 0.17, 50],  "hex": "#f08c00" } }
+    },
+    "neutral": {
+      "50":  { "$value": { "colorSpace": "oklch", "components": [0.98, 0, 0],     "hex": "#f5f6f8" } },
+      "500": { "$value": { "colorSpace": "oklch", "components": [0.55, 0.01, 256], "hex": "#6b7280" } },
+      "900": { "$value": { "colorSpace": "oklch", "components": [0.21, 0.01, 256], "hex": "#1f2430" } }
+    },
+    "theme": {
+      "light": {
+        "bg": { "$value": { "colorSpace": "oklch", "components": [0.99, 0, 0],     "hex": "#fcfcfc" } },
+        "fg": { "$value": { "colorSpace": "oklch", "components": [0.21, 0.01, 256], "hex": "#1f2430" } }
+      },
+      "dark": {
+        "bg": { "$value": { "colorSpace": "oklch", "components": [0.18, 0.01, 256], "hex": "#15171c" } },
+        "fg": { "$value": { "colorSpace": "oklch", "components": [0.93, 0.005, 256], "hex": "#e9ebf0" } }
+      }
+    }
+  },
+  "$extensions": {
+    "com.risco.contrast": [
+      { "fg": "#1f2430", "bg": "#fcfcfc", "use": "body",  "logo": false },
+      { "fg": "#ffffff", "bg": "#3b5bdb", "use": "button", "logo": false },
+      { "fg": "#e9ebf0", "bg": "#15171c", "use": "body-dark", "logo": false }
+    ]
+  }
+}
+```
+
+The `$extensions["com.risco.contrast"]` array is what `scripts/verify.sh` reads to prove
+each text/bg pair clears AA. `"logo": true` exempts a pair from the 4.5:1 floor.
+
+## Tailwind v4 `@theme` + CSS custom-properties mapping
+
+Generate these from the tokens file; never hand-edit them — the JSON is the source.
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-brand-primary:   oklch(0.55 0.19 256);
+  --color-brand-secondary: oklch(0.62 0.12 200);
+  --color-brand-accent:    oklch(0.72 0.17 50);
+  --color-neutral-50:      oklch(0.98 0 0);
+  --color-neutral-500:     oklch(0.55 0.01 256);
+  --color-neutral-900:     oklch(0.21 0.01 256);
+  --color-bg:              oklch(0.99 0 0);
+  --color-fg:              oklch(0.21 0.01 256);
+}
+```
+
+## Dark-mode strategy
+
+- Define `bg`/`fg` per theme; keep `brand.*` anchored across both (recognition is constant).
+- Don't simply invert lightness — dark surfaces want slightly desaturated, slightly warmer
+  neutrals to avoid the "pure black + pure white" vibration. Re-check contrast in dark too.
+- Switch with a `prefers-color-scheme` media query or a `.dark` class that re-points the
+  `--color-bg`/`--color-fg` vars at the `theme.dark` token group.

package/skills/brand-identity/references/logo-and-assets.md

@@ -0,0 +1,117 @@
+# Logo brief & asset export
+
+Depth offloaded from SKILL.md: the variation grid with when-to-use each, clear-space and
+min-size formulas, the full export matrix with DPI, the favicon set with HTML markup and a
+`prefers-color-scheme` SVG snippet, and the file-naming convention.
+
+## Variation grid
+
+A logo is a system of variations, each earning its place by the context it survives.
+
+| Variation | Form | When to use |
+| --- | --- | --- |
+| Primary | Horizontal lockup (mark + wordmark) | Default — headers, docs, most digital |
+| Stacked | Vertical (mark over wordmark) | Square/tight slots, social avatars, merch |
+| Mark-only | The symbol alone | Favicons, app icons, watermarks, ≤32px |
+| Monochrome | Single ink (black, or white knockout) | One-color print, dark/photo backgrounds, embossing |
+
+Build and test the **monochrome** version first. If the mark dies in one ink — needs its
+gradient or two colors to read — it is too fragile and must be simplified before color work.
+
+## Clear-space formula
+
+Define clear space relative to the mark so it scales with the logo instead of breaking at
+small sizes:
+
+```text
+clear space = cap-height of the wordmark (or x-height of the mark), on all four sides
+```
+
+Nothing — text, other logos, page edges — intrudes inside that margin. Expressing it as a
+ratio (not a fixed px) means it stays correct from favicon to billboard.
+
+## Minimum sizes
+
+Below these, detail collapses and the mark stops reading:
+
+| Variation | Digital min | Print min |
+| --- | --- | --- |
+| Primary lockup | 24px wide | 10mm wide |
+| Stacked | 32px wide | 12mm wide |
+| Mark-only | 16px wide (favicon territory) | 6mm wide |
+
+## Export matrix
+
+Ship vector first; raster for the cases vector can't cover. 72 DPI digital, 300 DPI print.
+
+| Asset | Format | DPI | Notes |
+| --- | --- | --- | --- |
+| Logo, digital primary | SVG | n/a (vector) | Scales infinitely, smallest file |
+| Logo, raster transparency | PNG @1x/@2x | 72 | Transparent background |
+| Logo, print | PDF or JPEG | 300 | CMYK color, embed fonts/outline |
+| Mark, app icon | PNG | 72 | Square, safe-zone padded |
+
+## Favicon set (2025 baseline)
+
+Modern baseline: an SVG primary that can carry a `prefers-color-scheme` dark variant, with
+PNG/ICO fallbacks for engines that don't render SVG favicons (notably older Safari).
+
+| File | Size | Purpose |
+| --- | --- | --- |
+| `favicon.svg` | vector, <1KB | Primary; can embed dark-mode CSS |
+| `favicon.ico` | 16/32 multi | Legacy root fallback |
+| `favicon-16.png`, `favicon-32.png` | 16, 32 | Tab/bookmark raster |
+| `apple-touch-icon.png` | 180×180 | iOS home screen |
+| `android-chrome-192.png`, `-512.png` | 192, 512 | Android / PWA |
+| `site.webmanifest` | — | Declares the icon set + theme color |
+
+### HTML markup
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="32x32">
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<link rel="apple-touch-icon" href="/apple-touch-icon.png">
+<link rel="manifest" href="/site.webmanifest">
+```
+
+### Dark-mode favicon (SVG with `prefers-color-scheme`)
+
+An SVG favicon can flip its fill in dark UI chrome — one file, no extra requests:
+
+```html
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <style>
+    path { fill: #1f2430; }
+    @media (prefers-color-scheme: dark) { path { fill: #e9ebf0; } }
+  </style>
+  <path d="M6 6 H26 V26 H6 Z" />
+</svg>
+```
+
+## File-naming convention
+
+Predictable names keep the asset folder usable years later:
+
+```text
+brand/
+  logo-primary.svg        logo-primary@2x.png
+  logo-stacked.svg        logo-stacked@2x.png
+  logo-mark.svg           logo-mark@2x.png
+  logo-mono-black.svg     logo-mono-white.svg
+  logo-print.pdf
+  favicon.svg  favicon.ico  favicon-16.png  favicon-32.png
+  apple-touch-icon.png  android-chrome-192.png  android-chrome-512.png
+  site.webmanifest
+```
+
+Pattern: `logo-<variation>[-<modifier>][@<scale>].<ext>`. Lowercase, hyphenated, no spaces.
+
+## Misuse rules (do / don't)
+
+- DON'T stretch, squash, or rotate the mark — scale uniformly only.
+- DON'T recolor the logo off-palette or apply gradients/shadows not in the brief.
+- DON'T place the color logo on a busy/low-contrast background — switch to the mono knockout.
+- DON'T violate clear space or drop below the minimum size.
+- DON'T recreate the lockup by hand-typing the wordmark — use the supplied files.
+- DO use the variation that fits the slot (stacked for square, mark-only for ≤32px).
+- DO keep the accent reserved; the logo is not a place to introduce new colors.