@iodes/releasekit 0.1.5 → 0.1.7

package/kit/references/theme-pairing.md

@@ -10,6 +10,8 @@ This generation policy does not require inventing a second appearance for suppli
 
 Policy is captured in each release when it is prepared. Editing the project default affects new releases. To apply the current project policy to an existing draft, run `releasekit image plan <version> --sync-config`. Previously selected files are retained; themes disabled by the new policy are not exported. Ready releases must be reopened before their policy changes.
 
+For a requested palette correction, change the relevant saved theme roles at the requested project or release scope before generating replacements. A project change belongs in `releasekit/config.yaml`; sync that policy into the target draft with `releasekit image plan <version> --sync-config`. A release-only change belongs in that draft's captured visual policy. Do not work around a saved dark glyph value by adding a one-off lighter color to a prompt. Regenerate and review the affected requested variants; preserve unchanged accepted counterparts. A light-only palette correction does not request dark regeneration. If the shared geometry needs correction, update the scene and review both affected variants, keeping each theme's palette. Palette changes are authoring policy changes, not a global filter over supplied images.
+
 ## Coverage and repeat runs
 
 The default image scope is every note in the saved release, including grouped minor fixes and improvements. A grouped note has one visual brief and the configured image variants; its bullets do not become separate notes or image requests. Use [common images](common-images.md) to reuse the appropriate original across releases before planning new generation. Review the current `release.yaml` each time so newly added notes are included. A plain `releasekit-image` invocation uses this full scope without asking the user to pick important notes. Honor an explicitly limited request and the user's explicit text-only choices. If earlier agent prioritization disabled a note's image without such a choice, restore `image: true` and create or complete its visual brief in place, preserving its text, translations, and existing assets. Do not recreate the note. Missing supplied media stays pending instead of making the note text-only.
@@ -22,15 +24,15 @@ An existing image reported as stale or invalid is unresolved, even though its fi
 
 ## One scene, two presentation treatments
 
-Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change presentation surfaces, neutral values, lighting, shadows, and necessary edge separation. Preserve meaningful status colors and natural photographic or material colors. Lock the absence of accent for a neutral scene; when accent is justified, keep it on the same meaningful elements in both variants. A theme change does not introduce an accent.
+Both outputs share the same scene brief. Lock subject identity, geometry, object count, positions, scale, crop, camera, UI topology, action state, chart values, and any allowed literal labels. Change neutral presentation values and necessary surface separation within the selected recipe. Match geometry, not apparent brightness or contrast: use each theme's independent treatment. Preserve meaningful status colors and natural photographic or material colors. Lock the absence of accent for a neutral scene; when accent is justified, keep it on the same meaningful elements in both variants. A theme change does not introduce an accent.
 
 | Role | Dark treatment | Light treatment |
 | --- | --- | --- |
 | Canvas | Quiet charcoal | Quiet near-white |
-| Interface surface | Separate adjacent dark values | Separate white and pale-gray values |
-| Primary neutral symbol | Legible mid-light neutral | Legible mid-dark neutral |
-| Secondary detail | Subdued, still distinguishable | Subdued, still distinguishable |
-| Contact shadow | Soft, with enough local separation | Light, restrained, never muddy |
+| Interface surface | Distinguish base and foreground charcoal layers | Separate white and pale-gray values |
+| Primary neutral symbol | Compact mid-light neutral; no oversized bright glyph | Medium gray from `primary`, without default charcoal fills |
+| Secondary detail | Subdued, still distinguishable | Lighter `secondary` for incidental bars and supporting detail |
+| Surface separation | Preserve only feature-relevant layers | Use surface roles and thin dividers; do not invent shadows |
 | Optional interaction or status color | Preserve assignment and semantic hue, or keep absent | Preserve assignment and semantic hue, or keep absent |
 | Photo or product material | Preserve authentic appearance | Preserve authentic appearance |
 
@@ -38,18 +40,18 @@ Do not invert pixels or shift brightness globally. A black lens remains a black
 
 ## Generation sequence
 
-1. Complete the shared brief and inspect its product references.
+1. Complete the shared brief and inspect its product references. Map schematic groups to the [neutral color roles](visual-language.md#assign-neutral-colors-by-role); preserve those assignments across themes while using each theme's saved values.
 2. Read the current image plan and the project's requested themes. Reuse existing current assets and import any suitable [common originals](common-images.md), then refresh the plan. The following rendering steps apply to `action: generate`; handle `action: provide` through the supplied-image workflow.
 3. Generate one requested variant using its prompt. Select and inspect the result.
 4. Import it. Re-run the image plan; a valid approved counterpart is now offered as a composition reference for the other theme.
 5. When the available tool supports image references or edits, use the counterpart for a constrained theme edit. Otherwise repeat the exact scene contract and inspect for layout drift. Never claim pixel-identical geometry from independent stochastic generations.
-6. Compare the pair. Both files should have the same pixel dimensions. Verify pose, crop, UI state, values, and semantic colors by sight, then import the selected counterpart.
+6. Review dark images together and light images together at equal display widths, then compare the pair. Check glyph ink size, supporting detail, and charcoal layer separation in dark; check medium-gray neutral symbols and soft supporting values in light. Check equivalent elements against their configured roles without forcing equal apparent contrast between themes. Both files should have the same pixel dimensions. Verify pose, crop, UI state, values, and semantic colors by sight, then import the selected counterpart.
 
 Use one file per theme, not a split canvas or a two-panel comparison image. Keep the current selection until a reviewed replacement is imported into the same slot. Do not restart the entire release when one small defect can be corrected locally.
 
 ## Replace or regenerate an image
 
-Treat replacement and regeneration as an edit to the existing release, note ID, and affected theme. Reopen a ready release as a draft before editing it. Reuse its scene brief and current assets as needed for the requested correction. A request to regenerate an image still needs work even if the unchanged asset is reported as current by the plan; report the requested replacement as pending until it has been generated, reviewed, and imported.
+Treat replacement and regeneration as an edit to the existing release, note ID, and affected theme. A requested accent-use correction updates the shared scene's color assignment; regenerate the affected variants while preserving unrelated geometry and theme palettes. Reopen a ready release as a draft before editing it. Reuse its scene brief and current assets as needed for the requested correction. A request to regenerate an image still needs work even if the unchanged asset is reported as current by the plan; report the requested replacement as pending until it has been generated, reviewed, and imported.
 
 Keep the existing variant metadata while preparing the candidate, then run `releasekit image import <version> <note> --theme <theme> --file <selected-file>` for the same slot. Import validates the candidate and saves the new selection before removing unused managed images for this note, including older imports and obsolete shared/themed files. Reimporting identical bytes reuses the same file. Other selected variants, notes, releases, declared image references, and original source files outside the note's managed assets are preserved. If decoding or saving fails, the previous source and selection remain intact; report the replacement as pending.
 

package/kit/references/visual-language.md

@@ -29,19 +29,38 @@ For each standalone note, derive the scene from that feature independently. Grou
 
 Separate the canvas, base surface, raised surface, primary symbol, secondary detail, and divider. These are semantic roles, not a global color filter. The project defines their dark and light values.
 
-On dark backgrounds, distinguish charcoal layers and use mid-light neutral symbols. Do not crush a dark object into the canvas or turn every small glyph pure white. On light backgrounds, use near-white space, subtle gray separation, and darker neutral symbols. A dark device or natural photo may stay dark in a light presentation.
+Judge each theme at the same display width using its own saved palette. On dark backgrounds, retain distinct charcoal layers and compact mid-light neutral symbols; keep supporting UI quieter than the focal control. Avoid oversized bright glyphs, thick label bars, and milky overlays. On light backgrounds, use near-white space, subtle gray separation, and medium-gray neutral symbols with lighter supporting details. Do not use charcoal glyphs or dark placeholder bars by default. A dark device or natural photo may stay dark in a light presentation. Equal geometry does not require equal apparent brightness or contrast. A light-only palette correction leaves the accepted dark treatment intact.
 
-For icons, use a compact flat rounded-square tile with a neutral monochrome filled glyph and clear negative space. A typical tile occupies 20–24% of the canvas width, with the glyph around 50–65% of the tile width. Keep broad margins, uniform background fills, and related corner radii. Use color only when the feature gives it a functional meaning. Do not default to a colored badge, physical object, or modeled icon.
+For generic capability icons, use a compact flat rounded-square tile with a neutral monochrome filled glyph and clear negative space. A typical tile occupies 20–24% of the canvas width, with the glyph around 50–65% of the tile width. Keep broad margins, uniform background fills, and related corner radii. Use color only when the feature gives it a functional meaning. Do not default to a colored badge, physical object, or modeled icon.
 
 Flat icons and symbol pairs have no perspective, extrusion, material texture, gradients, lighting, or shadows. Simplified interfaces may use restrained layer separation where it explains the actual control hierarchy. Preserve shading already present in supplied media. Do not add sculpted objects, decorative 3D, studio lighting, glass, glow, or bevels to generated release illustrations.
 
+## Assign neutral colors by role
+
+Use the release's captured palette as the source of truth. The default palettes give the themes independent value hierarchies:
+
+| Role | Default dark value | Default light value | Assignment |
+| --- | --- | --- | --- |
+| `canvas` | `#242527` | `#F8F8F8` | Uniform background |
+| `surface` | `#18191B` | `#FFFFFF` | Base or recessed panels |
+| `raised` | `#343638` | `#ECECEC` | Foreground panels, controls, and quiet tile fills |
+| `primary` | `#B9BBBE` | `#999999` | Main glyphs, focal controls, and feature-defining marks |
+| `secondary` | `#777B80` | `#B8B8B8` | Supporting glyphs, incidental bars, and abstract content |
+| `divider` | `#46494D` | `#D9D9D9` | Thin separators and necessary boundaries |
+
+Map visible schematic groups to these roles by hierarchy in `composition`; do not choose a fresh gray for each object or each image. Object type alone does not fix its role: a foreground row can use `raised`, and a subordinate thumbnail can share `secondary` with incidental bars. A feature-relevant title, value, or control may use `primary` when the scene calls for that distinction. Preserve that hierarchy across themes and equivalent scenes; do not brighten every label bar or flatten genuinely different levels into one tone. Use the configured values, including explicit project overrides, instead of copying hex values from a worked example. Keep uniform flat fills without arbitrary warm or cool casts, opacity washes, gradients, or invented shading. Antialiased edges can contain intermediate pixels.
+
+Light illustrations explain shapes and relationships without the contrast of a text document. If something is unclear at card size, improve silhouette, spacing, stroke width, scale, or crop first. Do not globally darken glyphs and placeholder bars or introduce shadows to make every element sharper. Preserve authentic dark hardware, supplied UI, content colors, and justified semantic colors; the neutral role map applies to generated schematic elements.
+
+Review same-role objects across the release's dark images together, and separately across its light images. Use equal display widths, not differently sized website cards. In dark images inspect glyph footprint and charcoal layer separation; in light images inspect soft neutral weight. A successful decode and matching dimensions do not validate the palette or visual weight.
+
 ## Color has a job
 
-Start with a fully neutral composition. Establish the focal point through placement, scale, shape, spacing, and value contrast. An image can be complete without any accent, and a release can contain many entirely neutral images. A new feature, an important capability, or the main subject does not by itself represent an active or selected state.
+Use neutral surroundings and a clear hierarchy, then choose focal color from the feature. Prefer the project accent for the primary action, a selected or enabled control, an active route, or a defined information distinction when it helps readers find what matters. Color can guide attention even when the shape or interaction also reads in grayscale; it does not have to be indispensable.
 
-Treat the project accent as an available color, not an instruction to use it. Add it only when a specific supported state, action, or information distinction needs color to explain the change: for example, an enabled switch, a selected item, a revealed action, or an active route. Even an interaction can remain neutral when its geometry and value contrast already make it clear. Keep the colored area confined to that meaningful element; leave unrelated glyphs, tiles, and supporting surfaces neutral.
+Keep the accent on the meaningful control, state, or feature-defining component; supporting glyphs, label bars, tiles, and surfaces remain neutral. Preserve an established functional accent instead of replacing it with gray merely for restraint. Use the neutral palette roles for neutral elements, not to recolor the chosen accent target. Honor explicit monochrome choices and authentic product colors.
 
-In the shared scene's `composition`, explicitly state either that no accent is used or which element uses it and what it communicates. Preserve that assignment, including the absence of accent, in both themes. Do not invent a selection, badge, status dot, or secondary marker to justify color. For `icon-tile`, ordinary capability and maintenance symbols stay neutral. For `symbol-pair`, a simple association uses the same neutral treatment for both symbols.
+In the shared scene's `composition`, name the accent target and what it communicates, or choose a neutral treatment when appropriate. Generic capability and maintenance symbols, and simple associations between symbols, normally stay neutral. A specific action or state within those archetypes may receive accent. Do not invent a selection, badge, or status just to use color. Preserve the chosen assignment across themes; revise it in the shared scene when the user requests a change in accent use.
 
 Preserve established meanings such as warnings, completed states, traffic or map semantics, chart categories, and authentic content colors between themes. These colors belong to supported information; a generic improvement or security note is not itself a success or protection status.
 
@@ -74,6 +93,6 @@ Make the brief concrete enough that another model can render the same scene. “
 
 ## Review the actual output
 
-Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. For each accent, identify the supported meaning that would become less clear without it; if there is none, remove it. Review the release images together for repeated decorative accents. Do not give every note one colored point or enforce a fixed quota of colored images. Attractive styling and theme similarity do not establish factual or structural correctness.
+Inspect the selected image at full resolution and at roughly 350 pixels wide. First compare the image with the release note, product evidence, and scene-specific constraints; use the chosen recipe's correctness checks. Then assess whether the changed capability reads in a moment, the focal object remains distinct, incidental detail stays subordinate, and every explicit label and crop is correct. Review accent in both directions: remove decorative spread into unrelated elements, and restore the intended functional accent if it has been suppressed into gray. A useful attention cue remains valid even when the image is understandable without color. Review the release together for both overuse and habitual avoidance; do not impose a minimum, maximum, or one-colored-point-per-note quota. Attractive styling and theme similarity do not establish factual or structural correctness.
 
 For a pair, compare both outputs side by side using [theme-pairing.md](theme-pairing.md). Automated checks establish file integrity, dimensions, configured variants, and scene freshness; they do not prove visual correspondence or truthfulness. Correct a specific defect with a targeted edit instead of randomly regenerating every asset. Preserve unrelated accepted assets. Import a reviewed replacement into the same note and theme slot so unused older managed files are removed; keep the previous selection until that import succeeds.

package/kit/skills/releasekit-image/SKILL.md

@@ -11,7 +11,7 @@ When a user decision is needed during image work, such as an ambiguous target fo
 
 For standalone notes, derive one visual message from the release note and its Git/product evidence. Minor groups use the common kind's generic scene, independent of their current bullet list. Choose an archetype and `source`; the scaffold leaves both unselected. Generate flat explanatory graphics when an abstraction is sufficient. `object-detail` and `editorial-scene` require supplied media, and any other type can use an actual capture when fidelity matters. Search existing approved assets or use the user's capture; if absent, ask for the specific image and keep it pending. Do not invent a physical product, content artwork, or decorative 3D scene. Examples illustrate individual features, not default layouts.
 
-Start each generated scene in neutral values and establish its focal point through composition, scale, and contrast. In `composition`, record either no accent or the exact element and supported meaning that needs color. The configured accent is optional; a newly announced capability or a simple relationship between symbols does not justify coloring an icon. Keep generic capability and minor-group icons neutral. Preserve meaningful status, map, chart, and supplied-content colors.
+Establish a clear hierarchy with neutral supporting elements and purposeful focal color. Map visible schematic groups to the captured palette roles in `composition`, using the [neutral role assignments](references/visual-language.md#assign-neutral-colors-by-role). Assign roles by hierarchy, not object type alone, and preserve explicit project color overrides. Follow the [independent theme treatments](references/theme-pairing.md#one-scene-two-presentation-treatments): dark images retain compact mid-light neutral glyphs and necessary charcoal layers; light images use medium-gray neutral glyphs and softer supporting values. Keep flat fills consistent. Correct glyph weight and spacing in the shared scene for both themes; a light-only palette correction leaves accepted dark assets intact. In `composition`, identify the accent target and its meaning, or choose a neutral treatment when appropriate. Prefer accent for the primary action, selected/enabled state, active path, or focal information when it helps readers find the feature; it need not be indispensable in grayscale. Keep generic information and minor-group icons normally neutral. Respect explicit monochrome choices. For a requested accent revision, update the affected scene assignment instead of treating an earlier neutral choice as permanent. Preserve meaningful status, map, chart, and supplied-content colors.
 
 Complete each missing or unfinished scene brief before planning the release. Preserve the briefs of unchanged accepted images. Each note has one shared scene brief for its configured variants. Keep common minor-group scenes independent of release-specific text and evidence. For standalone scenes, encode product facts and uncertainties in `context`, the relevant state and relationships in `composition`, and the feature-specific correctness constraints in `preserve` and `avoid`. Keep reference identities and attributed style names out of prompts and assets. Inspect product references as evidence. Do not invent a concrete UI or physical design to fill missing evidence; use a supported abstraction or leave the unresolved detail in the brief.
 
@@ -21,7 +21,7 @@ For an image replacement or regeneration request, reuse the existing release and
 
 If no image generator is available, preserve the generated prompt files and report the pending assets. Continue independent editorial work. Do not silently call a paid API, install a provider, or replace requested raster illustrations with placeholders. Import user-supplied PNG, JPEG, or WebP files when they become available.
 
-Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence, including whether accent is absent or stays confined to its justified elements. Review the release images together for repeated decorative accents; do not assign one colored point to every note or impose a fixed color quota. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
+Inspect selected images at full resolution and equal small-card widths. Review dark images together for compact glyph weight and charcoal hierarchy, then light images together for soft neutral values. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence: an assigned functional accent must remain visible and confined to its intended elements. Review the release for both decorative overuse and suppressed functional accents; grayscale readability alone is not a reason to remove color. Do not impose a fixed color quota. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
 
 If the accepted image requires an alt-text correction, update the source and affected translations using [Translate selected locales](references/workflow.md#translate-selected-locales), reviewing them before recording new source fingerprints.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iodes/releasekit",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Git-based visual release notes and portable agent skills",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -157,27 +157,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base or recessed interface panels."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Foreground panels, controls, and quiet tile fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs, focal controls, and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Supporting glyphs, incidental label bars, and abstract content."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [
@@ -195,27 +201,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base or recessed interface panels."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Foreground panels, controls, and quiet tile fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs, focal controls, and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Supporting glyphs, incidental label bars, and abstract content."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [

package/schemas/release.schema.json

@@ -122,27 +122,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base or recessed interface panels."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Foreground panels, controls, and quiet tile fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs, focal controls, and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Supporting glyphs, incidental label bars, and abstract content."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [
@@ -160,27 +166,33 @@
           "properties": {
             "canvas": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Uniform illustration background."
             },
             "surface": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Base or recessed interface panels."
             },
             "raised": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Foreground panels, controls, and quiet tile fills."
             },
             "primary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Main neutral glyphs, focal controls, and feature-defining marks; mid-gray in the default light theme."
             },
             "secondary": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Supporting glyphs, incidental label bars, and abstract content."
             },
             "divider": {
               "type": "string",
-              "pattern": "^#[a-fA-F0-9]{6}$"
+              "pattern": "^#[a-fA-F0-9]{6}$",
+              "description": "Thin separators and necessary surface boundaries."
             }
           },
           "required": [