@kiva/kv-tokens 4.0.3 → 4.1.0

package/README.md

@@ -65,6 +65,7 @@ Our Tailwind config has some differences to the standard install. Notably
 | `@kiva/kv-tokens/js`           | `dist/js/tokens.js`         | Generated JS tokens (flat + nested)       |
 | `@kiva/kv-tokens/css`          | `dist/css/tokens.css`       | Themed CSS custom properties              |
 | `@kiva/kv-tokens/scss`         | `dist/scss/tokens.scss`     | SCSS `$variable` map                      |
+| `@kiva/kv-tokens/make-kit/*`   | `dist/make-kit/*`           | Figma Make kit (guidelines + style context) |
 
 ## Importing Source Tokens
 
@@ -99,6 +100,36 @@ Or read them off disk from `node_modules/@kiva/kv-tokens/tokens/…` — useful
 
 For the transformed, resolved-values-with-code-facing-names shape used by component code, prefer the default export of `@kiva/kv-tokens` or the flat-and-nested `@kiva/kv-tokens/js` module.
 
+## Figma Make kit
+
+`npm run build` emits `dist/make-kit/`, a [Figma Make kit](https://developers.figma.com/docs/code/write-design-system-guidelines/) built from the design-system skills in [`docs/skills/`](docs/skills):
+
+```
+dist/make-kit/
+├── styles.css                 # compiled Tailwind stylesheet (base + utilities + type + theme vars)
+└── guidelines/
+    ├── Guidelines.md          # routing document Make reads first (replaces Make's auto-created stub)
+    ├── setup.md               # how to consume the kit (styles.css, tw- prefix, theming)
+    └── foundations/*.md       # one file per design foundation
+```
+
+A skill is included in the kit when its frontmatter sets `make_kit.include: true` (with a `category` and `order`); skills without that block are excluded. Adding a new tagged skill makes it appear in the kit — and in the `Guidelines.md` routing — on the next build, with no script changes. The transform logic lives in [`build/make-kit-transform.js`](build/make-kit-transform.js); the orchestrator is [`build/build-make-kit.js`](build/build-make-kit.js).
+
+`styles.css` is the Kiva Tailwind preset compiled to a full stylesheet — base layer (fonts, headings), `tw-`-prefixed token utilities, the `tw-text-*` type system (with responsive variants), and every theme's color variables — so Make can match the design system's measurements and type whether or not it runs Tailwind itself. The safelist of utilities to emit is generated from the token scales ([`build/make-kit-safelist.js`](build/make-kit-safelist.js)), so it stays in sync as tokens change.
+
+### Importing into Figma Make
+
+Figma Make has no API to pull these in by path — you upload/drag the files into the kit. One-time setup:
+
+1. **Get the files:** `npm i @kiva/kv-tokens`, then copy from `node_modules/@kiva/kv-tokens/dist/make-kit/` (the `guidelines/` files and `styles.css`).
+2. In Figma Make: **Settings → Create a kit**.
+3. Open the **Code** view → the **`guidelines/`** folder. **Upload or drag in** `setup.md` and the `foundations/*.md` files, and replace the auto-created `Guidelines.md` with ours (or paste its contents in).
+4. Add **`styles.css`** to the project as the kit's style context (drag it into the file explorer).
+5. *(Optional)* The kit import modal also accepts npm packages and library styles, but Make kits currently support **React** codebases only — so `@kiva/kv-tokens` (a Tailwind/token package, not React) isn't added here; the compiled `styles.css` is the delivery.
+6. **Test** (prompt Make to build something and confirm it matches), then **Publish kit** to your team/org. Teammates pick it via **"Select a Make kit"** in a Make file.
+
+See [Get started with Make kits](https://help.figma.com/hc/en-us/articles/39241689698839-Get-started-with-Make-kits) and [Add guidelines to Figma Make](https://help.figma.com/hc/en-us/articles/33665861260823-Add-guidelines-to-Figma-Make).
+
 ## Local Development
 
 The `dist/` directory is gitignored but regenerated automatically by the `prepare` lifecycle script whenever you run `npm install` — both at the monorepo root and inside this package. After a fresh clone, `npm install` leaves `dist/` ready to use, so downstream workspace packages like [`@kiva/kv-components`](../kv-components/) can consume tokens without a separate build step.

package/dist/make-kit/guidelines/Guidelines.md

@@ -0,0 +1,13 @@
+# Kiva Design System — Guidelines
+
+Guidelines for building with Kiva's design system in Figma Make. Each file below covers one foundation; read the one relevant to the decision you are making. Style context (CSS custom properties for every token) is in `../styles.css`. Read `setup.md` first for how to consume the system.
+
+## Foundations
+
+- [tailwind](foundations/tailwind.md) — How to use Tailwind CSS v3 when it is backed by Kiva's design tokens — what the @kiva/kv-tokens preset changes about stock Tailwind (the tw- prefix, themable colors compiled to CSS custom properties, disabled core plugins, token-driven scales, an opinionated base layer), how to wire the preset into a project, and how the preset is compiled from DTCG tokens. Mechanical and integration-focused; for which token to pick, defer to the per-topic skills (color, spacing, radius, typography, layout).
+- [color](foundations/color.md) — Semantic color system from the Kiva design system — primitive palettes (eco-green, marigold, desert-rose, stone, gray, neutral), the five themes (Default, Green Light, Green Dark, Marigold, Stone Light), the role/slot/state token grammar, accessibility levels per pairing, and rules for picking a token by purpose rather than hex value. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [color-themes](foundations/color-themes.md) — Per-theme semantic color token tables from the Kiva design system — every token in Default, Green Light, Green Dark, Marigold, and Stone Light, with hex value, primitive source, and Figma-authored description. Plus the shadow color tokens. The reference companion to the conceptual `color` skill.
+- [typography](foundations/typography.md) — Semantic typography guidelines from the Kiva design system — type scale, heading hierarchy, font families, pairing rules, and HTML/Tailwind mappings. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [spacing](foundations/spacing.md) — Semantic spacing system from the Kiva design system — token categories (Structure, Component Gap, Component Inset, Micro), the 4px-grain ramp, responsive per-tier values, and rules for picking a token by spatial relationship rather than pixel value. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [layout](foundations/layout.md) — Layout grid system from the Kiva design system — breakpoint tiers (XS/SM/MD/LG/XL), columns, gutters, margins, nested grids, and rules for aligning content within the grid. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [radius](foundations/radius.md) — Border-radius token system from the Kiva design system — the 8-step scale from none (0px) to full (9999px), per-component use cases, the inner-radius formula for nested elements, and rules for keeping corners consistent. Sourced from Figma; values describe design intent and may diverge from current code implementation.

package/dist/make-kit/guidelines/foundations/color-themes.md

@@ -0,0 +1,317 @@
+# Kiva Color — Theme Token Tables
+
+**When to use:** When implementing or designing in a specific theme and you need the full token list for that theme — every text, background, border, and underline slot with its hex, primitive token, and intended usage description. Load this alongside the `color` skill whenever you need the canonical data, not just the framework. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+
+This is the data companion to [color](color.md). Load that first for the *why* (principles, token grammar, accessibility framework, best practices, code-state caveats); load this when you need the full per-theme token list.
+
+Five themes are documented below in the order they appear in Figma, followed by the shadow color tokens. Each table is reproduced from the Figma "Color Themes and Usage" panel and uses the format:
+
+| Token | Hex | Primitive | Description |
+
+The **Token** column is the semantic name a designer or engineer references. The **Primitive** column shows which raw value powers it — useful when tracing how the system composes, and the only place opacity-based disabled tokens (e.g., `color/gray/800-1` = `#212121 (30%)`) are visible.
+
+**Wiring colors without the Tailwind preset?** These hex and primitive values are your fallback. See [color → Using with Tailwind](color.md#using-with-tailwind): when the `@kiva/kv-tokens` preset isn't registered, the themable `tw-bg-*` / `tw-text-*` utilities don't exist, so you either pull the CSS custom properties from `@kiva/kv-tokens/css` or apply the hex values in the tables below directly (losing runtime theming).
+
+## Source-of-truth caveats
+
+Several rows in the Figma source have obvious copy-paste or transcription errors. These are surfaced in **Figma source caveats** at the bottom of each theme rather than transcribed verbatim. When in doubt, treat the **Primitive** column as the canonical answer — primitive token names rarely have typos, and the hex/description should match the primitive.
+
+---
+
+## Default theme
+
+**White base · Used across all standard page layouts.**
+
+The fully populated theme. Every other theme inherits from this one and only redefines the tokens that differ. Forms and text fields render in this theme regardless of the surrounding section.
+
+### Text
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `text/primary` | `#223829` | `color/eco-green/4` | Primary text for all body copy, headlines, and icons. The darkest eco-green value. Use it for all high-importance content. |
+| `text/primary-inverse` | `#EDF4F1` | `color/eco-green/1` | Inverted text color for dark buttons and dark backgrounds. Used on dark surfaces (like `background/primary-inverse`) to maintain contrast. |
+| `text/secondary` | `#505050` | `color/gray/600` | Medium-contrast supportive text. Used for secondary labels, subtitles, metadata, and placeholder text. |
+| `text/tertiary` | `#757575` | `color/gray/500` | Low-contrast text for subtle information. Used for hints or non-essential decorative text. |
+| `text/action` | `#276A43` | `color/eco-green/3` | Brand-colored interactive text. Used for links, clickable labels, and active navigation items. |
+| `text/action-highlight` | `#223829` | `color/eco-green/4` | Darker brand text for active/pressed states. Used when the mouse hovers over links, secondary buttons, or clickable labels. |
+| `text/action-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled text within Default sections. Opacity-based — the intentionally low contrast communicates unavailability. |
+
+### Text — Alerts
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `text/caution` | `#593207` | `color/marigold/4` | Dark text for warning context. Used for warning messages or status labels that require user attention. |
+| `text/caution-highlight` | `#996210` | `color/marigold/3` | Hover state for warning-related text. Enhances visibility for interactive warning elements during hover. |
+| `text/danger` | `#5C2A22` | `color/desert-rose/4` | Dark text for error context. Used for error messages, critical alerts, and destructive action labels. |
+| `text/danger-highlight` | `#A24536` | `color/desert-rose/3` | Hover state for error-related text. Visual feedback for interactive destructive or error-prone elements. |
+
+### Background
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/primary` | `#FFFFFF` | `color/neutral/white` | Main application surface. The base color for the entire page or main content areas. |
+| `background/primary-inverse` | `#223829` | `color/eco-green/4` | High-contrast dark surface. Use for high-emphasis containers like dark headers, sidebars, or hero cards. |
+| `background/secondary` | `#EDF4F1` | `color/eco-green/1` | Subtle secondary surface. Use for section backgrounds, form inputs, or to differentiate cards from the main page. |
+| `background/tertiary` | `#C4C4C4` | `color/gray/300` | Low-priority decorative surface. Use inside a component (e.g., the track behind a progress bar) or for a disabled button surface. Not for page or section backgrounds. |
+| `background/action` | `#276A43` | `color/eco-green/3` | Brand-colored action surface. The base color for primary buttons, active toggles, and brand-heavy elements. Pair text with `text/primary-inverse`. |
+| `background/action-highlight` | `#223829` | `color/eco-green/4` | Hover state for action surfaces. Specifically for primary button hover and interactive brand surfaces. |
+| `background/action-secondary` | `#FFFFFF` | `color/neutral/white` | Surface color for secondary button default state within Default sections. |
+| `background/action-secondary-highlight` | `#EDF4F1` | `color/eco-green/1` | Hover state for secondary surfaces. Feedback color for interactive cards or buttons on hover. |
+| `background/primary-disabled` | `#276A43` (30%) | `color/eco-green/3-1` | Disabled or inactive state for primary button (30% opacity). |
+
+### Background — Alerts
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/caution` | `#F8CD69` | `color/marigold/2` | Subtle amber background. Background color for warning banners, toast notifications, and alert callouts. |
+| `background/caution-highlight` | `#F8F2E6` | `color/marigold/1` | Hover state for warning surfaces. Feedback color for interactive warning cards or actionable alerts on hover. |
+| `background/danger` | `#E0988D` | `color/desert-rose/2` | Subtle red background. Background color for error banners, destructive action dialogs, or invalid states. |
+| `background/danger-highlight` | `#F9F0EF` | `color/desert-rose/1` | Soft red background. The standard error alert surface — paired with `text/danger` for the body copy of an error message. |
+
+### Border
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `border/primary` | `#505050` | `color/gray/600` | High-contrast border. Use for component outlines, input field borders, and strong layout dividers. |
+| `border/primary-inverse` | `#FFFFFF` | `color/neutral/white` | Inverted border for dark surfaces. Contrast border for elements placed on dark-themed containers. |
+| `border/secondary` | `#757575` | `color/gray/500` | Medium-contrast border. Use for card borders, internal table dividers, and secondary component outlines. |
+| `border/secondary-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled or inactive state for secondary button (30% opacity). |
+| `border/tertiary` | `#C4C4C4` | `color/gray/300` | Low-contrast subtle border. Use for low-emphasis decorative lines or subtle element separation. |
+| `border/action` | `#276A43` | `color/eco-green/3` | Brand-colored border. Use for active focus states, selection rings, and brand-themed outlines. |
+| `border/action-highlight` | `#223829` | `color/eco-green/4` | Hover state for Default action borders. Darker green that darkens the outline on interaction. Apply on `:hover` and `:active` only. |
+
+### Border — Alerts
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `border/caution` | `#F8CD69` | `color/marigold/2` | Dark border for warning-related components. Borders on warning banners, alert cards, or validation states. |
+| `border/caution-highlight` | `#F8F2E6` | `color/marigold/1` | Hover state for warning-related borders. Visual feedback for interactive warning components on hover. |
+| `border/danger` | `#E0988D` | `color/desert-rose/2` | Dark border for error-related components. Borders on invalid input fields, error banners, or critical alert containers. |
+| `border/danger-highlight` | `#F9F0EF` | `color/desert-rose/1` | Hover state for error-related borders. Visual feedback for interactive destructive or error components on hover. |
+
+### Underline
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `heading-underline-primary` | `#2AA967` | `color/eco-green/default` | Brand-colored heading accent. A decorative variable used for brand underlines beneath main titles. |
+
+### Figma source caveats — Default
+
+- `background/danger-highlight` in the Figma table copies `background/danger`'s description verbatim. The corrected description above reflects how the token is actually used (soft error alert surface).
+
+---
+
+## Green Light theme
+
+**Light tint surface · Secondary sections, soft brand presence.**
+
+Green Light has only two unique tokens. Everything else — text, action, alerts, borders — is inherited from Default. Use Green Light for sections that need a subtle brand tint without owning the page atmosphere.
+
+### Background
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/primary` | `#EDF4F1` | `color/eco-green/1` | Light green section background. The base surface for all Green Light theme sections. |
+| `background/primary-inverse` | `#FFFFFF` | `color/neutral/white` | Theme-specific secondary surface. Provides contrast against `background/primary` for cards and inputs. |
+
+> **Why Green Light has only two unique tokens.** Green Light inherits all text, border, and alert tokens from the Default theme — they are identical in value and usage. Only `background/primary` and `background/primary-inverse` differ, because they define the section's surface color. The shared tokens are not duplicated here to avoid confusion — refer to the Default theme tables above for everything else.
+
+---
+
+## Green Dark theme
+
+**Dark green base · For high-emphasis sections, hero areas · Never full page.**
+
+Green Dark inverts the text/background relationship and brightens the action color so it remains legible against the dark surface. Reserved for section-level emphasis; never apply to a full page. Forms still render in Default — re-wrap form children in a Default-themed container.
+
+### Text
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `text/primary` | `#EDF4F1` | `color/eco-green/1` | Primary text on dark green surfaces. Use for body copy, headlines, and icons in Green Dark sections. |
+| `text/primary-inverse` | `#223829` | `color/eco-green/4` | Dark text color. Used for contrast when text is placed on rare light-colored components within a Green Dark section. |
+| `text/secondary` | `#C4C4C4` | `color/gray/300` | Subtle light gray text. Used for secondary labels, metadata, and supporting information. |
+| `text/tertiary` | `#E0E0E0` | `color/gray/200` | Low-contrast muted text. Used for hints or non-essential decorative text. |
+| `text/action` | `#78C79F` | `color/eco-green/2` | Bright accent green. High-visibility interactive color for links and active navigation tabs against dark surfaces. |
+| `text/action-highlight` | `#EDF4F1` | `color/eco-green/1` | Hover state for action text. Strong feedback color when hovering over interactive links in Green Dark sections. |
+| `text/action-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled text within Green Dark sections. Opacity-based — the low contrast communicates unavailability. |
+
+### Background
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/primary` | `#223829` | `color/eco-green/4` | Dark green base surface. The main background for Green Dark section content areas. |
+| `background/primary-inverse` | `#FFFFFF` | `color/neutral/white` | Pure white surface. High-contrast callouts or special containers needing maximum attention within a dark section. |
+| `background/secondary` | `#276A43` | `color/eco-green/3` | Subtle secondary surface. Use for nested cards, form inputs, or to differentiate sub-regions from the main dark surface. |
+| `background/tertiary` | `#C4C4C4` | `color/gray/300` | Low-priority decorative surface. Use inside a component (e.g., progress bar track) or for a disabled button surface. |
+| `background/action` | `#78C79F` | `color/eco-green/2` | Bright action surface. High-visibility background for primary buttons to stand out against dark environments. |
+| `background/action-highlight` | `#EDF4F1` | `color/eco-green/1` | Hover state for action surfaces. Specifically for primary button hover and active brand surfaces. |
+| `background/action-secondary` | `#223829` | `color/eco-green/4` | Surface color for secondary button default state within Green Dark sections. |
+| `background/action-secondary-highlight` | `#276A43` | `color/eco-green/3` | Hover state for secondary surfaces. Feedback color for interactive cards or buttons on hover. |
+| `background/primary-disabled` | `#276A43` (30%) | `color/eco-green/3-1` | Disabled or inactive state for primary button (30% opacity). |
+
+### Border
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `border/primary` | `#EDF4F1` | `color/eco-green/1` | Light green border. Primary component boundaries and strong dividers for Green Dark layouts. |
+| `border/primary-inverse` | `#223829` | `color/eco-green/4` | Dark border color. Inverted border for elements placed on rare light-colored containers within a Green Dark section. |
+| `border/secondary` | `#276A43` | `color/eco-green/3` | Muted brand green border. Subtle separation for secondary UI elements or nested sections. |
+| `border/secondary-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled or inactive state for secondary button (30% opacity). |
+| `border/tertiary` | `#78C79F` | `color/eco-green/2` | Low-contrast subtle border. Use for low-emphasis decorative lines or subtle element separation. |
+| `border/action` | `#78C79F` | `color/eco-green/2` | Bright interactive border. Used for active selection borders and focus rings in Green Dark sections. |
+| `border/action-highlight` | `#EDF4F1` | `color/eco-green/1` | Hover state for Green Dark action borders. Lighter green that lightens the outline on interaction. Apply on `:hover` and `:active` only. |
+
+### Underline
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `heading-underline-primary` | `#2AA967` | `color/eco-green/default` | Brand-colored heading accent. A decorative variable used for brand underlines beneath main titles. |
+
+### Figma source caveats — Green Dark
+
+- The Figma table renders `text/action`, `background/action`, `border/tertiary`, and `border/action` with hex `#276A43` (an `#` typo also appears as `##276A43`), but their primitive is `color/eco-green/2`. The shipped code resolves `eco-green/2` to `#78C79F`, which matches the visual in the Figma chips. The hex column above has been corrected to `#78C79F`; if you are reading the Figma table, ignore the textual hex and trust the primitive + chip.
+- `background/primary-disabled`'s Figma description ("Hover state for error surfaces…") was copy-pasted from another row. The corrected description above reflects how the token is actually used.
+
+---
+
+## Marigold theme
+
+**Warm amber surface for marketing, decoration, warning purposes.**
+
+Warm amber atmosphere for marketing pages, donation flows, and storytelling. Note that **the code names this theme `marigold-light`** even though Figma drops the `-light` suffix.
+
+### Text
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `text/primary` | `#593207` | `color/marigold/4` | Primary text for body copy, headlines, and icons within Marigold sections. The darkest marigold value. |
+| `text/primary-inverse` | `#F8F2E6` | `color/marigold/1` | Light marigold text for content placed on dark marigold surfaces (`background/primary-inverse`). Use exclusively on dark amber backgrounds — never on light surfaces where it becomes unreadable. |
+| `text/secondary` | `#505050` | `color/gray/600` | Mid-contrast supporting text within Marigold sections — labels, subtitles, metadata. |
+| `text/tertiary` | `#757575` | `color/gray/500` | Low-contrast muted text. Used for hints or non-essential decorative text. |
+| `text/action` | `#996210` | `color/marigold/3` | Deep gold interactive text. Used for interactive links and active navigation labels. |
+| `text/action-highlight` | `#593207` | `color/marigold/4` | Hover and pressed state for `text/action` within Marigold sections. Darker value ensures increased contrast on interaction. Apply on `:hover` and `:active` only — not for static emphasis. |
+| `text/action-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled text within Marigold sections. Opacity-based — the low contrast communicates unavailability. |
+
+### Background
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/primary` | `#F8F2E6` | `color/marigold/1` | Light amber section background. The base surface for Marigold sections. Use for warning-context sections, standout CTAs, or promotional sections. |
+| `background/primary-inverse` | `#593207` | `color/marigold/4` | Dark amber surface for high-emphasis containers within a Marigold section — banners, callout cards, or feature highlights. |
+| `background/secondary` | `#FFFFFF` | `color/neutral/white` | Subtle secondary surface. Use for nested cards, form inputs, or to differentiate sub-regions from the main amber surface. |
+| `background/tertiary` | `#C4C4C4` | `color/gray/300` | Low-priority decorative surface. Use inside a component (e.g., progress bar track) or for a disabled button surface. |
+| `background/action` | `#996210` | `color/marigold/3` | Golden action surface. Base color for primary buttons and active UI elements. |
+| `background/action-highlight` | `#593207` | `color/marigold/4` | Hover state for action surfaces. Feedback color for interactive surfaces and buttons on hover. |
+| `background/action-secondary` | `#F8F2E6` | `color/marigold/1` | Surface color for secondary button default state within Marigold sections. |
+| `background/action-secondary-highlight` | `#FFFFFF` | `color/neutral/white` | Hover state for secondary buttons within Marigold sections. Visual feedback that the outlined button is interactive. Apply on `:hover` and `:active` only. |
+| `background/primary-disabled` | `#996210` (30%) | `color/marigold/3-1` | Disabled state surface for Marigold primary buttons. Low opacity signals unavailability. |
+
+### Border
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `border/primary` | `#996210` | `color/marigold/3` | Deep gold border. Main border color for defining component boundaries within Marigold sections. |
+| `border/primary-inverse` | `#F8F2E6` | `color/marigold/1` | Light marigold inverted border. Used for elements placed on dark amber surfaces. |
+| `border/secondary` | `#F8CD69` | `color/marigold/2` | Medium-contrast border. Use for card borders, internal table dividers, and secondary component outlines. |
+| `border/secondary-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled or inactive state for secondary button (30% opacity). |
+| `border/tertiary` | `#FFFFFF` | `color/neutral/white` | Low-contrast subtle border for this theme. Use for low-emphasis decorative lines or subtle element separation. |
+| `border/action` | `#996210` | `color/marigold/3` | Brand-colored border for this theme. Use for active focus states, selection rings, and brand-themed outlines. |
+| `border/action-highlight` | `#593207` | `color/marigold/4` | Hover state for Marigold action borders. Darker amber that darkens the outline on interaction. Apply on `:hover` and `:active` only. |
+
+### Underline
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `heading-underline-primary` | `#F8CD69` | `color/marigold/2` | Brand-colored heading accent. A decorative variable used for brand underlines beneath main titles. |
+
+### Figma source caveats — Marigold
+
+- The Figma table renders `border/primary-inverse` with hex `#223829` (an eco-green value) and description "Brand gold accent. Specific decorative underline for headings." Both fields appear pasted from another token; the primitive `color/marigold/1` and the surrounding Marigold palette make `#F8F2E6` the correct value. Corrected above.
+
+---
+
+## Stone Light theme
+
+**Neutral warm stone · Earth-toned content.**
+
+Editorial and story atmosphere where green would compete with imagery. Note that **the code names this theme `stone-light`** which matches Figma's naming (unlike Marigold).
+
+### Text
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `text/primary` | `#2E271E` | `color/stone/4` | Primary text for body copy, headlines, and icons within Stone Light sections. The darkest stone value. |
+| `text/primary-inverse` | `#F3F1EF` | `color/stone/1` | Light stone text. Used for contrast when text is placed on dark stone surfaces (`background/primary-inverse`). |
+| `text/secondary` | `#505050` | `color/gray/600` | Subtle gray text. Used for secondary labels, metadata, and supporting information. |
+| `text/tertiary` | `#757575` | `color/gray/500` | Low-contrast muted text. Used for hints or non-essential decorative text. |
+| `text/action` | `#635544` | `color/stone/3` | Interactive text for links and clickable labels. Passes AA on `background/primary` and `background/secondary`. Do not use on `background/tertiary` (`#C4C4C4`) — contrast fails there. |
+| `text/action-highlight` | `#2E271E` | `color/stone/4` | Hover and pressed state for `text/action` within Stone sections. Apply on `:hover` and `:active` only. |
+| `text/action-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled text within Stone sections. Opacity-based — the low contrast communicates unavailability. |
+
+### Background
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `background/primary` | `#F3F1EF` | `color/stone/1` | Warm stone section background. Base surface for Stone Light sections — testimonials, partner areas, neutral content bands. |
+| `background/primary-inverse` | `#2E271E` | `color/stone/4` | Dark stone surface for high-emphasis containers within Stone sections. Creates strong contrast — use only when genuine emphasis is needed. |
+| `background/secondary` | `#FFFFFF` | `color/neutral/white` | Subtle secondary surface. Use for nested cards, form inputs, or to differentiate sub-regions from the main stone surface. |
+| `background/tertiary` | `#C4C4C4` | `color/gray/300` | Low-priority decorative surface. Use inside a component (e.g., progress bar track) or for a disabled button surface. |
+| `background/action` | `#635544` | `color/stone/3` | Muted stone action surface. Primary button fill for Stone theme buttons. |
+| `background/action-highlight` | `#2E271E` | `color/stone/4` | Hover state for action surfaces. Visual feedback for interactive buttons or cards on hover. |
+| `background/action-secondary` | `#F3F1EF` | `color/stone/1` | Surface color for secondary button default state within Stone sections. |
+| `background/action-secondary-highlight` | `#FFFFFF` | `color/neutral/white` | Hover state for secondary surfaces. Visual feedback for interactive cards or outlined buttons on hover. |
+| `background/primary-disabled` | `#635544` (30%) | `color/stone/3-1` | Disabled or inactive state for primary button (30% opacity). |
+
+### Border
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `border/primary` | `#635544` | `color/stone/3` | Muted stone border. Used for component outlines and layout dividers within Stone sections. |
+| `border/primary-inverse` | `#2E271E` | `color/stone/4` | Dark stone border. Inverted border for elements placed on light stone containers. |
+| `border/secondary` | `#AA9E8D` | `color/stone/2` | Muted stone border. Subtle separation for secondary UI elements or nested sections. |
+| `border/secondary-disabled` | `#212121` (30%) | `color/gray/800-1` | Disabled or inactive state for secondary button (30% opacity). |
+| `border/tertiary` | `#FFFFFF` | `color/neutral/white` | Low-contrast subtle border. Use for low-emphasis decorative lines or subtle element separation. |
+| `border/action` | `#635544` | `color/stone/3` | Muted stone interactive border. Base color for action selection borders and primary button outlines. |
+| `border/action-highlight` | `#2E271E` | `color/stone/4` | Hover state for Stone action borders. Visual feedback when hovering over interactive brand elements (e.g., secondary buttons). |
+
+### Underline
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `heading-underline-primary` | `#AA9E8D` | `color/stone/2` | Brand-colored heading accent. A decorative variable used for brand underlines beneath main titles. |
+
+### Figma source caveats — Stone Light
+
+- `background/action-secondary-highlight` and `background/primary-disabled` descriptions in Figma are copy-pasted from other rows ("Hover state for warning surfaces…" and "Hover state for error surfaces…"). The corrected descriptions above reflect actual use.
+- `border/secondary`'s Figma description refers to "muted brand green border" — left-over text from the Green Dark table. Corrected to "muted stone border."
+
+---
+
+## Shadow colors
+
+Three color tokens drive elevation. Apply the shadow token via the relevant component or utility rather than hand-rolling an `rgba()` — that way dark-theme shadows can be retuned without component rewrites.
+
+| Token | Hex | Primitive | Description |
+|---|---|---|---|
+| `shadow/default` | `#000000` (8%) | `color/shadow/default` | Default elevation shadow. Apply to cards, sticky elements, and any surface that should read as "lifted off the page." |
+| `shadow/hover` | `#000000` (16%) | `color/shadow/hover` | Stronger shadow for hover and interactive emphasis. Adds visible lift on `:hover` for cards and buttons. |
+| `shadow/click-active` | `#000000` (8%) | `color/shadow/click-active` | Pressed-state shadow. Used on `:active` to communicate the surface has been pushed back toward the page. |
+
+### Figma source caveats — Shadow
+
+- The Figma shadow table has the description and primitive-token columns swapped between the `shadow/hover` and `shadow/click-active` rows. The (semantic name, hex) pairings by row position are canonical and have been used above; the `:hover`-typically-stronger-than-`:active` convention confirms the assignment.
+
+---
+
+## Figma source reference
+
+- Color Themes and Usage: node `17950:8787`
+  - Default theme table: `18644:1206`
+  - Green Dark theme table: `18703:11854`
+  - Green Light theme table: `18712:12784`
+  - Marigold theme table: `18703:12254`
+  - Stone Light theme table: `18703:12497`
+  - Shadow token table: `18712:12793`
+
+File: `TPmBUB4olYPMF6glEhBGDG` (Ecosystem 2026 — WIP)

package/dist/make-kit/guidelines/foundations/color.md

@@ -0,0 +1,235 @@
+# Kiva Color
+
+**When to use:** When designing or implementing anything that has color — backgrounds, text, borders, button surfaces, alert states, themed sections — or when picking between two tokens that look similar. Use it before reaching for a hex value, before applying a theme to a section, and any time a color decision crosses a semantic line (action vs. caution, primary vs. secondary, default vs. inverse). Reference design intent first; verify token names against current code before relying on them.
+
+## Source of truth
+
+This skill captures the **semantic color system** as defined in Figma (the Kiva Ecosystem 2026 file). Figma is the canonical source for design intent: which primitives exist, which themes are supported, what each semantic token means, when to use it, and how tokens compose into accessible pairings.
+
+Hex values and token names in this document reflect the Figma specifications. The shipped code in `@kiva/kv-tokens` may temporarily lag behind these specs while the token sync work is in progress. **Verify any token reference against the current code before depending on it.** See "Outstanding discrepancies" at the end of this skill for known gaps, and "Using with Tailwind" for code naming and the shipped utility surface.
+
+## Why color matters
+
+Color does work on Kiva that the rest of the system can't: it tells a lender which button advances the lending flow, signals to a borrower that a field is in error, and separates a marigold "story" section from a default "form" section without needing a single word of copy. The semantic color system encodes that work in token names — `background/action` is *the* button color in whatever theme is active, not "green" — so the same component behaves correctly under any of the five themes.
+
+Common alternative names you may see used interchangeably: **color palette**, **color variables**, **design tokens**, **swatches**, **semantic colors**.
+
+## Design principles
+
+1. **Name the purpose, not the hue.** Use `text/action` for an interactive link, not "green" — the token resolves to the right color per theme. If you ever find yourself picking a token because it "looks right," step back and pick by intent.
+2. **Themes scope intent.** A theme is a coordinated set of role/slot tokens tuned for one page atmosphere. The token name stays the same across themes; the value changes. Compose pages from themed *sections*, don't repaint individual components.
+3. **Semantic meanings don't theme.** Error stays red, warning stays amber. Caution and danger token values are stable across themes precisely because the meaning is stable.
+4. **Always reference semantic tokens, not primitives.** Primitives exist to *build* semantic tokens. Components should never reach past the semantic layer into a raw `eco-green/3` or `gray/500`.
+
+## Primitives
+
+Primitive tokens are the raw values that power every semantic token. Use these only when defining new semantic tokens — components should always consume the semantic layer.
+
+| Family | Step | Hex | | Family | Step | Hex |
+|---|---|---|---|---|---|---|
+| **eco-green** | 1 | `#EDF4F1` | | **stone** | 1 | `#F3F1EF` |
+| | 2 | `#78C79F` | | | default | `#DFD0BC` |
+| | default | `#2AA967` | | | 2 | `#AA9E8D` |
+| | 3 | `#276A43` | | | 3 | `#635544` |
+| | 4 | `#223829` | | | 4 | `#2E271E` |
+| **marigold** | 1 | `#F8F2E6` | | **gray** | 50 | `#FAFAFA` |
+| | 2 | `#F8CD69` | | | 100 | `#F5F5F5` |
+| | default | `#F4B539` | | | 200 | `#E0E0E0` |
+| | 3 | `#996210` | | | 300 | `#C4C4C4` |
+| | 4 | `#593207` | | | 400 | `#9E9E9E` |
+| **desert-rose** | 1 | `#F9F0EF` | | | 500 | `#757575` |
+| | 2 | `#E0988D` | | | 600 | `#505050` |
+| | default | `#C45F4F` | | | 700 | `#454545` |
+| | 3 | `#A24536` | | | 800 | `#212121` |
+| | 4 | `#5C2A22` | | **neutral** | white | `#FFFFFF` |
+| | | | | | black | `#000000` |
+
+The stone family uses an out-of-order step naming (`1`, `default`, `2`, `3`, `4`) so the lighter swatch keeps the visual position designers expect. Don't try to "fix" it.
+
+> **Figma label typo for `eco-green/2`.** The Color Overview panel renders the text label `#C7EDD7` on top of the `eco-green/2` swatch, but the swatch's *actual fill* is `#78C79F` (the value above). The label is stale; the chip color, the Figma `color/eco-green/2` variable, and the shipped code (`tokens/core/color.json`) all agree on `#78C79F`. Use `#78C79F`.
+
+## Themes
+
+Five themes are supported. Each is suited to a specific page atmosphere; choose one as the section's base and let the semantic tokens do the rest.
+
+| Theme | Atmosphere | Use for |
+|---|---|---|
+| **Default** | White background, neutral and trustworthy | Forms, dashboards, primary content surfaces. The required theme for any form or text field. |
+| **Green Light** | Light green tinted surfaces | Secondary sections that lean on brand color without dominating. Inherits Default's text, action, and caution tokens. |
+| **Green Dark** | Dark green sections | High-emphasis brand moments (impact stats, partner CTAs). Section-level only — never the whole page. |
+| **Marigold** | Warm amber accents | Marketing, donation, warmth-forward stories. |
+| **Stone Light** | Neutral warm stone | Editorial / story content where green would compete with imagery. |
+
+## Token grammar
+
+Every semantic token reads as **role / slot / state-modifier**:
+
+| Part | Meaning | Examples |
+|---|---|---|
+| **Role** | What kind of property the token paints. | `text`, `background`, `border`, `heading-underline`, `shadow` |
+| **Slot** | What the color communicates. | `primary`, `secondary`, `tertiary`, `action`, `caution`, `danger` |
+| **State modifier** *(optional)* | Interaction or context variant. | `highlight` (hover / pressed), `inverse` (on opposite-tone surface), `disabled`, `secondary` (alternate emphasis within a state) |
+
+A few practical reads:
+
+- `text/primary` — the standard body copy color for the current theme.
+- `background/action-highlight` — the button surface under a hover or pressed state.
+- `border/primary-inverse` — the border color used when the component sits on a dark surface in the current theme.
+- `text/danger` — the foreground for an error message; pair with `background/danger-highlight` for the standard alert surface.
+
+## Per-theme token tables
+
+Every theme's full token list — name, hex, primitive source, and Figma-authored description for every text / background / border / underline token — lives in the companion reference file [color-themes.md](color-themes.md). That file is the data layer; this file is the framework.
+
+A quick orientation before you load it:
+
+- **Default** is the base. Every other theme inherits Default and only redefines the tokens that differ.
+- **Green Light** is the smallest theme — only two unique tokens (`background/primary`, `background/primary-inverse`). Everything else falls back to Default.
+- **Green Dark**, **Marigold**, and **Stone Light** each define their own full set of text / background / border tokens plus `heading-underline-primary`.
+- **Alert tokens** (`text/caution(+-highlight)`, `text/danger(+-highlight)`, `background/caution(+-highlight)`, `background/danger(+-highlight)`, `border/caution(+-highlight)`, `border/danger(+-highlight)`) are defined on Default only and used unchanged across themes — caution stays amber, danger stays desert-rose. See "Preserve semantic color meaning" below.
+
+The companion file also documents `shadow/default`, `shadow/hover`, and `shadow/click-active` and calls out the (several) Figma copy-paste errors in the source table.
+
+## The disabled-state pattern
+
+Disabled tokens (`text/action-disabled`, `background/primary-disabled`, `border/secondary-disabled`) are not full new color values — they are an **existing primitive at reduced opacity**. The Figma table renders this as a primitive name with a `-1` suffix (e.g., `color/gray/800-1` = `#212121` at 30%; `color/eco-green/3-1` = `#276A43` at 30%).
+
+The takeaway: a disabled state is the active-state color washed down — not a separately tuned gray. If you find yourself reaching for a custom disabled color, use the matching `*-disabled` token instead.
+
+## Shadow tokens (interaction-driven)
+
+Three color tokens drive elevation: `shadow/default` (resting), `shadow/hover` (lifted on hover), `shadow/click-active` (pressed). The naming is **interaction-state-based**, not severity-based. Full descriptions in [color-themes.md](color-themes.md#shadow-colors).
+
+## Accessibility
+
+Every meaningful foreground/background pairing in the Figma "Color Accessibility" panel is rated against **WCAG 2.1 AA (4.5:1)** and **AAA (7:1)** for normal body text.
+
+| Badge | Meaning | Safe for |
+|---|---|---|
+| **Pass** | Ratio ≥ 7:1 (passes AA and AAA) | All text, all sizes. |
+| **AA only** | 4.5:1 ≤ ratio < 7:1 | Normal body text; not for extended reading at small sizes or thin weights. |
+| **Large only** | 3:1 ≤ ratio < 4.5:1 | Large text (≥ 18pt or ≥ 14pt bold), icons, decorative type — never small body copy. |
+| **Fail** | Ratio < 4.5:1 (below AA) | Non-text decorative use only, or intentionally low-emphasis states (e.g., disabled). |
+
+A "Fail" is not automatically a bug. Some pairings fail on purpose — disabled controls, decorative panels — but a few are dangerous and should never be used for readable content. The Figma panel calls those out individually; treat its annotations as authoritative for which "Fail" pairings are acceptable.
+
+Notable real-world callouts from the Figma rating tables:
+
+- **Default theme:** `text/tertiary` on `background/secondary` is `4.1:1` and on `background/tertiary` is `2.6:1` — both flagged **Fail** in Figma with the note "Does not pass AA at any text size." Don't use `text/tertiary` for readable copy on those surfaces; use `text/primary` or `text/secondary` instead. (The 4.1:1 ratio technically clears 3:1 for large text, but the design system team is explicit that this pairing should not be used for readable text — heed the explicit guidance.)
+- **Green Light:** inherits Default's text/action/caution ratings — refer to Default for those, not duplicated in the Green Light table.
+- **Green Dark:** has a critically low pairing (`text/primary` on `background/tertiary` at `1.5:1`) explicitly flagged "must never be used." Treat the warning as load-bearing.
+- **Marigold:** `text/tertiary` pairings drop into Large-only or Fail; keep tertiary text off Marigold body surfaces.
+- **Stone Light:** similar caution around `text/tertiary` — Large-only on `background/primary`, Fail on `background/tertiary`.
+- **Alerts:** the alert tokens (`text/caution(+-highlight)`, `text/danger(+-highlight)`) are defined on Default and used across themes. They pass AA on their paired alert backgrounds.
+
+When in doubt, look the pairing up in the Figma table before approving it for body copy.
+
+## Best practices
+
+### Limit 1–2 primary themes per page
+
+- **Do** keep a page visually cohesive by anchoring it in one to two primary themes, with an optional tertiary theme for emphasis if needed.
+- **Don't** stack multiple themed sections (Default → Green Dark → Stone Light → Marigold) in a single page — the page reads as a swatchbook.
+
+### Buttons adapt to their theme context
+
+- **Do** use the theme's `background/action` and `text/action` tokens — the button reads as "primary" in whatever theme it sits in.
+- **Don't** hard-pin a button to a specific brand color or override `background/action` to enforce a global "primary green." Doing so breaks contrast guarantees in dark themes and defeats the point of theming.
+
+### Don't mix theme content within a single section
+
+- **Do** keep all content inside one section on the same theme. Theme switches should align with section boundaries.
+- **Don't** drop a Green Dark card into a Default section just to call attention to it — use spacing, hierarchy, or a sectioning component instead.
+
+### All forms and text fields follow the Default theme
+
+- **Do** render forms and inputs in Default theme, even when the surrounding section uses another theme.
+- **Don't** apply alternate themes to inputs, selects, or controls. Input contrast and focus states are tuned only against Default; off-theme inputs fail accessibility and read as broken.
+
+### Dark theme is for sections, not pages
+
+- **Do** use Green Dark to highlight specific sections.
+- **Don't** stack multiple Green Dark sections back to back without a visual break — the page loses rhythm and the dark sections stop reading as emphasized.
+
+### Preserve semantic color meaning
+
+- **Do** keep alert colors stable — caution is amber, danger is desert-rose, success is eco-green. Use `text/danger` and the danger backgrounds only for error states.
+- **Don't** redefine what a color represents per context (e.g., using desert-rose as a brand accent in a marketing band). The same color must mean the same thing everywhere or the system stops communicating.
+
+## How to use in Figma
+
+### Picking the right token
+
+Tokens are namespaced in the Figma variable picker by role. Search keywords:
+
+- `text` for foregrounds, `background` (or `bg`) for surfaces, `border` for outlines.
+- Add the slot to narrow further: `text/action`, `background/primary-inverse`, `border/danger-highlight`.
+
+If the variable picker shows two tokens with the same hex value, pick by *role*, not by value — `border/secondary` and `text/secondary` resolve to the same gray today but will diverge if the secondary text ramp shifts.
+
+### Theming a section
+
+1. Wrap the section frame in a component or auto-layout container themed via Figma variable modes.
+2. Switch the mode to the target theme (`default`, `green-light`, `green-dark`, `marigold`, `stone-light`).
+3. Every variable-bound color in that subtree updates automatically.
+4. Forms inside the section still use Default — re-wrap form children in a Default-themed container.
+
+### Before handoff
+
+Walk the file and check fills, strokes, and text colors for raw hex values. **Re-bind any raw value to a variable** — a raw hex is a detached color decision that won't follow updates and gives engineering nothing to map to. The Figma panel calls this out explicitly; treat it as a hard gate on hand-off.
+
+## Using with Tailwind
+
+The color utilities come from the `@kiva/kv-tokens` Tailwind preset. Haven't registered it yet? See [tailwind → Consuming the preset](tailwind.md#consuming-the-preset). Not using the preset? See [Without the preset](#without-the-preset) below.
+
+**Themable colors** are exposed as `tw-text-{slot}`, `tw-bg-{slot}`, `tw-border-{slot}`, `tw-divide-{slot}`, and `tw-ring-{slot}` — e.g. `tw-bg-primary`, `tw-text-action`, `tw-border-danger-highlight`. The slot names match the semantic token names in [color-themes.md](color-themes.md) (with `background/` → `bg-`). They compile to `rgb(var(--token))` and resolve at runtime from CSS custom properties, so they follow the active theme — reach for them by default. See [tailwind → Color is semantic, themable, and runtime-resolved](tailwind.md#color-is-semantic-themable-and-runtime-resolved), and [tailwind → Make themable colors resolve](tailwind.md#3-make-themable-colors-resolve-required-for-color-to-render) for how the custom properties get onto the page (`KvThemeProvider` does this in components).
+
+**Primitive (non-themed) utilities** — `tw-bg-eco-green-3`, `tw-text-marigold-DEFAULT`, `tw-bg-gray-100`, etc. — resolve directly to primitive values and do **not** change with theme. Use sparingly; components should consume semantic tokens, not primitives.
+
+**Theme names: type the code name, not the Figma name.** When importing themes from `@kiva/kv-tokens` (e.g. `marigoldLightTheme`) or referencing one in code:
+
+| Figma (design intent) | Code (what to type) |
+|---|---|
+| Default | `DEFAULT` |
+| Green Light | `green-light` |
+| Green Dark | `green-dark` |
+| Marigold | `marigold-light` *(code suffixes `-light`)* |
+| Stone Light | `stone-light` |
+
+Legacy themes still exported in code (`dark`, `dark-green`, `dark-mint`, `dark-stone`, `mint`, `stone-dark`) predate the five-theme system and are kept for backwards compatibility — **don't pick them for new work.**
+
+**Authoritative sources** (verify before depending):
+
+- `@kiva/kv-tokens/tokens/core/color.json` — primitive palette declarations.
+- `@kiva/kv-tokens/dist/js/tokens.js` (`colors.theme.*`) — the built, per-theme semantic token tree.
+- `@kiva/kv-tokens/configs/kivaColors.js` — turns each theme into CSS custom properties and exposes the Tailwind color choices.
+- `@kiva/kv-tokens/configs/tailwind.config.js` — wires the custom properties into the `tw-text-*` / `tw-bg-*` / `tw-border-*` / `tw-divide-*` / `tw-ring-*` utilities.
+- [`KvThemeProvider.vue`](../../../kv-components/src/vue/KvThemeProvider.vue) — sets the theme custom properties on a subtree.
+
+### Without the preset
+
+- **Kiva (or Kiva-adjacent) repo, preset not registered yet:** install and register it — [tailwind → Consuming the preset](tailwind.md#consuming-the-preset).
+- **Stock-Tailwind / non-Kiva project:** the themable utilities won't exist. Either import the shipped custom properties from `@kiva/kv-tokens/css` ([`dist/css/tokens.css`](../../dist/css/tokens.css), which ships a `:root` block plus `[data-theme="…"]` blocks) and reference `var(--token)` yourself, or use the static hex values from [color-themes.md](color-themes.md). The hex route loses runtime theming and the values are point-in-time.
+
+## Outstanding discrepancies
+
+- **`heading-underline/primary` is the only `heading-underline` token shipped,** and only Default, Marigold, and Stone Light (plus legacy `stone-dark`) define it; other themes fall back to whatever the parent provides.
+- **Semantic tokens defined in Figma but not yet in the shipped `colors.theme.*` tree:**
+  - `text/action-disabled` (all themes)
+  - `background/action-secondary`, `background/action-secondary-highlight`, `background/primary-disabled` (all themes except Green Light)
+  - `border/secondary-disabled`, `border/tertiary` (Green Dark, Marigold, Stone Light)
+  - `text/secondary`, `text/tertiary`, `background/tertiary`, `border/tertiary` (Green Dark, Marigold, Stone Light)
+
+  These can be added without breaking changes since they're new entries.
+- **Shadow tokens are not yet color-tokenized.** `boxShadow.DEFAULT` and `boxShadow.lg` in `tailwind.config.js` are hardcoded `rgb(0 0 0 / 0.08)`; the `shadow/default`, `shadow/hover`, `shadow/click-active` semantic tokens described in Figma have no code entry yet.
+
+When you find a divergence between this skill and the shipped tokens/components, flag it — closing those gaps is part of the long-running token sync work, and each instance is a data point.
+
+## Figma source references
+
+- Color Overview: node `18445:832`
+- Color Themes and Usage: node `17950:8787`
+- Color Accessibility: node `18829:465`
+- Color Guidelines: node `18296:7293`
+
+File: `TPmBUB4olYPMF6glEhBGDG` (Ecosystem 2026 — WIP)