@echelon-foundry/design-system 0.11.0 → 0.12.0-main.262.1

package/CHANGELOG.md

@@ -7,6 +7,34 @@ published as GitHub release tarballs
 and to npm. Earlier releases are described in `docs/CONSUMING-FORMA.md` and
 `HANDOFF.md`.
 
+## @echelon-foundry/forma-workflow 1.2.0
+
+Minor release of the workflow package (and `EchelonFoundry.Forma.Workflow` 1.2.0): it ships the Forma 0.12.0 engine. **Behaviour change: validation is stricter.** Documents that validated under 1.1.0 can now fail with `A11Y-NONTEXT-CONTRAST` (WCAG 1.4.11, 3:1), and `render` refuses documents that fail validation. Added: `token:status-warning|danger|success|info` diagram colours, `ValidationOptions.Theme` and `--theme` on `validate`/`render`. No element, class, attribute or token was removed or renamed (QD-004), so this is a minor release, as Forma 0.12.0 was. See 0.12.0 below for the migration.
+
+## 0.12.0
+
+Minor release: diagram non-text contrast and status tokens.
+
+**Behaviour change: workflow validation is stricter.** Diagram non-text contrast (R7-REM-009, `.praxis/inbox/documents/2026-10-29-R7-REM-009-diagram-nontext-contrast.md`).
+Documents that validated before can now fail with `A11Y-NONTEXT-CONTRAST`, and `forma-workflow render` refuses them (exit 1). The status tokens are additive.
+
+### Migration
+- Prefer Forma tokens for outlines and connectors: `token:status-*` or `token:border-functional` follow the theme and are not judged by the document rule.
+- If the host pins a theme, pass it: `--theme light|dark` on `validate` and `render`, or `ValidationOptions.Theme` with `Validation.loadWith`. Default-surface contrast is then judged for that theme only.
+- Otherwise adjust literal colours to reach 3:1 against the light (`#f2efe7`) and dark (`#171a18`) surfaces, or against the node's literal fill.
+
+### Added
+- **Status colour tokens in the workflow vocabulary.** `token:status-warning`, `token:status-danger`, `token:status-success` and `token:status-info` are accepted wherever a workflow colour is (`fill`, `stroke`, `accent`, `foreground`, edge `stroke`, palette slots) and render to `var(--ef-color-status-*)`. The workflow schema enum and `contracts/diagram-presentation.json` list them. An application can draw an attention outline with a Forma token instead of a brand literal.
+- **Validation rule `A11Y-NONTEXT-CONTRAST`** (error, accessibility; WCAG 1.4.11, 3:1). Literal (or literal-palette) colours on nodes, groups, legend swatches and edges. Without an authored fill, strokes, accents, legend swatches and edge strokes are judged against both default surfaces, light `#f2efe7` and dark `#171a18`, and the weaker theme is named; a pinned host theme (`--theme`, `ValidationOptions`) limits this to that theme's surface. With a literal fill, the accent must reach 3:1 against the fill; the stroke is reported only when it is below 3:1 against the fill and neither stroke nor fill reaches 3:1 against a default surface, so borderless filled shapes stay valid. Token values and token/literal mixes are not judged by the document rule; `tests/nontext-contrast.test.mjs` checks every status token and `border-functional` at 3:1 on surface-primary and surface-secondary in every shipped theme and brand. Rehearsal 6 regression: Causa's `#e9a23b` outline on `#f5f3ed` measured 1.95:1 and passed validation. See `docs/workflow/VALIDATION.md`, "Non-text contrast".
+- **Contract.** `contracts/diagram-presentation.json` marks `fill`, `stroke`, `accent` and `connectorStroke` `"contrast": "consumer"` (as `foreground` already was): colours set through the CSS custom properties bypass document validation and must be measured by the application.
+- **Browser regression.** `tests/browser/diagram-nontext-contrast.spec.mjs` measures real Forma.Workflow output (golden documents in `tests/fixtures/workflow-nontext/`, checked by the F# suite) in Chromium: status-token outlines, a diamond node and an edge reach 3:1 in light, dark and forced colours; the Rehearsal 6 document is reported by the validator and measures below 3:1.
+
+### Changed
+- **Validation is stricter** (see Migration above).
+- **`Validation.loadWith` / `ofJsonWith` / `semanticWith`** take `ValidationOptions` (`{ Theme }`); `load`, `ofJson` and `semantic` keep their behaviour with no pinned theme. The CLI's `validate` accepts `--theme`, and `render --theme` now also scopes validation.
+- `examples/workflows/forma/workflows/colored.forma-workflow.json`: connector `c2` stroke `#2f5fb3` → `#3d6cc0`. The old value is 2.85:1 on the dark surface and is now an `A11Y-NONTEXT-CONTRAST` error. Existing documents with literal colours may newly fail this rule.
+
+
 ## 0.11.0
 
 Minor release: typography roles (EII-F, `.praxis/inbox/documents/2026-10-28-EII-F-typography-roles.md`).

package/contracts/color-contract.json

@@ -1,6 +1,6 @@
 {
   "format": "forma.color-contract/1.0.0",
-  "formaVersion": "0.11.0",
+  "formaVersion": "0.12.0",
   "validationScope": "CSS var() references to --ef-color-* plus reserved internal color-related prefixes; other Forma APIs are governed by their own contracts.",
   "compatibility": {
     "policy": "Validate with the contract shipped by the pinned Forma package version.",

package/contracts/diagram-presentation.json

@@ -65,11 +65,11 @@
     }
   },
   "appearanceProperties": {
-    "fill": { "customProperty": "--ef-diagram-fill", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "--ef-color-surface-primary", "group": "transparent", "legend": "--ef-color-surface-primary" } },
-    "stroke": { "customProperty": "--ef-diagram-stroke", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "--ef-color-border-functional", "group": "--ef-color-border-functional", "legend": "--ef-color-border-functional" }, "print": "Authored stroke prints; otherwise black." },
-    "accent": { "customProperty": "--ef-diagram-accent", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "stroke", "group": "stroke", "legend": "stroke" } },
+    "fill": { "customProperty": "--ef-diagram-fill", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "--ef-color-surface-primary", "group": "transparent", "legend": "--ef-color-surface-primary" }, "contrast": "consumer" },
+    "stroke": { "customProperty": "--ef-diagram-stroke", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "--ef-color-border-functional", "group": "--ef-color-border-functional", "legend": "--ef-color-border-functional" }, "print": "Authored stroke prints; otherwise black.", "contrast": "consumer" },
+    "accent": { "customProperty": "--ef-diagram-accent", "appliesTo": ["node", "group", "legend"], "syntax": "color", "default": { "node": "stroke", "group": "stroke", "legend": "stroke" }, "contrast": "consumer" },
     "foreground": { "customProperty": "--ef-diagram-foreground", "appliesTo": ["node", "group"], "syntax": "color", "default": { "node": "--ef-color-text-primary", "group": "--ef-color-text-primary" }, "contrast": "consumer" },
-    "connectorStroke": { "customProperty": "--ef-diagram-connector-stroke", "appliesTo": ["connector"], "syntax": "color", "default": { "connector": "--ef-color-border-functional" } },
+    "connectorStroke": { "customProperty": "--ef-diagram-connector-stroke", "appliesTo": ["connector"], "syntax": "color", "default": { "connector": "--ef-color-border-functional" }, "contrast": "consumer" },
     "connectorWidth": { "customProperty": "--ef-diagram-connector-width", "appliesTo": ["connector"], "syntax": "number", "range": [1, 8], "default": { "connector": "2" } }
   },
   "geometryProperties": {
@@ -97,7 +97,11 @@
       "--ef-color-surface-secondary",
       "--ef-color-surface-inverse",
       "--ef-color-text-primary",
-      "--ef-color-text-secondary"
+      "--ef-color-text-secondary",
+      "--ef-color-status-warning",
+      "--ef-color-status-danger",
+      "--ef-color-status-success",
+      "--ef-color-status-info"
     ],
     "reset": "Remove the custom property to restore the Forma default (FMD-RESOLVE-006)."
   },

package/dist/icons/registry.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "formaVersion": "0.11.0",
+  "formaVersion": "0.12.0",
   "grid": 24,
   "icons": [
     {

package/dist/marketing/forma-all.css

@@ -1,4 +1,4 @@
-/*! Forma 0.11.0 | forma-all.css | bundle echelon-marketing
+/*! Forma 0.12.0 | forma-all.css | bundle echelon-marketing
     Complete Forma surface (application components, assessment, and marketing layers) for sites that also present Forma application patterns such as data grids or status lozenges.
     Generated by tools/PresentationBundler. Do not edit; pin by version and sha256. */
 

package/dist/marketing/forma-echelon-marketing.css

@@ -1,4 +1,4 @@
-/*! Forma 0.11.0 | forma-echelon-marketing.css | bundle echelon-marketing
+/*! Forma 0.12.0 | forma-echelon-marketing.css | bundle echelon-marketing
     Single-file Echelon marketing presentation: forma-marketing.css followed by the Echelon theme. Most sites load only this file.
     Generated by tools/PresentationBundler. Do not edit; pin by version and sha256. */
 

package/dist/marketing/forma-marketing-theme-echelon.css

@@ -1,4 +1,4 @@
-/*! Forma 0.11.0 | forma-marketing-theme-echelon.css | bundle echelon-marketing
+/*! Forma 0.12.0 | forma-marketing-theme-echelon.css | bundle echelon-marketing
     Echelon Marketing Theme: compiled theme tokens and theme hooks. Load after forma-marketing.css.
     Generated by tools/PresentationBundler. Do not edit; pin by version and sha256. */
 

package/dist/marketing/forma-marketing.css

@@ -1,4 +1,4 @@
-/*! Forma 0.11.0 | forma-marketing.css | bundle echelon-marketing
+/*! Forma 0.12.0 | forma-marketing.css | bundle echelon-marketing
     Brand-neutral marketing layer: core tokens, role defaults, Forma foundations, marketing foundations, components, and layouts.
     Generated by tools/PresentationBundler. Do not edit; pin by version and sha256. */
 

package/dist/marketing/forma-marketing.manifest.json

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "forma": "0.11.0",
+  "forma": "0.12.0",
   "bundle": "echelon-marketing",
   "description": "Forma presentation artifacts for Echelon marketing sites. Every artifact is a single self-contained CSS file with no imports or relative URLs.",
-  "releaseTag": "v0.11.0",
+  "releaseTag": "v0.12.0",
   "artifacts": [
     {
       "file": "forma-marketing.css",
       "description": "Brand-neutral marketing layer: core tokens, role defaults, Forma foundations, marketing foundations, components, and layouts.",
       "bytes": 92562,
-      "sha256": "d15eb11a605676935a683fd1382bdecf2fd9c070893c80974766b4c22ab63b75",
+      "sha256": "e945b2e9f5396108446be83c8b0af50b64487b5749fc35a05e3b8582090dbd5f",
       "sources": [
         "dist/tokens.css",
         "src/marketing/roles.css",
@@ -23,7 +23,7 @@
       "file": "forma-marketing-theme-echelon.css",
       "description": "Echelon Marketing Theme: compiled theme tokens and theme hooks. Load after forma-marketing.css.",
       "bytes": 6296,
-      "sha256": "66fcf350b0d36535df6fcb6fbca32bc1236b31398c49eeccf3670342f38e5ac9",
+      "sha256": "495b81a7dae75204ac9fcd2531754a2e0fa6e912009430d78d97d87807104402",
       "sources": [
         "build/marketing/echelon-marketing.tokens.css",
         "themes/echelon/marketing.css"
@@ -33,7 +33,7 @@
       "file": "forma-echelon-marketing.css",
       "description": "Single-file Echelon marketing presentation: forma-marketing.css followed by the Echelon theme. Most sites load only this file.",
       "bytes": 98702,
-      "sha256": "08975a531a7c4c8d2ec8c67e2c3998c4bbceaa25b8d1e5b1097a8420b85e6f12",
+      "sha256": "f93946ab2401d3a65f10ce96bbea8c830ad1c239bcc412c8f7906dfba8f6616c",
       "sources": [
         "artifact:forma-marketing.css",
         "artifact:forma-marketing-theme-echelon.css"
@@ -43,7 +43,7 @@
       "file": "forma-all.css",
       "description": "Complete Forma surface (application components, assessment, and marketing layers) for sites that also present Forma application patterns such as data grids or status lozenges.",
       "bytes": 342064,
-      "sha256": "8355d917009ade27384b73f43e29c756ae9298e499e26b18cee7ba198edf4fcf",
+      "sha256": "8126a388b0563f6d7f40a84058035bfd6cd62e966c181ff3c055f530bc2cc32c",
       "sources": [
         "dist/all.css"
       ]

package/dist/marketing/forma-marketing.sha256

@@ -1,4 +1,4 @@
-d15eb11a605676935a683fd1382bdecf2fd9c070893c80974766b4c22ab63b75  forma-marketing.css
-66fcf350b0d36535df6fcb6fbca32bc1236b31398c49eeccf3670342f38e5ac9  forma-marketing-theme-echelon.css
-08975a531a7c4c8d2ec8c67e2c3998c4bbceaa25b8d1e5b1097a8420b85e6f12  forma-echelon-marketing.css
-8355d917009ade27384b73f43e29c756ae9298e499e26b18cee7ba198edf4fcf  forma-all.css
+e945b2e9f5396108446be83c8b0af50b64487b5749fc35a05e3b8582090dbd5f  forma-marketing.css
+495b81a7dae75204ac9fcd2531754a2e0fa6e912009430d78d97d87807104402  forma-marketing-theme-echelon.css
+f93946ab2401d3a65f10ce96bbea8c830ad1c239bcc412c8f7906dfba8f6616c  forma-echelon-marketing.css
+8126a388b0563f6d7f40a84058035bfd6cd62e966c181ff3c055f530bc2cc32c  forma-all.css

package/dist/runtime.js

@@ -52,6 +52,6 @@ export function registerEchelonRuntime(name, metadata, target = globalThis) {
   return installEchelonRuntimeRegistrar(target)?.(name, metadata);
 }
 
-export const FORMA_VERSION = "0.11.0";
+export const FORMA_VERSION = "0.12.0";
 
 if (typeof window !== "undefined") registerEchelonRuntime("forma", { version: FORMA_VERSION }, window);

package/docs/workflow/FORMAT.md

@@ -104,7 +104,7 @@ saving.
 | `kindLabel` | Display text for the kind. Optional for core kinds. |
 | `label`, `description` | Visible text. |
 | `variant` | Forma shape: `rectangle`, `rounded`, `pill`, `ellipse` or `diamond`. Presentation only; a shape never implies a kind. |
-| `color` | `fill`, `stroke`, `accent` and `foreground`. Each is a `#rrggbb` literal, a Forma token (`token:accent-primary`) or a palette slot (`palette:finance`). |
+| `color` | `fill`, `stroke`, `accent` and `foreground`. Each is a `#rrggbb` literal, a Forma token or a palette slot (`palette:finance`). Tokens: `token:accent-primary`, `token:accent-secondary`, `token:border-functional`, `token:border-subtle`, `token:surface-primary`, `token:surface-secondary`, `token:surface-inverse`, `token:text-primary`, `token:text-secondary`, and the status roles `token:status-warning`, `token:status-danger`, `token:status-success` and `token:status-info` (render to `var(--ef-color-status-*)`; use them for attention outlines instead of a brand literal). |
 | `status` | `{ "state": "active", "label": "In progress", "detail": "...", "updatedAt": "..." }`. Core states are `none`, `pending`, `ready`, `active`, `waiting`, `complete`, `blocked`, `failed`, `skipped`, `cancelled` and `unknown`. A namespaced state needs a `label`. |
 | `ports` | Connection points: `id`, `side` (`top`, `right`, `bottom`, `left`), `direction` (`in`, `out`, `inout`), `label`, `maxConnections`. |
 | `references` | Domain references: `id`, `system` (a namespace), `type`, `key`, `label` and `href`. Forma displays them and never dereferences them. |

package/docs/workflow/VALIDATION.md

@@ -84,8 +84,57 @@ JSON Schema validator enforces it, so there is no hand-maintained copy.
 | Groups | `GROUP-MISSING-MEMBER`, `GROUP-MISSING-PARENT`, `GROUP-CYCLE`, `GROUP-LANE-CONFLICT` |
 | Extensions | `EXT-RESERVED` (and the schema's namespace and object rules) |
 | Compatibility | `COMPAT-UNAVAILABLE`, `COMPAT-UNKNOWN-CAPABILITY` |
-| Accessibility (static) | `A11Y-TITLE`, `A11Y-NAME`, `A11Y-CONTRAST` (authored text colour against fill below 4.5:1), `A11Y-BRANCH-LABEL`, `A11Y-LEGEND` |
+| Accessibility (static) | `A11Y-TITLE`, `A11Y-NAME`, `A11Y-CONTRAST` (authored text colour against fill below 4.5:1), `A11Y-NONTEXT-CONTRAST` (non-text indicators below 3:1, WCAG 1.4.11; see below), `A11Y-BRANCH-LABEL`, `A11Y-LEGEND` |
 | Security | `SEC-UNSAFE-URL` (anything other than http, https, mailto or relative; also control characters and leading spaces), `SEC-BIDI-CONTROL` |
 | Semantics (warnings) | `SEM-DECISION-BRANCHES`, `SEM-START-INCOMING`, `SEM-END-OUTGOING`, `LAYOUT-PARTIAL` |
 
 Errors decide the class. Warnings and notes do not.
+
+### Non-text contrast (`A11Y-NONTEXT-CONTRAST`)
+
+The rule judges literal colours (`#rrggbb`, or a palette slot holding one) on
+nodes, groups, legend swatches and edges against the 3:1 minimum of WCAG 1.4.11:
+
+- **No authored fill.** The shape is drawn on the default surface, so its
+  stroke and accent are judged against both default surfaces: light `#f2efe7`
+  and dark `#171a18` (`--ef-color-surface-primary` in the compiled light theme
+  and in the dark theme, including `prefers-color-scheme: dark`). The weaker
+  theme is reported and named. Legend swatches and edge strokes are judged the
+  same way.
+- **Pinned host theme.** When the host pins a theme (`--theme light|dark` on
+  `forma-workflow validate` and `render`, or `ValidationOptions.Theme` with
+  `Validation.loadWith`), default-surface comparisons use that theme's surface
+  only. Without a pinned theme the host follows `prefers-color-scheme`, so
+  both surfaces apply. Any other theme name is judged against both.
+- **Literal fill.** The accent is an indicator and must reach 3:1 against the
+  fill. The stroke is the shape's boundary: it is reported when it is below
+  3:1 against the fill *and* neither the stroke nor the fill reaches 3:1
+  against a default surface. A borderless filled shape (stroke equal to fill)
+  is valid wherever its fill stands out from the surface.
+
+**Limits.** The rule cannot know which theme a token resolves in, so it does
+not judge token values, token-backed palette slots, token fills, or
+token/literal mixes (a token stroke on a literal fill, a literal stroke on a
+token fill). Forma's own token pairs (every `status-*` token and
+`border-functional` on `surface-primary` and `surface-secondary`, in every
+shipped theme and brand) are covered by `tests/nontext-contrast.test.mjs`.
+Only `#f2efe7` and `#171a18` are used as default surfaces. Literal colours
+are judged against them, not against the surface of another Forma theme
+(for example `high-contrast`, `warm-earth` or `dark-technical`) or a brand an
+application applies; those surfaces are approximated by the light and dark
+defaults.
+
+The browser regression for this rule measures real Forma.Workflow output: the
+sources and golden HTML and findings files live in
+`tests/fixtures/workflow-nontext/`, and the F# suite checks them byte for
+byte. After an intended change to the renderer or the rule, regenerate them
+with `FORMA_UPDATE_GOLDEN=1 dotnet run --project tests/workflow/Forma.Workflow.Tests -c Release`.
+
+**CSS custom properties bypass validation.** Colours an application sets
+directly through `--ef-diagram-stroke`, `--ef-diagram-accent`,
+`--ef-diagram-fill`, `--ef-diagram-connector-stroke` or
+`--ef-diagram-foreground` never pass through the document, so no finding is
+produced; `contracts/diagram-presentation.json` marks them
+`"contrast": "consumer"`. An application that colours diagrams that way must
+measure the result in its own browser tests (computed border colour against
+computed background, as `tests/browser/diagram-nontext-contrast.spec.mjs` does).

package/examples/workflows/forma/workflows/colored.forma-workflow.json

@@ -80,7 +80,7 @@
         "node": "downlink"
       },
       "color": {
-        "stroke": "#2f5fb3"
+        "stroke": "#3d6cc0"
       },
       "width": 3
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/design-system",
-  "version": "0.11.0",
+  "version": "0.12.0-main.262.1",
   "private": false,
   "type": "module",
   "description": "Zero-component-runtime HTML and CSS design system for Echelon Foundry applications.",
@@ -86,7 +86,7 @@
     "site:mobile": "playwright test --config=playwright.site.config.mjs",
     "pack:verify": "npm run build && npm pack --dry-run",
     "test:package": "node --test tests/package-contract.test.mjs tests/conformance-package.test.mjs",
-    "test:css": "node --test tests/css-source.test.mjs tests/dist-css.test.mjs tests/contrast-pairs.test.mjs tests/diagram-contract.test.mjs",
+    "test:css": "node --test tests/css-source.test.mjs tests/dist-css.test.mjs tests/contrast-pairs.test.mjs tests/nontext-contrast.test.mjs tests/diagram-contract.test.mjs",
     "test:contrast": "node --test tests/contrast-pairs.test.mjs && playwright test tests/browser/pattern-contrast.spec.mjs --project=chromium",
     "brands:build": "dotnet run --project tools/BrandCompiler/BrandCompiler.fsproj -- brands dist/brands",
     "color:build": "node tools/color-contract/build.mjs",

package/schemas/workflow/1.0/forma-workflow.schema.json

@@ -259,7 +259,11 @@
             "token:surface-secondary",
             "token:surface-inverse",
             "token:text-primary",
-            "token:text-secondary"
+            "token:text-secondary",
+            "token:status-warning",
+            "token:status-danger",
+            "token:status-success",
+            "token:status-info"
           ]
         }
       ]