@cyber-dash-tech/revela 0.18.15 → 0.19.0

package/lib/design/designs.ts

@@ -3,7 +3,9 @@
  *
  * User designs are stored in ~/.config/revela/designs/<name>/.
  * Built-in designs are shipped read-only with this package under designs/<name>/.
- * Each design directory contains DESIGN.md (required) and optionally preview.html.
+ * Each design directory contains DESIGN.md (required), design.css for CSS-native styling,
+ * and optionally legacy preview.html. Current previews are generated from the built-in
+ * page-template fixture plus the design CSS.
  */
 
 import {
@@ -17,8 +19,9 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { dirname, join, resolve, basename, relative, sep } from "path"
+import { dirname, join, normalize, resolve, basename, relative, sep } from "path"
 import { tmpdir } from "os"
+import { pathToFileURL } from "url"
 import { parseFrontmatter } from "../frontmatter"
 import { collectDirectoryEntries, extractEntriesToDirectory, normalizePackageArchiveEntries, readTarArchive, writeTarArchive } from "./archive"
 import {
@@ -28,11 +31,14 @@ import {
   saveConfig,
 } from "../config"
 import { childLog } from "../log"
+import { PAGE_TEMPLATE_CLASSES, listPageTemplateVocabulary, templateDeckCss } from "../page-templates"
 
 const designLog = childLog("designs")
 
 // Seed directory: built-in designs shipped with this package.
 const SEED_DIR = resolve(__dirname, "../..", "designs")
+const BUILT_IN_PREVIEW_PATH = resolve(__dirname, "..", "page-templates", "built-in-preview.html")
+const PREVIEW_FALLBACK_ASSET_DESIGN = "lucent"
 
 export interface DesignInfo {
   name: string
@@ -51,7 +57,8 @@ export interface CreateDesignPackageArgs {
   name: string
   base?: string
   designMd: string
-  previewHtml: string
+  designCss?: string
+  previewHtml?: string
   assets?: DesignPackageAssetInput[]
   overwrite?: boolean
 }
@@ -85,6 +92,7 @@ export interface ValidateDesignPackageResult {
   name: string
   path: string
   hasDesignMd: boolean
+  hasDesignCss: boolean
   hasPreview: boolean
   hasMarkers: boolean
   sections: string[]
@@ -92,6 +100,7 @@ export interface ValidateDesignPackageResult {
   components: string[]
   assets: DesignPackageAssetInfo[]
   errors: string[]
+  warnings: string[]
 }
 
 export interface DesignPackageAssetInput {
@@ -143,6 +152,37 @@ export interface DesignPreviewInfo {
   hasPreview: boolean
 }
 
+export interface MaterializeDesignPreviewArgs {
+  workspaceRoot: string
+  name: string
+  source?: "draft" | "installed" | "builtin"
+}
+
+export interface MaterializeDesignPreviewResult {
+  ok: true
+  name: string
+  source: "draft" | "installed" | "builtin"
+  designDir: string
+  previewDir: string
+  previewPath: string
+  previewUrl: string
+  designCssPath: string
+  files: string[]
+  warnings: string[]
+}
+
+export interface DesignCssSnapshotResult {
+  ok: true
+  design: string
+  sourcePath: string
+  snapshotDir: string
+  cssPath: string
+  href: string
+  assetCount: number
+  generatedFallback: boolean
+  warnings: string[]
+}
+
 // ---------------------------------------------------------------------------
 // Seed
 // ---------------------------------------------------------------------------
@@ -299,6 +339,115 @@ export function resolveDesignPreview(name?: string): DesignPreviewInfo {
   }
 }
 
+export function materializeDesignPreview(args: MaterializeDesignPreviewArgs): MaterializeDesignPreviewResult {
+  const name = normalizeDesignName(args.name)
+  const { designDir, source } = resolveDesignPreviewSourceDir(args.workspaceRoot, name, args.source)
+  const previewDir = resolve(args.workspaceRoot, ".revela", "previews", "designs", name)
+  const previewPath = join(previewDir, "preview.html")
+  const designCssPath = join(previewDir, "design.css")
+  const warnings: string[] = []
+
+  if (!existsSync(BUILT_IN_PREVIEW_PATH)) {
+    throw new Error(`Built-in design preview fixture is missing: ${BUILT_IN_PREVIEW_PATH}`)
+  }
+
+  rmSync(previewDir, { recursive: true, force: true })
+  mkdirSync(previewDir, { recursive: true })
+
+  const previewHtml = readFileSync(BUILT_IN_PREVIEW_PATH, "utf-8").replace(/data-design="built-in-preview"/g, `data-design="${name}"`)
+  writeFileSync(previewPath, previewHtml, "utf-8")
+
+  const cssRead = readDesignCssFromDir(name, designDir)
+  warnings.push(...cssRead.warnings)
+  writeFileSync(designCssPath, `${cssRead.css.trim()}\n`, "utf-8")
+
+  const sourceAssets = join(designDir, "assets")
+  const targetAssets = join(previewDir, "assets")
+  if (existsSync(sourceAssets)) cpSync(sourceAssets, targetAssets, { recursive: true })
+  copyMissingBuiltInPreviewAssets(previewHtml, targetAssets)
+
+  return {
+    ok: true,
+    name,
+    source,
+    designDir,
+    previewDir,
+    previewPath,
+    previewUrl: pathToFileURL(previewPath).href,
+    designCssPath,
+    files: listDesignPackageFiles(previewDir),
+    warnings,
+  }
+}
+
+export function resolveDesignPackageDir(name?: string): string {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) throw new Error(`Design '${designName}' is not installed`)
+  return designDir
+}
+
+export function readDesignCss(name?: string): { css: string; path?: string; generatedFallback: boolean; warnings: string[] } {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignPackageDir(designName)
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) {
+    return { css: readFileSync(cssPath, "utf-8"), path: cssPath, generatedFallback: false, warnings: [] }
+  }
+
+  const foundation = getDesignSection("foundation", designName)
+  const cssBlocks = extractCssCodeBlocks(foundation)
+  if (cssBlocks.length === 0) throw new Error(`Design '${designName}' has no design.css and no CSS fallback in @design:foundation.`)
+  return {
+    css: [
+      "/* Generated compatibility CSS from DESIGN.md. Add design.css to make this design fully CSS-package native. */",
+      ...cssBlocks,
+      templateDeckCss({ designName, designAssetBasePath: "./assets" }),
+    ].join("\n\n"),
+    generatedFallback: true,
+    warnings: [`Design '${designName}' has no design.css; generated a deck-local compatibility CSS snapshot from DESIGN.md.`],
+  }
+}
+
+export function materializeDesignCssSnapshot(input: {
+  workspaceRoot: string
+  outputPath: string
+  designName?: string
+}): DesignCssSnapshotResult {
+  const designName = normalizeDesignName(input.designName || activeDesign())
+  const designDir = resolveDesignPackageDir(designName)
+  const outputDir = dirname(normalize(input.outputPath))
+  const snapshotRelDir = normalize(join(outputDir, "_revela-design", designName)).replace(/\\/g, "/")
+  const snapshotDir = resolve(input.workspaceRoot, snapshotRelDir)
+  const cssPath = join(snapshotDir, "design.css")
+  const cssRead = readDesignCss(designName)
+
+  mkdirSync(snapshotDir, { recursive: true })
+  writeFileSync(cssPath, cssRead.css.endsWith("\n") ? cssRead.css : `${cssRead.css}\n`, "utf-8")
+
+  const assetsDir = join(designDir, "assets")
+  let assetCount = 0
+  if (existsSync(assetsDir) && statSync(assetsDir).isDirectory()) {
+    const targetAssets = join(snapshotDir, "assets")
+    rmSync(targetAssets, { recursive: true, force: true })
+    cpSync(assetsDir, targetAssets, { recursive: true })
+    assetCount = listDesignPackageFiles(targetAssets).length
+  }
+
+  const href = normalize(relative(outputDir || ".", normalize(join(snapshotRelDir, "design.css")))).replace(/\\/g, "/")
+  return {
+    ok: true,
+    design: designName,
+    sourcePath: cssRead.path || join(designDir, "DESIGN.md"),
+    snapshotDir,
+    cssPath,
+    href: href.startsWith(".") ? href : `./${href}`,
+    assetCount,
+    generatedFallback: cssRead.generatedFallback,
+    warnings: cssRead.warnings,
+  }
+}
+
 /** Normalize and validate a design package name. */
 export function normalizeDesignName(name: string): string {
   const normalized = name.trim().toLowerCase()
@@ -312,10 +461,10 @@ export function normalizeDesignName(name: string): string {
 export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesignPackageResult {
   const name = normalizeDesignName(args.name)
   const designMd = args.designMd?.trim()
+  const designCss = args.designCss?.trim()
   const previewHtml = args.previewHtml?.trim()
 
   if (!designMd) throw new Error("designMd is required")
-  if (!previewHtml) throw new Error("previewHtml is required")
 
   const target = join(DESIGNS_DIR, name)
   const existed = existsSync(target)
@@ -329,7 +478,8 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
   }
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
-  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  if (designCss) writeFileSync(join(target, "design.css"), `${designCss}\n`, "utf-8")
+  if (previewHtml) writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
   writeDesignAssets(target, args.assets)
 
   const validation = validateDesignPackage(name)
@@ -352,10 +502,10 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
 export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDesignPackageResult {
   const name = normalizeDesignName(args.name)
   const designMd = args.designMd?.trim()
+  const designCss = args.designCss?.trim()
   const previewHtml = args.previewHtml?.trim()
 
   if (!designMd) throw new Error("designMd is required")
-  if (!previewHtml) throw new Error("previewHtml is required")
 
   const target = designDraftDir(args.workspaceRoot, name)
   const existed = existsSync(target)
@@ -369,7 +519,8 @@ export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDes
   }
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
-  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  if (designCss) writeFileSync(join(target, "design.css"), `${designCss}\n`, "utf-8")
+  if (previewHtml) writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
   writeDesignAssets(target, args.assets)
 
   const validation = validateDesignDraftPackage(args.workspaceRoot, name)
@@ -551,6 +702,7 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
 function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
   let name = nameInput
   const errors: string[] = []
+  const warnings: string[] = []
   try {
     name = normalizeDesignName(nameInput)
   } catch (e) {
@@ -558,8 +710,10 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
   }
 
   const mdPath = join(dir, "DESIGN.md")
+  const cssPath = join(dir, "design.css")
   const previewPath = join(dir, "preview.html")
   const hasDesignMd = existsSync(mdPath)
+  const hasDesignCss = existsSync(cssPath)
   const hasPreview = existsSync(previewPath)
   let hasMarkers = false
   let sections: string[] = []
@@ -569,7 +723,7 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
 
   if (!existsSync(dir)) errors.push(`Design directory does not exist: ${dir}`)
   if (!hasDesignMd) errors.push("DESIGN.md is missing")
-  if (!hasPreview) errors.push("preview.html is missing")
+  if (!hasDesignCss) warnings.push("design.css is missing; DESIGN.md CSS fallback remains compatibility-only and should be migrated.")
   if (existsSync(dir)) assets = listDesignAssetsInDir(dir)
 
   if (hasDesignMd) {
@@ -593,11 +747,13 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
 
   if (hasPreview) {
     const preview = readFileSync(previewPath, "utf-8")
+    const designCss = hasDesignCss ? readFileSync(cssPath, "utf-8") : ""
     if (!preview.includes('<section class="slide"')) errors.push("preview.html must include slide sections")
     if (!preview.includes("slide-qa=")) errors.push("preview.html slides must include slide-qa attributes")
     if (!preview.includes("slide-canvas")) errors.push("preview.html must include .slide-canvas")
-    if (!hasFixedSizeCssRule(preview, "slide-canvas")) {
-      errors.push("preview.html must define .slide-canvas CSS with width: 1920px and height: 1080px")
+    if (hasDesignCss && !previewReferencesDesignCss(preview)) errors.push("preview.html must reference design.css")
+    if (!hasFixedSizeCssRule(`${preview}\n${designCss}`, "slide-canvas")) {
+      errors.push("preview.html or design.css must define .slide-canvas CSS with width: 1920px and height: 1080px")
     }
     if (!hasSlideRole(preview, "cover")) errors.push('preview.html must include a slide section with data-slide-role="cover"')
     if (!hasSlideRole(preview, "closing")) errors.push('preview.html must include a slide section with data-slide-role="closing"')
@@ -605,13 +761,28 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     if (missingComponents.length > 0) {
       errors.push(`preview.html must showcase every @component; missing: ${missingComponents.join(", ")}`)
     }
+    const missingLayoutPreviews = layouts.filter((layout) => !hasDataAttribute(preview, "data-preview-layout", layout))
+    if (missingLayoutPreviews.length > 0) {
+      warnings.push(`preview.html should mark layout fixtures with data-preview-layout; missing: ${missingLayoutPreviews.join(", ")}`)
+    }
   }
+  if (hasDesignCss) {
+    const designCss = readFileSync(cssPath, "utf-8")
+    const missingCoreClasses = requiredDesignCssClasses().filter((className) => !cssTextHasClassSelector(designCss, className))
+    if (missingCoreClasses.length > 0) errors.push(`design.css must style core template classes; missing: ${missingCoreClasses.map((item) => `.${item}`).join(", ")}`)
+    errors.push(...missingDesignCssAssetErrors(designCss, dir))
+  }
+  const designText = hasDesignMd ? readFileSync(mdPath, "utf-8") : ""
+  const designCss = hasDesignCss ? readFileSync(cssPath, "utf-8") : ""
+  const tokenWarnings = designContractTokenWarnings(`${designText}\n${designCss}`)
+  warnings.push(...tokenWarnings)
 
   return {
     ok: errors.length === 0,
     name,
     path: dir,
     hasDesignMd,
+    hasDesignCss,
     hasPreview,
     hasMarkers,
     sections,
@@ -619,13 +790,141 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     components,
     assets,
     errors,
+    warnings,
+  }
+}
+
+function designContractTokenWarnings(text: string): string[] {
+  const warnings: string[] = []
+  const checks = [
+    { label: "grid", pattern: /--grid-|grid columns|grid-column|column line|safe area|safe-area/i },
+    { label: "spacing", pattern: /--space-|spacing scale|baseline|rhythm unit|gap scale/i },
+    { label: "type scale", pattern: /--font-size-|type scale|typographic scale|line-height/i },
+    { label: "surface", pattern: /--surface|surface token|border token|shadow token/i },
+  ]
+  for (const check of checks) {
+    if (!check.pattern.test(text)) warnings.push(`DESIGN.md/design.css should document ${check.label} design tokens or an equivalent contract`)
   }
+  return warnings
+}
+
+function previewReferencesDesignCss(preview: string): boolean {
+  return /<link\b[^>]*href=["'][^"']*design\.css["'][^>]*>/i.test(preview)
+}
+
+function requiredDesignCssClasses(): string[] {
+  return [
+    "slide-canvas",
+    "template-slide",
+    "template-frame",
+    "template-title",
+    "template-card",
+    "template-visual-slot-panel",
+  ]
+}
+
+function cssTextHasClassSelector(css: string, className: string): boolean {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, "")
+  const ruleRe = /([^{}]+)\{[^{}]*\}/g
+  let match: RegExpExecArray | null
+  while ((match = ruleRe.exec(withoutComments)) !== null) {
+    if (cssRuleHasClassSelector(match[1] ?? "", className)) return true
+  }
+  return false
+}
+
+function missingDesignCssAssetErrors(css: string, designDir: string): string[] {
+  const errors: string[] = []
+  const seen = new Set<string>()
+  const urlRe = /url\(\s*["']?([^"')]+)["']?\s*\)/gi
+  let match: RegExpExecArray | null
+  while ((match = urlRe.exec(css)) !== null) {
+    const raw = match[1].trim()
+    if (!raw || raw.startsWith("data:") || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("#")) continue
+    const normalized = raw.replace(/^\.\/+/, "")
+    if (!normalized.startsWith("assets/")) continue
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    if (!existsSync(join(designDir, ...normalized.split("/")))) errors.push(`design.css references missing asset: ${normalized}`)
+  }
+  return errors
+}
+
+function extractCssCodeBlocks(markdown: string): string[] {
+  const blocks: string[] = []
+  const fenceRe = /```css\n([\s\S]*?)```/g
+  let match: RegExpExecArray | null
+  while ((match = fenceRe.exec(markdown)) !== null) {
+    const body = match[1].trim()
+    if (body) blocks.push(body)
+  }
+  return blocks
 }
 
 function designDraftDir(workspaceRoot: string, name: string): string {
   return resolve(workspaceRoot, ".revela", "drafts", "designs", name)
 }
 
+function resolveDesignPreviewSourceDir(
+  workspaceRoot: string,
+  name: string,
+  requested?: "draft" | "installed" | "builtin",
+): { designDir: string; source: "draft" | "installed" | "builtin" } {
+  const draftDir = designDraftDir(workspaceRoot, name)
+  if (requested === "draft") {
+    if (!existsSync(draftDir)) throw new Error(`Design draft '${name}' does not exist: ${draftDir}`)
+    return { designDir: draftDir, source: "draft" }
+  }
+
+  const installedDir = resolveDesignDir(name)
+  if (requested === "installed" || requested === "builtin") {
+    if (!installedDir) throw new Error(`Design '${name}' is not installed`)
+    const source = requested === "builtin" ? "builtin" : installedDir.startsWith(SEED_DIR + sep) ? "builtin" : "installed"
+    return { designDir: installedDir, source }
+  }
+
+  if (existsSync(draftDir)) return { designDir: draftDir, source: "draft" }
+  if (!installedDir) throw new Error(`Design '${name}' is not available as a workspace draft or installed design`)
+  return { designDir: installedDir, source: installedDir.startsWith(SEED_DIR + sep) ? "builtin" : "installed" }
+}
+
+function readDesignCssFromDir(name: string, designDir: string): { css: string; warnings: string[] } {
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) return { css: readFileSync(cssPath, "utf-8"), warnings: [] }
+
+  const mdPath = join(designDir, "DESIGN.md")
+  const markdown = existsSync(mdPath) ? readFileSync(mdPath, "utf-8") : ""
+  const cssBlocks = extractCssCodeBlocks(markdown)
+  const css = [
+    "/* Generated preview compatibility CSS from DESIGN.md. Add design.css to make this design CSS-native. */",
+    templateDeckCss(),
+    ...cssBlocks,
+  ].join("\n\n")
+  return {
+    css,
+    warnings: [`Design '${name}' has no design.css; generated preview CSS from DESIGN.md compatibility blocks.`],
+  }
+}
+
+function copyMissingBuiltInPreviewAssets(previewHtml: string, targetAssetsDir: string): void {
+  const fallbackAssetsDir = join(SEED_DIR, PREVIEW_FALLBACK_ASSET_DESIGN, "assets")
+  const assetRefs = new Set<string>()
+  const re = /(?:src|href)=["'](?:\.\/)?assets\/([^"']+)["']/g
+  let match: RegExpExecArray | null
+  while ((match = re.exec(previewHtml)) !== null) assetRefs.add(match[1])
+  if (assetRefs.size === 0) return
+
+  mkdirSync(targetAssetsDir, { recursive: true })
+  for (const rel of assetRefs) {
+    const target = resolve(targetAssetsDir, rel)
+    if (existsSync(target)) continue
+    const source = resolve(fallbackAssetsDir, rel)
+    if (!existsSync(source) || !statSync(source).isFile()) continue
+    mkdirSync(dirname(target), { recursive: true })
+    cpSync(source, target)
+  }
+}
+
 function designDraftExists(workspaceRoot: string, name: string): boolean {
   const dir = designDraftDir(workspaceRoot, name)
   return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "DESIGN.md"))
@@ -764,6 +1063,23 @@ export interface DesignInventoryComponent {
     acceptsChildren: boolean
     allowedChildren?: string[]
   }
+  contract?: DesignComponentContract
+}
+
+export interface DesignComponentContractVariant {
+  name: string
+  requiredDescendantClasses: string[]
+  repeatedItemClass?: string
+  requiredItemClasses?: string[]
+  requireAlternatingClasses?: string[]
+}
+
+export interface DesignComponentContract {
+  component: string
+  kind: "structure"
+  requiredRootClasses: string[]
+  variants: DesignComponentContractVariant[]
+  guidance: string
 }
 
 export interface DesignInventory {
@@ -771,6 +1087,12 @@ export interface DesignInventory {
   sections: string[]
   layouts: DesignInventoryLayout[]
   components: DesignInventoryComponent[]
+  pageTemplates: Array<{
+    templateId: string
+    slots: string[]
+    requiredClasses: string[]
+    contractNotes: string[]
+  }>
   assets: DesignPackageAssetInfo[]
   hasMarkers: boolean
 }
@@ -838,17 +1160,19 @@ export function generateComponentIndex(components: Record<string, string>): stri
     const desc = firstLine
       ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
       : ""
-    return `| \`${name}\` | ${desc} |`
+    const contract = inferComponentContract(name, body)
+    const contractLabel = contract ? "✓" : "—"
+    return `| \`${name}\` | ${contractLabel} | ${desc} |`
   })
 
   return [
     "### Component Index",
     "",
-    "| Component | Description |",
-    "|---|---|",
+    "| Component | Contract | Description |",
+    "|---|---|---|",
     ...rows,
     "",
-    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML for any component._",
+    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML and any structure contract for a component._",
   ].join("\n")
 }
 
@@ -908,12 +1232,55 @@ export function getDesignInventory(designName?: string): DesignInventory {
       name: componentName,
       description: designBlockDescription(content),
       nesting: inferComponentNesting(componentName),
+      contract: inferComponentContract(componentName, content),
+    })),
+    pageTemplates: listPageTemplateVocabulary().map((template) => ({
+      templateId: template.templateId,
+      slots: template.slots.map((slot) => slot.name),
+      requiredClasses: template.requiredClasses,
+      contractNotes: template.contractNotes,
     })),
     assets: listDesignAssetsInDir(designDir),
     hasMarkers,
   }
 }
 
+export function extractDesignComponentContracts(designName?: string): DesignComponentContract[] {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) return []
+  const mdPath = join(designDir, "DESIGN.md")
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { components, hasMarkers } = parseDesignSections(body)
+  if (!hasMarkers) return []
+  return Object.entries(components)
+    .map(([componentName, content]) => inferComponentContract(componentName, content))
+    .filter((contract): contract is DesignComponentContract => Boolean(contract))
+}
+
+function inferComponentContract(name: string, content: string): DesignComponentContract | undefined {
+  const mentions = (value: string) => content.includes(value)
+
+  if (name === "roadmap-vertical" && ["tjv-axis", "tjv-item", "tjv-axis-dot", "tjv-stem", "tjv-tip-dot", "tjv-label"].every(mentions)) {
+    return {
+      component: name,
+      kind: "structure",
+      requiredRootClasses: ["roadmap-vertical"],
+      variants: [{
+        name: "timeline-journey-vertical",
+        requiredDescendantClasses: ["tjv-axis"],
+        repeatedItemClass: "tjv-item",
+        requiredItemClasses: ["tjv-axis-dot", "tjv-stem", "tjv-tip-dot", "tjv-label"],
+        requireAlternatingClasses: ["tjv-item--left", "tjv-item--right"],
+      }],
+      guidance: "Use structured milestone props/content to render axis-dot -> stem -> tip-dot -> label rows. Do not hand-roll a simplified axis plus labels.",
+    }
+  }
+
+  return undefined
+}
+
 function inferLayoutSlots(name: string, content: string): string[] {
   const slots = new Set<string>()
   const known = ["fullbleed", "left", "right", "top", "bottom", "main", "footer", "content", "overlay", "center"]
@@ -1145,6 +1512,7 @@ const UNIVERSAL_CLASSES = new Set([
   "overlay",
   "alt",
   "strong",
+  ...PAGE_TEMPLATE_CLASSES,
 ])
 
 /**
@@ -1280,6 +1648,9 @@ export function extractDesignClasses(designName?: string): DesignClassVocabulary
     extractFromSection(content)
   }
 
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) extractFromCss(readFileSync(cssPath, "utf-8"))
+
   return { classes, prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
 }