stylegallery 0.1.0

package/scripts/generate-patterns.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { patterns, samples } from "./pattern-data.mjs";
+
+const root = process.cwd();
+const patternsDir = path.join(root, "patterns");
+const generatedWarning = "<!-- Generated from `scripts/generate-patterns.mjs` and `scripts/pattern-data.mjs`. Do not hand-edit generated catalog or pattern docs; edit the source files and regenerate. -->";
+
+function rule(selector, declarations) {
+  const body = Object.entries(declarations)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([property, value]) => `    ${property}: ${value};`)
+    .join("\n");
+  return `${selector} {\n${body}\n}`;
+}
+
+function sampleHtml(slug) {
+  const html = samples[slug];
+  if (!html) throw new Error(`missing sample HTML for ${slug}`);
+  return html.trim();
+}
+
+function slugDir(category) {
+  return category.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+
+function normalize(raw) {
+  const [slug, category, problem, axis, responsiveness, source, rawRules, scrollOwnership] = raw;
+  const css = rawRules.map(([selector, declarations]) => rule(selector, declarations)).join("\n\n");
+  return { axis, category, css, problem, responsiveness, rules: rawRules, scrollOwnership, slug, source };
+}
+
+function declarationNames(pattern) {
+  return [...new Set(pattern.rules.flatMap(([, declarations]) => Object.keys(declarations)))];
+}
+
+function inlineCodeList(values) {
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+function cognitiveRisk(pattern) {
+  if (pattern.scrollOwnership && !pattern.scrollOwnership.startsWith("No internal")) {
+    return "Medium: scroll ownership can hide context, controls, or return points if it is not named in the consuming layout.";
+  }
+  if (pattern.responsiveness === "reflow") {
+    return "Medium: reflow can change spatial adjacency, so labels, controls, and related content must remain adjacent in DOM order.";
+  }
+  return "Low: the pattern should preserve ordinary reading flow when semantic order is already correct.";
+}
+
+function contractSections(pattern, rootClass) {
+  const properties = declarationNames(pattern);
+  const core = inlineCodeList(properties);
+  return [
+    "## Core Properties",
+    "",
+    `- ${core} define the spatial behavior for this pattern.`,
+    "",
+    "## Properties That Break The Layout If Removed",
+    "",
+    `- Removing ${core} changes the pattern from its documented layout responsibility back toward ordinary flow or an unsafe fixed arrangement.`,
+    "",
+    "## Constraints And Change Points",
+    "",
+    `- ${pattern.responsiveness} responsiveness is part of the contract; change sizing values only when the new minimum, maximum, or wrap point is documented with the pattern.`,
+    "- Keep the HTML class hooks and CSS selectors in one-to-one agreement.",
+    "",
+    "## Scroll Ownership",
+    "",
+    pattern.scrollOwnership ?? "No internal scroll container.",
+    "",
+    "## Accessibility And Source Order Notes",
+    "",
+    "- Semantic role expectation: Preserve the HTML sample's landmark, list, navigation, form, figure, or article roles; layout classes must not replace semantic elements.",
+    "- DOM order expectation: Keep semantic elements, DOM order, reading order, and focus order independent from the visual placement created by the layout classes.",
+    "- Focus risk: Any interactive descendants follow DOM order; do not use this pattern to create a visual order that keyboard focus cannot follow.",
+    `- Scroll expectation: ${pattern.scrollOwnership ?? "No internal scroll container."}`,
+    `- Cognitive risk: ${cognitiveRisk(pattern)}`,
+    "",
+    "## Browser And Fallback Notes",
+    "",
+    "The CSS uses modern grid, flex, intrinsic sizing, logical properties, or positioning. If a target browser cannot support a property, fall back to ordinary block flow before adding decorative or script-driven layout behavior.",
+    "",
+    "## Composition Notes",
+    "",
+    `Use \`${rootClass}\` as the stable pattern root and compose additional layout behavior outside that root unless the child class is part of the documented relationship.`,
+    "",
+    "## Anti-patterns",
+    "",
+    "- Do not add color, border, shadow, typography, or animation rules to reusable pattern CSS.",
+    "- Do not use this pattern to repair unclear HTML structure; make the DOM roles legible first.",
+    "",
+    "## IA Navigation",
+    "",
+    `Parent: [${pattern.category} patterns](index.md) in [Pattern Categories](../index.md).`,
+    "Next: [Layout Recipes](../../recipes/index.md) for screen-level composition, or return to the [Layout Pattern Catalog](../../CATALOG.md) when choosing another primitive.",
+    "",
+  ];
+}
+
+function render(raw) {
+  const pattern = normalize(raw);
+  const rootClass = pattern.slug.replaceAll("-", "_");
+  const html = sampleHtml(pattern.slug);
+  return [
+    "---",
+    "type: Layout Pattern",
+    `name: ${pattern.slug}`,
+    `title: ${pattern.slug}`,
+    `category: ${pattern.category}`,
+    `description: ${pattern.problem}`,
+    `primary_spatial_problem: ${pattern.problem}`,
+    "secondary_spatial_problems: none",
+    `layout_axis: ${pattern.axis}`,
+    "content_shape: mixed",
+    `responsiveness: ${pattern.responsiveness}`,
+    "constraints: Uses only local class hooks and explicit layout constraints.",
+    `scroll_ownership: ${pattern.scrollOwnership ?? "No internal scroll container."}`,
+    `source_lineage: ${pattern.source}`,
+    "lifecycle: generated",
+    "generated_from: scripts/generate-patterns.mjs, scripts/pattern-data.mjs",
+    "---",
+    "",
+    generatedWarning,
+    "",
+    `# ${pattern.slug}`,
+    "",
+    "## When To Use",
+    "",
+    `Use this pattern when you need to ${pattern.problem.charAt(0).toLowerCase()}${pattern.problem.slice(1)}`,
+    "",
+    "## HTML",
+    "",
+    "```html",
+    html,
+    "```",
+    "",
+    "## CSS",
+    "",
+    "```css",
+    pattern.css,
+    "```",
+    "",
+    ...contractSections(pattern, rootClass),
+  ].join("\n");
+}
+
+fs.rmSync(patternsDir, { force: true, recursive: true });
+for (const pattern of patterns) {
+  const [slug, category] = pattern;
+  const dir = path.join(patternsDir, slugDir(category));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${slug}.md`), render(pattern));
+}
+
+for (const category of [...new Set(patterns.map(([, category]) => category))]) {
+  const categoryPatterns = patterns.filter(([, patternCategory]) => patternCategory === category);
+  const dir = path.join(patternsDir, slugDir(category));
+  fs.writeFileSync(
+    path.join(dir, "index.md"),
+    [
+      `# ${category}`,
+      "",
+      generatedWarning,
+      "",
+      ...categoryPatterns.map(([slug, , problem]) => `- [${slug}](${slug}.md) - ${problem}`),
+      "",
+    ].join("\n"),
+  );
+}
+
+fs.writeFileSync(
+  path.join(patternsDir, "index.md"),
+  [
+    "# Pattern Categories",
+    "",
+    generatedWarning,
+    "",
+    ...[...new Set(patterns.map(([, category]) => category))]
+      .map((category) => `- [${category}](${slugDir(category)}/index.md)`),
+    "",
+  ].join("\n"),
+);
+
+fs.writeFileSync(
+  path.join(root, "CATALOG.md"),
+  [
+    "---",
+    "type: Catalog",
+    "title: Layout Pattern Catalog",
+    "description: Generated index of layout-gallery patterns.",
+    "---",
+    "",
+    "# Layout Pattern Catalog",
+    "",
+    "Primary role: pattern lookup.",
+    "",
+    generatedWarning,
+    "",
+    "Generated from `scripts/generate-patterns.mjs` and `scripts/pattern-data.mjs`.",
+    "",
+    "## Planning Layer",
+    "",
+    "- [Layout Planning Guide](GUIDE.md) - Pre-design entry point for choosing and composing patterns.",
+    "- [Decision Tree](guides/decision-tree.md) - Question-driven route from screen constraints to pattern categories.",
+    "- [Layout Brief](guides/layout-brief.md) - Questions to answer before selecting a pattern stack.",
+    "- [Layout Recipes](recipes/index.md) - Screen-level compositions built from reusable patterns.",
+    "",
+    "## Patterns",
+    "",
+    ...patterns.map(([slug, category, problem]) => `- [${slug}](patterns/${slugDir(category)}/${slug}.md) - ${category}: ${problem}`),
+    "",
+  ].join("\n"),
+);
+
+console.log(`generated ${patterns.length} patterns`);

package/scripts/governance-matrix-contract.mjs

@@ -0,0 +1,73 @@
+const governedProfileSources = [
+  "design-engineering/reference-profiles/governed-local/editorial/profile.json",
+  "design-engineering/reference-profiles/governed-local/editorial/tokens.dtcg.json",
+  "design-engineering/reference-profiles/governed-local/editorial/local-foundations.json",
+  "design-engineering/reference-profiles/governed-local/terminal/profile.json",
+  "design-engineering/reference-profiles/governed-local/terminal/tokens.dtcg.json",
+  "design-engineering/reference-profiles/governed-local/terminal/local-foundations.json",
+];
+
+const componentStateSources = ["components/*.component.json", "states/*.states.json", "fixtures/*.fixture.json", "evidence/*.evidence.json"];
+const componentStateArtifacts = ["editorial", "terminal"].flatMap((profile) =>
+  ["state-matrix.md", "keyboard-matrix.md", "evidence-coverage.md"].map(
+    (artifact) => `design-engineering/reference-profiles/governed-local/${profile}/generated/${artifact}`,
+  ),
+);
+
+function matrixRows(governance, family) {
+  return governance
+    .split("\n")
+    .filter((candidate) => /^ {0,3}\|/.test(candidate) && candidate.trimStart().startsWith(`| ${family} |`))
+    .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()));
+}
+
+function codeListValues(cell, finalAnd) {
+  if (typeof cell !== "string" || cell.length === 0) return null;
+  const parts = cell.split(", ");
+  if (finalAnd) {
+    const last = parts.at(-1);
+    if (parts.length < 2 || !last?.startsWith("and ")) return null;
+    parts[parts.length - 1] = last.slice(4);
+  } else if (parts.some((part) => part.startsWith("and "))) {
+    return null;
+  }
+  const actual = [];
+  for (const part of parts) {
+    const match = part.match(/^`([^`]+)`$/);
+    if (!match) return null;
+    actual.push(match[1]);
+  }
+  return actual;
+}
+
+function hasExpectedValues(actual, expected) {
+  if (!actual) return false;
+  return actual.length === expected.length && new Set(actual).size === expected.length && expected.every((value) => actual.includes(value));
+}
+
+export function referenceOwnershipFailures(governance) {
+  const failures = [];
+  const profileRows = matrixRows(governance, "Governed local reference profiles");
+  if (profileRows.length !== 1) {
+    failures.push("GOVERNANCE.md: Governed local reference profiles row must appear exactly once");
+  } else {
+    const profileRow = profileRows[0];
+    if (!hasExpectedValues(codeListValues(profileRow[1], false), governedProfileSources)) failures.push("GOVERNANCE.md: governed local reference profile sources must be the six explicit canonical profile files");
+    if (profileRow[2] !== "Manual" || profileRow[3] !== "None") failures.push("GOVERNANCE.md: governed local reference profiles must be manual sources with no generated artifacts");
+  }
+  const stateRows = matrixRows(governance, "Component-state evidence matrices");
+  if (stateRows.length !== 1) {
+    failures.push("GOVERNANCE.md: Component-state evidence matrices row must appear exactly once");
+  } else {
+    const stateRow = stateRows[0];
+    const sourceCell = stateRow[1];
+    const sourcePrefix = "Each profile's declared ";
+    const sourceSuffix = " records";
+    const sourceValues = sourceCell?.startsWith(sourcePrefix) && sourceCell.endsWith(sourceSuffix)
+      ? codeListValues(sourceCell.slice(sourcePrefix.length, -sourceSuffix.length), true)
+      : null;
+    if (!hasExpectedValues(sourceValues, componentStateSources)) failures.push("GOVERNANCE.md: component-state evidence sources must be the four declared record families");
+    if (!hasExpectedValues(codeListValues(stateRow[3], false), componentStateArtifacts)) failures.push("GOVERNANCE.md: component-state generated artifacts must be the six declared matrices");
+  }
+  return failures;
+}

package/scripts/governance-matrix-negative-cases.mjs

@@ -0,0 +1,114 @@
+function matrixRow(governance, family) {
+  return governance.split("\n").find((line) => line.startsWith(`| ${family} |`));
+}
+
+function duplicateRow(governance, row, replacement = row) {
+  return governance.replace(row, `${row}\n${replacement}`);
+}
+
+function mutateCell(row, index, mutate) {
+  const cells = row.split("|");
+  cells[index] = ` ${mutate(cells[index].trim())} `;
+  return cells.join("|");
+}
+
+function reverseCodeValues(cell) {
+  const values = [...cell.matchAll(/`([^`]+)`/g)].map((match) => match[1]).reverse();
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+export function governanceMatrixCases(governance) {
+  const profileRow = matrixRow(governance, "Governed local reference profiles");
+  const stateRow = matrixRow(governance, "Component-state evidence matrices");
+  if (!profileRow || !stateRow) throw new Error("canonical governance fixture must contain both reference ownership rows");
+
+  const conflictingProfileRow = profileRow.replace(
+    "`design-engineering/reference-profiles/governed-local/editorial/profile.json`",
+    "`design-engineering/reference-profiles/governed-local/**`",
+  );
+  const reorderedProfileRow = mutateCell(profileRow, 2, reverseCodeValues);
+  const reorderedStateSources = mutateCell(stateRow, 2, (cell) => {
+    const values = reverseCodeValues(cell);
+    return `Each profile's declared ${values.replace(/, ([^,]+)$/, ", and $1")} records`;
+  });
+  const reorderedStateRow = mutateCell(reorderedStateSources, 4, reverseCodeValues);
+
+  return [
+    {
+      name: "duplicate_governed_profile_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, profileRow) },
+      expect: "GOVERNANCE.md: Governed local reference profiles row must appear exactly once",
+    },
+    {
+      name: "conflicting_duplicate_governed_profile_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, profileRow, conflictingProfileRow) },
+      expect: "GOVERNANCE.md: Governed local reference profiles row must appear exactly once",
+    },
+    {
+      name: "one_space_duplicate_governed_profile_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, profileRow, ` ${profileRow}`) },
+      expect: "GOVERNANCE.md: Governed local reference profiles row must appear exactly once",
+    },
+    {
+      name: "three_space_conflicting_governed_profile_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, profileRow, `   ${conflictingProfileRow}`) },
+      expect: "GOVERNANCE.md: Governed local reference profiles row must appear exactly once",
+    },
+    {
+      name: "duplicate_component_state_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, stateRow) },
+      expect: "GOVERNANCE.md: Component-state evidence matrices row must appear exactly once",
+    },
+    {
+      name: "one_space_duplicate_component_state_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, stateRow, ` ${stateRow}`) },
+      expect: "GOVERNANCE.md: Component-state evidence matrices row must appear exactly once",
+    },
+    {
+      name: "three_space_conflicting_component_state_row",
+      mutate: { "GOVERNANCE.md": duplicateRow(governance, stateRow, `   ${mutateCell(stateRow, 2, () => "Each profile's declared `components/**` records")}`) },
+      expect: "GOVERNANCE.md: Component-state evidence matrices row must appear exactly once",
+    },
+    {
+      name: "duplicate_both_reference_rows",
+      mutate: { "GOVERNANCE.md": duplicateRow(duplicateRow(governance, profileRow), stateRow) },
+      expect: "GOVERNANCE.md: Governed local reference profiles row must appear exactly once",
+    },
+    {
+      name: "four_space_reference_rows_are_code_blocks",
+      mutate: {
+        "GOVERNANCE.md": duplicateRow(
+          duplicateRow(governance, profileRow, `    ${conflictingProfileRow}`),
+          stateRow,
+          `    ${mutateCell(stateRow, 2, () => "Each profile's declared `components/**` records")}`,
+        ),
+      },
+      expect: null,
+    },
+    {
+      name: "profile_source_extra_prose",
+      mutate: { "GOVERNANCE.md": governance.replace(profileRow, mutateCell(profileRow, 2, (cell) => `${cell} plus every generated matrix and evidence receipt`)) },
+      expect: "GOVERNANCE.md: governed local reference profile sources must be the six explicit canonical profile files",
+    },
+    {
+      name: "profile_artifact_extra_prose",
+      mutate: { "GOVERNANCE.md": governance.replace(profileRow, mutateCell(profileRow, 4, (cell) => `${cell} plus every generated matrix`)) },
+      expect: "GOVERNANCE.md: governed local reference profiles must be manual sources with no generated artifacts",
+    },
+    {
+      name: "component_source_extra_prose",
+      mutate: { "GOVERNANCE.md": governance.replace(stateRow, mutateCell(stateRow, 2, (cell) => `${cell} plus every related record`)) },
+      expect: "GOVERNANCE.md: component-state evidence sources must be the four declared record families",
+    },
+    {
+      name: "component_artifact_extra_prose",
+      mutate: { "GOVERNANCE.md": governance.replace(stateRow, mutateCell(stateRow, 4, (cell) => `${cell} plus every generated matrix and evidence receipt`)) },
+      expect: "GOVERNANCE.md: component-state generated artifacts must be the six declared matrices",
+    },
+    {
+      name: "reordered_reference_matrix_cells",
+      mutate: { "GOVERNANCE.md": governance.replace(profileRow, reorderedProfileRow).replace(stateRow, reorderedStateRow) },
+      expect: null,
+    },
+  ];
+}

package/scripts/governance-policy-contract.mjs

@@ -0,0 +1,49 @@
+export const sentinelProvenanceClauses = [
+  "Completed-CI repository, workflow, run ID and attempt, SHA, and artifact-name fields are workflow-recorded, self-asserted metadata, not an external attestation.",
+  "The self-asserted repository field names the canonical upstream changeroa/StyleGallery; the self-asserted execution_repository field names the actual GitHub Actions repository and is limited to changeroa/StyleGallery or ark-jo/StyleGallery.",
+  "The committed calibration's external_verification object records an independently checked GitHub Actions run and artifact API identity; artifact.api_digest is distinct from committed_ci.raw_evidence_sha256.",
+  "Future CI aggregates remain awaiting_external_verification until their uploaded artifact API identity is independently checked.",
+  "Linux/amd64 repeatability is externally verified only for committed run 29260372260; it does not establish baseline-owner approval or product suitability.",
+  "Baseline-owner approval remains unclaimed until the named owner explicitly approves it.",
+  "Synthetic fixtures validate rejection and acceptance behavior only; they are not authenticated provenance.",
+];
+
+export const requiredCodeowners = [
+  "* @changeroa",
+  "/GOVERNANCE.md @changeroa",
+  "/README.md @changeroa",
+  "/index.md @changeroa",
+  "/AGENTS.md @changeroa",
+  "/DOMAINS.md @changeroa",
+  "/layout/ @changeroa",
+  "/motion/ @changeroa",
+  "/design-engineering/ @changeroa",
+  "/game-ui/ @changeroa",
+  "/platform-guides/ @changeroa",
+  "/consumer-reference/ @changeroa",
+  "/consumer-reference/baselines/ @changeroa",
+  "/consumer-reference/policies/ @changeroa",
+  "/consumer-reference/fixtures/promotion/ @changeroa",
+  "/consumer-reference/schema/promotion-rfc.schema.json @changeroa",
+  "/tests/ @changeroa",
+  "/playwright.config.mjs @changeroa",
+  "/GUIDE.md @changeroa",
+  "/guides/ @changeroa",
+  "/recipes/ @changeroa",
+  "/quality/ @changeroa",
+  "/scripts/pattern-data.mjs @changeroa",
+  "/scripts/generate-patterns.mjs @changeroa",
+  "/patterns/ @changeroa",
+  "/CATALOG.md @changeroa",
+  "/.github/workflows/validate.yml @changeroa",
+  "/.github/ @changeroa",
+  "/scripts/ @changeroa",
+  "/scripts/validate-*.mjs @changeroa",
+  "/scripts/test-validate-*.mjs @changeroa",
+];
+
+export const immutableActionPins = [
+  "uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4",
+  "uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4",
+  "uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4",
+];