{ "name": "Protocol Institute Brand Kit", "version": "1.1.0", "summary": "Single source of truth for the Protocol Institute brand. Tokens encode DECISIONS (intent), not raw values — choose a decision token by context, never a bare hex or pixel. Two veins (institute, protocolized) share one token system and differ by typeface emphasis, color emphasis, and imagery.", "principles": [ "Decisions over values: reference `color.decision.*`, not `color.primitive.*`, in product code.", "Closed sets: the menus below are exhaustive. If a need is not covered, extend the system in this file first, then use it — do not invent ad-hoc values.", "Light is the default surface, but DARK SURFACES are first-class: heroes, CTA bands, and footers use `surface-dark` + the `on-dark*` tokens. (This is not a dark MODE / user toggle — there is still no light/dark switch.) Any text or chrome that can overlap a dark surface needs an on-dark color.", "Build with the component + behavior layer (brand.css `.pi-*` classes + brand.js), not raw tokens alone — the components have spacing, contrast, and responsive behavior baked in. Only compose a new component (from `components.rules` + decision tokens) when one is genuinely missing.", "Quality is verified, not assumed: run `scripts/contrast-check.mjs` and `scripts/preflight.mjs`, and the Playwright `scripts/qc.md` definition-of-done, before shipping an artifact." ], "veins": { "institute": { "label": "Protocol Institute — Research / Reports / SIGs", "use_when": "Working-group outputs, SIG write-ups, research reports, challenges, formal institutional pages.", "color_emphasis": "color.decision.action-primary (cobalt) for CTAs and emphasis; restrained accent use.", "type_emphasis": "Serif display (Computer Modern preferred, Instrument Serif fallback) + Lora body; precise, structured.", "imagery_emphasis": ["technical-schematic", "abstract-geometric", "figure-portrait"], "voice": "voice.institute" }, "protocolized": { "label": "Protocolized — The Magazine of New Nature", "use_when": "Magazine pieces: Non-Fiction (Studies / Obliquities / Science) and Fiction. Editorial, cover-art-led layouts.", "color_emphasis": "color.decision.action-secondary (forest green) is the site-current live accent; accent rust for 'Featured'.", "type_emphasis": "Instrument Serif display at weight 400 (never bold) + Lora body; literary, exploratory.", "imagery_emphasis": ["painterly-illustration", "retro-vintage", "surreal-collage", "photographic"], "voice": "voice.protocolized_nonfiction" } }, "color": { "primitive": { "cobalt-600": "#004fcc", "cobalt-500": "#0064ff", "cobalt-050": "#e6efff", "forest-700": "#085041", "forest-600": "#0f6e56", "forest-050": "#e1f5ee", "rust-700": "#9e3d18", "rust-500": "#d85a30", "rust-050": "#faece7", "paper": "#f9f8f5", "white": "#ffffff", "gray-100": "#f3f4f6", "gray-200": "#e5e7eb", "ink-900": "#2c2c2a", "ink-600": "#5f5e5a", "forest-950": "#0a1f17", "mint-200": "#bff0dd", "on-dark-muted": "#bac0bd" }, "decision": { "action-primary": { "value": "#0064ff", "ref": "cobalt-500", "usage": "Primary CTA fill, link emphasis, brand-forward highlight. Brand-kit primary (aspirational; see note). Pair with on-action text." }, "action-primary-pressed":{ "value": "#004fcc", "ref": "cobalt-600", "usage": "Pressed/hover state of action-primary." }, "action-primary-tint": { "value": "#e6efff", "ref": "cobalt-050", "usage": "Pale highlight background behind primary-colored elements." }, "action-secondary": { "value": "#0f6e56", "ref": "forest-600", "usage": "What protocolized.io renders today for CTAs, the italic tagline, secondary CTA border, Framework badge, focus ring. Use to match the live site." }, "action-secondary-deep": { "value": "#085041", "ref": "forest-700", "usage": "Text on the Framework badge tint." }, "action-secondary-tint": { "value": "#e1f5ee", "ref": "forest-050", "usage": "Framework badge background; soft mint fill." }, "accent": { "value": "#d85a30", "ref": "rust-500", "usage": "Reserved emphasis fill/glyph: the 'Featured' badge background-adjacent accent and very limited inline accents. As TEXT, only on white/paper at large sizes — see accent-deep for small text on accent-tint." }, "accent-deep": { "value": "#9e3d18", "ref": "rust-700", "usage": "Accent as TEXT where small/normal-size: the 'Featured' badge label on accent-tint. Meets WCAG AA (4.5:1) where bare accent (#d85a30) does not (3.36:1)." }, "accent-tint": { "value": "#faece7", "ref": "rust-050", "usage": "Featured badge background." }, "background-canvas": { "value": "#f9f8f5", "ref": "paper", "usage": "Page background — warm paper." }, "background-surface": { "value": "#ffffff", "ref": "white", "usage": "Cards, section bands, top nav, footer." }, "background-muted": { "value": "#f3f4f6", "ref": "gray-100", "usage": "Chips, pills, quiet section dividers." }, "border-hairline": { "value": "#e5e7eb", "ref": "gray-200", "usage": "1px borders on cards, inputs, nav underline, footer top border." }, "text-heading": { "value": "#2c2c2a", "ref": "ink-900", "usage": "Headlines and body emphasis." }, "text-body": { "value": "#2c2c2a", "ref": "ink-900", "usage": "Default body text." }, "text-secondary": { "value": "#5f5e5a", "ref": "ink-600", "usage": "Dek, breadcrumb, meta, captions, chips, footer links. The lightest text color that still passes AA on paper (6.11:1) — do NOT use a lighter grey for text (a #a3a3ab muted nav grey is only 2.36:1 and fails)." }, "on-action": { "value": "#ffffff", "ref": "white", "usage": "Text on action-primary / action-secondary / accent fills." }, "surface-dark": { "value": "#0a1f17", "ref": "forest-950","usage": "Dark New-Nature green band: hero backgrounds, CTA sections, dark slides, footers. Put on-dark* text/chrome on it." }, "on-dark": { "value": "#ffffff", "ref": "white", "usage": "Primary text / chrome on surface-dark (≈16:1)." }, "on-dark-muted": { "value": "#bac0bd", "ref": "on-dark-muted","usage": "Secondary text on surface-dark (AA-safe ≈8.3:1). Use instead of dark text-secondary, which fails on dark." }, "on-dark-line": { "value": "#bff0dd", "ref": "mint-200", "usage": "Active marker / accent / mint button on surface-dark." } }, "note": "The brand-kit PRIMARY is electric cobalt (#0064ff), aspirational and sourced from the Substack surface. The live protocolized.io still serves forest green (#0f6e56) as action-secondary. Use cobalt for new artifacts; use green to match the current production site.", "accessibility": { "note": "Verified by scripts/contrast-check.mjs (WCAG 2.1) — claims here are TESTED, not asserted. White on-action meets AA for normal text on action-primary, action-primary-pressed, and action-secondary. White on accent (#d85a30) is 3.87:1 — large-text / non-text ONLY, never small body text. The 'Featured' badge label uses accent-deep (#9e3d18), not bare accent, to meet AA on accent-tint (bare accent is 3.36:1). Cobalt link on paper is 4.63:1 — passes AA with little headroom; avoid sub-16px cobalt links on paper. text-secondary (#5f5e5a) is the lightest AA-safe text on paper (6.11:1) — a lighter muted grey (#a3a3ab) fails (2.36:1). On DARK surfaces, dark text fails (e.g. text-heading on surface-dark is 1.23:1): use on-dark / on-dark-muted, which is why chrome over a dark hero/CTA must flip (brand.js does this automatically via .pi-on-dark). Do not place text-secondary on action fills.", "thresholds": { "text": 4.5, "large": 3.0, "ui": 3.0, "_unit": "WCAG 2.1 minimum contrast ratio; text=normal (<24px / <18.66px bold), large=larger, ui=graphical/border (1.4.11)" }, "test": "node scripts/contrast-check.mjs", "pairings": [ { "fg": "text-body", "bg": "background-canvas", "kind": "text", "label": "Body text on paper" }, { "fg": "text-body", "bg": "background-surface", "kind": "text", "label": "Body text on white" }, { "fg": "text-body", "bg": "background-muted", "kind": "text", "label": "Body text on muted" }, { "fg": "text-secondary", "bg": "background-canvas", "kind": "text", "label": "Secondary text on paper" }, { "fg": "text-secondary", "bg": "background-surface", "kind": "text", "label": "Secondary text on white" }, { "fg": "text-secondary", "bg": "background-muted", "kind": "text", "label": "Secondary text on muted" }, { "fg": "action-primary", "bg": "background-canvas", "kind": "text", "label": "Cobalt link on paper" }, { "fg": "action-primary", "bg": "background-surface", "kind": "text", "label": "Cobalt link on white" }, { "fg": "action-secondary", "bg": "background-canvas", "kind": "text", "label": "Green link on paper" }, { "fg": "action-secondary", "bg": "background-surface", "kind": "text", "label": "Green link on white" }, { "fg": "on-action", "bg": "action-primary", "kind": "text", "label": "White on cobalt button" }, { "fg": "on-action", "bg": "action-primary-pressed","kind": "text", "label": "White on cobalt (pressed)" }, { "fg": "on-action", "bg": "action-secondary", "kind": "text", "label": "White on green button" }, { "fg": "on-action", "bg": "accent", "kind": "large", "label": "White on rust (large / UI only)" }, { "fg": "action-secondary-deep","bg": "action-secondary-tint", "kind": "text", "label": "Framework badge text" }, { "fg": "accent-deep", "bg": "accent-tint", "kind": "text", "label": "Featured badge text" }, { "fg": "action-primary-pressed","bg": "action-primary-tint", "kind": "text", "label": "Secondary-button hover text" }, { "fg": "on-dark", "bg": "surface-dark", "kind": "text", "label": "Text/chrome on dark surface" }, { "fg": "on-dark-muted", "bg": "surface-dark", "kind": "text", "label": "Secondary text on dark surface" }, { "fg": "surface-dark", "bg": "on-dark-line", "kind": "text", "label": "Mint button label (on-dark)" }, { "fg": "on-dark-line", "bg": "surface-dark", "kind": "ui", "label": "Active marker / accent on dark" }, { "fg": "border-hairline", "bg": "background-surface", "kind": "ui", "label": "Hairline border on white", "note": "decorative" } ] } }, "typography": { "load": "REQUIRED: link brand.css (it @imports Instrument Serif, Lora, Outfit) or add the Google Fonts . Declaring the stacks without loading the webfonts yields system fallbacks. Headings must render in Instrument Serif at weight 400 — verify after applying.", "fonts": { "serif": { "stack": "\"Computer Modern Serif\", \"CMU Serif\", \"Latin Modern Roman\", \"Instrument Serif\", Georgia, serif", "role": "Display + all headings; the italic tagline. Brand-kit prefers Computer Modern; the live site serves Instrument Serif." }, "body": { "stack": "\"Computer Modern Serif\", \"CMU Serif\", \"Latin Modern Roman\", Lora, Georgia, serif", "role": "Long-form prose, default body, dek." }, "sans": { "stack": "Outfit, system-ui, sans-serif", "role": "UI labels, buttons, badges, chips, breadcrumbs, meta, nav." }, "mono": { "stack": "\"JetBrains Mono\", \"Courier New\", monospace", "role": "Code and tokens." } }, "scale": { "hero-display": { "font": "serif", "size": "72px", "weight": 400, "leading": "72px", "tracking": "-1.8px", "use": "Homepage hero H1" }, "detail-display": { "font": "serif", "size": "48px", "weight": 400, "leading": "48px", "use": "Detail/page H1" }, "page-h1": { "font": "serif", "size": "36px", "weight": 400, "leading": "40px", "use": "Index page H1" }, "tagline-italic": { "font": "serif", "size": "30px", "weight": 400, "leading": "36px", "style": "italic", "color": "action (vein-dependent)", "use": "Tagline 'Accelerating Order.'" }, "heading-section":{ "font": "serif", "size": "24px", "weight": 400, "leading": "32px", "use": "Section H2" }, "heading-card": { "font": "serif", "size": "20px", "weight": 400, "leading": "28px", "use": "Card titles" }, "prose-lead": { "font": "body", "size": "18px", "weight": 400, "leading": "29px", "color": "text-secondary", "use": "Lead/dek" }, "body-md": { "font": "body", "size": "16px", "weight": 400, "leading": "24px", "use": "Default body" }, "body-strong": { "font": "body", "size": "16px", "weight": 700, "leading": "24px", "use": "Bold term in prose" }, "button": { "font": "sans", "size": "16px", "weight": 500, "leading": "24px", "use": "Buttons" }, "nav-link": { "font": "sans", "size": "14px", "weight": 400, "leading": "20px", "use": "Nav, footer links, meta" }, "caption": { "font": "sans", "size": "12px", "weight": 500, "leading": "16px", "use": "Badges, chips, filter pills" } }, "rules": [ "Headlines are weight 400 (regular). Never set display headings to 600/700.", "The tagline is italic serif in the vein's action color.", "Serif for anything 18px and up; sans only for UI <=16px." ] }, "space": { "xxs": "4px", "xs": "8px", "sm": "12px", "md": "16px", "lg": "20px", "xl": "24px", "xxl": "32px", "section": "64px", "section-lg": "112px" }, "radius": { "sm": "4px", "md": "8px", "lg": "12px", "pill": "9999px" }, "shadow": { "card-hover": "0 1px 2px 0 rgb(0 0 0 / 0.05)", "default": "0 1px 3px 0 rgb(0 0 0 / 0.10), 0 1px 2px -1px rgb(0 0 0 / 0.10)" }, "components": { "button-primary": { "bg": "action-primary", "text": "on-action", "type": "button", "radius": "md", "padding": "12px 24px" }, "button-secondary": { "bg": "transparent", "text": "action-primary", "border": "1px solid action-primary", "type": "button", "radius": "md", "padding": "12px 24px" }, "button-link": { "bg": "transparent", "text": "action-primary", "type": "nav-link", "suffix": "→" }, "badge-framework": { "bg": "action-secondary-tint", "text": "action-secondary-deep", "type": "caption", "radius": "pill", "padding": "2px 10px" }, "badge-featured": { "bg": "accent-tint", "text": "accent-deep", "type": "caption", "radius": "pill", "padding": "2px 10px" }, "tag-chip": { "bg": "background-muted", "text": "text-secondary", "type": "nav-link", "radius": "pill", "padding": "6px 12px" }, "card": { "bg": "background-surface", "border": "1px solid border-hairline", "radius": "md", "padding": "20px", "shadow": "none; card-hover on hover" }, "swatch": { "derived": "A color specimen: filled rounded-md chip + decision token name (mono) + hex, click-to-copy the token name. Derive from radius.md + border-hairline + text-secondary caption." }, "download-button": { "derived": "A button-secondary with a leading download glyph; same tokens as button-secondary." }, "site-header": { "layout": "The Protocol Institute wordmark anchored TOP-LEFT; page/local brand + nav on the RIGHT.", "nav": "Menu/nav links are UPPERCASE, sans (Outfit), letter-spacing ~0.05em — matching protocol-institute.org.", "classes": ".pi-topnav (uppercase links), .pi-wordmark (left anchor)." }, "wordmark": { "lockup": "P-mark + 'The Protocol Institute' set in the serif display face (Instrument Serif). Place as the TOP-LEFT anchor of every page header. On a dark surface add .pi-on-dark.", "link": "https://protocol-institute.org/", "class": ".pi-wordmark / .pi-wordmark.pi-on-dark" }, "section-head": { "class": ".pi-section-head", "use": "Centered eyebrow + title (+ optional lead) intro above a grid. Prevents left-scrunched single-column text. Contains a .pi-eyebrow." }, "eyebrow": { "class": ".pi-eyebrow", "use": "Uppercase kicker above a title; carries the label→title gap so it never collides with the heading." }, "card-media": { "class": ".pi-card .pi-card--media", "structure": "
…
", "use": "Link-preview / image card. Drop in the target page's og:image. Image is full-bleed via max-width:none + overflow:hidden (avoids the img{max-width:100%} footgun)." }, "figure-cta": { "class": ".pi-figure-cta", "structure": "
…buttons…
", "use": "A feature image with CTA button(s) overlaid on a bottom scrim. Use .pi-btn--on-image for ghost buttons over imagery." }, "gutter-nav": { "class": ".pi-gutter (links href='#section')", "behavior": "brand.js adds .is-active via scroll-spy and flips .pi-on-dark over dark surfaces. Active state is the cobalt LINE, not a hard color, so it survives the on-dark flip.", "desktop_only": "shows ≥1240px; pair with .pi-hamburger + .pi-mobile-menu below it." }, "mobile-menu": { "classes": ".pi-hamburger (button, data-pi-menu='#id') + .pi-mobile-menu#id", "behavior": "brand.js toggles .is-open; links close it. Hamburger shows <760px. Required because the gutter is desktop-only." }, "button-on-image": { "class": ".pi-btn.pi-btn--on-image", "use": "Ghost button with light border/text for placement over imagery (on a scrim)." } }, "components_rules": [ "Pills/badges/chips use radius.pill. Cards/buttons/inputs use radius.md.", "Cards have a 1px border-hairline and no resting shadow; shadow.card-hover appears only on hover.", "Missing component? Compose it from decision tokens + these radius/hairline/type roles. Keep the closed token set.", "Page header: nav/menu links are UPPERCASE; the 'The Protocol Institute' wordmark (serif) is anchored top-left and links to protocol-institute.org.", "Vertical rhythm: a label/eyebrow needs the gap-label-title space above its title, title→body uses gap-title-body, groups gap-group — inside-group gaps must be smaller than between-group. Never let a kicker sit ~0px above its title.", "Full-bleed images inside a card: a global img{max-width:100%} will silently cap them — use .pi-card--media (max-width:none + overflow:hidden) instead of a negative-margin hack.", "Buttons set their own text color; if your page has a global a{color:…} reset, it can override .pi-btn — keep the a.pi-btn rules from brand.css (they outrank it).", "No emoji in product UI; draw glyphs with CSS (e.g. the .pi-hamburger bars) or use brand marks." ], "build": { "summary": "Build WITH the component + behavior layer, not raw tokens. Link both files once.", "head": "", "files": { "css": "brand.css (tokens + .pi-* components)", "js": "brand.js (mobile menu, gutter scroll-spy, on-dark auto-flip)", "favicon": "favicon.svg (the cobalt P-mark)" }, "behavior_hooks": [ "Mark dark bands with data-pi-surface=\"dark\" so dark-aware chrome flips automatically.", "Mark chrome that overlaps dark bands with data-pi-dark-aware (the .pi-gutter is handled for you).", "Hamburger: