ContextualWisdomLab · cursor · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,6 @@ htmlcov/
 
 # CodeGraph local index
 .codegraph/
+
+# Storybook local build output
+storybook-static/
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -0,0 +1,9 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  framework: '@storybook/react-vite',
+  stories: ['../stories/**/*.stories.@(ts|tsx)'],
+  addons: ['@storybook/addon-docs'],
+};
+
+export default config;
diff --git a/.storybook/preview.ts b/.storybook/preview.ts
@@ -0,0 +1,11 @@
+import type { Preview } from '@storybook/react';
+
+import '../src/styles.css';
+
+const preview: Preview = {
+  parameters: {
+    controls: { disable: true },
+  },
+};
+
+export default preview;
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -25,6 +25,8 @@ The protected standalone product provides:
 - dependency-locked Chromium/Firefox/WebKit rich-clipboard release assurance; and
 - a network-free Office renderer for deterministic DOCX, XLSX, and PPTX output.
 
+A named editor-chrome theme-token catalog and Storybook inventory for repeating toolbar/editor objects are Active PR / Proposed. Hosts override `--cwl-*` on `.cwl-editor`; Inkspan does not own Figma Variables, brand certification, or design-tool sync.
+
 Hosts own transport, authorization, tenant isolation, persistence, credentials, migration, retention, and model-use policy. They also own authentication, deployment, durable audit, print destination policy, and any durable PDF/print-service authority; persistence includes durable storage and commit authority.
 
 Inkspan therefore never opens a production collaboration connection, chooses a tenant, stores a provider secret, creates a durable database transaction, decides a retention schedule, authorizes an AI operation, or claims that a browser print destination constitutes a durable authorized export. A standalone adopter can provide those capabilities directly; a CWL host can provide them through shared platform services.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,9 @@ Historical release entries from **0.1.0 through 0.5.27** are preserved verbatim
 
 ## [Unreleased]
 
+### Added
+- Named the repeating editor chrome as a host-facing theme-token catalog and Storybook inventory so hosts can override `--cwl-*` custom properties on `.cwl-editor` after checking WCAG 2.2 contrast, without editing Inkspan internals.
+
 ## [0.6.0] — 2026-08-10
 
 ### Release

diff --git a/README.md b/README.md
@@ -119,6 +119,21 @@ export function Example() {
 Set `mode="html"` when `value` and `onChange` should exchange HTML. Both modes
 embed accepted images as inline data URIs.
 
+### Theme the repeating chrome
+
+Override the named `--cwl-*` custom properties on `.cwl-editor` after checking
+WCAG 2.2 contrast. Do not edit Inkspan internals. See
+[`docs/design-tokens.md`](docs/design-tokens.md) for the token catalog and
+[`docs/storybook-inventory.md`](docs/storybook-inventory.md) for the Storybook
+preview of toolbar and editor chrome.
+
+```css
+.cwl-editor {
+  --cwl-accent: #0b6e4f;
+  --cwl-accent-soft: #d8f3e8;
+}
+```
+
 ### Server rendering
 
 `CwlEditor` and `CollaborativeCwlEditor` are safe to include in server-rendered

diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md
@@ -152,6 +152,7 @@ Rollback must preserve readable canonical documents and must not require silentl
 | autosave | local ordering/state, callback contract, validator validation | transport, durable CAS, retry/offline policy, persistence |
 | collaboration | provider-neutral editor/Yjs binding | provider lifecycle, rooms, identity, authorization, persistence, awareness privacy |
 | Office rendering | deterministic bounded JSON→artifact conversion | file destination policy, downstream distribution, tenant authorization |
+| editor chrome theming (Active PR / Proposed) | named `--cwl-*` tokens, DTCG interchange snapshot, Storybook inventory | host brand CSS, contrast certification, Figma Variables, design-tool sync |
 | naruon composition | stable local package/module boundary | authenticated compose transport, tenancy, provider/model policy |
 | model assistance | deterministic proposal acceptance boundary | provider, prompt/data policy, credentials, human approval |
 | release evidence | exact three-file draft inventory, package/artifact/digest verification and repository evidence | downstream deployment and operational rollout |

diff --git a/docs/DOCUMENTATION_FITNESS.md b/docs/DOCUMENTATION_FITNESS.md
@@ -56,6 +56,7 @@ Document fitness and implementation maturity are independent. A `present_current
 | Unified stable registry release train | ADR 0019, protected release workflow and release doctoring | `present_current` | `implemented_on_protected_main` | Stable npm/Office version equality, OIDC Trusted Publishing, exact-artifact publication and post-publication digest verification are source-integrated; live registry publication remains separate operational evidence. |
 | Framework-neutral Markdown package boundary | ADR 0020, protected `@contextualwisdomlab/cwl-editor/markdown` package subpath and shared policy modules from #114 | `present_current` | `implemented_on_protected_main` | Server/worker consumers can reuse deterministic Markdown/HTML/email/plain-text conversion without evaluating the React/TipTap editor graph. |
 | CSS paged-media print boundary | ADR 0021, protected `src/styles.css`, packaged stylesheet evidence and real-browser print tests from #116/#127 | `present_current` | `implemented_on_protected_main` | Declarative print output removes screen-only clipping/chrome while preserving authored content without creating a durable PDF service. |
+| Editor chrome design tokens / Storybook inventory | ADR 0027, `docs/design-tokens.md`, doctoring, token catalog, and Storybook stories | `present_current` | `implemented_on_active_pr` | Hosts can name, override, and preview repeating toolbar/editor tokens without treating the interchange snapshot as shipped protected-main authority. |
 | Informative DOCX PNG figures | ADR 0022, Office schema/renderer/tests and guidance | `present_current` | `implemented_on_protected_main` | Strict bounded inline PNG figures preserve informative alternative text without remote-resource or arbitrary OOXML authority. |
 | DOCX bounded rich-text runs | ADR 0023, Office schema/renderer/tests and doctoring | `present_current` | `implemented_on_protected_main` | Ordered bold/italic/underline runs preserve common inline fidelity under one bounded deterministic contract. |
 | DOCX bounded paragraph alignment | ADR 0024, Office schema/renderer/tests, Office guidance and doctoring | `present_current` | `implemented_on_protected_main` | `paragraph` and `rich_paragraph` preserve explicit left/center/right/justify alignment while omission retains inherited/default behavior. |
@@ -82,6 +83,7 @@ The documentation pack is substantially complete for acquisition review, but rep
 1. The protected manifests now agree at `0.6.0`, while registry operational acceptance remains open under issue #118 because the exact protected release still needs its tag/GitHub Release, live npm/PyPI Trusted Publisher execution, and public artifact digest verification.
 2. Future protected-source changes must continue to reconcile PRD/TRD/Architecture/ADR/UML/DATA_MODEL/security/test/operability/traceability semantics rather than treating this baseline as permanently complete.
 3. Documentation becoming mergeable, green, or protected-merged is never a reason for the commercial loop to stop; the next safe product, release, security, accessibility, package, Office-fidelity, or interoperability lane continues.
+4. Hosts still need a named, Storybook-previewable chrome-token catalog so brand theming does not require editing Inkspan internals; that lane is Active PR / Proposed and must not be described as shipped until protected integration.
 
 ## Sufficiency decision
 

diff --git a/docs/PRD.md b/docs/PRD.md
@@ -146,3 +146,5 @@ Shareable acquisition evidence excludes production tenant content and credential
 Protected `main` is the sole implemented baseline. Open PRs may describe Proposed or Active work but are not shipped contracts until protected integration. Canonical documentation must state when a requirement is target architecture rather than current implementation.
 
 SafeClipboard, real Chromium/Firefox/WebKit release assurance, lifecycle observation, the root security disclosure lifecycle, toolbar shortcut accessibility metadata, SSR/native-form serialization, revision-scoped selection evidence, W3C text-position selector evidence, document-transition evidence, and envelope identity migration routing are implemented on protected `main`.
+
+A named editor-chrome theme-token catalog, DTCG 2025.10 interchange snapshot, and Storybook inventory for repeating toolbar/editor objects are Active PR / Proposed and are not shipped claims until protected integration.
diff --git a/docs/README.md b/docs/README.md
@@ -18,6 +18,7 @@ This directory is the discoverable index for Inkspan's product, technical, secur
 | [`package-distribution.md`](package-distribution.md) | Buyer-facing public npm package entrypoints, packaged contents, runtime dependency boundaries, and consumer verification |
 | [`email-output.md`](email-output.md) | Deterministic email fragment/full-document authority, language/direction metadata, accessibility and host-owned transport boundary |
 | [`print-output.md`](print-output.md) | Browser print/paged-media presentation, accessibility/fidelity limits, host-owned governed-export boundary, and rollback |
+| [`design-tokens.md`](design-tokens.md) | Host-facing editor chrome tokens, DTCG 2025.10 interchange snapshot, and Storybook inventory (Active PR / Proposed) |
 | [`UML.md`](UML.md) | Component, sequence, state and authority-flow diagrams |
 | [`DATA_MODEL.md`](DATA_MODEL.md) | Conceptual evidence/domain model and persistence ownership |
 | [`THREAT_MODEL.md`](THREAT_MODEL.md) | Trust boundaries, abuse cases, security/privacy controls and residual risks |

diff --git a/docs/TRACEABILITY.md b/docs/TRACEABILITY.md
@@ -21,6 +21,7 @@ This record maps durable Inkspan product decisions to authoritative standards, p
 | Browser clipboard behavior | Security-relevant rich HTML handling requires actual paste-pipeline integration and bounded semantic reconstruction before editor state | WHATWG HTML parsing; W3C Clipboard API | protected-main rich-clipboard unit/integration corpus and SafeClipboard ADR | Protected jsdom/TipTap integration success is not universal browser-engine conformance |
 | Cross-engine release assurance | The same committed synthetic adversarial corpus runs under required Chromium, Firefox, and WebKit projects; exact package-lock and packed npm artifact SHA-256 digests are required, and only focused standards-grounded safe differences may be admitted | WHATWG HTML Living Standard; W3C Clipboard API and events; Playwright 1.62 release notes and browser/project documentation | ADR 0016, protected-main browser evidence source/workflows, TEST_STRATEGY, OPERABILITY and UML | Protected-main implementation is the release-policy authority; every release candidate must regenerate fresh exact-source/lock/run/browser evidence bound to the exact packed npm artifact SHA-256 and does not claim byte-identical browser serialization or branded enterprise-policy coverage |
 | CSS paged-media output | Shipped editor CSS has a declarative print boundary that removes interactive chrome and screen clipping while preserving authored document flow and bounded fragmentation behavior | W3C Media Queries Level 3; CSS Fragmentation Level 3; CSS Paged Media Level 3 as tracked draft input | protected-main #116 packaged stylesheet, real-browser print-media evidence, ADR 0021, print doctoring and tests | `implemented_on_protected_main`; browser print styling does not create a durable PDF service, page-number/header authority, persistence, signing, or PDF-conformance claim |
+| Editor chrome design tokens | Repeating toolbar/editor surfaces share named `--cwl-*` custom properties; hosts override those properties on `.cwl-editor` and preview them in Storybook | Design Tokens Format Module 2025.10; WCAG 2.2 contrast; Storybook React/Vite | Active-PR doctoring `docs/doctoring/editor-design-tokens.md`, operator guide, ADR 0027, token catalog tests, and Storybook inventory | Proposed until protected `main`; the interchange snapshot is not complete DTCG conformance, Figma Variables sync, or a host WCAG certification |
 | Editor integration | Public behavior must exercise the actual TipTap/ProseMirror integration path, not an inert extension field or test-only hook | official TipTap and ProseMirror documentation for the locked dependency line | integration tests and package consumers | Inkspan does not claim compatibility with untested major-version integration semantics |
 | Collaboration | Inkspan provides provider-neutral editor/Yjs bindings; host owns provider lifecycle, room authorization, awareness privacy, persistence and audit | official Yjs/provider documentation plus Inkspan public contract | collaboration tests and architecture ownership matrix | No network-provider or tenant-authorization authority is implied |
 | Secure development | Security controls are developed test-first, with exact-head scanning/review/package evidence and root-cause regression | NIST SP 800-218 SSDF 1.1 | CI/security/SAST/package/provenance gates, doctoring and regression history | Repository evidence is not a claim of complete SSDF organizational conformance |
@@ -38,6 +39,8 @@ Bray, T. (Ed.). (2015). *The I-JSON Message Format* (RFC 7493). RFC Editor. http
 
 Bray, T. (Ed.). (2017). *The JavaScript Object Notation (JSON) Data Interchange Format* (RFC 8259; STD 90). RFC Editor. https://doi.org/10.17487/RFC8259
 
+Design Tokens Community Group. (2025, October 28). *Design Tokens Format Module 2025.10* (Final Community Group Report). World Wide Web Consortium. https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/
+
 Ecma International. (2021). *ECMA-376: Office Open XML file formats* (5th ed.). https://ecma-international.org/publications-and-standards/standards/ecma-376/
 
 Ecma International. (2026). *ECMA-402: ECMAScript 2026 internationalization API specification* (13th ed.). https://402.ecma-international.org/
@@ -70,6 +73,8 @@ Rundgren, A., Jordan, B., & Erdtman, S. (2020). *JSON Canonicalization Scheme (J
 
 Souppaya, M., Scarfone, K., & Dodson, D. (2022). *Secure Software Development Framework (SSDF) Version 1.1: Recommendations for Mitigating the Risk of Software Vulnerabilities* (NIST SP 800-218). National Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-218
 
+Storybook. (n.d.). *Storybook for React with Vite*. Retrieved August 16, 2026, from https://storybook.js.org/docs/get-started/frameworks/react-vite
+
 Web Hypertext Application Technology Working Group. (2026). *HTML Standard: Parsing HTML documents* (Living Standard). Retrieved August 10, 2026, from https://html.spec.whatwg.org/multipage/parsing.html
 
 World Wide Web Consortium. (2013). *PROV-DM: The PROV Data Model*. https://www.w3.org/TR/prov-dm/

diff --git a/docs/adr/0027-editor-design-tokens-storybook.md b/docs/adr/0027-editor-design-tokens-storybook.md
@@ -0,0 +1,42 @@
+# ADR 0027: Editor chrome design tokens and Storybook inventory
+
+Status: Proposed
+
+## Context
+
+Inkspan ships repeating toolbar buttons, groups, and editor chrome styled through `--cwl-*` custom properties. Hosts already re-theme by overriding those properties, but the names, light/dark/forced-colors values, and buyer next action lived only inside `src/styles.css`. There was no typed catalog, no Design Tokens Format Module interchange snapshot, and no Storybook inventory of the repeating objects.
+
+## Alternatives considered
+
+1. **Leave theming as undocumented CSS.** Rejected because hosts would keep reading internals and drift from the shipped token set.
+2. **Generate CSS from a new token source of truth.** Rejected for this slice because it would rewrite the protected stylesheet and collide with print, forced-colors, and Office-unrelated presentation contracts.
+3. **Add Figma Variables sync or a design-tool connector.** Rejected because Figma/design-tool credentials and sync authority are host-owned; Inkspan remains independently usable.
+4. **Publish a named catalog plus Storybook inventory while CSS remains runtime authority.** Selected because hosts can override and preview repeating chrome without moving presentation authority or adding a design-tool runtime.
+
+## Decision
+
+Inkspan publishes a host-facing theme-token catalog for the nine shipped chrome tokens, a Design Tokens Format Module 2025.10 interchange snapshot, and a Storybook inventory of repeating toolbar/editor objects. Hosts override `--cwl-*` on `.cwl-editor` after checking WCAG 2.2 contrast. Unknown token names fail closed. No Figma, network, persistence, credential, or model authority is added.
+
+## Consequences and ownership trade-offs
+
+Hosts gain a copyable token list and a Storybook preview. Inkspan keeps CSS as the runtime source. naruon and other CWL hosts can apply the same overrides through host-owned brand CSS. Complete DTCG conformance, Figma Variables, and host WCAG certification remain out of scope.
+
+## Failure and recovery
+
+An unknown token name throws `EditorThemeTokenError` without reflecting caller input. A host override that fails contrast is recovered by changing only the named tokens, not by editing Inkspan internals or disabling forced-colors.
+
+## Security and privacy impact
+
+The catalog contains only public presentation values. It does not carry document bodies, tenant identifiers, credentials, or diagnostics. Storybook is a local development preview and is not a production transport.
+
+## Compatibility and migration
+
+The catalog is additive. Existing CSS overrides on `.cwl-editor` continue to work. A later CSS token addition must update the catalog, Storybook inventory, and this ADR together.
+
+## Verification and acceptance evidence
+
+Required evidence includes token-catalog tests against `src/styles.css`, documentation-contract tests, Storybook inventory stories for toolbar button states and token swatches, and exact-head CI/coverage/package/security gates on the unchanged head. This ADR stays Proposed until protected integration.
+
+## Rollback or supersession
+
+Rollback removes the catalog export, Storybook inventory/config, operator/doctoring records, and this ADR together. Supersession requires a new ADR if CSS ceases to be runtime presentation authority or if a design-tool sync contract is accepted.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -32,6 +32,7 @@ This index records durable architectural decisions. Protected-main implementatio
 | [0024](0024-bounded-docx-paragraph-alignment.md) | Accepted | Bounded paragraph alignment in deterministic DOCX output |
 | [0025](0025-bounded-docx-heading-alignment.md) | Accepted | Bounded heading alignment in deterministic DOCX output |
 | [0026](0026-bounded-docx-external-hyperlinks.md) | Accepted | Bounded external hyperlinks in deterministic DOCX rich text |
+| [0027](0027-editor-design-tokens-storybook.md) | Proposed | Editor chrome design tokens and Storybook inventory |
 
 ## Decision discipline
 

diff --git a/docs/design-tokens.md b/docs/design-tokens.md
@@ -0,0 +1,38 @@
+# Editor chrome design tokens
+
+Status: Active PR / Proposed
+
+Use this catalog when you need to re-theme Inkspan's repeating toolbar and editor chrome. Override the named custom properties on `.cwl-editor` after checking WCAG 2.2 contrast. Do not edit Inkspan internals.
+
+```css
+.cwl-editor {
+  --cwl-accent: #0b6e4f;
+  --cwl-accent-soft: #d8f3e8;
+}
+```
+
+```ts
+import {
+  listEditorThemeTokens,
+  toDesignTokenFormatGroup,
+} from '@contextualwisdomlab/cwl-editor';
+
+const tokens = listEditorThemeTokens();
+const dtcgGroup = toDesignTokenFormatGroup();
+void tokens;
+void dtcgGroup;
+```
+
+The stylesheet remains runtime presentation authority. `toDesignTokenFormatGroup()` is an interchange snapshot aligned to Design Tokens Format Module 2025.10. It is not complete DTCG conformance, Figma Variables sync, or a host WCAG certification.
+
+Preview the repeating objects in Storybook (`pnpm storybook`) using the inventory in [`storybook-inventory.md`](storybook-inventory.md).
+
+```mermaid
+flowchart LR
+  Host[Host brand CSS] --> Editor[".cwl-editor custom properties"]
+  Catalog[listEditorThemeTokens] --> Host
+  Editor --> Toolbar[".cwl-toolbar / .cwl-tb-btn"]
+  Editor --> Surface[".cwl-editor document surface"]
+  Storybook[Storybook inventory] --> Toolbar
+  Storybook --> Surface
+```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -146,3 +146,5 @@ Shareable acquisition evidence excludes production tenant content and credential
		Protected `main` is the sole implemented baseline. Open PRs may describe Proposed or Active work but are not shipped contracts until protected integration. Canonical documentation must state when a requirement is target architecture rather than current implementation.

		SafeClipboard, real Chromium/Firefox/WebKit release assurance, lifecycle observation, the root security disclosure lifecycle, toolbar shortcut accessibility metadata, SSR/native-form serialization, revision-scoped selection evidence, W3C text-position selector evidence, document-transition evidence, and envelope identity migration routing are implemented on protected `main`.

		A named editor-chrome theme-token catalog, DTCG 2025.10 interchange snapshot, and Storybook inventory for repeating toolbar/editor objects are Active PR / Proposed and are not shipped claims until protected integration.