@maccesar/aiskills 1.12.0 → 1.15.0

package/skills/refactoring-ui/references/07-component-patterns.md

@@ -0,0 +1,181 @@
+# Component Patterns: Modals, Forms, Tables
+
+> **Scope note**: *Refactoring UI* covers button tiers and label patterns directly (see `02-page-mechanics.md`), but does not have dedicated chapters for modals, forms, or tables. This file applies the book's principles — hierarchy through weight/color, generous spacing, grouping by proximity, finishing with restraint — to these three common components.
+
+---
+
+## Modals
+
+### When to Use a Modal
+
+- A focused decision that **blocks** the current task (confirm destructive action, complete a required step)
+- Short content that doesn't deserve a full page
+- Multi-step flows that should preserve the underlying context (the page behind the modal)
+
+When **not** to use a modal:
+
+- Anything the user might want to consult while doing the surrounding task — modals trap them
+- Long content that scrolls — make it a page
+- Anything that needs to be linkable — modals are stateless to the URL by default
+
+### Layout
+
+| Element | Rule |
+|---|---|
+| Width | Fixed pixel max (`max-width: 480px` typical) — never percentage |
+| Vertical position | Anchored ~10–15% from the top of viewport, not centered — feels more stable |
+| Backdrop | Semi-opaque dark overlay (~50–70% opacity) — darkens the page enough to focus attention |
+| Padding | Generous — modal content is usually short; tight padding feels cramped |
+| Close affordance | "Cancel" button in the footer AND an `×` in the top corner — keyboard users use Esc |
+
+### Focus and Keyboard
+
+Three keyboard requirements, all non-negotiable:
+
+1. **Focus moves into the modal on open** — typically to the first interactive element, or the close button if the modal is informational
+2. **Focus traps inside the modal** — Tab/Shift+Tab cycle through modal elements only, never leaking to the page behind
+3. **Esc closes the modal** AND focus returns to the element that opened it
+
+These are the table-stakes of accessibility for modals. Libraries like `focus-trap` or `@radix-ui/react-dialog` solve them — don't roll your own unless you must.
+
+### Button Order
+
+The primary action sits on the **right** in left-to-right UIs:
+
+```
+[ Cancel ]   [ Save changes ]
+```
+
+Destructive primary actions get an extra confirmation (a typed confirmation, or a secondary modal). Don't bury a destructive button next to a safe one.
+
+## Forms
+
+### Label Placement
+
+Top-aligned labels are the default for almost every form:
+
+- Fastest to scan top-to-bottom
+- Work on narrow screens without reflow
+- Easier to localize (labels grow in length across languages)
+
+Left-aligned labels look formal but force the user's eye to zig-zag and break on mobile. Reserve for dense data-entry screens where users repeatedly fill the same form.
+
+### Validation Timing
+
+- **On blur** for individual fields — show the error after the user leaves the field, not while they're typing
+- **On submit** for fields they haven't touched yet
+- **On change** ONLY for fields where the answer is binary and visible (e.g., a password strength meter, a username availability check)
+
+Inline validation while the user is mid-typing reads as the form fighting them.
+
+### Error Display
+
+A field in error state should have:
+
+- A color change (red border, but not the *only* signal)
+- A short message **below** the field, in the same color as the border
+- An icon at the start of the message — color is not enough (≈8% of males can't distinguish red from green)
+- The field's normal label and placeholder stay legible — don't replace them with the error
+
+### Spacing Within a Form
+
+Apply the Law of Proximity from `02-page-mechanics.md`:
+
+```
+[Label]
+[Input]
+ (small gap, ~8px)
+[Helper text]
+
+(large gap, ~24-32px to the next field group)
+
+[Label]
+[Input]
+```
+
+Label sits closer to its own input than to anything else. Each field group is clearly separated from the next.
+
+### Button Placement
+
+- **Single primary button** at the bottom left or center — never aligned right unless the form sits inside a modal (modals follow the modal rule)
+- **Secondary "Cancel"** to the left of the primary
+- Disable the submit button only when there are concrete errors — disabling it preemptively because the user "hasn't typed everything yet" leaves them guessing
+
+### Required vs Optional
+
+If most fields are required, mark only the **optional** ones — less noise overall. If most are optional, mark the required ones with `*`. Either system is fine — pick one and stay consistent.
+
+## Tables
+
+### Density Tiers
+
+Pick a row density based on the user's job:
+
+| Tier | Row height | Use |
+|---|---|---|
+| Comfortable | 56–64px | Marketing tables, dashboards seen occasionally |
+| Default | 40–48px | Most app tables |
+| Compact | 28–36px | Operator dashboards (CRM, admin, finance) where rows are scanned in bulk |
+
+Don't go below 28px unless the data is genuinely homogeneous — eye fatigue scales with row count, not just total height.
+
+### Alignment by Data Type
+
+| Data type | Alignment | Reason |
+|---|---|---|
+| Text (names, labels) | Left | Default reading direction |
+| Numbers (counts, money, percentages) | Right | Digits and decimals line up; magnitudes are scannable |
+| Dates | Left or right consistent | Pick one and stick — comparing dates is easier with consistent alignment |
+| Status / chips | Center inside their own column | Visually balanced when the chip is the only content |
+| Actions (icons, kebabs) | Right | Out of the way of the data |
+
+### Column Headers
+
+Mirror the column's content alignment. A right-aligned numeric column gets a right-aligned header.
+
+Sortable columns get an indicator (arrow up/down) AND show the active sort with stronger contrast — color alone isn't enough.
+
+### Sticky Headers
+
+For tables that scroll vertically inside their container, the header should stick. Two ways:
+
+1. `position: sticky; top: 0;` on the `<thead>` — easiest, works inside scrollable containers
+2. A second fixed header rendered above the scroll area — needed when the table itself scrolls in `<body>` (not its own container)
+
+Sticky headers must have a solid (opaque) background, otherwise rows scrolling behind them show through.
+
+### Row Hover and Selection
+
+- Subtle row hover background (one shade-step on neutrals) — helps the eye track across wide tables
+- Selection: a left-edge accent stripe **plus** a tinted background — selection should be obvious without screaming
+- Don't animate row hover — adds latency to bulk scanning
+
+### Empty Tables
+
+Apply the empty-state rule from `04-polish.md`: don't just show "No data" centered in a blank rectangle. The empty state communicates what could go there and offers a way to start.
+
+## Anti-Patterns
+
+### Modals
+
+- ❌ Centering vertically — feels unanchored
+- ❌ No close affordance — Esc users can escape, mouse users get stuck
+- ❌ Modals over modals (nested) — confusing back-stack
+- ❌ Destructive action as primary button without confirmation step
+- ❌ No focus trap — Tab leaks to the page behind
+
+### Forms
+
+- ❌ Placeholder as the only label — vanishes on focus, accessibility regression
+- ❌ Inline validation on keystroke — fights the user
+- ❌ Disabling the submit button without explaining why
+- ❌ Red asterisks on every field — visual noise
+- ❌ Forms wider than ~600px — eye tracking degrades
+
+### Tables
+
+- ❌ Centered text columns — slow to scan
+- ❌ Left-aligned numeric columns — magnitudes hide
+- ❌ Translucent sticky header — rows show through
+- ❌ Row dividers AND row hover background — over-decorated
+- ❌ A single fixed column width for every column — wastes space; let content determine width within sensible min/max

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