From f2e66dee0cdee20a7de0e8055f3d4b427f3d6f7b Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Thu, 24 Sep 2026 14:11:39 +0000
Subject: [PATCH] icon: a style says which ground it needs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rule 13 already observed that a style of near-black bodies and lit
accents is right on a dark terminal and illegible on a printed page, and
that only the set knows which is which — but it gave a reader no field
to read, so every surface had to guess from the style id.

`ground` is that field: light, dark or any, written into style_info.
Only agentic-emissive is dark. It matters more now that the marks are
re-rendered: the 22 whose own colour is too dark and too grey to emit
come back emitting neutral white, and on a white tile they are simply
not there. The logicsrc gallery drew exactly that until it could read
this.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/icon-hq.ts     | 1 +
 src/icon-styles.ts | 8 ++++++++
 src/icon.ts        | 7 +++++++
 3 files changed, 16 insertions(+)

diff --git a/src/icon-hq.ts b/src/icon-hq.ts
index 7879ede..8cc808e 100644
--- a/src/icon-hq.ts
+++ b/src/icon-hq.ts
@@ -419,6 +419,7 @@ export function withStyle(manifest: Manifest, style: StyleSpec, entries: Map<str
     dir: style.dir,
     label: style.label,
     material: style.material,
+    ground: style.ground,
     sizes,
     webp_sizes: [...HQ_WEBP_SIZES],
     made_by: 'both',
diff --git a/src/icon-styles.ts b/src/icon-styles.ts
index a441032..92b5431 100644
--- a/src/icon-styles.ts
+++ b/src/icon-styles.ts
@@ -53,6 +53,12 @@ export interface StyleSpec {
   dir: string;
   /** One line, for the manifest, the README and the set's index page. */
   material: string;
+  /**
+   * The ground this style needs. `dark` is a refusal a reader should honour:
+   * emissive marks that emit neutral white are invisible on a white tile, so
+   * a surface that cannot give them a dark ground should pick another style.
+   */
+  ground: 'light' | 'dark' | 'any';
   /** OpenEmoji masters used as style references; the agentic styles use none. */
   emojiRefs: readonly string[];
   /** The style paragraph, without the icon. */
@@ -211,6 +217,7 @@ function agenticStyle(variant: keyof typeof AGENTIC_MATERIALS): StyleSpec {
     label,
     dir: `styles/${id}`,
     material,
+    ground: variant === 'emissive' ? 'dark' : 'any',
     emojiRefs: [],
     styleText: `${AGENTIC_FRAME}\n${paragraph}`,
     promptFor(icon) {
@@ -230,6 +237,7 @@ export const HQ: StyleSpec = {
   label: 'HQ',
   dir: 'hq',
   material: 'Glass and enamel bodies under a warm key light, drawn beside the OpenEmoji masters.',
+  ground: 'any',
   emojiRefs: STYLE_REFS,
   styleText: HQ_STYLE,
   promptFor(icon) {
diff --git a/src/icon.ts b/src/icon.ts
index d2f9349..0245458 100644
--- a/src/icon.ts
+++ b/src/icon.ts
@@ -139,6 +139,13 @@ export interface StyleInfo {
   label?: string;
   /** One line on the material, so a reader can choose without looking. */
   material?: string;
+  /**
+   * The ground this style is drawn to sit on. `dark` means it is only legible
+   * against one — a near-black body with a lit accent vanishes on white, and
+   * the marks that emit neutral white vanish completely. Only the set knows
+   * this, so a reader that places icons has to be told rather than guess.
+   */
+  ground?: 'light' | 'dark' | 'any';
   sizes: number[];
   webp_sizes: number[];
   made_by: 'ai' | 'human' | 'both';