@echelon-foundry/design-system 0.12.0 → 0.13.0-main.264.1

package/dist/marketing/forma-marketing.css

@@ -1,4 +1,4 @@
-/*! Forma 0.12.0 | forma-marketing.css | bundle echelon-marketing
+/*! Forma 0.13.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. */
 
@@ -902,6 +902,20 @@
     outline: 3px solid var(--ef-color-focus-gap, #f2efe7);
     outline-offset: 2px;
     box-shadow: 0 0 0 5px var(--ef-color-focus-ring, #171a18);
+    /* Focus scrolling brings the whole indicator into view, not only the
+       element's border box (LRP-001). Changes scroll position only. */
+    scroll-margin: 0.5rem;
+  }
+
+  /* Keyboard focus on a date or time control's own picker button leaves the
+     host input :focus-within but neither :focus nor :focus-visible
+     (Chromium), which painted no indicator at all (LRP-001). :not(:focus)
+     limits this to that case: pointer focus on the input itself (WebKit)
+     keeps the native behaviour. */
+  :where(input[type="date"], input[type="time"], input[type="datetime-local"], input[type="month"], input[type="week"]):focus-within:not(:focus) {
+    outline: 3px solid var(--ef-color-focus-gap, #f2efe7);
+    outline-offset: 2px;
+    box-shadow: 0 0 0 5px var(--ef-color-focus-ring, #171a18);
   }
 
   .ef-stack { display: flex; flex-direction: column; gap: var(--ef-stack-gap, var(--ef-primitive-spacing-4, 1rem)); }
@@ -919,6 +933,39 @@
     overflow-wrap: anywhere;
   }
 
+  /*
+   * Layout reliability (LRP-001, docs/reliability/layout-baseline.md).
+   * Forma containers that hold arbitrary application content pass
+   * overflow-wrap: break-word to that content by inheritance, so a long token
+   * in a span, strong, em, div or li breaks instead of escaping the card,
+   * dialog or field. break-word, unlike anywhere, leaves min-content sizes
+   * alone: a word that fits is never split, and auto-sized flex and grid
+   * items keep whole words. Inheritance never overrides a declared value:
+   * text elements above keep anywhere, character-grid runs keep normal, and
+   * white-space: pre or nowrap content (code blocks, truncating selects,
+   * scrollers) does not wrap.
+   */
+  :where(
+    .ef-surface, .ef-stack, .ef-cluster, .ef-actions, .ef-grid, .ef-responsive-grid,
+    .ef-rail, .ef-mosaic, .ef-priority-stack, .ef-focus-stage, .ef-sidebar, .ef-switcher, .ef-split-pane,
+    .ef-dialog, .ef-popover, .ef-menu, .ef-form, .ef-field, .ef-validation-summary, .ef-record-header
+  ) {
+    overflow-wrap: break-word;
+  }
+
+  /*
+   * A wrapping row's item can be no wider than the row (LRP-001), which also
+   * caps its automatic flex minimum, so a long label or an inline-block item
+   * cannot push the row past its container; the item's text then breaks
+   * inside it. Items keep their content size whenever it fits: nothing here
+   * shrinks a control below its label. Top-layer children (a dialog or
+   * popover authored inside the row) keep their own sizing. A full-bleed
+   * child with negative margins is capped at the row's width.
+   */
+  :where(.ef-cluster, .ef-actions) > :not(dialog, [popover]) {
+    max-inline-size: 100%;
+  }
+
   /* Action labels never split mid-word because their container allows it
      (a link button inherits the rule above; a button inherits it from a
      table cell). A single word wider than its container may still break
@@ -1305,6 +1352,23 @@
     overflow-wrap: anywhere;
   }
 
+  /*
+   * Marketing containment (MKT-CONTAIN, WI-0043). LRP-001 passes
+   * overflow-wrap: break-word to arbitrary content inside the application
+   * containers; marketing components hold the same kind of content (list
+   * items, spans and divs that the element rule above does not reach), so
+   * they pass it on too. break-word never splits a word that fits and leaves
+   * min-content sizes alone; declared values (badges, steps, code) win over
+   * inheritance. Found by the EDF site at 320px: list words escaped a card at
+   * 200% text and a release URL in a span escaped it at every width.
+   */
+  .ef-site :where(
+    .ef-hero, .ef-section-heading, .ef-card, .ef-facts, .ef-index, .ef-callout,
+    .ef-cta, .ef-split, .ef-doc, .ef-prose, .ef-statement, .ef-site-footer
+  ) {
+    overflow-wrap: break-word;
+  }
+
   .ef-site :where(hr) {
     margin-block: var(--ef-layout-section-space);
     border: 0;
@@ -1887,6 +1951,10 @@
 
   .ef-cta[data-ef-tone]:not([data-ef-tone="page"]) {
     padding: calc(var(--ef-layout-block-space) * 2);
+    /* Same cap as a toned .ef-section (ULI-L05): at 320px and 200% text the
+       uncapped inline padding left a 96px content box (MKT-CONTAIN). It
+       changes nothing at the default text size. */
+    padding-inline: min(calc(var(--ef-layout-block-space) * 2), 12.5vw);
     border-block-start: 0;
   }
 

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

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "forma": "0.12.0",
+  "forma": "0.13.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.12.0",
+  "releaseTag": "v0.13.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": "e945b2e9f5396108446be83c8b0af50b64487b5749fc35a05e3b8582090dbd5f",
+      "bytes": 96137,
+      "sha256": "08c70e579ad93f28d2dedf5d4c5e1b7d455773acff50b19a2a688f132123b9df",
       "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": "495b81a7dae75204ac9fcd2531754a2e0fa6e912009430d78d97d87807104402",
+      "sha256": "0b803cade4de294a2e15ac8a8482cb2448617a2558d70fc6542a4b3b9a357bf2",
       "sources": [
         "build/marketing/echelon-marketing.tokens.css",
         "themes/echelon/marketing.css"
@@ -32,8 +32,8 @@
     {
       "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": "f93946ab2401d3a65f10ce96bbea8c830ad1c239bcc412c8f7906dfba8f6616c",
+      "bytes": 102277,
+      "sha256": "d440c969a3defb5e8eb51043da8b66d3faa29094a429ece6a046deeea98377cb",
       "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": 342064,
-      "sha256": "8126a388b0563f6d7f40a84058035bfd6cd62e966c181ff3c055f530bc2cc32c",
+      "bytes": 346402,
+      "sha256": "0ba4ce2e6ef70b94000a725780d90e0061b312960265387bc3e2e06c34b92484",
       "sources": [
         "dist/all.css"
       ]

package/dist/marketing/forma-marketing.sha256

@@ -1,4 +1,4 @@
-e945b2e9f5396108446be83c8b0af50b64487b5749fc35a05e3b8582090dbd5f  forma-marketing.css
-495b81a7dae75204ac9fcd2531754a2e0fa6e912009430d78d97d87807104402  forma-marketing-theme-echelon.css
-f93946ab2401d3a65f10ce96bbea8c830ad1c239bcc412c8f7906dfba8f6616c  forma-echelon-marketing.css
-8126a388b0563f6d7f40a84058035bfd6cd62e966c181ff3c055f530bc2cc32c  forma-all.css
+08c70e579ad93f28d2dedf5d4c5e1b7d455773acff50b19a2a688f132123b9df  forma-marketing.css
+0b803cade4de294a2e15ac8a8482cb2448617a2558d70fc6542a4b3b9a357bf2  forma-marketing-theme-echelon.css
+d440c969a3defb5e8eb51043da8b66d3faa29094a429ece6a046deeea98377cb  forma-echelon-marketing.css
+0ba4ce2e6ef70b94000a725780d90e0061b312960265387bc3e2e06c34b92484  forma-all.css

package/dist/marketing.css

@@ -285,6 +285,23 @@
     overflow-wrap: anywhere;
   }
 
+  /*
+   * Marketing containment (MKT-CONTAIN, WI-0043). LRP-001 passes
+   * overflow-wrap: break-word to arbitrary content inside the application
+   * containers; marketing components hold the same kind of content (list
+   * items, spans and divs that the element rule above does not reach), so
+   * they pass it on too. break-word never splits a word that fits and leaves
+   * min-content sizes alone; declared values (badges, steps, code) win over
+   * inheritance. Found by the EDF site at 320px: list words escaped a card at
+   * 200% text and a release URL in a span escaped it at every width.
+   */
+  .ef-site :where(
+    .ef-hero, .ef-section-heading, .ef-card, .ef-facts, .ef-index, .ef-callout,
+    .ef-cta, .ef-split, .ef-doc, .ef-prose, .ef-statement, .ef-site-footer
+  ) {
+    overflow-wrap: break-word;
+  }
+
   .ef-site :where(hr) {
     margin-block: var(--ef-layout-section-space);
     border: 0;
@@ -866,6 +883,10 @@
 
   .ef-cta[data-ef-tone]:not([data-ef-tone="page"]) {
     padding: calc(var(--ef-layout-block-space) * 2);
+    /* Same cap as a toned .ef-section (ULI-L05): at 320px and 200% text the
+       uncapped inline padding left a 96px content box (MKT-CONTAIN). It
+       changes nothing at the default text size. */
+    padding-inline: min(calc(var(--ef-layout-block-space) * 2), 12.5vw);
     border-block-start: 0;
   }
 

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.12.0";
+export const FORMA_VERSION = "0.13.0";
 
 if (typeof window !== "undefined") registerEchelonRuntime("forma", { version: FORMA_VERSION }, window);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/design-system",
-  "version": "0.12.0",
+  "version": "0.13.0-main.264.1",
   "private": false,
   "type": "module",
   "description": "Zero-component-runtime HTML and CSS design system for Echelon Foundry applications.",
@@ -47,6 +47,8 @@
     "docs/MARKETING-SITES.md",
     "tokens/echelon.tokens.json",
     "tools/color-contract",
+    "tools/TokenValidator/*.fs",
+    "tools/TokenValidator/TokenValidator.fsproj",
     "contracts/color-contract.json",
     "docs/COLOR.md",
     "figma/component-contracts.json",
@@ -71,7 +73,8 @@
     "assets:build": "node tools/build-assets.mjs",
     "build": "npm run clean && npm run tokens:build && npm run brands:build && npm run color:build && npm run marketing:theme && npm run runtime:build && npm run assets:build && npm run marketing:build && npm run example:install",
     "runtime:build": "node tools/build-runtime.mjs",
-    "test:tokens": "node --test tests/token-compiler.test.mjs",
+    "test:tokens": "node --test tests/token-compiler.test.mjs tests/token-validator.test.mjs",
+    "tokens:validate": "dotnet run --project tools/TokenValidator/TokenValidator.fsproj -c Release -- --self",
     "test:browser": "playwright test",
     "test:a11y": "playwright test tests/browser/accessibility.spec.mjs",
     "test:runtime": "node --test tests/zero-runtime.test.mjs",
@@ -79,7 +82,7 @@
     "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: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",
+    "check": "npm run build && npm run icons:check && npm run tokens:validate && 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",
@@ -97,7 +100,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 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: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 tokens:validate && 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: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",

package/tools/TokenValidator/Css.fs

@@ -0,0 +1,171 @@
+/// A minimal, dependency-free CSS reader: enough structure to find custom
+/// property declarations and var() references with their selector, file and
+/// line. It is not a validating parser; malformed CSS still yields whatever
+/// declarations can be recognised.
+module Forma.TokenValidator.Css
+
+open System
+open System.Text
+
+type VarReference =
+    { Name: string
+      HasFallback: bool }
+
+type Declaration =
+    { File: string
+      Line: int
+      Selector: string
+      /// Every enclosing prelude, outermost first (at-rules and selectors).
+      Context: string
+      Property: string
+      Value: string
+      References: VarReference list }
+
+/// Replace comments with spaces and blank the contents of quoted strings,
+/// keeping their quotes and every newline, so offsets and line numbers still
+/// match the source. Braces, comment markers and var() inside a string
+/// (content: "}") are then inert.
+let normalise (text: string) =
+    let builder = StringBuilder(text.Length)
+    let blank (c: char) = if c = '\n' then '\n' else ' '
+    let rec go index (state: char option) inComment =
+        if index >= text.Length then ()
+        elif inComment then
+            if index + 1 < text.Length && text[index] = '*' && text[index + 1] = '/' then
+                builder.Append("  ") |> ignore
+                go (index + 2) None false
+            else
+                builder.Append(blank text[index]) |> ignore
+                go (index + 1) None true
+        else
+            match state with
+            | Some _ when text[index] = '\\' && index + 1 < text.Length ->
+                builder.Append(blank text[index]).Append(blank text[index + 1]) |> ignore
+                go (index + 2) state false
+            | Some quote when text[index] = quote ->
+                builder.Append(quote) |> ignore
+                go (index + 1) None false
+            | Some _ ->
+                builder.Append(blank text[index]) |> ignore
+                go (index + 1) state false
+            | None when index + 1 < text.Length && text[index] = '/' && text[index + 1] = '*' ->
+                builder.Append("  ") |> ignore
+                go (index + 2) None true
+            | None when text[index] = '"' || text[index] = '\'' ->
+                builder.Append(text[index]) |> ignore
+                go (index + 1) (Some text[index]) false
+            | None ->
+                builder.Append(text[index]) |> ignore
+                go (index + 1) None false
+    go 0 None false
+    builder.ToString()
+
+let private isNameChar (c: char) = Char.IsLetterOrDigit c || c = '-' || c = '_'
+
+/// Index of the parenthesis closing the one opened just before `start`.
+let private closingParen (value: string) start =
+    let rec go index depth =
+        if index >= value.Length then value.Length
+        else
+            match value[index] with
+            | '(' -> go (index + 1) (depth + 1)
+            | ')' when depth = 0 -> index
+            | ')' -> go (index + 1) (depth - 1)
+            | _ -> go (index + 1) depth
+    go start 0
+
+/// Every var(--name[, fallback]) in a value, including those nested in
+/// fallbacks, in source order.
+let rec references (value: string) : VarReference list =
+    let index = value.IndexOf("var(", StringComparison.OrdinalIgnoreCase)
+    if index < 0 then []
+    else
+        let start = index + 4
+        let close = closingParen value start
+        let inner = value.Substring(start, close - start)
+        let nameStart = inner.Length - inner.TrimStart().Length
+        let name = inner.Substring(nameStart) |> Seq.takeWhile isNameChar |> Seq.toArray |> String
+        let rest = inner.Substring(nameStart + name.Length).TrimStart()
+        let fallback = if rest.StartsWith(",") then rest.Substring(1) else ""
+        let own =
+            if name.StartsWith("--") then [ { Name = name; HasFallback = rest.StartsWith(",") } ] else []
+        own @ references fallback @ references (value.Substring(min value.Length (close + 1)))
+
+/// Offsets at which each line starts, for line lookup by binary search.
+let private lineStarts (text: string) =
+    Array.append [| 0 |] (text |> Seq.indexed |> Seq.filter (fun (_, c) -> c = '\n') |> Seq.map (fun (i, _) -> i + 1) |> Seq.toArray)
+
+let private lineAt (starts: int array) offset =
+    let found = Array.BinarySearch(starts, offset)
+    if found >= 0 then found + 1 else ~~~found
+
+/// Split a block body at top-level semicolons, keeping each piece's offset.
+let private pieces (body: string) (offset: int) =
+    let rec go index depth quote start acc =
+        if index >= body.Length then List.rev ((start, body.Substring(start)) :: acc)
+        else
+            let c = body[index]
+            match quote with
+            | Some q when c = q -> go (index + 1) depth None start acc
+            | Some _ -> go (index + 1) depth quote start acc
+            | None ->
+                match c with
+                | '"' | '\'' -> go (index + 1) depth (Some c) start acc
+                | '(' -> go (index + 1) (depth + 1) None start acc
+                | ')' -> go (index + 1) (max 0 (depth - 1)) None start acc
+                | ';' when depth = 0 -> go (index + 1) depth None (index + 1) ((start, body.Substring(start, index - start)) :: acc)
+                | _ -> go (index + 1) depth None start acc
+    go 0 0 None 0 [] |> List.map (fun (start, piece) -> offset + start, piece)
+
+/// Declarations of one file. Nested blocks (@media, @layer, nesting) are
+/// walked; a declaration's selector is the innermost enclosing prelude.
+let declarations (file: string) (source: string) : Declaration list =
+    let text = normalise source
+    let starts = lineStarts text
+    let declarationOf (stack: string list) (offset: int, piece: string) =
+        let selector = match stack with innermost :: _ -> innermost | [] -> ""
+        let colon = piece.IndexOf(':')
+        let property = if colon > 0 then piece.Substring(0, colon).Trim() else ""
+        if colon <= 0 || property.Length = 0 || property.Contains("{") || property.Contains("}") || property.StartsWith("@") then None
+        else
+            let value = piece.Substring(colon + 1).Trim()
+            let leading = piece.Length - piece.TrimStart().Length
+            Some
+                { File = file
+                  Line = lineAt starts (offset + leading)
+                  Selector = selector
+                  Context = stack |> List.rev |> String.concat " » "
+                  Property = property
+                  Value = value
+                  References = references value }
+    // Walk the text, splitting at braces. Text between braces at one level is
+    // either declarations (inside a block) or a prelude (before '{').
+    let rec walk index segmentStart stack acc =
+        if index >= text.Length then
+            let tail =
+                match stack with
+                | _ :: _ -> pieces (text.Substring(segmentStart)) segmentStart |> List.choose (declarationOf stack)
+                | [] -> []
+            List.rev acc @ tail
+        else
+            match text[index] with
+            | '{' ->
+                // The segment before '{' may hold declarations followed by a nested prelude.
+                let segment = text.Substring(segmentStart, index - segmentStart)
+                let lastSemicolon = segment.LastIndexOf(';')
+                let declared, prelude =
+                    if lastSemicolon >= 0 then segment.Substring(0, lastSemicolon + 1), segment.Substring(lastSemicolon + 1)
+                    else "", segment
+                let found =
+                    match stack with
+                    | _ :: _ when declared.Length > 0 -> pieces declared segmentStart |> List.choose (declarationOf stack)
+                    | _ -> []
+                walk (index + 1) (index + 1) (prelude.Trim() :: stack) (List.rev found @ acc)
+            | '}' ->
+                let found =
+                    match stack with
+                    | _ :: _ -> pieces (text.Substring(segmentStart, index - segmentStart)) segmentStart |> List.choose (declarationOf stack)
+                    | [] -> []
+                walk (index + 1) (index + 1) (match stack with _ :: rest -> rest | [] -> []) (List.rev found @ acc)
+            | _ -> walk (index + 1) segmentStart stack acc
+    walk 0 0 [] []

package/tools/TokenValidator/Program.fs

@@ -0,0 +1,104 @@
+module Forma.TokenValidator.Program
+
+open System
+open System.IO
+open System.Text.Json
+open Forma.TokenValidator.Validation
+
+let private usage =
+    """usage: TokenValidator [--forma DIR] [--json] (--self | PATH...)
+
+  --forma DIR  Forma root to validate against: an installed package
+               (node_modules/@echelon-foundry/design-system) or a built
+               checkout. Default: the current directory.
+  --self       Validate Forma itself: token sources (aliases, cycles, theme
+               completeness), brand manifests, and every var() in the built
+               stylesheets.
+  PATH...      Application CSS files or directories (searched for *.css,
+               skipping node_modules) to validate against that Forma version.
+  --json       Print findings as JSON.
+
+Exit status: 0 no errors, 1 errors found, 2 invalid arguments or unreadable input."""
+
+type private Options =
+    { Forma: string
+      Self: bool
+      Json: bool
+      Paths: string list }
+
+let rec private parse (options: Options) (args: string list) =
+    match args with
+    | [] -> Ok { options with Paths = List.rev options.Paths }
+    | "--forma" :: dir :: rest -> parse { options with Forma = dir } rest
+    | "--self" :: rest -> parse { options with Self = true } rest
+    | "--json" :: rest -> parse { options with Json = true } rest
+    | ("--help" | "-h") :: _ -> Error ""
+    | flag :: _ when flag.StartsWith("--") -> Error $"unknown option {flag}"
+    | path :: rest -> parse { options with Paths = path :: options.Paths } rest
+
+let private cssFiles (path: string) =
+    if Directory.Exists path then
+        Directory.EnumerateFiles(path, "*.css", SearchOption.AllDirectories)
+        |> Seq.filter (fun file -> not (file.Split(Path.DirectorySeparatorChar) |> Array.contains "node_modules"))
+        |> Seq.sort
+        |> Seq.toList
+    elif File.Exists path then [ path ]
+    else failwith $"no such file or directory: {path}"
+
+let private relative (file: string) =
+    if String.IsNullOrEmpty file then file else Path.GetRelativePath(Environment.CurrentDirectory, file)
+
+let private render json (findings: Finding list) =
+    if json then
+        let rows =
+            findings
+            |> List.map (fun f ->
+                dict [ "code", box f.Code
+                       "severity", box (match f.Severity with Blocking -> "error" | Advisory -> "warning")
+                       "file", box (relative f.File)
+                       "line", box f.Line
+                       "name", box f.Name
+                       "message", box f.Message ])
+        printfn "%s" (JsonSerializer.Serialize(rows, JsonSerializerOptions(WriteIndented = true)))
+    else
+        findings
+        |> List.iter (fun f ->
+            let location = if f.Line > 0 then $"{relative f.File}:{f.Line}" else relative f.File
+            let severity = match f.Severity with Blocking -> "error" | Advisory -> "warning"
+            printfn $"{location}: {severity} [{f.Code}] {f.Message}")
+
+[<EntryPoint>]
+let main argv =
+    match parse { Forma = "."; Self = false; Json = false; Paths = [] } (List.ofArray argv) with
+    | Error message ->
+        if message <> "" then eprintfn "%s" message
+        eprintfn "%s" usage
+        if message = "" then 0 else 2
+    | Ok options when not options.Self && options.Paths.IsEmpty ->
+        eprintfn "%s" usage
+        2
+    | Ok options ->
+        try
+            let root = Path.GetFullPath options.Forma
+            let registry = registryOf root
+            let selfFindings =
+                if options.Self then
+                    let tokens = validateTokens registry.Tokens
+                    let brands =
+                        let directory = Path.Combine(root, "brands")
+                        if Directory.Exists directory then
+                            Directory.EnumerateFiles(directory, "*.brand.json") |> Seq.sort |> Seq.toList |> List.collect validateBrand
+                        else []
+                    tokens @ brands @ validateFormaCss registry
+                else []
+            let appFindings =
+                options.Paths |> List.collect cssFiles |> declarationsOf |> validateCss registry
+            let findings = (selfFindings @ appFindings) |> List.distinct |> List.sortBy (fun f -> f.File, f.Line, f.Name, f.Code)
+            render options.Json findings
+            let errors = findings |> List.filter (fun f -> f.Severity = Blocking) |> List.length
+            if not options.Json then
+                eprintfn $"token validation: {errors} error(s); {registry.Defined.Count} defined Forma properties and {registry.Hooks.Count} documented inputs in {relative root}"
+            if errors > 0 then 1 else 0
+        with ex ->
+            eprintfn $"ERROR {ex.Message}"
+            2

package/tools/TokenValidator/TokenValidator.fsproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <AssemblyName>forma-token-validator</AssemblyName>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Css.fs" />
+    <Compile Include="Validation.fs" />
+    <Compile Include="Program.fs" />
+  </ItemGroup>
+</Project>