1// Parse a DESIGN.md (Stitch-spec format) into a structured JSON model that
2// the live-mode design-system panel can render. Deterministic, dependency-free.
3//
4// Two-layer: YAML frontmatter (machine-readable tokens) + markdown body
5// (prose with six canonical H2 sections). When frontmatter is present, it's
6// exposed on `model.frontmatter` alongside the prose-scraped sections;
7// consumers can prefer frontmatter values and fall back to prose.
8 
9const CANONICAL_SECTIONS = [
10  'Overview',
11  'Colors',
12  'Typography',
13  'Elevation',
14  'Components',
15  "Do's and Don'ts",
16];
17 
18// ---------- Frontmatter (Stitch YAML subset) ----------
19 
20function parseFrontmatter(md) {
21  const lines = md.split(/\r?\n/);
22  if (lines[0]?.trim() !== '---') return { frontmatter: null, body: md };
23 
24  let end = -1;
25  for (let i = 1; i < lines.length; i++) {
26    if (lines[i].trim() === '---') { end = i; break; }
27  }
28  if (end === -1) return { frontmatter: null, body: md };
29 
30  const yaml = lines.slice(1, end).join('\n');
31  const body = lines.slice(end + 1).join('\n');
32  try {
33    return { frontmatter: parseYamlSubset(yaml), body };
34  } catch {
35    return { frontmatter: null, body: md };
36  }
37}
38 
39// Minimal YAML reader for the Stitch frontmatter subset: scalar maps with
40// one level of nested objects (typography roles, components). Indent-based,
41// 2-space convention. No arrays, no anchors, no multi-line scalars — Stitch's
42// schema doesn't need them and accepting them would require a real YAML
43// dependency we don't want to vendor.
44function parseYamlSubset(yaml) {
45  const lines = yaml.split(/\r?\n/);
46  const root = {};
47  const stack = [{ indent: -1, obj: root }];
48 
49  for (const raw of lines) {
50    // Skip blanks and line-only comments. Don't strip inline comments:
51    // unquoted hex values start with `#` and can't be safely distinguished
52    // from a comment after whitespace.
53    if (!raw.trim() || /^\s*#/.test(raw)) continue;
54 
55    const indent = raw.match(/^\s*/)[0].length;
56    const content = raw.slice(indent);
57 
58    const colonIdx = findTopLevelColon(content);
59    if (colonIdx === -1) continue;
60 
61    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
62      stack.pop();
63    }
64 
65    const key = unquoteYamlKey(content.slice(0, colonIdx).trim());
66    const rest = stripInlineYamlComment(content.slice(colonIdx + 1).trim());
67    const parent = stack[stack.length - 1].obj;
68 
69    if (rest === '') {
70      const obj = {};
71      parent[key] = obj;
72      stack.push({ indent, obj });
73    } else {
74      parent[key] = parseScalar(rest);
75    }
76  }
77 
78  return root;
79}
80 
81function findTopLevelColon(s) {
82  let inQuote = null;
83  for (let i = 0; i < s.length; i++) {
84    const ch = s[i];
85    if (inQuote) {
86      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
87    } else if (ch === '"' || ch === "'") {
88      inQuote = ch;
89    } else if (ch === ':') {
90      return i;
91    }
92  }
93  return -1;
94}
95 
96function unquoteYamlKey(key) {
97  if ((key.startsWith('"') && key.endsWith('"')) || (key.startsWith("'") && key.endsWith("'"))) {
98    return key.slice(1, -1);
99  }
100  return key;
101}
102 
103function stripInlineYamlComment(s) {
104  let inQuote = null;
105  for (let i = 0; i < s.length; i++) {
106    const ch = s[i];
107    if (inQuote) {
108      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
109    } else if (ch === '"' || ch === "'") {
110      inQuote = ch;
111    } else if (ch === '#' && i > 0 && /\s/.test(s[i - 1])) {
112      return s.slice(0, i).trimEnd();
113    }
114  }
115  return s;
116}
117 
118function parseScalar(raw) {
119  const s = raw.trim();
120  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
121    return s.slice(1, -1);
122  }
123  if (s === 'true') return true;
124  if (s === 'false') return false;
125  if (s === 'null' || s === '~') return null;
126  if (/^-?\d+$/.test(s)) return Number(s);
127  if (/^-?\d*\.\d+$/.test(s)) return Number(s);
128  return s;
129}
130 
131const HEX_RE = /#[0-9a-fA-F]{3,8}\b/g;
132const OKLCH_RE = /oklch\([^)]+\)/gi;
133const RGBA_RE = /rgba?\([^)]+\)/gi;
134const BOX_SHADOW_RE = /(?:box-shadow:\s*)?((?:-?\d[\w\d\s\-.,/()#%]*)+)/;
135const NAMED_RULE_RE = /\*\*(The [^*]+?Rule)\.\*\*\s*(.+)/;
136 
137// ---------- Section splitting ----------
138 
139function splitSections(md) {
140  const lines = md.split(/\r?\n/);
141  let title = null;
142  const sections = {};
143  let current = null;
144 
145  for (const raw of lines) {
146    const line = raw.trimEnd();
147 
148    if (!title && line.startsWith('# ') && !line.startsWith('## ')) {
149      title = line.replace(/^#\s+/, '').trim();
150      continue;
151    }
152 
153    const h2 = line.match(/^##\s+(?:\d+\.\s*)?([^:\n]+?)(?::\s*(.+))?$/);
154    if (h2) {
155      const rawName = normalizeApostrophes(h2[1].trim());
156      const subtitle = h2[2] ? h2[2].trim() : null;
157      const canonical = matchCanonicalSection(rawName);
158      if (canonical) {
159        current = { name: canonical, subtitle, lines: [] };
160        sections[canonical] = current;
161        continue;
162      }
163      // non-canonical H2 — ignore but stop feeding into current
164      current = null;
165      continue;
166    }
167 
168    if (current) current.lines.push(raw);
169  }
170 
171  return { title, sections };
172}
173 
174function normalizeApostrophes(s) {
175  return s.replace(/[\u2018\u2019]/g, "'");
176}
177 
178function matchCanonicalSection(name) {
179  const normalized = normalizeApostrophes(name).toLowerCase();
180  // Exact match first
181  for (const c of CANONICAL_SECTIONS) {
182    if (normalizeApostrophes(c).toLowerCase() === normalized) return c;
183  }
184  // Keyword-contained match: "Overview & Creative North Star" -> "Overview",
185  // "Elevation & Depth" -> "Elevation", etc.
186  for (const c of CANONICAL_SECTIONS) {
187    const key = normalizeApostrophes(c).toLowerCase();
188    const pattern = new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
189    if (pattern.test(normalized)) return c;
190  }
191  return null;
192}
193 
194// ---------- Subsection splitting (inside a canonical section) ----------
195 
196function splitSubsections(lines) {
197  const subs = [];
198  let current = { name: null, lines: [] };
199  subs.push(current);
200 
201  for (const raw of lines) {
202    const h3 = raw.match(/^###\s+(.+?)\s*$/);
203    if (h3) {
204      current = { name: h3[1].trim(), lines: [] };
205      subs.push(current);
206      continue;
207    }
208    current.lines.push(raw);
209  }
210 
211  return subs;
212}
213 
214// ---------- Generic helpers ----------
215 
216function collectParagraphs(lines) {
217  const paragraphs = [];
218  let buf = [];
219  const flush = () => {
220    if (buf.length) {
221      paragraphs.push(buf.join(' ').trim());
222      buf = [];
223    }
224  };
225  for (const raw of lines) {
226    const trimmed = raw.trim();
227    if (trimmed === '') { flush(); continue; }
228    // Horizontal rules (---, ***) and headings/bullets end a paragraph.
229    if (/^(?:-{3,}|\*{3,}|_{3,})$/.test(trimmed)) { flush(); continue; }
230    if (raw.startsWith('#') || raw.match(/^[-*]\s/)) { flush(); continue; }
231    buf.push(trimmed);
232  }
233  flush();
234  return paragraphs.filter(Boolean);
235}
236 
237function collectBullets(lines) {
238  const bullets = [];
239  let current = null;
240  for (const raw of lines) {
241    const m = raw.match(/^\s*[-*]\s+(.+)$/);
242    if (m) {
243      if (current) bullets.push(current);
244      current = m[1];
245      continue;
246    }
247    // continuation of a bullet (indented line)
248    if (current && raw.match(/^\s{2,}\S/)) {
249      current += ' ' + raw.trim();
250      continue;
251    }
252    // blank line ends a bullet
253    if (raw.trim() === '' && current) {
254      bullets.push(current);
255      current = null;
256    }
257  }
258  if (current) bullets.push(current);
259  return bullets;
260}
261 
262function stripBold(s) {
263  return s.replace(/\*\*(.+?)\*\*/g, '$1');
264}
265 
266function extractNamedRules(lines) {
267  const rules = [];
268  const seen = new Set();
269 
270  // Style A (Impeccable): "**The X Rule.** body body body" — can span lines.
271  const joined = lines.join('\n');
272  const inlineStart = /\*\*(The [^*]+?Rule)\.\*\*/g;
273  const inlineMatches = [];
274  let m;
275  while ((m = inlineStart.exec(joined)) !== null) {
276    inlineMatches.push({ name: m[1], start: m.index, end: inlineStart.lastIndex });
277  }
278  for (let i = 0; i < inlineMatches.length; i++) {
279    const mm = inlineMatches[i];
280    const bodyEnd = i + 1 < inlineMatches.length ? inlineMatches[i + 1].start : joined.length;
281    const body = joined
282      .slice(mm.end, bodyEnd)
283      .replace(/\n##[^\n]*$/s, '')
284      .replace(/\n###[^\n]*$/s, '')
285      .trim();
286    const name = stripBold(mm.name).trim();
287    seen.add(name.toLowerCase());
288    rules.push({ name, body: stripBold(body) });
289  }
290 
291  // Style B (Stitch): `### The "X" Rule` or `### The X Fallback`, body is the
292  // bullets/paragraphs until the next heading. Accept Rule / Fallback / Principle.
293  for (let i = 0; i < lines.length; i++) {
294    const h3 = lines[i].match(/^###\s+(.+?)\s*$/);
295    if (!h3) continue;
296    const headerName = stripBold(h3[1]).replace(/["“”]/g, '').trim();
297    if (!/^The\b.*\b(Rule|Fallback|Principle)\b/i.test(headerName)) continue;
298    if (seen.has(headerName.toLowerCase())) continue;
299 
300    const bodyLines = [];
301    for (let j = i + 1; j < lines.length; j++) {
302      if (/^##\s|^###\s/.test(lines[j])) break;
303      bodyLines.push(lines[j]);
304    }
305    const body = stripBold(bodyLines.join('\n').replace(/\n+/g, ' ')).trim();
306    if (body) {
307      seen.add(headerName.toLowerCase());
308      rules.push({ name: headerName, body });
309    }
310  }
311 
312  // Style C (Stitch bullet form): "*   **The Layering Principle:** body"
313  // Colon/period lives inside the bold, so match "**...**" then inspect.
314  for (const b of collectBullets(lines)) {
315    const mm = b.match(/^\*\*([^*]+?)\*\*\s*(.+)$/);
316    if (!mm) continue;
317    const nameRaw = mm[1].replace(/[.:]\s*$/, '').replace(/["“”]/g, '').trim();
318    if (!/^The\b.+\b(Rule|Fallback|Principle)$/i.test(nameRaw)) continue;
319    if (seen.has(nameRaw.toLowerCase())) continue;
320    seen.add(nameRaw.toLowerCase());
321    rules.push({ name: nameRaw, body: stripBold(mm[2]).trim() });
322  }
323 
324  return rules;
325}
326 
327// ---------- Per-section extractors ----------
328 
329function extractOverview(section) {
330  if (!section) return null;
331  const text = section.lines.join('\n');
332  const northStar = text.match(/\*\*Creative North Star:\s*"([^"]+)"\*\*/);
333  const keyChars = [];
334  const keyCharMatch = text.match(/\*\*Key Characteristics:\*\*\s*\n([\s\S]+?)(?:\n##|\n###|$)/);
335  if (keyCharMatch) {
336    for (const line of keyCharMatch[1].split('\n')) {
337      const m = line.match(/^\s*[-*]\s+(.+)$/);
338      if (m) keyChars.push(stripBold(m[1].trim()));
339    }
340  }
341 
342  // Philosophy paragraphs: everything that isn't a rule header or key-char block
343  const paragraphs = collectParagraphs(section.lines).filter(
344    (p) =>
345      !p.startsWith('**Creative North Star') &&
346      !p.startsWith('**Key Characteristics')
347  );
348 
349  return {
350    subtitle: section.subtitle,
351    creativeNorthStar: northStar ? northStar[1] : null,
352    philosophy: paragraphs,
353    keyCharacteristics: keyChars,
354  };
355}
356 
357function extractColors(section) {
358  if (!section) return null;
359  const subs = splitSubsections(section.lines);
360 
361  const description = collectParagraphs(subs[0].lines).join(' ');
362  const groups = [];
363  const ROLE_KEYWORDS = /^(primary|secondary|tertiary|neutral|accent)\b/i;
364 
365  for (const sub of subs.slice(1)) {
366    if (!sub.name || /Named Rules?/i.test(sub.name) || /^The\s/i.test(sub.name)) continue;
367 
368    const bullets = collectBullets(sub.lines);
369    const parsed = bullets.map((b) => parseColorBullet(b)).filter(Boolean);
370    if (parsed.length === 0) continue;
371 
372    // If every bullet starts with a role keyword (Primary/Secondary/...), promote
373    // each bullet to its own group. Otherwise keep the subsection as the group.
374    const allRoleBullets =
375      parsed.length > 0 && parsed.every((p) => p.name && ROLE_KEYWORDS.test(p.name));
376 
377    if (allRoleBullets) {
378      for (const p of parsed) {
379        groups.push({ role: p.name, colors: [p] });
380      }
381    } else {
382      groups.push({ role: sub.name, colors: parsed });
383    }
384  }
385 
386  // If the Colors section has no subsections at all (unlikely), fall back to
387  // scanning the whole section as a flat bullet list.
388  if (groups.length === 0) {
389    const flat = collectBullets(section.lines)
390      .map((b) => parseColorBullet(b))
391      .filter(Boolean);
392    if (flat.length) {
393      for (const p of flat) {
394        if (p.name && ROLE_KEYWORDS.test(p.name)) {
395          groups.push({ role: p.name, colors: [p] });
396        } else {
397          const fallback = groups.find((g) => g.role === 'Palette');
398          if (fallback) fallback.colors.push(p);
399          else groups.push({ role: 'Palette', colors: [p] });
400        }
401      }
402    }
403  }
404 
405  return {
406    subtitle: section.subtitle,
407    description: description || null,
408    groups,
409    rules: extractNamedRules(section.lines),
410  };
411}
412 
413function parseColorBullet(bullet) {
414  const text = bullet.trim();
415 
416  // Case 1 (Impeccable): **Name** (value-with-maybe-nested-parens): description
417  const bold = text.match(/^\*\*(.+?)\*\*\s*(.*)$/);
418  if (bold && bold[2].startsWith('(')) {
419    const value = extractParenGroup(bold[2]);
420    if (value !== null) {
421      const after = bold[2].slice(value.length + 2).trimStart();
422      if (after.startsWith(':')) {
423        return buildColor(bold[1], value, after.slice(1).trim());
424      }
425    }
426  }
427 
428  // Case 2 (Stitch): **Name (values):** description   — value embedded in bold.
429  const stitch = text.match(/^\*\*([^*]+?)\s*\(([^)]+)\):\*\*\s*(.*)$/);
430  if (stitch) {
431    return buildColor(stitch[1].trim(), stitch[2], stitch[3]);
432  }
433 
434  // Case 3: bullet without bold, just hex/oklch inside.
435  const values = collectColorValues(text);
436  if (values.length) {
437    return buildColor(null, values.join(' to '), text);
438  }
439  return null;
440}
441 
442function extractParenGroup(s) {
443  if (s[0] !== '(') return null;
444  let depth = 0;
445  for (let i = 0; i < s.length; i++) {
446    if (s[i] === '(') depth++;
447    else if (s[i] === ')') {
448      depth--;
449      if (depth === 0) return s.slice(1, i);
450    }
451  }
452  return null;
453}
454 
455function buildColor(name, rawValue, description) {
456  const values = collectColorValues(rawValue);
457  const primary = values[0] ?? rawValue.trim();
458  return {
459    name: name ? stripBold(name).trim() : null,
460    value: primary,
461    valueRange: values.length > 1 ? values : null,
462    format: detectFormat(primary),
463    description: stripBold(description || '').trim() || null,
464  };
465}
466 
467function collectColorValues(s) {
468  const out = [];
469  s.replace(HEX_RE, (v) => {
470    out.push(v);
471    return v;
472  });
473  s.replace(OKLCH_RE, (v) => {
474    out.push(v);
475    return v;
476  });
477  return out;
478}
479 
480function detectFormat(v) {
481  if (!v) return 'unknown';
482  if (v.startsWith('#')) return 'hex';
483  if (/^oklch/i.test(v)) return 'oklch';
484  if (/^rgb/i.test(v)) return 'rgb';
485  return 'unknown';
486}
487 
488function scanInlineColors(lines) {
489  const out = [];
490  for (const line of lines) {
491    if (!/^\s*[-*]\s/.test(line)) continue;
492    const trimmed = line.replace(/^\s*[-*]\s+/, '');
493    const color = parseColorBullet(trimmed);
494    if (color) out.push(color);
495  }
496  return out;
497}
498 
499function parseStitchInlineGroups(lines) {
500  // Stitch writes: `*   **Primary (`#00478d` to `#005eb8`):** Use for "..."`
501  // Each bullet IS its own role. Group them under the spoken role name.
502  const out = [];
503  for (const line of lines) {
504    if (!/^\s*[-*]\s/.test(line)) continue;
505    const trimmed = line.replace(/^\s*[-*]\s+/, '').trim();
506    const m = trimmed.match(
507      /^\*\*([A-Z][a-zA-Z]+)\s*\(([^)]+)\):\*\*\s*(.*)$/
508    );
509    if (m) {
510      const role = m[1];
511      const color = buildColor(role, m[2], m[3]);
512      out.push({ role, colors: [color] });
513    }
514  }
515  return out;
516}
517 
518function extractTypography(section) {
519  if (!section) return null;
520  const text = section.lines.join('\n');
521 
522  const fonts = {};
523  // Pattern A: **Display Font:** Family (with fallback)
524  const fontLineRe = /\*\*([\w\s/]+?)Font:\*\*\s*([^\n(]+?)(?:\s*\(with\s+([^)]+)\))?\s*$/gm;
525  let fm;
526  while ((fm = fontLineRe.exec(text)) !== null) {
527    const rawRole = fm[1].trim().toLowerCase().replace(/\s+/g, '-');
528    const role = normalizeFontRole(rawRole) || 'display';
529    fonts[role] = {
530      family: fm[2].trim(),
531      fallback: fm[3] ? fm[3].trim() : null,
532    };
533  }
534 
535  // Pattern B (Stitch): *   **Display & Headlines (Noto Serif):** description
536  if (Object.keys(fonts).length === 0) {
537    const stitchRe = /\*\*([\w\s&/]+?)\s*\(([^)]+)\):\*\*\s*(.+)/g;
538    let sm;
539    while ((sm = stitchRe.exec(text)) !== null) {
540      const rawRole = sm[1]
541        .trim()
542        .toLowerCase()
543        .replace(/\s*&\s*/g, '-')
544        .replace(/\s+/g, '-');
545      const role = normalizeFontRole(rawRole) || rawRole;
546      fonts[role] = { family: sm[2].trim(), fallback: null, purpose: sm[3].trim() };
547    }
548  }
549 
550  // Character paragraph — either a **Character:** label, or fall back to the
551  // first free paragraph under the section header (Stitch style).
552  const characterMatch = text.match(/\*\*Character:\*\*\s*([^\n]+(?:\n[^\n]+)*?)(?=\n\n|\n###|\n##|$)/);
553  let character = characterMatch ? characterMatch[1].replace(/\n/g, ' ').trim() : null;
554  if (!character) {
555    const paragraphs = collectParagraphs(section.lines).filter(
556      (p) => !/^\*\*[\w\s/&]+Font/i.test(p) && !/^\*\*[\w\s/&]+\([^)]+\)/.test(p)
557    );
558    if (paragraphs.length) character = paragraphs[0];
559  }
560 
561  // Hierarchy bullets under ### Hierarchy
562  const subs = splitSubsections(section.lines);
563  let hierarchy = [];
564  const hierSub = subs.find((s) => s.name && /hierarch/i.test(s.name));
565  if (hierSub) {
566    const bullets = collectBullets(hierSub.lines);
567    hierarchy = bullets.map(parseTypeBullet).filter(Boolean);
568  }
569 
570  return {
571    subtitle: section.subtitle,
572    fonts,
573    character,
574    hierarchy,
575    rules: extractNamedRules(section.lines),
576  };
577}
578 
579function normalizeFontRole(raw) {
580  // Canonical roles the panel cares about: display, body, label, mono.
581  // Stitch often writes compound roles like "display-&-headlines" or "ui-&-body"
582  // — collapse them to the first canonical role present.
583  const tokens = raw.split(/[-/&\s]+/).filter(Boolean);
584  const priority = ['display', 'headline', 'body', 'ui', 'label', 'mono'];
585  const canonical = { headline: 'display', ui: 'body' };
586  for (const p of priority) {
587    if (tokens.includes(p)) return canonical[p] || p;
588  }
589  return null;
590}
591 
592function parseTypeBullet(bullet) {
593  // - **Display** (family, weight 300, italic, clamp(...), line-height 1): purpose
594  const m = bullet.match(/^\*\*(.+?)\*\*\s*\(([^)]+)\):\s*(.*)$/);
595  if (!m) return null;
596  const name = m[1].trim();
597  const specs = m[2].split(',').map((s) => s.trim());
598  return {
599    name,
600    specs,
601    purpose: stripBold(m[3] || '').trim() || null,
602  };
603}
604 
605function extractElevation(section) {
606  if (!section) return null;
607  const subs = splitSubsections(section.lines);
608 
609  const description = collectParagraphs(subs[0].lines).join(' ') || null;
610 
611  const shadows = [];
612  const seen = new Set();
613  const dedupe = (entry) => {
614    const key = (entry.name || '') + '::' + entry.value;
615    if (seen.has(key)) return;
616    seen.add(key);
617    shadows.push(entry);
618  };
619 
620  for (const b of collectBullets(section.lines)) {
621    const parsed = parseShadowBullet(b);
622    if (parsed) dedupe(parsed);
623  }
624 
625  // Fallback: extract shadows written inline in prose. Stitch style is
626  //   "...use an extra-diffused shadow: `box-shadow: 0 12px 40px rgba(...)`."
627  for (const p of collectParagraphs(section.lines)) {
628    for (const inline of extractInlineShadows(p)) dedupe(inline);
629  }
630  for (const b of collectBullets(section.lines)) {
631    for (const inline of extractInlineShadows(b)) dedupe(inline);
632  }
633 
634  return {
635    subtitle: section.subtitle,
636    description,
637    shadows,
638    rules: extractNamedRules(section.lines),
639  };
640}
641 
642function extractInlineShadows(text) {
643  // Find `box-shadow: ...` anywhere in prose and capture the value. Work on the
644  // raw string so it handles both backtick-fenced and unfenced variants.
645  const out = [];
646  const re = /box-shadow\s*:\s*([^`;\n]+)/gi;
647  let m;
648  while ((m = re.exec(text)) !== null) {
649    const value = m[1].replace(/[`.)]+$/, '').trim();
650    if (!value) continue;
651    // Name heuristic: the noun immediately before the shadow phrase.
652    // e.g. "an extra-diffused shadow: ..." -> "extra-diffused shadow"
653    const before = text.slice(0, m.index);
654    const nameMatch = before.match(/\b([A-Za-z][A-Za-z\- ]{2,40})\s+shadow\b[^A-Za-z0-9]*$/i);
655    let name = null;
656    if (nameMatch) {
657      const stripped = nameMatch[1]
658        .replace(/^(?:use|using|apply|applying|is|are|looks? like)\s+/i, '')
659        .replace(/^(?:a|an|the)\s+/i, '')
660        .trim();
661      if (stripped) {
662        name =
663          stripped.charAt(0).toUpperCase() + stripped.slice(1) + ' shadow';
664      }
665    }
666    out.push({
667      name,
668      value,
669      purpose: null,
670    });
671  }
672  return out;
673}
674 
675function parseShadowBullet(bullet) {
676  // - **Name** (`box-shadow: value`): purpose
677  // - **Name** (`value`): purpose
678  // Only accept if the paren content looks like a shadow value (contains px,
679  // rem, rgba, or box-shadow). This filters out `**Rule Name:**` bullets.
680  const m = bullet.match(/^\*\*(.+?)\*\*\s*\(`?([^`]+?)`?\):\s*(.*)$/);
681  if (!m) return null;
682  const rawValue = m[2].replace(/^box-shadow:\s*/i, '').trim();
683  const looksLikeShadow =
684    /box-shadow|rgba?\(|\bpx\b|\brem\b|^-?\d+\s/i.test(rawValue) &&
685    /\d/.test(rawValue);
686  if (!looksLikeShadow) return null;
687  const name = stripBold(m[1]).trim();
688  return {
689    name,
690    value: rawValue,
691    purpose: stripBold(m[3] || '').trim() || null,
692  };
693}
694 
695function extractComponents(section) {
696  if (!section) return null;
697  const subs = splitSubsections(section.lines);
698  const components = [];
699 
700  for (const sub of subs.slice(1)) {
701    if (!sub.name) continue;
702 
703    const bullets = collectBullets(sub.lines);
704    const paragraphs = collectParagraphs(sub.lines);
705 
706    const variants = [];
707    const properties = {};
708 
709    for (const b of bullets) {
710      // - **Key:** value
711      const m = b.match(/^\*\*(.+?):?\*\*:?\s*(.+)$/);
712      if (m) {
713        const key = stripBold(m[1]).trim();
714        const value = stripBold(m[2]).trim();
715        // Heuristic: "Primary", "Secondary", "Hover", "Focus" etc are variants;
716        // "Shape", "Background", "Padding" are properties.
717        if (/^(primary|secondary|tertiary|ghost|hover|focus|active|disabled|default|error|selected|unselected|state)$/i.test(key.split(/[\s/]/)[0])) {
718          variants.push({ name: key, description: value });
719        } else {
720          properties[key.toLowerCase()] = value;
721        }
722      }
723    }
724 
725    components.push({
726      name: sub.name,
727      description: paragraphs.join(' ') || null,
728      properties,
729      variants,
730    });
731  }
732 
733  return {
734    subtitle: section.subtitle,
735    components,
736  };
737}
738 
739function extractDosDonts(section) {
740  if (!section) return null;
741  const subs = splitSubsections(section.lines);
742  const dos = [];
743  const donts = [];
744 
745  for (const sub of subs.slice(1)) {
746    if (!sub.name) continue;
747    const subName = normalizeApostrophes(sub.name);
748    const bullets = collectBullets(sub.lines).map((b) => stripBold(b).trim());
749    if (/^do'?t?:?$/i.test(subName) || /^do:?$/i.test(subName)) {
750      dos.push(...bullets);
751    } else if (/^don'?t:?$/i.test(subName)) {
752      donts.push(...bullets);
753    }
754  }
755 
756  // Classify by bullet prefix as a backup (catches loose bullets outside H3 wrappers)
757  for (const b of collectBullets(section.lines)) {
758    const stripped = normalizeApostrophes(stripBold(b).trim());
759    if (/^don'?t\b/i.test(stripped)) {
760      if (!donts.some((d) => normalizeApostrophes(d) === stripped)) donts.push(stripped);
761    } else if (/^do\b/i.test(stripped)) {
762      if (!dos.some((d) => normalizeApostrophes(d) === stripped)) dos.push(stripped);
763    }
764  }
765 
766  return { dos, donts };
767}
768 
769// ---------- Coverage assessment ----------
770 
771function assessCoverage(model) {
772  const report = {};
773 
774  report.overview = model.overview
775    ? {
776        northStar: Boolean(model.overview.creativeNorthStar),
777        philosophy: model.overview.philosophy.length > 0,
778        keyCharacteristics: model.overview.keyCharacteristics.length,
779      }
780    : 'missing';
781 
782  report.colors = model.colors
783    ? {
784        groups: model.colors.groups.length,
785        totalColors: model.colors.groups.reduce((n, g) => n + g.colors.length, 0),
786        rules: model.colors.rules.length,
787      }
788    : 'missing';
789 
790  report.typography = model.typography
791    ? {
792        fonts: Object.keys(model.typography.fonts).length,
793        hierarchyEntries: model.typography.hierarchy.length,
794        character: Boolean(model.typography.character),
795        rules: model.typography.rules.length,
796      }
797    : 'missing';
798 
799  report.elevation = model.elevation
800    ? {
801        shadows: model.elevation.shadows.length,
802        rules: model.elevation.rules.length,
803        description: Boolean(model.elevation.description),
804      }
805    : 'missing';
806 
807  report.components = model.components
808    ? {
809        count: model.components.components.length,
810        variantTotal: model.components.components.reduce((n, c) => n + c.variants.length, 0),
811      }
812    : 'missing';
813 
814  report.dosDonts = model.dosDonts
815    ? {
816        dos: model.dosDonts.dos.length,
817        donts: model.dosDonts.donts.length,
818      }
819    : 'missing';
820 
821  return report;
822}
823 
824// ---------- Main ----------
825 
826export function parseDesignMd(md) {
827  const { frontmatter, body } = parseFrontmatter(md);
828  const { title, sections } = splitSections(body);
829  return {
830    schemaVersion: 2,
831    title,
832    frontmatter,
833    overview: extractOverview(sections['Overview']),
834    colors: extractColors(sections['Colors']),
835    typography: extractTypography(sections['Typography']),
836    elevation: extractElevation(sections['Elevation']),
837    components: extractComponents(sections['Components']),
838    dosDonts: extractDosDonts(sections["Do's and Don'ts"]),
839  };
840}
841 
842export { assessCoverage };
843