saglitzdesign-mcp 0.4.0 → 0.5.0

package/README.md

@@ -9,7 +9,7 @@ expert‑level guidance on **web, iOS, Android and macOS design** — plus the
 **UX, copywriting, SEO, GEO and marketing** knowledge that makes a product
 actually convert.
 
-56 curated knowledge documents · 10 tools · 5 build/review workflows · phased roadmaps · real‑world visual examples
+57 curated knowledge documents · 12 tools · 7 build/review workflows · real token & a11y generators · phased roadmaps · real‑world visual examples
 
 [![npm](https://img.shields.io/npm/v/saglitzdesign-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/saglitzdesign-mcp)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -71,6 +71,8 @@ scores it against the critique rubric, and iterates until it passes.
 | **`build_landing_page`** | Designs & builds a conversion‑focused landing page, copy‑first, with a visual critique loop. |
 | **`build_website`** | Builds a multi‑page marketing site — positioning, IA, SEO/GEO, shared design system. |
 | **`build_mobile_app_ui`** | Builds iOS or Android screens on the correct platform baseline (HIG/Liquid Glass or Material 3). |
+| **`critique_screenshot`** | Grounded, reproducible critique of an attached UI screenshot against the fixed 0–40 rubric — cites specific elements, no padding. |
+| **`review_paywall`** | Scores a paywall / subscription onboarding against real RevenueCat 2026 conversion benchmarks. |
 | **`design_review`** | Audits an existing site/app against the checklists and the 0–40 critique rubric, ranked by severity. |
 | **`redesign`** | Improves an existing UI (bolder / quieter / higher‑converting) using the craft standards, with before→after scoring. |
 
@@ -92,6 +94,8 @@ scores it against the critique rubric, and iterates until it passes.
 | **`get_design_examples`** | **Real screenshots** of a pattern from top apps/sites, returned as images with notes on what each does well. |
 | **`design_review_checklist`** | An assembled audit checklist per project type and focus (UI, UX, accessibility, SEO, GEO, conversion, copywriting). |
 | **`seo_geo_guide`** | SEO and GEO guides, optionally narrowed to a topic. |
+| **`generate_design_tokens`** | **Real artifacts, not advice** — turns a color/spacing/type spec into CSS variables, Tailwind v4, SwiftUI, Jetpack Compose, and W3C DTCG JSON. |
+| **`audit_accessibility`** | Deterministic WCAG 2.2 checks — exact contrast ratios for color pairs + tap‑target sizes per platform, with fixes. |
 | **`list_design_knowledge`** | Browse the full knowledge index by category / platform. |
 | **`knowledge_freshness`** | Reports each doc's age vs a per‑category staleness threshold, so the base can be kept current. |
 

package/dist/a11y.js

@@ -0,0 +1,98 @@
+// Deterministic, design-time accessibility checks: WCAG 2.2 contrast + tap targets.
+// Mirrors the axe-style rules designers wish ran at design time, not just in CI.
+import { normalizeHex } from "./tokens.js";
+function channelLuminance(c) {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+function relativeLuminance(hex) {
+    const h = normalizeHex(hex).slice(1);
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b);
+}
+/** WCAG contrast ratio between two opaque colors (1..21). */
+export function contrastRatio(fg, bg) {
+    const l1 = relativeLuminance(fg);
+    const l2 = relativeLuminance(bg);
+    const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+    return (hi + 0.05) / (lo + 0.05);
+}
+export function checkContrast(pairs) {
+    return pairs.map((p, i) => {
+        const label = p.label ?? `pair ${i + 1}`;
+        const fg = normalizeHex(p.foreground);
+        const bg = normalizeHex(p.background);
+        if (!fg || !bg) {
+            return { label, detail: `${p.foreground} on ${p.background}`, required: "valid hex", actual: "invalid hex", pass: false, fix: "Use #RGB / #RRGGBB / #RRGGBBAA." };
+        }
+        const ratio = contrastRatio(fg, bg);
+        const required = p.ui_component ? 3 : p.large_text ? 3 : 4.5;
+        const kind = p.ui_component ? "non-text UI (WCAG 1.4.11)" : p.large_text ? "large text (WCAG 1.4.3 AA)" : "normal text (WCAG 1.4.3 AA)";
+        const pass = ratio >= required;
+        return {
+            label,
+            detail: `${fg} on ${bg} — ${kind}`,
+            required: `≥ ${required}:1`,
+            actual: `${ratio.toFixed(2)}:1`,
+            pass,
+            fix: pass ? undefined : `Increase contrast to ≥${required}:1 (darken/lighten one color). AAA target is ${p.large_text || p.ui_component ? "4.5" : "7"}:1.`,
+        };
+    });
+}
+export function checkTargets(targets) {
+    const MIN = { ios: 44, android: 48, web: 24 }; // pt / dp / css px (WCAG 2.2 min for web)
+    const REC = 44; // recommended comfortable minimum across platforms
+    return targets.map((t, i) => {
+        const platform = t.platform ?? "web";
+        const min = MIN[platform];
+        const smaller = Math.min(t.width, t.height);
+        const pass = smaller >= min;
+        const unit = platform === "ios" ? "pt" : platform === "android" ? "dp" : "px";
+        return {
+            label: t.label ?? `target ${i + 1}`,
+            detail: `${t.width}×${t.height}${unit} (${platform})`,
+            required: `≥ ${min}×${min}${unit}${platform === "web" ? ` (rec. ${REC})` : ""}`,
+            actual: `${smaller}${unit} smallest side`,
+            pass,
+            fix: pass ? undefined : `Enlarge to ≥${min}${unit}, or expand the hit area (padding) beyond the visible bounds.`,
+        };
+    });
+}
+export function contrastReport(pairs, targets) {
+    const out = ["# Accessibility audit (WCAG 2.2)"];
+    const cr = checkContrast(pairs);
+    const tr = checkTargets(targets);
+    const all = [...cr, ...tr];
+    const fails = all.filter((r) => !r.pass).length;
+    out.push(`\n**${all.length} checks · ${all.length - fails} pass · ${fails} fail**\n`);
+    if (cr.length) {
+        out.push("## Color contrast");
+        out.push("| element | measured | required | result |");
+        out.push("|---|---|---|---|");
+        for (const r of cr)
+            out.push(`| ${r.label} — ${r.detail} | ${r.actual} | ${r.required} | ${r.pass ? "✅ pass" : "❌ FAIL"} |`);
+        const failFixes = cr.filter((r) => !r.pass);
+        if (failFixes.length) {
+            out.push("\n**Fixes:**");
+            for (const r of failFixes)
+                out.push(`- **${r.label}:** ${r.fix}`);
+        }
+    }
+    if (tr.length) {
+        out.push("\n## Tap / target sizes");
+        out.push("| target | size | required | result |");
+        out.push("|---|---|---|---|");
+        for (const r of tr)
+            out.push(`| ${r.label} | ${r.detail} | ${r.required} | ${r.pass ? "✅ pass" : "❌ FAIL"} |`);
+        const failFixes = tr.filter((r) => !r.pass);
+        if (failFixes.length) {
+            out.push("\n**Fixes:**");
+            for (const r of failFixes)
+                out.push(`- **${r.label}:** ${r.fix}`);
+        }
+    }
+    out.push("\n---\n_Deterministic checks only (contrast + target size). These are ~the machine-verifiable slice of accessibility; axe-core-style automation catches ~57% of issues by volume. Still verify manually: keyboard/focus order, screen-reader labels & announcements, Dynamic Type at 200%, motion, and cognitive load. See get_design_doc(\"accessibility\")._");
+    return out.join("\n");
+}

package/dist/index.js

@@ -8,6 +8,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { loadKnowledge, searchKnowledge, sections } from "./knowledge.js";
 import { loadExamples, searchExamples, imageMime } from "./examples.js";
 import { registerPrompts } from "./prompts.js";
+import { generateTokens, validateColors, DEFAULT_SPACING, DEFAULT_RADII, DEFAULT_FONT_SIZES, DEFAULT_FONT_FAMILIES, } from "./tokens.js";
+import { contrastReport } from "./a11y.js";
 // knowledge/ sits next to dist/ (repo root) both in dev (tsx) and after build
 const here = dirname(fileURLToPath(import.meta.url));
 const knowledgeDir = [join(here, "..", "knowledge"), join(here, "..", "..", "knowledge")].find(existsSync);
@@ -20,7 +22,7 @@ const examplesDir = join(knowledgeDir, "examples");
 const examples = loadExamples(examplesDir);
 const server = new McpServer({
     name: "saglitzdesign",
-    version: "0.4.0",
+    version: "0.5.0",
 });
 function docHeader(d) {
     return `# ${d.title}\n_id: ${d.id} · category: ${d.category} · platform: ${d.platform} · tags: ${d.tags.join(", ")}_\n`;
@@ -369,6 +371,54 @@ server.tool("knowledge_freshness", "Report how fresh each knowledge document is
     ];
     return text(lines.join("\n"));
 });
+// ── Tool 11: generate design tokens ──────────────────────────────────────────
+server.tool("generate_design_tokens", "Turn a design-token spec (semantic colors + optional spacing/radius/type scales) into REAL, ready-to-use artifact files: CSS custom properties, Tailwind v4 @theme, SwiftUI, Jetpack Compose, and W3C DTCG JSON. Deterministic — outputs code, not advice. Use it to give a project one source of truth across web, iOS and Android. Pair with audit_accessibility to verify the palette's contrast.", {
+    name: z.string().optional().describe("Token set / brand name (default 'Brand')"),
+    colors: z.record(z.string()).describe("Semantic color roles → hex. e.g. {\"primary\":\"#4F46E5\",\"onPrimary\":\"#FFFFFF\",\"surface\":\"#0A0A0B\",\"textPrimary\":\"#F5F5F5\",\"danger\":\"#EF4444\"}"),
+    format: z.enum(["css", "tailwind", "swiftui", "compose", "dtcg", "all"]).optional().describe("Output format (default 'all')"),
+    spacing: z.array(z.number()).optional().describe("px spacing scale (default 8pt scale 2..96)"),
+    radii: z.record(z.number()).optional().describe("radius name→px (default sm/md/lg/xl/full; use 9999 for pill)"),
+    fontSizes: z.record(z.number()).optional().describe("type scale name→px (default xs..4xl)"),
+    fontFamilies: z.record(z.string()).optional().describe("font role→stack (default sans/mono)"),
+}, async ({ name, colors, format, spacing, radii, fontSizes, fontFamilies }) => {
+    const bad = validateColors(colors);
+    if (bad.length)
+        return text(`Invalid hex value(s): ${bad.join(", ")}. Use #RGB, #RRGGBB, or #RRGGBBAA.`);
+    if (Object.keys(colors).length === 0)
+        return text("Provide at least one color role in `colors`.");
+    const spec = {
+        name: name || "Brand",
+        colors,
+        spacing: spacing && spacing.length ? spacing : DEFAULT_SPACING,
+        radii: radii && Object.keys(radii).length ? radii : DEFAULT_RADII,
+        fontSizes: fontSizes && Object.keys(fontSizes).length ? fontSizes : DEFAULT_FONT_SIZES,
+        fontFamilies: fontFamilies && Object.keys(fontFamilies).length ? fontFamilies : DEFAULT_FONT_FAMILIES,
+    };
+    return text(generateTokens(spec, format ?? "all"));
+});
+// ── Tool 12: accessibility audit ─────────────────────────────────────────────
+server.tool("audit_accessibility", "Deterministic design-time accessibility checks: WCAG 2.2 color-contrast ratios for text/UI color pairs, and minimum tap/target sizes per platform (iOS 44pt, Android 48dp, web 24px min / 44 recommended). Returns exact ratios, pass/fail, and fixes — the machine-verifiable slice of a11y you can run before code. For keyboard/screen-reader/Dynamic Type checks, see get_design_doc('accessibility').", {
+    contrast_pairs: z.array(z.object({
+        foreground: z.string().describe("text/element hex"),
+        background: z.string().describe("background hex"),
+        label: z.string().optional().describe("what this is, e.g. 'body text on surface'"),
+        large_text: z.boolean().optional().describe("true if ≥24px or ≥18.66px bold (threshold drops to 3:1)"),
+        ui_component: z.boolean().optional().describe("true for non-text UI: borders, icons, focus rings (3:1)"),
+    })).optional().describe("Color pairs to check for contrast"),
+    tap_targets: z.array(z.object({
+        label: z.string().optional(),
+        width: z.number().describe("width in pt/dp/px"),
+        height: z.number().describe("height in pt/dp/px"),
+        platform: z.enum(["ios", "android", "web"]).optional().describe("default web"),
+    })).optional().describe("Interactive targets to check for minimum size"),
+}, async ({ contrast_pairs, tap_targets }) => {
+    const pairs = (contrast_pairs ?? []);
+    const targets = (tap_targets ?? []);
+    if (pairs.length === 0 && targets.length === 0) {
+        return text("Provide `contrast_pairs` and/or `tap_targets` to audit. Example: {\"contrast_pairs\":[{\"foreground\":\"#6B7280\",\"background\":\"#FFFFFF\",\"label\":\"muted text\"}]}");
+    }
+    return text(contrastReport(pairs, targets));
+});
 // ── prompts (user-invocable build/review/redesign workflows) ─────────────────
 registerPrompts(server, {
     brief: z

package/dist/prompts.js

@@ -97,6 +97,43 @@ Finish with: screens built, how to run/preview, critique scores, platform-fit no
     },
 ];
 const ACTION_PROMPTS = [
+    {
+        name: "critique_screenshot",
+        title: "Critique a screenshot (SaglitzDesign)",
+        description: "Grounded, reproducible visual critique of an attached UI screenshot against the fixed 0–40 rubric — cites specific elements, no padding.",
+        build: (brief) => `Critique the **attached UI screenshot**${brief ? ` (context: ${brief})` : ""} as a rigorous senior designer, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Method — avoid the failure modes of typical AI critique
+Research shows most AI critiques (a) hallucinate issues inconsistently, (b) pad the list to look thorough, and (c) critique a text description instead of the actual pixels. Do NOT do these. Instead:
+
+1. **Look at the image first.** Describe what you actually see (layout, hierarchy, the primary action, states shown) before judging. If you're unsure what an element is, say so — don't invent.
+2. **Apply the fixed rubric.** Call get_design_doc("design-critique-scoring") and score each of the 10 heuristics 0–4 for a total /40. Use the SAME rubric every time so scores are reproducible.
+3. **Cite specific elements.** Every finding must point to a concrete element ("the secondary 'Learn more' button competes with the primary CTA — two filled buttons"), not generic advice.
+4. **No padding.** Report only real issues. If the screen is genuinely good, a short list is the correct answer — do not manufacture findings to seem thorough.
+5. **Rank by severity P0→P3** and give one concrete fix per finding, citing the SaglitzDesign rule/doc it comes from.
+6. If it's a known screen type, also run the matching design_review_checklist and get_design_examples to compare against how top apps handle it.
+
+Output: the /40 score with per-heuristic line, then findings ranked by severity (element → problem → why (cite rule) → fix), then the 3 highest-impact changes. Keep it tight and specific.`,
+    },
+    {
+        name: "review_paywall",
+        title: "Review a paywall / onboarding (SaglitzDesign)",
+        description: "Score a paywall or subscription onboarding against real RevenueCat 2026 conversion benchmarks and paywall-anatomy rules.",
+        build: (brief) => `Review this **paywall / subscription onboarding**${brief ? `: ${brief}` : ""} using the SaglitzDesign method and real 2026 benchmarks.
+
+${TOOLS_NOTE}
+
+## Method
+1. Load the data: get_design_doc("paywall-benchmarks") (RevenueCat 2026: hard paywall ~10.7% vs freemium ~2.1%; 17–32 day trials convert 42.5% vs 25.5% for <4 days; 55% of 3-day-trial cancels happen Day 0; Android involuntary churn ~2.2× iOS) and get_design_doc("onboarding-paywall") for anatomy.
+2. If given a screenshot, look at it and describe the actual paywall (model, plans, trial, price placement, CTA, trust copy). If given a description, work from that; ask up to 3 questions only if a benchmark-critical fact is missing (model, trial length, platform).
+3. Score it against the review rubric in paywall-benchmarks.md — each item pass/fail with the benchmark it maps to.
+4. Estimate where it likely leaves conversion on the table (e.g. "≤4-day trial → ~40% relative conversion lost vs a 14–30 day trial").
+5. Give prioritized, concrete fixes (model choice, trial length, price placement, trial reminder, Android dunning, trust microcopy), each tied to a benchmark number.
+
+Output: a pass/fail scorecard, the top 3 conversion risks with their benchmark impact, and the exact changes to make. Be specific and numeric — no generic "add social proof" advice.`,
+    },
     {
         name: "design_review",
         title: "Design review (SaglitzDesign)",

package/dist/tokens.js

@@ -0,0 +1,148 @@
+// Deterministic design-token artifact generator.
+// One source spec → CSS variables, Tailwind v4, SwiftUI, Jetpack Compose, DTCG JSON.
+// Fills the gap where Style Dictionary v4 doesn't yet emit the stable DTCG 2025.10 format.
+export const DEFAULT_SPACING = [2, 4, 8, 12, 16, 24, 32, 48, 64, 96];
+export const DEFAULT_RADII = { sm: 6, md: 10, lg: 16, xl: 24, full: 9999 };
+export const DEFAULT_FONT_SIZES = { xs: 12, sm: 14, base: 16, lg: 18, xl: 20, "2xl": 24, "3xl": 30, "4xl": 40 };
+export const DEFAULT_FONT_FAMILIES = {
+    sans: "Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+    mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
+};
+const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+export function normalizeHex(hex) {
+    if (!HEX_RE.test(hex))
+        return null;
+    let h = hex.slice(1);
+    if (h.length === 3)
+        h = h.split("").map((c) => c + c).join("");
+    if (h.length === 4)
+        h = h.split("").map((c) => c + c).join("");
+    return "#" + h.toLowerCase();
+}
+function hexParts(hex) {
+    const h = normalizeHex(hex).slice(1);
+    return {
+        r: parseInt(h.slice(0, 2), 16),
+        g: parseInt(h.slice(2, 4), 16),
+        b: parseInt(h.slice(4, 6), 16),
+        a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+    };
+}
+function kebab(s) {
+    return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+}
+function pascal(s) {
+    return s.replace(/(^|[-_\s]+)([a-zA-Z0-9])/g, (_, __, c) => c.toUpperCase());
+}
+function camel(s) {
+    const p = pascal(s);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+}
+// ── CSS custom properties ────────────────────────────────────────────────────
+function toCss(s) {
+    const lines = [":root {"];
+    lines.push("  /* color */");
+    for (const [k, v] of Object.entries(s.colors))
+        lines.push(`  --color-${kebab(k)}: ${normalizeHex(v)};`);
+    lines.push("  /* spacing */");
+    s.spacing.forEach((v) => lines.push(`  --space-${v}: ${v}px;`));
+    lines.push("  /* radius */");
+    for (const [k, v] of Object.entries(s.radii))
+        lines.push(`  --radius-${kebab(k)}: ${v >= 9999 ? "9999px" : v + "px"};`);
+    lines.push("  /* font size */");
+    for (const [k, v] of Object.entries(s.fontSizes))
+        lines.push(`  --text-${kebab(k)}: ${(v / 16).toFixed(4).replace(/\.?0+$/, "")}rem;`);
+    lines.push("  /* font family */");
+    for (const [k, v] of Object.entries(s.fontFamilies))
+        lines.push(`  --font-${kebab(k)}: ${v};`);
+    lines.push("}");
+    return lines.join("\n");
+}
+// ── Tailwind v4 (@theme) ─────────────────────────────────────────────────────
+function toTailwind(s) {
+    const lines = ["@theme {"];
+    for (const [k, v] of Object.entries(s.colors))
+        lines.push(`  --color-${kebab(k)}: ${normalizeHex(v)};`);
+    s.spacing.forEach((v) => lines.push(`  --spacing-${v}: ${v}px;`));
+    for (const [k, v] of Object.entries(s.radii))
+        lines.push(`  --radius-${kebab(k)}: ${v >= 9999 ? "9999px" : v + "px"};`);
+    for (const [k, v] of Object.entries(s.fontSizes))
+        lines.push(`  --text-${kebab(k)}: ${(v / 16).toFixed(4).replace(/\.?0+$/, "")}rem;`);
+    for (const [k, v] of Object.entries(s.fontFamilies))
+        lines.push(`  --font-${kebab(k)}: ${v};`);
+    lines.push("}");
+    return lines.join("\n");
+}
+// ── SwiftUI ──────────────────────────────────────────────────────────────────
+function toSwiftUI(s) {
+    const lines = ["import SwiftUI", "", `enum ${pascal(s.name)}Tokens {`];
+    lines.push("    // Colors");
+    for (const [k, v] of Object.entries(s.colors)) {
+        const { r, g, b, a } = hexParts(v);
+        lines.push(`    static let ${camel(k)} = Color(.sRGB, red: ${(r / 255).toFixed(3)}, green: ${(g / 255).toFixed(3)}, blue: ${(b / 255).toFixed(3)}, opacity: ${a.toFixed(3)})`);
+    }
+    lines.push("    // Spacing (pt)");
+    s.spacing.forEach((v) => lines.push(`    static let space${v}: CGFloat = ${v}`));
+    lines.push("    // Corner radius (pt)");
+    for (const [k, v] of Object.entries(s.radii))
+        lines.push(`    static let radius${pascal(k)}: CGFloat = ${v >= 9999 ? 9999 : v}`);
+    lines.push("    // Font size (pt)");
+    for (const [k, v] of Object.entries(s.fontSizes))
+        lines.push(`    static let text${pascal(k)}: CGFloat = ${v}`);
+    lines.push("}");
+    return lines.join("\n");
+}
+// ── Jetpack Compose ──────────────────────────────────────────────────────────
+function toCompose(s) {
+    const lines = ["import androidx.compose.ui.graphics.Color", "import androidx.compose.ui.unit.dp", "import androidx.compose.ui.unit.sp", "", `object ${pascal(s.name)}Tokens {`];
+    lines.push("    // Colors (0xAARRGGBB)");
+    for (const [k, v] of Object.entries(s.colors)) {
+        const { r, g, b, a } = hexParts(v);
+        const argb = ((Math.round(a * 255) << 24) | (r << 16) | (g << 8) | b) >>> 0;
+        lines.push(`    val ${camel(k)} = Color(0x${argb.toString(16).padStart(8, "0").toUpperCase()})`);
+    }
+    lines.push("    // Spacing");
+    s.spacing.forEach((v) => lines.push(`    val space${v} = ${v}.dp`));
+    lines.push("    // Corner radius");
+    for (const [k, v] of Object.entries(s.radii))
+        lines.push(`    val radius${pascal(k)} = ${v >= 9999 ? 9999 : v}.dp`);
+    lines.push("    // Font size");
+    for (const [k, v] of Object.entries(s.fontSizes))
+        lines.push(`    val text${pascal(k)} = ${v}.sp`);
+    lines.push("}");
+    return lines.join("\n");
+}
+// ── DTCG JSON (W3C Design Tokens Community Group, stable 2025.10) ─────────────
+function toDtcg(s) {
+    const obj = {
+        $description: `${s.name} design tokens (DTCG format)`,
+        color: Object.fromEntries(Object.entries(s.colors).map(([k, v]) => [kebab(k), { $type: "color", $value: normalizeHex(v) }])),
+        spacing: Object.fromEntries(s.spacing.map((v) => [String(v), { $type: "dimension", $value: { value: v, unit: "px" } }])),
+        radius: Object.fromEntries(Object.entries(s.radii).map(([k, v]) => [kebab(k), { $type: "dimension", $value: { value: v, unit: "px" } }])),
+        fontSize: Object.fromEntries(Object.entries(s.fontSizes).map(([k, v]) => [kebab(k), { $type: "dimension", $value: { value: v, unit: "px" } }])),
+        fontFamily: Object.fromEntries(Object.entries(s.fontFamilies).map(([k, v]) => [kebab(k), { $type: "fontFamily", $value: v.split(",").map((f) => f.trim()) }])),
+    };
+    return JSON.stringify(obj, null, 2);
+}
+const GENERATORS = {
+    css: { label: "CSS custom properties (tokens.css)", lang: "css", fn: toCss },
+    tailwind: { label: "Tailwind v4 theme (app.css)", lang: "css", fn: toTailwind },
+    swiftui: { label: "SwiftUI (Tokens.swift)", lang: "swift", fn: toSwiftUI },
+    compose: { label: "Jetpack Compose (Tokens.kt)", lang: "kotlin", fn: toCompose },
+    dtcg: { label: "DTCG JSON (tokens.json)", lang: "json", fn: toDtcg },
+};
+export function generateTokens(spec, format) {
+    const formats = format === "all" ? Object.keys(GENERATORS) : [format];
+    const blocks = formats.map((f) => {
+        const g = GENERATORS[f];
+        return `## ${g.label}\n\`\`\`${g.lang}\n${g.fn(spec)}\n\`\`\``;
+    });
+    return `# ${spec.name} — design tokens\n\n${blocks.join("\n\n")}`;
+}
+export function validateColors(colors) {
+    const bad = [];
+    for (const [k, v] of Object.entries(colors))
+        if (!normalizeHex(v))
+            bad.push(`${k}: "${v}"`);
+    return bad;
+}

package/knowledge/marketing/paywall-benchmarks.md

@@ -0,0 +1,58 @@
+---
+id: paywall-benchmarks
+title: "Paywall & Onboarding Conversion Benchmarks (2026)"
+category: marketing
+platform: mobile
+tags: [paywall, subscription, onboarding, conversion, revenuecat, trial, retention]
+sources: ["https://www.revenuecat.com/state-of-subscription-apps/", "https://www.revenuecat.com/blog/growth/subscription-app-trends-benchmarks-2026/", "https://www.revenuecat.com/blog/engineering/android-paywall-gap/"]
+updated: 2026-07-08
+---
+
+# Paywall & Onboarding Conversion Benchmarks (2026)
+
+Real benchmarks from RevenueCat's *State of Subscription Apps 2026* (115k+ apps, $16B+ tracked revenue). Use these to judge whether a paywall/onboarding is competitive — not vibes.
+
+## Headline numbers
+
+| Metric | Benchmark | Implication |
+|---|---|---|
+| Hard paywall (signup gate) conversion | **~10.7%** install→trial/purchase | ~5× freemium |
+| Freemium (optional paywall) conversion | **~2.1%** | Higher reach, far lower conversion |
+| Day-60 revenue per install (hard vs freemium) | **$3.09 vs $0.38** | ~8× |
+| Trial length 17–32 days → trial-start→paid | **42.5%** | Longer trials convert better |
+| Trial length <4 days → trial-start→paid | **25.5%** | …yet **46.5% of apps use ≤4-day trials** (mistake) |
+| Share of 3-day-trial cancellations on Day 0 | **55%** (84% by Day 1) | The first session decides everything |
+| iOS Day-35 subscriber retention (median) | **~2.6%** of installs | |
+| Android Day-35 (median) | **~0.9%** | Android lags ~3× |
+| Android involuntary (billing-failure) churn | **~2.2× iOS** | Dunning/grace-period handling matters |
+
+## Design rules derived
+
+1. **Choose the model deliberately.** Hard paywall ≈5× conversion and ≈8× RPI — default to it unless the product's value genuinely requires free exploration first (network/UGC/virality). Freemium is a reach play, not a revenue play.
+2. **Longer trials win.** Move to 14–30 day trials; ≤4-day trials leave ~40% relative conversion on the table. Pair with a **trial reminder** before charge (trust + fewer chargebacks).
+3. **Win Day 0.** 55% of cancels happen the first day → the onboarding must deliver the "aha" and the paywall must state value + price clearly in session one. Instrument Day-0 retention as the leading indicator.
+4. **Show value before the wall when possible**, but don't bury the paywall — hard-paywall apps that clearly present the offer up front convert best.
+5. **Paywall anatomy that converts** (from `onboarding-paywall` pattern): benefit checklist (≤6 concrete benefits), 1–2 plan cards with the recommended one badged, trial timeline ("today → day 12 reminder → day 14 charge"), price + terms disclosed right next to the CTA, restore-purchases link, single primary CTA.
+6. **Android: fix involuntary churn.** Grace periods, account hold, billing-retry, and clear payment-update prompts — 2.2× iOS involuntary churn is mostly a dunning-design problem, not intent.
+7. **Personalized onboarding lifts paywall conversion** only when answers visibly change the experience or the paywall framing; ≤5 steps with a progress indicator.
+
+## Review rubric (score a paywall against this)
+
+- [ ] Model fits the product (hard vs freemium) — justified, not accidental
+- [ ] Trial length ≥14 days (or a deliberate reason it's shorter)
+- [ ] Pre-charge trial reminder scheduled
+- [ ] Single primary CTA; price + billing terms adjacent to it
+- [ ] ≤6 concrete benefits, recommended plan badged
+- [ ] Restore purchases + terms/privacy links present
+- [ ] Day-0 activation designed (aha before or at the wall)
+- [ ] Android: grace period + billing-retry + payment-update UX
+- [ ] Trust microcopy ("cancel anytime", "you won't be charged until…")
+
+## Anti-patterns
+
+- ≤4-day trials by default (industry's most common, costly mistake).
+- Freemium chosen "to be nice" when the product could hard-gate — leaves ~5× on the table.
+- Paywall with hidden/unclear price, or price far from the CTA.
+- No trial reminder → surprise charges → chargebacks + 1-star reviews.
+- Ignoring Android billing failures (treating churn as intent when it's involuntary).
+- Multi-step personalization that never changes anything downstream.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saglitzdesign-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "SaglitzDesign — expert MCP server for mobile app & website design: UI, UX, buttons, design languages, SEO and GEO guidance backed by a curated knowledge base and real-world pattern research.",
   "type": "module",
   "bin": {