@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.6

package/design-system/knowledge/v3/sources.json

@@ -0,0 +1,425 @@
+{
+  "schemaVersion": 1,
+  "researchDate": "2026-09-28",
+  "status": "research-only; implementation and comparative trials pending",
+  "sources": [
+    {
+      "id": "S01",
+      "publisher": "Every Layout",
+      "title": "Composition",
+      "url": "https://every-layout.dev/rudiments/composition/",
+      "evidenceClass": "practitioner-teaching",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Layout can be composed from small responsibilities without giving every component a fixed complete design.",
+      "application": "Use relational composition as an authoring method; implement original examples.",
+      "limitation": "This is teaching, not a controlled comparison of Vitris output.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S02",
+      "publisher": "Nielsen Norman Group",
+      "title": "5 Principles of Visual Design in UX",
+      "url": "https://www.nngroup.com/articles/principles-visual-design/",
+      "evidenceClass": "usability-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Scale, hierarchy, balance, contrast and grouping shape how visual information is understood.",
+      "application": "Teach emphasis and relationships rather than style labels.",
+      "limitation": "Does not prescribe a universal page composition.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S03",
+      "publisher": "Nielsen Norman Group",
+      "title": "Proximity Principle in Visual Design",
+      "url": "https://www.nngroup.com/articles/gestalt-proximity/",
+      "evidenceClass": "usability-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Distance communicates grouping; responsive changes can alter perceived relationships.",
+      "application": "Check that labels, captions, proof and actions remain associated.",
+      "limitation": "Proximity is one cue; it does not replace semantic markup.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S04",
+      "publisher": "IBM",
+      "title": "Layout: Tips and techniques",
+      "url": "https://www.ibm.com/design/language/layout/tips-and-techniques/",
+      "evidenceClass": "first-party-design-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "IBM describes structural and editorial rhythm, repetition, contrast and asymmetry within its own identity.",
+      "application": "Teach relationships across a page; retain deliberate repeated lists.",
+      "limitation": "Do not import IBM's preference against symmetry as a Vitris rule.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S05",
+      "publisher": "IBM",
+      "title": "2x Grid",
+      "url": "https://www.ibm.com/design/language/2x-grid/",
+      "evidenceClass": "first-party-design-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-text-extract",
+      "finding": "A shared spatial framework relates type, spacing and layout while allowing different applications.",
+      "application": "Teach site-specific alignment systems and proportions.",
+      "limitation": "IBM's exact grid and spacing units are brand choices, not universal requirements.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S06",
+      "publisher": "Google Design",
+      "title": "Better, Easier, Emotional UX",
+      "url": "https://design.google/library/expressive-material-design-google-research",
+      "evidenceClass": "first-party-research-report",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Google reports expressive interface research and also examples where unfamiliar arrangements or removed labels reduced usability.",
+      "application": "Let expression clarify priority while keeping interaction understandable.",
+      "limitation": "Vendor-reported app research; reported gains are not website conversion evidence.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S07",
+      "publisher": "Pentagram",
+      "title": "Hiut",
+      "url": "https://www.pentagram.com/work/hiut",
+      "evidenceClass": "first-party-case-study",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "The account connects typography, photography and palette to the factory, makers and location.",
+      "application": "Derive visual relationships from customer-specific material.",
+      "limitation": "Case-study claims are not independent outcome research; no reuse rights for brand assets assumed.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included.",
+      "visualInspection": "Browser viewport 1265x712: case-study opening and adjacent color/monochrome photographic panels inspected. This was not an audit of the customer website."
+    },
+    {
+      "id": "S08",
+      "publisher": "Pentagram",
+      "title": "Isomorphic Labs",
+      "url": "https://www.pentagram.com/work/isomorphic-labs",
+      "evidenceClass": "first-party-case-study",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "The account derives grid, visual language and motion from a central biological/digital symmetry idea.",
+      "application": "A business idea can govern several types of expression coherently.",
+      "limitation": "Do not copy its cubes, identity, medical claims or imply Vitris needs 3D.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included.",
+      "visualInspection": "Browser viewport 1265x712: case-study artwork and identity applications inspected. No full website or mobile audit performed."
+    },
+    {
+      "id": "S09",
+      "publisher": "Wadinambiarachchi et al.",
+      "title": "The Effects of Generative AI on Design Fixation and Divergent Thinking",
+      "url": "https://arxiv.org/abs/2403.11164",
+      "evidenceClass": "primary-research",
+      "checkedAt": "2026-09-28",
+      "inspection": "abstract",
+      "finding": "A 60-person visual ideation experiment reported more fixation and lower idea variety with the tested AI image support.",
+      "application": "Test whether contrasting examples and content-first planning reduce anchoring.",
+      "limitation": "Human visual ideation study, not autonomous HTML generation; abstract inspected.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S10",
+      "publisher": "Doshi and Hauser",
+      "title": "Generative AI enhances individual creativity but reduces the collective diversity of novel content",
+      "url": "https://discovery.ucl.ac.uk/10195027/1/Generative%20AI%20enhances%20individual%20creativity%20but%20reduces%20the%20collective%20diversity%20of%20novel%20content.pdf",
+      "evidenceClass": "primary-research",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "The short-fiction experiment found improved individual evaluations alongside greater similarity between AI-assisted stories.",
+      "application": "Evaluate output quality and diversity separately across multiple runs.",
+      "limitation": "Different task and participants; no direct estimate of Vitris design effects.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S11",
+      "publisher": "Dow et al., Stanford HCI",
+      "title": "Parallel Prototyping Leads to Better Design Results, More Divergence, and Increased Self-Efficacy",
+      "url": "https://hci.stanford.edu/publications/2010/parallel-prototyping/ParallelPrototyping2010-final.pdf",
+      "evidenceClass": "primary-research",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "A 33-participant web-ad experiment compared multiple alternatives before feedback with serial refinement and found benefits in the parallel condition.",
+      "application": "Compare a few genuinely different proposals before over-refining one when uncertainty warrants it.",
+      "limitation": "2010 human banner-ad study; does not justify mandatory new agent calls or five variants for every site.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S12",
+      "publisher": "web.dev / Miriam Suzanne",
+      "title": "Container queries and units in action",
+      "url": "https://web.dev/articles/baseline-in-action-container-queries",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Container queries let a component respond to allocated space; viewport queries still serve page-level changes.",
+      "application": "Use available-space behavior for original elements.",
+      "limitation": "Recheck individual enhancement support; the article's 2025 compatibility notes can age.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S13",
+      "publisher": "MDN",
+      "title": "Subgrid",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Subgrid",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Nested grids can share parent tracks.",
+      "application": "Support cross-element alignment without flattening semantic grouping.",
+      "limitation": "Intrinsic sizing and fallback still need tests with real content.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S14",
+      "publisher": "MDN",
+      "title": "text-wrap-style",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-wrap-style",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Wrapping strategies have different purposes and implementation limits.",
+      "application": "Use measured headline shaping and resilient normal-wrap fallbacks.",
+      "limitation": "A property's Baseline badge does not establish identical support for every value.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S15",
+      "publisher": "Google Design",
+      "title": "Google Sans: Evolving Google's Typeface",
+      "url": "https://design.google/library/google-sans-flex-font",
+      "evidenceClass": "first-party-case-study",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-text-extract",
+      "finding": "Variable axes enable expression within a coherent typographic family.",
+      "application": "Teach width, weight and optical relationships using suitable licensed fonts.",
+      "limitation": "Do not mandate this font or generalize its vendor-reported research to all audiences.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S16",
+      "publisher": "MDN",
+      "title": "font-optical-sizing",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-optical-sizing",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Optical sizing adapts glyph forms in fonts that provide the relevant axis.",
+      "application": "Check text roles and real font capabilities at actual sizes.",
+      "limitation": "Does not add an optical axis to a font that lacks one.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S17",
+      "publisher": "web.dev",
+      "title": "The picture element",
+      "url": "https://web.dev/learn/design/picture-element",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Picture sources can supply different crops while srcset and sizes handle many resolution cases.",
+      "application": "Preserve the subject and meaning across image placements.",
+      "limitation": "Alt text must still describe the selected presentations appropriately.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S18",
+      "publisher": "Nielsen Norman Group",
+      "title": "Cards: UI-Component Definition",
+      "url": "https://www.nngroup.com/articles/cards-component/",
+      "evidenceClass": "usability-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Cards group heterogeneous summaries; regular lists can better support scanning comparable items.",
+      "application": "Choose a collection presentation from the visitor task.",
+      "limitation": "Does not make cards inherently bad or obsolete.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S19",
+      "publisher": "GOV.UK Design System",
+      "title": "Details",
+      "url": "https://design-system.service.gov.uk/components/details/",
+      "evidenceClass": "first-party-design-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Disclosure is useful for information only some visitors need; important common information should remain visible.",
+      "application": "Use optional detail without hiding the decision.",
+      "limitation": "Borrow the decision rule, not GOV.UK styling or mandatory component choice.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S20",
+      "publisher": "W3C WAI",
+      "title": "ARIA APG: Read Me First",
+      "url": "https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/",
+      "evidenceClass": "official-accessibility-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "ARIA patterns require complete behavior; semantics alone do not implement an interaction.",
+      "application": "Reuse verified controls while authoring original composition.",
+      "limitation": "APG is informative guidance; native HTML is preferred where suitable.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S21",
+      "publisher": "W3C WAI",
+      "title": "Understanding Reflow",
+      "url": "https://www.w3.org/WAI/WCAG22/Understanding/reflow.html",
+      "evidenceClass": "standard-explanation",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Explains WCAG 2.2 reflow, including equivalent 320 CSS-pixel width and exceptions.",
+      "application": "Test actual reflow as well as usual screenshot widths.",
+      "limitation": "Understanding material is informative; exceptions need context.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S22",
+      "publisher": "W3C WAI",
+      "title": "Understanding Meaningful Sequence",
+      "url": "https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html",
+      "evidenceClass": "standard-explanation",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "A correct reading sequence must be programmatically determinable when sequence affects meaning.",
+      "application": "Plan DOM reading order alongside spatial layouts.",
+      "limitation": "Different visual and DOM orders are not automatically failures; meaning and operation determine the issue.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S23",
+      "publisher": "W3C WAI",
+      "title": "Understanding Animation from Interactions",
+      "url": "https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html",
+      "evidenceClass": "standard-explanation",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Explains disabling nonessential interaction-triggered motion under criterion 2.3.3.",
+      "application": "Specify reduced-motion and static experiences for motion lessons.",
+      "limitation": "This criterion is AAA; reduced-motion handling can separately be Vitris project policy.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S24",
+      "publisher": "W3C WAI",
+      "title": "Understanding Target Size (Minimum)",
+      "url": "https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html",
+      "evidenceClass": "standard-explanation",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "WCAG 2.2 AA criterion 2.5.8 uses 24 by 24 CSS pixels with stated exceptions.",
+      "application": "Separate normative targets from a larger project design preference.",
+      "limitation": "A universal 44-pixel rule must not be mislabeled as this AA criterion.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S25",
+      "publisher": "MDN",
+      "title": "View Transition API",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-text-extract",
+      "finding": "The API supports transitions between states and documents with distinct feature surfaces.",
+      "application": "Offer continuity enhancements with usable ordinary navigation.",
+      "limitation": "Check each used subfeature against supported browsers; motion is optional.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S26",
+      "publisher": "MDN",
+      "title": "CSS scroll-driven animations",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-text-extract",
+      "finding": "Scroll and view timelines can connect animation progress to scrolling.",
+      "application": "Allow explanatory motion with content visible without animation.",
+      "limitation": "No global support claim; inspect exact properties and test fallback and reduced motion.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S27",
+      "publisher": "MDN",
+      "title": "CSS anchor positioning",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Anchor_positioning",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Positioned elements can be related to anchors, with positioning and overflow controls.",
+      "application": "Keep optional annotations near their referents.",
+      "limitation": "Not a substitute for semantics, focus handling, or an in-flow fallback.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S28",
+      "publisher": "MDN",
+      "title": "popover HTML global attribute",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Native popovers provide browser-managed presentation behavior for appropriate transient content.",
+      "application": "Use for optional context when it improves understanding.",
+      "limitation": "Popover presentation does not automatically supply a domain-specific accessible widget.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S29",
+      "publisher": "Playwright",
+      "title": "Visual comparisons",
+      "url": "https://playwright.dev/docs/test-snapshots",
+      "evidenceClass": "official-tool-documentation",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "Screenshot comparisons depend on rendering environment and baseline management.",
+      "application": "Pin capture conditions and separate pixel regressions from aesthetic judgment.",
+      "limitation": "A passing screenshot comparison cannot establish design quality or novelty.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S30",
+      "publisher": "web.dev",
+      "title": "Web Vitals",
+      "url": "https://web.dev/articles/vitals",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "LCP, INP and CLS assess loading, interaction responsiveness and visual stability.",
+      "application": "Check the cost of expressive media and interactions.",
+      "limitation": "Local lab results are not field percentile performance or conversion measurements.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S31",
+      "publisher": "web.dev",
+      "title": "Baseline 2026",
+      "url": "https://web.dev/baseline/2026",
+      "evidenceClass": "official-platform",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-page-text",
+      "finding": "The current 2026 listing includes features such as container style queries, :open and @scope.",
+      "application": "Maintain a dated implementation capability ledger.",
+      "limitation": "Newly available does not imply support in every visitor's installed browser.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    },
+    {
+      "id": "S32",
+      "publisher": "GOV.UK Service Manual",
+      "title": "Building a robust frontend using progressive enhancement",
+      "url": "https://www.gov.uk/service-manual/technology/using-progressive-enhancement",
+      "evidenceClass": "official-practice-guidance",
+      "checkedAt": "2026-09-28",
+      "inspection": "primary-source-text-extract",
+      "finding": "HTML-first structure provides a robust foundation for CSS and JavaScript enhancements.",
+      "application": "Keep core information and actions meaningful before enhancements.",
+      "limitation": "GOV.UK service requirements do not become universal Vitris mandates automatically.",
+      "reuse": "Link and paraphrase; no third-party assets or complete implementations included."
+    }
+  ]
+}

package/design-system/references/v1/README.md

@@ -0,0 +1,27 @@
+# Reference teaching release 2026-10-05.1
+
+`manifest.json` pins the authoritative `catalog.json`. The 60 deep records are a subset of the 100 screened publishers. External images and code are not cleared for redistribution or generation; eligible records supply original written observations and abstract lessons, with publisher links for live inspection. View timestamps, routes, sizes, loading limitations and evidence pointers describe actual inspections. Metadata delivery is not visual inspection or human taste approval.
+
+Original compilable material lives in `design-system/compositions/v2`, with its own manifest, source/media pins, and 64 approved compact previews. Its fictional facts never populate customer inventories. Existing calibration v1, knowledge v3 and compositions v1 retain their contracts.
+
+Opt in for a site by adding this to its existing launch.json:
+
+```json
+"designReferences": { "mode": "lessons", "release": "2026-10-05.1" }
+```
+
+Optional `manifestHash` and `teachingManifestHash` pin SHA-256 hashes of the respective manifest bytes. This policy is independent of `designAuthoring`; omitting it preserves legacy behavior. Ordinary `npm run go` and the existing creative/efficiency paths include selected references in real prepared CURRENT.md and integrity-bound expansions. Follow CURRENT.md expansion commands, inspect relevant source/preview pixels, and record relevance, boundaries and homepage/interior/mobile/action relationships in reference-analysis.json. Later stages reuse accepted choices. Do not treat context delivery as a completed inspection.
+
+From the harness checkout:
+
+```text
+node --experimental-strip-types scripts/reference-library.ts --coverage
+node --experimental-strip-types scripts/reference-library.ts --gallery --serve --port 4178
+node --experimental-strip-types scripts/reference-library.ts --preview clearwell-directory --serve --port 4179
+node --experimental-strip-types scripts/reference-library.ts --select --site SITE --out artifacts/reference-selection
+node --experimental-strip-types scripts/reference-library.ts --exposure --receipts SITE/agent --out artifacts/reference-exposure
+```
+
+Installed equivalents use `vitris-references`. Gallery serves http://127.0.0.1:4178; pair preview serves homepage `/` and interior `/detail`. IDs are listed in the gallery and compositions v2 catalog. Gallery filters expression/composition/tasks through search, evidence depth, asset minimum and eligibility, and compares up to four entries. No external thumbnails are fabricated.
+
+For research continuation, author a new record under artifacts and ingest with `--record FILE`; replacements must increment revision. Validate all linked lessons, studies and evidence hashes before publication. `--seal --release-ready` explicitly labels completed curation without human preference approval. Keep failed/rejected attempts and never edit frozen official baselines. Progress/evidence: `docs/plans/reference-library-execution-ledger-2026-10-05.md` and `artifacts/reference-library-expansion-20261005/`.