@kangentic/branding 2.0.1 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +63 -98
  2. package/assets/brandmark-mono-amber.svg +1 -0
  3. package/assets/brandmark-mono.svg +1 -0
  4. package/assets/mascot/overseer-blink.svg +1 -0
  5. package/assets/mascot/overseer-wave.svg +1 -0
  6. package/package.json +4 -2
  7. package/resources/README.md +17 -0
package/README.md CHANGED
@@ -1,111 +1,76 @@
1
1
  # Kangentic Branding
2
2
 
3
- Single source of truth for ALL Kangentic content assets - the icon, the
3
+ Single source of truth for the Kangentic brand assets - the icon, the
4
4
  mascot, and the social image - consumed by the website (kangentic.com),
5
- the desktop app, and the mobile app. Content changes here, version bumps,
6
- consumers update - never edit an asset inside a consumer repo.
7
-
8
- ## Versioning
9
-
10
- The package major tracks the brand generation (semver):
11
-
12
- - **v1 - blue K (2025)**: the original blue disc K. Frozen verbatim in
13
- `archive/v1/` (app icon ladder + ICO/ICNS in `app/`, website logo and
14
- favicons in `web/`) so the brand's history and progression stay
15
- comparable. Never regenerated, never edited.
16
- - **v2 - Warm Craft (2026)**: the current line. Cream, ink, rust, amber;
17
- the two-tier mark below. Minor/patch bumps for refinements within the
18
- line; the next full rebrand becomes v3 and this line moves to
19
- `archive/v2/` first (the `/release` skill enforces it).
20
-
21
- ## The mark (v2): a two-tier system
22
-
23
- | Asset | Mark | Use |
24
- |-------|------|-----|
25
- | `assets/brandmark-small.svg` | F4k board glyph knockout: three column holes through the rust disc, amber card mid-drop (letterless) | **THE APP ICON** (taskbar, dock, favicons, tray, stores) and in-page marks at nav/header size |
26
- | `assets/brandmark.svg` | Card-K knockout: rust disc, card-shaped alpha hole, floating rust K with severed amber arm-tip | Large in-page/marketing display only (hero, social, print) |
27
- | `assets/brandmark-filled.svg` | Card-K with the card painted cream (fixed appearance) | Large display on unknown grounds |
28
-
29
- The tier is picked by DISPLAYED size, never raster resolution - a 1024px
30
- app icon still renders at taskbar/dock size, so every icon raster is F4k.
31
- Both marks are knockouts (true alpha holes, the page or OS theme flows
32
- through) and share the "holes in the rust disc" DNA. The split exists
33
- because at small display the card-K fails structurally (the rust K merges
34
- with the rust ring); the letterless board glyph won the live in-header
35
- review. Full rationale, geometry, and decision history:
36
- `.claude/skills/icon-drafting/SKILL.md`.
37
-
38
- ## The production tree: `resources/`
39
-
40
- Everything each surface ships, generated by `npm run gen:icons`, two-tier
41
- by displayed context (card-K where the mark shows large, F4k where the OS
42
- shows it small):
43
-
44
- - **`resources/desktop/`** - Electron set: `icon.ico` (16-256),
45
- `icon.icns` (16-1024), the full PNG ladder. Tiered per entry - the OS
46
- pulls card-K at 128+ (dock, Finder-large) and F4k at 16-64 (taskbar).
47
- - **`resources/web/`** - favicons (F4k), apple-touch + manifest squares
48
- (F4k, opaque cream), `logo.png` (card-K, shown large in search), both
49
- brandmark SVGs
50
- - **`resources/mobile/`** - iOS App Store 1024, Play Store 512, Android
51
- adaptive layers. All F4k: these are single masters the OS downscales to
52
- the small installed icon, so card-K would shrink to an illegible mini-K.
53
-
54
- Per-file tables and the exact per-surface mark: `resources/README.md`.
55
- `exploration/icon-concepts/preview.png` shows the desktop tier boundary on
56
- light and dark (a review artifact, not a shipped resource).
57
-
58
- ## The mascot: the Overseer
59
-
60
- A separate asset from the brandmark, by design (mascot = personality, icon
61
- = app identity). A soft amber pixel blob with three sparkle eyes, authored
62
- as an ASCII map and rendered to a crisp rect-grid SVG by the shared sprite
63
- engine (`scripts/lib/sprite.mjs`).
64
-
65
- - `assets/mascot/overseer.svg` - the canonical inline mascot (amber on
66
- transparency, theme-agnostic). `npm run gen:sprites`.
67
- - `resources/social/og-image.png` (1200x630) - the share image: pixel
68
- wordmark + the Overseer, no font dependency. `npm run gen:og`.
69
- - `exploration/mascot/` - alternates and retired poses (kangaroo, board
70
- creature, rust Overseer). Full rationale and decision history:
71
- `.claude/skills/sprite-drafting/SKILL.md`.
72
-
73
- Every rejected creature round and the superseded mascot-based icon sets
74
- are frozen in `archive/mascot-explorations/` so the progression is never
75
- lost.
76
-
77
- ## Regenerating
5
+ the desktop app, and the mobile app. Assets change here, a release ships,
6
+ consumers update. Never edit an asset inside a consumer repo.
7
+
8
+ Published as [`@kangentic/branding`](https://www.npmjs.com/package/@kangentic/branding).
9
+
10
+ ## What's here
11
+
12
+ - **The mark** - `assets/brandmark*.svg`. A two-tier system: the card-K
13
+ (the letter) where the mark shows large, the F4k board glyph where the
14
+ OS shows it small. Tier is keyed to displayed size, not raster
15
+ resolution. For in-app chrome the consumer themes, two `currentColor`
16
+ variants tint with the surface's foreground when inlined (or used as a
17
+ CSS mask): `brandmark-mono-amber.svg` (theme-tinted disc, amber card
18
+ kept - the default themed lockup) and `brandmark-mono.svg` (pure
19
+ single color, all shape as alpha - strict monochrome, tray-template
20
+ source).
21
+ - **The mascot** - `assets/mascot/overseer.svg`. The Overseer, a pixel-art
22
+ amber blob, authored as an ASCII map and rendered to a crisp SVG.
23
+ Animation pose frames ship alongside it (`overseer-blink.svg`,
24
+ `overseer-wave.svg`) for consumer-side stepped frame swaps; reduced
25
+ motion rests on the canonical frame.
26
+ - **The production tree** - `resources/`. Everything each surface ships:
27
+ `desktop/` (Electron .ico/.icns + PNG ladder), `web/` (favicons,
28
+ manifest icons, logo), `mobile/` (store + adaptive icons), and
29
+ `social/og-image.png`. See `resources/README.md` for the per-file table.
30
+
31
+ `assets/` is the vector home (consumer-agnostic SVGs); `resources/` holds
32
+ the shipped per-consumer files, mostly rasters for surfaces that cannot
33
+ take an SVG. The `resources/web/brandmark*.svg` files are byte copies of
34
+ the `assets/` ones so the website deploys a single folder.
35
+
36
+ Older brand lines and rejected explorations are frozen under `archive/`.
37
+
38
+ ## Use it
78
39
 
79
40
  ```bash
80
- npm install
81
- npm run gen # exploration sheets + canonical assets/
82
- npm run gen:icons # production resources/
41
+ npm install @kangentic/branding
83
42
  ```
84
43
 
85
- All geometry lives in `scripts/lib/mark.mjs` (the K is frozen path data -
86
- no font dependency at render time). Generated output is committed; the
87
- release pipeline fails if committed assets drift from the harness.
44
+ Copy or import from
45
+ `node_modules/@kangentic/branding/{assets,resources}/`. A git submodule
46
+ also works for consumers that can't take an npm dependency.
47
+
48
+ ## Regenerate
88
49
 
89
- ## Consuming
50
+ Assets are generated and committed - never hand-edit one. To change an
51
+ asset, edit the generator and rerun:
90
52
 
91
- Preferred: npm - `npm install @kangentic/branding`, copy or import from
92
- `node_modules/@kangentic/branding/{assets,resources}/`. A git submodule
93
- also works if a consumer can't take an npm dependency, with the usual
94
- submodule pointer-bump caveats.
53
+ ```bash
54
+ npm install
55
+ npm run gen # canonical assets/ + exploration sheets
56
+ npm run gen:icons # production icon tree -> resources/
57
+ npm run gen:sprites # mascot -> assets/mascot/
58
+ npm run gen:og # social image -> resources/social/
59
+ ```
60
+
61
+ All mark geometry lives in `scripts/lib/mark.mjs` (the K is frozen path
62
+ data, so there's no font dependency at render time). Generators are
63
+ deterministic; the release pipeline fails if committed output drifts.
95
64
 
96
- ## Releasing
65
+ ## Release
97
66
 
98
- `/release [patch|minor|major]` in Claude Code: determinism gate (regenerate
99
- + verify no drift), version bump, changelog, tag, GitHub release, npm
100
- publish. Major bumps are reserved for brand generations and require
101
- archiving the outgoing line.
67
+ `/release [patch|minor|major]` in Claude Code handles the determinism
68
+ gate, version bump, changelog, tag, GitHub release, and npm publish. The
69
+ package major tracks the brand generation (v1 blue K, v2 Warm Craft); a
70
+ major bump archives the outgoing line first.
102
71
 
103
- ## Migration status
72
+ ## Deeper docs
104
73
 
105
- Moved here: the brandmark geometry + harness, canonical marks, the
106
- production icon tree, v1 archive. Still in consumer repos, migrating during
107
- the production build-out: mascot sprite pipeline (`gen-sprites.mjs`), OG
108
- image builder (`gen-brand.mjs`) - both in kangentic.com `scripts/` - and
109
- the Warm Craft exploration history in the app repo's `resources/rebrand/`.
110
- kangentic.com's copy of `gen-brandmark.mjs` is slated for removal; do not
111
- evolve geometry there.
74
+ The full mark rationale, geometry, and decision history live in the
75
+ project's Claude Code skills (`icon-drafting`, `sprite-drafting`,
76
+ `design-language`).
package/assets/brandmark-mono-amber.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path fill-rule="evenodd" fill="currentColor" d="M0 50a50 50 0 1 0 100 0a50 50 0 1 0 -100 0ZM26.4 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v44.84a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-44.84a3.54 3.54 0 0 1 3.54 -3.54ZM45.87 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v16.52a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-16.52a3.54 3.54 0 0 1 3.54 -3.54ZM65.34 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v44.84a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-44.84a3.54 3.54 0 0 1 3.54 -3.54Z"/><rect x="42.33" y="52.36" width="14.75" height="20.06" rx="2.36" fill="#e8a33d"/></svg>
package/assets/brandmark-mono.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path fill-rule="evenodd" fill="currentColor" d="M0 50a50 50 0 1 0 100 0a50 50 0 1 0 -100 0ZM26.4 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v44.84a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-44.84a3.54 3.54 0 0 1 3.54 -3.54ZM45.87 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v16.52a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-16.52a3.54 3.54 0 0 1 3.54 -3.54ZM65.34 20.5h7.67a3.54 3.54 0 0 1 3.54 3.54v44.84a3.54 3.54 0 0 1 -3.54 3.54h-7.67a3.54 3.54 0 0 1 -3.54 -3.54v-44.84a3.54 3.54 0 0 1 3.54 -3.54ZM44.69 52.36h10.03a2.36 2.36 0 0 1 2.36 2.36v15.34a2.36 2.36 0 0 1 -2.36 2.36h-10.03a2.36 2.36 0 0 1 -2.36 -2.36v-15.34a2.36 2.36 0 0 1 2.36 -2.36Z"/></svg>
package/assets/mascot/overseer-blink.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 12" width="18" height="12" shape-rendering="crispEdges" role="img" aria-label="Pixel-art Kangentic mascot"><rect x="5" y="0" width="8" height="1" fill="#e8a33d"/><rect x="3" y="1" width="12" height="1" fill="#e8a33d"/><rect x="2" y="2" width="14" height="1" fill="#e8a33d"/><rect x="2" y="3" width="14" height="1" fill="#e8a33d"/><rect x="2" y="4" width="2" height="1" fill="#e8a33d"/><rect x="4" y="4" width="2" height="1" fill="#24201b"/><rect x="6" y="4" width="2" height="1" fill="#e8a33d"/><rect x="8" y="4" width="2" height="1" fill="#24201b"/><rect x="10" y="4" width="2" height="1" fill="#e8a33d"/><rect x="12" y="4" width="2" height="1" fill="#24201b"/><rect x="14" y="4" width="2" height="1" fill="#e8a33d"/><rect x="0" y="5" width="18" height="1" fill="#e8a33d"/><rect x="0" y="6" width="18" height="1" fill="#e8a33d"/><rect x="2" y="7" width="14" height="1" fill="#e8a33d"/><rect x="2" y="8" width="14" height="1" fill="#e8a33d"/><rect x="3" y="9" width="12" height="1" fill="#e8a33d"/><rect x="4" y="10" width="2" height="1" fill="#e8a33d"/><rect x="8" y="10" width="2" height="1" fill="#e8a33d"/><rect x="12" y="10" width="2" height="1" fill="#e8a33d"/><rect x="4" y="11" width="2" height="1" fill="#e8a33d"/><rect x="8" y="11" width="2" height="1" fill="#e8a33d"/><rect x="12" y="11" width="2" height="1" fill="#e8a33d"/></svg>
package/assets/mascot/overseer-wave.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 12" width="18" height="12" shape-rendering="crispEdges" role="img" aria-label="Pixel-art Kangentic mascot"><rect x="5" y="0" width="8" height="1" fill="#e8a33d"/><rect x="3" y="1" width="12" height="1" fill="#e8a33d"/><rect x="2" y="2" width="14" height="1" fill="#e8a33d"/><rect x="2" y="3" width="2" height="1" fill="#e8a33d"/><rect x="4" y="3" width="1" height="1" fill="#24201b"/><rect x="5" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="6" y="3" width="2" height="1" fill="#e8a33d"/><rect x="8" y="3" width="1" height="1" fill="#24201b"/><rect x="9" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="10" y="3" width="2" height="1" fill="#e8a33d"/><rect x="12" y="3" width="1" height="1" fill="#24201b"/><rect x="13" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="14" y="3" width="2" height="1" fill="#e8a33d"/><rect x="2" y="4" width="2" height="1" fill="#e8a33d"/><rect x="4" y="4" width="2" height="1" fill="#24201b"/><rect x="6" y="4" width="2" height="1" fill="#e8a33d"/><rect x="8" y="4" width="2" height="1" fill="#24201b"/><rect x="10" y="4" width="2" height="1" fill="#e8a33d"/><rect x="12" y="4" width="2" height="1" fill="#24201b"/><rect x="14" y="4" width="4" height="1" fill="#e8a33d"/><rect x="0" y="5" width="18" height="1" fill="#e8a33d"/><rect x="0" y="6" width="16" height="1" fill="#e8a33d"/><rect x="2" y="7" width="14" height="1" fill="#e8a33d"/><rect x="2" y="8" width="14" height="1" fill="#e8a33d"/><rect x="3" y="9" width="12" height="1" fill="#e8a33d"/><rect x="4" y="10" width="2" height="1" fill="#e8a33d"/><rect x="8" y="10" width="2" height="1" fill="#e8a33d"/><rect x="12" y="10" width="2" height="1" fill="#e8a33d"/><rect x="4" y="11" width="2" height="1" fill="#e8a33d"/><rect x="8" y="11" width="2" height="1" fill="#e8a33d"/><rect x="12" y="11" width="2" height="1" fill="#e8a33d"/></svg>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kangentic/branding",
3
- "version": "2.0.1",
3
+ "version": "2.2.0",
4
4
  "description": "Kangentic brand assets: the two-tier brandmark (card-K / F4k board glyph), icon sets, and the drafting harness that generates them. Single source of truth for the website, desktop app, and mobile app.",
5
5
  "type": "module",
6
6
  "files": [
@@ -11,7 +11,9 @@
11
11
  "gen": "node scripts/gen-brandmark.mjs",
12
12
  "gen:icons": "node scripts/gen-icons.mjs",
13
13
  "gen:sprites": "node scripts/gen-sprites.mjs",
14
- "gen:og": "node scripts/gen-og.mjs"
14
+ "gen:og": "node scripts/gen-og.mjs",
15
+ "gen:review": "node scripts/gen-review.mjs",
16
+ "check": "node scripts/check-invariants.mjs"
15
17
  },
16
18
  "repository": {
17
19
  "type": "git",
package/resources/README.md CHANGED
@@ -17,6 +17,13 @@ like the v1 blue K did). The desktop tier boundary is previewed in the
17
17
  branding repo at `exploration/icon-concepts/preview.png` (a review artifact,
18
18
  not shipped here).
19
19
 
20
+ **Vectors:** the canonical SVG marks live in `../assets/` (consumer-agnostic,
21
+ including the theme-tinted in-app pair: `brandmark-mono-amber.svg`, the
22
+ currentColor disc with the amber card kept, the default themed lockup, and
23
+ `brandmark-mono.svg`, pure currentColor for strict monochrome). The
24
+ `web/brandmark*.svg` files below are byte copies so the website deploys one
25
+ folder.
26
+
20
27
  ## desktop/ (kangentic, Electron)
21
28
  | File | Use | Mark |
22
29
  |------|-----|------|
@@ -24,6 +31,16 @@ not shipped here).
24
31
  | icon.icns | macOS dock / Finder; 16-1024 | tiered per entry |
25
32
  | icon.png + icon-{16..1024}.png | Linux / BrowserWindow ladder | F4k <=64, card-K >=128 |
26
33
 
34
+ These rasters feed NATIVE OS surfaces that do not decode SVG: electron-builder
35
+ requires .ico/.icns/.png for the packaged app icon, and Electron's
36
+ `nativeImage.createFromPath()` (BrowserWindow icon, `app.dock.setIcon`,
37
+ `Tray`) decodes PNG/JPEG/ICO/ICNS only. The raster ladder is a requirement of
38
+ the native layer, not a missed optimization. In-app renderer surfaces consume
39
+ `../assets/*.svg` instead - `brandmark-mono-amber.svg` for themed lockups
40
+ (the disc tints, the amber card stays), `brandmark-mono.svg` for strict
41
+ monochrome, `brandmark-small.svg` where the fixed palette works. A future
42
+ macOS tray would take a template PNG derived from the pure mono, not an SVG.
43
+
27
44
  ## web/ (kangentic.com)
28
45
  | File | Use | Mark |
29
46
  |------|-----|------|