[changeroa]

Summary

P1 from the HIG audit direction report: a dated, paraphrased extraction of Apple Human Interface Guidelines principles, published as a governed Platform Guides leaf plus a machine-readable record.

• platform-guides/hig-universal-principles.json: 187 principles from a walk of the HIG documentation data (Foundations, Patterns, Components including every page in its eight groups, Inputs, Technologies). Each principle has a stable id (hig.<section>.<page>.<slug>), a paraphrased statement, a source URL, a class (universal 147, adapt 34, apple-specific 6) with a reason, WCAG 2.2 success criteria, a Material 3 counterpart, a WAI-ARIA APG pattern where relevant, a verification question, and reviewed_on: 2026-10-19.
• The record also inventories all 149 walked pages: 95 extracted, 8 covered (each with a covered_by principle id), and 46 excluded (each with a reason, such as Apple hardware or a system surface with no web default). Getting Started is recorded as out of scope.
• platform-guides/hig-universal-principles.md: the human guide (boundary, method, classification rules, audit procedure, and per-section principle tables), registered like its neighbors.
• text_policy: paraphrase_and_link_only. No HIG prose is copied. Every statement and verification question was checked mechanically against the full text of all 149 fetched HIG pages and has no 7-word overlap; the few 6-word overlaps were reworded unless they were generic phrases. The apple-interaction.md no-imitation boundary is followed: Apple materials, system fonts, the symbol set, the macOS menu bar, and payment marks are apple-specific do-not-imitate checks, never web defaults.
• All 50 WCAG anchors and all APG URLs were fetched and confirmed. The Material 3 URLs were confirmed in a headless browser, because m3.material.io is a single-page app that answers 200 for any path.

Validator, test, and freshness

• scripts/validate-hig-principles.mjs checks the JSON and the guide together. It fails on missing or unknown fields, unknown classes, duplicate or malformed ids, unknown WCAG/Material 3/APG keys, unused dictionary entries, source URLs that don't match the page, inventory pages with no principle or disposition, dangling covered_by links, invalid dates, and principle ids missing from the guide.
• scripts/test-validate-hig-principles.mjs proves the failures with committed fixtures in tests/fixtures/hig-principles/: missing-field.json must produce exactly field_missing, unknown-class.json exactly class_unknown, duplicate-id.json exactly id_duplicate, and valid-minimal.json must pass. Five in-memory mutations cover guide drift, dangling covered_by, unknown WCAG criteria, unextracted pages, and source URL mismatches.
• Evidence freshness: scripts/audit-evidence-freshness.mjs gains a platform_principle_extraction record kind. Its explicit review_by (2027-04-19) is the threshold, with review_due semantics; the record's reviewed_on is reported as verified_at. Records with a missing or invalid review_by, or with a principle reviewed_on later than the record's, are rejected. scripts/test-audit-evidence-freshness.mjs adds 5 cases (fresh, expiring, review_due blocking, missing review_by, future principle date), and .github/workflows/evidence-freshness.yml now audits the record.
• New workflow .github/workflows/hig-principles.yml runs the validator and self-test on every PR. validate.yml is byte-sealed by the lifecycle sentinel calibration, so the steps could not be added there.

Registration and generated files

• Registration: DOMAINS.md page manifest, scripts/validate-domains.mjs and its test, platform-guides/index.md, a GOVERNANCE.md source-of-truth row, the admission policy (with its VersionID re-bound) plus schema and test counts (195 to 196) and the sealed path hash, the package.json files entry for the guide and the validate:hig-principles and test:hig-principles scripts, and search-eval questions hig01, hig02 (must-pass) and hig03 (mismatch).
• Regenerated rather than hand-merged after rebasing onto e776481 (Add audit ledger schema and stylegallery audit status (P5) #71 audit ledger and feat(expression): AI-slop UI anti-pattern catalog (P3) #70 anti-pattern catalog): material-registry.json, search-embeddings.json (196 documents), and the lifecycle a2a and ag-ui extension inventories via generateProtocolExtensionInventory. This follows the precedent in c4880d9. The inventories bind package.json, GOVERNANCE.md, and the package test.

Governance classification

• Domain: Platform Guides. This is a new experimental, local-provenance leaf (provenance_kind: local) that follows the apple-interaction.md boundary. The JSON is its manual source record; it is not a generated artifact.
• No Layout dependency: nothing enters layout/**, patterns/**, scripts/pattern-data.mjs, or CATALOG.md. No Expression or showcase changes.
• Shared infrastructure touched only as registration requires: admission policy and counts, regenerated material registry and embeddings, regenerated lifecycle extension inventories (inventory blocks only; no lifecycle state, owner, deadline, or disposition changed), and the freshness auditor plus its workflow.
• No version bump and no log.md entry.

Handoff

consumer_reference: not_applicable: this change adds platform-guidance knowledge and validators; it selects and changes no consumer-reference record.

Design-terminology reliance: none. No term identifiers or relation types are used.

Before / After

stylegallery search (hybrid, --paths-only --limit 5). Before is a clean export of origin/main at a820e4c (search results are unaffected by #70); after is this branch.

$ stylegallery search "Which Apple HIG principles apply to the web and which are Apple-specific?" --paths-only --limit 5
before: platform-guides/apple-interaction.md, platform-guides/adaptive-navigation.md, platform-guides/input-and-focus.md, platform-guides/preferences-and-accessibility.md, design-terminology/interaction-semantics.md
after:  platform-guides/hig-universal-principles.md, platform-guides/index.md, platform-guides/apple-interaction.md, platform-guides/adaptive-navigation.md, platform-guides/input-and-focus.md

$ stylegallery search "HIG target size WCAG 2.5.8 universal" --paths-only --limit 5
before: platform-guides/input-and-focus.md, expression/techniques/webgl-hero.md, quality/audit/README.md, design-engineering/evidence-patterns/dark-mode-contrast.md, motion/accessible-motion.md
after:  platform-guides/hig-universal-principles.md, platform-guides/index.md, platform-guides/input-and-focus.md, expression/techniques/webgl-hero.md, design-engineering/evidence-patterns/dark-mode-contrast.md

$ stylegallery read platform-guides/hig-universal-principles.md --outline
before: ok=false (read_reference_not_found)
after:  ok=true "Apple HIG Universal Principles Extraction" - Repository Boundary, Reusable Method, Principles, Opinionated Guidance, Platform-Specific Guidance, Unsupported Absolutes, Verification Contract, Source, License, And Attribution, IA Navigation

$ node scripts/validate-hig-principles.mjs
before: (script absent)
after:  ok: 187 HIG principles across 149 source pages

Search gate after (hybrid): must-pass 37/37 and eval:search exits 0. The new hig01, hig02, and hig03 questions all hit.

Verification (local, after rebase onto e776481)

All 123 commands passed: every command in the main validate.yml job, the search-eval, compiler, registrar, state-management, and story-examples workflow commands, bun run validate, bun run test, bun run test:audit, bun run validate:hig-principles, bun run test:hig-principles, bun run eval:search, and an advisory freshness audit of both records.