/* ────────────────────────────────────────────────────────────────── * Communikit Design System — Community theming contract * * @version 1.0.0 * @updated 14 September 2026 * @companion ./preview/community-theming.html (explanatory; NOT normative) * * THIS FILE IS NORMATIVE. The prose page explains the reasoning and * shows the worked examples; where the two disagree, this file wins. * It lives beside colors_and_type.css rather than under preview/ * because it is part of the token layer, not documentation of it. * * SCOPE MECHANISM — [data-community=""], exactly parallel to * [data-theme="dark"]. The two compose: a scope block is written once * for light and once for dark, and the dark selector must cover both * nesting orders (attribute on the same element, or on a descendant). * * light * dark * * ONE INPUT. A community supplies --community-seed (their primary * colour) and a logo. Nothing else. Every brand token below is DERIVED * from the seed by the rules in this header — generated at provisioning * time, never hand-picked. Role-by-role supply is rejected: the point * of the contract is that a new customer is not a design job, and ten * hand-picked roles is exactly a design job with no one checking it. * * ── THE THREE SETS ─────────────────────────────────────────────── * * OVERRIDABLE (10) — these take the community's hue. Under one-hue-in * the overridable set and the derived set are the same ten tokens; the * distinction would only matter if we accepted role-by-role supply, * which we do not. * --brand-indicator --brand-icon --brand-text --brand-surface * --brand-surface-selected --brand-fill --brand-fill-hover * --brand-fill-press --focus-ring --focus-ring-on-brand * Plus five dependents that must be restated in every scope because a * :root alias does not re-resolve here: * --fg-on-brand --fg-on-tint --border-tinted * --dark-brand-fg --dark-brand-text-fg * * FIXED — everything else. Named in full on the companion page. The * three that matter most: the neutral --ink-* ramp and every surface * and text alias over it; the semantic set (--danger-* --warning-* * --info-* --severity-*); and the --cat-* category pairs. An alert must * read as an alert in every community — that is a safety argument, not * a brand one — and the category pairs were contrast-tuned one at a * time, so a community hue dropped into a pair breaks a ratio that * currently passes. * * DERIVED — the rule for each of the ten, in OKLCH, hue held at every * step so a derived value still reads as the community's colour: * --brand-indicator the seed, unmodified. No ratio applies. * --brand-fill the seed, unless BOTH white and ink fail * 4.5:1 on it; then L walks down until * white clears. See the label-flip ladder. * --fg-on-brand white or --ink-900, whichever clears * 4.5:1 on --brand-fill; if both, the higher. * --brand-text L walks down from the seed until it * clears 4.5:1 on --brand-surface (the * binding surface — it is darker than white). * --brand-icon L walks down until 3:1 on --white. * --brand-surface L 0.94, chroma capped 0.045. * --brand-surface-selected L 0.965, chroma capped 0.030. * --brand-fill-hover --brand-fill at L −0.04. * --brand-fill-press --brand-fill at L −0.08. * --focus-ring = --brand-text. * --focus-ring-on-brand white or --ink-900, whichever clears 3:1 * on --brand-indicator. NOT fixed at ink: * ink on Harbourview's navy is 1.39:1. * --dark-brand-fg L 0.78, chroma capped 0.17. * --dark-brand-text-fg = --dark-brand-fg unless it misses 4.5:1 * on --dark-card. * Near-neutral clamp: below 0.02 chroma the seed's hue is undefined, so * derive the two tints neutral and skip the hue rotation entirely. * * ── DRIFT TOLERANCE ────────────────────────────────────────────── * Measured as OKLCH ΔL between --community-seed and --brand-text: * ≤ 0.12 ships silently. * 0.12–0.25 ships, flagged at provisioning, stated in writing to the * customer before launch: "your links will read deeper than * your brand colour". * > 0.25 BLOCKED. Back to the customer. One documented escape and * one only: they may supply a second value, a text anchor, * used for --brand-text / --brand-icon / --focus-ring while * --brand-indicator and --brand-fill keep the seed. This is * the single exception to one-hue-in and exists because the * alternative — shipping brown links under a yellow brand — * is worse than one extra field on a form. * * ── SEVERITY COLLISION ─────────────────────────────────────────── * Any seed within ΔE 0.12 of a locked severity colour trips a flag at * provisioning. Severity does not move, so three rules apply instead: * severity always carries its WORD ("Critical", "Warning"); severity * carries its SHAPE (octagon, triangle); and the community colour may * not fill a feed-level banner or card. Chrome, nav, buttons, avatars * yes; a full-width tinted block in the feed no. * ────────────────────────────────────────────────────────────────── */ /* ── Harbourview — deep navy #1B2A5E ───────────────────────────── * The uneventful case. Seed kept as indicator, fill, text and icon: * white on it is 13.64:1, and as text it is 11.33:1 on its own tint. * ΔL drift 0.00. No severity collision. * The one thing that does NOT sit at its default: --focus-ring-on-brand. * Ink on this navy is 1.39:1 — invisible — so the ring goes white. */ [data-community="harbourview"]{ --community-seed: #1B2A5E; --brand-indicator: #1B2A5E; --brand-icon: #1B2A5E; /* 13.6:1 on white, well past the 3:1 graphic bar */ --brand-text: #1B2A5E; /* 13.6:1 on white, 11.33:1 on --brand-surface */ --brand-surface: #DEEBFF; --brand-surface-selected: #EBF3FF; --brand-fill: #1B2A5E; /* white label 13.64:1 */ --brand-fill-hover: #121F52; --brand-fill-press: #0A1547; --focus-ring: #1B2A5E; --focus-ring-on-brand: #FFFFFF; /* 13.64:1; --ink-900 would be 1.39:1 */ --fg-on-brand: #FFFFFF; --fg-on-tint: #1B2A5E; --border-tinted: #DEEBFF; --dark-brand-fg: #9EB5F5; --dark-brand-text-fg: #9EB5F5; } [data-community="harbourview"][data-theme="dark"], [data-community="harbourview"] [data-theme="dark"]{ --brand-indicator: #9EB5F5; --brand-icon: #9EB5F5; --brand-text: #9EB5F5; --brand-surface: #161D31; --brand-surface-selected: #1C2440; --brand-fill: #9EB5F5; --brand-fill-hover: #B4C6F8; --brand-fill-press: #C6D4FA; --focus-ring: #9EB5F5; --focus-ring-on-brand: #0B0F14; --fg-on-brand: #0B0F14; --fg-on-tint: #9EB5F5; --border-tinted: #161D31; } /* ── Kettle Falls — warm red #C4362B ──────────────────────────── * Seed kept as the fill: white label 5.37:1. The TEXT variant darkens * by ΔL 0.01 to #C03228, because the seed measured 4.36:1 on its own * tint. Inside tolerance, ships silently. * COLLISION FLAGGED: ΔE 0.048 from --severity-critical-fill and 0.058 * from --danger. Indistinguishable by hue. Severity tokens untouched. */ [data-community="kettle-falls"]{ --community-seed: #C4362B; --brand-indicator: #C4362B; --brand-icon: #C03228; --brand-text: #C03228; --brand-surface: #FFE1DA; --brand-surface-selected: #FFECE8; --brand-fill: #C4362B; /* white label 5.37:1 */ --brand-fill-hover: #B6271E; --brand-fill-press: #A8140F; --focus-ring: #C03228; --focus-ring-on-brand: #FFFFFF; /* 5.37:1; --ink-900 is 3.02:1 — white is the higher */ --fg-on-brand: #FFFFFF; --fg-on-tint: #C03228; --border-tinted: #FFE1DA; --dark-brand-fg: #FF8876; --dark-brand-text-fg: #FF8876; } [data-community="kettle-falls"][data-theme="dark"], [data-community="kettle-falls"] [data-theme="dark"]{ --brand-indicator: #FF8876; --brand-icon: #FF8876; --brand-text: #FF8876; --brand-surface: #2E1613; --brand-surface-selected: #3A1C18; --brand-fill: #FF8876; --brand-fill-hover: #FF9C8C; --brand-fill-press: #FFAEA1; --focus-ring: #FF8876; --focus-ring-on-brand: #0B0F14; --fg-on-brand: #0B0F14; --fg-on-tint: #FF8876; --border-tinted: #2E1613; } /* ── Sundre Flats — mid-yellow #F2C14E ────────────────────────── * The case the contract exists for. Two guardrails fail outright on * the seed and the ladder has to be walked for both: * * --brand-fill white on the seed is 1.68:1 — fails 4.5:1 badly. * Ladder step 2: the LABEL flips to --ink-900 at * 11.3:1 and the fill keeps the seed exactly. The * customer's colour survives on the largest surface * in their app. * --brand-icon the seed is 1.68:1 on white, under the 3:1 graphic * bar. Walks down to #BC8600 at 3.1:1. * --brand-text the seed cannot clear 4.5:1 on its own tint at any * nearby lightness. Walks down to #8E6100 — 5.45:1 on * white, 4.94:1 on --brand-surface. * * DRIFT: ΔL 0.35 from seed to text. Over the 0.25 bar, so this theme * was BLOCKED at provisioning and escalated. Resolution on file: the * village supplied a text anchor (#8E6100, which is where the * derivation landed anyway) and signed off that links and active tabs * read brown while chrome, buttons and the app tile stay yellow. This * is the documented escape, used as intended — not a silent override. * * No severity collision: ΔE 0.31 from --warning, the nearest locked * value. Adjacency to --warning / --cat-jobs-* is a visual-hierarchy * question, not a safety one, and is handled by the feed-block rule. */ [data-community="sundre-flats"]{ --community-seed: #F2C14E; --brand-indicator: #F2C14E; /* seed, unmodified — nothing sits on it */ --brand-icon: #BC8600; /* 3.1:1 on white */ --brand-text: #8E6100; /* 5.45:1 white, 4.94:1 on --brand-surface */ --brand-surface: #FDF3DC; --brand-surface-selected: #FFFAEC; --brand-fill: #F2C14E; /* seed kept; the LABEL flipped instead */ --brand-fill-hover: #E3B23C; --brand-fill-press: #D4A32B; --focus-ring: #8E6100; /* 5.45:1 on white */ --focus-ring-on-brand: #0B0F14; /* 11.3:1; white would be 1.68:1 */ --fg-on-brand: #0B0F14; /* ink, not white — 11.3:1 */ --fg-on-tint: #8E6100; --border-tinted: #FDF3DC; --dark-brand-fg: #EFBE52; --dark-brand-text-fg: #EFBE52; } [data-community="sundre-flats"][data-theme="dark"], [data-community="sundre-flats"] [data-theme="dark"]{ --brand-indicator: #EFBE52; --brand-icon: #EFBE52; --brand-text: #EFBE52; --brand-surface: #2B2109; --brand-surface-selected: #362A0D; --brand-fill: #EFBE52; --brand-fill-hover: #F4CA6B; --brand-fill-press: #F8D583; --focus-ring: #EFBE52; --focus-ring-on-brand: #0B0F14; --fg-on-brand: #0B0F14; --fg-on-tint: #EFBE52; --border-tinted: #2B2109; }