Merge pull request #73 from changeroa/feat/audit-p1-hig-principles

Add HIG universal principles extraction (P1)

Author: changeroa

.github/workflows/evidence-freshness.yml

@@ -42,6 +42,7 @@ jobs:
           set +e
           node scripts/audit-evidence-freshness.mjs \
             --record consumer-reference/baselines/calibration.json \
+            --record platform-guides/hig-universal-principles.json \
             --as-of "$as_of" \
             --mode advisory \
             --json > evidence-freshness-report.json

.github/workflows/hig-principles.yml

@@ -0,0 +1,28 @@
+name: HIG principles extraction
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  hig-principles:
+    name: HIG principles record, guide, and freshness contracts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.14
+      - run: bun install --frozen-lockfile --ignore-scripts
+      - run: bun run validate:hig-principles
+      - run: bun run test:hig-principles

DOMAINS.md

@@ -28,7 +28,7 @@ This manifest is the source of truth for top-level StyleGallery domains. A domai
 | Layout | `layout/index.md` | Existing `GUIDE.md`, Layout-specific `guides/*.md`, and `recipes/*.md`; generated `patterns/**/*.md` and `CATALOG.md` remain at current paths. Shared `quality/**/*.md` infrastructure governs every domain without becoming a Layout leaf. |
 | Motion | `motion/index.md` | `motion/vocabulary.md`, `motion/review-workflow.md`, `motion/practice-reference.md`, `motion/decision-tree.md`, `motion/motion-brief.md`, `motion/interaction-recipes.md`, `motion/observed-choreography.md`, `motion/accessible-motion.md`, `motion/interruption-and-retargeting.md`, `motion/rendering-and-performance.md`, `motion/techniques/scroll-choreography.md`, `motion/techniques/kinetic-type.md` |
 | Design Engineering | `design-engineering/index.md` | `design-engineering/interface-craft.md`, `design-engineering/consumer-migration-readiness.md`, `design-engineering/reference-profiles/index.md`, `design-engineering/reference-profiles/governed-local/index.md`, `design-engineering/reference-profiles/external-adaptation/index.md`, `design-engineering/decision-tree.md`, `design-engineering/component-contract.md`, `design-engineering/worked-examples.md`, `design-engineering/state-management/decision-tree.md`, `design-engineering/state-management/index.md`, `design-engineering/state-management/patterns/derived-state.md`, `design-engineering/state-management/patterns/draft-and-baseline.md`, `design-engineering/state-management/patterns/id-selection.md`, `design-engineering/state-management/patterns/identity-reset.md`, `design-engineering/state-management/patterns/latest-request-wins.md`, `design-engineering/state-management/patterns/optimistic-overlay.md`, `design-engineering/state-management/patterns/single-flight.md`, `design-engineering/state-management/patterns/single-owner.md`, `design-engineering/state-management/patterns/submitted-snapshot.md`, `design-engineering/state-management/patterns/unsaved-navigation.md`, `design-engineering/state-management/patterns/url-state.md`, `design-engineering/state-management/patterns/versioned-restore.md`, `design-engineering/state-management/recipes/delete-undo.md`, `design-engineering/state-management/recipes/index.md`, `design-engineering/state-management/recipes/multi-step-form.md`, `design-engineering/state-management/recipes/search-detail.md`, `design-engineering/state-management/recipes/settings-save.md`, `design-engineering/state-management/state-brief.md`, `design-engineering/state-management/verification.md`, `design-engineering/native-interaction-contracts.md`, `design-engineering/text-input-and-internationalization.md`, `design-engineering/loading-and-feedback.md`, `design-engineering/evidence-patterns/autocomplete.md`, `design-engineering/evidence-patterns/bottom-navigation.md`, `design-engineering/evidence-patterns/breadcrumbs.md`, `design-engineering/evidence-patterns/dark-mode-contrast.md`, `design-engineering/evidence-patterns/data-tables.md`, `design-engineering/evidence-patterns/empty-states.md`, `design-engineering/evidence-patterns/error-recovery.md`, `design-engineering/evidence-patterns/faceted-filters.md`, `design-engineering/evidence-patterns/form-labels.md`, `design-engineering/evidence-patterns/index.md`, `design-engineering/evidence-patterns/inline-validation.md`, `design-engineering/evidence-patterns/input-masks.md`, `design-engineering/evidence-patterns/tabs-and-segmented-controls.md` |
-| Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md`, `platform-guides/adaptation-workflow.md`, `platform-guides/android-interaction.md`, `platform-guides/windows-interaction.md`, `platform-guides/compatibility-matrix.md`, `platform-guides/adaptive-navigation.md`, `platform-guides/preferences-and-accessibility.md`, `platform-guides/input-and-focus.md` |
+| Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md`, `platform-guides/adaptation-workflow.md`, `platform-guides/android-interaction.md`, `platform-guides/windows-interaction.md`, `platform-guides/compatibility-matrix.md`, `platform-guides/adaptive-navigation.md`, `platform-guides/preferences-and-accessibility.md`, `platform-guides/input-and-focus.md`, `platform-guides/hig-universal-principles.md` |
 | Design Terminology | `design-terminology/index.md` | `design-terminology/source-kinds.md`, `design-terminology/source-vocabularies.md`, `design-terminology/concept-families.md`, `design-terminology/relation-types.md`, `design-terminology/conflict-cases.md`, `design-terminology/comparison-workflow.md`, `design-terminology/token-semantics.md`, `design-terminology/interaction-semantics.md`, `design-terminology/typography-semantics.md` |
 | Expression | `expression/index.md` | `expression/direction-brief.md`, `expression/brand-studies.md`, `expression/directions/nocturne-editorial.md`, `expression/directions/warm-print.md`, `expression/techniques/gradient-atmosphere.md`, `expression/techniques/grain-and-texture.md`, `expression/techniques/webgl-hero.md`, `expression/directions/fintech-clarity.md`, `expression/directions/hardware-catalogue.md`, `expression/directions/developer-tool.md`, `expression/directions/korean-service.md`, `expression/techniques/drawn-products.md`, `expression/techniques/live-product-demos.md`, `expression/techniques/canvas-3d.md`, `expression/study-atlas.md`, `expression/measured-benchmarks.md`, `expression/techniques/image-weight.md`, `expression/techniques/display-type-calibration.md`, `expression/techniques/surface-detail.md`, `expression/anti-patterns.md` |
 

GOVERNANCE.md

@@ -41,6 +41,7 @@ Use this file before editing repository documentation. It names which file is au
 | Motion domain guidance | `motion/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Motion domain owner |
 | Design Engineering domain guidance | `design-engineering/*.md`, `design-engineering/state-management/**/*.md`, `design-engineering/evidence-patterns/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Design Engineering domain owner |
 | Platform Guides domain guidance | `platform-guides/*.md` | Manual | None | `experimental` | Platform version, upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Platform Guides domain owner |
+| HIG universal principles extraction | `platform-guides/hig-universal-principles.json` with its manual guide `platform-guides/hig-universal-principles.md` | Manual, paraphrase-and-link only | None | `experimental` dated extraction | `review_by` deadline, HIG index page added, removed, or renamed, cited WCAG/Material 3/APG change, or audit misclassification. | `scripts/validate-hig-principles.mjs`, `scripts/test-validate-hig-principles.mjs`, `scripts/audit-evidence-freshness.mjs` | Platform Guides domain owner with Validation owner |
 | Design Terminology domain guidance | `design-terminology/*.md` | Manual; term and relation tables remain authoring sources | None | `experimental` | Source-kind, source-vocabulary, concept-family, relation-model, or conflict-case changes. | `scripts/validate-domains.mjs`, `scripts/validate-design-terminology.mjs` | Design Terminology domain owner |
 | Expression domain guidance | `expression/**/*.md` | Manual | None | `experimental` | Direction value, technique code, brand-study policy, or guidance changes. | `scripts/validate-domains.mjs` | Expression domain owner |
 | Expression anti-pattern catalog | `expression/anti-patterns.json`, `expression/anti-patterns.md` | Manual | None | `experimental` | Benchmark value, Showcase QA floor, entry, or detection-rule changes. | `scripts/validate-anti-patterns.mjs`, `scripts/test-validate-anti-patterns.mjs` | Expression domain owner with Validation owner |

consumer-reference/agent-native/v2/admission-policy.json

@@ -769,6 +769,11 @@
       "domain": "platform-guides",
       "lifecycle": "experimental"
     },
+    {
+      "repository_path": "platform-guides/hig-universal-principles.md",
+      "domain": "platform-guides",
+      "lifecycle": "experimental"
+    },
     {
       "repository_path": "platform-guides/index.md",
       "domain": "platform-guides",
@@ -1057,5 +1062,5 @@
       "code": "material_path_internal_excluded"
     }
   ],
-  "version_id": "sg:policy/material-admission-v2@sha256:d3a7ac528239965bddc336917239158b43a8e504f004f374789346f1feb86d5e"
+  "version_id": "sg:policy/material-admission-v2@sha256:f0f5758d8da48a15861f3cadc7e1cb437d59fecc71fdf8d9991466776cc9ff20"
 }

consumer-reference/agent-native/v2/material-registry.json

@@ -13,8 +13,8 @@
     "media_type": { "const": "text/markdown" },
     "allowed_materials": {
       "type": "array",
-      "minItems": 195,
-      "maxItems": 195,
+      "minItems": 196,
+      "maxItems": 196,
       "items": {
         "type": "object",
         "additionalProperties": false,

consumer-reference/agent-native/v2/schema/admission-policy.schema.json

@@ -629,9 +629,13 @@
    "text_sha256": "53e6463f348140821f64cc8fccd3816ada2c2aabb181835bd18f3d3aa87600d9",
    "vector": "9vv7/v3+Bf//BQH//wH/BAYEBgD8+wT9BgsC/ALm/QL/Av4A+/4BAQEIBQn9+/sD9/4B//0DAQcGCAUGBP7zCQb//QD+AvYF/gIJAAMCAPwAAvsDBP//AwEC+gIE/Pj8A/z+Kf4G/gn/+P36AgUB/Qb8//v+BQb4/gAE/fwABAUFBAr99PoJBAb//AT++wsC9xT/Av4ABwn6AvsGAv/2B/39+wkD8QEJBAP8AgL9+v/yAwH/CPP1AQED+wAI/P7/Agv9+QAA/QAGCfYA/wX9+QMC9wb7AAD7AQEECP0JANYA+gf7+v/9/gEKAgEE/Pj7/f78/AX9+gMADQABAAMGAPcABwL2Afz9BQD0+/4A+/4HBv/+BvwE/v8B+PsABfkF/wQB/wABCQX8CwP9//39AwUEAwUBBfYB/wH//PcHAuD/Awb0+wP2+fv7CQb+BQMU/QH3A/8WAP79//4FAP74CQUBAv0KAAD+Avj9CwL8//z7AvX+/gMDAQL++woHBwQC"
   },
+  "platform-guides/hig-universal-principles.md": {
+   "text_sha256": "a1652689b494704381bef57f767bb7ad5861e0763d85825be974337fe66bba6f",
+   "vector": "+AcA/QL9Bf78BAQA/fwCAwMBAgIKAf37BAf/+gTm+wMDAQAB/gIDBAEFAwQAAf389QIGCAEJAgYGBgQIAf7wCgYCAfwBAP8C//8C/Qj8AP/9BwD+CAb8+gP++fgB+vj/BP0AK/sF/gQH/QD+A//+AQX7BwH4BQv4+AIF+wABAP8O/QkD9fsCAwQCAgL9//4D+BL8B/kA/wj+AfkJCAL7Av76/A8D7wEGAgX9AQUAAgD4AgEDBfX3/QgA/f4MBAAE/gwCAP4C//kGBfv7AQQB9wP99gAABAP8BQX8BPv++db+/QD5/gT//wAKBP0D+/8GAPkBAAf6+QQADgEF/f4BAvEBBP3//fb6B/73Av789P79BgL+AvsB+f3/+P8DAvr+Af8F/vz6BwL4AQP+/ff8AAcHBAQEBvYA/QAA+v4JBOL9AAr3/gP0//72BQX3Av8N/gH5AQMX/AD7AP8CAAT9BQYHAQD8Af//BPX+A/n+//37AfgA/QD+BQX6/QQNAAoH"
+  },
   "platform-guides/index.md": {
-   "text_sha256": "ebb90497294fab433fb6c1c1ab33270e7622d3535d4c33917aaf1289b6070d2b",
-   "vector": "9fgB/QAAAQL9/v0BAvoE/wL9AfwB/AT/AAoB/f/p+wP+BP3+/AAABQQFAQX//PoA9vsB/v8D+wIECgUEAfzxCgQF/fv///8GAgYDAQQCA/v+BPz9AwABBwQB+foE/fgCAPr8MgAB/gMB/AL9AAv/AAL+BP0E/wj4/QIE+//9AgEHAAsD8wIFAgAAAwX+/Av/+g8BBfj/CQn/A/sDAAT2AP/8/QsB8P0JAAL9/fwCAP3wAQIDB/v2AQL/+v0HBfv9/wUAAAH9/f0HBPcB/QH6+g4B9wL+BP75BAUACPkC+9f/+wT++QX+/v4K/PkF/f4C+wD7+QUA+P4DDwID/QULAPgBCQD2Avz/B//3+//8+vsF/AEA//UA/AIE/gABBPgF/gMBAAD7Bf79BwcBBPsABAQJBgIEA/cH+v4A/PUIA98CCAj5AATz/v4ABAL8AwAS/QAAAgIZ/PwBBgEGAgD5CwgBAfwH/gL+BfwCCQH//v34/vr9AQD/CPv9/AsGBwED"
+   "text_sha256": "dfc71a40ce833efdc429ad3ce996037d76744e3a9a22ddd2823eda8edd68621e",
+   "vector": "9fsC/QH+AQH9//0AAPkD/gP8AfwB/AP/AwkA/f/n+wL/Bf38/f4BAwUGAQX/+/n/9vwB//8D/AQECgUGAf3xCgQF/vsB/wAFAgUEAAcBA/sABf7+BQABBAUA+fsD+/cDAfn6MgAD/gQC+wD+Agr//wT8BP8DAAn5+wIE+wH9AgAI/wsD8/8FAgECBAb7/QsB+RAABvj/BwYAAvsDAAX2AP79/Q3+8f8JAAT9/vwBAfzxAQACB/r3/wQA+v0HBPr//wcB/wH///wHBfgA/QX89wz/+AT+BQH5Awj9CfkA+tb9/AL++gb9/v8L/fgF/f4A/gD8/Af/9/4CDwEF/gQHA/gBCQD6Avv+B/33/gH6+/0C/gL9APcA+gED/QEBBfsE/gQDAAD7A/38BwcBAfr/BAUJBgIEBPcF+///+/UIAuAABgr3/wPz/v0ABAT5AgAQ/QAAAQIZ+/wBAwEEAQH7CggCAfwDAAL/BPwACf38Af74/fr+AP/9Cf78+wkHBgID"
   },
   "platform-guides/input-and-focus.md": {
    "text_sha256": "0412e61fdcfefe0d78aa3a59eb74e056abfa90c539859e27049ca9151a65d21e",

consumer-reference/agent-native/v2/search-embeddings.json

@@ -94,8 +94,8 @@
         "scripts/test-lifecycle-disposition.mjs",
         "scripts/validate-lifecycle-disposition.mjs"
       ],
-      "scanned_file_count": 631,
-      "scanned_paths_content_id": "sha256:2a2d852256399b0dd65d4abe601de756d82014dfe3cc005fa77550fe3e1f1f69"
+      "scanned_file_count": 640,
+      "scanned_paths_content_id": "sha256:63a7df1af982ff3599fa3d8f1117e79846dd90a50b81ece3b61549507b6c38d8"
     },
     "implementation": {
       "path": "scripts/agent-native/v2/extensions/a2a-projection.mjs",
@@ -145,13 +145,13 @@
         "role": "repository_reference",
         "lines": {
           "start": 1,
-          "end": 371
+          "end": 374
         },
-        "file_sha256": "d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
-        "content_id": "sha256:d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
+        "file_sha256": "95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
+        "content_id": "sha256:95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
         "reference_lines": [
-          245,
-          261
+          246,
+          262
         ],
         "reference_kinds": [
           "forwarder_path",
@@ -281,8 +281,8 @@
           "start": 1,
           "end": 300
         },
-        "file_sha256": "1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
-        "content_id": "sha256:1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
+        "file_sha256": "0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
+        "content_id": "sha256:0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
         "reference_lines": [
           54
         ],
@@ -391,8 +391,8 @@
           "start": 1,
           "end": 300
         },
-        "file_sha256": "1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
-        "content_id": "sha256:1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c"
+        "file_sha256": "0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
+        "content_id": "sha256:0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38"
       }
     ],
     "docs_and_registry": [
@@ -432,10 +432,10 @@
       "role": "installed_package_exposure",
       "lines": {
         "start": 1,
-        "end": 371
+        "end": 374
       },
-      "file_sha256": "d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
-      "content_id": "sha256:d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588"
+      "file_sha256": "95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
+      "content_id": "sha256:95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b"
     },
     "forwarding": {
       "path": "scripts/agent-native/a2a-projection.mjs",

consumer-reference/policies/lifecycle-a2a-extension.json

@@ -94,8 +94,8 @@
         "scripts/test-lifecycle-disposition.mjs",
         "scripts/validate-lifecycle-disposition.mjs"
       ],
-      "scanned_file_count": 631,
-      "scanned_paths_content_id": "sha256:2a2d852256399b0dd65d4abe601de756d82014dfe3cc005fa77550fe3e1f1f69"
+      "scanned_file_count": 640,
+      "scanned_paths_content_id": "sha256:63a7df1af982ff3599fa3d8f1117e79846dd90a50b81ece3b61549507b6c38d8"
     },
     "implementation": {
       "path": "scripts/agent-native/v2/extensions/agui-projection.mjs",
@@ -129,14 +129,14 @@
         "role": "repository_reference",
         "lines": {
           "start": 1,
-          "end": 234
+          "end": 235
         },
-        "file_sha256": "ab886bd4132283a8b1075d786789b62c10ec350eb5bb2a62df6385e1d796dc78",
-        "content_id": "sha256:ab886bd4132283a8b1075d786789b62c10ec350eb5bb2a62df6385e1d796dc78",
+        "file_sha256": "87dafd4ffbe53978ef16edd75834ff6c95ce31025a40445132b6b03eeaed3902",
+        "content_id": "sha256:87dafd4ffbe53978ef16edd75834ff6c95ce31025a40445132b6b03eeaed3902",
         "reference_lines": [
           28,
-          91,
-          93
+          92,
+          94
         ],
         "reference_kinds": [
           "documentation_reference"
@@ -203,13 +203,13 @@
         "role": "repository_reference",
         "lines": {
           "start": 1,
-          "end": 371
+          "end": 374
         },
-        "file_sha256": "d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
-        "content_id": "sha256:d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
+        "file_sha256": "95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
+        "content_id": "sha256:95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
         "reference_lines": [
-          246,
-          262
+          247,
+          263
         ],
         "reference_kinds": [
           "forwarder_path",
@@ -329,8 +329,8 @@
           "start": 1,
           "end": 300
         },
-        "file_sha256": "1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
-        "content_id": "sha256:1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
+        "file_sha256": "0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
+        "content_id": "sha256:0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
         "reference_lines": [
           55
         ],
@@ -438,8 +438,8 @@
           "start": 1,
           "end": 300
         },
-        "file_sha256": "1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c",
-        "content_id": "sha256:1a3ac4dd22ac0875f8206de0b7aefb12f9433d0f6ab7b43f61a831a07328034c"
+        "file_sha256": "0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38",
+        "content_id": "sha256:0c561fe9dc5ee04f3f5b3abaa2c8b782bd6ac57e18cda5b770ae1eef73234e38"
       }
     ],
     "docs_and_registry": [
@@ -479,10 +479,10 @@
       "role": "installed_package_exposure",
       "lines": {
         "start": 1,
-        "end": 371
+        "end": 374
       },
-      "file_sha256": "d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588",
-      "content_id": "sha256:d93f49cff874bb809af8e73f7e08a75b37ea0ddd45a897f1673d8eb6c1941588"
+      "file_sha256": "95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b",
+      "content_id": "sha256:95939c914a4861896dc70b156f70d9958e382afe6016e5f30d8d9f18b893533b"
     },
     "forwarding": {
       "path": "scripts/agent-native/agui-projection.mjs",