@mandujs/core 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -25,6 +25,7 @@
     "./content/llms-txt": "./src/content/llms-txt.ts",
     "./content/schema": "./src/content/schema.ts",
     "./db": "./src/db/index.ts",
+    "./design": "./src/design/index.ts",
     "./desktop": "./src/desktop/index.ts",
     "./desktop/worker": "./src/desktop/worker.ts",
     "./email": "./src/email/index.ts",

package/src/client/router.ts

@@ -346,9 +346,19 @@ export async function navigate(
       // `startViewTransition` is part of the View Transitions API which
       // is not yet in every lib.dom.d.ts. Narrow the cast to the only
       // method we call rather than widening to `any`.
-      (document as Document & {
-        startViewTransition: (callback: () => void) => unknown;
+      const transition = (document as Document & {
+        startViewTransition: (callback: () => void) => {
+          finished?: Promise<unknown>;
+          ready?: Promise<unknown>;
+          updateCallbackDone?: Promise<unknown>;
+        };
       }).startViewTransition(applyUpdate);
+      // ViewTransition.finished/ready reject with InvalidStateError when a
+      // newer transition aborts this one (rapid navigation, popstate, etc.).
+      // Swallow those — they are expected and not actionable for the app.
+      transition?.finished?.catch(() => {});
+      transition?.ready?.catch(() => {});
+      transition?.updateCallbackDone?.catch(() => {});
     } else {
       applyUpdate();
     }

package/src/client/spa-nav-helper.ts

@@ -97,7 +97,7 @@
  * flow is documented in this file's JSDoc; anyone editing this string
  * MUST update the exclusion-matrix test and the body-swap test to match.
  */
-export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function esc(h){try{if(typeof CSS!=="undefined"&&CSS&&typeof CSS.escape==="function")return CSS.escape(h);}catch(_){}return String(h).replace(/([^a-zA-Z0-9_-])/g,"\\\\$1");}function extractHash(u){var i=u.indexOf("#");return i>=0?u.slice(i+1):"";}function scrollToHash(hash,url){if(!hash){try{window.scrollTo(0,0);}catch(_){}return;}var el=null;try{el=document.getElementById?document.getElementById(hash):null;}catch(_){}if(!el){try{el=document.querySelector?document.querySelector('[name="'+esc(hash)+'"]'):null;}catch(_){}}if(el&&typeof el.scrollIntoView==="function"){try{el.scrollIntoView({behavior:"instant",block:"start"});}catch(e1){try{el.scrollIntoView();}catch(_){}}try{if(L.hash!=="#"+hash)L.hash="#"+hash;}catch(_){}info("scrolled to #"+hash,url==null?"":url);}else{info("hash target #"+hash+" not found, scrolling to top",url==null?"":url);try{window.scrollTo(0,0);}catch(_){}}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h)return null;var u;try{u=new URL(h,L.href);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;if(u.pathname===L.pathname&&u.search===L.search&&!u.hash)return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}try{var cRoot=document.getElementById?document.getElementById("root"):null;var nRoot=doc.getElementById?doc.getElementById("root"):null;var ck=cRoot&&cRoot.getAttribute?cRoot.getAttribute("data-mandu-layout"):"";var nk=nRoot&&nRoot.getAttribute?nRoot.getAttribute("data-mandu-layout"):"";if(ck&&nk&&ck!==nk){hardNav(url,"cross-layout transition ("+ck+" -> "+nk+")");return false;}}catch(_){}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);scrollToHash(extractHash(url),url);var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}function samePageHashNav(u,push){var url=u.pathname+u.search+u.hash;if(push){try{H.pushState({mandu:1},"",url);}catch(e){warn("pushState threw on same-page hash nav",e&&e.message||e);}}info("same-page hash nav "+url);scrollToHash(u.hash?u.hash.slice(1):"",url);try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:0,container:"hash"}}));}catch(_){}}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();if(url.pathname===L.pathname&&url.search===L.search&&url.hash){samePageHashNav(url,true);return;}nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
+export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function esc(h){try{if(typeof CSS!=="undefined"&&CSS&&typeof CSS.escape==="function")return CSS.escape(h);}catch(_){}return String(h).replace(/([^a-zA-Z0-9_-])/g,"\\\\$1");}function extractHash(u){var i=u.indexOf("#");return i>=0?u.slice(i+1):"";}function scrollToHash(hash,url){if(!hash){try{window.scrollTo(0,0);}catch(_){}return;}var el=null;try{el=document.getElementById?document.getElementById(hash):null;}catch(_){}if(!el){try{el=document.querySelector?document.querySelector('[name="'+esc(hash)+'"]'):null;}catch(_){}}if(el&&typeof el.scrollIntoView==="function"){try{el.scrollIntoView({behavior:"instant",block:"start"});}catch(e1){try{el.scrollIntoView();}catch(_){}}try{if(L.hash!=="#"+hash)L.hash="#"+hash;}catch(_){}info("scrolled to #"+hash,url==null?"":url);}else{info("hash target #"+hash+" not found, scrolling to top",url==null?"":url);try{window.scrollTo(0,0);}catch(_){}}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h)return null;var u;try{u=new URL(h,L.href);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;if(u.pathname===L.pathname&&u.search===L.search&&!u.hash)return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}try{var cRoot=document.getElementById?document.getElementById("root"):null;var nRoot=doc.getElementById?doc.getElementById("root"):null;var ck=cRoot&&cRoot.getAttribute?cRoot.getAttribute("data-mandu-layout"):"";var nk=nRoot&&nRoot.getAttribute?nRoot.getAttribute("data-mandu-layout"):"";if(ck&&nk&&ck!==nk){hardNav(url,"cross-layout transition ("+ck+" -> "+nk+")");return false;}}catch(_){}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);scrollToHash(extractHash(url),url);var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{var vt=document.startViewTransition(run);if(vt){if(vt.finished&&typeof vt.finished.catch==="function")vt.finished.catch(function(){});if(vt.ready&&typeof vt.ready.catch==="function")vt.ready.catch(function(){});if(vt.updateCallbackDone&&typeof vt.updateCallbackDone.catch==="function")vt.updateCallbackDone.catch(function(){});}}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}function samePageHashNav(u,push){var url=u.pathname+u.search+u.hash;if(push){try{H.pushState({mandu:1},"",url);}catch(e){warn("pushState threw on same-page hash nav",e&&e.message||e);}}info("same-page hash nav "+url);scrollToHash(u.hash?u.hash.slice(1):"",url);try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:0,container:"hash"}}));}catch(_){}}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();if(url.pathname===L.pathname&&url.search===L.search&&url.hash){samePageHashNav(url,true);return;}nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
 
 /** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
 export const SPA_NAV_HELPER_SCRIPT = `<script>${SPA_NAV_HELPER_BODY}</script>`;

package/src/config/validate.ts

@@ -114,6 +114,34 @@ const GuardTypeAwareConfigSchema = z
  *   - `GuardRule[]` (Phase 18.ν) → consumer-defined custom rules.
  * The runner dispatches on `Array.isArray()`.
  */
+/**
+ * Issue #245 — DESIGN.md-driven design system enforcement.
+ *
+ * `forbidInlineClasses` stops agents from re-inlining the same UI
+ * pattern across pages (the regression #245 was filed for); when set,
+ * the named classes trigger a Guard violation if they appear directly
+ * in `className` outside the canonical component dirs.
+ *
+ * `requireComponent` maps a forbidden class to the component that
+ * should be used instead — surfaced verbatim in the violation message
+ * so an agent reading the diagnostic knows the fix.
+ *
+ * `autoFromDesignMd` extracts the forbid list from DESIGN.md §7
+ * Do's & Don'ts when set, so users only need to maintain the spec.
+ */
+const GuardDesignConfigSchema = z
+  .object({
+    designMd: z.string().default("DESIGN.md"),
+    forbidInlineClasses: z.array(z.string().min(1)).default([]),
+    autoFromDesignMd: z.boolean().default(false),
+    requireComponent: z.record(z.string()).default({}),
+    exclude: z
+      .array(z.string())
+      .default(["src/client/shared/ui/**", "src/client/widgets/**"]),
+    severity: z.enum(["warning", "error"]).default("error"),
+  })
+  .strict();
+
 const GuardConfigSchema = z
   .object({
     preset: z.enum(["mandu", "fsd", "clean", "hexagonal", "atomic", "cqrs"]).default("mandu"),
@@ -136,6 +164,14 @@ const GuardConfigSchema = z
      * Follow-up E — `oxlint --type-aware` bridge. Optional.
      */
     typeAware: GuardTypeAwareConfigSchema.optional(),
+    /**
+     * Issue #245 — design system enforcement. Optional; when present,
+     * the design-inline-class checker runs alongside the standard
+     * Guard pipeline. Most projects start by setting `designMd:
+     * "DESIGN.md"` + `autoFromDesignMd: true` and let the spec drive
+     * the forbid list.
+     */
+    design: GuardDesignConfigSchema.optional(),
   })
   .strict();
 

package/src/design/__tests__/parser.test.ts

@@ -0,0 +1,195 @@
+/**
+ * DESIGN.md parser tests.
+ *
+ * Cover the structural contract: each of the 9 sections is recognised
+ * across reasonable formatting variants, and a malformed row never
+ * throws — it just gets skipped.
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  parseDesignMd,
+  validateDesignSpec,
+  EMPTY_DESIGN_MD,
+  DESIGN_SECTION_IDS,
+} from "../index";
+
+describe("parseDesignMd", () => {
+  it("parses an empty source without throwing", () => {
+    const spec = parseDesignMd("");
+    expect(spec.title).toBeUndefined();
+    for (const id of DESIGN_SECTION_IDS) {
+      expect(spec.sections[id].present).toBe(false);
+    }
+  });
+
+  it("captures the H1 title", () => {
+    const spec = parseDesignMd("# Acme DESIGN.md\n\n## Color Palette\n\n- primary — #000\n");
+    expect(spec.title).toBe("Acme DESIGN.md");
+    expect(spec.sections["color-palette"].present).toBe(true);
+  });
+
+  it("recognises all 9 sections via fuzzy heading matching", () => {
+    const md = `# X
+
+## Visual Theme & Philosophy
+Minimal and dense.
+
+## Color Palette
+- primary — #FF8C42 — brand action
+
+## Typography
+- display — Inter, 48px, weight 700 — hero
+
+## Components
+### Button
+variant: primary | secondary | ghost
+
+## Layout
+- md — 16px
+
+## Depth & Elevation
+- card: 0 1px 2px rgba(0,0,0,.06)
+
+## Do's & Don'ts
+### Do
+- Use tokens
+
+### Don't
+- Inline btn-hard
+
+## Responsive
+- mobile — 640px
+
+## Agent Prompts
+### hero
+Generate using display token.
+`;
+    const spec = parseDesignMd(md);
+    expect(spec.sections.theme.present).toBe(true);
+    expect(spec.sections.theme.summary).toBe("Minimal and dense.");
+    expect(spec.sections["color-palette"].tokens).toEqual([
+      { name: "primary", value: "#FF8C42", role: "brand action" },
+    ]);
+    expect(spec.sections.typography.tokens[0]?.name).toBe("display");
+    expect(spec.sections.typography.tokens[0]?.size).toBe("48px");
+    expect(spec.sections.components.tokens[0]?.name).toBe("Button");
+    expect(spec.sections.components.tokens[0]?.variants.variant).toEqual([
+      "primary",
+      "secondary",
+      "ghost",
+    ]);
+    expect(spec.sections.layout.tokens[0]).toEqual({ name: "md", value: "16px" });
+    expect(spec.sections.shadows.tokens[0]?.name).toBe("card");
+    expect(spec.sections["dos-donts"].rules.find((r) => r.kind === "do")?.text).toBe(
+      "Use tokens",
+    );
+    expect(spec.sections["dos-donts"].rules.find((r) => r.kind === "dont")?.text).toBe(
+      "Inline btn-hard",
+    );
+    expect(spec.sections.responsive.breakpoints[0]).toEqual({
+      name: "mobile",
+      value: "640px",
+      notes: undefined,
+    });
+    expect(spec.sections["agent-prompts"].prompts[0]?.title).toBe("hero");
+  });
+
+  it("treats unknown H2 sections as extras (round-trip)", () => {
+    const md = `## Color Palette\n- primary — #000\n\n## Internationalization\nKO + EN only.\n`;
+    const spec = parseDesignMd(md);
+    expect(spec.sections["color-palette"].present).toBe(true);
+    expect(spec.extraSections).toHaveLength(1);
+    expect(spec.extraSections[0]?.heading).toBe("Internationalization");
+  });
+
+  it("absorbs malformed rows without throwing", () => {
+    const md = `## Color Palette
+- primary — #FF8C42 — brand
+- garbage row with no shape at all
+- — — — —
+- accent — not-a-color — ok
+`;
+    expect(() => parseDesignMd(md)).not.toThrow();
+    const spec = parseDesignMd(md);
+    const tokens = spec.sections["color-palette"].tokens;
+    // primary (with hex) survives. accent (no hex) is captured with name+role only.
+    expect(tokens.find((t) => t.name === "primary")?.value).toBe("#FF8C42");
+    expect(tokens.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("supports markdown table rows for color palette", () => {
+    const md = `## Color Palette
+| Name | Hex | Role |
+|------|-----|------|
+| primary | #000000 | brand |
+| surface | #ffffff | background |
+`;
+    const spec = parseDesignMd(md);
+    const names = spec.sections["color-palette"].tokens.map((t) => t.name);
+    expect(names).toContain("primary");
+    expect(names).toContain("surface");
+  });
+
+  it("parses the empty skeleton without finding tokens", () => {
+    const spec = parseDesignMd(EMPTY_DESIGN_MD);
+    expect(spec.title).toBe("DESIGN.md");
+    // All sections are present (headings exist) but have no structured tokens.
+    for (const id of DESIGN_SECTION_IDS) {
+      expect(spec.sections[id].present).toBe(true);
+    }
+    expect(spec.sections["color-palette"].tokens).toEqual([]);
+  });
+});
+
+describe("validateDesignSpec", () => {
+  it("flags empty source with all 9 missing", () => {
+    const result = validateDesignSpec(parseDesignMd(""));
+    expect(result.ok).toBe(false);
+    expect(result.issues.filter((i) => i.kind === "missing")).toHaveLength(9);
+  });
+
+  it("flags the empty skeleton as `empty` for every section", () => {
+    const result = validateDesignSpec(parseDesignMd(EMPTY_DESIGN_MD));
+    // All sections present, all empty — so no `missing`, all `empty`.
+    expect(result.issues.every((i) => i.kind === "empty")).toBe(true);
+    expect(result.issues).toHaveLength(9);
+  });
+
+  it("returns ok=true when every section has structured content", () => {
+    const md = `# X
+
+## Visual Theme & Philosophy
+Minimal.
+
+## Color Palette
+- primary — #000
+
+## Typography
+- body — Inter, 16px
+
+## Components
+### Button
+variant: primary | secondary
+
+## Layout
+- md — 16px
+
+## Depth & Elevation
+- card: 0 1px 2px rgba(0,0,0,.06)
+
+## Do's & Don'ts
+### Do
+- Use tokens
+
+## Responsive
+- mobile — 640px
+
+## Agent Prompts
+### default
+Use tokens.
+`;
+    const result = validateDesignSpec(parseDesignMd(md));
+    expect(result.ok).toBe(true);
+    expect(result.issues).toHaveLength(0);
+  });
+});

package/src/design/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@mandujs/core/design` — DESIGN.md primitives.
+ *
+ * Public surface for Issue #245 M1 (parser + scaffold + import +
+ * validate). Other modules — Guard rule, MCP discovery, token bridge —
+ * consume `parseDesignMd` and the `DesignSpec` type.
+ *
+ * @module core/design
+ */
+
+export {
+  parseDesignMd,
+  validateDesignSpec,
+  humanizeSectionId,
+} from "./parser";
+
+export {
+  EMPTY_DESIGN_MD,
+  fetchUpstreamDesignMd,
+  AWESOME_DESIGN_MD_RAW_BASE,
+} from "./scaffold";
+
+export type {
+  AgentPrompt,
+  AgentPromptsSection,
+  AnyDesignSection,
+  ColorPaletteSection,
+  ColorToken,
+  ComponentToken,
+  ComponentsSection,
+  DesignSection,
+  DesignSectionId,
+  DesignSpec,
+  DoDontRule,
+  DosDontsSection,
+  LayoutSection,
+  ResponsiveBreakpoint,
+  ResponsiveSection,
+  ShadowToken,
+  ShadowsSection,
+  SpacingToken,
+  ThemeSection,
+  TypographyToken,
+  TypographySection,
+  ValidationIssue,
+  ValidationResult,
+} from "./types";
+
+export { DESIGN_SECTION_IDS } from "./types";