feat(brand): adopt official Kode brand guidelines

- Brand palette: purple #6B35A7 (primary), #000000 (ink), #FFFFFF, #F5F4F0 (canvas)
- Typography: Manrope (UI, 200-800) + Opificio Bold (wordmark/display); drop Inter
- design.md: add wordmarkSecondary token, new display scale (Opificio 72/80)
- foundations: refresh swatches and typography README to match guidelines
- assets/fonts: replace Inter folder with Manrope; add Opificio cuts (Bold/Rounded/Regular)
- fonts.css: register Manrope variable + Opificio cuts; keep Roboto Mono for code only
- examples/web: render the kode wordmark lockup on the off-white canvas
- brand-guidelines: real specs (lockup, palette, typography, logo variant rules)
- README: add brand-at-a-glance, bump version to beta

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -1,9 +1,19 @@
-# KDC Design System
+# Kode Design Consultants — Design System
 
-The official design system for KDC — tokens, components, brand assets, and guidelines for building consistent KDC product and brand experiences.
+The official design system for **Kode Design Consultants Ltd** (KDC) — tokens, components, brand assets, and guidelines for building consistent product and brand experiences.
 
 > The single source of truth lives in [`design.md`](./design.md), which encodes the design tokens (colors, typography, spacing, radii, components) in the [google-labs-code/design.md](https://github.com/google-labs-code/design.md) format.
 
+## Brand at a glance
+
+| | |
+|--|--|
+| Wordmark | `kode` set in **Opificio Bold** (72pt / 52pt) |
+| Secondary line | `design consultants` in **Manrope ExtraLight** (20pt / 76pt) |
+| Brand color | Kode purple `#6B35A7` |
+| Supporting | Black `#000000`, White `#FFFFFF`, Off-white `#F5F4F0` |
+| UI typeface | **Manrope** (200–800) |
+
 ## Repository structure
 
 ```
@@ -12,7 +22,7 @@ KDCDesignSystem/
 ├── brand/                     # Logos, wordmarks, brand guidelines
 ├── tokens/                    # Generated/exported design tokens
 ├── foundations/               # Color, type, spacing, motion, grid, breakpoints
-├── assets/                    # Fonts, icons, illustrations, images, patterns
+├── assets/                    # Fonts (Manrope + Opificio), icons, illustrations
 ├── components/                # Per-component specs and anatomy
 ├── themes/                    # Light, dark, high-contrast theme overrides
 ├── templates/                 # Web, mobile, email, print, presentation
@@ -29,7 +39,7 @@ KDCDesignSystem/
 
 ## Status
 
-Version: **alpha**. Tokens and components are still settling — expect breaking changes.
+Version: **beta**. Tokens and components are still settling — expect breaking changes.
 
 ## Contributing
 

assets/fonts/Inter/README.md

@@ -1,10 +0,0 @@
-# Inter
-
-Place the licensed Inter font files here:
-
-- Inter-Regular.woff2
-- Inter-Medium.woff2
-- Inter-SemiBold.woff2
-- Inter-Bold.woff2
-
-Include the upstream LICENSE alongside the binaries.

assets/fonts/Manrope/README.md

@@ -0,0 +1,17 @@
+# Manrope
+
+Primary UI typeface for Kode Design Consultants — used for all headings, body
+copy, captions, and the secondary line of the wordmark lockup.
+
+Drop the licensed binaries here:
+
+- Manrope-Variable.woff2 (preferred, weights 200–800)
+- Manrope-ExtraLight.woff2 (200) — secondary wordmark line
+- Manrope-Regular.woff2 (400)
+- Manrope-Medium.woff2 (500)
+- Manrope-SemiBold.woff2 (600)
+- Manrope-Bold.woff2 (700)
+- Manrope-ExtraBold.woff2 (800)
+
+Manrope is licensed under the SIL Open Font License — include LICENSE.txt
+alongside the binaries.

assets/fonts/Opificio/README.md

@@ -0,0 +1,12 @@
+# Opificio
+
+Display typeface for Kode Design Consultants — used **only** for the `kode`
+wordmark and headline display moments. Bold is the canonical cut.
+
+Drop the licensed binaries here:
+
+- Opificio-Bold.woff2     — canonical wordmark cut
+- Opificio-Rounded.woff2  — editorial / friendly variant
+- Opificio-Regular.woff2  — used sparingly
+
+Confirm Opificio's licensing terms with the foundry before redistributing.

assets/fonts/fonts.css

@@ -1,14 +1,41 @@
-/* KDC Design System — font-face declarations.
+/* Kode Design Consultants — font-face declarations.
    Self-host these files from /assets/fonts/. */
 
+/* Manrope — primary UI typeface (variable, 200–800). */
 @font-face {
-  font-family: "Inter";
+  font-family: "Manrope";
   font-style: normal;
-  font-weight: 100 900;
+  font-weight: 200 800;
   font-display: swap;
-  src: url("./Inter/Inter-Regular.woff2") format("woff2");
+  src: url("./Manrope/Manrope-Variable.woff2") format("woff2-variations"),
+       url("./Manrope/Manrope-Regular.woff2") format("woff2");
 }
 
+/* Opificio — display / wordmark only.
+   Three cuts: Bold (canonical), Rounded, Regular. */
+@font-face {
+  font-family: "Opificio";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("./Opificio/Opificio-Bold.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Opificio Rounded";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("./Opificio/Opificio-Rounded.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Opificio";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("./Opificio/Opificio-Regular.woff2") format("woff2");
+}
+
+/* Roboto Mono — code / tabular figures only. Not a brand typeface. */
 @font-face {
   font-family: "Roboto Mono";
   font-style: normal;

brand/brand-guidelines/README.md

@@ -1,12 +1,40 @@
 # Brand Guidelines
 
-Placeholder. Replace with the formal KDC brand book covering:
+## Wordmark
 
-- Mission, vision, and personality
+**Primary lockup** — `kode` set in **Opificio Bold**, 72pt size with 52pt spacing.
-- Logo clear-space and minimum sizes
+
-- Approved color usage
+**Secondary lockup** — `kode` (Opificio Bold, 72pt / 52pt) above `design consultants` (Manrope ExtraLight, 20pt / 76pt spacing).
-- Typography in marketing
+
-- Photography & illustration direction
+Use the secondary lockup wherever clarity about the legal name is required (legal documents, contracts, invoices, footers, first-mention contexts). Use the primary single-line `kode` wherever the brand is already established (favicons, app bar, signed emails, swag).
-- Voice and tone
+
-- Co-branding rules
+## Color palette
-- Do's and don'ts (with examples)
+
+| Color | Hex | Use |
+|-------|-----|-----|
+| Kode purple | `#6B35A7` | Primary brand color, links, primary actions. |
+| Black       | `#000000` | Wordmark, high-emphasis text. |
+| White       | `#FFFFFF` | Cards, modals, contrast surface. |
+| Off-white   | `#F5F4F0` | Default page background. |
+
+## Typography
+
+| Use | Family |
+|-----|--------|
+| Wordmark / display | **Opificio Bold** (Rounded and Regular cuts available for editorial moments) |
+| All UI (headings, body, labels) | **Manrope** — weights 200, 300, 400, 500, 600, 700, 800 |
+| Code / tabular figures | Roboto Mono (system fallback) |
+
+## Logo variants
+
+The brand mark must always appear in one of:
+
+- Solid Kode purple (`#6B35A7`) on white or off-white
+- Solid black on white or off-white
+- Outlined (white interior) on a Kode purple or photographic background
+
+Never re-color, re-stretch, drop-shadow, or place the wordmark on busy or low-contrast imagery.
+
+## Reference
+
+The canonical asset board (kode wordmark, color blocks, typography ramps) lives in [`../logos-source/`](../logos-source/). Replace the placeholders there with the official source artwork before use.

design.md

@@ -3,13 +3,13 @@ version: beta
 name: Kode Design Consultants Ltd Design System
 description: The official design system for Kode Design Consultants — tokens, components, and guidelines for building consistent KDC product and brand experiences.
 colors:
-  brand.primary: "rgb(11, 95, 255)"
+  brand.primary: "#6B35A7"
-  brand.primaryHover: "#0848C2"
+  brand.primaryHover: "#582A8D"
-  brand.primaryPressed: "#063494"
+  brand.primaryPressed: "#45216E"
-  brand.secondary: "#FF6B00"
+  brand.ink: "#000000"
-  brand.accent: "#00C2A8"
+  brand.canvas: "#F5F4F0"
   neutral.0: "#FFFFFF"
-  neutral.50: "#F7F8FA"
+  neutral.50: "#F5F4F0"
   neutral.100: "#EDEFF3"
   neutral.200: "#D9DCE3"
   neutral.300: "#B8BDC9"
@@ -31,48 +31,54 @@ colors:
   border.strong: "{colors.neutral.300}"
 typography:
   display:
-    fontFamily: "Inter"
+    fontFamily: "Opificio"
-    fontSize: "48px"
+    fontSize: "72px"
     fontWeight: 700
-    lineHeight: "56px"
+    lineHeight: "80px"
-    letterSpacing: "-0.02em"
+    letterSpacing: "-0.01em"
+  wordmarkSecondary:
+    fontFamily: "Manrope"
+    fontSize: "20px"
+    fontWeight: 200
+    lineHeight: "28px"
+    letterSpacing: "0.04em"
   headingXL:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "32px"
     fontWeight: 700
     lineHeight: "40px"
   headingL:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "24px"
     fontWeight: 600
     lineHeight: "32px"
   headingM:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "20px"
     fontWeight: 600
     lineHeight: "28px"
   headingS:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "16px"
     fontWeight: 600
     lineHeight: "24px"
   bodyL:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "18px"
     fontWeight: 400
     lineHeight: "28px"
   bodyM:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "16px"
     fontWeight: 400
     lineHeight: "24px"
   bodyS:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "14px"
     fontWeight: 400
     lineHeight: "20px"
   caption:
-    fontFamily: "Inter"
+    fontFamily: "Manrope"
     fontSize: "12px"
     fontWeight: 500
     lineHeight: "16px"
@@ -176,9 +182,9 @@ KDS targets WCAG 2.2 AA at minimum across all components and themes.
 
 Color is organized in three layers:
 
-1. **Brand** — primary identity colors (`brand.primary`, `brand.secondary`, `brand.accent`).
+1. **Brand** — the four-color brand palette: `brand.primary` (`#6B35A7` purple), `brand.ink` (`#000000`), `neutral.0` (`#FFFFFF`), and `brand.canvas` (`#F5F4F0` off-white).
-2. **Neutral** — a 12-step gray ramp powering surfaces, text, and borders.
+2. **Neutral** — a 12-step gray ramp powering surfaces, text, and borders. `neutral.50` is set to `brand.canvas` so the off-white reads as the natural page surface.
-3. **Semantic** — meaning-bearing colors for status: success, warning, danger, info.
+3. **Semantic** — meaning-bearing colors for status: success, warning, danger, info. These sit alongside the brand palette but are not part of brand identity.
 
 Always reference *role* tokens (`text.default`, `surface.subtle`, `border.default`) in product code rather than raw palette values, so themes can swap without churn.
 
@@ -190,11 +196,18 @@ Contrast minimums:
 
 ## Typography
 
-The primary typeface is **Inter** (variable, 100–900). The monospace companion is **Roboto Mono**, used only for code, tabular figures, and technical content.
+KDS uses two brand typefaces:
 
-The scale is a modular 8-step ramp (`caption` → `display`). Use semantic tokens (`headingL`, `bodyM`) — never hardcode `font-size`. Body copy defaults to `bodyM`/16px with a 1.5 line-height for readability. Display sizes use tighter tracking (`-0.02em`) to prevent airy letterspacing at large sizes.
+- **Opificio Bold** — reserved for the **kode** wordmark and headline display moments. Available in Bold, Rounded, and Regular cuts; Bold is the canonical brand weight.
+- **Manrope** — the working typeface for all UI: headings, body, captions, and the secondary wordmark line ("design consultants"). Use the full weight ramp: ExtraLight (200), Light (300), Regular (400), Medium (500), SemiBold (600), Bold (700), ExtraBold (800).
 
-Web fonts are self-hosted from `assets/fonts/` and preloaded for the two most common weights (400, 600).
+The wordmark lockup pairs them: primary line in Opificio Bold (72pt, 52pt spacing), secondary line in Manrope ExtraLight (20pt, 76pt spacing).
+
+The UI scale is a modular 8-step ramp (`caption` → `display`). Use semantic tokens (`headingL`, `bodyM`) — never hardcode `font-size`. Body copy defaults to `bodyM`/16px with a 1.5 line-height for readability.
+
+A monospace stack (Roboto Mono fallback to system mono) is available for code and tabular figures only — it is **not** part of the brand identity.
+
+Web fonts are self-hosted from `assets/fonts/` and preloaded for Manrope Regular (400) and SemiBold (600), plus Opificio Bold for the wordmark.
 
 ## Layout
 

examples/web/index.html

@@ -3,15 +3,16 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>KDC Design System — Web Example</title>
+    <title>Kode Design Consultants — Design System Example</title>
     <link rel="icon" href="../../brand/logos/favicon/favicon.svg" />
     <link rel="stylesheet" href="../../assets/fonts/fonts.css" />
     <link rel="stylesheet" href="./styles.css" />
   </head>
   <body>
     <main class="container">
-      <h1 class="display">KDC Design System</h1>
+      <h1 class="wordmark">kode</h1>
-      <p class="body">A minimal page wired up to KDS tokens and fonts.</p>
+      <p class="wordmark-sub">design consultants</p>
+      <p class="body">A minimal page wired up to the KDC design tokens and brand fonts.</p>
       <button class="btn-primary">Primary action</button>
     </main>
   </body>

examples/web/styles.css

@@ -1,6 +1,9 @@
 :root {
-  --color-brand-primary: #0B5FFF;
+  --color-brand-primary: #6B35A7;
-  --color-brand-primary-hover: #0848C2;
+  --color-brand-primary-hover: #582A8D;
+  --color-brand-primary-pressed: #45216E;
+  --color-brand-ink: #000000;
+  --color-brand-canvas: #F5F4F0;
   --color-text-default: #111827;
   --color-surface-bg: #FFFFFF;
   --radius-md: 8px;
@@ -10,13 +13,31 @@
 
 body {
   margin: 0;
-  font-family: "Inter", system-ui, sans-serif;
+  font-family: "Manrope", system-ui, sans-serif;
   color: var(--color-text-default);
-  background: var(--color-surface-bg);
+  background: var(--color-brand-canvas);
 }
 
 .container { max-width: 1200px; margin: 0 auto; padding: var(--space-5); }
-.display   { font-size: 48px; font-weight: 700; line-height: 56px; letter-spacing: -0.02em; }
+
+.wordmark {
+  font-family: "Opificio", "Manrope", system-ui, sans-serif;
+  font-weight: 700;
+  font-size: 72px;
+  line-height: 80px;
+  letter-spacing: -0.01em;
+  color: var(--color-brand-primary);
+  margin: 0;
+}
+.wordmark-sub {
+  font-family: "Manrope", system-ui, sans-serif;
+  font-weight: 200;
+  font-size: 20px;
+  letter-spacing: 0.04em;
+  color: var(--color-brand-primary);
+  margin: 0 0 24px;
+}
+
 .body { font-size: 16px; line-height: 24px; }
 
 .btn-primary {
@@ -26,6 +47,8 @@ body {
   border-radius: var(--radius-md);
   padding: 12px 20px;
   font: inherit;
+  font-weight: 600;
   cursor: pointer;
 }
 .btn-primary:hover  { background: var(--color-brand-primary-hover); }
+.btn-primary:active { background: var(--color-brand-primary-pressed); }

foundations/colors/swatches.md

@@ -1,13 +1,27 @@
 # Color Swatches
 
-| Token | Hex | Preview |
+## Brand palette
-|-------|-----|---------|
+
-| `brand.primary`         | `#0B5FFF` | 🟦 |
+| Token | Hex | Use |
-| `brand.secondary`       | `#FF6B00` | 🟧 |
+|-------|-----|-----|
-| `brand.accent`          | `#00C2A8` | 🟩 |
+| `brand.primary`   | `#6B35A7` | Kode purple — primary brand color, links, primary actions. |
-| `neutral.0`             | `#FFFFFF` | ⬜ |
+| `brand.ink`       | `#000000` | Wordmark, high-emphasis text. |
-| `neutral.900`           | `#111827` | ⬛ |
+| `neutral.0`       | `#FFFFFF` | Pure white — cards, modals, top-bar. |
-| `semantic.success`      | `#16A34A` | ✅ |
+| `brand.canvas`    | `#F5F4F0` | Brand off-white — default page background. |
-| `semantic.warning`      | `#F59E0B` | ⚠️  |
+
-| `semantic.danger`       | `#DC2626` | 🛑 |
+## Primary state ramp
-| `semantic.info`         | `#0EA5E9` | ℹ️  |
+
+| Token | Hex |
+|-------|-----|
+| `brand.primary`         | `#6B35A7` |
+| `brand.primaryHover`    | `#582A8D` |
+| `brand.primaryPressed`  | `#45216E` |
+
+## Semantic
+
+| Token | Hex |
+|-------|-----|
+| `semantic.success` | `#16A34A` |
+| `semantic.warning` | `#F59E0B` |
+| `semantic.danger`  | `#DC2626` |
+| `semantic.info`    | `#0EA5E9` |

foundations/typography/README.md

@@ -1,8 +1,14 @@
 # Foundations · Typography
 
-Reference documentation for the **typography** foundation. The canonical token values
+KDS uses two brand typefaces:
-live in [`../../design.md`](../../design.md) and the machine-readable export
-in [`../../tokens/`](../../tokens/).
 
-This page is for human-facing rationale: when to use which token, examples,
+| Family | Use | Weights |
-and platform notes.
+|--------|-----|---------|
+| **Opificio** | Wordmark and display moments only. | Bold (700) — canonical. Rounded and Regular cuts available for editorial. |
+| **Manrope**  | All UI typography — headings, body, labels, captions. | 200 ExtraLight, 300 Light, 400 Regular, 500 Medium, 600 SemiBold, 700 Bold, 800 ExtraBold |
+
+Roboto Mono is available as a non-brand fallback for code and tabular figures.
+
+The wordmark lockup pairs them: `kode` in Opificio Bold (72pt, 52pt spacing) above `design consultants` in Manrope ExtraLight (20pt, 76pt spacing).
+
+Canonical token values live in [`../../design.md`](../../design.md); machine-readable typography tokens are in [`../../tokens/typography.json`](../../tokens/typography.json).

tokens/colors.json

@@ -2,15 +2,15 @@
   "$schema": "https://design-tokens.github.io/community-group/format/",
   "color": {
     "brand": {
-      "primary":        { "$value": "#0B5FFF", "$type": "color" },
+      "primary":         { "$value": "#6B35A7", "$type": "color", "$description": "Kode purple — primary brand color." },
-      "primary-hover":  { "$value": "#0848C2", "$type": "color" },
+      "primary-hover":   { "$value": "#582A8D", "$type": "color" },
-      "primary-pressed":{ "$value": "#063494", "$type": "color" },
+      "primary-pressed": { "$value": "#45216E", "$type": "color" },
-      "secondary":      { "$value": "#FF6B00", "$type": "color" },
+      "ink":             { "$value": "#000000", "$type": "color", "$description": "Brand black — wordmark and high-emphasis text." },
-      "accent":         { "$value": "#00C2A8", "$type": "color" }
+      "canvas":          { "$value": "#F5F4F0", "$type": "color", "$description": "Brand off-white — default page surface." }
     },
     "neutral": {
       "0":    { "$value": "#FFFFFF", "$type": "color" },
-      "50":   { "$value": "#F7F8FA", "$type": "color" },
+      "50":   { "$value": "#F5F4F0", "$type": "color", "$description": "Aliased to brand.canvas." },
       "100":  { "$value": "#EDEFF3", "$type": "color" },
       "200":  { "$value": "#D9DCE3", "$type": "color" },
       "300":  { "$value": "#B8BDC9", "$type": "color" },

tokens/typography.json

@@ -1,14 +1,15 @@
 {
   "typography": {
-    "display":    { "fontFamily": "Inter", "fontSize": "48px", "fontWeight": 700, "lineHeight": "56px", "letterSpacing": "-0.02em" },
+    "display":            { "fontFamily": "Opificio", "fontSize": "72px", "fontWeight": 700, "lineHeight": "80px", "letterSpacing": "-0.01em", "$description": "Wordmark / hero only." },
-    "headingXL":  { "fontFamily": "Inter", "fontSize": "32px", "fontWeight": 700, "lineHeight": "40px" },
+    "wordmarkSecondary":  { "fontFamily": "Manrope",  "fontSize": "20px", "fontWeight": 200, "lineHeight": "28px", "letterSpacing": "0.04em", "$description": "Secondary lockup line: 'design consultants'." },
-    "headingL":   { "fontFamily": "Inter", "fontSize": "24px", "fontWeight": 600, "lineHeight": "32px" },
+    "headingXL":          { "fontFamily": "Manrope",  "fontSize": "32px", "fontWeight": 700, "lineHeight": "40px" },
-    "headingM":   { "fontFamily": "Inter", "fontSize": "20px", "fontWeight": 600, "lineHeight": "28px" },
+    "headingL":           { "fontFamily": "Manrope",  "fontSize": "24px", "fontWeight": 600, "lineHeight": "32px" },
-    "headingS":   { "fontFamily": "Inter", "fontSize": "16px", "fontWeight": 600, "lineHeight": "24px" },
+    "headingM":           { "fontFamily": "Manrope",  "fontSize": "20px", "fontWeight": 600, "lineHeight": "28px" },
-    "bodyL":      { "fontFamily": "Inter", "fontSize": "18px", "fontWeight": 400, "lineHeight": "28px" },
+    "headingS":           { "fontFamily": "Manrope",  "fontSize": "16px", "fontWeight": 600, "lineHeight": "24px" },
-    "bodyM":      { "fontFamily": "Inter", "fontSize": "16px", "fontWeight": 400, "lineHeight": "24px" },
+    "bodyL":              { "fontFamily": "Manrope",  "fontSize": "18px", "fontWeight": 400, "lineHeight": "28px" },
-    "bodyS":      { "fontFamily": "Inter", "fontSize": "14px", "fontWeight": 400, "lineHeight": "20px" },
+    "bodyM":              { "fontFamily": "Manrope",  "fontSize": "16px", "fontWeight": 400, "lineHeight": "24px" },
-    "caption":    { "fontFamily": "Inter", "fontSize": "12px", "fontWeight": 500, "lineHeight": "16px", "letterSpacing": "0.02em" },
+    "bodyS":              { "fontFamily": "Manrope",  "fontSize": "14px", "fontWeight": 400, "lineHeight": "20px" },
+    "caption":            { "fontFamily": "Manrope",  "fontSize": "12px", "fontWeight": 500, "lineHeight": "16px", "letterSpacing": "0.02em" },
     "mono":               { "fontFamily": "Roboto Mono", "fontSize": "14px", "fontWeight": 400, "lineHeight": "20px" }
   }
 }