@openpresentation/opf-editor 0.22.0 → 0.23.0

package/README.md

@@ -110,7 +110,7 @@ Chart options (RR-35): `@openpresentation/opf-editor/chart-options` edits a char
 
 Chart highlight (FA-14): the same module edits `chart.highlight`: `setChartOptions(editor, chartPath, { highlight: { series: ["Revenue"], categories: ["Q3"] } })` replaces each listed part (an empty list removes it, `null` removes the field), refuses a name the chart does not have, and writes only what the chart type can highlight (core `chartOptionSupport(...).highlight`). `readChartOptions(chart, document)` returns the `choices` (plotted series and category labels, resolved through the document for a dataset chart), and the panel lists them as two groups of checkboxes ("Highlight series", "Highlight categories").
 
-Chart colors (known gap): core 0.21 added `chart.colors` (a position-matched list of series or category colors, as a hex color, a scheme slot or a role), and opf-pptx 0.22.0 exports it (the opf-render preview follows once opf-render#256 lands), but the editor has no control for it yet. The chart options panel edits `highlight` as its only color-related setting (the two checkbox groups above), and `setChartOptions` does not accept `colors`. Until a control exists, set `chart.colors` in the document directly (the JSON control or a patch).
+Chart colors (RR-96): the same module edits `chart.colors`, the colors by position, as one undoable patch: `setChartOptions(editor, chartPath, { colors: ["accent3", "#7B241C"] })` replaces the list (an entry is a hex color, a scheme slot such as `accent3`, which keeps following the deck and is written to PowerPoint as a theme color, or a `var:` color variable; `null` or `""` leaves that position to the deck palette, written as the palette color itself when a later position is set; `null` for the whole value removes the field; at most 24). `readChartOptions` reports what a position means (`colors.by`: the plotted series, the slices or rows of a pie, doughnut, treemap or funnel, or the colors a histogram, pareto or waterfall draws with; `colors.labels`) and the list as written (`state.colors`). The chart options panel gains a "Colors" group: one row per position with the deck's accent swatches, a "Default" choice and a hex field, plus "Reset to deck palette". The swatches come from `readSchemeSlots` (`/color-slots`), the deck's resolved scheme at a slide. The opf-render preview draws `chart.colors` once opf-render#256 lands; the document, Undo and the PowerPoint export carry it now.
 
 ```js
 import { createCanvasEditor } from '@openpresentation/opf-editor/canvas';
@@ -351,6 +351,8 @@ The playground's Content tab mounts the block-level and slide-structure actions
 
 `@openpresentation/opf-editor/design-options` edits the design-level settings that used to need All properties. Each call is one validated patch and one undo step, at the deck or on one slide with `slideIndex`; `null` removes a value so it is inherited again. `prepare...` forms return the patch without touching a session.
 
+Color variants (RR-96, needs core 0.23): `@openpresentation/opf-editor/design-variants` edits `design.variant`, PowerPoint's Variants for the deck's one color scheme: a mapping over its twelve slots (never a second scheme) that says which slot is the background, and so the text and the alternate surface, plus an optional accent order. `setDesignVariant(editor, "dark1")` writes the slot name (so it keeps following the scheme), at the deck or on one slide with `{ slideIndex }`; `{ accents: [...] }` reorders the six accents and keeps the background; `null` removes the variant (a slide then follows the deck); `{ clearSlideOverrides: true }` also removes slides' own variants that would hide a deck change, and the result's `shadowed` lists the slides whose own variant or theme-slot background still does. `readDesignVariant` reports the scope's own variant and the effective one (core's resolution, so a theme-slot background or a picture's `tone` counts) and `variantSwatches` the four variants (`light1`, `light2`, `dark1`, `dark2`) as colors built from the deck's own slots, like PowerPoint's gallery. The design controls gain a "Color variant" section with those four swatches, "Same as presentation" on a slide, and an accent order control; the editor imports core's `normalizeColorVariant`, so it needs core 0.23 (the peer floor moves with the release). The preview and the PowerPoint export read the variant from core's roles (the renderer and exporter releases that follow core 0.23); the editor only commits the patch.
+
 ```js
 import { setDesignOption, setOrganizationLogo, setHeaderFooterZone, insertZoneValue, insertZoneLogo, getDesignOption, designWarnings } from "@openpresentation/opf-editor/design-options";
 

package/dist/chart-options-panel.js

@@ -4,8 +4,11 @@
 // `setChartOptions` (src/chart-options.js), the canvas redraws, and Undo restores the chart. The panel shows only what
 // the selected chart type can show (core's support table), and hides itself when no chart is selected. On a combo chart
 // (FA-15) a "Series" group sets which series are lines and which lines use the secondary value axis, and a secondary axis
-// title field appears while a line uses that axis.
+// title field appears while a line uses that axis. (RR-96) A "Colors" group sets the color of each series (or slice) from the deck's accent
+// swatches or a hex color; a swatch writes the scheme slot, so the chart keeps following the deck.
 import { CHART_LABEL_CONTENT, CHART_LEGEND_POSITIONS, parseChartPath, readChartOptions, setChartOptions } from "./chart-options.js";
+import { readSchemeSlots } from "./color-slots.js";
+import { isColorRef } from "./background-options.js";
 
 const LEGEND_LABELS = { default: "Default", none: "None", top: "Top", bottom: "Bottom", left: "Left", right: "Right" };
 const CONTENT_LABELS = { category: "Category", value: "Value", percent: "Percent" };
@@ -46,6 +49,7 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       <label class="opf-co-row" data-row="position"><span>Label position</span><select id="${id}-position" aria-label="Label position" data-opf-chart-option="dataLabels.position"></select></label>
       <label class="opf-co-row" data-row="separator"><span>Separator</span><input type="text" id="${id}-separator" aria-label="Label separator" data-opf-chart-option="dataLabels.separator" autocomplete="off"></label>
     </div>
+    <fieldset class="opf-co-group opf-co-colors" data-group="colors"><legend>Colors</legend><div data-row="colors"></div><button type="button" class="opf-co-reset" data-opf-chart-option="colors.reset" aria-label="Reset chart colors to the deck palette">Reset to deck palette</button></fieldset>
     <div class="opf-co-group" data-group="highlight">
       <fieldset class="opf-co-highlight" data-part="series"><legend>Highlight series</legend><div class="opf-co-choices" data-choices="series"></div></fieldset>
       <fieldset class="opf-co-highlight" data-part="categories"><legend>Highlight categories</legend><div class="opf-co-choices" data-choices="categories"></div></fieldset>
@@ -54,11 +58,12 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
   const $ = (selector) => root.querySelector(selector);
   const fields = {
     alt: $(`#${id}-alt`), decorative: $(`#${id}-decorative`), category: $(`#${id}-category`), value: $(`#${id}-value`), secondary: $(`#${id}-secondary`), legend: $(`#${id}-legend`), labels: $(`#${id}-labels`),
-    series: $("[data-row='combo-series']"),
+    series: $("[data-row='combo-series']"), colors: $("[data-row='colors']"), colorsReset: $("[data-opf-chart-option='colors.reset']"),
     position: $(`#${id}-position`), separator: $(`#${id}-separator`), contents: [...root.querySelectorAll("[data-opf-chart-option^='dataLabels.content.']")],
     highlight: { series: $("[data-choices='series']"), categories: $("[data-choices='categories']") },
   };
   let chartPath;
+  let colorState = { entries: [], count: 0 };
 
   function refresh() {
     const path = parseChartPath(getSelectedPath?.() ?? "");
@@ -70,7 +75,7 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       return;
     }
     chartPath = path;
-    const { fields: support, state, choices, combo } = readChartOptions(chart, editor.presentation);
+    const { fields: support, state, choices, combo, colors } = readChartOptions(chart, editor.presentation);
     root.hidden = false;
     const setValue = (input, value) => { if (input !== document.activeElement && input.value !== value) input.value = value; };
     setValue(fields.alt, state.alt);
@@ -145,6 +150,62 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       for (const input of list.querySelectorAll("input")) input.checked = state.highlight[part].includes(input.value);
     }
     $("[data-group='highlight']").hidden = $("[data-part='series']").hidden && $("[data-part='categories']").hidden;
+    refreshColors(colors, state.colors, chartPath);
+  }
+
+  // RR-96: one row per position of `chart.colors`: the deck's accent swatches, a "Default" choice and a hex field. The swatches are the
+  // deck's own colors (the resolved scheme of the chart's slide), and choosing one writes its slot name.
+  function refreshColors(positions, entries, path) {
+    colorState = { entries, count: positions.labels.length };
+    const slide = Number(/^slides\.(\d+)/.exec(path)?.[1] ?? 0);
+    const slots = readSchemeSlots(editor.presentation, { slideIndex: slide, catalogs: editor.catalogs });
+    const signature = JSON.stringify([positions.labels, positions.slots.map((slot) => slots[slot] ?? ""), entries]);
+    $("[data-group='colors']").hidden = positions.labels.length === 0;
+    fields.colorsReset.hidden = entries.length === 0;
+    if (fields.colors.dataset.signature === signature) return;
+    fields.colors.dataset.signature = signature;
+    fields.colors.replaceChildren(...positions.labels.map((name, index) => {
+      const entry = entries[index] ?? "";
+      const row = document.createElement("div");
+      row.className = "opf-co-row opf-co-color-row";
+      row.dataset.position = String(index);
+      const label = document.createElement("span");
+      label.textContent = name;
+      const group = document.createElement("span");
+      group.className = "opf-co-swatches";
+      group.setAttribute("role", "group");
+      group.setAttribute("aria-label", `${name} color`);
+      const choose = (value, text, color) => {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "opf-co-swatch";
+        button.dataset.opfChartOption = "colors.choose";
+        button.dataset.color = value;
+        button.setAttribute("aria-label", `${name}: ${text}`);
+        button.setAttribute("aria-pressed", String(entry === value));
+        if (color) button.style.background = color;
+        else button.textContent = "Default";
+        return button;
+      };
+      group.append(choose("", "deck palette", undefined), ...positions.slots.map((slot, k) => choose(slot, `accent ${k + 1}`, slots[slot])));
+      const hex = document.createElement("input");
+      hex.type = "text";
+      hex.className = "opf-co-hex";
+      hex.dataset.opfChartOption = "colors.hex";
+      hex.setAttribute("aria-label", `${name} hex color`);
+      hex.placeholder = "#RRGGBB";
+      hex.autocomplete = "off";
+      hex.value = entry && !positions.slots.includes(entry) ? entry : "";
+      row.append(label, group, hex);
+      return row;
+    }));
+  }
+
+  // The `colors` list with position `index` set to `value` ("" leaves it to the deck palette); other positions keep what the chart has.
+  function colorsWith(index, value) {
+    const next = Array.from({ length: Math.max(colorState.entries.length, index + 1) }, (_, k) => colorState.entries[k] ?? null);
+    next[index] = value || null;
+    return next;
   }
 
   function commit(change, message) {
@@ -175,6 +236,21 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
     [fields.labels, "change", () => commit({ dataLabels: fields.labels.checked }, fields.labels.checked ? "Showing data labels. Undo restores the chart." : "Hid the data labels. Undo restores them.")],
     [fields.position, "change", () => commit({ dataLabels: { position: fields.position.value } }, "Moved the data labels. Undo restores them.")],
     [fields.separator, "change", () => commit({ dataLabels: { separator: fields.separator.value } }, "Changed the label separator. Undo restores it.")],
+    [fields.colors, "click", (event) => {
+      const button = event.target.closest?.("[data-opf-chart-option='colors.choose']");
+      if (!button) return;
+      const index = Number(button.closest("[data-position]").dataset.position);
+      commit({ colors: colorsWith(index, button.dataset.color) }, button.dataset.color ? "Changed a chart color. Undo restores it." : "Returned a chart color to the deck palette. Undo restores it.");
+    }],
+    [fields.colors, "change", (event) => {
+      const input = event.target.closest?.("[data-opf-chart-option='colors.hex']");
+      if (!input) return;
+      const index = Number(input.closest("[data-position]").dataset.position);
+      const value = input.value.trim();
+      if (value && !isColorRef(value)) { onStatus("Use a hex color such as #7B241C."); refresh(); return; }
+      commit({ colors: colorsWith(index, value) }, "Changed a chart color. Undo restores it.");
+    }],
+    [fields.colorsReset, "click", () => commit({ colors: null }, "Returned the chart colors to the deck palette. Undo restores them.")],
     ...["series", "categories"].map((part) => [fields.highlight[part], "change", () => {
       const names = checkedNames(part);
       commit({ highlight: { [part]: names } }, names.length ? `Highlighted ${names.join(", ")}. Undo restores the colors.` : `Cleared the ${part} highlight. Undo restores it.`);

package/dist/chart-options.d.ts

@@ -6,6 +6,10 @@ export type ChartLabelPosition = "center" | "inside-end" | "inside-base" | "outs
 
 export declare const CHART_LEGEND_POSITIONS: readonly ["default", "none", "top", "bottom", "left", "right"];
 export declare const CHART_LABEL_CONTENT: readonly ["category", "value", "percent"];
+/** The most colors `chart.colors` takes. */
+export declare const CHART_COLORS_MAX: 24;
+/** The scheme slots a chart color is offered from, in palette order. */
+export declare const CHART_COLOR_SLOTS: readonly ["accent1", "accent2", "accent3", "accent4", "accent5", "accent6"];
 
 /** What a chart type can show (core's `chartOptionSupport`). */
 export interface ChartOptionFields {
@@ -26,6 +30,14 @@ export interface ChartOptionFields {
 }
 /** The names a highlight can take on a chart, from its resolved data (empty when the data does not resolve). */
 export interface ChartHighlightChoices { series: string[]; categories: string[] }
+/** What the positions of `chart.colors` mean on a chart (RR-96): its plotted series, its slices or rows, or the colors a histogram, pareto or waterfall draws with. */
+export interface ChartColorPositions {
+  by: "series" | "categories" | "colors";
+  /** One name per position (at most 24), in the order `chart.colors` is matched. */
+  labels: string[];
+  /** The scheme slots to offer as swatches. */
+  slots: readonly string[];
+}
 /** A plotted series of a combo chart: drawn as columns ("bar") or as a line, on the primary or secondary value axis (FA-15). */
 export interface ChartComboSeriesState {
   name: string;
@@ -43,6 +55,8 @@ export interface ChartOptionState {
   dataLabels: { on: boolean; explicit: boolean; content: ChartLabelContent[]; position: ChartLabelPosition | "auto"; separator: string };
   /** The series and categories `chart.highlight` names (empty lists when it is absent). */
   highlight: { series: string[]; categories: string[] };
+  /** `chart.colors` as written, a ColorRef per position (empty when absent: the deck palette applies). */
+  colors: string[];
 }
 export interface ChartOptionChange {
   /** The text alternative: what the data shows. Trimmed; an empty string or null removes it. */
@@ -58,6 +72,11 @@ export interface ChartOptionChange {
   dataLabels?: boolean | null | { content?: ChartLabelContent[]; position?: ChartLabelPosition | "auto"; separator?: string };
   /** `null` removes the highlight; a list replaces that part (an empty list removes it) and the other part is kept. */
   highlight?: null | { series?: string[]; categories?: string[] };
+  /**
+   * RR-96: `chart.colors`, the colors by position. `null` removes it; a list replaces it: an entry is a hex color, a scheme color (`accent3`, which keeps following the
+   * deck) or `var:<id>`, and `null` or `""` leaves that position to the deck palette (a gap before a chosen color is written as the palette color itself). At most 24.
+   */
+  colors?: null | Array<string | null>;
 }
 export interface PreparedChartOptions {
   action: "chart-options";
@@ -70,6 +89,6 @@ export interface PreparedChartOptions {
 /** The chart path a selection path points at, or undefined. */
 export declare function parseChartPath(path: string): string | undefined;
 /** `combo` is present on a combo chart: its plotted series in data order. Pass the `document` for a dataset-backed chart. */
-export declare function readChartOptions(chart: unknown, presentation?: unknown): { target: unknown; fields: ChartOptionFields; choices: ChartHighlightChoices; state: ChartOptionState; combo?: { series: ChartComboSeriesState[] } };
+export declare function readChartOptions(chart: unknown, presentation?: unknown): { target: unknown; fields: ChartOptionFields; choices: ChartHighlightChoices; colors: ChartColorPositions; state: ChartOptionState; combo?: { series: ChartComboSeriesState[] } };
 export declare function prepareChartOptions(presentation: unknown, chartPath: string, change: ChartOptionChange): PreparedChartOptions;
 export declare function setChartOptions(editor: EditorSession, chartPath: string, change: ChartOptionChange, meta?: Record<string, unknown>): EditorChange & { action: "chart-options"; chartPath: string; changed: boolean };

package/dist/chart-options.js

@@ -7,15 +7,21 @@
 // choice, and only a pie or doughnut can show percent. A highlight names plotted series and category labels (the
 // choices come from the chart's resolved data, so a dataset chart offers its dataset's columns and rows); a pie
 // highlights slices (categories), an area only series. Nothing here invents text. A combo chart (FA-15) also offers which series are lines (`line`), which lines use the secondary value
-// axis (`secondaryAxis`) and that axis's title.
-import { resolveChartData } from "@openpresentation/opf";
-import { chartOptionSupport, chartOptionTarget } from "@openpresentation/opf/composition";
+// axis (`secondaryAxis`) and that axis's title. (RR-96) `colors` edits `chart.colors`, the series (or slice) colors by position, each a hex
+// color, a scheme slot such as `accent3` (it keeps following the deck) or a `var:` color variable.
+import { resolveChartData, resolveSlideContext } from "@openpresentation/opf";
+import { chartOptionSupport, chartOptionTarget, chartSeriesPalette } from "@openpresentation/opf/composition";
 import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { checkedDocument, fail, same } from "./edit-helpers.js";
 import { checkFormat } from "./checks.js";
+import { isColorRef } from "./background-options.js";
 
 export const CHART_LEGEND_POSITIONS = Object.freeze(["default", "none", "top", "bottom", "left", "right"]);
 export const CHART_LABEL_CONTENT = Object.freeze(["category", "value", "percent"]);
+/** The most colors `chart.colors` takes (the schema's maxItems). */
+export const CHART_COLORS_MAX = 24;
+/** The scheme slots a chart color is offered from, in palette order: the deck's accents. */
+export const CHART_COLOR_SLOTS = Object.freeze(["accent1", "accent2", "accent3", "accent4", "accent5", "accent6"]);
 
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const CONTENT_ORDER = CHART_LABEL_CONTENT;
@@ -52,6 +58,29 @@ function highlightChoices(chart, document) {
   return { series: resolved.columns.slice(first), categories: [...new Set(resolved.rows.map((row) => label(row[0])).filter(Boolean))] };
 }
 
+// RR-96: what `chart.colors` positions mean on a chart. A series chart colors its plotted series, a pie, doughnut, treemap or funnel
+// its slices or rows (one per data row, to the schema's 24), and a histogram, pareto or waterfall the colors it draws with.
+const SERIES_KINDS = new Set(["bar", "line", "area", "scatter", "radar", "combo"]);
+const ROW_KINDS = new Set(["pie", "doughnut", "treemap", "funnel"]);
+function colorPositions(chart, target, document, combo) {
+  const kind = target?.kind;
+  const label = (cell) => (cell === null || cell === undefined ? "" : String(cell));
+  let by = "colors";
+  let labels = [];
+  if (SERIES_KINDS.has(kind)) {
+    by = "series";
+    labels = combo ? combo.map((entry) => entry.name) : highlightChoices(chart, document).series;
+  } else if (ROW_KINDS.has(kind)) {
+    by = "categories";
+    try {
+      const resolved = resolveChartData(chart, document);
+      if (resolved?.ok) labels = resolved.rows.map((row) => label(row[0]));
+    } catch { /* unresolved data: no positions to name */ }
+  }
+  if (!labels.length) { by = "colors"; labels = CHART_COLOR_SLOTS.map((_, index) => `Color ${index + 1}`); }
+  return { by, labels: labels.slice(0, CHART_COLORS_MAX).map((text, index) => text || `Color ${index + 1}`), slots: CHART_COLOR_SLOTS };
+}
+
 const names = (value) => (Array.isArray(value) ? [...new Set(value.filter((entry) => typeof entry === "string"))] : []);
 
 /**
@@ -85,7 +114,10 @@ export function readChartOptions(chart, presentation) {
     // FA-15: a combo chart's plotted series, each drawn as columns ("bar") or as a line, on the primary or secondary value axis.
     ...(combo ? { combo: { series: combo } } : {}),
     choices: highlightChoices(chart, presentation),
+    colors: colorPositions(chart, target, presentation, combo),
     state: {
+      // RR-96: `chart.colors` as written (a ColorRef per position); [] when absent, so the deck palette applies.
+      colors: Array.isArray(chart?.colors) ? chart.colors.filter((entry) => typeof entry === "string") : [],
       // FA-09: the text alternative. `decorative` is the empty alt, a reviewed choice, not a missing one.
       alt: typeof chart?.alt === "string" ? chart.alt : "",
       decorative: chart?.alt === "",
@@ -142,7 +174,7 @@ function comboFields(chart, change, document) {
 }
 
 // The desired value of each field (undefined removes it), from the chart and a patch.
-function desired(chart, change, support, choices, current, document) {
+function desired(chart, change, support, choices, current, document, parts) {
   const out = {};
   const combo = support.axisTitles.secondary === true;
   if (change.line !== undefined || change.secondaryAxis !== undefined) {
@@ -201,12 +233,46 @@ function desired(chart, change, support, choices, current, document) {
       out.highlight = Object.keys(next).length ? next : undefined;
     }
   }
+  if (change.colors !== undefined) out.colors = chartColors(change.colors, document, parts);
   return out;
 }
 
+// RR-96: the `chart.colors` list to write (undefined removes the field). A position left to the deck palette (null or "") is only
+// expressible as the palette color itself, so a gap before a chosen color is filled with the accent slot (the palette's own color for
+// the first six; later ones are its tints, written as that hex), and trailing gaps are dropped, which keeps the palette.
+function chartColors(wanted, document, parts) {
+  if (wanted === null) return undefined;
+  if (!Array.isArray(wanted)) throw fail("invalid-chart-option", "colors is a list of colors by position, or null to remove it.", { colors: wanted });
+  if (wanted.length > CHART_COLORS_MAX) throw fail("invalid-chart-option", `A chart takes at most ${CHART_COLORS_MAX} colors.`, { count: wanted.length });
+  const entries = wanted.map((entry, index) => {
+    if (entry === null || entry === undefined || entry === "") return undefined;
+    if (!isColorRef(entry)) throw fail("invalid-chart-option", `Color ${index + 1} must be a hex color such as #7B241C, a scheme color such as accent3, or var:<id>.`, { index, color: entry });
+    return /^#/.test(entry) ? entry.toUpperCase() : entry;
+  });
+  while (entries.length && entries[entries.length - 1] === undefined) entries.pop();
+  if (!entries.length) return undefined;
+  let palette;
+  return entries.map((entry, index) => {
+    if (entry !== undefined) return entry;
+    if (index < CHART_COLOR_SLOTS.length) return CHART_COLOR_SLOTS[index];
+    palette ??= paletteOf(document, parts);
+    return palette[index];
+  });
+}
+
+// The deck palette of the slide a chart is on (`chartSeriesPalette` of its resolved color scheme), for positions past the six accents.
+function paletteOf(document, parts) {
+  let scheme = {};
+  try {
+    const slide = parts[0] === "slides" ? Number(parts[1]) : 0;
+    scheme = resolveSlideContext(document, Number.isInteger(slide) ? slide : 0, {}).resolved?.colorScheme ?? {};
+  } catch { /* the engine default palette */ }
+  return chartSeriesPalette(scheme);
+}
+
 /**
  * Prepare one validated patch for a change to the chart's options. `change` is
- * `{ alt?, decorative?, axisTitles?: { category?, value?, secondary? }, legend?, dataLabels?, highlight?, line?, secondaryAxis? }`: `alt` is the text alternative (trimmed; empty or `null`
+ * `{ alt?, decorative?, axisTitles?: { category?, value?, secondary? }, legend?, dataLabels?, highlight?, colors?, line?, secondaryAxis? }`: `alt` is the text alternative (trimmed; empty or `null`
  * removes it), `decorative: true` writes the empty alt (and wins over `alt`), `decorative: false` removes an empty alt; `axisTitles` entries are strings (empty removes a title),
  * `legend` is `"default"` (remove the field), `"none"`, `"top"`, `"bottom"`, `"left"` or `"right"`, and `dataLabels` is
  * `true`, `false` (or `null`, which removes the field), or `{ content?, position?, separator? }` merged over the current labels, and
@@ -214,13 +280,15 @@ function desired(chart, change, support, choices, current, document) {
  * chart does not have is refused) and the other part is kept. On a combo chart (FA-15), `line` lists the series drawn as lines and
  * `secondaryAxis` the lines on the secondary value axis, by name; at least one series stays columns and at least one is a line, `line`
  * is written only when it differs from the default (the last series), and the secondary axis title goes when no series uses that axis.
+ * `colors` (RR-96) is `null` (remove the field) or a list of colors by position (a hex color, a scheme color such as `accent3` that keeps following the deck, or
+ * `var:<id>`; `null` or `""` leaves that position to the deck palette), at most 24; it replaces the whole list, and trailing positions left to the palette are dropped.
  * Fields the chart type cannot show are never written. The document is not modified.
  */
 export function prepareChartOptions(presentation, chartPath, change) {
   const before = checkFormat(presentation);
   const { parts, chart } = chartAt(presentation, chartPath);
   const read = readChartOptions(chart, presentation);
-  const wanted = desired(chart, change, read.fields, read.choices, read.state, presentation);
+  const wanted = desired(chart, change, read.fields, read.choices, read.state, presentation, parts);
   const patches = [];
   for (const [key, value] of Object.entries(wanted)) {
     const path = opfPathToJsonPointer([...parts, key]);

package/dist/color-slots.d.ts

@@ -0,0 +1,12 @@
+import type { Catalog } from "@openpresentation/opf";
+
+/** The four background slots a variant maps to the background: `light1`, `light2`, `dark1`, `dark2`. */
+export declare const VARIANT_BACKGROUND_SLOTS: readonly ["light1", "light2", "dark1", "dark2"];
+/** The six accent slots, in the scheme's own order. */
+export declare const ACCENT_SLOTS: readonly ["accent1", "accent2", "accent3", "accent4", "accent5", "accent6"];
+export type VariantBackgroundSlot = (typeof VARIANT_BACKGROUND_SLOTS)[number];
+export type AccentSlot = (typeof ACCENT_SLOTS)[number];
+/** Slot name to `#RRGGBB`; a slot the resolved scheme leaves out is absent. */
+export type SchemeSlots = Partial<Record<VariantBackgroundSlot | AccentSlot, string>>;
+/** The deck's resolved color scheme slots at `slideIndex` (default 0), for swatches. Never throws: an unresolvable document gives `{}`. */
+export declare function readSchemeSlots(presentation: unknown, options?: { slideIndex?: number; catalogs?: readonly Catalog[] }): SchemeSlots;

package/dist/color-slots.js

@@ -0,0 +1,31 @@
+// RR-96: the color scheme slots a picker offers as swatches, read from the scheme the document resolves for a slide. A slot is
+// shown as its own color, so a swatch is what the deck draws, and a choice writes the slot name (`accent3`, `dark1`), never the hex,
+// so it keeps following the deck if its scheme changes. Read only: no edit goes through here.
+import { resolveSlideContext } from "@openpresentation/opf";
+
+/** The four background slots a variant maps to the background, in the order PowerPoint's Variants gallery shows them. */
+export const VARIANT_BACKGROUND_SLOTS = Object.freeze(["light1", "light2", "dark1", "dark2"]);
+/** The six accent slots, in the scheme's own order. */
+export const ACCENT_SLOTS = Object.freeze(["accent1", "accent2", "accent3", "accent4", "accent5", "accent6"]);
+
+const HEX = /^#[0-9a-f]{6}$/i;
+
+/**
+ * The hex color of each of `light1`, `light2`, `dark1`, `dark2` and `accent1` to `accent6` in the deck's resolved color scheme at
+ * `slideIndex` (default: the first slide; a slide has the deck's scheme unless it sets its own). A slot the scheme leaves out is
+ * absent. Never throws: an unresolvable document gives `{}`.
+ */
+export function readSchemeSlots(presentation, { slideIndex = 0, catalogs } = {}) {
+  let scheme;
+  try {
+    const slides = Array.isArray(presentation?.slides) ? presentation.slides.length : 0;
+    scheme = resolveSlideContext(presentation, Math.min(Math.max(slideIndex, 0), Math.max(slides - 1, 0)), catalogs ? { catalogs } : {}).resolved?.colorScheme;
+  } catch {
+    return {};
+  }
+  const slots = {};
+  for (const name of [...VARIANT_BACKGROUND_SLOTS, ...ACCENT_SLOTS]) {
+    if (typeof scheme?.[name] === "string" && HEX.test(scheme[name])) slots[name] = scheme[name];
+  }
+  return slots;
+}

package/dist/design-controls.js

@@ -41,6 +41,8 @@ import {
   setHeaderFooterZone,
   setOrganizationLogo,
 } from "./design-options.js";
+import { ACCENT_SLOTS } from "./color-slots.js";
+import { readDesignVariant, setDesignVariant, variantSwatches } from "./design-variants.js";
 import { createContentControls } from "./content-controls.js";
 import { IMAGE_EDGES, IMAGE_FITS, IMAGE_SHAPES, readImageTreatments, setImageTreatment } from "./image-options.js";
 import { applyCatalogUpdate, catalogRecordAt, checkCatalogUpdates, mergeCatalogs, moveToCustom, referenceFindings } from "./catalogs.js";
@@ -48,10 +50,11 @@ import { describeTableCell, mergeTableCells, parseTableCellPath, readTableAlt, r
 import { OPFEditorError } from "./index.js";
 
 /** The sections a panel can show. `selection` and `table` follow the current selection; the rest follow the deck or the current slide. */
-export const DESIGN_CONTROL_SECTIONS = Object.freeze(["look", "background", "header-footer", "brand", "layout-options", "info", "selection", "image", "table", "slide-content", "catalog"]);
+export const DESIGN_CONTROL_SECTIONS = Object.freeze(["look", "variant", "background", "header-footer", "brand", "layout-options", "info", "selection", "image", "table", "slide-content", "catalog"]);
 
 const SECTION_TITLES = {
   look: "Look and language",
+  variant: "Color variant",
   background: "Background",
   image: "Selected image",
   catalog: "Catalog records",
@@ -431,7 +434,7 @@ export function createDesignControls(container, options = {}) {
   const scopeIndex = () => (state.scope === "slide" ? getSlide() : undefined);
   const scoped = (extra = {}) => (state.scope === "slide" ? { slideIndex: getSlide(), ...extra } : extra);
   const sourceNote = (scope, inherited) => (state.scope === "slide" ? (scope === "slide" ? "set on this slide" : inherited ? "from the presentation" : "default") : "");
-  const scopeNeeded = sections.some((name) => ["look", "background", "header-footer", "brand", "layout-options"].includes(name));
+  const scopeNeeded = sections.some((name) => ["look", "variant", "background", "header-footer", "brand", "layout-options"].includes(name));
   let scopeField;
   if (scopeNeeded) {
     scopeField = selectField("scope", "Applies to", {
@@ -502,6 +505,75 @@ export function createDesignControls(container, options = {}) {
     });
   }
 
+  // --- color variant (RR-96) ----------------------------------------------------------------------
+
+  // PowerPoint's Variants gallery: four swatches built from the deck's own scheme slots (light1, light2, dark1, dark2) and, below
+  // them, the order of the accents. A choice writes the slot name (`design.variant`), so it keeps following the color scheme, and the
+  // preview comes from core's roles. Needs core 0.23 (`design.variant`).
+  if (built.variant) {
+    const { body } = built.variant;
+    const view = () => ({ ...scoped(), catalogs: catalogOptions().catalogs });
+    const SLOT_LABELS = { light1: "Light 1", light2: "Light 2", dark1: "Dark 1", dark2: "Dark 2" };
+    const gallery = h("div", { class: "opf-dc-variants", role: "radiogroup", "aria-label": "Color variant" });
+    const sameAsDeck = button("Same as presentation", () => run(() => setDesignVariant(editor, null, view()), "This slide follows the presentation's color variant."), { quiet: true });
+    const accentRows = ACCENT_SLOTS.map((_, index) => {
+      const field = selectField(`variant-accent-${index + 1}`, `Accent ${index + 1}`, {
+        onChange: (value) => {
+          const order = readDesignVariant(editor.presentation, view()).accents;
+          const from = order.indexOf(value);
+          const next = [...order];
+          // A permutation: the slot that was drawn as this accent takes the place of the one chosen.
+          [next[index], next[from]] = [order[from], order[index]];
+          run(() => setDesignVariant(editor, { accents: next }, view()), "Accent order changed.");
+        },
+      });
+      field.setOptions(ACCENT_SLOTS.map((slot, k) => ({ value: slot, label: `Accent ${k + 1} color (${slot})` })));
+      return field;
+    });
+    const resetAccents = button("Reset accent order", () => run(() => {
+      const current = readDesignVariant(editor.presentation, view());
+      return setDesignVariant(editor, { background: current.background, accents: ACCENT_SLOTS }, view());
+    }, "Accents are back in the color scheme's own order."), { quiet: true });
+    const accentGroup = h("fieldset", { class: "opf-dc-fieldset", "data-variant-accents": "" }, h("legend", {}, "Accent order"), ...accentRows.map((row) => row.wrap), resetAccents);
+    body.append(gallery, sameAsDeck, accentGroup);
+    const pick = (slot) => {
+      const current = readDesignVariant(editor.presentation, view());
+      // Keep a reordered accent order when only the background changes.
+      const accents = current.own?.accents;
+      return run(() => setDesignVariant(editor, accents ? { background: slot, accents } : slot, view()), (change) => {
+        const hidden = change.shadowed?.length ? ` ${change.shadowed.length === 1 ? "One slide keeps its own" : `${change.shadowed.length} slides keep their own`} background or variant.` : "";
+        return `Color variant set to ${SLOT_LABELS[slot]}.${hidden}`;
+      });
+    };
+    syncs.push(() => {
+      const current = readDesignVariant(editor.presentation, view());
+      const swatches = variantSwatches(editor.presentation, view());
+      const signature = JSON.stringify([swatches, state.scope]);
+      if (gallery.dataset.signature !== signature) {
+        gallery.dataset.signature = signature;
+        gallery.replaceChildren(...swatches.map((entry) => {
+          const chip = (color, className) => h("span", { class: className, style: color ? `background:${color}` : undefined, "aria-hidden": "true" });
+          return h("button", {
+            type: "button",
+            class: "opf-dc-variant",
+            role: "radio",
+            "aria-checked": String(entry.selected),
+            "data-variant": entry.slot,
+            "aria-label": `${SLOT_LABELS[entry.slot]}: ${entry.slot} background${entry.dark ? " (dark)" : ""}`,
+            title: `${SLOT_LABELS[entry.slot]}: ${entry.slot} background`,
+            style: entry.background ? `background:${entry.background};color:${entry.text ?? "inherit"}` : undefined,
+            onclick: () => pick(entry.slot),
+          }, h("span", { class: "opf-dc-variant-text", "aria-hidden": "true" }, "Aa"), h("span", { class: "opf-dc-variant-chips", "aria-hidden": "true" }, chip(entry.surface, "opf-dc-variant-chip"), ...entry.accents.map((color) => chip(color, "opf-dc-variant-chip"))));
+        }));
+      }
+      const note = current.scope === "default" ? "default" : state.scope === "slide" ? (current.inherited ? "from the presentation" : "set on this slide") : "";
+      gallery.setAttribute("aria-description", note);
+      sameAsDeck.hidden = !(state.scope === "slide" && current.own !== undefined);
+      accentRows.forEach((row, index) => row.set(current.accents[index]));
+      resetAccents.hidden = current.own?.accents === undefined;
+    });
+  }
+
   // --- background ---------------------------------------------------------------------------------
 
   if (built.background) {

package/dist/design-variants.d.ts

@@ -0,0 +1,90 @@
+import type { Catalog } from "@openpresentation/opf";
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+import type { AccentSlot, VariantBackgroundSlot } from "./color-slots.js";
+
+export { ACCENT_SLOTS, VARIANT_BACKGROUND_SLOTS } from "./color-slots.js";
+export type { AccentSlot, VariantBackgroundSlot } from "./color-slots.js";
+
+/** A variant of the deck's one color scheme: the slot that is the background and, optionally, the order of the accents (core's `ColorVariant`). */
+export interface DesignVariant {
+  background: VariantBackgroundSlot;
+  /** A permutation of `accent1` to `accent6`: entry i is the slot drawn as accent i + 1 (primary, secondary, accent and the chart series colors follow it). */
+  accents?: AccentSlot[];
+}
+/** What `design.variant` takes: the background slot (the shorthand) or the object. */
+export type DesignVariantInput = VariantBackgroundSlot | DesignVariant;
+/** What the editor writes: the slot as a string, or the object only for a reordered accent order. */
+export type StoredDesignVariant = VariantBackgroundSlot | { background: VariantBackgroundSlot; accents: AccentSlot[] };
+
+/** For each background slot, the slots the variant maps to bg1, tx1, bg2 and tx2 (PowerPoint's color map), and whether it is dark. */
+export declare const VARIANT_MAPS: Readonly<Record<VariantBackgroundSlot, { readonly bg1: string; readonly tx1: string; readonly bg2: string; readonly tx2: string; readonly dark: boolean }>>;
+
+/** Validate a variant and return what to store (see {@link StoredDesignVariant}). Throws `invalid-variant` with a sentence a person can act on. */
+export declare function normalizeVariant(value: DesignVariantInput): StoredDesignVariant;
+
+export interface DesignVariantOptions {
+  /** One slide instead of the deck. */
+  slideIndex?: number;
+  /** Deck scope: also remove the slides' own variants that would hide the change. */
+  clearSlideOverrides?: boolean;
+  /** Catalogs the document's references resolve against (a session form uses the session's). */
+  catalogs?: readonly Catalog[];
+  /** Session change metadata (session form only). */
+  meta?: Record<string, unknown>;
+}
+export interface DesignVariantState {
+  /** What this scope's own `design.variant` says, normalized to the object; undefined when it sets none. */
+  own?: DesignVariant;
+  /** The slide's effective variant background, by core's resolution (a variant, a theme-slot background or a picture's tone, the deck's, the theme's, else light1). */
+  background: VariantBackgroundSlot;
+  /** The effective accent order (the six slots; the scheme's own order unless a variant reorders it). */
+  accents: AccentSlot[];
+  /** Where `own` comes from: "slide" (the slide sets it), "deck", or "default" (nothing sets one). */
+  scope: "slide" | "deck" | "default";
+  /** True when a slide takes its variant from the deck (it sets none itself). */
+  inherited: boolean;
+}
+export declare function readDesignVariant(presentation: unknown, options?: Pick<DesignVariantOptions, "slideIndex" | "catalogs">): DesignVariantState;
+
+/** One of the four variants as a swatch built from the deck's own scheme slots. */
+export interface VariantSwatch {
+  slot: VariantBackgroundSlot;
+  dark: boolean;
+  /** Hex colors of the slots the variant maps to its background, text and alternate surface; undefined when the scheme leaves a slot out. */
+  background?: string;
+  text?: string;
+  surface?: string;
+  /** The first three accents in the effective accent order. */
+  accents: Array<string | undefined>;
+  /** Whether it is the effective variant of the slide. */
+  selected: boolean;
+}
+/** The four variants (`light1`, `light2`, `dark1`, `dark2`) as swatches from the deck's scheme at a scope, like PowerPoint's Variants gallery. */
+export declare function variantSwatches(presentation: unknown, options?: Pick<DesignVariantOptions, "slideIndex" | "catalogs">): VariantSwatch[];
+
+export interface PreparedDesignVariant {
+  option: "variant";
+  scope: "deck" | "slide";
+  slideIndex?: number;
+  presentation: unknown;
+  patches: JsonPatchOperation[];
+  changed: boolean;
+  /** Slides whose own variant, or theme-slot or toned background, still hides a deck-level change. */
+  shadowed: number[];
+}
+/**
+ * The patch that sets the variant (a slot, `{ background, accents? }`, or `null` to remove it; `{ accents }` alone keeps the background)
+ * at the deck, or on one slide with `slideIndex`. The document is not modified.
+ */
+export declare function prepareDesignVariant(presentation: unknown, value: DesignVariantInput | { accents: AccentSlot[] } | null, options?: Omit<DesignVariantOptions, "meta">): PreparedDesignVariant;
+export interface DesignVariantChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
+  patches: JsonPatchOperation[];
+  option: "variant";
+  scope: "deck" | "slide";
+  slideIndex?: number;
+  changed: boolean;
+  shadowed: number[];
+}
+/** Set the variant as one undoable transaction. */
+export declare function setDesignVariant(editor: EditorSession, value: DesignVariantInput | { accents: AccentSlot[] } | null, options?: DesignVariantOptions): DesignVariantChange;

package/dist/design-variants.js

@@ -0,0 +1,180 @@
+// Color variants (RR-96): `design.variant`, at the deck or on one slide. A variant is a mapping over the deck's one twelve-slot color
+// scheme, as PowerPoint's color map is, never a second scheme: which slot is the background (and so the text and the alternate
+// surface) and, optionally, the order of the accents. `light1`, `light2`, `dark1` and `dark2` are the four backgrounds PowerPoint's
+// Variants gallery offers. A choice writes the slot name, so it keeps following the deck's color scheme. Every function has a
+// `prepare…` form that returns the patch without touching a session and a session form that commits it as one undoable edit, like
+// every other design option; the preview and the PowerPoint export read the variant from core, nothing is drawn here.
+import { resolveSlideContext } from "@openpresentation/opf";
+import { normalizeColorVariant } from "@openpresentation/opf/composition";
+import { getValueAtPath, opfPathToJsonPointer } from "./index.js";
+import { checkedDocument, designPatches, fail } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
+import { ACCENT_SLOTS, VARIANT_BACKGROUND_SLOTS, readSchemeSlots } from "./color-slots.js";
+
+export { ACCENT_SLOTS, VARIANT_BACKGROUND_SLOTS };
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const sameOrder = (accents) => accents.every((slot, index) => slot === ACCENT_SLOTS[index]);
+
+/** For each background slot: the slots the variant maps to the text, the alternate surface and the secondary text (the schema's ColorVariant table). */
+export const VARIANT_MAPS = Object.freeze({
+  light1: Object.freeze({ bg1: "light1", tx1: "dark1", bg2: "light2", tx2: "dark2", dark: false }),
+  light2: Object.freeze({ bg1: "light2", tx1: "dark1", bg2: "light2", tx2: "dark2", dark: false }),
+  dark1: Object.freeze({ bg1: "dark1", tx1: "light1", bg2: "dark2", tx2: "light2", dark: true }),
+  dark2: Object.freeze({ bg1: "dark2", tx1: "light1", bg2: "dark2", tx2: "light2", dark: true }),
+});
+
+/**
+ * Validate a variant and return what to store: the background slot as a string, or `{ background, accents }` only when the accents are
+ * reordered. Accepts a slot, `{ background, accents? }`; a full accent list in the scheme's own order is dropped (it says nothing).
+ */
+export function normalizeVariant(value) {
+  const spec = typeof value === "string" ? { background: value } : value;
+  if (!isObject(spec)) throw fail("invalid-variant", `A variant is a background slot (${VARIANT_BACKGROUND_SLOTS.join(", ")}) or { background, accents }.`, { value });
+  const extra = Object.keys(spec).filter((key) => key !== "background" && key !== "accents");
+  if (extra.length) throw fail("invalid-variant", `A variant has a background and optionally accents, not ${extra.join(", ")}.`, { fields: extra });
+  if (!VARIANT_BACKGROUND_SLOTS.includes(spec.background)) throw fail("invalid-variant", `The variant background is one of ${VARIANT_BACKGROUND_SLOTS.join(", ")}.`, { background: spec.background });
+  if (spec.accents === undefined || spec.accents === null) return spec.background;
+  const accents = spec.accents;
+  if (!Array.isArray(accents) || accents.length !== ACCENT_SLOTS.length || new Set(accents).size !== ACCENT_SLOTS.length || accents.some((slot) => !ACCENT_SLOTS.includes(slot)))
+    throw fail("invalid-variant", "The accent order uses each of accent1 to accent6 once.", { accents });
+  return sameOrder(accents) ? spec.background : { background: spec.background, accents: [...accents] };
+}
+
+// Core's own normalization of a stored variant (the string shorthand or the object) to the object it resolves with.
+const asObject = (stored) => normalizeColorVariant(stored);
+
+function scopeOf(presentation, options) {
+  const index = options.slideIndex;
+  if (index === undefined) return { scope: "deck", base: [] };
+  if (!Number.isInteger(index) || !presentation.slides?.[index]) throw fail("slide-index-out-of-range", "Choose an existing slide for this option.", { slideIndex: index });
+  return { scope: "slide", base: ["slides", String(index)], slideIndex: index };
+}
+
+const ownVariant = (presentation, base) => {
+  const design = getValueAtPath(presentation, base.length ? [...base, "design"] : ["design"]);
+  return isObject(design) && design.variant !== undefined ? design.variant : undefined;
+};
+
+/**
+ * The variant at a scope, for a panel. `own` is what that scope's `design.variant` says (`{ background, accents? }`, undefined when
+ * it sets none), `background` and `accents` the slide's effective variant (core's resolution: a slide's variant, a theme-slot
+ * background, a picture or gradient `tone`, the deck's variant, the theme's, then the default; `accents` always has the six slots in
+ * order), `scope` where `own` comes from ("slide", "deck" or "default") and `inherited` whether a slide takes it from the deck.
+ */
+export function readDesignVariant(presentation, options = {}) {
+  const { base } = scopeOf(presentation, options);
+  const own = ownVariant(presentation, base);
+  const deck = ownVariant(presentation, []);
+  let effective;
+  try {
+    const slide = options.slideIndex ?? 0;
+    effective = resolveSlideContext(presentation, Math.min(Math.max(slide, 0), Math.max((presentation.slides?.length ?? 1) - 1, 0)), options.catalogs ? { catalogs: options.catalogs } : {}).resolved?.roles?.variant;
+  } catch { /* older core or an unresolvable document: fall back to what the document says */ }
+  const fallback = asObject(own ?? deck) ?? { background: "light1" };
+  const shown = isObject(effective) && typeof effective.background === "string" ? effective : fallback;
+  const slideScope = options.slideIndex !== undefined;
+  return {
+    own: own === undefined ? undefined : asObject(own),
+    background: shown.background,
+    accents: Array.isArray(shown.accents) ? [...shown.accents] : [...ACCENT_SLOTS],
+    scope: own !== undefined ? (slideScope ? "slide" : "deck") : slideScope && deck !== undefined ? "deck" : "default",
+    inherited: slideScope && own === undefined,
+  };
+}
+
+/**
+ * The four variants as swatches built from the deck's own scheme slots at a scope: for each of `light1`, `light2`, `dark1` and `dark2`
+ * the colors of its background, text, alternate surface and first three accents (in the effective accent order), and whether it is
+ * the effective one. A color the scheme leaves out is undefined.
+ */
+export function variantSwatches(presentation, options = {}) {
+  const slots = readSchemeSlots(presentation, { slideIndex: options.slideIndex ?? 0, catalogs: options.catalogs });
+  const current = readDesignVariant(presentation, options);
+  return VARIANT_BACKGROUND_SLOTS.map((slot) => {
+    const map = VARIANT_MAPS[slot];
+    return {
+      slot,
+      dark: map.dark,
+      background: slots[map.bg1],
+      text: slots[map.tx1],
+      surface: slots[map.bg2],
+      accents: current.accents.slice(0, 3).map((accent) => slots[accent]),
+      selected: current.background === slot,
+    };
+  });
+}
+
+/** Slides whose own design hides a deck-level variant: their own `variant`, or a theme-slot background that decides the slide's variant (or a tone). */
+function shadowedSlides(presentation) {
+  const hidden = [];
+  (presentation.slides ?? []).forEach((slide, index) => {
+    const design = slide?.design;
+    if (!isObject(design)) return;
+    const background = design.background;
+    const decides = design.variant !== undefined || background === "light1" || background === "light2" || background === "dark1" || background === "dark2" || (isObject(background) && (background.type === "theme" || background.tone !== undefined));
+    if (decides) hidden.push(index);
+  });
+  return hidden;
+}
+
+/**
+ * Compute the patch that sets the variant, at the deck or (with `slideIndex`) on one slide. `value` is a background slot, `{ background,
+ * accents? }`, or `null` to remove the variant at that scope (a slide then follows the deck). `{ accents }` alone keeps the scope's
+ * (or else the effective) background. Deck scope: `clearSlideOverrides` also removes the slides' own variants that would hide the
+ * change; `shadowed` lists the slides whose own variant or background would still hide it.
+ */
+export function prepareDesignVariant(presentation, value, options = {}) {
+  if (!isObject(presentation)) throw fail("invalid-input", "Design variants need an OPF document object.");
+  if (value === undefined) throw fail("invalid-variant", "Pass a variant, or null to remove it.");
+  const before = checkFormat(presentation);
+  const { scope, base, slideIndex } = scopeOf(presentation, options);
+  let stored = null;
+  if (value !== null) {
+    let spec = value;
+    if (isObject(value) && value.background === undefined) {
+      const current = readDesignVariant(presentation, { slideIndex, catalogs: options.catalogs });
+      spec = { background: current.background, ...value };
+    }
+    stored = normalizeVariant(spec);
+  }
+  const patches = designPatches(presentation, base, { variant: stored });
+  let shadowed = [];
+  if (scope === "deck") {
+    shadowed = shadowedSlides(presentation);
+    if (options.clearSlideOverrides) {
+      for (const index of shadowed) {
+        if (presentation.slides[index].design?.variant !== undefined) patches.push({ op: "remove", path: opfPathToJsonPointer(["slides", String(index), "design", "variant"]) });
+      }
+      shadowed = shadowedSlides(applyRemovals(presentation, patches));
+    }
+  }
+  const next = checkedDocument(presentation, patches, before);
+  return { option: "variant", scope, ...(slideIndex !== undefined ? { slideIndex } : {}), presentation: next, patches, changed: patches.length > 0, shadowed };
+}
+
+function applyRemovals(presentation, patches) {
+  const copy = structuredClone(presentation);
+  for (const patch of patches) {
+    if (patch.op !== "remove") continue;
+    const match = /^\/slides\/(\d+)\/design\/variant$/.exec(patch.path);
+    if (match) delete copy.slides[Number(match[1])].design.variant;
+  }
+  return copy;
+}
+
+function checkEditor(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function")
+    throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/** Set the variant as one undoable transaction. See {@link prepareDesignVariant}. */
+export function setDesignVariant(editor, value, options = {}) {
+  checkEditor(editor);
+  const { meta = {}, ...rest } = options;
+  const prepared = prepareDesignVariant(editor.presentation, value, { catalogs: editor.catalogs, ...rest });
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(patches, { ...meta, source: meta.source ?? "design-option", option: "variant", scope: prepared.scope });
+  return { ...change, ...summary };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-editor",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
   "license": "MIT",
   "type": "module",
@@ -114,6 +114,14 @@
       "types": "./dist/assets.d.ts",
       "default": "./dist/assets.js"
     },
+    "./design-variants": {
+      "types": "./dist/design-variants.d.ts",
+      "default": "./dist/design-variants.js"
+    },
+    "./color-slots": {
+      "types": "./dist/color-slots.d.ts",
+      "default": "./dist/color-slots.js"
+    },
     "./backgrounds": {
       "types": "./dist/background-options.d.ts",
       "default": "./dist/background-options.js"
@@ -266,11 +274,11 @@
     "@codemirror/state": "6.7.6",
     "@codemirror/view": "6.43.14",
     "@lezer/highlight": "1.2.5",
-    "@openpresentation/opf": "^0.22.1",
+    "@openpresentation/opf": "^0.23.0",
     "jsonc-parser": "3.3.1"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.22.2"
+    "@openpresentation/opf-render": "^0.23.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
@@ -323,8 +331,8 @@
     "@expo-google-fonts/roboto-mono": "0.4.2",
     "@expo-google-fonts/stix-two-math": "0.4.0",
     "@expo-google-fonts/tinos": "0.4.2",
-    "@openpresentation/opf-pptx": "^0.22.0",
-    "@openpresentation/opf-render": "^0.22.2",
+    "@openpresentation/opf-pptx": "^0.23.0",
+    "@openpresentation/opf-render": "^0.23.0",
     "@resvg/resvg-js": "2.6.2",
     "axe-core": "4.14.0",
     "esbuild": "0.28.2",