@wix/himalaya-cli 0.1540.0 → 0.1541.0

package/guides/himi-json-output.md

@@ -287,6 +287,16 @@ unresolved migration finding.
 - `topbar_coverage_failed`: a source top-bar control has no matching action
   with a non-empty `onTap.actionId` (exit 1).
 
+## `himi one-app validate-design` codes
+
+- `invalid_usage`: required options are missing or incompatible (exit 2).
+- `evidence_invalid`: the collected source evidence is missing or invalid (exit 1).
+- `tokens_unreadable`: the token file cannot be read, or `--fix` cannot safely write it (exit 1).
+- `design_mismatch`: a source value differs from the drawn target value (exit 1).
+- `design_unresolved`: `--record` was requested while a design value still needs an
+  adapted ledger row; no evidence is written (exit 1).
+- `record_failed`: `--record` could not safely write its private evidence files (exit 1).
+
 ## `himi one-app coverage` codes
 
 - `invalid_usage`: the mode or required paths are missing (exit 2).

package/guides/one-app-to-himi-app.md

@@ -151,6 +151,23 @@ Apply these interpretation rules:
   a feature to account for; they do not alone prove visibility or access for every
   visitor or member. Resolve those rules separately. This check is specific to this
   migration workflow; it does not change the behavior of `himi validate`.
+- Before publishing, run the migration-only design check:
+  `himi one-app validate-design --evidence-dir .himi/one-app --content .`.
+  It resolves the effective source theme with the reader the source app instance
+  actually uses, then compares the resolved primary, background and content colors
+  and each button's `borderRadius` and `outlineWidth` against the app's `tokens.json`.
+  Hex case and shorthand are normalized; an absent button token is compared with the
+  value the renderer draws (an outline only on `secondary`; a radius of `radius.pill`,
+  else 24), not called a difference. A variant without its own radius must draw the
+  source radius at every Button size. A descriptor's per-button `cornerRadius` overrides
+  the tokens and is not checked. `--fix` writes the mismatching source values into
+  `tokens.json` and pins the dark and high-contrast schemes to what they drew before,
+  because a missing scheme falls back to the light value. Rebuild after `--fix`.
+  The report names every theme pointer the check did not compare, including typography
+  kits and any button `uppercase`, which Himi tokens cannot carry; resolve those
+  explicitly rather than treating a pass as full design parity. A deliberate difference
+  is waived only by a `design` coverage row with status `adapted` that cites the user's
+  instruction and explains the change. This check compares values, not rendered screens.
 - For each configured Detailed header, import and call the shared
   `detailedHeader` builder from `@wix/himalaya/screens`. Do not recreate its
   component tree in the app. Resolve the source fallback and visibility rules
@@ -254,15 +271,17 @@ Run `himi one-app coverage init --evidence-dir .himi/one-app --content .` to
 create `ONE-APP-COVERAGE.json` from the verified source graph. After edits or a
 CLI upgrade, run `coverage sync` and review new rows; `coverage check` fails when
 the file is absent or source requirements have appeared, disappeared or changed.
-Rows cover source graph warnings as well as routes and controls. This is an
-inventory of migration obligations, not proof that their target actions work.
+Rows cover source graph warnings and app-wide design values as well as routes and
+controls. This is an inventory of migration obligations, not proof that their target
+actions work.
 
 Map each row to a target screen and, for interactions or top-bar controls, a
-target control. Set its `status` to `supported`, `adapted`, `conditional`, or
+target control. A `design` row is app-wide, so it needs no screen or control: it is
+satisfied by the design check instead. Set its `status` to `supported`, `adapted`, `conditional`, or
 `unresolved`. For an adaptation, cite the user's instruction and explain the
 change. Each resolved row needs a `verification` record using the required check
 ID for its kind (`route-walkthrough`, `visual-comparison`, `behavior-crawl`,
-`topbar-control`, `access-state`, or `source-resolution`), a safe relative path to
+`topbar-control`, `access-state`, `design-token`, or `source-resolution`), a safe relative path to
 a JSON check record, and the exact release payload SHA-256 in `releaseHash`.
 The JSON file's `checks[]` must contain a passed record with that requirement ID,
 check ID, release hash, target mapping, and a relative `artifact` path to the
@@ -270,6 +289,25 @@ actual screenshot, test output, or walkthrough record. Multiple rows may share
 one file, but each needs its own passed check record. Keep private evidence under
 `.himi/` so it is excluded from the app source archive.
 
+`design-token` evidence is the one kind nobody writes by hand. Run
+`himi one-app validate-design --evidence-dir .himi/one-app --content . --record
+--release-hash <64-hex-sha256>` after the release is built: it writes
+`.himi/one-app/design-report.json` and `.himi/one-app/design-checks.json`, with one
+passed record per matched or adapted design row, and refuses to write either file when
+the check does not pass or any design row remains unresolved. Point each `design` row's
+`verification` at the checks file. `--fix` writes only to a regular token file inside the
+content directory; read-only validation can inspect an external token path.
+The check also compares each idiom overlay selected by the app's statically readable policy
+against the source value. An active overlay
+that changes it needs a deliberate edit or an adapted ledger row that lists the overlay name in
+`adaptation.idioms` (for example, `["ios"]`); a base-token adaptation alone does not waive it.
+`--fix` repairs base tokens only.
+A row the check cannot compare — an `unresolved` one, such as a button `uppercase` —
+gets a record only once it is resolved as `adapted`, with the user's instruction and an
+explanation. An adaptation counts only while the ledger's `sourceHashes` match the
+collected evidence; after recollection, run `coverage sync` and decide again. `--record`
+refuses `--fix` in the same run: the release hash names the tokens as built.
+
 For example, one entry in the referenced JSON file is:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1540.0",
+  "version": "0.1541.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "a1d4dc831a852d303dab5ab6d7d7c2eea37f28a6f0c949a4d2c1ce6f"
+  "falconPackageHash": "77f49a0fa384b30d68adfb678fda491e11084dd3f66b62764b113aaf"
 }