@amityco/social-plus-vise 1.3.0 → 1.4.1

package/dist/tools/creative.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { platformCapabilityAvailability } from "../capabilities.js";
+import { platformFeatureGapsForObjects } from "../outcomes.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { inspectProject } from "./project.js";
@@ -195,27 +196,27 @@ export async function buildCreativeBrief(options) {
         candidateSolutions: candidates,
         selectionGuidance: {
             mode: "agent-grounded-selection",
-            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. Vise will validate (ground) your choice against the catalog; it does not infer the variant for you.",
+            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. Before accepting a variant, present an EI choice block to the user: recommended experience, 2-3 concrete request/project signals, 2-3 credible alternatives with when-to-choose/tradeoffs, expected blueprint surfaces/objects, and the no-fit option. Do not collapse EI into a one-sentence recommendation or accept before the choice is visible. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. Vise will validate (ground) your choice against the catalog; it does not infer the variant for you.",
             howToAccept: "vise creative accept <repoPath> --variant <candidate id> --rationale \"<one line, grounded in the request and catalog>\" --confidence high|medium|low",
             contract: {
                 variant: "A candidateSolutions id chosen by best fit to the request (not by listed order or the fallbackDefault flag).",
                 fallbackDefault: "One candidate carries fallbackDefault=true: the keyword top, used as the default ONLY when no agent makes a grounded selection. Do not defer to it; decide by fit.",
                 rationale: "Required: one line explaining, grounded in the request and the candidate's catalog fit, why this variant. A selection without a rationale is rejected.",
                 confidence: "high | medium | low. Use low when the request is vague or genuinely split between variants; low/missing confidence is recorded as a review signal, not a failure.",
-                noFit: "If no candidate genuinely fits the request, do not force one. Record the no-fit instead: `vise creative accept <repoPath> --variant none --rationale \"<what the catalog is missing>\" [--closest <nearest variant id>]`. This writes a local catalog-gap record for human review (it does not change the catalog or upload anything); it is a signal the catalog may need a new variant.",
+                noFit: "If no candidate genuinely fits the request, do not force one. Record the no-fit instead: `vise creative accept <repoPath> --variant none --rationale \"<what the catalog is missing>\" --confidence high|medium|low [--closest <nearest variant id>]`. This writes a local catalog-gap record for human review (it does not change the catalog or upload anything); it is a signal the catalog may need a new variant.",
             },
         },
         questions: [
             {
                 id: "preferred_solution",
-                question: "Which creative variant best fits this request, and why?",
+                question: "Which EI experience should be selected after presenting the recommendation, alternatives, tradeoffs, expected blueprint surfaces, and no-fit option?",
                 why: "Creative mode proposes product/UX directions. The driving agent selects the best-fitting variant and accepts it with a grounded rationale and confidence (see selectionGuidance); normal Vise planning starts only after a variant is accepted.",
                 required: true,
                 blocksImplementationWhenMissing: true,
                 options: candidates.map((candidate) => candidate.id),
             },
         ],
-        nextStep: "Choose the best-fitting variant for the request by reasoning over candidateSolutions (listed order is advisory), then accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. Vise validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\"`.",
+        nextStep: "Present the EI choice block first: recommended experience, concrete fit signals, credible alternatives/tradeoffs, expected blueprint surfaces/objects, and no-fit option. Then choose the best-fitting variant by reasoning over candidateSolutions (listed order is advisory) and accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. Vise validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\" --confidence high|medium|low`.",
     };
     if (options.rankingPreview === true) {
         brief.candidateRankingPreview = buildCandidateRankingPreview(brief);
@@ -242,12 +243,9 @@ export async function acceptCreativeVariant(options) {
     if (!selected) {
         throw new Error(`Creative variant "${variantId}" was not found in ${repoRelativePath(repoRoot, briefPath)}. Available variants: ${brief.candidateSolutions.map((candidate) => candidate.id).join(", ") || "(none)"}.`);
     }
-    let grounding;
-    if (options.rationale !== undefined || options.confidence !== undefined) {
-        grounding = groundSelection({ variantId, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
-        if (grounding.status === "rejected") {
-            throw new Error(`Grounded selection for "${variantId}" was rejected: ${grounding.signals.filter((signal) => signal.severity === "error").map((signal) => signal.message).join(" ")}`);
-        }
+    const grounding = groundSelection({ variantId, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
+    if (grounding.status === "rejected") {
+        throw new Error(`Grounded selection for "${variantId}" was rejected: ${grounding.signals.filter((signal) => signal.severity === "error").map((signal) => signal.message).join(" ")}`);
     }
     const selection = {
         schema_version: CREATIVE_SELECTION_SCHEMA_VERSION,
@@ -263,7 +261,7 @@ export async function acceptCreativeVariant(options) {
         },
         objective: brief.objective,
         selectedVariant: selected,
-        ...(grounding ? { grounding } : {}),
+        grounding,
         implementationContext: {
             planRequest: `${selected.title}: ${brief.request}`,
             surfaceHints: creativeSurfaceHints(selected),
@@ -560,9 +558,13 @@ async function feasibilityForVariant(variant, inspection) {
     if (outcomes.length === 0) {
         notes.push("No current Vise outcome maps directly to this variant yet; treat it as exploratory product guidance.");
     }
+    const objectGaps = platform === "unknown" ? [] : platformFeatureGapsForObjects(variant.experienceObjectIds, platform);
+    for (const { gap, objects } of objectGaps) {
+        notes.push(`References experience object(s) ${objects.join(", ")} not available in the ${platform} SDK (${gap.feature} — available on ${gap.availableOn.join("/")}). See platformAvailability; this variant is not buildable as specified on ${platform}.`);
+    }
     return {
         platform,
-        support: supportFor(outcomeResults, customObjectIds),
+        support: objectGaps.length > 0 ? "references-unavailable-objects" : supportFor(outcomeResults, customObjectIds),
         outcomes: outcomeResults,
         customObjectIds,
         notes,

package/dist/tools/design.js

@@ -13,6 +13,21 @@ const MAX_PROTOTYPE_FILES = 300;
 const MAX_SCAN_FILES = 2000;
 const OFF_CONTRACT_SAMPLE = 20;
 const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".dart", ".kt", ".java", ".swift", ".css", ".scss", ".vue", ".xml"]);
+const UIKIT_JSON_DENY = new Set([
+    "package.json", "package-lock.json", "tsconfig.json", "jsconfig.json", "manifest.json",
+    "app.json", "babel.config.json", "components.json", "design-contract.json", "design-profile.json",
+]);
+function isUikitThemeConfigCandidate(file) {
+    const base = path.basename(file).toLowerCase();
+    if (UIKIT_JSON_DENY.has(base) || base.startsWith("tsconfig.") || base.endsWith(".lock") || base.endsWith("-lock.json")) {
+        return false;
+    }
+    return base === "uikit.config.json" || base === "config.json" || /uikit/.test(base);
+}
+function looksLikeUikitThemeConfig(content) {
+    return /"preferred_theme"\s*:/.test(content) ||
+        (/"theme"\s*:/.test(content) && /"(?:primary_color|secondary_color|base_color|background_color)"\s*:/.test(content));
+}
 const MODULE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const MAX_FILE_BYTES = 2_000_000;
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", "vendor", ".turbo", ".cache"]);
@@ -99,6 +114,7 @@ export async function extractDesignContractFromProject(repoPath) {
     const root = path.resolve(repoPath);
     const files = await findProjectDesignFiles(root);
     const css = [];
+    const htmlSources = [];
     const moduleTokens = [];
     const inputs = [];
     for (const abs of files) {
@@ -119,6 +135,10 @@ export async function extractDesignContractFromProject(repoPath) {
             css.push(content);
             inputs.push(rel);
         }
+        else if (ext === ".html" || ext === ".htm" || ext === ".vue" || ext === ".svelte") {
+            htmlSources.push(content);
+            inputs.push(rel);
+        }
         else if (MODULE_EXTS.has(ext)) {
             const tokens = extractTokensFromModule(content);
             if (tokens.length > 0) {
@@ -155,6 +175,13 @@ export async function extractDesignContractFromProject(repoPath) {
                 inputs.push(rel);
             }
         }
+        else if (ext === ".kt") {
+            const tokens = extractTokensFromKotlin(content);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
     }
     inputs.sort();
     const input_digests = {};
@@ -165,7 +192,7 @@ export async function extractDesignContractFromProject(repoPath) {
         }
         catch { }
     }
-    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, input_digests, file_count: inputs.length }, moduleTokens);
+    return buildDesignContract({ css, html: htmlSources, inputs }, { kind: "host-project", inputs, input_digests, file_count: inputs.length }, moduleTokens);
 }
 export async function writeDesignContract(repoPath, contract) {
     const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
@@ -188,6 +215,145 @@ export async function readDesignContract(repoPath) {
         return null;
     }
 }
+export const DESIGN_PROFILE_FILENAME = "design-profile.json";
+export const BRAND_PROFILE_PROTOCOL = [
+    "Author sp-vise/design-profile.json to ground social.plus UI in the host's BRAND, not just its tokens.",
+    "A capable agent produces it by examining the host app's REAL screens (screenshots / live UI), capturing what a token scrape misses:",
+    '  - schemaVersion: "0.1.0"',
+    "  - essence: one sentence of the brand identity",
+    "  - personality: 4-7 adjectives ; voice: the tone of UI microcopy this brand uses",
+    '  - palette: [{ role: "bg|surface|text|textDim|accent|accentText|line", hex, note }] — colors WITH ROLES (which color does what), incl. how the accent is rationed',
+    "  - typography: { headingFamily, bodyFamily, headingStyle, scaleNote, letterSpacing }",
+    '  - density: "dense|comfortable|airy" + rhythm note ; elevation: "flat|soft-shadow|strong"',
+    "  - motion: implied motion energy ; imagery: gradient-heavy | photographic | minimal-illustrative | iconographic",
+    "  - do: 4-6 concrete on-brand directives ; avoid: 3-5 off-brand things",
+    "Then build each surface honoring this profile (palette ROLES, type treatment, density, shape, voice).",
+    "Advisory — it grounds generation; it never gates `vise check`.",
+].join("\n");
+const REQUIRED_PROFILE_STRINGS = ["essence", "voice", "density", "elevation", "motion", "imagery"];
+export function validateDesignProfile(raw) {
+    if (!raw || typeof raw !== "object") {
+        return null;
+    }
+    const p = raw;
+    if (typeof p.schemaVersion !== "string") {
+        return null;
+    }
+    for (const f of REQUIRED_PROFILE_STRINGS) {
+        if (typeof p[f] !== "string" || p[f].trim().length === 0) {
+            return null;
+        }
+    }
+    const isStrArr = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+    if (!isStrArr(p.personality) || !isStrArr(p.do) || !isStrArr(p.avoid)) {
+        return null;
+    }
+    if (!Array.isArray(p.palette) ||
+        !p.palette.every((e) => e &&
+            typeof e === "object" &&
+            typeof e.role === "string" &&
+            typeof e.hex === "string")) {
+        return null;
+    }
+    if (!p.typography || typeof p.typography !== "object") {
+        return null;
+    }
+    return raw;
+}
+export async function readDesignProfile(repoPath) {
+    const target = path.join(path.resolve(repoPath), "sp-vise", DESIGN_PROFILE_FILENAME);
+    try {
+        return validateDesignProfile(JSON.parse(await readFile(target, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeDesignProfile(repoPath, profile) {
+    const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
+    await mkdir(sidecarDir, { recursive: true });
+    const target = path.join(sidecarDir, DESIGN_PROFILE_FILENAME);
+    await writeFile(target, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    return target;
+}
+function hexToRgb(value) {
+    const h = normalizeHex(value.trim().startsWith("#") ? value.trim() : `#${value.trim()}`);
+    const m = /^#([0-9a-f]{6})$/.exec(h);
+    if (!m) {
+        return null;
+    }
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+export function contrastRatio(a, b) {
+    const ca = hexToRgb(a);
+    const cb = hexToRgb(b);
+    if (!ca || !cb) {
+        return null;
+    }
+    const lum = ([r, g, bl]) => {
+        const channel = (c) => {
+            const s = c / 255;
+            return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+        };
+        return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(bl);
+    };
+    const la = lum(ca);
+    const lb = lum(cb);
+    const hi = Math.max(la, lb);
+    const lo = Math.min(la, lb);
+    return Math.round(((hi + 0.05) / (lo + 0.05)) * 100) / 100;
+}
+const DESIGN_REVIEW_STATES = [
+    "empty — first post / no messages yet: an inviting empty state, not a blank screen",
+    "loading — skeletons matching the real layout, not a bare spinner",
+    "error — a human message + a retry affordance, not a dead end",
+];
+export function paletteContrastChecks(palette) {
+    const byRole = (role) => palette.find((p) => p.role.toLowerCase().trim() === role)?.hex;
+    const bg = byRole("bg") ?? byRole("surface") ?? byRole("background");
+    const text = byRole("text");
+    const textDim = byRole("textdim");
+    const accent = byRole("accent");
+    const accentText = byRole("accenttext");
+    const checks = [];
+    const add = (pair, fg, on, threshold, note) => {
+        if (!fg || !on) {
+            return;
+        }
+        const ratio = contrastRatio(fg, on);
+        if (ratio == null) {
+            return;
+        }
+        checks.push({ pair, ratio, threshold, passes: ratio >= threshold, ...(note ? { note } : {}) });
+    };
+    add("body text on background", text, bg, 4.5);
+    add("dim/secondary text on background", textDim, bg, 4.5);
+    add("text on accent (e.g. a button label)", accentText, accent, 4.5, "the white-on-bright trap: a label on an accent fill must clear 4.5:1");
+    add("accent against background", accent, bg, 3.0, "accent used for icons/borders needs 3:1; if you put TEXT in the raw accent it needs 4.5:1 — otherwise reserve the accent for fills");
+    return checks;
+}
+export function buildDesignReviewLoop(profile) {
+    const accessibility = paletteContrastChecks(profile.palette);
+    const paletteDiscipline = profile.palette
+        .filter((p) => p.note != null && p.note.trim().length > 0)
+        .map((p) => `${p.role} (${p.hex}): ${p.note.trim()}`);
+    return {
+        status: "custom-ui",
+        note: "Advisory generation-time self-check for the FIRST custom-UI build of this surface — render it, score it against the checks below, and iterate. vise never edits your code and this never gates `vise check`; your own design choices (and edits to sp-vise/design-profile.json) are authority. It is not an ongoing audit of work you've already tuned.",
+        protocol: [
+            "Build the surface honouring brandGrounding — palette ROLES, type treatment, density, voice — not just the hex values.",
+            "Render what you built (headless browser / your preview tooling) and actually look at it.",
+            "Score the render against the checks below: brandAvoids, paletteDiscipline, the computed accessibility ratios, statesRequired, and 'does it read as intentionally designed, not framework-default?'.",
+            "Do NOT eyeball contrast. For every text/icon colour you use that is NOT one of the palette pairs above (e.g. a one-off 'subtle' grey), compute it with `vise design contrast <foreground> <background>` and don't ship a pair below 4.5:1 (3:1 for large/bold text) — a faint colour that looks fine on a bright screen routinely fails.",
+            "Fix each failure and re-render. Iterate up to 3 rounds; stop when the checks are clean. Don't ship a round with a failing accessibility pair.",
+        ],
+        brandAvoids: profile.avoid,
+        paletteDiscipline,
+        accessibility,
+        statesRequired: DESIGN_REVIEW_STATES,
+    };
+}
 export async function writeDesignPreview(repoPath, contract, referencePath) {
     const check = await runDesignCheck(repoPath).catch(() => null);
     const reference = referencePath ? await readReferenceHtml(referencePath) : null;
@@ -232,8 +398,19 @@ export const designPreviewTool = {
             written,
             digest: contract.digest,
             strength: contract.stats.strength,
+            ...(contract.source.self_referential ? { self_referential: true } : {}),
             referenceEmbedded: Boolean(reference),
-            conformance: check && check.status === "advisory" ? { coverage: `${check.tokenCoverage?.referenced}/${check.tokenCoverage?.declared_total}`, off_contract: check.colorLiterals?.off_contract } : "no UI code scanned",
+            conformance: check && check.status === "advisory"
+                ? {
+                    coverage: `${check.tokenCoverage?.referenced}/${check.tokenCoverage?.declared_total}`,
+                    off_contract: check.colorLiterals?.off_contract,
+                    off_contract_ratio: check.colorLiterals?.off_contract_ratio,
+                    ...(check.colorLiterals?.palette_review ? { palette_review: check.colorLiterals.palette_review } : {}),
+                }
+                : "no UI code scanned",
+            ...(contract.source.self_referential
+                ? { self_referential_note: "Contract derived from this project's own files (--from-project): conformance is circular and is NOT a design-quality signal. For a real design target, extract from an external prototype/theme." }
+                : {}),
             note: "Open the HTML to visually compare the contract (and embedded reference, if HTML) against your app. A human or VLM judges the visual match — this is not an automated pixel diff.",
             where: written ? `Open ${written} in a browser.` : "Not written (write=false).",
         });
@@ -1080,6 +1257,50 @@ export const designCheckTool = {
         return textResult(await runDesignCheck(optionalStringField(args, "repoPath") ?? "."));
     },
 };
+export function designContrastReport(foreground, background) {
+    const fg = typeof foreground === "string" ? foreground : "";
+    const bg = typeof background === "string" ? background : "";
+    const ratio = contrastRatio(fg, bg);
+    if (ratio == null) {
+        return {
+            status: "invalid",
+            message: `Could not parse a colour. Expected hex like #5a6477 or #abc. Got foreground="${fg}", background="${bg}".`,
+        };
+    }
+    const verdict = ratio >= 7.0
+        ? "Excellent — clears WCAG AAA for body text."
+        : ratio >= 4.5
+            ? "Passes WCAG AA for body text."
+            : ratio >= 3.0
+                ? "Passes AA only for LARGE/bold text (≥18.66px bold or ≥24px) and UI/graphics — FAILS for normal body text."
+                : "FAILS WCAG AA — unreadable as text. Choose a colour with more contrast against the background.";
+    return {
+        status: "ok",
+        foreground: fg,
+        background: bg,
+        ratio,
+        passes: { aaNormal: ratio >= 4.5, aaLarge: ratio >= 3.0, aaaNormal: ratio >= 7.0 },
+        verdict,
+        note: "WCAG 2.x contrast ratio (1–21). Advisory — never gates `vise check`.",
+    };
+}
+export const designContrastTool = {
+    name: "design_contrast",
+    description: "Compute the WCAG 2.x contrast ratio between two colours (advisory). Use it to check any text/icon colour you use that is NOT one of your brand palette's role pairs — never eyeball contrast.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            foreground: { type: "string", description: "Foreground (text/icon) colour, e.g. #5a6477" },
+            background: { type: "string", description: "Background colour it sits on, e.g. #0e1726" },
+        },
+        required: ["foreground", "background"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(designContrastReport(optionalStringField(args, "foreground"), optionalStringField(args, "background")));
+    },
+};
 export async function runDesignCheck(repoPath) {
     const repoRoot = path.resolve(repoPath);
     const contract = await readDesignContract(repoRoot);
@@ -1091,7 +1312,12 @@ export async function runDesignCheck(repoPath) {
         };
     }
     const staleContract = await checkContractFreshness(repoRoot, contract);
-    const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => SCAN_EXTS.has(path.extname(file).toLowerCase()));
+    const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => {
+        const ext = path.extname(file).toLowerCase();
+        if (SCAN_EXTS.has(ext))
+            return true;
+        return ext === ".json" && isUikitThemeConfigCandidate(file);
+    });
     if (files.length === 0) {
         return { status: "no-sources", message: "No UI source files found to check against the contract.", contract: contractSummary(contract), note: ADVISORY_NOTE };
     }
@@ -1118,6 +1344,9 @@ export async function runDesignCheck(repoPath) {
         catch {
             continue;
         }
+        if (path.extname(file).toLowerCase() === ".json" && !looksLikeUikitThemeConfig(content)) {
+            continue;
+        }
         scanned += 1;
         const rel = path.relative(repoRoot, file);
         const isCss = file.toLowerCase().endsWith(".css") || file.toLowerCase().endsWith(".scss");
@@ -1160,14 +1389,33 @@ export async function runDesignCheck(repoPath) {
         .map((token) => token.name ?? token.value);
     const contractTokenNames = new Set(contract.tokens.map((token) => token.name).filter((name) => Boolean(name)));
     const undefinedRefs = dedupeByToken(varRefs.filter((ref) => !definedVars.has(ref.token) && !contractTokenNames.has(ref.token)));
+    const offContract = totalColors - onContract;
+    const offContractRatio = totalColors > 0 ? offContract / totalColors : 0;
+    const paletteReview = totalColors >= 10 && offContractRatio >= 0.5
+        ? `${offContract} of ${totalColors} color literals (${Math.round(offContractRatio * 100)}%) are off-contract — the palette is mostly ad-hoc hardcoded colors, not token-driven. Worth a human's eyes on visual coherence.`
+        : undefined;
+    const selfRefNote = contract.source.self_referential
+        ? `Contract is SELF-REFERENTIAL (derived from this project's own files via --from-project): token-coverage measures internal reuse, not conformance to an external/authoritative design — not a design-quality signal. For that, extract from a real prototype/theme. `
+        : "";
+    const profile = await readDesignProfile(repoRoot);
+    const palettePairs = profile ? paletteContrastChecks(profile.palette) : [];
+    const accessibility = palettePairs.length > 0
+        ? {
+            palettePairs,
+            failing: palettePairs.filter((c) => !c.passes).length,
+            note: "Computed WCAG contrast for your brand palette's role pairs (advisory, never gates). A failing pair means that combination is unreadable — fix the palette or don't use it for text. Don't eyeball one-off colours: run `vise design contrast <fg> <bg>`.",
+        }
+        : undefined;
     return {
         status: "advisory",
-        message: `Checked ${scanned} source file(s) against design contract ${contract.digest}. ` +
+        message: selfRefNote +
+            `Checked ${scanned} source file(s) against design contract ${contract.digest}. ` +
+            (paletteReview ? `${paletteReview} ` : "") +
             `${referencedTokens.length}/${declaredTokens.length} declared tokens referenced` +
             (seededOnlyTokens.length > 0
                 ? ` (${referencedTokens.length - seededOnlyTokens.length} used in your code, ${seededOnlyTokens.length} only in the Vise-seeded ${SP_TOKENS_PATH} — apply them to count)`
                 : "") +
-            `; ${totalColors - onContract} of ${totalColors} color literal(s) are off-contract (review hints)` +
+            `; ${offContract} of ${totalColors} color literal(s) are off-contract (review hints)` +
             (undefinedRefs.length > 0 ? `; ${undefinedRefs.length} undefined token reference(s) (likely broken styles)` : "") +
             ".",
         contract: contractSummary(contract),
@@ -1183,13 +1431,16 @@ export async function runDesignCheck(repoPath) {
             scanned_files: scanned,
             total: totalColors,
             on_contract: onContract,
-            off_contract: totalColors - onContract,
+            off_contract: offContract,
+            off_contract_ratio: Math.round(offContractRatio * 100) / 100,
+            ...(paletteReview ? { palette_review: paletteReview } : {}),
             sample: colorSample,
         },
         undefinedTokenRefs: {
             count: undefinedRefs.length,
             sample: undefinedRefs.slice(0, OFF_CONTRACT_SAMPLE),
         },
+        ...(accessibility ? { accessibility } : {}),
         ...(staleContract ? { staleContract } : {}),
         note: ADVISORY_NOTE,
     };
@@ -1252,6 +1503,7 @@ function contractSummary(contract) {
         strength: contract.stats.strength,
         declared_tokens: contract.stats.declared_tokens,
         inferred_tokens: contract.stats.inferred_tokens,
+        ...(contract.source.self_referential ? { self_referential: true } : {}),
     };
 }
 function tokenKey(token) {
@@ -1409,6 +1661,12 @@ async function isDesignFile(full) {
     if (ext === ".swift") {
         return /(theme|color|palette|style|appearance|design)/.test(base);
     }
+    if (ext === ".kt") {
+        return /(theme|color|token|palette)/.test(base);
+    }
+    if (ext === ".html" || ext === ".htm" || ext === ".vue" || ext === ".svelte") {
+        return htmlFileDeclaresDesignTokens(full);
+    }
     if (MODULE_EXTS.has(ext)) {
         if (/^tailwind\.config\.(js|ts|cjs|mjs)$/.test(base)) {
             return true;
@@ -1433,6 +1691,20 @@ async function cssFileDeclaresDesignTokens(full) {
         return false;
     }
 }
+async function htmlFileDeclaresDesignTokens(full) {
+    try {
+        const info = await stat(full);
+        if (info.size > MAX_FILE_BYTES) {
+            return false;
+        }
+        const content = await readFile(full, "utf8");
+        const styleCss = extractStyleBlocks(content).join("\n");
+        return /(^|[{\s;])--[a-zA-Z0-9_-]+\s*:\s*[^;{}]+[;}]/.test(stripCssComments(styleCss));
+    }
+    catch {
+        return false;
+    }
+}
 export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = []) {
     const cssText = [...sources.css, ...sources.html.flatMap(extractStyleBlocks)].join("\n");
     const strippedCss = stripCssComments(cssText);
@@ -1505,11 +1777,12 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
     const components = inferComponents(sources.html, strippedCss);
     const declaredCount = tokens.filter((token) => token.provenance === "declared").length;
     const inferredCount = tokens.filter((token) => token.provenance === "inferred").length;
+    const selfReferential = sourceMeta.kind === "host-project";
     const contract = {
         schema_version: DESIGN_CONTRACT_SCHEMA_VERSION,
         vise_version: packageVersion,
         foundry_version: packageVersion,
-        source: sourceMeta,
+        source: selfReferential ? { ...sourceMeta, self_referential: true } : sourceMeta,
         digest: "",
         tokens,
         breakpoints,
@@ -1518,15 +1791,15 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
             declared_tokens: declaredCount,
             inferred_tokens: inferredCount,
             advisory_components: components.length,
-            strength: gradeStrength(declaredCount, inferredCount),
+            strength: gradeStrength(declaredCount, inferredCount, selfReferential),
         },
     };
     contract.digest = digestContract(contract);
     return contract;
 }
-function gradeStrength(declared, inferred) {
+function gradeStrength(declared, inferred, selfReferential = false) {
     if (declared >= 6) {
-        return "strong";
+        return selfReferential ? "partial" : "strong";
     }
     if (declared >= 1 || inferred >= 4) {
         return "partial";
@@ -2038,6 +2311,22 @@ export function extractTokensFromDart(content) {
     }
     return tokens;
 }
+export function extractTokensFromKotlin(content) {
+    const tokens = [];
+    const seen = new Set();
+    const pattern = /(\w+)\s*[:=]\s*(?:const\s+)?Color\(\s*0x([0-9a-fA-F]{8})\s*\)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const name = match[1];
+        const value = `#${match[2].slice(2).toLowerCase()}`;
+        const key = `color::${name}::${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            tokens.push({ category: "color", name, value, provenance: "declared", uses: 0 });
+        }
+    }
+    return tokens;
+}
 export function extractTokensFromColorset(contentsJson, name) {
     let parsed;
     try {
@@ -2300,7 +2589,7 @@ function bestCandidate(a, b) {
         return b;
     return a.token.length <= b.token.length ? a : b;
 }
-export function buildDesignBrief(contract) {
+export function buildDesignBrief(contract, profile) {
     const strength = contract.stats.strength;
     const colorTokens = contract.tokens.filter((t) => t.category === "color" && t.name !== null);
     const roleMap = new Map();
@@ -2478,6 +2767,26 @@ export function buildDesignBrief(contract) {
         : tokenCount > 0
             ? `Brief grounded in ${tokenCount} named token(s); no colour roles could be inferred from token names. Contract strength: ${strength}. roles/hints cover ${briefCoveredCount} of ${totalDeclaredTokens} declared tokens — consult the full set.`
             : `Contract has no named tokens — guidance is unavailable. Contract strength: ${strength}. Run \`vise design extract --from-project\` to derive tokens from the host project.`;
+    const brandGrounding = profile
+        ? {
+            status: "active",
+            essence: profile.essence,
+            personality: profile.personality,
+            voice: profile.voice,
+            palette: profile.palette,
+            typography: profile.typography,
+            density: profile.density,
+            elevation: profile.elevation,
+            motion: profile.motion,
+            imagery: profile.imagery,
+            do: profile.do,
+            avoid: profile.avoid,
+            source: profile.capturedFrom ?? "sp-vise/design-profile.json",
+        }
+        : {
+            status: "absent",
+            howTo: "These are tokens only. For richer brand grounding (personality, type system, density, voice, do/avoid), author sp-vise/design-profile.json from the host's real screens, then honor it per surface. See the 'Brand profile' subsection of the social.plus design skill for the schema.",
+        };
     return {
         summary,
         strength,
@@ -2486,6 +2795,7 @@ export function buildDesignBrief(contract) {
         do: doLines,
         avoid: avoidLines,
         reviewNotes,
+        brandGrounding,
     };
 }
 export function buildOutcomeDesignRecipe(brief, outcome) {

package/dist/tools/experienceCompiler.js

@@ -54,7 +54,7 @@ export async function compileExperience(options) {
     const repoRoot = path.resolve(options.repoPath);
     const selection = await readCreativeSelection(repoRoot);
     if (!selection) {
-        throw new Error("Experience Compiler requires an accepted creative selection. Run `vise creative . --request \"...\"`, then `vise creative accept . --variant <id>` first.");
+        throw new Error("Experience Compiler requires an accepted creative selection. Run `vise creative . --request \"...\"`, then `vise creative accept . --variant <id> --rationale \"<why>\" --confidence high` first.");
     }
     const request = options.request ?? selection.source.request;
     const inspection = await inspectProject(repoRoot, options.surfacePath);

package/dist/tools/experienceSensors.js

@@ -266,7 +266,7 @@ function businessSensors(uxHarness) {
             title: "Selected variant maps goals to patterns, objects, and UX",
             status: hasMapping ? "passed" : selected ? "needs-review" : "needs-setup",
             source: "ux-harness",
-            command: "vise creative accept . --variant <id>",
+            command: "vise creative accept . --variant <id> --rationale \"<why>\" --confidence high",
             reason: hasMapping
                 ? `Selected variant "${selected?.title}" carries business goals, solution patterns, experience objects, and UX patterns.`
                 : selected

package/dist/tools/harness.js

@@ -305,6 +305,19 @@ async function packageJsonSensors(root) {
             ...(skip ? { skip } : {}),
         };
     });
+    if (hasPackageDependency(parsed, "@amityco/ts-sdk-react-native")) {
+        sensors.push({
+            name: "React Native SDK import smoke",
+            command: [
+                "node",
+                "-e",
+                "require.resolve('@amityco/ts-sdk-react-native'); console.log('Vise smoke: @amityco/ts-sdk-react-native resolves')",
+            ],
+            timing: "after-change",
+            purpose: "Verify the social.plus React Native SDK resolves from the host project runtime environment.",
+            source: "package.json",
+        });
+    }
     if (hasPackageDependency(parsed, "@amityco/ts-sdk")) {
         sensors.push({
             name: "TypeScript SDK import smoke",