@norskvideo/ctl-dev-kit 0.2.108 → 0.2.110

package/conventions/DESIGN.family.md

@@ -0,0 +1,73 @@
+<!-- BEGIN ctl-shared-design v1 -->
+<!--
+  This block is the SHARED family design core for Norsk operator consoles,
+  single-sourced in @norskvideo/ctl-dev-kit (conventions/DESIGN.family.md). It
+  is copied verbatim into every product dashboard's DESIGN.md
+  (dashboards/<name>/DESIGN.md) between these fenced markers, and the drift
+  gate fails CI if a copy diverges. Do NOT hand-edit a copy: edit the dev-kit
+  source and re-sync. The console's own north star, accent, components and
+  product rules live OUTSIDE the markers and are yours to own.
+-->
+
+## Family rules (shared by every Norsk operator console — do not edit in place)
+
+An operator moving between consoles (a commentary gallery, a playout desk) must
+read on-air, health and interaction identically. These rules and the shared
+palette below hold on every console. The operator-UI principles behind them live
+in norsk-studio `docs/operator-ui-principles.md`; change a principle there first,
+then here.
+
+### Shared palette
+
+Status and neutral tokens are the same on every console. Each console's
+frontmatter `colors:` must carry exactly these values (the drift gate checks);
+its `accent` tokens are its own.
+
+| Token     | Value     | Role                                                        |
+| --------- | --------- | ----------------------------------------------------------- |
+| `live`    | `#ff4557` | On-Air Red: live / on air. The only colour allowed to glow. |
+| `ok`      | `#35d29a` | Healthy.                                                    |
+| `warn`    | `#f4b63f` | At risk.                                                    |
+| `crit`    | `#ff7a4d` | Failed.                                                     |
+| `bg`      | `#0d1014` | Background.                                                 |
+| `panel`   | `#141a21` | Panel tone 1.                                               |
+| `panel-2` | `#1a2129` | Panel tone 2.                                               |
+| `panel-3` | `#202932` | Panel tone 3.                                               |
+| `line`    | `#262f3b` | Hairline border.                                            |
+| `ink`     | `#e8edf3` | Primary text.                                               |
+| `ink-mut` | `#9aa6b5` | Secondary text.                                             |
+| `ink-dim` | `#8794a3` | Tertiary text; still clears 4.5:1.                          |
+
+### Family named rules
+
+**The Reserved Accent Rule.** The console's accent means _interactive_. Status
+never borrows it: health, metering and channel state live entirely in the
+red/green/amber/coral system. If a swatch of the accent is not clickable or a
+focus state, it is wrong.
+
+**The One Glow Rule.** Only On-Air Red is allowed a glow (`box-shadow` bloom),
+and it sits on the console's on-air programme view. Everything else is flat. A
+glow anywhere else dilutes the one signal that must never be missed.
+
+**The Tabular Rule.** Any column or readout of numbers (timecode, durations,
+countdowns, meter scales, dB, ports) is `font-variant-numeric: tabular-nums`, so
+digits never jitter as they tick.
+
+**The Flat-By-Default Rule.** New surfaces get a tone step and a 1px border.
+Reach for `box-shadow` only for the On-Air glow or the focus ring; never to lift
+a card.
+
+**The Immediate-PGM, Honest-OUT Rule.** Show an operator's decision the moment
+it is decided, and keep a separate, true view of what is going out. A desk that
+cuts or takes programme carries two labelled views: **PGM**, which changes the
+instant a cut or take is committed, using a preview the desk already has; and
+**OUT**, the real encoded output with graphics and everything else applied
+downstream, whose transport lag is labelled as expected rather than styled as a
+fault. Only a committed decision is immediate: a guarded action changes nothing
+on PGM until it is confirmed, and a load or a source still arriving shows its
+pending state. Never simulate downstream processing in PGM; OUT is the authority
+on what aired. When both views are present, the ON AIR pill and the One Glow sit
+on PGM, following the gallery tally convention. A desk with only one programme
+view shows the true output and labels its lag.
+
+<!-- END ctl-shared-design v1 -->

package/conventions/check-drift.ts

@@ -5,6 +5,9 @@
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
 //     product with tests/demo.spec.ts is asked for it), publish-docs-site.yml
 //     (only a repo with a docs site may carry it, and never a turnkey)
+//   - verbatim marker block + palette: each dashboards/*/DESIGN.md embeds the
+//     DESIGN.family.md block, and its frontmatter colors: carry that block's
+//     shared palette (no DESIGN.md, no requirement)
 //   - masked per-repo line: checks.yml, bump.yml, publish-docs.yml and the
 //     other dispatching workflows (`product:` key)
 //   - retired: upgrade-latest.yml, sync-dev-kit.yml, sync-ctl-packages.yml,
@@ -255,6 +258,97 @@ function coreProblem(claude: string, canonicalCore: string): string | undefined
   return `CLAUDE.md fenced core has drifted from @norskvideo/ctl-dev-kit conventions/CLAUDE.core.md (${firstDiffLine(region, canonicalCore.trimEnd())}). ${RESYNC}`;
 }
 
+// Each operator console's dashboards/<name>/DESIGN.md embeds the family design
+// block verbatim between these markers, and its frontmatter `colors:` must carry
+// the shared palette that block's table defines. The table is the one source of
+// the expected values, so editing DESIGN.family.md is the only change needed.
+export const DESIGN_BEGIN = "<!-- BEGIN ctl-shared-design v1 -->";
+export const DESIGN_END = "<!-- END ctl-shared-design v1 -->";
+const DESIGN_SOURCE = "@norskvideo/ctl-dev-kit conventions/DESIGN.family.md";
+
+export function designDocs(repoRoot: string): string[] {
+  const dir = join(repoRoot, "dashboards");
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, "DESIGN.md")))
+    .map((d) => `dashboards/${d.name}/DESIGN.md`)
+    .sort();
+}
+
+const PALETTE_ROW = /^\|\s*`([a-z0-9-]+)`\s*\|\s*`([^`]+)`\s*\|/gm;
+
+export function sharedPalette(canonicalDesign: string): Map<string, string> {
+  return new Map([...canonicalDesign.matchAll(PALETTE_ROW)].map((m) => [m[1] as string, m[2] as string]));
+}
+
+const unquote = (v: string): string => {
+  const m = /^(["'])(.*)\1(\s+#.*)?$/.exec(v);
+  return m ? (m[2] as string) : v;
+};
+
+// Just enough YAML for a flat `colors:` map in the leading frontmatter: no
+// dependency, since this script ships to products and runs from node_modules.
+export function frontmatterColors(text: string): Map<string, string> | undefined {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() !== "---") return undefined;
+  const close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  if (close === -1) return undefined;
+  const start = lines.findIndex((l, i) => i < close && /^colors:\s*$/.test(l));
+  if (start === -1) return undefined;
+  const colors = new Map<string, string>();
+  for (const line of lines.slice(start + 1, close)) {
+    if (line.trim() === "") continue;
+    if (!/^\s/.test(line)) break;
+    const m = /^\s+([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line);
+    if (m) colors.set(m[1] as string, unquote(m[2] as string));
+  }
+  return colors;
+}
+
+function designBlockProblem(rel: string, text: string, canonicalDesign: string): string | undefined {
+  if (text.includes(canonicalDesign.trimEnd())) return undefined;
+  const begin = text.indexOf(DESIGN_BEGIN);
+  const end = text.indexOf(DESIGN_END);
+  if (begin === -1 || end === -1 || end < begin) {
+    return `${rel} is missing the '${DESIGN_BEGIN}' / '${DESIGN_END}' marker block. Copy conventions/DESIGN.family.md from @norskvideo/ctl-dev-kit verbatim between the markers.`;
+  }
+  const region = text.slice(begin, end + DESIGN_END.length);
+  return `${rel} fenced family design block has drifted from ${DESIGN_SOURCE} (${firstDiffLine(region, canonicalDesign.trimEnd())}). ${RESYNC}`;
+}
+
+function paletteProblems(rel: string, text: string, canonicalDesign: string): string[] {
+  const expected = sharedPalette(canonicalDesign);
+  if (expected.size === 0) throw new Error("canonical DESIGN.family.md has no shared palette table");
+  const colors = frontmatterColors(text);
+  if (colors === undefined) {
+    return [
+      `${rel} has no frontmatter colors: map; it must carry the shared palette tokens (${[...expected.keys()].join(", ")}) from ${DESIGN_SOURCE}.`,
+    ];
+  }
+  const problems: string[] = [];
+  for (const [token, want] of expected) {
+    const got = colors.get(token);
+    if (got === undefined || got === "") {
+      problems.push(
+        `${rel} frontmatter colors: has no \`${token}\` — the shared palette in ${DESIGN_SOURCE} sets it to ${JSON.stringify(want)}.`,
+      );
+    } else if (got.toLowerCase() !== want.toLowerCase()) {
+      problems.push(
+        `${rel} frontmatter colors.${token} is ${JSON.stringify(got)}, but the shared palette in ${DESIGN_SOURCE} sets it to ${JSON.stringify(want)}. Status and neutral tokens are the family's; only accent tokens are the console's own.`,
+      );
+    }
+  }
+  return problems;
+}
+
+export function designProblems(repoRoot: string, canonicalDesign: string): string[] {
+  return designDocs(repoRoot).flatMap((rel) => {
+    const text = readFileSync(join(repoRoot, rel), "utf8");
+    const block = designBlockProblem(rel, text, canonicalDesign);
+    return [...(block ? [block] : []), ...paletteProblems(rel, text, canonicalDesign)];
+  });
+}
+
 export interface CanonicalBytes {
   core: string;
   /** build/flake.nix — the starter flake a Studio product begins from, and what
@@ -316,6 +410,10 @@ export interface CanonicalBytes {
    *  pins step has no Studio pair or manifest.seed.json, and bumps the norsk
    *  family off the SDK nightly. Optional for the same reason as flakeSdkApp. */
   bumpSdkApp?: string;
+  /** conventions/DESIGN.family.md -- the family design block each
+   *  dashboards/<name>/DESIGN.md embeds between DESIGN_BEGIN/DESIGN_END, whose
+   *  palette table its frontmatter colors: must match. */
+  design: string;
 }
 
 export const SERVER_KIT_COPIES = [
@@ -927,6 +1025,7 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   for (const p of productLogsProblems(repoRoot)) push(p);
   for (const p of bunVersionProblems(repoRoot, canonical.ctlShell)) push(p);
   for (const p of ctlPinProblems(repoRoot)) push(p);
+  for (const p of designProblems(repoRoot, canonical.design)) push(p);
 
   return { ok: problems.length === 0, problems };
 }
@@ -958,6 +1057,7 @@ if (import.meta.main) {
     flakeSdkApp: readFileSync(join(import.meta.dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(import.meta.dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(import.meta.dir, "bump.sdk-app.yml"), "utf8"),
+    design: readFileSync(join(import.meta.dir, "DESIGN.family.md"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical, {
     repoName: resolveRepoName(repoRoot),

package/conventions/sync-drift.ts

@@ -15,7 +15,8 @@
 //                                                       sync-ctl-packages) are DELETED
 //   - nix/ctl-shell.nix                              -> overwrite with canonical (created if absent)
 //   - flake.nix (legacy verbatim copy only)          -> the starter, repo's floating ctl pin kept
-//   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
+//   - marker-block (CLAUDE core, dprint, .gitignore, -> replace the shared block, keep the rest
+//     dashboards/*/DESIGN.md family block)            (DESIGN.md: appended where absent)
 //   - publish-docs-site.yml                          -> verbatim; CREATED where the repo has a
 //                                                       docs site and is not a turnkey
 // Structural per-repo files (root tsconfig.json, deployment/build-image.sh,
@@ -37,8 +38,11 @@ import {
   CTL_SHELL_PATH,
   CTL_VERSION_LINE,
   carriesIntegrationMarker,
+  DESIGN_BEGIN,
+  DESIGN_END,
   DOCS_SITE_DIR,
   DOCS_SITE_WORKFLOW,
+  designDocs,
   END,
   GITIGNORE_BEGIN,
   GITIGNORE_END,
@@ -285,6 +289,20 @@ function syncClaude(repoRoot: string, core: string, r: SyncReport): void {
   writeIfChanged(path, out, "CLAUDE.md", r.written);
 }
 
+// dashboards/<name>/DESIGN.md: the family design block is fenced like the CLAUDE
+// core; a console that has none yet gets it appended. The frontmatter palette is
+// the product's to fix (the gate names each token), so it is never rewritten.
+function syncDesign(repoRoot: string, design: string, r: SyncReport): void {
+  for (const rel of designDocs(repoRoot)) {
+    const path = join(repoRoot, rel);
+    const existing = readFileSync(path, "utf8");
+    const out =
+      replaceMarkerBlock(existing, DESIGN_BEGIN, DESIGN_END, design) ??
+      `${existing.replace(/\n*$/, "\n\n")}${design.trimEnd()}\n`;
+    writeIfChanged(path, out, rel, r.written);
+  }
+}
+
 // .gitignore: the shared block is marker-delimited; repo-specific ignores live
 // outside it. Replace the block, or prepend it if the repo has none yet (the
 // one-time migration case).
@@ -489,6 +507,7 @@ export function syncDrift(
   syncPackageManager(repoRoot, canonical.ctlShell, r);
   syncFlake(repoRoot, flakeCanon, r);
   syncClaude(repoRoot, canonical.core, r);
+  syncDesign(repoRoot, canonical.design, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
   syncDemoShim(repoRoot, canonical.demoShim, r);
@@ -528,6 +547,7 @@ if (import.meta.main) {
     flakeSdkApp: readFileSync(join(dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(dir, "bump.sdk-app.yml"), "utf8"),
+    design: readFileSync(join(dir, "DESIGN.family.md"), "utf8"),
   };
   const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot), { repoName: resolveRepoName(repoRoot) });
   if (report.written.length === 0) {

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.108",
+  "version": "0.2.110",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/id3as/norsk-ctl.git",
+    "directory": "packages/dev-kit"
+  },
   "exports": {
     "./create-product": "./create-product/create-product.ts",
     "./doc-guide": "./doc-guide/doc-guide.js",