@maccesar/aiskills 1.7.0

package/skills/stitch-showcase/references/04-screen-gallery.md

@@ -0,0 +1,102 @@
+# Section: Screen Gallery
+
+## Purpose
+
+The main browsing area where users explore all screens. Organized by sections with filterable tabs, searchable, and switchable between grid and list views.
+
+## Data Required (from showcase_context.json)
+
+- `sections` — array of `{name, key, screens}` for section grouping and tabs
+- `all_screens` — flat list for search/filter
+- Each screen: `slug`, `title`, `description`, `html_file`, `png_file`, `detected_type`
+- `type` — project-level type for default aspect ratios
+- `color_tokens.accent` or `colors.primary` — accent color for hover/active states
+
+## Design Requirements
+
+### Section Tabs
+
+- Horizontal scrollable pill bar below the navbar (or inside gallery header)
+- "All" tab + one tab per section with screen count badge
+- Active tab: accent color background with white text
+- Inactive: ghost pill with hover state
+- Tabs scroll horizontally on mobile with `-webkit-overflow-scrolling: touch`
+
+### Screen Cards (Grid Mode)
+
+- **Aspect ratio adapts to screen type**:
+  - If `detected_type === "mobile"` → `aspect-ratio: 9/16` (portrait phone)
+  - If `detected_type === "web"` → `aspect-ratio: 16/10` (landscape desktop)
+  - If `detected_type === "unknown"` → use project-level `type` default
+- Thumbnail: `object-cover object-top` for natural cropping
+- Card structure: thumbnail on top, title + description below, separated by subtle border
+- Hover: slight scale (1.02), accent border, elevated shadow
+- Dark/light variant badge: if slug ends with `_oscuro`/`_dark` → dark badge; `_claro`/`_light` → light badge
+- Grid: 4 columns for mobile screens, `auto-fill minmax(280px, 1fr)` for web screens
+- Gap: 16-20px between cards
+
+### Screen Cards (List Mode)
+
+- Horizontal card: small thumbnail (120px wide) on left, title + full description on right
+- No line-clamp on description in list mode
+- Compact vertical spacing (8px gap)
+
+### Empty State
+
+- When search yields no results: centered message with muted icon and "No screens match your search" text
+- When a section has 0 screens: section is hidden from tabs
+
+### Card Link Behavior
+
+- Each card links to `viewer.html?screen={html_file}&title={title}&desc={description}`
+- **Critical**: if `detected_type === "web"`, link to the web viewer. If `detected_type === "mobile"`, link to the mobile viewer.
+- Opens in new tab (`target="_blank"`)
+
+## Functional Requirements
+
+- **Section filtering**: clicking a tab shows only that section's cards; "All" shows everything
+- **Search**: filters cards by title and description text match (case-insensitive)
+- **View toggle**: switches between grid and list layouts; persists in localStorage
+- **Smooth transitions**: cards fade/slide when filtering sections
+- Cards use `loading="lazy"` on thumbnail images
+
+## Anti-Patterns
+
+- Do NOT use uniform aspect ratios for mixed web+mobile projects — web screens in portrait cards look broken
+- Do NOT hide descriptions in grid mode — they provide context for choosing which screen to view
+- Do NOT use tiny cards — minimum card width of 200px for mobile, 240px for web
+- Do NOT use pagination — show all screens and rely on section tabs + search for navigation
+
+## Structural Pattern
+
+```
+<section> gallery: max-w-7xl mx-auto px-6
+  <div> gallery-header
+    <h2> "Screens" + intro text
+    <div> section tabs (pill bar)
+
+  <div> screens-container
+    for each section:
+      <section> data-section="{key}"
+        <h3> section name + count
+        <div> screens-grid: grid of cards
+          for each screen:
+            <a> screen-card → viewer.html?...
+              <div> card-thumb: aspect-ratio based on detected_type
+                <img> thumbnail
+                <span> dark/light badge (conditional)
+              <div> card-info
+                <p> title
+                <p> description
+```
+
+## Contract (Required IDs/Classes)
+
+- `.screen-section[data-section="{key}"]` — section wrapper for tab filtering
+- `.screen-card` — each card element
+- `.screens-grid` — the grid container (JS toggles `.list-mode` class)
+- `.filter-tab[data-section="{key}"]` — tab buttons
+- `.card-thumb` — thumbnail container
+- `.card-info` — text info container
+- `.card-desc` — description paragraph
+- Viewer URL format: `viewer.html?screen={html_file}&title={encodeURIComponent(title)}&desc={encodeURIComponent(description)}`

package/skills/stitch-showcase/references/05-viewer-web.md

@@ -0,0 +1,105 @@
+# Section: Viewer — Web
+
+## Purpose
+
+Full-screen viewer for web (desktop/dashboard) designs. Displays the screen's HTML in an iframe that fills the available viewport width, mimicking a real browser window with chrome decoration.
+
+## Data Required (from URL parameters)
+
+- `screen` — path to the HTML file (e.g., `assets/dashboard.html`)
+- `title` — screen title for the header
+- `desc` — screen description
+
+## Data Required (from showcase_context.json — embedded in viewer)
+
+- `all_screens` — flat ordered list for prev/next navigation
+- `font_family` — consistent typography
+- `default_theme` — initial theme
+- `project_name` — page title
+
+## Design Requirements
+
+### Browser Chrome Bar
+
+- A decorative bar at the top of the iframe area simulating a browser window:
+  - Three dots (red/yellow/green) on the left
+  - URL bar in the center showing the screen slug (non-functional, decorative)
+  - Subtle rounded corners on the chrome bar
+- The chrome bar is purely decorative — it frames the web design to feel like viewing a real website
+
+### Iframe Container
+
+- **Full viewport width** within content area (no phone frame!)
+- `width: 100%` with natural height based on content, or `height: calc(100vh - header - chrome)`
+- No artificial width constraints — web designs must breathe
+- Border: subtle `1px solid` border around the iframe area
+- Background: neutral dark (matches iframe loading state)
+
+### Header Bar
+
+- Compact header (48-56px) with:
+  - Back button (← or X) that calls `window.close()` or navigates back
+  - Screen title (truncated)
+  - Screen description (right-aligned, muted, hidden on mobile)
+  - Prev/Next navigation arrows
+  - Fullscreen toggle button
+
+### Navigation
+
+- **Prev/Next**: arrow buttons cycle through `all_screens` in order
+- **Keyboard shortcuts**: Left/Right arrow keys for prev/next, Escape to go back, F for fullscreen
+- Wrap around: after last screen, next goes to first
+
+## Functional Requirements
+
+- **URL-driven**: reads `?screen=...&title=...&desc=...` params on load
+- **Prev/Next updates URL** without page reload (history.replaceState)
+- **Fullscreen**: Fullscreen API on the iframe container (not the whole page)
+- **Theme**: respects localStorage theme setting from index.html
+- **Responsive**: on very small screens, hide the chrome bar and description, keep core functionality
+
+## Anti-Patterns
+
+- **NEVER** use a phone frame for web designs — this is the critical bug being fixed
+- **NEVER** constrain the iframe to a fixed narrow width (like 390px)
+- Do NOT add scrollbars around the iframe — let the iframe content handle its own scroll
+- Do NOT use a heavy header that competes with the design being viewed
+
+## Structural Pattern
+
+```
+<html>
+  <head> title, theme setup, Tailwind CDN, font
+  <body> flex flex-col h-screen
+    <header> compact bar
+      <button> back
+      <span> title
+      <span> description (desktop only)
+      <div> prev / next / fullscreen buttons
+
+    <main> flex-1 overflow-hidden
+      <div> browser-chrome-bar
+        <div> three dots
+        <div> fake URL bar
+      <div> iframe-container
+        <iframe> src={screen param} width=100% height=100%
+
+    <script>
+      - Parse URL params
+      - Load all_screens from embedded JSON
+      - Prev/next navigation
+      - Keyboard shortcuts
+      - Fullscreen toggle
+      - Theme management
+```
+
+## Contract
+
+- `id="viewer-frame"` — the iframe element
+- `id="screen-title"` — title display
+- `id="screen-desc"` — description display
+- `id="btn-back"` — back/close button
+- `id="btn-prev"` / `id="btn-next"` — navigation buttons
+- `id="btn-fullscreen"` — fullscreen toggle
+- URL format: `viewer.html?screen={path}&title={title}&desc={desc}`
+- `SCREENS_DATA` — embedded JSON array of all screens (for prev/next)

package/skills/stitch-showcase/references/06-viewer-mobile.md

@@ -0,0 +1,104 @@
+# Section: Viewer — Mobile
+
+## Purpose
+
+Viewer for mobile app designs. Displays the screen's HTML inside a realistic phone frame (390×844), centered on the page, with device-like bezel styling.
+
+## Data Required (from URL parameters)
+
+- `screen` — path to the HTML file (e.g., `assets/login.html`)
+- `title` — screen title for the header
+- `desc` — screen description
+
+## Data Required (from showcase_context.json — embedded in viewer)
+
+- `all_screens` — flat ordered list for prev/next navigation
+- `font_family` — consistent typography
+- `default_theme` — initial theme
+- `project_name` — page title
+
+## Design Requirements
+
+### Phone Frame
+
+- **Dimensions**: 390×844px (iPhone 14/15 logical resolution)
+- **Bezel**: 8px solid border with rounded corners (40px border-radius)
+- **Notch/Dynamic Island**: optional decorative element at the top (a small pill shape)
+- **Shadow**: deep box-shadow to lift the device off the background: `0 20px 60px rgba(0,0,0,0.4)`
+- **Background behind frame**: dark neutral (#0d0d0d dark mode, #f0f0f0 light mode)
+
+### Responsive Scaling
+
+- On viewports narrower than ~450px, scale the phone frame down using `transform: scale()` to fit
+- Calculate scale factor: `min(1, (viewportWidth - 40) / 390)`
+- Also scale vertically if viewport height is limited: `min(1, (viewportHeight - headerHeight - 40) / 844)`
+- Use `transform-origin: top center`
+
+### Header Bar
+
+- Same compact header pattern as web viewer:
+  - Back button → `window.close()`
+  - Screen title (truncated)
+  - Description (hidden on mobile)
+  - Prev/Next arrows
+  - Fullscreen toggle
+
+### Iframe Inside Frame
+
+- `width: 390px; height: 844px` — matches the frame interior
+- `border: none`
+- Overflow handled by the iframe's own content
+
+## Functional Requirements
+
+- **URL-driven**: reads `?screen=...&title=...&desc=...` params
+- **Prev/Next**: cycles through all_screens; updates URL via history.replaceState
+- **Keyboard shortcuts**: Left/Right arrows, Escape, F for fullscreen
+- **Fullscreen**: expands the phone frame container (not just the iframe)
+- **Theme**: respects localStorage theme from index.html
+- **Scaling recalculates on window resize**
+
+## Anti-Patterns
+
+- **NEVER** display web designs in this viewer — they will be crushed to 390px
+- Do NOT remove the phone frame border/bezel — it provides essential context
+- Do NOT use fixed positioning that breaks on mobile browsers
+- Do NOT let the phone frame overflow the viewport without scaling
+
+## Structural Pattern
+
+```
+<html>
+  <head> title, theme setup, Tailwind CDN, font
+  <body> flex flex-col h-screen bg-neutral
+    <header> compact bar
+      <button> back
+      <span> title
+      <span> description (desktop only)
+      <div> prev / next / fullscreen buttons
+
+    <main> flex-1 flex items-center justify-center
+      <div> phone-wrap: 390x844, border, border-radius, shadow
+        <iframe> src={screen} 390x844
+
+    <script>
+      - Parse URL params
+      - Responsive scaling logic
+      - Prev/next from embedded SCREENS_DATA
+      - Keyboard shortcuts
+      - Fullscreen toggle
+      - Theme management
+      - Window resize handler for scale recalculation
+```
+
+## Contract
+
+- `id="phone-wrap"` — the phone frame container
+- `id="viewer-frame"` — the iframe element
+- `id="screen-title"` — title display
+- `id="screen-desc"` — description display
+- `id="btn-back"` — back/close button
+- `id="btn-prev"` / `id="btn-next"` — navigation buttons
+- `id="btn-fullscreen"` — fullscreen toggle
+- Phone dimensions: exactly 390×844px (CSS), scaled via transform
+- `SCREENS_DATA` — embedded JSON array of all screens

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

@@ -0,0 +1,77 @@
+# Section: Theme System (Light/Dark Mode)
+
+## Purpose
+
+Consistent light/dark mode across index.html and viewer.html, with intelligent defaults based on the project's surface color and user preference persistence.
+
+## Data Required (from showcase_context.json)
+
+- `default_theme` — "light" or "dark", computed from surface color luminance
+- `color_tokens.surface` — the app's surface color (used to compute smart default)
+
+## Design Requirements
+
+### Smart Default
+
+The default theme is the **opposite** of the app's surface color for maximum contrast:
+- Dark app surface (luminance < 100) → showcase opens in **light** mode
+- Light app surface (luminance > 155) → showcase opens in **dark** mode
+- This ensures thumbnails stand out against the showcase background
+
+### Color Tokens
+
+| Element | Light Mode | Dark Mode |
+|---------|-----------|-----------|
+| Page background | `#f5f5f5` or `#fafafa` | `#0d0d0d` or `#0a0a0a` |
+| Card background | `#ffffff` | `#1a1a1a` |
+| Card border | `rgba(0,0,0,0.08)` | `rgba(255,255,255,0.08)` |
+| Text primary | `#111827` (gray-900) | `#f3f4f6` (gray-100) |
+| Text secondary | `#6b7280` (gray-500) | `#9ca3af` (gray-400) |
+| Text muted | `#9ca3af` (gray-400) | `#6b7280` (gray-500) |
+
+### Transitions
+
+- All color transitions: `transition-colors duration-200`
+- Apply to `<body>` and major containers
+- No flash of wrong theme on load (theme class applied before render)
+
+## Functional Requirements
+
+### Initialization (Critical — no flash)
+
+```javascript
+// In <head> BEFORE any rendering — blocks render until class is set
+(function() {
+  const saved = localStorage.getItem('showcase-theme');
+  const defaultTheme = '{{DEFAULT_THEME}}'; // from context
+  const theme = saved || defaultTheme;
+  if (theme === 'dark') document.documentElement.classList.add('dark');
+})();
+```
+
+### Toggle Logic
+
+```javascript
+document.getElementById('theme-toggle').addEventListener('click', () => {
+  document.documentElement.classList.toggle('dark');
+  const isDark = document.documentElement.classList.contains('dark');
+  localStorage.setItem('showcase-theme', isDark ? 'dark' : 'light');
+});
+```
+
+### Shared State
+
+- Both index.html and viewer.html read/write the same `localStorage` key: `'showcase-theme'`
+- Opening viewer from index inherits the current theme immediately
+
+## Implementation Notes
+
+- Use Tailwind's `darkMode: 'class'` configuration
+- 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
+
+## Anti-Patterns
+
+- 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

@@ -0,0 +1,81 @@
+# Section: Type Detection & Routing
+
+## Purpose
+
+Intelligent per-screen type detection that ensures web designs open in the web viewer (full-width) and mobile designs open in the mobile viewer (phone frame). Solves the critical bug where web designs were displayed inside a phone frame.
+
+## Data Required (from showcase_context.json)
+
+- `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)
+
+Each screen's HTML is analyzed for these signals:
+
+| Signal | Points | Type |
+|--------|--------|------|
+| `user-scalable=no` in viewport meta | +2 | mobile |
+| `maximum-scale=1` in viewport meta | +1 | mobile |
+| Fixed widths 375-430px in CSS | +2 | mobile |
+| Desktop breakpoints (768px+) in media queries | +2 | web |
+| Sidebar/nav-rail/drawer patterns | +1 | web |
+| Wide fixed widths (900px+) | +1 | web |
+
+If mobile score > web score → mobile. If web > mobile → web. Tie → "unknown".
+
+## Routing Rules
+
+### In index.html (Gallery Cards)
+
+When generating card links, the AI must use the correct viewer:
+
+```
+if screen.detected_type === "web":
+    link → viewer-web.html?screen=...
+elif screen.detected_type === "mobile":
+    link → viewer-mobile.html?screen=...
+elif screen.detected_type === "unknown":
+    link → viewer based on project-level type
+```
+
+### Single vs Dual Viewer Strategy
+
+**Option A — Two separate viewer files** (simpler):
+- `viewer-web.html` — always renders full-width with browser chrome
+- `viewer-mobile.html` — always renders in phone frame
+- Cards link to the appropriate one
+
+**Option B — Single viewer.html with mode parameter** (DRYer):
+- `viewer.html?screen=...&mode=web` or `mode=mobile`
+- Viewer reads mode param and adjusts layout accordingly
+- Prev/next must respect mode of each screen
+
+**Recommended**: Option B for mixed-type projects, Option A when all screens are the same type.
+
+### Gallery Card Aspect Ratios
+
+Cards in the gallery should adapt their thumbnail aspect ratio:
+- Mobile screens: `aspect-ratio: 9/16` (tall portrait)
+- Web screens: `aspect-ratio: 16/10` (wide landscape)
+- This provides visual differentiation even before clicking
+
+### Mixed-Type Badges
+
+For projects with both web and mobile screens, add a small badge on cards:
+- Mobile screens: phone icon or "Mobile" pill
+- Web screens: monitor icon or "Web" pill
+- Only show these badges in mixed-type projects (when both types exist)
+
+## Anti-Patterns
+
+- **NEVER** route all screens to the same viewer regardless of type — this is the bug being fixed
+- Do NOT ignore `detected_type` and only use project-level `type`
+- Do NOT show web designs in a phone frame under any circumstance
+- Do NOT show mobile designs in a full-width iframe (they'll be tiny and lost)
+
+## Contract
+
+- Viewer URL must include type/mode information
+- `detected_type` field must be present on every screen in the context JSON
+- Gallery cards must use adaptive aspect ratios based on detected_type

package/skills/stitch-showcase/references/09-quality-standards.md

@@ -0,0 +1,126 @@
+# Section: Quality Standards & Anti-Patterns
+
+## Purpose
+
+Guardrails that prevent the AI from generating generic, flat, "obviously AI-made" showcase HTML. This document defines the visual quality bar and common failure modes to avoid.
+
+## Required Skills
+
+Before generating ANY showcase HTML, the AI MUST invoke these skills:
+- **`frontend-design`** — for creative, distinctive HTML generation that avoids generic AI patterns
+- **`refactoring-ui`** — for visual hierarchy, depth, spacing, and typography decisions
+- **`ui-ux-pro-max`** — for color system best practices, component patterns, and interaction design
+
+These skills contain specific techniques for achieving professional-grade output.
+
+## Visual Quality Bar
+
+The generated showcase should feel like it was designed by a product designer at **Linear, Raycast, Stripe, or Vercel** — not by a template engine. Specific qualities:
+
+### Depth & Layering
+- Use subtle shadows at multiple levels (not just `shadow-lg` on everything)
+- Cards should feel lifted off the surface with layered borders + shadows
+- Background should have subtle texture or gradient (not flat solid color)
+- Ghost borders (`border: 1px solid rgba(255,255,255,0.06)`) add refinement in dark mode
+
+### Typography
+- Use the project's font family with a clear **type scale** (not everything the same size)
+- Tracking adjustments: `-0.02em` on headings, normal on body
+- Font weight hierarchy: Bold (700) for headings, Semibold (600) for labels, Regular (400) for body
+- Line height: tight (1.2) on headings, relaxed (1.6) on body text
+
+### Color Usage
+- Accent color used sparingly: tab highlights, hover borders, interactive elements
+- **NEVER** as large surface backgrounds
+- Neutral surfaces with slight warmth or coolness (not pure gray)
+- Sufficient contrast ratios (WCAG AA minimum: 4.5:1 for text)
+
+### Spacing & Rhythm
+- Consistent spacing scale: 4px base (4, 8, 12, 16, 24, 32, 48, 64)
+- Generous whitespace between sections (48-96px)
+- Tighter spacing within components (8-16px)
+- Asymmetric padding creates visual interest (more top than bottom, more left than right for headers)
+
+### Micro-interactions
+- Hover states on ALL interactive elements (cards, buttons, tabs)
+- Scale transforms on card hover: `scale(1.02)` — subtle, not bouncy
+- Color transitions: `transition-colors duration-200`
+- Focus-visible rings for keyboard navigation accessibility
+
+### Responsive Behavior
+- Mobile-first: single column, then expand to grid
+- No horizontal scroll on any viewport
+- Touch-friendly tap targets (minimum 44×44px)
+- Breakpoints: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
+
+## Banned Patterns (The "Generic AI" Checklist)
+
+If you see yourself doing ANY of these, STOP and redesign:
+
+| Banned Pattern | Why It's Bad | What To Do Instead |
+|---|---|---|
+| Flat gray (#f3f4f6) background everywhere | Lifeless, no personality | Use near-white/near-black with subtle warmth |
+| All cards exactly the same size and spacing | Monotonous grid | Vary card sizes for DS section vs gallery cards |
+| Color swatches as small circles | Minimizes the design system | Large blocks showing relationships |
+| "Aa" as the only type specimen | Tells nothing about the typeface | Full type scale with real project text |
+| Generic sans-serif (system-ui) when font exists | Ignores project identity | Always load and apply the project's font |
+| Bright colored header/hero backgrounds | Clashes with thumbnails | Neutral backgrounds, accent as detail only |
+| No hover states | Feels static, dead | Every clickable element needs hover feedback |
+| Same border-radius everywhere | Boring uniformity | Vary: 8px for cards, 12px for modals, full for pills |
+| Centered everything | Template feel | Left-align text, asymmetric layouts |
+| "Welcome to..." copy | AI copywriting smell | Jump straight to project stats and content |
+| Rainbow gradients | Unprofessional | Monochrome or two-tone gradients from project palette |
+| Icon soup (decorative icons everywhere) | Visual noise | Icons only for functional purposes (toggle, nav) |
+
+## Technical Standards
+
+### Self-Contained HTML
+- Single HTML file with all CSS inline (in `<style>` or Tailwind classes)
+- Tailwind CSS via CDN: `<script src="https://cdn.tailwindcss.com"></script>`
+- Google Fonts via CDN link
+- No external JS libraries beyond Tailwind
+- No build step required — just open in browser
+
+### Performance
+- Images use `loading="lazy"`
+- Minimal DOM nesting (avoid wrapper div soup)
+- CSS transitions, not JS animations
+- No layout shift on theme toggle
+
+### Accessibility
+- Semantic HTML: `<header>`, `<main>`, `<section>`, `<nav>`
+- All images have `alt` text
+- Focus-visible styles on interactive elements
+- Keyboard navigable: Tab through cards, Enter to open
+- `role="button"` on non-button clickable elements
+
+### URL Contract
+- Index links to viewer via: `viewer.html?screen={path}&title={title}&desc={desc}`
+- Viewer reads URL params and renders accordingly
+- Prev/next updates URL without reload (history.replaceState)
+
+## Inspiration References
+
+Study these products for visual quality benchmarks:
+- **Linear** — dark mode, subtle gradients, layered cards, excellent typography
+- **Raycast** — clean hierarchy, bold headings, muted descriptions, pill badges
+- **Stripe Docs** — structured sections, code blocks, clear information hierarchy
+- **Vercel Dashboard** — minimal, high contrast, excellent use of whitespace
+- **Apple Human Interface Guidelines** — phone frame styling, device showcasing
+
+## Verification Checklist
+
+Before declaring the showcase complete, verify:
+
+- [ ] Project font is loaded and applied (not falling back to system-ui)
+- [ ] Accent color from project is used (hover, active tab, not generic indigo)
+- [ ] Dark/light mode works and persists across pages
+- [ ] Design system section shows color RELATIONSHIPS, not just swatches
+- [ ] Typography specimen shows multiple sizes and weights
+- [ ] Gallery cards have correct aspect ratios (portrait for mobile, landscape for web)
+- [ ] Web screens open in full-width viewer, mobile screens in phone frame
+- [ ] Search filters cards
+- [ ] Section tabs filter correctly
+- [ ] Prev/next works in viewer with keyboard shortcuts
+- [ ] No horizontal scroll on mobile viewport
+- [ ] All hover states are present and smooth

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

@@ -0,0 +1,40 @@
+# Component Standardization
+
+## Problem
+
+Google Stitch generates slight variations of shared components (navbar, footer, tabbar) across screens within the same session. Navigation might have a different link order, footer might use different spacing, tabbar icons might differ.
+
+## Solution
+
+The `--components` flag detects these shared components, groups variants by similarity, and recommends a canonical version for the user to replicate across all screens.
+
+## Detection Strategy
+
+1. **Semantic tags**: `<nav>`, `<header>`, `<footer>`, `<aside>`
+2. **ARIA roles**: `role="navigation"`, `role="contentinfo"`, `role="tablist"`
+3. **CSS class patterns**: classes containing `nav`, `footer`, `sidebar`, `tabbar`, `bottom-nav`
+4. **Position fallback**: `position: fixed/sticky` with `top: 0` (navbar) or `bottom: 0` (tabbar)
+
+## Similarity Scoring
+
+Components are compared using a weighted score:
+- **DOM structure (50%)**: Tag-only tree signature comparison via `SequenceMatcher`
+- **CSS classes (30%)**: Jaccard similarity of class name sets
+- **Visible text (20%)**: Text content similarity via `SequenceMatcher`
+
+Default grouping threshold: **85% similarity**.
+
+## Canonical Selection
+
+Priority for choosing the canonical (best) version:
+1. Screens with "home", "main", "dashboard", "landing" in the slug
+2. Most DOM nodes (most complete version)
+3. First encountered
+
+## Output
+
+`shared_components.json` in the showcase directory, containing per component type:
+- `found_in`: number of screens containing this component
+- `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