stitch-kit 1.5.0

package/docs/tailwind-reference.md

@@ -0,0 +1,207 @@
+# Tailwind Utility Reference for Stitch Conversions
+
+Stitch exports **Tailwind-based HTML**. When converting to a target framework, map Tailwind utilities to the framework's native patterns — do not copy class names verbatim into non-Tailwind projects.
+
+This is the Tailwind-side lookup. Framework-specific mappings live in each skill's `resources/` directory.
+
+---
+
+## Scale quick reference
+
+Default spacing scale: `1` unit = `0.25rem` = `4px`
+
+| Tailwind | px | rem |
+|----------|----|-----|
+| `p-1` | 4px | 0.25rem |
+| `p-2` | 8px | 0.5rem |
+| `p-3` | 12px | 0.75rem |
+| `p-4` | 16px | 1rem |
+| `p-5` | 20px | 1.25rem |
+| `p-6` | 24px | 1.5rem |
+| `p-8` | 32px | 2rem |
+| `p-10` | 40px | 2.5rem |
+| `p-12` | 48px | 3rem |
+| `p-16` | 64px | 4rem |
+
+Same scale applies to `m-*`, `gap-*`, `space-*`, `w-*`, `h-*`.
+
+---
+
+## Layout
+
+| Tailwind class | Meaning |
+|----------------|---------|
+| `flex` | `display: flex` |
+| `flex-col` | `flex-direction: column` |
+| `flex-row` | `flex-direction: row` |
+| `flex-wrap` | `flex-wrap: wrap` |
+| `items-center` | `align-items: center` |
+| `items-start` | `align-items: flex-start` |
+| `items-end` | `align-items: flex-end` |
+| `justify-center` | `justify-content: center` |
+| `justify-between` | `justify-content: space-between` |
+| `justify-around` | `justify-content: space-around` |
+| `justify-end` | `justify-content: flex-end` |
+| `grid` | `display: grid` |
+| `grid-cols-2` | `grid-template-columns: repeat(2, 1fr)` |
+| `grid-cols-3` | `grid-template-columns: repeat(3, 1fr)` |
+| `gap-4` | `gap: 16px` |
+| `absolute` | `position: absolute` |
+| `relative` | `position: relative` |
+| `fixed` | `position: fixed` |
+| `sticky` | `position: sticky` |
+| `inset-0` | `top:0; right:0; bottom:0; left:0` |
+| `z-10` | `z-index: 10` |
+| `overflow-hidden` | `overflow: hidden` |
+| `overflow-y-scroll` | `overflow-y: scroll` |
+
+---
+
+## Sizing
+
+| Tailwind | CSS equivalent |
+|----------|----------------|
+| `w-full` | `width: 100%` |
+| `w-screen` | `width: 100vw` |
+| `w-1/2` | `width: 50%` |
+| `w-1/3` | `width: 33.333%` |
+| `w-auto` | `width: auto` |
+| `w-fit` | `width: fit-content` |
+| `h-full` | `height: 100%` |
+| `h-screen` | `height: 100vh` |
+| `h-auto` | `height: auto` |
+| `min-h-screen` | `min-height: 100vh` |
+| `min-h-[44px]` | `min-height: 44px` (touch target) |
+| `max-w-xs` | `max-width: 320px` |
+| `max-w-sm` | `max-width: 384px` |
+| `max-w-md` | `max-width: 448px` |
+| `max-w-lg` | `max-width: 512px` |
+| `max-w-xl` | `max-width: 576px` |
+| `max-w-2xl` | `max-width: 672px` |
+| `max-w-7xl` | `max-width: 1280px` |
+
+---
+
+## Typography
+
+| Tailwind | Size / weight |
+|----------|---------------|
+| `text-xs` | 12px |
+| `text-sm` | 14px |
+| `text-base` | 16px |
+| `text-lg` | 18px |
+| `text-xl` | 20px |
+| `text-2xl` | 24px |
+| `text-3xl` | 30px |
+| `text-4xl` | 36px |
+| `font-normal` | weight 400 |
+| `font-medium` | weight 500 |
+| `font-semibold` | weight 600 |
+| `font-bold` | weight 700 |
+| `leading-tight` | line-height 1.25 |
+| `leading-normal` | line-height 1.5 |
+| `leading-relaxed` | line-height 1.625 |
+| `tracking-tight` | letter-spacing -0.025em |
+| `tracking-wide` | letter-spacing 0.025em |
+| `truncate` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` |
+| `line-clamp-2` | clamp to 2 lines |
+| `text-left` | `text-align: left` |
+| `text-center` | `text-align: center` |
+
+---
+
+## Colors (Stitch custom tokens)
+
+Stitch extends Tailwind with custom theme keys. These appear in the HTML as classes like `bg-primary`, `text-primary`, `border-[var(--color-border)]`.
+
+| Stitch class / token | Likely semantic role |
+|----------------------|---------------------|
+| `bg-primary` / `--color-primary` | Brand primary color |
+| `text-primary` | Primary foreground text |
+| `bg-background` / `--color-background` | Page background |
+| `bg-surface` / `--color-surface` | Card / panel background |
+| `bg-card-light` / `bg-card-dark` | Card background (theme-specific) |
+| `border-[var(--color-border)]` | Default border color |
+| `text-muted` / `--color-text-muted` | Secondary / muted text |
+| `shadow-soft` / `shadow-floating` | Custom shadow values |
+
+When converting, map these to:
+- **CSS variables** (HTML, Next.js) — keep as `var(--color-primary)` etc.
+- **ThemeTokens struct** (SwiftUI) — `theme.primary`, `theme.surface`
+- **useTheme() hook** (React Native) — `theme.primary`, `theme.surface`
+- **Tailwind theme extension** (Next.js + Tailwind) — add to `tailwind.config.js`
+
+---
+
+## Border radius
+
+| Tailwind | Radius |
+|----------|--------|
+| `rounded-sm` | 2px |
+| `rounded` / `rounded-md` | 6–8px |
+| `rounded-lg` | 12px |
+| `rounded-xl` | 16px |
+| `rounded-2xl` | 24px |
+| `rounded-full` | 9999px (pill / circle) |
+| `rounded-none` | 0px |
+
+---
+
+## Backgrounds & effects
+
+| Tailwind | CSS |
+|----------|-----|
+| `bg-transparent` | `background: transparent` |
+| `opacity-50` | `opacity: 0.5` |
+| `shadow-sm` | small drop shadow |
+| `shadow-md` | medium drop shadow |
+| `shadow-lg` | large drop shadow |
+| `shadow-none` | no shadow |
+| `backdrop-blur-sm` | `backdrop-filter: blur(4px)` |
+| `backdrop-blur-md` | `backdrop-filter: blur(12px)` |
+
+---
+
+## Dark mode
+
+Stitch uses the `dark:` prefix. Classes like `dark:bg-gray-800` override the light mode value.
+
+In conversions:
+- **CSS variables approach** (Next.js, Svelte, HTML): map to `.dark` selector or `[data-theme="dark"]`
+- **`prefers-color-scheme`**: use `@media (prefers-color-scheme: dark)` for HTML/CSS
+- **React Native**: `useColorScheme()` → select `darkTokens` vs. `lightTokens`
+- **SwiftUI**: `@Environment(\.colorScheme)` → select `ThemeTokens.dark` vs. `.light`
+
+---
+
+## State variants
+
+| Tailwind prefix | When it applies |
+|-----------------|----------------|
+| `hover:` | Mouse hover |
+| `focus:` | Keyboard / programmatic focus |
+| `focus-visible:` | Focus only from keyboard (not click) |
+| `active:` | While being pressed |
+| `disabled:` | Element is disabled |
+| `sm:` | ≥ 640px viewport |
+| `md:` | ≥ 768px viewport |
+| `lg:` | ≥ 1024px viewport |
+| `xl:` | ≥ 1280px viewport |
+| `dark:` | Dark color scheme |
+
+---
+
+## Transitions & animation
+
+| Tailwind | CSS |
+|----------|-----|
+| `transition` | `transition: all 150ms cubic-bezier(...)` |
+| `transition-colors` | transition only color properties |
+| `duration-150` | 150ms |
+| `duration-300` | 300ms |
+| `ease-in-out` | `animation-timing-function: ease-in-out` |
+| `animate-spin` | infinite rotation |
+| `animate-pulse` | opacity pulse |
+| `animate-bounce` | bounce |
+
+For production animations, use `stitch-animate` instead of raw Tailwind animation utilities.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "stitch-kit",
+  "version": "1.5.0",
+  "description": "AI UI design to production code — Stitch MCP skills for Claude Code and Codex CLI. Generates screens, iterates designs, extracts tokens, converts to Next.js, Svelte, React, React Native, SwiftUI, or HTML.",
+  "bin": {
+    "stitch-kit": "./bin/stitch-kit.mjs"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "skills/",
+    "agents/",
+    "docs/",
+    "scripts/",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "stitch",
+    "ui-design",
+    "text-to-ui",
+    "claude-code",
+    "codex-cli",
+    "mcp",
+    "design-to-code",
+    "nextjs",
+    "svelte",
+    "react-native",
+    "swiftui",
+    "agent-skills"
+  ],
+  "author": "gabelul",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gabelul/stitch-kit.git"
+  },
+  "homepage": "https://github.com/gabelul/stitch-kit#readme"
+}

package/skills/stitch-a11y/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: stitch-a11y
+description: Audits Stitch-generated components for WCAG 2.1 AA accessibility issues and applies fixes — semantic HTML, ARIA attributes, keyboard navigation, focus management, and screen reader support.
+allowed-tools:
+  - "Read"
+  - "Write"
+  - "Bash"
+---
+
+# Stitch Accessibility Audit & Fix
+
+You are an accessibility engineer. You audit components generated from Stitch designs, identify WCAG 2.1 AA violations, and apply fixes directly to the source files. You don't just report issues — you fix them.
+
+**Run this skill AFTER** component generation. Components should be working before you audit them.
+
+## When to use this skill
+
+Use this skill when:
+- Components are generated and working, and need accessibility review before shipping
+- The design has complex interactive patterns (modals, dropdowns, tab panels, accordions, carousels)
+- The user mentions "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation"
+- Preparing for a production launch or accessibility audit
+
+## Step 1: Discover components to audit
+
+Read the project file structure to find all component files:
+```bash
+# Next.js / React
+find src -name "*.tsx" -not -path "*/node_modules/*"
+
+# SvelteKit
+find src -name "*.svelte" -not -path "*/node_modules/*"
+```
+
+Read each component file before auditing. Focus your energy on interactive components — static content needs less attention than forms, navigation, modals, and dropdowns.
+
+## Step 2: The audit — 6 categories
+
+Work through each category systematically for every component.
+
+### Category 1: Semantic HTML
+
+**Violations to find:**
+- `<div>` or `<span>` used for navigation, headers, footers, main content, articles, sections
+- `<div onClick>` instead of `<button>` or `<a>`
+- Heading hierarchy out of order (h3 before h2, skipping levels)
+- Tables used for layout (not data)
+- Lists rendered as plain `<div>` elements
+
+**Fixes:**
+```tsx
+// ❌ Wrong
+<div className="nav">
+  <div onClick={goHome}>Home</div>
+</div>
+
+// ✅ Fixed
+<nav aria-label="Main navigation">
+  <a href="/">Home</a>
+</nav>
+
+// ❌ Wrong — div button
+<div className="btn" onClick={handleClick}>Submit</div>
+
+// ✅ Fixed — real button
+<button type="button" onClick={handleClick}>Submit</button>
+
+// ❌ Wrong — visual list as divs
+<div className="menu">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+
+// ✅ Fixed
+<ul role="list">
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+```
+
+### Category 2: ARIA attributes
+
+Only add ARIA where semantic HTML doesn't provide sufficient information. Remember: **no ARIA is better than bad ARIA.**
+
+**Violations to find:**
+- Icon-only buttons with no accessible name
+- Multiple `<nav>` landmarks with no `aria-label`
+- Multiple `<main>` elements
+- Status/live regions that update dynamically but have no `aria-live`
+- Interactive elements missing `aria-expanded`, `aria-haspopup`, `aria-controls`
+
+**Fixes:**
+```tsx
+// Icon-only button
+<button aria-label="Close dialog" type="button">
+  <XIcon aria-hidden="true" />
+</button>
+
+// Multiple nav regions
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Breadcrumb">...</nav>
+<nav aria-label="Pagination">...</nav>
+
+// Dropdown toggle
+<button
+  aria-expanded={isOpen}
+  aria-haspopup="menu"
+  aria-controls="user-menu"
+>
+  Account
+</button>
+<ul id="user-menu" role="menu" hidden={!isOpen}>
+  <li role="menuitem"><a href="/profile">Profile</a></li>
+</ul>
+
+// Live status region
+<div aria-live="polite" aria-atomic="true" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+### Category 3: Keyboard navigation
+
+Every interactive element must be operable by keyboard. Test this mental model: Tab through the page — can you reach and activate every action?
+
+**Violations to find:**
+- Custom interactive elements that don't receive Tab focus
+- `tabIndex={-1}` used where focus should be reachable
+- `tabIndex={1}` or higher (breaks natural tab order)
+- Modal open — focus not moved into modal
+- Modal closed — focus not returned to trigger
+- Dropdown closed with Escape — focus not returned
+
+**Fixes:**
+```tsx
+// Focus management for modal — React
+import { useEffect, useRef } from 'react'
+
+export function Modal({ isOpen, onClose, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+
+  useEffect(() => {
+    if (isOpen) {
+      // Move focus into modal when it opens
+      modalRef.current?.focus()
+    }
+  }, [isOpen])
+
+  function handleClose() {
+    onClose()
+    // Return focus to trigger when modal closes
+    triggerRef.current?.focus()
+  }
+
+  return (
+    <>
+      <button ref={triggerRef} onClick={() => setIsOpen(true)}>
+        Open Modal
+      </button>
+      {isOpen && (
+        <div
+          ref={modalRef}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby="modal-title"
+          tabIndex={-1}  /* Makes div focusable without entering tab order */
+        >
+          <h2 id="modal-title">Modal Title</h2>
+          {children}
+          <button onClick={handleClose}>Close</button>
+        </div>
+      )}
+    </>
+  )
+}
+
+// Keyboard handler for custom interactive elements
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleAction}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      handleAction()
+    }
+  }}
+>
+  Custom button behavior
+</div>
+```
+
+```svelte
+<!-- Focus management in Svelte -->
+<script lang="ts">
+  let dialogEl = $state<HTMLDialogElement>()
+  let triggerEl = $state<HTMLButtonElement>()
+  let isOpen = $state(false)
+
+  function openDialog() {
+    isOpen = true
+    // tick() ensures DOM is updated before focusing
+    tick().then(() => dialogEl?.focus())
+  }
+
+  function closeDialog() {
+    isOpen = false
+    triggerEl?.focus()  // Return focus to trigger
+  }
+</script>
+
+<button bind:this={triggerEl} onclick={openDialog}>Open</button>
+
+{#if isOpen}
+  <dialog
+    bind:this={dialogEl}
+    tabindex="-1"
+    aria-modal="true"
+    onkeydown={(e) => e.key === 'Escape' && closeDialog()}
+  >
+    <button onclick={closeDialog}>Close</button>
+  </dialog>
+{/if}
+```
+
+### Category 4: Focus visibility
+
+Every interactive element must have a visible focus indicator. Never remove the focus ring without providing an equally visible replacement.
+
+**Violations to find:**
+- `outline: none` or `outline: 0` without a custom focus style
+- `.focus:outline-none` in Tailwind without `focus-visible:ring-*`
+- Focus styles that only appear on click, not keyboard focus
+
+**Fixes:**
+
+In CSS:
+```css
+/* Never this */
+*:focus { outline: none; }
+
+/* Always this — uses :focus-visible to show only on keyboard focus */
+*:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+```
+
+In Tailwind:
+```tsx
+// ❌ Wrong
+<button className="focus:outline-none">
+
+// ✅ Fixed
+<button className="focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2">
+```
+
+### Category 5: Images and media
+
+**Violations to find:**
+- `<img>` or `<Image>` without `alt` attribute
+- Meaningful images with `alt=""`
+- Decorative images with descriptive alt text (adds noise to screen readers)
+- Icons without accessible labels when used as interactive elements
+- Video without captions
+
+**Fixes:**
+```tsx
+// Meaningful image
+<Image src="/hero.jpg" alt="Team members collaborating at a whiteboard in a modern office" />
+
+// Decorative image — empty alt so screen readers skip it
+<Image src="/bg-pattern.svg" alt="" aria-hidden="true" />
+
+// Icon in a button — hide icon, label the button
+<button aria-label="Delete item">
+  <TrashIcon aria-hidden="true" />
+</button>
+
+// Icon with adjacent text — hide the icon (it's redundant)
+<button>
+  <SaveIcon aria-hidden="true" />
+  <span>Save changes</span>
+</button>
+```
+
+### Category 6: Color and contrast
+
+Check these without automated tools by reasoning about the design:
+
+**Violations to find:**
+- Muted text (`--color-text-muted`) on a muted background (`--color-surface`) — often fails 4.5:1
+- Primary color on white at small sizes — verify it passes 4.5:1
+- Disabled state text that's too light to read even as a hint
+- Relying on color alone to convey meaning (error states, required fields)
+
+**Fixes:**
+```tsx
+// Add non-color indicator for errors
+<input
+  aria-invalid={hasError}
+  aria-describedby={hasError ? 'email-error' : undefined}
+  className={hasError ? 'border-error' : 'border-border'}
+/>
+{hasError && (
+  <p id="email-error" role="alert" className="text-error">
+    {/* Icon + text — not color alone */}
+    <AlertIcon aria-hidden="true" />
+    Please enter a valid email address
+  </p>
+)}
+
+// Required field indicator
+<label>
+  Email
+  <span aria-hidden="true" className="text-error"> *</span>
+  <span className="sr-only">(required)</span>
+</label>
+```
+
+## Step 3: The `sr-only` utility class
+
+Add this to your global CSS if it's not there already. You'll use it frequently:
+
+```css
+/* Visually hidden, but readable by screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+/* Skip link — visible on focus for keyboard users */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+.skip-link:focus {
+  position: fixed;
+  top: 1rem;
+  left: 1rem;
+  width: auto;
+  height: auto;
+  padding: 0.5rem 1rem;
+  background: var(--color-primary);
+  color: var(--color-primary-fg);
+  border-radius: var(--radius-md);
+  font-weight: 600;
+  z-index: 9999;
+}
+```
+
+## Step 4: Skip navigation link
+
+Add a skip link as the first element in every page layout. This lets keyboard users jump past the navigation:
+
+```tsx
+// app/layout.tsx or +layout.svelte — first child of <body>
+<a href="#main-content" className="skip-link">
+  Skip to main content
+</a>
+
+// The target
+<main id="main-content" tabIndex={-1}>
+  {children}
+</main>
+```
+
+## Step 5: Generate the audit report
+
+After fixing, create `accessibility-audit.md` summarizing what was found and fixed:
+
+```markdown
+# Accessibility Audit Report
+
+**Date:** [date]
+**WCAG Target:** 2.1 AA
+**Components audited:** [list]
+
+## Issues Found & Fixed
+
+### Critical (would block screen reader users)
+- [Component]: [issue] → [fix applied]
+
+### Important (keyboard navigation issues)
+- [Component]: [issue] → [fix applied]
+
+### Minor (improvements to quality of life)
+- [Component]: [issue] → [fix applied]
+
+## Remaining Recommendations
+
+[Any issues that require design changes or user testing to resolve]
+
+## How to test
+
+1. Tab through the entire page — every interactive element should be reachable
+2. Activate with Enter/Space — all buttons and links should work
+3. Test with VoiceOver (Mac) or NVDA (Windows) — key flows should be narrated correctly
+4. Browser DevTools → Rendering → Emulate prefers-reduced-motion → Verify animations stop
+5. axe DevTools extension for automated checks
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `aria-labelledby` points to wrong ID | Ensure IDs are unique across the page |
+| Focus trap locking keyboard in modal | Implement proper Tab/Shift+Tab cycling within modal bounds |
+| Screen reader announcing redundant info | Add `aria-hidden="true"` to decorative elements |
+| Multiple violations in one component | Fix semantic HTML first — ARIA issues often cascade from it |
+| Skip link not showing | Ensure `:focus` state overrides the off-screen positioning |
+
+## References
+
+- `resources/audit-checklist.md` — Quick reference checklist for pre-ship review