@adea-ai/themes 0.1.2 → 0.3.0

package/src/sources.ts

@@ -37,6 +37,7 @@
  */
 
 import type { Base24Slot } from './adapters/base24'
+import { CONTRAST_FLOORS } from './normalize'
 import type { ThemeAppearance, ThemeProvenance } from './schema'
 
 /** The dataset the Base24 schemes are reproduced from. */
@@ -58,6 +59,258 @@ export const ADEA_PROVENANCE: ThemeProvenance = Object.freeze({
   license: 'Apache-2.0',
 })
 
+/**
+ * A theme composed from **two** upstream palettes.
+ *
+ * Adea's own dark theme is not a copy of any published palette, and it is not
+ * hand-authored either. It is a deliberate composition: the canvas, the greys, the
+ * cursor and the selection come from a palette chosen for exactly those — Aardvark
+ * Ink, whose near-black navy and muted blue-grey foreground are why it was picked —
+ * and the sixteen ANSI hues come from a second palette chosen for its saturation,
+ * GitHub's dark scheme.
+ *
+ * The split exists because the two properties are in tension inside one palette. A
+ * palette tuned for a comfortable canvas mutes its hues to agree with it; a palette
+ * tuned for vivid syntax colours tends to sit on a canvas that is very dark or very
+ * flat. Taking one of each yields a calm ground with legible colour on it.
+ *
+ * ## Why it is composed rather than merged by hand
+ *
+ * The alternative was to read both palettes and paste the merged hex into
+ * `palettes/adea-dark.json`. That works once and is wrong afterwards: nothing then
+ * records which donor each value came from, so neither donor could ever be
+ * refreshed. Composing in the vendor step keeps both parents named, keeps the values
+ * upstream's own bytes rather than a transcription, and makes "GitHub changed its
+ * blue" a one-line diff plus a rebuild.
+ */
+export interface ComposedSource {
+  id: string
+  name: string
+  family: 'adea'
+  familyLabel: string
+  label: string
+  description: string
+  appearance: ThemeAppearance
+  tags: readonly string[]
+  /** The two donors' slugs in the dataset, and which half each supplies. */
+  donors: Readonly<Record<'structure' | 'hues', string>>
+  /**
+   * The Base24 slot map.
+   *
+   * Each entry is `[donor, key]`, where the donor is `structure` or `hues` and the
+   * key is a role name in that donor's published palette — the dataset's own names,
+   * so `purple` is Base24's magenta slot and `brightPurple` its bright magenta.
+   */
+  slots: Readonly<Partial<Record<Base24Slot, readonly ['structure' | 'hues', string]>>>
+  /**
+   * Slots neither donor supplies, derived from one of them.
+   *
+   * `slots` and `synthesise` are jointly total: between them they must cover every
+   * Base24 slot, and the vendor step asserts that rather than trusting it. The two
+   * are separate maps rather than one so that "this value came from a donor" and
+   * "this value was computed" stay distinguishable in review.
+   */
+  synthesise: Readonly<
+    Partial<
+      Record<
+        Base24Slot,
+        readonly ['structure' | 'hues', string, { rotate?: number; lighten?: number }]
+      >
+    >
+  >
+  /**
+   * ANSI roles pinned to the structure donor's own values.
+   *
+   * The greyscale ramp is normally *derived* by ranking a scheme's grey slots by
+   * measured contrast, because Base24 does not name `black`, `white` or
+   * `brightBlack` and light schemes invert them. That derivation is right for an
+   * imported palette and wrong here: Aardvark Ink publishes a greyscale it chose,
+   * the greyscale is the reason it was chosen as the structure donor, and
+   * re-deriving it gives back something close but not equal. So the four roles are
+   * pinned to the donor's own values instead.
+   */
+  ansiFromStructure: readonly ('black' | 'brightBlack' | 'white' | 'brightWhite')[]
+  /** The role supplying the accent, when the family's identity demands one. */
+  accentSlot?: 'blue' | 'magenta' | 'cyan' | 'green'
+  palette?: Partial<Record<Base24Slot, string>>
+  /**
+   * Transpose this composition's hues onto the borrowed canvas.
+   *
+   * Set when a composition takes its hues from a palette authored against a different
+   * kind of canvas — which is what borrowing a *dark* palette's hues for a *light*
+   * canvas is. See `transposeHues` in `src/normalize.ts` for why the whole hue set
+   * moves by one common step rather than each hue being repaired on its own.
+   */
+  hueTranspose?: { floor: number }
+  provenance: ThemeProvenance
+}
+
+/**
+ * Adea's two default themes.
+ *
+ * Both are compositions and both were previously authored here — the light one as a
+ * neutral grey ramp on white with a monochrome accent, the dark one as a neutral grey
+ * ramp on `#252525`. They replaced those entirely while keeping their names, because
+ * they are the defaults: the system's own appearance, not a pair of options beside it.
+ *
+ * ## Why they are a *pair* rather than two themes
+ *
+ * They share one hue donor, so a red is the same red and a blue the same blue in both,
+ * and each borrows its canvas from a palette chosen for the *canvas* rather than for
+ * its colours:
+ *
+ * | | canvas | canvas hue | hues |
+ * | --- | --- | --- | --- |
+ * | Adea Dark | Aardvark Ink `#0f141f` | 265° | GitHub Dark Default |
+ * | Adea Light | Nord Light `#e3e9f4` | 262° | GitHub Dark Default |
+ *
+ * Three degrees apart, and both canvases are *tinted* rather than neutral — 0.024 and
+ * 0.016 of chroma — which is the property that makes the pair feel like one theme seen
+ * at two exposures instead of two themes that happen to ship together. Switching
+ * appearance changes lightness and nothing else about the theme's identity; that claim
+ * is asserted in `tests/provenance.test.ts` rather than left as intent.
+ *
+ * The light theme is the reason `hueTranspose` exists: GitHub's dark hues measure
+ * between 2.5:1 and 4.1:1 on a light canvas, so the whole hue set is transposed down in
+ * lightness by one common step — hue and chroma intact, relative brightness ordering
+ * intact — rather than repaired hue by hue, which would have collapsed every bright
+ * variant onto its normal sibling.
+ */
+export const COMPOSED_SOURCES: readonly ComposedSource[] = Object.freeze([
+  {
+    id: 'adea-dark',
+    name: 'Adea Dark',
+    family: 'adea',
+    familyLabel: 'Adea',
+    label: 'Dark',
+    description:
+      "The default dark theme. Aardvark Ink's quiet canvas, with GitHub's vivid hues on it.",
+    appearance: 'dark',
+    tags: ['dark', 'default', 'vivid'],
+    donors: { structure: 'aardvark-ink', hues: 'github-dark-default' },
+    slots: {
+      // The structure donor. `base01` receives its `black` rather than a background
+      // step: an ANSI black equal to the background is invisible as foreground text,
+      // which is the defect the normalizer's ramp notes describe.
+      base00: ['structure', 'background'],
+      base01: ['structure', 'black'],
+      base02: ['structure', 'selection'],
+      base03: ['structure', 'brightBlack'],
+      base04: ['structure', 'white'],
+      base05: ['structure', 'foreground'],
+      base06: ['structure', 'brightWhite'],
+      base07: ['structure', 'brightWhite'],
+      // The hue donor. Base24's bright slots run red, yellow, green, cyan, blue,
+      // magenta — not the ANSI order of yellow before green.
+      base08: ['hues', 'red'],
+      base0A: ['hues', 'yellow'],
+      base0B: ['hues', 'green'],
+      base0C: ['hues', 'cyan'],
+      base0D: ['hues', 'blue'],
+      base0E: ['hues', 'purple'],
+      base12: ['hues', 'brightRed'],
+      base13: ['hues', 'brightYellow'],
+      base14: ['hues', 'brightGreen'],
+      base15: ['hues', 'brightCyan'],
+      base16: ['hues', 'brightBlue'],
+      base17: ['hues', 'brightPurple'],
+    },
+    synthesise: {
+      // Neither donor's ANSI set has an orange or a brown, and Base24 defines both.
+      // A hue rotation off red and yellow is how the export adapter fills them too,
+      // so a composed scheme and an exported one are synthesised identically.
+      base09: ['hues', 'red', { rotate: 26 }],
+      base0F: ['hues', 'yellow', { rotate: -34 }],
+      // The two rungs below the canvas, which the specification defines as "dark
+      // black" and "darker than that". Lightness slices of the structure donor's own
+      // canvas, so the theme keeps its hue as it darkens.
+      base10: ['structure', 'background', { lighten: -0.03 }],
+      base11: ['structure', 'background', { lighten: -0.06 }],
+    },
+    ansiFromStructure: ['black', 'brightBlack', 'white', 'brightWhite'],
+    provenance: {
+      project: 'Adea',
+      url: 'https://github.com/adea-ai/themes',
+      license: 'Apache-2.0',
+      bootstrappedFrom: [
+        'Aardvark Ink (iTerm2-Color-Schemes)',
+        'GitHub Dark Default (iTerm2-Color-Schemes)',
+      ],
+    },
+  },
+  {
+    id: 'adea-light',
+    name: 'Adea Light',
+    family: 'adea',
+    familyLabel: 'Adea',
+    label: 'Light',
+    description:
+      "The default light theme. Nord Light's cool canvas, with the same hues as Adea Dark.",
+    appearance: 'light',
+    tags: ['light', 'default', 'cool'],
+    donors: { structure: 'nord-light', hues: 'github-dark-default' },
+    slots: {
+      // The structure donor. Same shape as the dark theme's, with one difference worth
+      // noting: Nord Light's `black` (`#3b4252`) is *darker* than its foreground, which
+      // is what an ANSI black should be on a light canvas — the text colour and the
+      // darkest neutral are the same role there, and Base24's `base01` is where Nord
+      // keeps it.
+      base00: ['structure', 'background'],
+      base01: ['structure', 'black'],
+      base02: ['structure', 'selection'],
+      base03: ['structure', 'brightBlack'],
+      base04: ['structure', 'white'],
+      base05: ['structure', 'foreground'],
+      base06: ['structure', 'brightWhite'],
+      base07: ['structure', 'brightWhite'],
+      base08: ['hues', 'red'],
+      base0A: ['hues', 'yellow'],
+      base0B: ['hues', 'green'],
+      base0C: ['hues', 'cyan'],
+      base0D: ['hues', 'blue'],
+      base0E: ['hues', 'purple'],
+      base12: ['hues', 'brightRed'],
+      base13: ['hues', 'brightYellow'],
+      base14: ['hues', 'brightGreen'],
+      base15: ['hues', 'brightCyan'],
+      base16: ['hues', 'brightBlue'],
+      base17: ['hues', 'brightPurple'],
+    },
+    synthesise: {
+      base09: ['hues', 'red', { rotate: 26 }],
+      base0F: ['hues', 'yellow', { rotate: -34 }],
+      // Beyond the canvas rather than below it, which is the convention for a light
+      // scheme: these two slots are the light end of the ramp.
+      base10: ['structure', 'background', { lighten: 0.03 }],
+      base11: ['structure', 'background', { lighten: 0.06 }],
+    },
+    /**
+     * The one deliberate deviation from the donor, and it is aesthetic rather than
+     * factual — unlike the One Dark correction above, nothing here is wrong.
+     *
+     * Nord Light's canvas carries 0.010 of chroma against Aardvark Ink's 0.024, so
+     * rendering the same hue at half the tint makes the light theme read as neutral grey
+     * beside a partner that is clearly navy. Deepening it to 0.016 — two thirds of the
+     * dark theme's — is what makes the pair look like siblings. Lightness and hue are
+     * untouched, so no contrast pairing moves: body text measures 7.5:1 either way.
+     */
+    palette: { base00: 'oklch(0.933 0.016 261.79)' },
+    ansiFromStructure: ['black', 'brightBlack', 'white', 'brightWhite'],
+    // GitHub's hues were drawn for a `#0d1117` canvas. On Nord Light's they measure
+    // between 2.5:1 and 4.1:1, which is legible as an accent and not as terminal text.
+    hueTranspose: { floor: CONTRAST_FLOORS.status },
+    provenance: {
+      project: 'Adea',
+      url: 'https://github.com/adea-ai/themes',
+      license: 'Apache-2.0',
+      bootstrappedFrom: [
+        'Nord Light (iTerm2-Color-Schemes)',
+        'GitHub Dark Default (iTerm2-Color-Schemes)',
+      ],
+    },
+  },
+])
+
 /**
  * Per-family provenance.
  *
@@ -505,9 +758,17 @@ export const VENDORED_SOURCES: readonly VendoredSource[] = Object.freeze([
  * accent — the design system's default has to work as a default for everyone, which
  * means it cannot be anybody's favourite colour.
  *
- * Both appearances are generated from the accent-and-grey ramp below, so the two
- * variants cannot drift apart: a change to the ramp changes both, and the contrast
- * suite measures both.
+ * Intentionally empty, and worth leaving that way until something needs it.
+ *
+ * This was where both default themes lived. They are now
+ * {@link COMPOSED_SOURCES} entries instead, which is a better home for them: a
+ * composition names the upstream palettes it came from and can be rebuilt when either
+ * moves, while an authored entry is a table of values nobody can refresh.
+ *
+ * The route stays because it is the only way to specify *semantic* roles directly
+ * rather than deriving them through Base24 slots — which is what a brand theme with
+ * values handed over by a designer would need. Nothing uses it today; if nothing has by
+ * the time someone reads this, delete it.
  */
 export interface AuthoredSource {
   id: string
@@ -575,108 +836,4 @@ export interface AuthoredSource {
   selection: string
 }
 
-export const AUTHORED_SOURCES: readonly AuthoredSource[] = Object.freeze([
-  {
-    id: 'adea-light',
-    family: 'adea',
-    familyLabel: 'Adea',
-    label: 'Light',
-    name: 'Adea Light',
-    description: "The default light theme. A neutral ladder with a monochrome accent.",
-    appearance: 'light',
-    tags: ['light', 'neutral', 'default'],
-    ramp: {
-      background: '#ffffff',
-      foreground: '#252525',
-      surface: '#ffffff',
-      surfaceElevated: '#ffffff',
-      surfaceHover: '#f7f7f7',
-      surfaceActive: '#f0f0f0',
-      border: '#ebebeb',
-      borderMuted: '#f2f2f2',
-      textMuted: '#6f6f6f',
-      textSubtle: '#767676',
-    },
-    accent: '#343434',
-    accentForeground: '#fcfcfc',
-    status: {
-      success: '#1a7f37',
-      warning: '#a16207',
-      error: '#c53c2b',
-      info: '#0e7490',
-    },
-    ansi: {
-      black: '#1b1f24',
-      red: '#b91c1c',
-      green: '#116a2e',
-      yellow: '#8a5a1b',
-      blue: '#0b57d0',
-      magenta: '#a0186f',
-      cyan: '#0e7490',
-      white: '#57606a',
-      brightBlack: '#57606a',
-      brightRed: '#c94d4d',
-      brightGreen: '#1f9d4f',
-      brightYellow: '#a9752c',
-      brightBlue: '#3b82f6',
-      brightMagenta: '#c04a92',
-      brightCyan: '#0891b2',
-      brightWhite: '#24292f',
-    },
-    cursor: '#24292f',
-    selection: '#b6c7ff',
-  },
-  {
-    id: 'adea-dark',
-    family: 'adea',
-    familyLabel: 'Adea',
-    label: 'Dark',
-    name: 'Adea Dark',
-    description: "The default dark theme. A soft grey, never a near-black.",
-    appearance: 'dark',
-    tags: ['dark', 'neutral', 'default'],
-    ramp: {
-      background: '#252525',
-      foreground: '#fcfcfc',
-      surface: '#2d2d2d',
-      surfaceElevated: '#343434',
-      surfaceHover: '#444444',
-      surfaceActive: '#4d4d4d',
-      border: '#3d3d3d',
-      borderMuted: '#333333',
-      textMuted: '#a3a3a3',
-      textSubtle: '#8a8a8a',
-    },
-    accent: '#ebebeb',
-    accentForeground: '#343434',
-    status: {
-      success: '#3fb950',
-      warning: '#e3b341',
-      // Lighter than the value the product shipped: `#e07060` measures 4.37:1 on
-      // this theme's raised surface and 4.09:1 on a popover, which is where an
-      // alert is most likely to sit. Same hue, same chroma, four steps up.
-      error: '#ee7c6c',
-      info: '#39c5cf',
-    },
-    ansi: {
-      black: '#2f3742',
-      red: '#ff8183',
-      green: '#56d364',
-      yellow: '#e3b341',
-      blue: '#6ca4f8',
-      magenta: '#db61a2',
-      cyan: '#39c5cf',
-      white: '#d5dde5',
-      brightBlack: '#57606a',
-      brightRed: '#ff9494',
-      brightGreen: '#79dd8a',
-      brightYellow: '#f0c264',
-      brightBlue: '#8db9ff',
-      brightMagenta: '#e87cb4',
-      brightCyan: '#66d3dc',
-      brightWhite: '#eef2f6',
-    },
-    cursor: '#e6edf3',
-    selection: '#264f78',
-  },
-])
+export const AUTHORED_SOURCES: readonly AuthoredSource[] = Object.freeze([])