@echelon-foundry/design-system 0.4.1 → 0.5.0-main.231.1

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

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "forma": "0.4.1",
+  "forma": "0.5.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.4.1",
+  "releaseTag": "v0.5.0",
   "artifacts": [
     {
       "file": "forma-marketing.css",
       "description": "Brand-neutral marketing layer: core tokens, role defaults, Forma foundations, marketing foundations, components, and layouts.",
       "bytes": 78117,
-      "sha256": "28874da37c70ac0f820a73d7a39e2e44a9fcc04df3ed213e424a9f3271a65c03",
+      "sha256": "9c84f0b5693e6583d4129ecc4603ed0e723b342463642d1663ba4200426ac41b",
       "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": 6295,
-      "sha256": "01deabdbc7fc522c56e261657e62a06b084876b920a117da6e78e81b5ae952ef",
+      "sha256": "2475da7fd4c4236024f0ffd7205044ee8f00556df069da0cb8b24209f491c0d3",
       "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": 84257,
-      "sha256": "bf6be3078b577d013fa9eacd50a9dcf71afba73382cf82b41c3069502d2b7212",
+      "sha256": "93d9172547f4a59a06cd42592c6f32df5b46032a7039abc9f88de907229e44ef",
       "sources": [
         "artifact:forma-marketing.css",
         "artifact:forma-marketing-theme-echelon.css"
@@ -42,8 +42,8 @@
     {
       "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": 316730,
-      "sha256": "84dd284067615b97e29ebaba34de54daf6204a3d99cabdc59e6f786b44ad35e3",
+      "bytes": 317382,
+      "sha256": "e338a6b0b392a4114f91c6ce9fface0284a403b0d7b2c7851640d2702565c62d",
       "sources": [
         "dist/all.css"
       ]

package/dist/marketing/forma-marketing.sha256

@@ -1,4 +1,4 @@
-28874da37c70ac0f820a73d7a39e2e44a9fcc04df3ed213e424a9f3271a65c03  forma-marketing.css
-01deabdbc7fc522c56e261657e62a06b084876b920a117da6e78e81b5ae952ef  forma-marketing-theme-echelon.css
-bf6be3078b577d013fa9eacd50a9dcf71afba73382cf82b41c3069502d2b7212  forma-echelon-marketing.css
-84dd284067615b97e29ebaba34de54daf6204a3d99cabdc59e6f786b44ad35e3  forma-all.css
+9c84f0b5693e6583d4129ecc4603ed0e723b342463642d1663ba4200426ac41b  forma-marketing.css
+2475da7fd4c4236024f0ffd7205044ee8f00556df069da0cb8b24209f491c0d3  forma-marketing-theme-echelon.css
+93d9172547f4a59a06cd42592c6f32df5b46032a7039abc9f88de907229e44ef  forma-echelon-marketing.css
+e338a6b0b392a4114f91c6ce9fface0284a403b0d7b2c7851640d2702565c62d  forma-all.css

package/dist/patterns/icon.html

@@ -0,0 +1 @@
+<ef-icon class="ef-component-tag"><span class="ef-icon" data-ef-icon="search"><svg xmlns="http://www.w3.org/2000/svg" class="ef-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="10.3" cy="10.3" r="6.2"/><path d="M15 15L20.5 20.5"/></svg></span></ef-icon>

package/docs/ICONS.md

@@ -0,0 +1,51 @@
+# Forma icons (foundation preview)
+
+The icon registry is in `icons/registry.json`, validated by `schemas/icon-registry.schema.json` and compiled by `tools/icons/build.mjs`. It now contains forty first-party outline icons, including the eight foundation icons: add, agent, close, edit, search, success, warning and workflow. The compiler and public catalog are implemented, but Forma Studio/Folio consumer integration and independent visual review remain open.
+
+## Build and validate
+
+```sh
+npm run icons:check
+npm run build
+npm pack --dry-run
+```
+
+The documentation site also publishes a complete categorized, copyable gallery at `/icons/` and one page per icon at `/icons/<name>/`. Each icon page shows the construction on the 24-unit grid, the meaning and when to use or avoid it, the reviewed sizes (16, 20, 24, 32 and 48px), the icon in every colour role including the inverse surface, forced-colour and print behaviour, seven copyable configurations (button with text, icon-only button, inline text, custom size, custom colour, meaningful image, decorative image), the package paths, the downloadable SVG, the release version and digest, an accessibility checklist and related icons. Page guidance lives in `catalog/icons.mjs`; geometry always comes from the compiled registry. The normal Forma build generates:
+
+- `dist/icons/<name>.svg`: static SVG for `<img>`, CSS or print use
+- `dist/icons/html/<name>.html`: pre-rendered decorative inline SVG with inert `<ef-icon>` authoring tag and `.ef-icon` presentation span
+- `dist/icons/registry.json`: metadata for static galleries, consumers and tools, stamped with `formaVersion` (the producing package release) and each icon's `svgSha256` so a consumer can verify that bundled geometry matches its pinned release
+
+The icon assets are part of the versioned `@echelon-foundry/design-system` tarball; the wildcard export path is `@echelon-foundry/design-system/icons/<name>.svg` and `.../icons/html/<name>.html`. Nothing fetches a CDN and no runtime JavaScript is required.
+
+## HTML usage
+
+Use the *generated* HTML snippet from `dist/icons/html/search.html`, rather than hand-copying path geometry. For an application button, put that snippet inside a real button that also carries an accessible name:
+
+```html
+<button type="button" aria-label="Search">
+  <!-- paste the version-pinned, generated decorative search snippet here -->
+</button>
+```
+
+Static image alternative, when the icon conveys meaning by itself:
+
+```html
+<img src="/assets/forma/icons/workflow.svg" alt="Workflow" width="24" height="24">
+```
+
+Use `alt=""` on an image that is purely decorative. The generated *inline HTML* SVG is intentionally `aria-hidden="true"`; never depend on it to label a button or convey status. A meaningful standalone inline SVG requires an explicit application-authored `role="img"` and a correct accessible name. Icon names are not translated accessible labels.
+
+Default size is `1.25em`. Set `--ef-icon-size: 1rem` or `2rem` on an icon's presentation span or ancestor. Icons inherit text color through `currentColor`; brands and skins must not rewrite the geometry. Avoid assigning only color or icons to communicate success, failure or warning.
+
+## Contribution rules
+
+1. Choose a stable lower-kebab-case ID and an appropriate semantic category.
+2. Add the icon's guidance (meaning, use for, avoid, example accessible name, related icons) to `catalog/icons.mjs`. The site build fails if any registry icon has no guidance or a related icon does not exist.
+3. Submit new source geometry in the registry (24-unit grid, 1.8-unit strokes, round caps and joins).
+4. Mark original art as `origin: original`. Third-party assets are currently disallowed by the compiler until provenance/source/license extension and review are implemented.
+5. Run `npm run icons:check`, `npm run build`, `npm run site:check` and `npm run release:check`.
+6. Review at 16, 20, 24, 32 CSS px; light/dark/brand; forced colors; 320px layout; and print.
+7. Never edit the generated `dist/icons` files, add scripts/filters/external hrefs, or make icons interactive themselves.
+
+See `requirements/ICON-SYSTEM.md` and `docs/decisions/ADR-2026-10-07-icon-foundation.md`. Additional work items own production catalog integration, comprehensive browser visual/a11y tests, Forma Studio and Folio consumers, and the next icon batch.

package/figma/component-contracts.json

@@ -730,6 +730,16 @@
         "status": "requires-published-figma-component"
       }
     },
+    {
+      "id": "icon",
+      "figmaName": "Forma / Icon",
+      "source": "patterns/icon.html",
+      "codeConnect": {
+        "id": "Forma/icon",
+        "nodeUrl": null,
+        "status": "requires-published-figma-component"
+      }
+    },
     {
       "id": "identifier",
       "figmaName": "Forma / Identifier",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/design-system",
-  "version": "0.4.1",
+  "version": "0.5.0-main.231.1",
   "private": false,
   "type": "module",
   "description": "Zero-runtime HTML and CSS design system for Echelon Foundry applications.",
@@ -28,7 +28,9 @@
     "./workflow/forma-workflow.schema.json": "./schemas/workflow/1.0/forma-workflow.schema.json",
     "./contracts/workflow-capabilities.json": "./contracts/workflow-capabilities.json",
     "./workflow/examples/*": "./examples/workflows/forma/workflows/*",
-    "./contracts/machine-operability.json": "./contracts/machine-operability.json"
+    "./contracts/machine-operability.json": "./contracts/machine-operability.json",
+    "./icons/registry.schema.json": "./schemas/icon-registry.schema.json",
+    "./icons/*": "./dist/icons/*"
   },
   "files": [
     "dist",
@@ -45,7 +47,9 @@
     "examples/workflows/fixtures.json",
     "docs/workflow",
     "contracts/machine-operability.json",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "schemas/icon-registry.schema.json",
+    "docs/ICONS.md"
   ],
   "scripts": {
     "clean": "node tools/clean.mjs",
@@ -58,9 +62,9 @@
     "test:runtime": "node --test tests/zero-runtime.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 test:tokens && npm run test:brands && npm run test:runtime && 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: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",
+    "site:test": "node --test tests/site-build.test.mjs tests/catalog-coverage.test.mjs tests/icon-docs.test.mjs",
     "site:check": "npm run site:build && npm run catalog:check && npm run site:test && npm run site:mobile",
     "site:mobile": "playwright test --config=playwright.site.config.mjs",
     "pack:verify": "npm run build && npm pack --dry-run",
@@ -75,7 +79,7 @@
     "test:marketing": "node --test tests/marketing-tokens.test.mjs tests/marketing-distribution.test.mjs tests/marketing-structure.test.mjs tests/site-css-policy.test.mjs",
     "example:install": "mkdir -p build/example && cp examples/echelon-marketing-site/forma.lock build/example/forma.lock && bash actions/install-presentation/install.sh --lock build/example/forma.lock --source dist/marketing --update --output examples/echelon-marketing-site/assets/forma",
     "policy:check": "dotnet run --project tools/SiteCssPolicy/SiteCssPolicy.fsproj --",
-    "release:check": "npm run build && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:css && npm run test:package && npm run test:machine && playwright test tests/browser/marketing.spec.mjs && npm run site:check",
+    "release:check": "npm run build && npm run icons:check && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:css && npm run test:package && npm run test:machine && playwright test tests/browser/marketing.spec.mjs && npm run site:check",
     "test:figma": "node --test tests/figma-contract.test.mjs",
     "catalog:check": "node tools/catalog/validate.mjs && node tools/catalog/inventory.mjs --check",
     "catalog:inventory": "node tools/catalog/inventory.mjs",
@@ -85,7 +89,8 @@
     "test:workflow-package": "node --test tests/workflow-package.test.mjs",
     "test:workflow-browser": "playwright test tests/browser/workflow-static.spec.mjs tests/browser/workflow-embed.spec.mjs",
     "workflow:check": "npm run workflow:test && npm run workflow:build && npm run test:workflow-package && npm run test:workflow-browser",
-    "test:machine": "playwright test tests/browser/machine-operability.spec.mjs"
+    "test:machine": "playwright test tests/browser/machine-operability.spec.mjs",
+    "icons:check": "node --test tests/icons.test.mjs"
   },
   "devDependencies": {
     "@axe-core/playwright": "4.13.0",

package/patterns/icon.html

@@ -0,0 +1 @@
+<ef-icon class="ef-component-tag"><span class="ef-icon" data-ef-icon="search"><svg xmlns="http://www.w3.org/2000/svg" class="ef-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="10.3" cy="10.3" r="6.2"/><path d="M15 15L20.5 20.5"/></svg></span></ef-icon>

package/schemas/icon-registry.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forma.echelonfoundry.com/schemas/icon-registry.schema.json",
+  "title": "Forma icon registry v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "grid",
+    "strokeWidth",
+    "linecap",
+    "linejoin",
+    "icons"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "grid": {
+      "const": 24
+    },
+    "strokeWidth": {
+      "const": 1.8
+    },
+    "linecap": {
+      "const": "round"
+    },
+    "linejoin": {
+      "const": "round"
+    },
+    "icons": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/icon"
+      }
+    }
+  },
+  "$defs": {
+    "icon": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "category",
+        "label",
+        "keywords",
+        "origin",
+        "shapes"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+        },
+        "category": {
+          "enum": [
+            "actions",
+            "navigation",
+            "status",
+            "workflow",
+            "diagnostics",
+            "documents",
+            "agents"
+          ]
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "keywords": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          }
+        },
+        "origin": {
+          "const": "original"
+        },
+        "shapes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": {
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "element",
+                  "d"
+                ],
+                "properties": {
+                  "element": {
+                    "const": "path"
+                  },
+                  "d": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1200
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "element",
+                  "cx",
+                  "cy",
+                  "r"
+                ],
+                "properties": {
+                  "element": {
+                    "const": "circle"
+                  },
+                  "cx": {
+                    "type": "number"
+                  },
+                  "cy": {
+                    "type": "number"
+                  },
+                  "r": {
+                    "type": "number",
+                    "exclusiveMinimum": 0
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "element",
+                  "x",
+                  "y",
+                  "width",
+                  "height"
+                ],
+                "properties": {
+                  "element": {
+                    "const": "rect"
+                  },
+                  "x": {
+                    "type": "number"
+                  },
+                  "y": {
+                    "type": "number"
+                  },
+                  "width": {
+                    "type": "number",
+                    "exclusiveMinimum": 0
+                  },
+                  "height": {
+                    "type": "number",
+                    "exclusiveMinimum": 0
+                  },
+                  "rx": {
+                    "type": "number",
+                    "minimum": 0
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}