dfinity · marc0olo · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026
@@ -0,0 +1,73 @@
+/* =========================================================
+   ICP / DFINITY Product Design Tokens
+   Source of truth: https://skills.internetcomputer.org
+   Version 1.0 — 2026
+   ========================================================= */
+
+:root {
+  /* --- Backgrounds --- */
+  --icp-bg:          #f8f5ef;  /* parchment — page background */
+  --icp-bg-elev:     #fdfaf3;  /* cream — cards, inputs, code headers */
+
+  /* --- Text --- */
+  --icp-fg:          #1a1714;  /* ink — headings, body */
+  --icp-muted:       #6b6660;  /* stone — subtext, captions */
+
+  /* --- Lines --- */
+  --icp-rule:        #e5ddcf;  /* tan — borders, dividers */
+
+  /* --- Accent / Brand --- */
+  --icp-accent:      #cc5a2b;  /* terracotta — primary brand color */
+  --icp-accent-dim:  #f2d7c7;  /* blush — callout / tinted background */
+
+  /* --- Code --- */
+  --icp-code-bg:     #efe8da;  /* sand — code surfaces */
+  --icp-code-fg:     #1a1714;
+
+  /* --- Fonts --- */
+  --icp-serif: "Newsreader", "Source Serif 4", "EB Garamond", ui-serif, Georgia, Cambria, "Times New Roman", serif;
+  --icp-sans:  "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --icp-mono:  ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+
+  /* --- Layout --- */
+  --icp-max:        68rem;   /* container  ~1088px */
+  --icp-max-prose:  48rem;   /* prose      ~768px  */
+  --icp-gutter:     1.75rem; /* 28px horizontal padding */
+
+  /* --- Radii --- */
+  --icp-r-sm: 3px;   /* inline code */
+  --icp-r-md: 6px;   /* buttons, pre, meta cards */
+  --icp-r-lg: 8px;   /* search, callout right-side */
+
+  /* --- Transitions --- */
+  --icp-transition: 0.15s ease;
+}
+
+/* Dark mode is opt-in only. Apply [data-theme="dark"] on <html> to activate.
+   We do NOT listen to prefers-color-scheme: light mode is the default
+   so that every product in the system looks the same out of the box. */
+
+/* Manual override — useful when a product ships its own theme switcher. */
+[data-theme="dark"] {
+  --icp-bg:         #14110d;
+  --icp-bg-elev:    #1b1812;
+  --icp-fg:         #f0ebe0;
+  --icp-muted:      #a29a8d;
+  --icp-rule:       #2d2820;
+  --icp-accent:     #ff7a4d;
+  --icp-accent-dim: #3a2218;
+  --icp-code-bg:    #1b1812;
+  --icp-code-fg:    #f0ebe0;
+}
+
+[data-theme="light"] {
+  --icp-bg:         #f8f5ef;
+  --icp-bg-elev:    #fdfaf3;
+  --icp-fg:         #1a1714;
+  --icp-muted:      #6b6660;
+  --icp-rule:       #e5ddcf;
+  --icp-accent:     #cc5a2b;
+  --icp-accent-dim: #f2d7c7;
+  --icp-code-bg:    #efe8da;
+  --icp-code-fg:    #1a1714;
+}
@@ -0,0 +1 @@
+../../.agents/skills/icp-brand-guidelines
@@ -4,6 +4,22 @@ Record decisions that constrain future work — things an agent needs to know th
 
 ---
 
+## 2026-04-23: icp-brand-guidelines skill lives directly in the repo
+
+**Context:** The `icp-brand-guidelines` skill was added to support design/brand work on the docs (CSS tokens, typography, voice). No upstream repo exists for it yet.
+**Decision:** Committed directly under `.agents/skills/icp-brand-guidelines/` (real directory, not a submodule). Symlinked from `.claude/skills/icp-brand-guidelines`. If the skill is later published to a DFINITY repo, migrate to a submodule then.
+**Rationale:** No upstream repo to pin. All other skills are submodule-backed; this is the only exception. The skill contains `SKILL.md` and `assets/tokens.css`.
+
+---
+
+## 2026-04-23: ICP brand guidelines applied to docs design
+
+**Context:** New `icp-brand-guidelines` skill defines the visual and verbal system for all DFINITY/ICP surfaces.
+**Decision:** Switched docs theme from dark-first/purple to light-default/terracotta. Newsreader serif added for headings. Custom `ThemeProvider` overrides Starlight's default to prevent auto-switching on `prefers-color-scheme`.
+**Rationale:** Brand skill spec: "Light mode is the default. Dark mode is opt-in. Never use `prefers-color-scheme` to auto-switch."
+
+---
+
 ## 2026-04-17: Added chain-fusion-signer, papi, ic-pub-key submodules
 **Context:** Page proposal #24 (chain-fusion signer guide) required source material not yet in `.sources/`
 **Decision:** Added three new release-pinned submodules: `chain-fusion-signer` (v0.3.0), `papi` (v0.1.1), `ic-pub-key` (v1.0.1)

@@ -210,6 +210,7 @@ For current release hashes, see `.sources/VERSIONS`.
 | `.sources/papi` | `dfinity/papi` | latest release | PAPI (payment API) — cycle payment interface used by the Chain Fusion Signer |
 | `.sources/ic-pub-key` | `dfinity/ic-pub-key` | latest release | `@dfinity/ic-pub-key` CLI tool for deriving public keys via the Chain Fusion Signer |
 | `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) |
+| `.agents/skills/icp-brand-guidelines` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand guidelines: colors, typography, voice, component patterns |
 | `.sources/internetidentity` | `dfinity/internet-identity` | `main` | Internet Identity spec (`docs/ii-spec.mdx`), Candid interface (`src/internet_identity/internet_identity.did`) |
 
 ### Submodule initialization
@@ -349,6 +350,8 @@ ls .agents/skills/icp-cli/SKILL.md .agents/skills/technical-documentation/SKILL.
 
 If no skill matches, use `technical-documentation` only. Topics with no dedicated icskill yet: on-chain AI, randomness/VRF, timers, Candid, chain-key tokens.
 
+**For design and brand work** (CSS, copy, UI components, docs styling, marketing copy) — load `icp-brand-guidelines` instead of or in addition to the above. This skill is not an icskill; it covers visual tokens, typography, voice, and component patterns for all surfaces under the DFINITY / Internet Computer mark.
+
 ## Frontmatter schema
 
 ```yaml

@@ -25,6 +25,7 @@ export default defineConfig({
       components: {
         EditLink: "./src/components/EditLink.astro",
         Footer: "./src/components/Footer.astro",
+        ThemeProvider: "./src/components/ThemeProvider.astro",
       },
       head: [
         {
@@ -98,6 +99,10 @@ export default defineConfig({
         "@fontsource/inter/500.css",
         "@fontsource/inter/600.css",
         "@fontsource/inter/700.css",
+        "@fontsource/newsreader/400.css",
+        "@fontsource/newsreader/400-italic.css",
+        "@fontsource/newsreader/500.css",
+        "@fontsource/newsreader/500-italic.css",
         "./src/styles/custom.css",
       ],
       social: [

@@ -15,6 +15,7 @@
   "dependencies": {
     "@astrojs/starlight": "^0.38.1",
     "@fontsource/inter": "^5.2.8",
+    "@fontsource/newsreader": "^5.2.10",
     "astro": "^6.1.8",
     "sharp": "^0.34.2"
   },

@@ -0,0 +1,41 @@
+---
+---
+
+{/* Inlined to avoid FOUC. Defaults to light; dark is opt-in. Never auto-switches on prefers-color-scheme. */}
+<script is:inline>
+	window.StarlightThemeProvider = (() => {
+		const storedTheme =
+			typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+		const theme = storedTheme || 'light';
+		document.documentElement.dataset.theme = theme === 'dark' ? 'dark' : 'light';
+		return {
+			updatePickers(theme = storedTheme || 'auto') {
+				document.querySelectorAll('starlight-theme-select').forEach((picker) => {
+					const select = picker.querySelector('select');
+					if (select) select.value = theme;
+					/** @type {HTMLTemplateElement | null} */
+					const tmpl = document.querySelector(`#theme-icons`);
+					const newIcon = tmpl && tmpl.content.querySelector('.' + theme);
+					if (newIcon) {
+						const oldIcon = picker.querySelector('svg.label-icon');
+						if (oldIcon) {
+							oldIcon.replaceChildren(...newIcon.cloneNode(true).childNodes);
+						}
+					}
+				});
+			},
+		};
+	})();
+</script>
+
+<template id="theme-icons">
+	<svg class="light" aria-hidden="true" width="1em" height="1em" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M5 12a1 1 0 0 0-1-1H3a1 1 0 0 0 0 2h1a1 1 0 0 0 1-1Zm.64 5-.71.71a1 1 0 0 0 0 1.41 1 1 0 0 0 1.41 0l.71-.71A1 1 0 0 0 5.64 17ZM12 5a1 1 0 0 0 1-1V3a1 1 0 0 0-2 0v1a1 1 0 0 0 1 1Zm5.66 2.34a1 1 0 0 0 .7-.29l.71-.71a1 1 0 1 0-1.41-1.41l-.66.71a1 1 0 0 0 0 1.41 1 1 0 0 0 .66.29Zm-12-.29a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.71-.71a1.004 1.004 0 1 0-1.43 1.41l.73.71ZM21 11h-1a1 1 0 0 0 0 2h1a1 1 0 0 0 0-2Zm-2.64 6A1 1 0 0 0 17 18.36l.71.71a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.76-.66ZM12 6.5a5.5 5.5 0 1 0 5.5 5.5A5.51 5.51 0 0 0 12 6.5Zm0 9a3.5 3.5 0 1 1 0-7 3.5 3.5 0 0 1 0 7Zm0 3.5a1 1 0 0 0-1 1v1a1 1 0 0 0 2 0v-1a1 1 0 0 0-1-1Z"/>
+	</svg>
+	<svg class="dark" aria-hidden="true" width="1em" height="1em" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M21.64 13a1 1 0 0 0-1.05-.14 8.049 8.049 0 0 1-3.37.73 8.15 8.15 0 0 1-8.14-8.1 8.59 8.59 0 0 1 .25-2A1 1 0 0 0 8 2.36a10.14 10.14 0 1 0 14 11.69 1 1 0 0 0-.36-1.05Zm-9.5 6.69A8.14 8.14 0 0 1 7.08 5.22v.27a10.15 10.15 0 0 0 10.14 10.14 9.784 9.784 0 0 0 2.1-.22 8.11 8.11 0 0 1-7.18 4.32v-.04Z"/>
+	</svg>
+	<svg class="auto" aria-hidden="true" width="1em" height="1em" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M21 14h-1V7a3 3 0 0 0-3-3H7a3 3 0 0 0-3 3v7H3a1 1 0 0 0-1 1v2a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3v-2a1 1 0 0 0-1-1ZM6 7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v7H6V7Zm14 10a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-1h16v1Z"/>
+	</svg>
+</template>