npm - @maccesar/aiskills - Versions diffs - 1.12.0 → 1.15.0 - Mend

@maccesar/aiskills 1.12.0 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/skills/stitch-showcase/references/viewer.html CHANGED Viewed

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="{{HTML_LANG}}">
 <head>
   <meta charset="UTF-8">
@@ -82,6 +82,18 @@
       background: #fff;
     }
     html.dark #viewer-frame { background: #111; }
+    /* ── Real mobile: hide simulator chrome on small viewports ── */
+    @media (max-width: 639px) {
+      .view-mobile #mobile-frame { padding-top: 0 !important; align-items: stretch !important; }
+      .view-mobile #phone-container { transform: none !important; width: 100% !important; height: 100% !important; }
+      .view-mobile #phone-wrap {
+        width: 100% !important; height: 100% !important;
+        border: none !important; border-radius: 0 !important; box-shadow: none !important;
+      }
+      .view-web #browser-chrome { display: none !important; }
+      .view-web #iframe-wrap-web { border: none !important; border-radius: 0 !important; }
+    }
   </style>
 </head>
@@ -93,20 +105,20 @@
   <!-- ── Header ──────────────────────────────────────────── -->
   <header id="main-header" class="flex-shrink-0 border-b border-gray-200/60 backdrop-blur-xl bg-white/80 dark:border-white/10 dark:bg-[#0a0a0a]/80" style="height:56px">
-    <div class="mx-auto flex h-full max-w-[1440px] items-center gap-3 px-5">
+    <div class="mx-auto flex h-full max-w-[1440px] items-center gap-2 px-3 sm:gap-3 sm:px-5">
       <!-- Back button -->
-      <a id="btn-back" href="index.html" title="Back to gallery (Esc)" class="flex shrink-0 items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-[13px] text-gray-500 no-underline transition-colors hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-white/10 dark:hover:text-gray-100">
+      <a id="btn-back" href="index.html" title="Volver a la galería (Esc)" aria-label="Volver" class="flex shrink-0 items-center gap-1.5 rounded-lg px-2 py-1.5 text-[13px] text-gray-500 no-underline transition-colors hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-white/10 dark:hover:text-gray-100 sm:px-2.5">
         <svg class="h-3.5 w-3.5" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
           <path d="M10 13L5 8l5-5" />
         </svg>
-        Back
+        <span class="hidden sm:inline">Volver</span>
       </a>
-      <div class="h-4 w-px shrink-0 bg-gray-200 dark:bg-white/10"></div>
+      <div class="hidden sm:block h-4 w-px shrink-0 bg-gray-200 dark:bg-white/10"></div>
       <!-- Screen title -->
-      <span id="screen-title" class="shrink-0 text-[13px] font-semibold leading-none">--</span>
+      <span id="screen-title" class="min-w-0 truncate text-[13px] font-semibold leading-none">--</span>
       <!-- Screen description (inline after title) -->
       <span id="screen-desc" class="hidden text-[11px] text-gray-400 dark:text-gray-500 truncate sm:inline"></span>
@@ -115,20 +127,20 @@
       <div class="flex-1"></div>
       <!-- Position counter -->
-      <span id="nav-pos" class="shrink-0 tabular-nums text-[11px] text-gray-400 dark:text-gray-500">-- / --</span>
+      <span id="nav-pos" class="hidden sm:inline shrink-0 tabular-nums text-[11px] text-gray-400 dark:text-gray-500">-- / --</span>
       <!-- Prev button -->
-      <button id="btn-prev" title="Previous screen (ArrowLeft)" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-30" disabled>
+      <button id="btn-prev" title="Pantalla anterior (←)" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-30" disabled>
         <svg class="h-3.5 w-3.5" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M10 13L5 8l5-5"/></svg>
       </button>
       <!-- Next button -->
-      <button id="btn-next" title="Next screen (ArrowRight)" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-30" disabled>
+      <button id="btn-next" title="Pantalla siguiente (→)" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-30" disabled>
         <svg class="h-3.5 w-3.5" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M6 3l5 5-5 5"/></svg>
       </button>
       <!-- Theme toggle -->
-      <button id="theme-toggle" title="Toggle light/dark" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
+      <button id="theme-toggle" title="Cambiar claro/oscuro" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
         <svg class="block h-3.5 w-3.5 dark:hidden" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
           <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
         </svg>
@@ -146,7 +158,7 @@
       </button>
       <!-- View mode toggle -->
-      <button id="view-mode-toggle" title="Toggle mobile/web view" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
+      <button id="view-mode-toggle" title="Cambiar vista móvil/web" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
         <svg id="icon-phone" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
           <rect x="5" y="2" width="14" height="20" rx="2" ry="2"/><line x1="12" y1="18" x2="12.01" y2="18"/>
         </svg>
@@ -156,7 +168,7 @@
       </button>
       <!-- Fullscreen button -->
-      <button id="btn-fullscreen" title="Fullscreen (F)" class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
+      <button id="btn-fullscreen" title="Pantalla completa (F)" class="hidden sm:flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-gray-500 transition-colors hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-white/10">
         <svg id="icon-expand" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3"/>
         </svg>

package/skills/stitch-showcase/scripts/__pycache__/build_showcase.cpython-314.pyc CHANGED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/component_utils.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/detect_components.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/extract_catalog.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/extract_text.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/extract_zips.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/parse_design_md.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/__pycache__/slug_demangle.cpython-314.pyc ADDED Viewed

Binary file

package/skills/stitch-showcase/scripts/build_showcase.py CHANGED Viewed

@@ -40,6 +40,7 @@ import parse_design_md
 import extract_text
 import detect_components
 import extract_catalog
+from slug_demangle import slug_to_title
 def _extract_source_zip(zip_path: Path) -> Path:
@@ -150,6 +151,9 @@ def build(source_dir: str, project_type: str = None, project_name: str = None) -
     # Generate catalog.html (always included)
     _generate_catalog(output_dir, assets_dir, metadata)
+    # Sanity-check the generated output — warnings only, never aborts.
+    _validate_showcase(output_dir, screens)
     print(f"\n🎉 Showcase ready: {output_dir}/index.html\n")
     return output_dir
@@ -344,6 +348,11 @@ def _prepare_source(source_dir: str, project_type: str, project_name: str) -> tu
         # Defer type detection — will resolve after screen extraction via _detect_type_from_screens()
         metadata["_type_pending"] = True
+    # Language: showcase.json wins over DESIGN.md if both present, else fall through.
+    if config.get("lang"):
+        metadata["lang"] = str(config["lang"])
+    metadata.setdefault("lang", "en")
     ptype = metadata.get("type", "unknown")
     if ptype != "unknown":
         print(f"📱 Type: {ptype} | Project: {metadata['project_name']}")
@@ -518,16 +527,21 @@ def _enrich_screens(screens_raw: list, metadata: dict, source: Path) -> list:
     for raw in screens_raw:
         slug = raw["slug"]
         design = design_screens.get(slug, {})
+        html_path = raw.get("html_path", "")
-        # Title
-        title = design.get("title") or _slug_to_title(slug)
+        # Title resolution order: explicit DESIGN.md → <title> HTML → demangled slug
+        title = (
+            design.get("title")
+            or _read_html_title_tag(html_path)
+            or slug_to_title(slug)
+        )
         # Description priority: DESIGN.md → individual .md → meta/h1/title/visible body text → ""
         desc = design.get("description") or ""
         if not desc:
             desc = _read_md_desc(slug, source)
         if not desc:
-            desc = _read_html_title(raw.get("html_path", ""))
+            desc = _read_html_title(html_path)
         enriched.append({
             "slug": slug,
@@ -540,6 +554,50 @@ def _enrich_screens(screens_raw: list, metadata: dict, source: Path) -> list:
     return enriched
+def _read_html_title_tag(html_path: str) -> str:
+    """
+    Read the <title> tag of an HTML file and return a usable screen title.
+    Skips generic placeholders (Untitled, index, etc.). Strips a leading
+    "Brand - " or "Brand | " prefix when the title contains a separator,
+    so "Lumiere Dining - Rústico & Artesanal" becomes "Rústico & Artesanal".
+    Decodes basic HTML entities (&amp;, &nbsp;…).
+    """
+    if not html_path:
+        return ""
+    try:
+        text = Path(html_path).read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+    m = re.search(r"<title[^>]*>(.+?)</title>", text, re.IGNORECASE | re.DOTALL)
+    if not m:
+        return ""
+    val = re.sub(r"<[^>]+>", "", m.group(1)).strip()
+    for entity, char in [
+        ("&amp;", "&"), ("&lt;", "<"), ("&gt;", ">"),
+        ("&nbsp;", " "), ("&#39;", "'"), ("&quot;", '"'),
+    ]:
+        val = val.replace(entity, char)
+    val = re.sub(r"\s+", " ", val).strip()
+    if not val:
+        return ""
+    if re.match(r"^(untitled|index|screen|page|document|\d+)$", val, re.IGNORECASE):
+        return ""
+    # Strip a "Brand - " / "Brand | " / "Brand: " prefix and return the last segment.
+    for sep in (" - ", " — ", " | ", ": "):
+        if sep in val:
+            tail = val.split(sep)[-1].strip()
+            if tail:
+                val = tail
+                break
+    return val
 def _read_md_desc(slug: str, source: Path) -> str:
     """Look for an individual .md file with the screen description."""
     for md_file in source.glob("*.md"):
@@ -718,6 +776,23 @@ def _generate_viewer(output_dir: Path, ptype: str, metadata: dict, screens: list
     template = template_path.read_text(encoding="utf-8")
+    # Reorder screens to follow DESIGN.md section order (mirrors _build_sections_html)
+    # so prev/next navigation matches the visual order in index.html.
+    sections = metadata.get("sections", [])
+    if sections:
+        slug_to_screen = {s["slug"]: s for s in screens}
+        ordered = []
+        seen = set()
+        for section in sections:
+            for slug in section.get("slugs", []):
+                if slug in slug_to_screen and slug not in seen:
+                    ordered.append(slug_to_screen[slug])
+                    seen.add(slug)
+        for s in screens:
+            if s["slug"] not in seen:
+                ordered.append(s)
+        screens = ordered
     # Build screens JSON for prev/next navigation
     screens_data = [
         {"title": s["title"], "desc": s["description"], "html_file": s["html_file"]}
@@ -738,6 +813,7 @@ def _generate_viewer(output_dir: Path, ptype: str, metadata: dict, screens: list
     font_family = font or "system-ui"
     html = template
+    html = html.replace("{{HTML_LANG}}", metadata.get("lang", "en"))
     html = html.replace("{{PROJECT_NAME}}", escape(metadata["project_name"]))
     html = html.replace("{{SCREENS_JSON}}", json.dumps(screens_data, ensure_ascii=False))
     html = html.replace("{{DEFAULT_THEME}}", metadata.get("default_theme", "light"))
@@ -796,12 +872,13 @@ def _generate_index(output_dir: Path, ptype: str, metadata: dict, screens: list)
     )
     # New template variables
-    type_labels = {"mobile": "Mobile App", "web": "Web App"}
+    type_labels = {"mobile": "App Móvil", "web": "App Web"}
     type_label = type_labels.get(metadata.get("type", ""), "Showcase")
     project_desc = _project_description_html(metadata, filtered_screens)
     screens_intro = _screens_intro_text(metadata)
     html = template
+    html = html.replace("{{HTML_LANG}}", metadata.get("lang", "en"))
     html = html.replace("{{PROJECT_NAME}}", escape(metadata["project_name"]))
     html = html.replace("{{SCREEN_COUNT}}", str(len(filtered_screens)))
     html = html.replace("{{SCREENS_HTML}}", sections_html)
@@ -925,7 +1002,7 @@ def _design_system_html(ds_screen: dict | None, metadata: dict) -> str:
             f'style="font-family:\'{escape(font)}\',sans-serif">Aa</span>'
             f'<div>'
             f'<span class="text-sm font-medium text-gray-700 dark:text-gray-200">{escape(font)}</span>'
-            f'<span class="text-xs text-gray-400 dark:text-gray-500 ml-2">Primary typeface</span>'
+            f'<span class="text-xs text-gray-400 dark:text-gray-500 ml-2">Tipografía principal</span>'
             f'</div>'
             f'</div>'
         )
@@ -1292,10 +1369,73 @@ def _card_html(screen: dict, ptype: str) -> str:
         </a>"""
-def _slug_to_title(slug: str) -> str:
-    """01_splash_screen → 'Splash Screen' (strips numeric prefix)."""
-    s = re.sub(r"^[\d_]+", "", slug)
-    return s.replace("_", " ").replace("-", " ").title().strip() or slug.title()
+# ─── Post-build validation ───────────────────────────────────────────────────
+def _validate_showcase(output_dir: Path, screens: list) -> None:
+    """
+    Sanity-check the generated showcase. Prints warnings only — never aborts.
+    Checks:
+      1. JSON embedded in viewer.html (`var SCREENS = [...]`) parses.
+      2. Each screen has both `assets/<slug>.html` and `assets/<slug>.png`.
+      3. Local `src=` references (img / video / source) inside each screen
+         resolve on disk (URLs starting with http/https/data: are skipped).
+    """
+    assets_dir = output_dir / "assets"
+    issues: list[str] = []
+    # 1) Embedded SCREENS JSON in viewer.html
+    viewer_path = output_dir / "viewer.html"
+    if viewer_path.exists():
+        viewer_text = viewer_path.read_text(encoding="utf-8")
+        m = re.search(r"var\s+SCREENS\s*=\s*(\[.*?\]);", viewer_text, re.DOTALL)
+        if not m:
+            issues.append("viewer.html: no encontré `var SCREENS = [...]`")
+        else:
+            try:
+                json.loads(m.group(1))
+            except json.JSONDecodeError as e:
+                issues.append(f"viewer.html: SCREENS JSON inválido — {e}")
+    # 2) Per-screen assets
+    for s in screens:
+        slug = s["slug"]
+        if not (assets_dir / f"{slug}.html").exists():
+            issues.append(f"{slug}: falta assets/{slug}.html")
+        if not (assets_dir / f"{slug}.png").exists():
+            issues.append(f"{slug}: falta assets/{slug}.png")
+    # 3) Local img / video / source references inside each screen HTML
+    src_re = re.compile(
+        r"""<(?:img|video|source)\s[^>]*src=["']([^"']+)["']""",
+        re.IGNORECASE,
+    )
+    for s in screens:
+        slug = s["slug"]
+        html_path = assets_dir / f"{slug}.html"
+        if not html_path.exists():
+            continue
+        try:
+            text = html_path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for src in src_re.findall(text):
+            if src.startswith(("http://", "https://", "data:", "//")):
+                continue
+            ref = (html_path.parent / src).resolve()
+            if not ref.exists():
+                issues.append(f"{slug}: src inexistente '{src}'")
+    # 4) Report
+    print()
+    if not issues:
+        print(f"✅ {len(screens)}/{len(screens)} screens válidos")
+    else:
+        print(f"⚠ {len(issues)} problema(s) detectado(s):")
+        for issue in issues[:20]:
+            print(f"   - {issue}")
+        if len(issues) > 20:
+            print(f"   ...({len(issues) - 20} más)")
 def _project_slug(name: str) -> str:
@@ -1422,7 +1562,7 @@ def _init(source_dir: str, project_type: str, project_name: str) -> None:
         sys.exit(1)
     # Auto-group slugs for skeleton
-    fake_screens = [{"slug": s, "title": _slug_to_title(s), "description": ""} for s in slugs]
+    fake_screens = [{"slug": s, "title": slug_to_title(s), "description": ""} for s in slugs]
     groups = _auto_group_screens(fake_screens)
     pname = project_name or source.name.replace("_", " ").replace("-", " ").title()

package/skills/stitch-showcase/scripts/parse_design_md.py CHANGED Viewed

@@ -3,13 +3,26 @@ parse_design_md.py — Extracts metadata from DESIGN.md for stitch-showcase.
 Usage:
     python parse_design_md.py /path/to/DESIGN.md
-    → prints JSON with project_name, type, colors, color_tokens, default_theme, font_family, screens, sections
+    → prints JSON with project_name, type, lang, colors, color_tokens, default_theme, font_family, screens, sections
 """
 import re
 import sys
 import json
 from pathlib import Path
+# Ensure sibling modules resolve when this file is invoked directly.
+sys.path.insert(0, str(Path(__file__).parent))
+from slug_demangle import slug_to_title
+SPANISH_STOPWORDS = {
+    "de", "el", "la", "los", "las", "para", "con", "por", "una", "uno",
+    "del", "que", "es", "se", "su", "sus", "como", "más", "muy", "este",
+    "esta", "estos", "estas", "pantalla", "pantallas", "aplicación",
+    "aplicacion", "usuario", "usuarios", "diseño", "diseno", "móvil",
+    "movil", "perfil", "configuración", "configuracion",
+}
 def parse(design_md_path: str) -> dict:
     path = Path(design_md_path)
@@ -17,6 +30,7 @@ def parse(design_md_path: str) -> dict:
         return {
             "project_name": "",
             "type": "unknown",
+            "lang": "en",
             "colors": {},
             "color_tokens": {},
             "default_theme": "light",
@@ -26,9 +40,17 @@ def parse(design_md_path: str) -> dict:
         }
     text = path.read_text(encoding="utf-8")
+    frontmatter = _parse_yaml_frontmatter(text)
+    lang = _extract_lang_override(text) or _detect_lang(text)
     colors = _extract_colors(text)
     color_tokens = _extract_color_tokens(text)
+    # Frontmatter fills in fields the Markdown body doesn't define.
+    if not colors and frontmatter.get("colors"):
+        colors = dict(frontmatter["colors"])
+    if not color_tokens and frontmatter.get("colors"):
+        color_tokens = _semantic_tokens_from_dict(frontmatter["colors"])
     # Determine default_theme from surface token
     surface_hex = color_tokens.get("surface") or color_tokens.get("background")
     if not surface_hex:
@@ -58,7 +80,7 @@ def parse(design_md_path: str) -> dict:
         # Apply titles/descriptions to screens already in the list
         for s in screens:
             slug = s["slug"]
-            if not s.get("title") or s["title"] == _slug_to_title(slug):
+            if not s.get("title") or s["title"] == slug_to_title(slug):
                 if slug in section_titles:
                     s["title"] = section_titles[slug]
             if not s.get("description") and slug in section_descs:
@@ -69,29 +91,145 @@ def parse(design_md_path: str) -> dict:
                 if slug not in existing_slugs:
                     screens.append({
                         "slug": slug,
-                        "title": section_titles.get(slug) or _slug_to_title(slug),
+                        "title": section_titles.get(slug) or slug_to_title(slug),
                         "description": section_descs.get(slug, ""),
                     })
                     existing_slugs.add(slug)
+    project_name = _extract_project_name(text) or frontmatter.get("name", "")
+    font_family = _extract_typography(text) or frontmatter.get("font_family")
     return {
-        "project_name": _extract_project_name(text),
+        "project_name": project_name,
         "type": _detect_type(text),
+        "lang": lang,
         "colors": colors,
         "color_tokens": color_tokens,
         "default_theme": default_theme,
-        "font_family": _extract_typography(text),
+        "font_family": font_family,
         "screens": screens,
         "sections": sections,
     }
+def _parse_yaml_frontmatter(text: str) -> dict:
+    """
+    Parse a Stitch-style YAML frontmatter at the top of DESIGN.md.
+    Recognizes (everything else is ignored):
+      - top-level ``name:`` → ``"name"``
+      - ``colors:`` block with hex values → ``"colors"`` dict
+      - ``typography:`` block — returns the first ``fontFamily`` → ``"font_family"``
+    Returns an empty dict if no frontmatter delimiter is present.
+    """
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
+    if not m:
+        return {}
+    fm = m.group(1)
+    result: dict = {}
+    # name: <value>
+    name_m = re.search(r"^name:\s*(.+?)\s*$", fm, re.MULTILINE)
+    if name_m:
+        val = name_m.group(1).strip().strip("'\"")
+        if val:
+            result["name"] = val
+    # colors: block — collect indented "key: '#hex'" pairs until indentation drops.
+    colors_m = re.search(r"^colors:\s*\n((?:[ \t]+\S.*\n?)+)", fm, re.MULTILINE)
+    if colors_m:
+        colors: dict = {}
+        for line in colors_m.group(1).splitlines():
+            cm = re.match(
+                r"^\s+([a-z][a-z0-9\-]*):\s*['\"]?(#[0-9A-Fa-f]{3,8})['\"]?\s*$",
+                line,
+            )
+            if cm:
+                colors[cm.group(1).lower()] = "#" + cm.group(2).lstrip("#").upper()
+        if colors:
+            result["colors"] = colors
+    # typography: pick the first fontFamily declared anywhere in the block.
+    typo_m = re.search(r"fontFamily:\s*['\"]?([^'\"\n,]+)['\"]?", fm)
+    if typo_m:
+        font = typo_m.group(1).strip().rstrip(",;")
+        if font:
+            result["font_family"] = font
+    return result
+def _semantic_tokens_from_dict(colors: dict) -> dict:
+    """
+    Compute `accent` / `surface` semantic tokens from a flat color dict.
+    Mirrors the rules used by :func:`_extract_color_tokens`:
+      - ``accent``  → first key containing ``primary`` (not ``on-primary``)
+      - ``surface`` → first key named ``surface`` or containing ``background``/``bg``
+    """
+    tokens = dict(colors)
+    for name, val in colors.items():
+        if "primary" in name and not name.startswith("on-"):
+            tokens["accent"] = val
+            break
+    for name, val in colors.items():
+        if name == "surface" or "background" in name or name == "bg":
+            tokens["surface"] = val
+            break
+    return tokens
 def _extract_project_name(text: str) -> str:
     """First H1 heading in the document."""
     m = re.search(r"^#\s+(.+)$", text, re.MULTILINE)
     return m.group(1).strip() if m else ""
+def _extract_lang_override(text: str) -> str | None:
+    """
+    Explicit override via ``## Lang`` (or ``## Language``) section in DESIGN.md.
+    Expected format:
+        ## Lang
+        es
+    Returns a BCP-47-ish code (``es``, ``en``, ``pt-BR``…) or None if absent.
+    """
+    m = re.search(
+        r"^##\s+Lang(?:uage)?\s*\n\s*([A-Za-z]{2}(?:-[A-Za-z]{2,4})?)\s*$",
+        text, re.IGNORECASE | re.MULTILINE
+    )
+    if not m:
+        return None
+    raw = m.group(1)
+    # Normalize: language subtag lowercase, region subtag uppercase (BCP-47).
+    if "-" in raw:
+        lang, region = raw.split("-", 1)
+        return f"{lang.lower()}-{region.upper()}"
+    return raw.lower()
+def _detect_lang(text: str) -> str:
+    """
+    Heuristic language detection. Distinguishes Spanish from everything else.
+    Signals:
+      - Spanish-only accented characters (á é í ó ú ñ ü).
+      - Common Spanish stop words from SPANISH_STOPWORDS.
+    Returns 'es' when either signal is present, else 'en'.
+    """
+    if not text:
+        return "en"
+    lower = text.lower()
+    if re.search(r"[áéíóúñü]", lower):
+        return "es"
+    words = re.findall(r"[a-záéíóúñü]+", lower)
+    stop_hits = sum(1 for w in words if w in SPANISH_STOPWORDS)
+    return "es" if stop_hits >= 3 else "en"
 def _detect_type(text: str) -> str:
     """Returns 'mobile', 'web', or 'unknown'.
@@ -292,7 +430,7 @@ def _parse_table(text: str) -> list:
         cols = [c.strip() for c in line.split("|") if c.strip()]
         if len(cols) >= 2:
             slug = _to_slug(cols[0])
-            title = cols[1] if len(cols) > 1 else _slug_to_title(slug)
+            title = cols[1] if len(cols) > 1 else slug_to_title(slug)
             desc = cols[2] if len(cols) > 2 else ""
             rows.append({"slug": slug, "title": title, "description": desc})
@@ -324,7 +462,7 @@ def _parse_screen_list(text: str) -> list:
                 title = title_part.strip()
                 desc = desc_part.strip()
             else:
-                title = _slug_to_title(slug)
+                title = slug_to_title(slug)
                 desc = raw
             screens.append({"slug": slug, "title": title, "description": desc})
@@ -384,11 +522,6 @@ def _to_slug(s: str) -> str:
     return s
-def _slug_to_title(slug: str) -> str:
-    """splash_screen → 'Splash Screen'"""
-    return slug.replace("_", " ").replace("-", " ").title()
 if __name__ == "__main__":
     if len(sys.argv) < 2:
         print("Usage: python parse_design_md.py /path/to/DESIGN.md", file=sys.stderr)