Add accessibility, performance, SEO, dark mode & code examples

README.md

@@ -14,17 +14,27 @@ I'd love to hear your thoughts! If you have suggestions or find any bugs:
 
 There are four skills in this project. Each one lives in its own folder and contains a `SKILL.md` file.
 
-### 1. taste-skill
-The main design skill. Teaches the AI how to write good-looking frontend code from scratch. Covers layout, typography, colors, spacing, motion, and overall visual quality.
+### 1. taste-skill (14 sections)
+The main design skill. Teaches the AI how to write good-looking frontend code from scratch. Covers layout, typography, colors, spacing, motion, and overall visual quality. **Now includes:** accessibility (WCAG 2.2 AA), Core Web Vitals performance, responsive images, dark/light mode system, SEO meta architecture, and 4 before/after code examples.
 
 ### 2. redesign-skill
-For upgrading existing projects. Instead of rebuilding from zero, this skill walks the AI through auditing what's already there and fixing the biggest design problems first.
+For upgrading existing projects. Instead of rebuilding from zero, this skill walks the AI through auditing what's already there and fixing the biggest design problems first. **Now includes:** accessibility audit, Core Web Vitals audit, SEO audit, and an expanded 10-step fix priority.
 
-### 3. soft-skill
-Focuses on making things look and feel expensive. Covers premium fonts, big breathing whitespace, layered card designs with depth, smooth spring-based animations, and floating navigation. Bans all the generic defaults that make AI output look like a template.
+### 3. soft-skill (11 sections)
+Focuses on making things look and feel expensive. Use for luxury, editorial, or Awwwards-tier builds. Covers premium fonts, big breathing whitespace, layered card designs with depth, smooth spring-based animations, and floating navigation. Bans all the generic defaults that make AI output look like a template. **Now includes:** accessibility, dark/light mode, SEO & performance, and a clear "when to use this vs taste-skill" guide.
 
 ### 4. output-skill
-Stops the AI from being lazy. Prevents placeholder comments, skipped code blocks, and half-finished outputs. Forces the AI to actually write everything instead of cutting corners.
+Stops the AI from being lazy. Prevents placeholder comments, skipped code blocks, and half-finished outputs. Forces the AI to actually write everything instead of cutting corners. **Now includes:** multi-file output handling and iterative request rules.
+
+### When to use which skill
+
+| Scenario | Skill |
+|----------|-------|
+| Building a new SaaS, dashboard, or web app | taste-skill |
+| Building a luxury/editorial/agency site (Awwwards-tier) | soft-skill |
+| Upgrading an existing project | redesign-skill |
+| Any task requiring complete, untruncated output | output-skill |
+| Production build | taste-skill + output-skill (combine both) |
 
 ## How to Use
 

output-skill/SKILL.md

@@ -40,10 +40,30 @@ When a response approaches the token limit:
 
 On "continue", pick up exactly where you stopped. No recap, no repetition.
 
+## Multi-File Outputs
+
+When a task requires multiple files (e.g., "build a landing page with 5 components"):
+
+1. **Declare the file manifest** at the start. List every file you will create with its path.
+2. **Output each file completely** with its full path as the code block label.
+3. **Never merge files** to save space. Each file gets its own complete code block.
+4. **Imports must resolve.** For files created or modified in this response, ensure import/export paths are valid. Do not duplicate untouched repository files just to satisfy imports.
+5. **Include dependency commands.** If any file requires a package not in `package.json`, list all `npm install` commands at the top before any code.
+
+## Handling Iterative Requests
+
+When the user asks you to modify existing code:
+
+1. **Show the complete modified file** — not just the changed lines. Partial diffs are ambiguous and error-prone.
+2. **If only a small section changed,** you may show the full file and highlight the changed region in surrounding prose (use inline comments only when the file format supports them) — but never omit unchanged code with `// ...`.
+3. **If the user explicitly asks for "just the diff"** or "just the changed part," you may show only the changed section — but this is the ONLY exception.
+
 ## Quick Check
 
 Before finalizing any response, verify:
 - No banned patterns from the list above appear anywhere in the output
 - Every item the user requested is present and finished
 - Code blocks contain actual runnable code, not descriptions of what code would do
 - Nothing was shortened to save space
+- All imports across files resolve correctly
+- Dependency install commands are included for any new packages

redesign-skill/SKILL.md

@@ -120,6 +120,41 @@ Check for these problems and fix them:
 - **Import hallucinations.** Check that every import actually exists in `package.json` or the project dependencies.
 - **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta tags.
 
+### Accessibility
+
+- **Missing `prefers-reduced-motion` support.** All animations, transitions, parallax, and auto-playing carousels must disable or simplify when reduced motion is requested. This is the most commonly missed accessibility rule in AI-generated code.
+- **Poor color contrast.** Run all text/background pairs through a contrast checker. WCAG AA requires 4.5:1 for normal text, 3:1 for large text. Low-opacity text on subtle backgrounds usually fails.
+- **No focus indicators.** Every interactive element needs a visible `focus-visible` ring. Never set `outline: none` without a replacement.
+- **Missing ARIA labels.** Icon-only buttons, hamburger menus, close buttons, social links — all need `aria-label`.
+- **No skip-to-content link.** Add a hidden link that becomes visible on focus for keyboard users.
+- **Color used alone for meaning.** Error states, status indicators, and validation all need icons or text in addition to color.
+- **Missing `alt` text.** Every meaningful image needs descriptive alt text. Decorative images should have `alt=""` and `role="presentation"`.
+- **No keyboard trap handling.** Modals should trap focus when open and restore on close; menus should allow Tab/Shift+Tab to move away and Escape to close.
+- **Form inputs without labels.** Every `<input>` needs a visible `<label>` with matching `htmlFor`/`id`. Placeholder text is not a label.
+
+### Performance (Core Web Vitals)
+
+- **No image optimization.** Replace raw PNGs/JPGs with Next.js `<Image>`, `<picture>` with `srcset`, or WebP/AVIF formats. Set explicit `width` and `height` to prevent CLS.
+- **Hero image not preloaded.** Add `priority` (Next.js Image) or `<link rel="preload">` for the largest above-the-fold image. Target LCP < 2.5s.
+- **Fonts not preloaded.** Custom fonts cause FOUT/FOIT. Use `<link rel="preload" as="font" crossorigin>` for critical fonts. Use `font-display: swap`.
+- **No lazy loading below the fold.** Every image and heavy component below the fold should use `loading="lazy"` or `next/dynamic`.
+- **Oversized JavaScript bundle.** Check if Framer Motion (~57KB gz), GSAP (~25KB gz), or other animation libraries are imported but barely used. Tree-shake or dynamically import.
+- **Animations using layout-triggering properties.** `top`, `left`, `width`, `height` cause reflows. Switch to `transform` and `opacity`.
+- **No CLS prevention.** Images without dimensions, dynamically injected banners, and late-loading fonts all cause layout shift. Reserve space with skeletons.
+- **Missing `will-change` cleanup.** If `will-change: transform` is applied, it must be removed when animation completes.
+
+### SEO
+
+- **Missing or generic `<title>` tags.** Each page needs a unique, keyword-rich title under 60 characters.
+- **No meta description.** Add `<meta name="description">` under 160 characters per page.
+- **Missing Open Graph tags.** Add `og:title`, `og:description`, `og:image` (1200x630px), `og:url` for every public page.
+- **No canonical URL.** Add `<link rel="canonical">` to prevent duplicate content issues.
+- **Missing sitemap.xml and robots.txt.** Generate and serve both. Use the project's framework conventions (e.g., Next.js App Router: `app/sitemap.ts` and `app/robots.ts`; Pages Router/static setups: serve from `public/sitemap.xml` and `public/robots.txt`).
+- **Heading hierarchy broken.** One `<h1>` per page. Never skip levels (h1 → h3). Screen readers and crawlers use heading structure.
+- **No structured data (JSON-LD).** Add schema markup for Organization, Product, FAQ, BreadcrumbList as appropriate.
+- **Critical content hidden behind JavaScript.** Hero text, navigation, and primary CTAs must be server-rendered, not loaded client-side.
+- **Images without alt text.** Google indexes alt text. Be descriptive and specific, not generic.
+
 ### Strategic Omissions (What AI Typically Forgets)
 
 - **No legal links.** Add privacy policy and terms of service links in the footer.
@@ -162,11 +197,14 @@ Apply changes in this order for maximum visual impact with minimum risk:
 
 1. **Font swap** — biggest instant improvement, lowest risk
 2. **Color palette cleanup** — remove clashing or oversaturated colors
-3. **Hover and active states** — makes the interface feel alive
-4. **Layout and spacing** — proper grid, max-width, consistent padding
-5. **Replace generic components** — swap cliche patterns for modern alternatives
-6. **Add loading, empty, and error states** — makes it feel finished
-7. **Polish typography scale and spacing** — the premium final touch
+3. **Accessibility fixes** — contrast, focus rings, reduced motion, ARIA labels
+4. **Hover and active states** — makes the interface feel alive
+5. **Layout and spacing** — proper grid, max-width, consistent padding
+6. **Image optimization & performance** — responsive images, preloads, lazy loading
+7. **Replace generic components** — swap cliche patterns for modern alternatives
+8. **Add loading, empty, and error states** — makes it feel finished
+9. **SEO meta tags & structured data** — discoverability and social sharing
+10. **Polish typography scale and spacing** — the premium final touch
 
 ## Rules
 

soft-skill/SKILL.md

@@ -5,9 +5,12 @@ description: Teaches the AI to design like a high-end agency. Defines the exact
 
 # Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
 
+## 0. WHEN TO USE THIS SKILL
+Use **soft-skill** when building luxury, editorial, or agency-tier experiences where the visual bar is "Awwwards Site of the Day." Use **taste-skill** for general-purpose premium interfaces (SaaS, dashboards, standard web apps). When in doubt, start with taste-skill — it covers 90% of cases. Soft-skill is the upgrade path for projects where the client specifically demands "make it feel expensive."
+
 ## 1. Meta Information & Core Directive
 - **Persona:** `Vanguard_UI_Architect`
-- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion. 
+- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion.
 - **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. You must dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
 
 ## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
@@ -83,7 +86,33 @@ When generating UI code, follow this exact sequence:
 4. **[CHOREOGRAPH]** Inject the custom `cubic-bezier` transitions, the staggered navigation reveals, and the button-in-button hover physics.
 5. **[OUTPUT]** Deliver flawless, pixel-perfect React/Tailwind/HTML code. Do not include basic, generic fallbacks.
 
-## 8. PRE-OUTPUT CHECKLIST
+## 8. ACCESSIBILITY (NON-NEGOTIABLE)
+Premium is not premium if 15% of users cannot use it. Apply these rules without exception:
+* **Contrast:** All text must meet WCAG 2.2 AA (4.5:1 normal, 3:1 large). Ethereal Glass vibes with low-opacity text are beautiful but fail contrast — add a solid text-shadow or increase opacity.
+* **Reduced Motion:** Wrap ALL Framer Motion, GSAP, and CSS animations in `prefers-reduced-motion` checks. Spring physics, parallax, scroll hijacks — all must degrade to instant transitions when reduced motion is active. Use stack-appropriate detection: CSS `@media (prefers-reduced-motion: reduce)`, `window.matchMedia` in JS/GSAP, or `useReducedMotion()` only when Framer Motion is already in use. For a complete Framer Motion implementation example, see taste-skill Section 10 (ReducedMotionWrapper.tsx).
+* **Focus Indicators:** Every clickable element needs a visible `focus-visible` ring. Never use `outline-none` without an alternative.
+* **Keyboard Navigation:** Full Tab flow through all interactive elements. Focus traps limited to true modals. Hamburger menus must allow Escape to close and Tab to exit naturally.
+* **ARIA:** Icon-only buttons need `aria-label`. Dynamic content (toasts, counters) needs `aria-live`. Form inputs need linked `<label>` elements.
+* **Skip Link:** First focusable element must be "Skip to main content" — hidden until focused.
+* **Semantic HTML:** `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>` — not div soup.
+* **Color Independence:** Never use color alone for meaning. Status dots need text labels. Error inputs need icons + descriptive text.
+
+## 9. DARK/LIGHT MODE
+* Default to `prefers-color-scheme` detection on first visit. Store override in `localStorage`. Prevent theme flash with a blocking `<script>` in `<head>`.
+* **Dark mode is not inverted light mode.** Higher surfaces = lighter backgrounds (`#141414` → `#1c1c1c` → `#262626`). Reduce text contrast slightly (`#e4e4e7` body, not pure `#ffffff`).
+* **Shadows in dark mode** should be deeper (`rgba(0,0,0,0.5)`) and more diffused.
+* **Images:** Apply `brightness(0.9)` to photos in dark mode to prevent eye strain.
+* Use CSS custom properties as the single source of truth for all color values.
+
+## 10. SEO & PERFORMANCE
+* **Core Web Vitals:** LCP < 2.5s (preload hero image, fonts), CLS < 0.1 (explicit image dimensions), INP < 200ms (debounce handlers).
+* **Responsive Images:** Use `<Image>` (Next.js) or `<picture>` with `srcset`. Serve WebP/AVIF. Set explicit `sizes` attribute.
+* **Bundle Size:** Framer Motion (~57KB gz) + GSAP (~25KB gz) — never import both unless genuinely needed. Dynamic import heavy components below the fold.
+* **Meta Tags:** Every page needs `<title>`, `description`, `og:image`, `twitter:card`, canonical URL. Add JSON-LD structured data.
+* **Semantic Headings:** One `<h1>` per page. Never skip levels. Server-render all critical text content.
+* **Sitemap & Robots:** Generate `sitemap.xml` and `robots.txt`. Index all public pages.
+
+## 11. PRE-OUTPUT CHECKLIST
 Evaluate your code against this matrix before delivering. This is the last filter.
 - [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
 - [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
@@ -95,4 +124,11 @@ Evaluate your code against this matrix before delivering. This is the last filte
 - [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
 - [ ] All animations use only `transform` and `opacity` — no layout-triggering properties
 - [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
+- [ ] ALL animations respect `prefers-reduced-motion` (Section 8)
+- [ ] Color contrast meets WCAG AA ratios (4.5:1 normal, 3:1 large) (Section 8)
+- [ ] Focus indicators visible on all interactive elements (Section 8)
+- [ ] Semantic HTML used — no div soup (Section 8)
+- [ ] Hero image preloaded, all images responsive with explicit dimensions (Section 10)
+- [ ] Meta tags, OG image, canonical URL, and JSON-LD present (Section 10)
+- [ ] Dark mode uses elevated surfaces, not inverted shadows (Section 9)
 - [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"