@amityco/social-plus-vise 0.12.2 → 0.12.3

package/README.md

@@ -250,6 +250,7 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise design extract --from-project [path] [--no-write]` | No external prototype? Derive the contract from the host project's **own** design system — CSS custom properties (incl. shadcn `:root` and Tailwind v4 `@theme`), TS/JS token modules, inline tailwind configs, **Android** `colors.xml`/`dimens.xml`, **Flutter** `Color(0x…)`, and **iOS** `.xcassets/*.colorset` + Swift `Color(hex:)`/`Color(red:g:b:)`. Reference values (`var()`/`theme()`/`calc()`) are skipped, so a var-mapped config contributes nothing rather than wrong tokens |
 | `vise design check [path]` | Advisory, **non-blocking** report on how closely the UI code matches the contract (token coverage + on/off-contract color literals). Never fails a build and is **not** a `vise check` gate |
 | `vise design preview [path] [--reference <prototype>]` | Write a self-contained `sp-vise/design-preview.html`: the contract's tokens as visual swatches + the conformance report + the HTML reference embedded for side-by-side review. Vise renders the artifact; a human/VLM judges the visual match. Dependency-free — **not** an automated pixel diff |
+| `vise design reference [path] [--title <name>]` | Write a self-contained `sp-vise/design-reference.html`: human/VLM-readable design-system spec — token swatches, type samples, component demos, and a growth-layer summary. Pairs with `design-contract.json` (machine-readable). Use `--title` to name the design system (e.g. `--title Streamly`). Advisory — **not** an enforcement gate |
 
 The extracted contract is **advisory input for generation**, not an enforcement gate: a token-poor prototype yields a weaker — never wrong — contract, and absence of a prototype simply means no contract (the existing `*.design.reuse-detected-tokens` rules still cover reuse of a host project's own design system).
 

package/dist/server.js

@@ -7,7 +7,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
-import { designCheckTool, designExtractTool, designPreviewTool } from "./tools/design.js";
+import { designCheckTool, designExtractTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { planHarnessTool } from "./tools/harness.js";
 import { planIntegrationTool } from "./tools/integration.js";
@@ -37,6 +37,7 @@ const tools = new Map([
     designExtractTool,
     designCheckTool,
     designPreviewTool,
+    designReferenceTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
 const cliResult = await handleCli(process.argv.slice(2));
@@ -295,7 +296,16 @@ async function handleCli(args) {
                 });
                 return "exit";
             }
-            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", or "preview".`);
+            if (sub === "reference") {
+                assertOnlyKnownFlags(subArgs, ["title", "no-write"], "design reference");
+                await printToolResult(designReferenceTool, {
+                    repoPath: positionalRepoPath(subArgs),
+                    title: flagValue(subArgs, "title"),
+                    write: !hasFlag(subArgs, "no-write"),
+                });
+                return "exit";
+            }
+            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", or "reference".`);
             process.exitCode = 1;
             return "exit";
         }
@@ -504,23 +514,28 @@ Usage:
   vise design extract --from-project [repoPath] [--no-write]
   vise design check [repoPath]
   vise design preview [repoPath] [--reference <prototypePath>]
-
-extract  Build a graded design contract and write it to sp-vise/design-contract.json.
-         Declared CSS custom properties become exact tokens; repeated literal values
-         become inferred (advisory) tokens; single-use literals are treated as one-offs.
-         With --from-project (no external prototype), derive the contract from the host
-         project's OWN design system: CSS custom properties (incl. shadcn :root and
-         Tailwind v4 @theme), TS/JS token modules, inline tailwind configs, Android
-         colors.xml/dimens.xml, Flutter Color(0x..), and iOS .xcassets/.colorset +
-         Swift colors. Reference values (var()/theme()/calc()) are skipped, so a
-         var-mapped config contributes nothing rather than wrong tokens.
-check    Advisory, non-blocking report on how closely the project's UI code
-         matches the contract (token coverage + on/off-contract color literals).
-         Never fails a build; it is NOT a \`vise check\` gate.
-preview  Write a self-contained sp-vise/design-preview.html: the contract's tokens
-         as visual swatches + the conformance report + the HTML reference embedded
-         (with --reference) for side-by-side review. Vise renders; a human/VLM
-         judges the visual match. Dependency-free — NOT an automated pixel diff.`;
+  vise design reference [repoPath] [--title "Streamly"] [--no-write]
+
+extract    Build a graded design contract and write it to sp-vise/design-contract.json.
+           Declared CSS custom properties become exact tokens; repeated literal values
+           become inferred (advisory) tokens; single-use literals are treated as one-offs.
+           With --from-project (no external prototype), derive the contract from the host
+           project's OWN design system: CSS custom properties (incl. shadcn :root and
+           Tailwind v4 @theme), TS/JS token modules, inline tailwind configs, Android
+           colors.xml/dimens.xml, Flutter Color(0x..), and iOS .xcassets/.colorset +
+           Swift colors. Reference values (var()/theme()/calc()) are skipped, so a
+           var-mapped config contributes nothing rather than wrong tokens.
+check      Advisory, non-blocking report on how closely the project's UI code
+           matches the contract (token coverage + on/off-contract color literals).
+           Never fails a build; it is NOT a \`vise check\` gate.
+preview    Write a self-contained sp-vise/design-preview.html: the contract's tokens
+           as visual swatches + the conformance report + the HTML reference embedded
+           (with --reference) for side-by-side review. Vise renders; a human/VLM
+           judges the visual match. Dependency-free — NOT an automated pixel diff.
+reference  Write a self-contained sp-vise/design-reference.html: human/VLM-readable
+           design-system spec (token swatches, type samples, component demos, growth-layer
+           summary). Pairs with the machine-readable design-contract.json. Use --title to
+           set the design system name. Advisory — not an enforcement gate.`;
     }
     return `${packageName}
 

package/dist/tools/design.js

@@ -297,7 +297,14 @@ export function renderDesignPreview(contract, check, referenceHtml) {
     const shadows = byCat("shadow").map((t) => tokenRow(t, `<span class="box" style="box-shadow:${safeCss(t.value)}"></span>`)).join("");
     const fonts = byCat("fontFamily").map((t) => tokenRow(t, `<span class="type" style="font-family:${safeCss(t.value)}">Ag</span>`)).join("");
     const sizes = byCat("fontSize").map((t) => tokenRow(t, `<span class="type" style="font-size:${safeCss(t.value)}">Ag</span>`)).join("");
+    const weights = byCat("fontWeight").map((t) => tokenRow(t, `<span class="type" style="font-weight:${safeCss(t.value)};font-size:20px">Ag</span>`)).join("");
+    const lineHeights = byCat("lineHeight").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
+    const letterSpacings = byCat("letterSpacing").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
+    const borderWidths = byCat("borderWidth").map((t) => tokenRow(t, `<span class="box" style="border:${safeCss(t.value)} solid #888"></span>`)).join("");
+    const breakpoints = byCat("breakpoint").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
     const motions = byCat("motion").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
+    const opacities = byCat("opacity").map((t) => tokenRow(t, `<span class="sw" style="background:#888;opacity:${safeCss(t.value)}"></span>`)).join("");
+    const zIndices = byCat("zIndex").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
     const group = (title, body) => (body ? `<h2>${esc(title)}</h2><div class="grid">${body}</div>` : "");
     const reference = referenceHtml
         ? `<iframe class="ref" sandbox="allow-same-origin" srcdoc="${escAttr(referenceHtml)}" title="reference prototype"></iframe>`
@@ -351,9 +358,16 @@ ${group("Colors", colors)}
 ${group("Spacing", spaces)}
 ${group("Radius", radii)}
 ${group("Shadow", shadows)}
+${group("Border width", borderWidths)}
 ${group("Type — families", fonts)}
 ${group("Type — sizes", sizes)}
+${group("Font weight", weights)}
+${group("Line height", lineHeights)}
+${group("Letter spacing", letterSpacings)}
+${group("Breakpoints", breakpoints)}
 ${group("Motion", motions)}
+${group("Opacity", opacities)}
+${group("Z-index", zIndices)}
 </body></html>`;
 }
 function esc(s) {
@@ -366,6 +380,529 @@ function escAttr(s) {
 function safeCss(value) {
     return value.replace(/[<>"]/g, "").slice(0, 200);
 }
+// ---------------------------------------------------------------------------
+// Design-system reference document (human/VLM-readable, advisory)
+// ---------------------------------------------------------------------------
+//
+// Pairs with design-contract.json (machine-readable): this is the "v1.0" visual
+// spec a human or VLM can read, share, or diff. It reads the source CSS so that
+// var(--x) resolves live in the browser; for non-CSS projects (Android, Flutter,
+// iOS, TS module) it falls back to rendering directly from the contract tokens.
+//
+// NOT a gate — advisory documentation only.
+export const designReferenceTool = {
+    name: "design_reference",
+    description: "Generate a self-contained HTML design-system reference (token swatches, type samples, component demos, growth-layer summary) from the Vise design contract. Human/VLM-readable; advisory, not an enforcement gate.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string", description: "Project root containing sp-vise/design-contract.json. Defaults to current directory." },
+            title: { type: "string", description: "Design system name shown in the document heading (e.g. 'Streamly'). Defaults to 'Design System'." },
+            write: { type: "boolean", description: "Write sp-vise/design-reference.html (default true)." },
+        },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = optionalStringField(args, "repoPath") ?? ".";
+        const title = optionalStringField(args, "title") ?? "Design System";
+        const write = args.write !== false;
+        const contract = await readDesignContract(repoPath);
+        if (!contract) {
+            return textResult({
+                status: "no-contract",
+                message: "No sp-vise/design-contract.json found. Run `vise design extract` first.",
+            });
+        }
+        const html = await generateDesignReference(repoPath, contract, title);
+        let written;
+        if (write) {
+            const target = path.join(path.resolve(repoPath), "sp-vise", "design-reference.html");
+            await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(target, html, "utf8");
+            written = target;
+        }
+        return textResult({
+            status: "rendered",
+            written,
+            digest: contract.digest,
+            title,
+            note: "Advisory reference document — not an enforcement gate. Open the HTML in a browser to see the full design system.",
+            where: written ? `Open ${written} in a browser.` : "Not written (write=false).",
+        });
+    },
+};
+/**
+ * Generate a self-contained HTML design-system reference from the contract.
+ * Reads source CSS files for full var() resolution; falls back to contract tokens
+ * for non-CSS projects (Android XML, Flutter Dart, iOS, TS module sources).
+ */
+export async function generateDesignReference(repoPath, contract, title) {
+    const root = path.resolve(repoPath);
+    const cssTexts = await Promise.all((contract.source?.inputs ?? []).map(async (rel) => {
+        try {
+            const info = await stat(path.join(root, rel));
+            if (info.size > MAX_FILE_BYTES)
+                return "";
+            return readFile(path.join(root, rel), "utf8");
+        }
+        catch {
+            return "";
+        }
+    }));
+    const tokenCss = cssTexts.join("\n");
+    // `ref` = how this token is referenced in a CSS style attribute.
+    // CSS projects: `var(--name)` so the token resolves live via the inlined :root.
+    // Non-CSS projects (Android/Flutter/iOS/TS module): use the concrete value directly
+    // since there is no :root to resolve from.
+    const hasCssInputs = (contract.source?.inputs ?? []).some((rel) => /\.(css|scss)$/i.test(rel));
+    let allTokens;
+    if (hasCssInputs && tokenCss.trim()) {
+        const contractNames = new Set(contract.tokens.map((t) => t.name).filter((n) => n !== null));
+        allTokens = [...tokenCss.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/gi)].map((m) => ({
+            name: m[1],
+            value: m[2].trim(),
+            ref: `var(${m[1]})`,
+            inContract: contractNames.has(m[1]),
+        }));
+    }
+    else {
+        // Non-CSS project: render from contract tokens directly, using concrete values.
+        allTokens = contract.tokens
+            .filter((t) => t.name !== null)
+            .map((t) => ({ name: t.name, value: t.value, ref: safeCss(t.value), inContract: true, category: t.category }));
+    }
+    const GROUP_DEFS = [
+        { id: "brand", label: "Brand", kind: "color", match: (n) => n.startsWith("--color-brand") },
+        { id: "bg", label: "Background", kind: "color", match: (n) => /^--color-(bg|surface|overlay)/.test(n) },
+        { id: "text", label: "Text", kind: "color", match: (n) => n.startsWith("--color-text") },
+        { id: "line", label: "Lines & semantic", kind: "color", match: (n) => /^--color-(border|success|warning|danger|info)/.test(n) },
+        { id: "font", label: "Font families", kind: "family", match: (n) => n.startsWith("--font-") },
+        { id: "fs", label: "Type scale", kind: "fontsize", match: (n) => n.startsWith("--fs-") },
+        { id: "fw", label: "Font weight", kind: "weight", match: (n) => n.startsWith("--fw-") },
+        { id: "lh", label: "Line height / tracking", kind: "chip", match: (n) => /^--(lh|ls)-/.test(n) },
+        { id: "space", label: "Spacing", kind: "space", match: (n) => n.startsWith("--space-") },
+        { id: "size", label: "Sizing (controls & icons)", kind: "size", match: (n) => /^--(size|control)-/.test(n) },
+        { id: "radius", label: "Radius", kind: "radius", match: (n) => n.startsWith("--radius-") },
+        { id: "border", label: "Border width", kind: "border", match: (n) => n.startsWith("--border-width-") },
+        { id: "shadow", label: "Elevation", kind: "shadow", match: (n) => n.startsWith("--shadow-") },
+        { id: "opacity", label: "Opacity", kind: "opacity", match: (n) => n.startsWith("--opacity-") },
+        { id: "motion", label: "Motion", kind: "chip", match: (n) => /^--(duration|ease)-/.test(n) },
+        { id: "bp", label: "Breakpoints", kind: "chip", match: (n) => n.startsWith("--bp-") },
+        { id: "z", label: "Z-index", kind: "chip", match: (n) => n.startsWith("--z-") },
+    ];
+    // Maps contract category → rendering kind; used as fallback for non-CSS tokens
+    // whose names don't carry the --prefix conventions above.
+    const CATEGORY_TO_KIND = {
+        color: "color", space: "space", radius: "radius", shadow: "shadow",
+        fontFamily: "family", fontSize: "fontsize", motion: "chip", opacity: "opacity",
+    };
+    const CATEGORY_LABEL = {
+        color: "Colors", space: "Spacing", radius: "Radius", shadow: "Elevation",
+        fontFamily: "Font families", fontSize: "Type scale", motion: "Motion", opacity: "Opacity",
+    };
+    const used = new Set();
+    const grouped = GROUP_DEFS.map((g) => {
+        const items = allTokens.filter((t) => g.match(t.name));
+        items.forEach((t) => used.add(t.name));
+        return { id: g.id, label: g.label, kind: g.kind, items };
+    }).filter((g) => g.items.length > 0);
+    // For non-CSS tokens not matched by name-prefix above, fall back to grouping by
+    // the contract category field so native projects produce a properly-sectioned doc.
+    const unmatchedByName = allTokens.filter((t) => !used.has(t.name));
+    const catBuckets = new Map();
+    const trueUngrouped = [];
+    for (const t of unmatchedByName) {
+        const cat = t.category;
+        if (cat && CATEGORY_TO_KIND[cat]) {
+            const bucket = catBuckets.get(cat) ?? [];
+            bucket.push(t);
+            catBuckets.set(cat, bucket);
+        }
+        else {
+            trueUngrouped.push(t);
+        }
+    }
+    for (const [cat, items] of catBuckets) {
+        grouped.push({ id: cat, label: CATEGORY_LABEL[cat] ?? cat, kind: CATEGORY_TO_KIND[cat] ?? "chip", items });
+    }
+    if (trueUngrouped.length > 0)
+        grouped.push({ id: "other", label: "Other", kind: "chip", items: trueUngrouped });
+    const provTag = (t) => (t.inContract === false ? ` <span class="prov">not extracted</span>` : "");
+    function renderRefItem(t, kind) {
+        const n = esc(t.name);
+        const v = esc(t.value);
+        const r = t.ref;
+        const meta = `<div class="tk-name">${n}${provTag(t)}</div><div class="tk-val">${v}</div>`;
+        switch (kind) {
+            case "color": return `<div class="tk"><div class="sw" style="background:${r}"></div>${meta}</div>`;
+            case "family": return `<div class="tk wide"><div class="fam" style="font-family:${r}">${esc(title)} — The quick brown fox</div>${meta}</div>`;
+            case "fontsize": return `<div class="tk wide"><div class="samp" style="font-size:${r}">${esc(title)} ${v}</div>${meta}</div>`;
+            case "weight": return `<div class="tk wide"><div class="samp" style="font-weight:${r};font-size:20px">${esc(title)} ${v}</div>${meta}</div>`;
+            case "space": return `<div class="tk"><div class="bar" style="width:${r}"></div>${meta}</div>`;
+            case "size": return `<div class="tk"><div class="bar" style="width:${r};height:${r};max-height:48px"></div>${meta}</div>`;
+            case "radius": return `<div class="tk"><div class="rad" style="border-radius:${r}"></div>${meta}</div>`;
+            case "border": return `<div class="tk"><div class="rad" style="border:${r} solid var(--color-border-strong,#404040)"></div>${meta}</div>`;
+            case "opacity": return `<div class="tk"><div class="sw" style="background:var(--color-brand,#e50914);opacity:${r}"></div>${meta}</div>`;
+            case "shadow": return `<div class="tk"><div class="elev" style="box-shadow:${r}"></div>${meta}</div>`;
+            default: return `<div class="tk chip">${meta}</div>`;
+        }
+    }
+    function renderTokenRow(t) {
+        return `<div class="ds-token-row"><code class="ds-token-name">${esc(t.name)}${provTag(t)}</code><code class="ds-token-pill">${esc(t.value)}</code></div>`;
+    }
+    // Super-group assignment for nav + section tags.
+    const GROUP_SUPER = {
+        brand: "COLOR", bg: "COLOR", text: "COLOR", line: "COLOR",
+        font: "TYPOGRAPHY", fs: "TYPOGRAPHY", fw: "TYPOGRAPHY", lh: "TYPOGRAPHY",
+        space: "LAYOUT", size: "LAYOUT", bp: "LAYOUT",
+        radius: "SURFACE", border: "SURFACE", shadow: "SURFACE",
+        opacity: "EFFECTS", motion: "EFFECTS", z: "EFFECTS",
+        // category-based (native projects)
+        color: "COLOR", fontFamily: "TYPOGRAPHY", fontSize: "TYPOGRAPHY",
+        other: "OTHER",
+    };
+    const SUPER_ORDER = ["COLOR", "TYPOGRAPHY", "LAYOUT", "SURFACE", "EFFECTS", "OTHER"];
+    const superNav = new Map();
+    for (const g of grouped) {
+        const sg = GROUP_SUPER[g.id] ?? "OTHER";
+        const list = superNav.get(sg) ?? [];
+        list.push(g);
+        superNav.set(sg, list);
+    }
+    const navHtml = SUPER_ORDER.filter((sg) => superNav.has(sg))
+        .map((sg) => {
+        const items = (superNav.get(sg) ?? [])
+            .map((g) => {
+            const dot = g.kind === "color" && g.items.length > 0
+                ? `style="background:${g.items[0].ref}"`
+                : `style="background:var(--color-text-faint,var(--text-subdued,#888))"`;
+            return `<a class="ds-nav-item" href="#${esc(g.id)}"><span class="ds-nav-dot" ${dot}></span>${esc(g.label)}</a>`;
+        })
+            .join("\n        ");
+        return `<div class="ds-nav-section">
+        <div class="ds-nav-group-label">${esc(sg)}</div>
+        ${items}
+      </div>`;
+    })
+        .join("\n      ");
+    const sectionsHtml = grouped
+        .map((g) => {
+        const sg = GROUP_SUPER[g.id] ?? "OTHER";
+        const useList = g.kind === "chip";
+        const body = useList
+            ? `<div class="ds-token-list">${g.items.map((t) => renderTokenRow(t)).join("")}</div>`
+            : `<div class="grid">${g.items.map((t) => renderRefItem(t, g.kind)).join("")}</div>`;
+        return `<section id="${esc(g.id)}" class="ds-section">
+        <div class="ds-section-header">
+          <div class="ds-section-tag">${esc(sg)}</div>
+          <h2 class="ds-section-title">${esc(g.label)}</h2>
+          <div class="ds-section-count">${g.items.length} token${g.items.length === 1 ? "" : "s"}</div>
+        </div>
+        ${body}
+      </section>`;
+    })
+        .join("\n      ");
+    const digestShort = esc(contract.digest.slice(0, 23));
+    const logoLetter = esc(title.slice(0, 1).toUpperCase());
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>${esc(title)} — Design System</title>
+<style>
+${tokenCss}
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+html{scroll-behavior:smooth}
+body{
+  font-family:var(--font-body,var(--encore-body-font-stack,system-ui,sans-serif));
+  background:var(--color-bg,var(--background-base,var(--bg-base,#fafafa)));
+  color:var(--color-text,var(--text-base,var(--text-primary,#1a1a1a)));
+  min-height:100vh;font-size:13px;line-height:1.5;
+}
+.ds-layout{display:flex;min-height:100vh}
+
+/* ── Sidebar ── */
+.ds-sidebar{
+  position:fixed;top:0;left:0;width:240px;height:100vh;
+  background:var(--color-surface,var(--background-elevated-base,var(--bg-elevated,#f0f0f0)));
+  border-right:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.1)));
+  display:flex;flex-direction:column;overflow:hidden;z-index:200;
+}
+.ds-sidebar-header{
+  padding:20px 16px 16px;flex-shrink:0;
+  border-bottom:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.1)));
+}
+.ds-logo{display:flex;align-items:center;gap:10px}
+.ds-logo-mark{
+  width:32px;height:32px;border-radius:6px;flex-shrink:0;
+  background:var(--color-brand,var(--essential-bright-accent,var(--action-primary,#888)));
+  display:flex;align-items:center;justify-content:center;
+  font-size:15px;font-weight:700;color:#fff;
+}
+.ds-logo-name{
+  font-size:13px;font-weight:700;line-height:1.2;
+  color:var(--color-text,var(--text-base,var(--text-primary,inherit)));
+}
+.ds-logo-sub{
+  font-size:10px;font-weight:500;letter-spacing:.08em;text-transform:uppercase;margin-top:1px;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+}
+.ds-nav{flex:1;overflow-y:auto;padding:12px 8px;scrollbar-width:thin}
+.ds-nav-section{margin-bottom:20px}
+.ds-nav-group-label{
+  font-size:10px;font-weight:600;letter-spacing:.10em;text-transform:uppercase;
+  padding:0 8px;margin-bottom:4px;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+}
+.ds-nav-item{
+  display:flex;align-items:center;gap:8px;padding:5px 8px;border-radius:6px;
+  font-size:13px;font-weight:500;
+  color:var(--color-text-muted,var(--text-subdued,var(--text-secondary,#666)));
+  text-decoration:none;cursor:pointer;transition:background .1s,color .1s;
+}
+.ds-nav-item:hover{
+  background:var(--color-surface-raised,var(--background-elevated-highlight,rgba(0,0,0,.06)));
+  color:var(--color-text,var(--text-base,var(--text-primary,inherit)));
+}
+.ds-nav-dot{width:6px;height:6px;border-radius:50%;flex-shrink:0}
+.ds-sidebar-footer{
+  padding:12px 16px;flex-shrink:0;
+  border-top:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.1)));
+  font-size:11px;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+}
+
+/* ── Main ── */
+.ds-main{flex:1;margin-left:240px;min-height:100vh}
+.ds-topbar{
+  position:sticky;top:0;z-index:150;
+  background:var(--color-overlay,rgba(0,0,0,.55));
+  backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);
+  border-bottom:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.1)));
+  padding:10px 48px;display:flex;align-items:center;justify-content:space-between;
+}
+.ds-topbar-title{
+  font-size:13px;font-weight:600;letter-spacing:.02em;
+  color:var(--color-text-muted,var(--text-subdued,#888));
+}
+.ds-topbar-meta{
+  font-size:11px;font-family:ui-monospace,'SF Mono',monospace;
+  color:var(--color-text-faint,var(--text-subdued,#aaa));
+}
+
+/* ── Section scaffold ── */
+.ds-section{
+  padding:48px;
+  border-bottom:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.06)));
+}
+.ds-section-header{margin-bottom:32px}
+.ds-section-tag{
+  font-size:10px;font-weight:600;letter-spacing:.12em;text-transform:uppercase;margin-bottom:6px;
+  color:var(--color-brand,var(--essential-bright-accent,var(--action-primary,#888)));
+}
+.ds-section-title{
+  font-family:var(--font-display,var(--encore-title-font-stack,inherit));
+  font-size:22px;font-weight:700;line-height:1.1;margin-bottom:4px;
+  color:var(--color-text,var(--text-base,var(--text-primary,inherit)));
+  transition:color .15s;
+}
+.ds-section-count{
+  font-size:12px;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+}
+section:target .ds-section-title{
+  color:var(--color-brand,var(--essential-bright-accent,var(--action-primary,#888)));
+}
+
+/* ── Swatch grid ── */
+.grid{display:flex;flex-wrap:wrap;gap:16px;align-items:flex-end}
+.tk{width:150px}
+.tk.wide{width:100%}
+.tk.chip{width:auto;
+  background:var(--color-surface,var(--background-elevated-base,rgba(0,0,0,.04)));
+  border:1px solid var(--color-border,rgba(0,0,0,.08));
+  border-radius:var(--radius-md,8px);padding:8px 12px;
+}
+.tk-name{
+  font-size:11px;font-family:ui-monospace,'SF Mono','Fira Code',monospace;margin-top:6px;
+  color:var(--color-text-muted,var(--text-subdued,var(--text-secondary,#666)));
+}
+.tk-val{
+  font-size:11px;font-family:ui-monospace,'SF Mono','Fira Code',monospace;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+}
+.prov{
+  color:var(--color-warning,var(--essential-warning,var(--status-warning,#e8a020)));
+  font-size:10px;
+}
+.sw{height:64px;border-radius:var(--radius-md,8px);border:1px solid var(--color-border,rgba(0,0,0,.1))}
+.bar{height:12px;background:var(--color-brand,var(--essential-bright-accent,#888));border-radius:3px;min-width:2px}
+.rad{
+  width:80px;height:64px;
+  background:var(--color-surface-raised,var(--background-elevated-highlight,rgba(0,0,0,.06)));
+  border:1px solid var(--color-border-strong,var(--border-default,rgba(0,0,0,.15)));
+}
+.elev{
+  width:120px;height:64px;border-radius:var(--radius-md,8px);
+  background:var(--color-surface-raised,var(--background-elevated-base,#fff));
+}
+.samp,.fam{color:var(--color-text,var(--text-base,var(--text-primary,inherit)))}
+
+/* ── Token list (motion / bp / z-index / lh) ── */
+.ds-token-list{display:flex;flex-direction:column;max-width:680px}
+.ds-token-row{
+  display:flex;align-items:baseline;gap:16px;padding:8px 0;
+  border-bottom:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.06)));
+}
+.ds-token-row:last-child{border-bottom:none}
+.ds-token-name{
+  font-size:12px;font-family:ui-monospace,'SF Mono','Fira Code',monospace;
+  color:var(--color-text-muted,var(--text-subdued,var(--text-secondary,#666)));
+  min-width:220px;flex-shrink:0;
+}
+.ds-token-pill{
+  font-size:11px;font-family:ui-monospace,'SF Mono','Fira Code',monospace;
+  background:var(--color-surface-raised,var(--background-elevated-base,rgba(0,0,0,.05)));
+  color:var(--color-text,var(--text-base,inherit));
+  border-radius:4px;padding:2px 8px;
+}
+
+/* ── Components ── */
+.comps{display:flex;gap:12px;flex-wrap:wrap;align-items:center}
+.btn{
+  border:none;cursor:pointer;font-weight:var(--fw-medium,500);
+  font-size:var(--fs-sm,var(--encore-text-size-smaller,13px));
+  padding:8px 20px;
+  border-radius:var(--radius-sm,var(--encore-corner-radius-base,4px));
+  font-family:inherit;transition:opacity .12s;
+}
+.btn-primary{
+  background:var(--color-brand,var(--essential-bright-accent,#888));
+  color:var(--color-text-on-brand,var(--text-bright-accent,#fff));
+}
+.btn-secondary{
+  background:var(--color-surface-raised,var(--background-elevated-base,rgba(0,0,0,.06)));
+  color:var(--color-text,var(--text-base,inherit));
+  border:1px solid var(--color-border,rgba(0,0,0,.1));
+}
+.card{
+  width:200px;height:112px;
+  background:var(--color-surface,var(--background-elevated-base,#f4f4f4));
+  border-radius:var(--radius-md,var(--encore-corner-radius-larger-2,8px));
+  box-shadow:var(--shadow-2,var(--encore-overlay-box-shadow,0 4px 12px rgba(0,0,0,.2)));
+  display:flex;align-items:flex-end;padding:12px;
+  border:1px solid var(--color-border,rgba(0,0,0,.08));
+}
+.badge{
+  background:var(--color-brand,var(--essential-bright-accent,#888));
+  color:var(--color-text-on-brand,#fff);font-size:11px;padding:2px 8px;
+  border-radius:var(--radius-pill,var(--encore-border-radius-rounded,999px));
+}
+
+/* ── Growth layer ── */
+.growth-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:16px}
+.growth-card{
+  padding:16px;border-radius:var(--radius-md,8px);
+  background:var(--color-surface-raised,var(--background-elevated-base,rgba(0,0,0,.03)));
+  border:1px solid var(--color-border,var(--border-subtle,rgba(0,0,0,.08)));
+}
+.growth-card-title{
+  font-size:13px;font-weight:600;margin-bottom:4px;
+  color:var(--color-text,var(--text-base,inherit));
+}
+.growth-card-desc{
+  font-size:12px;line-height:1.5;
+  color:var(--color-text-faint,var(--text-subdued,#888));
+}
+
+/* ── Footer ── */
+.ds-footer{
+  padding:24px 48px;font-size:11px;
+  color:var(--color-text-faint,var(--text-subdued,var(--text-tertiary,#888)));
+  border-top:1px solid var(--color-border,rgba(0,0,0,.06));
+}
+</style></head>
+<body>
+<div class="ds-layout">
+
+  <aside class="ds-sidebar">
+    <div class="ds-sidebar-header">
+      <div class="ds-logo">
+        <div class="ds-logo-mark">${logoLetter}</div>
+        <div>
+          <div class="ds-logo-name">${esc(title.toUpperCase())}</div>
+          <div class="ds-logo-sub">Design System</div>
+        </div>
+      </div>
+    </div>
+    <nav class="ds-nav">
+      ${navHtml}
+      <div class="ds-nav-section">
+        <div class="ds-nav-group-label">REFERENCE</div>
+        <a class="ds-nav-item" href="#components"><span class="ds-nav-dot" style="background:var(--color-brand,var(--essential-bright-accent,#888))"></span>Components</a>
+        <a class="ds-nav-item" href="#growth"><span class="ds-nav-dot" style="background:var(--color-text-faint,#888)"></span>Growth layer</a>
+      </div>
+    </nav>
+    <div class="ds-sidebar-footer">
+      <div>v1.0 &middot; ${digestShort}</div>
+      <div style="margin-top:2px">${contract.tokens.length} tokens extracted</div>
+    </div>
+  </aside>
+
+  <div class="ds-main">
+    <div class="ds-topbar">
+      <span class="ds-topbar-title">${esc(title)} &mdash; Design Reference</span>
+      <span class="ds-topbar-meta">${digestShort}</span>
+    </div>
+    <main>
+      ${sectionsHtml}
+      <section id="components" class="ds-section">
+        <div class="ds-section-header">
+          <div class="ds-section-tag">REFERENCE</div>
+          <h2 class="ds-section-title">Component Samples</h2>
+          <div class="ds-section-count">built from the tokens above</div>
+        </div>
+        <div class="comps">
+          <button class="btn btn-primary">&#9654; Play</button>
+          <button class="btn btn-secondary">+ My List</button>
+          <span class="badge">NEW</span>
+          <div class="card"><span style="font-size:12px;color:var(--color-text-muted,var(--text-subdued,#888))">${esc(title)}</span></div>
+        </div>
+      </section>
+      <section id="growth" class="ds-section">
+        <div class="ds-section-header">
+          <div class="ds-section-tag">GROWTH LAYER</div>
+          <h2 class="ds-section-title">Extends This Template</h2>
+          <div class="ds-section-count">advisory — not an enforcement gate</div>
+        </div>
+        <div class="growth-grid">
+          <div class="growth-card">
+            <div class="growth-card-title">Component specs &#10003;</div>
+            <div class="growth-card-desc">Buttons, card, badge shown above. Every component is a composition of the tokens in this document.</div>
+          </div>
+          <div class="growth-card">
+            <div class="growth-card-title">Usage guidelines</div>
+            <div class="growth-card-desc">Do / don&apos;t, when-to-use, pairing rules per token group. Defined by the team, not by extraction.</div>
+          </div>
+          <div class="growth-card">
+            <div class="growth-card-title">Accessibility</div>
+            <div class="growth-card-desc">Contrast ratios, focus states, motion-reduce overrides. Requires computation against real backgrounds.</div>
+          </div>
+        </div>
+        <p style="margin-top:20px;font-size:12px;color:var(--color-text-faint,var(--text-subdued,#888))">
+          The token taxonomy above is the <strong>minimum template</strong> — deterministically extracted, never fabricated.
+          Components, usage guidelines, and accessibility are the advisory growth layer: they extend the source-of-truth tokens but are never gates.
+        </p>
+      </section>
+    </main>
+    <footer class="ds-footer">
+      Generated by Vise design-reference &mdash; advisory documentation, not an enforcement gate.
+      Contract digest: ${esc(contract.digest)}. Source: ${esc((contract.source?.inputs ?? []).join(", "))}.
+    </footer>
+  </div>
+
+</div>
+</body></html>`;
+}
 const ADVISORY_NOTE = "Advisory only — non-blocking and NOT part of `vise check`. One-off literals (overlays, scrims, pure #fff/#000, gradients) are expected and fine; off-contract literals are review hints, not violations.";
 export const designCheckTool = {
     name: "design_check",
@@ -912,14 +1449,21 @@ function categorizeDeclaredVar(name, value) {
     if (/radius|radii|corner|\bround/.test(n)) {
         return "radius";
     }
+    // borderWidth: name-and-value gated, MUST come before the color branch because
+    // the color regex matches /border/ — `--border-width-thin: 1px` is a length, not a color.
+    if (/border-?width|stroke-?width|outline-?width/.test(n) && LENGTH.test(v)) {
+        return "borderWidth";
+    }
     if (/(color|colour|bg|background|fg|foreground|surface|border|brand|primary|secondary|accent|fill|stroke|ink|text-color)/.test(n) || isColor(v)) {
         return "color";
     }
     if (/(font-family|fontfamily|typeface|family)/.test(n) && /[a-z]/i.test(v) && !LENGTH.test(v) && !isColor(v)) {
         return "fontFamily";
     }
-    if (/(font-size|fontsize|text-size|leading|line-height)/.test(n) || /\btext-(xs|sm|base|md|lg|xl|\dxl|\d)\b/.test(n)) {
-        return "fontSize"; // incl. the Tailwind text-scale convention (--text-sm/base/lg)
+    // fontSize: broaden to include the common --fs-* naming convention (e.g. --fs-sm: 14px).
+    // 'leading' and 'line-height' are moved to lineHeight below.
+    if (/(font-size|fontsize|text-size)/.test(n) || /\btext-(xs|sm|base|md|lg|xl|\dxl|\d)\b/.test(n) || /^--fs-\w/.test(n)) {
+        return "fontSize"; // incl. the Tailwind text-scale convention (--text-sm/base/lg) and --fs-* shorthand
     }
     // Motion is value-gated: only time/easing values become motion tokens. This
     // stops substring matches like "increase"/"decrease" (which contain "ease")
@@ -935,6 +1479,30 @@ function categorizeDeclaredVar(name, value) {
     if (/(font|type)/.test(n) && /[a-z]/i.test(v) && !LENGTH.test(v) && !isColor(v) && !TIME.test(v)) {
         return "fontFamily";
     }
+    // fontWeight: name-gated (bare integers collide with z-index). Value must be a
+    // 3-digit integer in the valid CSS font-weight range 100–950.
+    if (/\bfw\b|font-?weight|\bweight\b/.test(n)) {
+        const num = Number(v);
+        if (/^\d{3}$/.test(v) && num >= 100 && num <= 950) {
+            return "fontWeight";
+        }
+    }
+    // lineHeight: name-gated + unitless value (1.1, 1.4, 1.6 etc.). Captures both
+    // 'lh-*' shorthand and 'leading-*'/'line-height-*' naming conventions.
+    if (/\blh\b|leading|line-?height|lineheight/.test(n) && /^-?[0-9]*\.?[0-9]+$/.test(v) && !LENGTH.test(v)) {
+        return "lineHeight";
+    }
+    // letterSpacing: name-gated + any CSS length. Must come before the generic
+    // LENGTH→space fallback so --ls-* tokens aren't misfiled as spacing.
+    if (/\bls\b|letter-?spacing|letterspacing|\btracking\b/.test(n) && LENGTH.test(v)) {
+        return "letterSpacing";
+    }
+    // breakpoint: name-gated + length. Must precede the LENGTH fallback. The
+    // contract already captures @media breakpoints in contract.breakpoints[]; this
+    // catches explicit --bp-* / --breakpoint-* custom-property tokens.
+    if (/\bbp\b|break-?point|viewport-?width|screen-?size/.test(n) && LENGTH.test(v)) {
+        return "breakpoint";
+    }
     if (/(space|spacing|gap|size|gutter|inset|pad|margin)/.test(n) && LENGTH.test(v)) {
         return "space";
     }
@@ -944,6 +1512,16 @@ function categorizeDeclaredVar(name, value) {
     if (LENGTH.test(v)) {
         return "space";
     }
+    // Opacity: declared-only (a bare 0.4 in code could be line-height/scale/anything — never infer).
+    if (/opacity/.test(n) && /^(0(\.\d+)?|\.\d+|1(\.0*)?)$/.test(v)) {
+        return "opacity";
+    }
+    // zIndex: name-gated strictly; integers collide with fontWeight so the name is
+    // the only reliable signal. Use z-index / z-idx or the common --z-* prefix.
+    // Note: bare `/z/` would catch --zoom, --size, etc. — do NOT relax this guard.
+    if ((/z-?index|z-?idx/.test(n) || /^--z-\w/.test(n)) && /^-?\d+$/.test(v)) {
+        return "zIndex";
+    }
     return null;
 }
 /** Emit zero or more (category, normalizedValue) observations from one literal declaration. */
@@ -1118,7 +1696,7 @@ function friendlyComponentName(cls) {
 // ---------------------------------------------------------------------------
 // Sorting, summarizing, digest
 // ---------------------------------------------------------------------------
-const CATEGORY_ORDER = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "motion"];
+const CATEGORY_ORDER = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "borderWidth", "breakpoint", "motion", "opacity", "zIndex"];
 function sortTokens(tokens) {
     return [...tokens].sort((a, b) => {
         const cat = CATEGORY_ORDER.indexOf(a.category) - CATEGORY_ORDER.indexOf(b.category);
@@ -1435,8 +2013,11 @@ function categorizeTokenModuleValue(keyPath, value) {
         return null; // reference / computed — not a concrete token
     }
     const key = keyPath.toLowerCase();
-    if (/screen|breakpoint|media|z-?index|opacity|weight/.test(key)) {
-        return null; // not a design token we model (or handled as breakpoints elsewhere)
+    // These categories are CSS-only (declared custom properties): the name-gating
+    // that makes them safe against false positives only works in CSS. Module/native
+    // extraction skips them rather than risk inventing wrong tokens.
+    if (/screen|breakpoint|media|z-?index|opacity|weight|\blh\b|leading|line-?height|letter-?spacing/.test(key)) {
+        return null;
     }
     // Colors: unambiguous from the value alone.
     if (isColor(v)) {

package/dist/tools/project.js

@@ -499,8 +499,16 @@ async function validateEnvSecretHygiene(root, platform, sourceContent) {
     const findings = [];
     if (platform === "typescript") {
         const envSecretFiles = await committedEnvSecretFiles(root);
-        for (const file of envSecretFiles) {
-            findings.push(finding("typescript.secret.committed-env", "warning", "A local env file appears to contain a social.plus secret.", file, "Do not commit .env files with real API keys. Commit a placeholder .env.example and keep local env files ignored."));
+        if (envSecretFiles.length > 0) {
+            // Only fire when the secret-bearing env file is NOT gitignored. A gitignored local `.env` (the
+            // exact practice this rule's own recommendation endorses) won't be committed, so flagging it is
+            // a false positive — committed-env is about a `.env` that WILL be committed (no .gitignore cover).
+            const gitignore = await readIfExists(path.join(root, ".gitignore"));
+            if (!gitignore || !gitignoreIgnoresEnvFiles(gitignore)) {
+                for (const file of envSecretFiles) {
+                    findings.push(finding("typescript.secret.committed-env", "warning", "A local env file appears to contain a social.plus secret.", file, "Do not commit .env files with real API keys. Commit a placeholder .env.example and keep local env files ignored."));
+                }
+            }
         }
     }
     if (platform === "typescript" || platform === "react-native") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",