@maccesar/aiskills 1.12.0 → 1.16.0

package/skills/stitch-showcase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stitch-showcase
-description: Use this skill whenever the user has Google Stitch design exports and wants to do anything with them — build a gallery, organize screens, generate a navigable showcase, process zip files, or browse designs. Triggers on "organiza mis diseños de Stitch", "arma el muestrario", "organize my Stitch designs", "build the showcase", "I have the Stitch zips in X", "process this design folder", "generate the index for my Stitch screens", "tengo los zips de Stitch", "quiero ver mis pantallas", or any mention of Stitch exports, screen.png + code.html pairs, or design zip files. Even if the user just says "I have a zip from Stitch" or "mis exports de Stitch" — use this skill. Also triggers on "optimiza el showcase", "mejora las descripciones", "enrich the showcase", "optimize titles", "optimiza", or any request to improve an existing showcase's content.
+description: 'Use when the user has Google Stitch design exports and wants to do anything with them — build a gallery, organize screens, generate a navigable showcase, process zip files, or browse designs. Triggers: "organiza mis diseños de Stitch", "arma el muestrario", "organize my Stitch designs", "build the showcase", "tengo los zips de Stitch", "mis exports de Stitch", or any mention of Stitch exports, screen.png + code.html pairs, or design zip files. Also: "optimiza el showcase", "mejora las descripciones", "enrich the showcase" to improve an existing showcase.'
 ---
 
 # stitch-showcase
@@ -48,6 +48,7 @@ digraph showcase {
 This is the default mode. No AI analysis needed — the script handles everything with smart defaults.
 
 Steps:
+
 1. Identify the source path from the user's message
 2. Run the build script — **nothing else**:
    ```bash
@@ -62,12 +63,7 @@ Steps:
 
 **That's it.** No pre-flight questions, no DESIGN.md enrichment, no `--extract-text`, no `--init`.
 
-Only ask `--type` or `--name` if the **script fails** or the **user explicitly wants to override**:
-```bash
-# Only if script fails to detect type or user requests it
-python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --type mobile
-python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --name "My App" --type mobile
-```
+Only ask `--type` or `--name` if the **script fails** or the **user explicitly wants to override**. Full flag reference in [`references/15-build-flags.md`](references/15-build-flags.md).
 
 ## Mode 2: Enrich (on-demand — user asks)
 
@@ -76,6 +72,7 @@ python <SKILL_DIR>/scripts/build_showcase.py /path/to/source --name "My App" --t
 This mode improves the AI-generated content in DESIGN.md and rebuilds the showcase with enriched data.
 
 Steps:
+
 1. Find the source folder (from the user's message or the project's `showcase.json`)
 2. Run `--extract-text` to get screen summaries:
    ```bash
@@ -84,9 +81,8 @@ Steps:
    This generates `screen_summaries.txt` — a compact text file with visible text from all screen HTMLs.
 3. Read the existing `DESIGN.md` (in the source folder) + `screen_summaries.txt`
 4. **Keep existing sections as-is** — do NOT re-group screens. Only improve content within each section:
-   - **De-mangle titles**: `configuraci_n` → "Configuración", `membres_as_y_pagos` → "Membresías y Pagos"
    - **Write real descriptions**: From the extracted text, write a 1-sentence Spanish description for each screen explaining what it does for the user (NOT just a UI label). Example: "Panel principal del miembro con estado de membresía, próximas clases y accesos rápidos."
-   - **Fix the `Title | Description` format** for mangled slugs (see format below)
+   - **Titles are handled by the script** — `scripts/slug_demangle.py` already converts mangled slugs like `configuraci_n_oscuro` → `"Configuración Oscuro"` and `membres_as` → `"Membresías"`. Use the `Title | Description` override only when the demangler can't infer the right title (rare word) or you want a title different from what the slug would yield.
 5. **Update the project description** at the top of DESIGN.md — this feeds the hero section. It should describe the full scope of the project based on the screens' content.
 6. **Verify colors/fonts**: Scan the screen HTMLs for hex colors in CSS variables and font families. Update `## Colors` and `## Typography` sections if they're missing or incomplete.
 7. Re-run the build to regenerate HTMLs with enriched data:
@@ -95,24 +91,23 @@ Steps:
    ```
 8. Done — tell the user the showcase has been updated with improved descriptions
 
-**Mangled slugs (Stitch replaces accented characters with `_`):**
+**Title override format (`Title | Description`):**
 
-Google Stitch strips accent characters from filenames, replacing each with `_`. When you see slugs like `confirmaci_n_de_reserva` or `men_m_s`, reconstruct the correct display title and write it explicitly using the `Title | Description` format:
+When the demangler doesn't cover a slug (uncommon word or composite), provide both pieces explicitly. The parser splits on ` | ` — everything before is the display title, everything after is the description:
 
 ```markdown
 ### Cuenta
-- configuraci_n_oscuro: Configuración | Ajustes de cuenta, notificaciones y preferencias del usuario.
-- notificaci_n_oscuro: Notificación | Centro de alertas y mensajes recibidos.
-- esc_ner_oscuro: Escáner | Lector de código QR para acceso o verificación.
+- weird_man_leado_slug: Título Correcto | Descripción de la pantalla.
 ```
 
-The parser splits on ` | ` — everything before is the display title, everything after is the description. For slugs without mangled characters, the plain `- slug: description` format is fine (title is inferred from the slug automatically).
+For slugs that the demangler already handles correctly, the plain `- slug: description` form is enough. Full DESIGN.md format in [`references/16-design-md-format.md`](references/16-design-md-format.md).
 
 ## Mode 3: Update (add new screens to an existing showcase)
 
 **Triggers**: "add these new screens", "el cliente pidió una pantalla más", "coloca este zip en el proyecto", "agrégalos al muestrario", or any similar update request.
 
 Steps:
+
 1. Copy the new zip(s) into the same source folder as the existing screens
 2. Run `build_showcase.py /path/to/source --update`
    - Extracts new zips (existing screens skipped via mtime)
@@ -133,29 +128,12 @@ Steps:
 
 **Triggers**: "standardize the navbars", "make all footers the same", "usa el navbar del home", "estandariza los botones", or similar.
 
-Steps:
-1. Open `catalog.html` in the browser — review the comparison view
-2. User decides which variant to use as canonical
-3. Run `apply_canonical.py` to apply the chosen canonical:
-
-```bash
-# Structural components (navbar, footer, sidebar, tabbar)
-python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen
-
-# Atomic components (button, input, heading, etc.)
-python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ button home_screen
-
-# Target specific screens only
-python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen --targets login settings profile
-```
-
-4. Rebuild the showcase: `build_showcase.py /path/to/source`
-5. Verify the catalog shows fewer variants / more items in "Already Unified"
-6. Repeat until all components are standardized
+Open `catalog.html` to compare variants, decide a canonical, then run `apply_canonical.py` and rebuild. **Full workflow in [`references/10-component-standardization.md`](references/10-component-standardization.md).**
 
 ## Verification
 
 Confirm with the user:
+
 - Open `index.html` — thumbnails visible and correct
 - Design system section shows color relationships and type specimen (not just swatches)
 - Click a screen → viewer opens with correct default frame (phone for mobile, browser chrome for web)
@@ -168,202 +146,7 @@ Confirm with the user:
 
 ## Component Catalog & Comparison (automatic)
 
-The catalog is generated automatically as part of every build. Open `catalog.html` to:
-
-- **Browse all components** organized by type: Structural (navbars, footers, sidebars), Atomic (buttons, headings, inputs, badges, links, icons), Composite (cards, CTAs, heroes, testimonials)
-- **Compare variants** side-by-side with styled previews (original Tailwind CSS), canonical badges, similarity scores, and screen counts
-- **See what's unified** — components with only one variant appear in a collapsed "Already Unified" section
-- **Copy component HTML** for use in other projects
-
-## Build Script Reference
-
-### Running the build
-
-```bash
-# Point to the project root — the script discovers the source automatically
-python <SKILL_DIR>/scripts/build_showcase.py /path/to/project
-
-# Or point directly to the folder with zips/screens
-python <SKILL_DIR>/scripts/build_showcase.py /path/to/project/stitch
-
-# Single mega-zip (zip containing all screens as subfolders)
-python <SKILL_DIR>/scripts/build_showcase.py /path/to/export.zip
-```
-
-### Flags
-
-| Flag | Description |
-|------|-------------|
-| `--type mobile\|web` | Set default view mode instead of auto-detecting |
-| `--name "Title"` | Set project name when no DESIGN.md is present |
-| `--init` | Generate a DESIGN.md skeleton from detected screen slugs |
-| `--update` | Detect new screens not yet in DESIGN.md and append under `### Por Clasificar` |
-| `--extract-text` | Extract visible text from screen HTMLs → `screen_summaries.txt` (for LLM consumption) |
-| `--context` | (Debug only) Generate showcase_context.json without building HTML — do NOT use for normal builds |
-| `--watch` | Auto-rebuild on file changes (Ctrl+C to stop) |
-
-**Note**: Component detection and catalog generation are now automatic — no `--catalog` or `--components` flags needed. Every build produces `catalog.html` alongside `index.html` and `viewer.html`.
-
-### Output structure
-
-The script creates a single `showcase/` directory next to the source folder:
-```
-showcase/                         ← single output dir (view mode toggle inside)
-├── index.html                    ← open this in browser (gallery + design system)
-├── viewer.html                   ← individual screen viewer
-├── catalog.html                  ← component catalog with comparison view
-├── component_catalog.json        ← atomic + composite + cluster data
-├── shared_components.json        ← structural component variants
-├── DESIGN.md                     ← copy from source
-└── assets/
-    ├── splash_screen.html
-    ├── splash_screen.png
-    ├── login.html
-    ├── login.png
-    └── ...
-```
-
-Source folder with original zips is **never touched**.
-
-### Source discovery
-
-The script accepts **any folder in the project** — it doesn't need to be the exact folder with screens. Discovery order:
-1. If the given path has screens (zips or `code.html` folders) → use it directly
-2. If `showcase.json` exists in the given path or its parent → follow its `source` field
-3. Auto-discover: scan one level of subdirectories for screens (skips `showcase`, `showcase-mobile`, `showcase-web` output dirs)
-4. Clear error with a suggestion to create `showcase.json`
-
-### Supported input structures
-
-| Structure | Example |
-|-----------|---------|
-| Project root with `showcase.json` | `project/showcase.json` → `{"source": "stitch"}` |
-| Folder of individual zips | `folder/login.zip`, `folder/home.zip` |
-| Folder of pre-extracted screen folders | `folder/login/code.html`, `folder/home/code.html` |
-| Single mega-zip (Stitch "Export all") | `export.zip → stitch/screen1/code.html, stitch/screen2/code.html` |
-| Single screen zip | `screen.zip → code.html + screen.png` |
-
-## Screen Grouping
-
-Screens are grouped into sections in this priority order:
-
-1. **`DESIGN.md` sections** (best result) — explicit `### Section Name` blocks under `## Screens`
-2. **Auto-grouping** (fallback) — keyword overlap between slugs; screens sharing a meaningful word are grouped together
-
-When auto-grouping applies, offer to improve it:
-- List the detected screen names for the user
-- Suggest logical section groupings based on the app domain
-- Write the sections to `DESIGN.md` in the source folder
-- Re-run the script to apply them
-
-**DESIGN.md section format for explicit grouping:**
-```markdown
-## Screens
-### Onboarding
-- splash_screen
-- welcome
-
-### Login & Registration
-- login
-- signup
-- forgot_password
-
-### Home
-- home
-- home_oscuro
-```
-
-The script merges DESIGN.md sections with slug auto-detection — slugs not listed in any section appear in an "Other screens" group at the end.
-
-## Description Sources (priority)
-
-1. `DESIGN.md` — screen list with descriptions
-2. Individual `{num}-{name}.md` in source folder (per-screen prompt files)
-3. `<meta name="description">` or `<meta property="og:description">` inside the HTML
-4. First `<h1>` or `<h2>` visible text in the HTML body
-5. `<title>` tag (skipped if generic: "Untitled", "index", "screen", etc.)
-6. First meaningful visible text phrase found in the HTML body (strips scripts/styles/SVGs)
-7. Formatted slug fallback ("splash_screen" → "Splash Screen")
-
-Stitch-exported HTML rarely has `<title>` or meta descriptions — steps 4 and 6 are the most useful for those files.
-
-## showcase.json
-
-Optional config file in the project root. Tells the script where to find screens, the project type, and name — so you can point the script at any folder in the project.
-
-```json
-{
-  "source": "stitch",
-  "type": "mobile",
-  "name": "SNAP Gym"
-}
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `source` | yes | Relative path from the JSON file to the folder with screens |
-| `type` | no | `"mobile"` or `"web"` (overridden by `--type` CLI flag) |
-| `name` | no | Project name (overridden by `--name` CLI flag or DESIGN.md) |
-
-The `--init` flag generates this file automatically alongside DESIGN.md.
-
-## DESIGN.md Format
-
-```markdown
-# Project Name
-
-## Type
-mobile  ← or "web"
-
-## Screens
-### Onboarding
-- splash_screen
-- login
-
-### Home
-- home_dashboard
-
-## Colors
-- Primary: #FDD900
-- Background: #0A0A0A
-
-## Typography
-- **Inter**
-```
-
-The parser also accepts:
-- Free-form bullets/numbered lists under `## Screens`
-- Markdown table format: `| slug | title | description |`
-- Color tokens in Stitch format: `` `primary-container` (#FDD900) `` or bare `surface (#0B1326)`
-  - Token named `primary-*` → accent color for tabs and hover
-  - Token named `surface` or `background` → used to compute smart showcase theme
-
-The `--init` flag auto-generates a skeleton DESIGN.md from detected slugs.
-
-## Color Strategy
-
-**Do NOT use brand colors for showcase backgrounds** — if the app's background matches the showcase background, thumbnails disappear.
-
-| Element | Value |
-|---------|-------|
-| Page background | Smart: dark (`#0d0d0d`) if app surface is light, light (`#f5f5f5`) if app surface is dark |
-| Card background | `#1a1a1a` (dark mode) / `#ffffff` (light mode) |
-| Accent (tabs, hover, borders) | From context `color_tokens.accent` or `colors.primary` → fallback `#6366f1` |
-| Large surfaces | Always neutral — never brand color |
-
-The smart default theme is computed from the `surface` color token luminance: dark surface (luminance < 100) → showcase opens in light mode for contrast, and vice versa. The user's preference is saved in `localStorage` and overrides the default on subsequent visits.
-
-## Mobile vs Web Detection
-
-### Project-level (from DESIGN.md):
-- Keywords: "mobile", "iOS", "Android", "app"
-- If ambiguous → pass `--type` flag
-
-### Per-screen (from HTML analysis):
-- Viewport meta `user-scalable=no`, `maximum-scale=1` → mobile
-- Fixed widths 375-430px → mobile
-- Desktop breakpoints, sidebars → web
-- Stored as `detected_type` per screen in context JSON
+The catalog is generated automatically as part of every build. Open `catalog.html` to browse components by type (Structural, Atomic, Composite), compare variants side-by-side with similarity scores, see what's already unified, and copy component HTML. Design details in [`references/11-component-catalog.md`](references/11-component-catalog.md).
 
 ## Scripts
 
@@ -376,6 +159,8 @@ The smart default theme is computed from the `surface` color token luminance: da
 | `scripts/extract_catalog.py` | Extracts atomic + composite components for visual catalog |
 | `scripts/component_utils.py` | Shared HTML parsing helpers (stdlib html.parser) |
 | `scripts/parse_design_md.py` | Parses DESIGN.md → metadata dict |
+| `scripts/slug_demangle.py` | De-mangles Stitch slugs back to accented titles (`configuraci_n` → `Configuración`) |
+| `scripts/apply_canonical.py` | Applies a canonical component variant across selected screens |
 
 ## Reference Templates
 
@@ -385,13 +170,20 @@ The smart default theme is computed from the `surface` color token luminance: da
 | `references/viewer.html` | Unified viewer — phone frame + browser chrome toggled by view mode, prev/next, fullscreen |
 | `references/catalog-template.html` | Visual component catalog with tabs, previews, code snippets |
 
-## Reference Guides (design documentation)
+## Reference Guides
 
 | Guide | Purpose |
 |-------|---------|
 | `references/01-navbar.md` through `references/09-quality-standards.md` | Design decisions documentation for each section |
-| `references/10-component-standardization.md` | Component standardization design doc |
+| `references/07-theme-system.md` | Theme system, smart default, **showcase color strategy** (never use brand colors for surfaces) |
+| `references/08-type-detection.md` | Mobile vs web detection (project-level keywords + per-screen HTML signals) |
+| `references/10-component-standardization.md` | Component standardization design + **Mode 4 workflow** |
 | `references/11-component-catalog.md` | Component catalog design doc |
+| `references/12-video-embedding.md` | How to embed videos in slots (autoplay, aspect ratio, AV1 → H.264) |
+| `references/13-language-detection.md` | How `<html lang>` is resolved (auto-detect + overrides) |
+| `references/14-troubleshooting-known-issues.md` | Known issues and workarounds |
+| `references/15-build-flags.md` | **Build script reference**: flags, output structure, source discovery, supported input layouts |
+| `references/16-design-md-format.md` | **DESIGN.md & showcase.json formats**: project metadata, screen grouping, description sources priority |
 
 ## Common Errors
 

package/skills/stitch-showcase/references/07-theme-system.md

@@ -70,8 +70,20 @@ document.getElementById('theme-toggle').addEventListener('click', () => {
 - Tailwind config should extend colors with the project's accent: `colors: { accent: '{{PRIMARY_COLOR}}' }`
 - The theme initialization script MUST be in `<head>`, not at end of body, to prevent flash
 
+## Showcase Color Strategy
+
+**Do NOT use brand colors for showcase backgrounds** — if the app's background matches the showcase background, thumbnails disappear.
+
+| Element | Value |
+|---------|-------|
+| Page background | Smart default (see above): dark (`#0d0d0d`) if app surface is light; light (`#f5f5f5`) if app surface is dark |
+| Card background | `#1a1a1a` (dark mode) / `#ffffff` (light mode) |
+| Accent (tabs, hover, borders) | From context `color_tokens.accent` or `colors.primary` → fallback `#6366f1` |
+| Large surfaces | Always neutral — never brand color |
+
 ## Anti-Patterns
 
+- Do NOT use brand colors as large showcase surfaces — thumbnails disappear against matching backgrounds
 - Do NOT use `prefers-color-scheme` as the only source — the smart default from surface luminance is more important for showcase contrast
 - Do NOT animate the initial theme application (only transitions after user interaction)
 - Do NOT forget to sync theme between index and viewer pages

package/skills/stitch-showcase/references/08-type-detection.md

@@ -9,7 +9,15 @@ Intelligent per-screen type detection that ensures web designs open in the web v
 - `type` — project-level type ("mobile" or "web")
 - Each screen's `detected_type` — per-screen type ("mobile", "web", or "unknown")
 
-## How Detection Works (in build_showcase.py)
+## Project-Level Detection (from DESIGN.md)
+
+Before per-screen detection, the script reads `DESIGN.md` for hints about the whole project:
+
+- Keywords in the project description: `"mobile"`, `"iOS"`, `"Android"`, `"app"` → likely a mobile project
+- Explicit `## Type` section (`mobile` or `web`) wins over keywords
+- If ambiguous or absent → fall back to per-screen detection (next section) and use `--type` CLI flag to force
+
+## Per-Screen Detection (in build_showcase.py)
 
 Each screen's HTML is analyzed for these signals:
 

package/skills/stitch-showcase/references/10-component-standardization.md

@@ -38,3 +38,28 @@ Priority for choosing the canonical (best) version:
 - `total_screens`: total screens analyzed
 - `canonical`: the recommended version with slug and HTML snippet
 - `variants`: list of other versions with similarity scores and difference descriptions
+
+## Workflow (Mode 4: Standardize Components)
+
+**Triggers**: "standardize the navbars", "make all footers the same", "usa el navbar del home", "estandariza los botones", or similar.
+
+Steps:
+
+1. Open `catalog.html` in the browser — review the comparison view
+2. User decides which variant to use as canonical
+3. Run `apply_canonical.py` to apply the chosen canonical:
+
+```bash
+# Structural components (navbar, footer, sidebar, tabbar)
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen
+
+# Atomic components (button, input, heading, etc.)
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ button home_screen
+
+# Target specific screens only
+python <SKILL_DIR>/scripts/apply_canonical.py /path/to/showcase/assets/ navbar home_screen --targets login settings profile
+```
+
+4. Rebuild the showcase: `build_showcase.py /path/to/source`
+5. Verify the catalog shows fewer variants / more items in "Already Unified"
+6. Repeat until all components are standardized

package/skills/stitch-showcase/references/12-video-embedding.md

@@ -0,0 +1,113 @@
+# Section: Video Embedding in Slots
+
+## Purpose
+
+Sometimes a Stitch slot needs to show a video instead of a still image
+(product demo, animated logo, looping background, recorded screen). This
+document captures the exact pattern that works across browsers and avoids
+the common pitfalls — content recropping, layout shift, AV1 codec, and
+aspect-ratio mismatch with the original wrapper.
+
+## The Tag
+
+Use a plain `<video>` element with native `width` and `height` attributes
+plus inline styling for safe defaults:
+
+```html
+<video
+  autoplay
+  muted
+  loop
+  playsinline
+  width="W"
+  height="H"
+  preload="metadata"
+  style="display:block;width:100%;height:auto;background:#000">
+  <source src="../videos/<slug>.mp4" type="video/mp4">
+</video>
+```
+
+Replace `W` / `H` with the **native** video dimensions and `<slug>` with
+the screen slug (or whatever filename you used inside `videos/`).
+
+### Why each attribute
+
+| Attribute | Why |
+|-----------|-----|
+| `autoplay muted loop playsinline` | All four are required for in-app autoplay on iOS and Android. Drop any one and mobile browsers refuse to play without a tap. |
+| Native `width` / `height` | Lets the browser compute the aspect ratio from the very first paint — prevents layout shift and CLS regressions. |
+| `preload="metadata"` | Loads just enough to know the dimensions and duration; avoids hammering the user's bandwidth when the screen is offscreen. |
+| `style="display:block"` | Removes the small descender gap inline videos otherwise get. |
+| `style="width:100%;height:auto"` | Scales the video to fit the parent column while keeping its native aspect ratio. **Do NOT use `object-cover`** — it crops the video. |
+| `background:#000` | Hides letterboxing during the brief moment before the first frame paints. |
+
+## File Workflow
+
+1. **Download** the source video. For Facebook/Instagram/YouTube/TikTok we
+   recommend `yt-dlp`:
+
+   ```bash
+   yt-dlp "https://www.facebook.com/<...>/videos/<id>" -o "videos/<slug>.%(ext)s"
+   ```
+
+2. **Re-encode to H.264** if the source comes down as AV1. AV1 doesn't
+   preview in macOS Finder and is rejected by Safari < 17:
+
+   ```bash
+   ffmpeg -i in.mp4 \
+     -c:v libx264 -preset fast -crf 23 \
+     -c:a aac \
+     -movflags +faststart \
+     videos/<slug>.mp4
+   ```
+
+   - `-preset fast`: balanced speed/quality.
+   - `-crf 23`: visually-lossless default; lower number = bigger file.
+   - `-movflags +faststart`: moves the moov atom to the front so the video
+     can start playing before fully downloaded.
+
+3. **Place** the encoded `.mp4` in a `videos/` folder at the **project
+   level** (the same level as `stitch/` or `showcase/`, not inside
+   `assets/`), so the build keeps it out of the screen-extraction pipeline:
+
+   ```text
+   my-project/
+   ├── stitch/                 ← Stitch exports (zips)
+   ├── videos/                 ← your videos
+   │   └── hero.mp4
+   └── showcase/               ← generated
+       └── assets/
+           └── <slug>.html     ← references ../../videos/hero.mp4
+   ```
+
+4. **Reference from the screen HTML** with a relative path. From inside
+   `showcase/assets/<slug>.html`, `videos/` is two levels up:
+
+   ```html
+   <source src="../../videos/hero.mp4" type="video/mp4">
+   ```
+
+## Aspect-Ratio Mismatch
+
+The original Stitch wrapper for a video slot usually carries a fixed
+aspect ratio (e.g. `aspect-[4/5]`). If your video is a different shape —
+say 9/16 — keeping the wrapper's aspect locks the video into the wrong
+box, which then forces a choice:
+
+| Option | Effect |
+|--------|--------|
+| Keep wrapper's `aspect-*` + `object-cover` | Video crops; logos and edges get chopped. |
+| **Remove wrapper's `aspect-*` + `height:auto`** | Video keeps its native aspect; the slot grows or shrinks vertically to fit. ✅ |
+
+The second option is almost always what you want — better to have a
+slightly taller card than to chop the brand logo out of the frame.
+
+## Quick Sanity Checks
+
+After embedding, open the screen in a browser and confirm:
+
+- The video autoplays without a tap on Chrome, Safari, and Firefox.
+- The video loops cleanly (no flash on rewind).
+- On mobile (iOS Safari), it autoplays silently inline (not fullscreen).
+- The file size is reasonable — re-encode with a higher `-crf` if it's
+  more than ~3-5 MB per 10 seconds.

package/skills/stitch-showcase/references/13-language-detection.md

@@ -0,0 +1,82 @@
+# Section: Language Detection
+
+## Purpose
+
+The `<html lang="…">` attribute on the generated `index.html` and
+`viewer.html` tells the browser which natural language the content uses.
+If the value disagrees with the actual content, Chrome shows a "Translate
+this page" banner and assistive technologies pronounce words with the
+wrong phoneme set. This document explains how the build picks the value
+and how to override it.
+
+## Resolution Order
+
+The `lang` attribute is chosen by the first rule that fires:
+
+1. **CLI flag** (future — not implemented yet): `--lang es` on
+   `build_showcase.py`.
+2. **`showcase.json` field**:
+
+   ```json
+   {
+     "source": "stitch",
+     "type": "mobile",
+     "name": "My App",
+     "lang": "es"
+   }
+   ```
+
+3. **`## Lang` section in `DESIGN.md`** (same shape as `## Type`):
+
+   ```markdown
+   ## Lang
+   es
+   ```
+
+4. **Auto-detection** from the text content of `DESIGN.md` (project name,
+   section names, descriptions). The detector counts Spanish signals:
+
+   - Accented characters (`á é í ó ú ñ`).
+   - Common Spanish stop words (`de`, `el`, `la`, `los`, `las`, `para`,
+     `con`, `pantalla`, `aplicación`, `usuario`, etc.).
+
+   If the Spanish score crosses a small threshold, the lang resolves to
+   `"es"`; otherwise it falls through.
+
+5. **Default**: `"en"`.
+
+## When to Override
+
+The auto-detector handles obvious cases (a project whose DESIGN.md is
+entirely Spanish or entirely English), but it can be fooled by very
+short DESIGN.md files or by projects where the UI language differs from
+the documentation language. Use an explicit override when:
+
+- The DESIGN.md is in English but the actual screen content is Spanish
+  (you'd be documenting an es-MX app in English for a client).
+- The DESIGN.md is sparse and the heuristic has nothing to score on.
+- You want a non-Spanish, non-English language (`pt`, `fr`, `de` …) —
+  the auto-detector only distinguishes Spanish vs everything else.
+
+## Why It Matters
+
+- **Chrome's translate prompt**: with `lang="en"` and Spanish content,
+  Chrome offers to translate the page to the user's locale. Users
+  perceive this as a bug.
+- **Screen readers**: VoiceOver and TalkBack switch pronunciation
+  engines per `lang`. A wrong value makes Spanish text sound like a
+  speech synthesizer trying to pronounce "configuración" as English.
+- **Search engines**: the `lang` attribute is a soft signal but it's
+  read by indexers when ranking pages by locale.
+
+## Common Mistake: Mismatched Lang and Content
+
+The previous template hard-coded `lang="en"` even for Spanish-only
+projects. The fix wasn't to flip the default to `"es"` (that just moves
+the bug to English projects) — it was to detect or accept an override.
+The same logic now lives in `parse_design_md.py` (`_detect_lang`) and
+`build_showcase.py` (the `{{HTML_LANG}}` placeholder substitution).
+
+If you ever see Chrome offering to translate one of your showcases:
+that's the signal that the resolved `lang` is wrong. Add an override to
+`showcase.json` or `DESIGN.md` and rebuild.