@echelon-foundry/design-system 0.8.0 → 0.9.0-main.252.1

package/dist/tokens.css

@@ -159,6 +159,10 @@
   --ef-color-control-track: #686d68;
   --ef-color-focus-gap: #f2efe7;
   --ef-color-focus-ring: #171a18;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #202421;
   --ef-color-surface-inverse-secondary: #3a403c;
   --ef-color-surface-primary: #f2efe7;
@@ -180,6 +184,10 @@
   --ef-color-control-track: #686d68;
   --ef-color-focus-gap: #171a18;
   --ef-color-focus-ring: #f2efe7;
+  --ef-color-status-danger: #ef9a8b;
+  --ef-color-status-info: #90b9dc;
+  --ef-color-status-success: #8cc49f;
+  --ef-color-status-warning: #ddb266;
   --ef-color-surface-inverse: #f2efe7;
   --ef-color-surface-inverse-secondary: #e3e0d7;
   --ef-color-surface-primary: #171a18;
@@ -201,6 +209,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #005ea8;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -221,6 +233,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #315f8c;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -241,6 +257,10 @@
   --ef-color-control-track: #50636d;
   --ef-color-focus-gap: #f8fafb;
   --ef-color-focus-ring: #005ea8;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #17242b;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f8fafb;
@@ -261,6 +281,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #175f8f;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -281,6 +305,10 @@
   --ef-color-control-track: #50636d;
   --ef-color-focus-gap: #f4f7f8;
   --ef-color-focus-ring: #245d7a;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #17252b;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f4f7f8;
@@ -301,6 +329,10 @@
   --ef-color-control-track: #686d68;
   --ef-color-focus-gap: #171a18;
   --ef-color-focus-ring: #f2efe7;
+  --ef-color-status-danger: #ef9a8b;
+  --ef-color-status-info: #90b9dc;
+  --ef-color-status-success: #8cc49f;
+  --ef-color-status-warning: #ddb266;
   --ef-color-surface-inverse: #f2efe7;
   --ef-color-surface-inverse-secondary: #e3e0d7;
   --ef-color-surface-primary: #171a18;
@@ -321,6 +353,10 @@
   --ef-color-control-track: #686d68;
   --ef-color-focus-gap: #12191d;
   --ef-color-focus-ring: #e8f1f4;
+  --ef-color-status-danger: #ef9a8b;
+  --ef-color-status-info: #90b9dc;
+  --ef-color-status-success: #8cc49f;
+  --ef-color-status-warning: #ddb266;
   --ef-color-surface-inverse: #e8f1f4;
   --ef-color-surface-inverse-secondary: #e3e0d7;
   --ef-color-surface-primary: #12191d;
@@ -341,6 +377,10 @@
   --ef-color-control-track: #686d68;
   --ef-color-focus-gap: #101619;
   --ef-color-focus-ring: #e7eef0;
+  --ef-color-status-danger: #ef9a8b;
+  --ef-color-status-info: #90b9dc;
+  --ef-color-status-success: #8cc49f;
+  --ef-color-status-warning: #ddb266;
   --ef-color-surface-inverse: #e7eef0;
   --ef-color-surface-inverse-secondary: #e3e0d7;
   --ef-color-surface-primary: #101619;
@@ -361,6 +401,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #000000;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #000000;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -381,6 +425,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #161616;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -401,6 +449,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #eeeeee;
   --ef-color-focus-ring: #161616;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #eeeeee;
@@ -421,6 +473,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #f1f0e5;
   --ef-color-focus-ring: #20281f;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #20281f;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f1f0e5;
@@ -441,6 +497,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #f6f4ef;
   --ef-color-focus-ring: #161616;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f6f4ef;
@@ -461,6 +521,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #9c2f25;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -481,6 +545,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #f7f2e7;
   --ef-color-focus-ring: #211d18;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #211d18;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f7f2e7;
@@ -501,6 +569,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #ffffff;
   --ef-color-focus-ring: #7a3f70;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #161616;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #ffffff;
@@ -521,6 +593,10 @@
   --ef-color-control-track: #555555;
   --ef-color-focus-gap: #f3eadc;
   --ef-color-focus-ring: #29231c;
+  --ef-color-status-danger: #a13a2c;
+  --ef-color-status-info: #2d5f86;
+  --ef-color-status-success: #2e6a45;
+  --ef-color-status-warning: #86560f;
   --ef-color-surface-inverse: #29231c;
   --ef-color-surface-inverse-secondary: #303030;
   --ef-color-surface-primary: #f3eadc;

package/docs/BRANDING.md

@@ -125,9 +125,12 @@ Ordo / domain
 
 ## Accessibility
 
-The brand compiler currently validates the relationships that are most likely to
-make a branded interface unreadable: primary and secondary text, text on
-secondary surfaces, inverse text, primary/secondary accents, and focus rings.
+The brand compiler validates the relationships that are most likely to make a
+branded interface unreadable: primary and secondary text, text on secondary
+surfaces, inverse text, primary/secondary accents, focus rings, and every
+declared status role. Shipped brands override success, warning, danger, and
+info; a third-party 1.0 manifest may omit them and inherit the active core
+theme, preserving schema compatibility.
 
 A failed brand does not get a best-effort output. Fix the manifest and compile
 again.

package/docs/COLOR.md

@@ -0,0 +1,77 @@
+# Semantic color contract
+
+Forma 0.9.0 publishes its machine-readable color vocabulary at
+`contracts/color-contract.json`. The file is generated from the token source,
+shipped brand manifests, and `package.json`; consumers must use the contract
+from the exact Forma version they pin. The manifest separates public
+`--ef-color-*` properties from internal component variables, records every
+theme and shipped brand value, and declares supported semantic pairings.
+
+Validate application CSS without copying Forma CSS:
+
+```bash
+npx forma-color validate src/**/*.css
+```
+
+The programmatic API is exported as
+`@echelon-foundry/design-system/color-contract`. `validateCssColorReferences`
+reports the source file, line, column, unsupported name, and supported role.
+Public `--ef-color-*` references and reserved internal color-related prefixes
+are governed; other Forma APIs keep their own contracts. Application variables
+such as `--summa-*` are deliberately ignored. Internal variables reported by
+the validator are not consumer APIs even when they appear in compiled CSS.
+
+## Fallback policy
+
+An unknown `--ef-*` name is invalid even when `var()` supplies a literal
+fallback. For a known public color token, a six-digit literal fallback is
+allowed only when it exactly repeats that release's light-theme value. This
+narrow exception supports loading a standalone Forma layer; it is not a way to
+invent a brand or semantic value. Prefer no literal fallback when the complete
+Forma stylesheet is loaded.
+
+## Supported pairings
+
+The manifest is the canonical exhaustive table. In summary:
+
+| Meaning | Foreground | Surface or boundary | Non-color requirement |
+| --- | --- | --- | --- |
+| Primary action | `text-inverse` | `surface-inverse` | visible label and native action semantics |
+| Secondary action | `text-primary` | `surface-primary`, `border-functional` | visible label and boundary |
+| Link | `accent-primary` | `surface-primary` | underline or link context; Forma re-pairs links on secondary surfaces |
+| Selection/current | `text-inverse` | `surface-inverse` | native checked/selected state or `aria-current` |
+| Notice/pending/unknown | `status-info` | `surface-primary` | explicit state text plus glyph, border, or accessible name |
+| Warning | `status-warning` | `surface-primary` | explicit state text plus glyph, border, or accessible name |
+| Danger | `status-danger` | `surface-primary` | explicit state text plus glyph, border, or accessible name |
+| Success | `status-success` | `surface-primary` | explicit state text plus glyph, border, or accessible name |
+| Disabled | `text-primary` | `surface-secondary`, dashed `border-functional` | native `disabled`; opacity is supplemental |
+| Focus | `focus-ring` | effective rendered surface, separated by `focus-gap` | keyboard-visible outline geometry |
+
+Every shipped theme and brand provides the four status roles. Each status
+foreground is contrast-gated at 4.5:1 on `surface-primary`. In forced colors,
+foreground and status roles project to `CanvasText`, surfaces to `Canvas`, and
+selection to `Highlight`/`HighlightText` where a component owns selection.
+Derived `color-mix()` and translucent colors must be tested after browser
+composition against their effective surface.
+
+Categorical and ordinal data-visualization palettes are application-level
+extensions, not Forma primitives. Applications must provide direct labels,
+shapes, patterns, ordered position, or a text/table alternative and validate
+the complete rendered palette. Grayscale and protan/deutan/tritan simulations
+are useful regression screens, not proof of perception or aesthetic quality.
+
+## Summa migration
+
+The plausible-looking names below have never been public Forma tokens and must
+remain refused, including against the 0.6.1 compatibility fixture:
+
+| Unsupported name | Supported role | Required pairing |
+| --- | --- | --- |
+| `--ef-color-action-primary` | `--ef-color-surface-inverse` | `--ef-color-text-inverse` |
+| `--ef-color-text-link` | `--ef-color-accent-primary` | `--ef-color-surface-primary` or Forma's secondary-surface link hook |
+| `--ef-color-focus` | `--ef-color-focus-ring` | `--ef-color-focus-gap` on the effective surface |
+| `--ef-color-text-danger` | `--ef-color-status-danger` | `--ef-color-surface-primary` plus explicit error text |
+
+A valid token reference proves compatibility only. It does not prove that the
+role is the right product-level palette, emphasis, hierarchy, or cultural
+choice. Those decisions require contextual design review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/design-system",
-  "version": "0.8.0",
+  "version": "0.9.0-main.252.1",
   "private": false,
   "type": "module",
   "description": "Zero-runtime HTML and CSS design system for Echelon Foundry applications.",
@@ -23,6 +23,8 @@
     "./marketing.css": "./dist/marketing.css",
     "./marketing/*": "./dist/marketing/*",
     "./tokens.json": "./tokens/echelon.tokens.json",
+    "./color-contract": "./tools/color-contract/index.mjs",
+    "./contracts/color-contract.json": "./contracts/color-contract.json",
     "./figma/components.json": "./figma/component-contracts.json",
     "./contracts/diagram-presentation.json": "./contracts/diagram-presentation.json",
     "./workflow/forma-workflow.schema.json": "./schemas/workflow/1.0/forma-workflow.schema.json",
@@ -42,6 +44,9 @@
     "docs/BRANDING.md",
     "docs/MARKETING-SITES.md",
     "tokens/echelon.tokens.json",
+    "tools/color-contract",
+    "contracts/color-contract.json",
+    "docs/COLOR.md",
     "figma/component-contracts.json",
     "contracts/diagram-presentation.json",
     "schemas/workflow/1.0/forma-workflow.schema.json",
@@ -62,15 +67,16 @@
     "clean": "node tools/clean.mjs",
     "tokens:build": "dotnet run --project tools/TokenCompiler/TokenCompiler.fsproj -- tokens/echelon.tokens.json dist/tokens.css",
     "assets:build": "node tools/build-assets.mjs",
-    "build": "npm run clean && npm run tokens:build && npm run brands:build && npm run marketing:theme && npm run assets:build && npm run marketing:build && npm run example:install",
+    "build": "npm run clean && npm run tokens:build && npm run brands:build && npm run color:build && npm run marketing:theme && npm run assets:build && npm run marketing:build && npm run example:install",
     "test:tokens": "node --test tests/token-compiler.test.mjs",
     "test:browser": "playwright test",
     "test:a11y": "playwright test tests/browser/accessibility.spec.mjs",
     "test:runtime": "node --test tests/zero-runtime.test.mjs",
     "test:design": "node --test tests/design-contract.test.mjs",
+    "test:color": "node --test tests/color-contract.test.mjs",
     "motion:audit": "node tools/motion-audit.mjs",
     "test:motion": "node --test tests/motion-audit.test.mjs tests/motion-gate.test.mjs && node tools/motion-audit.mjs --strict",
-    "check": "npm run build && npm run icons:check && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:figma && npm run test:css && npm run test:package && npm run workflow:test && npm run workflow:build && npm run test:workflow-package && npm run test:browser",
+    "check": "npm run build && npm run icons:check && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:color && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:figma && npm run test:css && npm run test:package && npm run workflow:test && npm run workflow:build && npm run test:workflow-package && npm run test:browser",
     "site:build": "npm run build && node tools/build-site.mjs",
     "site:test": "node --test tests/site-build.test.mjs tests/catalog-coverage.test.mjs tests/icon-docs.test.mjs tests/catalog-interaction.test.mjs",
     "site:check": "npm run site:build && npm run catalog:check && npm run site:test && npm run site:mobile",
@@ -80,6 +86,7 @@
     "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: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",
     "test:brands": "node --test tests/brand-compiler.test.mjs",
     "test:character-grid": "node --test tests/character-grid.test.mjs",
     "marketing:theme": "dotnet run --project tools/TokenCompiler/TokenCompiler.fsproj -- themes/echelon/marketing.tokens.json build/marketing/echelon-marketing.tokens.css --reference tokens/echelon.tokens.json",
@@ -106,6 +113,9 @@
     "@axe-core/playwright": "4.13.0",
     "@playwright/test": "1.63.0"
   },
+  "bin": {
+    "forma-color": "./tools/color-contract/cli.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true

package/schemas/brand-manifest.schema.json

@@ -122,7 +122,7 @@
             "status": {
               "type": "object",
               "additionalProperties": false,
-              "description": "Optional marketing status roles; each must reach 4.5:1 on the primary surface and always accompany text.",
+              "description": "Optional brand overrides for public status roles. Omitted roles inherit from the active core theme; declared values must reach 4.5:1 on the primary surface and accompany a non-color cue.",
               "properties": {
                 "success": { "$ref": "#/$defs/hex" },
                 "warning": { "$ref": "#/$defs/hex" },