@verevoir/design-gate 0.1.0 → 0.2.0

package/surface/surface.js

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import { validateDtcg } from '../design/dtcg.mjs';
+// DESIGN SURFACE — the common interlingua you go in and out of. It reads like a
+// design system's own documentation: not just a component catalogue, but how they
+// compose, and the softer, load-bearing qualities a design system actually turns on
+// — its VOICE, its FEEL, its PRINCIPLES. Those aren't decoration: across an
+// ecosystem the real question is "do these surfaces cohere as one design language,
+// or has each drifted?", and you can only answer it if voice/feel/principles are
+// first-class, carry provenance, and synthesise + deviate the same way components do.
+//
+// Stance (first stab, expect the schema to move under real surfaces):
+//   - PRIMARY artefact / source of truth. Doc renders it, overlay diffs it,
+//     synthesis merges it, export projects it.
+//   - Sits directly above the DTCG token plane (a variant links down to tokens).
+//   - Everything repeated carries PROVENANCE — the same button, or the same voice,
+//     seen in two apps is one entry with two provenances. The cross-source map is
+//     the point.
+//   - CLOSED under synthesis: a single-source surface has one source and one voice;
+//     a landscape has many, same type. So audit-of-existing and proposed-new are the
+//     same type, and you fold an ecosystem with `sources.reduce(merge)`.
+export const SCHEMA_URL = 'https://verevoir.dev/schemas/design-surface/v0';
+/** Where something was found. First-class + repeated. `confidence` is the adapter's
+ * own reading confidence (a screenshot read is less sure than a parsed repo). */
+export const Provenance = z.object({
+    sourceId: z.string(),
+    kind: z.enum(['screenshot', 'flat', 'figma', 'repo', 'website', 'claude-design', 'v0']),
+    locator: z.string(),
+    confidence: z.number().min(0).max(1).optional(),
+});
+// ── the soft, load-bearing design-system qualities ───────────────────────────
+/** How the product SPEAKS — tone, personality, language. Attributes are the axes a
+ * design system names ("plain-spoken", "authoritative", "warm"); examples are real
+ * copy that shows it. Per-source, so the landscape can compare voices across apps. */
+export const Voice = z.object({
+    sourceId: z.string().optional(), // set once attributed to a source; a synthesised/proposed voice may omit it
+    summary: z.string(),
+    attributes: z.array(z.string()).default([]),
+    examples: z.array(z.string()).default([]),
+    provenance: z.array(Provenance).default([]),
+});
+/** How the product FEELS — the aesthetic character. Attributes are the axes
+ * ("minimal", "high-contrast", "dense", "playful"); references point at what
+ * evidences it (a screenshot, a page). */
+export const Feel = z.object({
+    sourceId: z.string().optional(),
+    summary: z.string(),
+    attributes: z.array(z.string()).default([]),
+    references: z.array(z.string()).default([]),
+    provenance: z.array(Provenance).default([]),
+});
+/** A design PRINCIPLE the surface holds — a rule with teeth ("no decorative borders
+ * or shadows", "one primary action per view"). Deviations from these are the
+ * high-value findings of an overlay. */
+export const Principle = z.object({
+    id: z.string(),
+    statement: z.string(),
+    rationale: z.string().optional(),
+    provenance: z.array(Provenance).min(1),
+});
+/** The project CONTEXT a surface must serve — the yardstick the overlay judges
+ * against, so the design is never evaluated in a vacuum. A young audience should
+ * show TENSION with something oak-panelled: `audience` + `positioning` say what it is
+ * FOR, and `tensions` name what it must NOT drift into. Pulled from the aigency
+ * project context for an audit; authored for a proposal; carried forward on an
+ * accepted surface. This is the aigency plug: the design surface answers to the same
+ * project intent the code and the ADRs do. */
+export const Intent = z.object({
+    audience: z.string().optional(),
+    positioning: z.string().optional(), // "modern, approachable" / "authoritative" / "playful but trustworthy"
+    tensions: z.array(z.string()).default([]), // what it must NOT be — "oak-panelled", "stuffy", "enterprise-grey"
+    notes: z.string().optional(),
+});
+/** Where a surface sits in its lifecycle. An `accepted` surface IS project context —
+ * persisted in the substrate, versioned, and developed over time exactly as the code
+ * is; it's not a one-off report. */
+export const SurfaceStatus = z.enum(['audit', 'landscape', 'proposal', 'accepted']);
+/** The design TOKENS a surface uses — the DTCG set (colour / type / space / …), the
+ * bottom layer this whole surface sits on. This is where the earlier design-token
+ * work FOLDS IN, not as a separate thing: `ingest-style-guide` is a token importer,
+ * `generate-design-tokens` a token exporter, and the DTCG design-gate is the token
+ * half of `validateSurface`. Per-source + collected (like voices), so the landscape
+ * shows token DIVERGENCE across the ecosystem (Nexus's blue vs Timesheets's blue).
+ * `dtcg` is the raw DTCG object; the zod schema keeps it an opaque record, and
+ * `validateSurface` runs the shared design-gate (`validateDtcg`) over it — the same
+ * zero-dependency check a produced pack runs in CI — so the token layer is gated
+ * exactly like the rest of the surface (STDIO-524). */
+export const TokenSet = z.object({
+    sourceId: z.string().optional(),
+    dtcg: z.record(z.unknown()), // { color: {...}, spacing: {...}, typography: {...}, ... }
+    provenance: z.array(Provenance).default([]),
+});
+// ── the component catalogue ──────────────────────────────────────────────────
+export const Variant = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    tokens: z.record(z.string()).optional(), // the link DOWN to the DTCG token layer
+});
+export const PropSpec = z.object({
+    name: z.string(),
+    type: z.string().optional(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+});
+export const ComponentKind = z.enum(['atom', 'molecule', 'organism', 'layout', 'page']);
+export const Component = z.object({
+    id: z.string(),
+    name: z.string(),
+    kind: ComponentKind,
+    role: z.string().optional(),
+    description: z.string().optional(),
+    composition: z.string().optional(), // prose: how it composes / when to reach for it (design-system doc voice)
+    variants: z.array(Variant).default([]),
+    props: z.array(PropSpec).default([]),
+    states: z.array(z.string()).default([]),
+    composes: z.array(z.string()).default([]), // ids it is built from
+    a11y: z.array(z.string()).default([]),
+    evidence: z.array(z.string()).default([]),
+    provenance: z.array(Provenance).min(1), // never empty — no provenance = hallucination
+});
+export const Pattern = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    components: z.array(z.string()).default([]),
+    provenance: z.array(Provenance).min(1),
+});
+export const SourceRef = z.object({
+    id: z.string(),
+    kind: z.enum(['screenshot', 'flat', 'figma', 'repo', 'website', 'claude-design', 'v0']),
+    locator: z.string(),
+    label: z.string().optional(),
+});
+/** The surface. `sources`/`voices`/`feels` are length 1 for a single-source surface,
+ * N for a synthesised landscape — same type either way (closed under synthesis). */
+export const DesignSurface = z.object({
+    $schema: z.literal(SCHEMA_URL).default(SCHEMA_URL),
+    status: SurfaceStatus.default('audit'),
+    intent: Intent.optional(), // the project context this surface serves / is judged against
+    sources: z.array(SourceRef).min(1),
+    voices: z.array(Voice).default([]),
+    feels: z.array(Feel).default([]),
+    principles: z.array(Principle).default([]),
+    tokens: z.array(TokenSet).default([]), // the DTCG base layer — the design-token work, folded in
+    components: z.array(Component).default([]),
+    patterns: z.array(Pattern).default([]),
+    generatedAt: z.string().optional(),
+});
+/** Parse against the schema, then the semantic checks it can't express: every
+ * `composes` / pattern `components` id resolves, and every `tokens` layer is valid
+ * DTCG (delegated to the shared design-gate). Deterministic gate, precise patchable
+ * findings — the surface's own half plus the token half of the DTCG gate. */
+export function validateSurface(input) {
+    const parsed = DesignSurface.safeParse(input);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            findings: parsed.error.issues.map((i) => ({
+                kind: 'SCHEMA',
+                where: i.path.join('.') || '(root)',
+                message: i.message,
+            })),
+        };
+    }
+    const s = parsed.data;
+    const findings = [];
+    const ids = new Set(s.components.map((c) => c.id));
+    for (const c of s.components)
+        for (const dep of c.composes)
+            if (!ids.has(dep))
+                findings.push({
+                    kind: 'DANGLING_REF',
+                    where: `components.${c.id}.composes`,
+                    message: `composes "${dep}" but no component with that id exists`,
+                });
+    for (const p of s.patterns)
+        for (const dep of p.components)
+            if (!ids.has(dep))
+                findings.push({
+                    kind: 'DANGLING_REF',
+                    where: `patterns.${p.id}.components`,
+                    message: `references component "${dep}" but no component with that id exists`,
+                });
+    // the token half of the gate: the same zero-dependency DTCG check a produced pack
+    // runs in CI, applied here so a malformed token layer fails the surface too.
+    s.tokens.forEach((t, i) => {
+        for (const f of validateDtcg(t.dtcg))
+            findings.push({
+                kind: 'DTCG',
+                where: `tokens.${t.sourceId ?? i}.${f.path}`,
+                message: `${f.code}: ${f.message}`,
+            });
+    });
+    return { ok: findings.length === 0, findings };
+}
+// ── synthesis (the merge — closed over the schema) ───────────────────────────
+function dedupeBy(items, key) {
+    const seen = new Map();
+    for (const it of items)
+        if (!seen.has(key(it)))
+            seen.set(key(it), it);
+    return [...seen.values()];
+}
+function foldById(items, combine) {
+    const order = [];
+    const byId = new Map();
+    for (const it of items) {
+        const cur = byId.get(it.id);
+        if (cur)
+            byId.set(it.id, combine(cur, it));
+        else {
+            byId.set(it.id, it);
+            order.push(it.id);
+        }
+    }
+    return order.map((id) => byId.get(id));
+}
+const provKey = (p) => `${p.sourceId}:${p.kind}:${p.locator}`;
+function mergeComponent(a, b) {
+    return {
+        ...a,
+        description: a.description ?? b.description,
+        role: a.role ?? b.role,
+        composition: a.composition ?? b.composition,
+        variants: dedupeBy([...a.variants, ...b.variants], (v) => v.name),
+        props: dedupeBy([...a.props, ...b.props], (p) => p.name),
+        states: [...new Set([...a.states, ...b.states])],
+        composes: [...new Set([...a.composes, ...b.composes])],
+        a11y: [...new Set([...a.a11y, ...b.a11y])],
+        evidence: [...new Set([...a.evidence, ...b.evidence])],
+        provenance: dedupeBy([...a.provenance, ...b.provenance], provKey),
+    };
+}
+function mergePattern(a, b) {
+    return {
+        ...a,
+        description: a.description ?? b.description,
+        components: [...new Set([...a.components, ...b.components])],
+        provenance: dedupeBy([...a.provenance, ...b.provenance], provKey),
+    };
+}
+/** Merge two surfaces, CLOSED over the schema. Components/patterns fold by id (same
+ * id → one entry, unioned provenance). Voices/feels/principles are COLLECTED (kept
+ * per-source, deduped) rather than folded into one — because the landscape's job is
+ * to let you SEE the spread ("Nexus feels dense, .com feels airy"); reconciling them
+ * into a single unified voice/feel is a PROPOSE-stage decision, not a merge. So the
+ * merge preserves the divergence that the overlay then reasons about. */
+export function mergeSurfaces(a, b) {
+    return {
+        $schema: SCHEMA_URL,
+        // merging surfaces yields a landscape; the project intent is shared, so carry it
+        status: 'landscape',
+        intent: a.intent ?? b.intent,
+        sources: dedupeBy([...a.sources, ...b.sources], (s) => s.id),
+        voices: dedupeBy([...a.voices, ...b.voices], (v) => `${v.sourceId ?? ''}:${v.summary}`),
+        feels: dedupeBy([...a.feels, ...b.feels], (f) => `${f.sourceId ?? ''}:${f.summary}`),
+        principles: foldById([...a.principles, ...b.principles], (x, y) => ({
+            ...x,
+            rationale: x.rationale ?? y.rationale,
+            provenance: dedupeBy([...x.provenance, ...y.provenance], provKey),
+        })),
+        // token sets collected per-source (like voices), so the landscape shows token drift
+        tokens: dedupeBy([...a.tokens, ...b.tokens], (t) => t.sourceId ?? JSON.stringify(t.dtcg)),
+        components: foldById([...a.components, ...b.components], mergeComponent),
+        patterns: foldById([...a.patterns, ...b.patterns], mergePattern),
+        generatedAt: a.generatedAt ?? b.generatedAt,
+    };
+}
+export function synthesise(surfaces) {
+    if (surfaces.length === 0)
+        throw new Error('synthesise: need at least one surface');
+    return surfaces.reduce(mergeSurfaces);
+}