ima2-gen 2.0.15 → 2.0.16

package/skills/ima2-front/references/reference-capture.md

@@ -0,0 +1,120 @@
+# Reference Capture
+
+Capture reference sites only to learn structure, ground visual judgment, and
+provide reference material for concept mockups. Captures are analysis inputs,
+not project assets.
+
+Use this workflow when a page, component, brand system, or visual interaction
+needs source-grounded study before design synthesis or `ima2 --ref` mockups.
+
+---
+
+## Purpose
+
+### Analysis-Only Capture (FE-CAPTURE-01, STRICT)
+
+Captured third-party HTML, CSS, images, videos, logos, and font references are
+analysis-only. They may be used to:
+
+- study layout structure, density, hierarchy, spacing, and interaction shape
+- compare DOM/component composition against a target pattern
+- ground an `ima2 --ref` concept mockup or style exploration
+- document observed behavior in a devlog unit
+
+They must not be copied into shipped source, public assets, production
+bundles, marketing exports, or final deliverables.
+
+---
+
+## Mechanics
+
+### Capture Channels (FE-CAPTURE-02, DEFAULT)
+
+Use the least invasive public capture method that gives enough evidence.
+
+| Channel | Use |
+| --- | --- |
+| In-app browser `pageAssets` capability | List and bundle observed page assets from the rendered page |
+| `curl` / `wget` | Fetch public HTML, CSS, JSON, images, or videos needed for analysis |
+| DOM snapshot | Record structure, landmarks, role patterns, component nesting, and text density |
+| Screenshot | Capture visual state, responsive breakpoints, hover/open states, and motion posters |
+
+Do not bypass auth, paywalls, robots restrictions, private CDNs, signed URLs,
+or technical access controls.
+
+### Storage Location (FE-CAPTURE-03, STRICT)
+
+Store captures under the active devlog unit, never under shipped project asset
+directories such as `public/`, `assets/`, `images/`, `src/assets/`, or app
+static folders.
+
+Recommended shape: `devlog/<active-unit>/captures/manifest.md` plus one
+folder per source with captured DOM, CSS, screenshots, and notes.
+
+---
+
+## Legal Boundary
+
+### Never-Ship Rule (FE-CAPTURE-04, STRICT)
+
+Captured third-party assets never ship. This includes copied photographs,
+illustrations, videos, icons, logos, CSS artwork, SVGs, and bundled media.
+
+Webfont binaries are never copied. Treat webfonts as license-restricted by
+default even when they are publicly downloadable. You may record the font name,
+CSS stack, metrics observations, and usage notes for analysis.
+
+Photography, illustrations, videos, and logos are analysis-only unless they are
+independently re-sourced through shippable channels. Shippable brand assets
+come only from `brand-asset-sourcing.md` channels such as official press kits,
+Simple Icons, SVGL, theSVG, or other explicit licensed libraries.
+
+### Mockup Reference Boundary (FE-CAPTURE-05, DEFAULT)
+
+Captured material may be passed to `ima2 --ref` to ground composition, density,
+palette, or material exploration. The generated concept mockup remains an
+exploration artifact unless all shipped pixels are recreated or sourced through
+legal build-asset channels.
+
+Do not crop a captured logo, photo, illustration, or UI region out of a
+reference and place it into the build.
+
+---
+
+## Provenance Manifest
+
+### Manifest Required (FE-CAPTURE-06, STRICT)
+
+Every capture set needs a manifest stored next to the captured files, usually
+`captures/manifest.md` or `captures/manifest.json` inside the active devlog
+unit.
+
+Each capture record must include:
+
+| Field | Required Value |
+| --- | --- |
+| `source_url` | Original page or asset URL |
+| `capture_date` | Date captured, preferably ISO `YYYY-MM-DD` |
+| `license_status` | Known license, or `unknown - assume restricted` |
+| `intended_use` | `analysis` or `mockup-ref` |
+| `storage_path` | Path to the local captured file or folder |
+
+Optional fields: viewport, interaction state, tool used, notes, and
+replacement plan for any shippable equivalent.
+
+---
+
+## Ship Gate
+
+### Captured Asset Preflight (FE-CAPTURE-07, STRICT)
+
+Before shipping, verify that no captured third-party asset appears in the
+shipped build. The same row belongs in `preflight-full.md`:
+
+```text
+No captured third-party asset in the shipped build; capture manifest present
+for any reference captures.
+```
+
+If a captured reference inspired the final design, document the shippable
+replacement source or confirm the final pixels were recreated from scratch.

package/skills/ima2-front/references/responsive-viewport.md

@@ -0,0 +1,139 @@
+# Responsive & Viewport Rules (MANDATORY)
+
+Every multi-column layout, every full-height section, every image-heavy page MUST follow these rules. "It works at 1440px" is not responsive.
+
+---
+
+## Canonical Breakpoint Tiers
+
+| Tier | Breakpoint | Name | Tailwind | Devices |
+|------|-----------|------|----------|---------|
+| T1 | < 640px | Mobile | default | Phone portrait/landscape |
+| T2 | ≥ 640px | Large Mobile | `sm:` | Landscape phones, small tablets |
+| T3 | ≥ 768px | Tablet | `md:` | iPad portrait, desktop half-screen (1440px split) |
+| T4 | ≥ 1024px | Small Desktop | `lg:` | iPad landscape, laptop, desktop half-screen (1920px split) |
+| T5 | ≥ 1280px | Desktop | `xl:` | Standard desktop monitors |
+| T5+ | ≥ 1536px | Large Desktop | `2xl:` | Ultra-wide, large monitors |
+
+Use these tiers consistently. Do not invent ad-hoc `@media` breakpoints. Container query breakpoints are based on container width (not viewport tiers) — custom values like 400px or 900px are fine there.
+
+## Page Containment (MANDATORY)
+
+Every page layout MUST have a max-width wrapper:
+```css
+max-w-[1400px] mx-auto px-4 sm:px-6 lg:px-8
+```
+
+Without containment, text lines stretch to 200+ characters on wide monitors — unreadable.
+Full-bleed sections (hero images, color blocks) break out of containment with negative margins or `w-screen`.
+
+## Viewport Units
+
+- `min-h-[100dvh]` — ALWAYS. Accounts for mobile browser chrome (iOS Safari address bar).
+- `h-screen` / `100vh` — BANNED for full-height sections. These cause layout jump on mobile.
+- `svh` — use for "minimum guaranteed visible height" (rare).
+- `lvh` — use for background sizing where slight overflow is acceptable.
+
+## Container Queries (default for components)
+
+Prefer `@container` over `@media` for any reusable component. Components should adapt to their parent's width, not the viewport — this is what makes the same component work in a sidebar, modal, full-width layout, AND split-screen.
+
+```css
+.card-grid { container-type: inline-size; }
+
+@container (min-width: 600px) {
+  .card-grid { grid-template-columns: repeat(2, 1fr); }
+}
+@container (min-width: 900px) {
+  .card-grid { grid-template-columns: repeat(3, 1fr); }
+}
+```
+
+Reserve `@media` for page-level layout shifts (sidebar show/hide, nav mode switch, page grid columns).
+
+## Split-Screen / Half-Window (the neglected viewport)
+
+macOS split-view on a 1440px display gives each app ~640-720px. Windows snap on 1440px gives ~720px. On 1920px displays, each half is ~960px.
+
+This range (640-1024px) falls between "mobile collapse" and "full desktop." Most pages break here because rules only exist for < 768px and ≥ 1280px.
+
+Rules:
+- At 640-767px (T2): 2-column grids reduce to 1-column. Side-by-side hero stacks. Padding tightens.
+- At 768-1023px (T3): 3-column grids reduce to 2-column. Hero can remain side-by-side if text-heavy. Bento reduces to 2-column.
+- Test at 768px AND 1024px in addition to mobile and desktop widths.
+
+## Responsive Spacing Scale
+
+Section padding scales with viewport tier:
+
+| Element | Mobile (<640px) | Tablet (640-1023px) | Desktop (≥1024px) |
+|---------|-----------------|---------------------|--------------------|
+| Section vertical padding | `py-12` (3rem) | `py-16` (4rem) | `py-20` to `py-24` (5-6rem) |
+| Section horizontal padding | `px-4` (1rem) | `px-6` (1.5rem) | `px-8` (2rem) |
+| Inter-section gap | `gap-12` | `gap-16` | `gap-20` |
+| Card grid gap | `gap-4` | `gap-5` | `gap-6` |
+| Content max-width | `max-w-full` | `max-w-2xl` | `max-w-[1400px]` |
+
+## Responsive Images (MANDATORY for image-heavy pages)
+
+### srcset / sizes
+Above-fold / LCP images use `loading="eager"` (or omit — eager is the default) + `fetchpriority="high"`. Below-fold images use `loading="lazy"`. Example (above-fold hero):
+```html
+<img
+  src="hero-800.webp"
+  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+  alt="..."
+  loading="eager"
+  fetchpriority="high"
+  decoding="async"
+/>
+```
+
+### Art Direction (picture element)
+When the image crop must change between viewports (landscape hero → portrait on mobile):
+```html
+<picture>
+  <source media="(max-width: 639px)" srcset="hero-portrait.webp" />
+  <source media="(max-width: 1023px)" srcset="hero-square.webp" />
+  <img src="hero-landscape.webp" alt="..." />
+</picture>
+```
+
+### Aspect Ratio
+Lock aspect ratios to prevent layout shift:
+```css
+.hero-image { aspect-ratio: 16/9; object-fit: cover; }
+@media (max-width: 767px) { .hero-image { aspect-ratio: 4/5; } }
+```
+
+## Safe Area / Notch (MANDATORY for mobile)
+
+Modern phones have notches, dynamic islands, and home indicators. Content MUST not hide behind them:
+
+Apply safe-area insets selectively, not as blanket body padding (top inset on `body` conflicts with fixed navigation bars):
+
+```css
+/* Fixed bottom elements (sticky CTA, tab bar) */
+.sticky-bottom {
+  padding-bottom: calc(0.75rem + env(safe-area-inset-bottom));
+}
+
+/* Horizontal safe area for landscape notch devices */
+.page-wrapper {
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+```
+
+Add `viewport-fit=cover` to the meta viewport tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+## Nav Height Cap
+
+- Desktop nav: 64-72px default, 80px absolute max
+- Mobile nav: 56-64px
+- Nav must not consume >10% of viewport height
+- On scroll, nav can compact to 48px with `transition-all duration-200`

package/skills/ima2-front/references/seo-baseline.md

@@ -0,0 +1,123 @@
+# SEO, GEO & Social Sharing
+
+## Technical SEO
+
+### Required Meta Tags
+
+```html
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{Page Title} — {Site Name}</title>     <!-- ≤60 chars -->
+  <meta name="description" content="...">       <!-- ≤160 chars -->
+  <link rel="canonical" href="https://...">     <!-- absolute URL -->
+</head>
+```
+
+- One `<title>` per page, unique across the site
+- Description: complete sentence, not keyword stuffing
+- Canonical URL resolves www/non-www and trailing slash consistently
+- `lang` attribute must match page content language
+
+### Heading Hierarchy
+
+- `<h1>`: one per page, contains primary keyword naturally
+- `<h2>`: section headings, each a distinct topic
+- `<h3>`: subsections within h2. No skipping (h2 → h4 is invalid)
+- Never use heading tags for visual sizing — use CSS classes
+
+### Semantic HTML
+
+Use `<header>`, `<main>` (one per page), `<article>`, `<section>`, `<aside>`, `<footer>`, `<nav>`. Every `<img>` needs `alt` text. Every `<a>` needs discernible text. Use `<time datetime="...">` for dates.
+
+### Structured Data (JSON-LD)
+
+Always JSON-LD in `<head>`, never Microdata or RDFa.
+
+| Page Type | Schema | Required Fields |
+|-----------|--------|-----------------|
+| Landing/Home | `WebPage` + `Organization` | name, url, logo, description |
+| Product | `Product` | name, description, offers |
+| Blog post | `BlogPosting` | headline, datePublished, dateModified, author, image |
+| FAQ | `FAQPage` + `Question`/`Answer` | each Q&A pair |
+| Service | `Service` | name, description, provider, areaServed |
+| Breadcrumbs | `BreadcrumbList` | itemListElement with position + name + URL |
+
+- Schema MUST match visible page content — mismatched schema is penalized
+- Include `dateModified` on content pages
+- FAQPage schema has the highest AI citation lift
+- Test with Google Rich Results Test before shipping
+
+### Robots & Sitemap
+
+```
+User-agent: *
+Allow: /
+Sitemap: https://example.com/sitemap.xml
+
+User-agent: GPTBot
+Allow: /
+User-agent: ChatGPT-User
+Allow: /
+User-agent: anthropic-ai
+Allow: /
+User-agent: PerplexityBot
+Allow: /
+User-agent: Google-Extended
+Allow: /
+```
+
+- XML sitemap with `<lastmod>`, `<changefreq>`, `<priority>`
+- Allow AI crawlers by default — GEO requires it
+
+## GEO (Generative Engine Optimization)
+
+Optimizing content so AI answer engines (ChatGPT, Perplexity, Gemini, Claude) retrieve and cite your content. GEO is a layer ON TOP of SEO, not a replacement.
+
+### Strategies
+
+1. **Quotable content** — clear factual statements, TL;DR summaries, data tables an LLM can extract verbatim. Primary value proposition in the first 200 words.
+2. **FAQPage schema** — highest AI citation lift. Use whenever the page addresses common questions.
+3. **Content freshness** — visible "Last updated: YYYY-MM-DD" timestamp.
+4. **Authority signals** — original data, proprietary research, expert commentary.
+5. **Performance** — faster FCP strongly correlates with higher AI citation likelihood.
+6. **AI-generated pages** — always SSR/SSG. Never gate critical text behind client-side JS.
+
+## Social Sharing
+
+### Open Graph (Required)
+
+```html
+<meta property="og:title" content="Page Title">        <!-- ≤60 chars -->
+<meta property="og:description" content="...">          <!-- ≤160 chars -->
+<meta property="og:image" content="https://.../og.png"> <!-- 1200x630px -->
+<meta property="og:url" content="https://...">
+<meta property="og:type" content="website">
+<meta property="og:site_name" content="Site Name">
+<meta property="og:locale" content="ko_KR">
+```
+
+### Twitter Cards
+
+```html
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="Page Title">
+<meta name="twitter:description" content="...">
+<meta name="twitter:image" content="https://.../og.png">
+```
+
+- OG image: 1200x630px, PNG or JPG, < 1MB, no text smaller than 24px
+- For dynamic pages, generate OG images via edge function (Vercel OG, Satori)
+- Test with Twitter Card Validator, Facebook Debugger
+
+## Pre-flight
+
+- [ ] `<title>` unique and ≤ 60 chars
+- [ ] `<meta name="description">` present and ≤ 160 chars
+- [ ] `<link rel="canonical">` with absolute URL
+- [ ] `<html lang="...">` matches content language
+- [ ] JSON-LD structured data matches page type
+- [ ] OG tags present (title, description, image, url)
+- [ ] `<h1>` unique, one per page, no skipped levels
+- [ ] "Last updated" date visible on content pages

package/skills/ima2-front/references/soft-3d-asset-gates.md

@@ -0,0 +1,70 @@
+# Soft 3D / Character-Like Asset Gates
+
+Use this when a design includes soft 3D miniatures, toy-like objects, mascot/character illustrations, chibi proportions, rounded pastel 3D graphics, or tactile product metaphors.
+
+## Definition
+
+"Cute" in this context means visual assets, not Korean copy:
+
+- soft 3D miniature objects
+- toy-like product metaphors
+- character or mascot-like illustrations
+- rounded pastel tactile graphics
+- chibi/miniature proportions
+- finance/education/commerce concepts made into friendly objects
+
+It does not mean:
+
+- aegyo labels
+- childish error messages
+- excessive exclamation marks
+- fake friendliness in high-trust flows
+
+## Domain Gate
+
+| Domain | Gate |
+| --- | --- |
+| Kids / education | Allowed when it guides learning |
+| Community / casual commerce | Allowed when local, friendly, and restrained |
+| Consumer onboarding | Allowed when it reduces anxiety |
+| Fintech | Allowed only as premium semantic support, Toss-style; text and trust stay primary |
+| Government / public service | Avoid by default |
+| B2B / admin / ops | Avoid by default |
+| Developer tools | Avoid by default |
+| Auth / security / payment | Avoid unless it clarifies state without reducing trust |
+
+## Premium vs Slop
+
+Premium:
+
+- custom or brand-consistent asset system
+- semantic product metaphor
+- consistent lighting, material, perspective, and palette
+- one core graphic or clear hierarchy
+- subordinate to headline, CTA, and state
+- optimized and performant
+- works across supported themes
+
+Slop:
+
+- generic public 3D icon pack
+- random cute object unrelated to the page
+- inconsistent lighting/materials
+- low-polish AI output
+- decorative overload
+- asset competes with text or CTA
+- heavy 3D scene with no product value
+
+## Toss-Style Exception
+
+Soft 3D can work in Korean fintech when it behaves like Toss:
+
+- blue/white restrained palette
+- finance-related object metaphors
+- high production value
+- text-first hierarchy
+- simple clean digital style
+- no obstruction of key information
+
+Do not copy Toss assets. Extract the rule: premium, semantic, restrained, and brand-consistent.
+

package/skills/ima2-front/references/stacks/astro.md

@@ -0,0 +1,204 @@
+# Astro Stack
+
+Last reviewed: 2026-06-16
+Applies to: Astro 5.x
+When to read: Building or modifying Astro projects
+Canonical owner: dev-frontend
+
+Read `core/aesthetics.md` + `core/anti-slop.md` first.
+
+## 1. Islands Architecture
+
+Astro ships zero JavaScript by default. Interactive components are explicit **islands** that hydrate independently:
+
+```astro
+---
+// Static by default — no JS shipped
+import Header from '../components/Header.astro';
+import Counter from '../components/Counter.tsx';  // React island
+import Newsletter from '../components/Newsletter.svelte';  // Svelte island
+---
+
+<Header />
+
+<!-- Interactive islands — each hydrates independently -->
+<Counter client:load />
+<Newsletter client:visible />
+```
+
+| Directive | When JS Loads | Use Case |
+|-----------|--------------|----------|
+| `client:load` | Immediately on page load | Above-fold interactive elements (nav, search, auth) |
+| `client:idle` | After page is idle (`requestIdleCallback`) | Below-fold interactive elements, analytics |
+| `client:visible` | When element enters viewport | Comments, newsletter forms, lazy widgets |
+| `client:media` | When media query matches | Mobile-only interactive elements |
+| `client:only="react"` | Immediately, no SSR | Components that cannot SSR (canvas, WebGL, browser APIs) |
+| _(none)_ | Never — static HTML only | Content display, navigation, layout |
+
+Rules:
+- Default to no `client:*` directive — components are static HTML unless interaction is required.
+- Use `client:visible` for anything below the fold — saves initial bundle size.
+- Use `client:only` only when SSR genuinely fails (browser APIs, canvas) — it sends no HTML.
+- Every `client:*` directive adds a framework runtime to the page bundle — minimize island count.
+- Astro components (`.astro`) are always static — they cannot be islands. Use React/Svelte/Vue for interactive islands.
+
+## 2. Multi-Framework Shell
+
+Astro uniquely supports mixing frameworks in one project:
+
+| Framework | File Extension | Island Support | When to Use |
+|-----------|---------------|---------------|-------------|
+| React | `.tsx` / `.jsx` | Yes | Existing React component library, complex interactive UI |
+| Svelte | `.svelte` | Yes | Lightweight interactivity, transitions, form handling |
+| Vue | `.vue` | Yes | Existing Vue codebase, directive-heavy UI |
+| Solid | `.tsx` (with Solid plugin) | Yes | Performance-critical islands, fine-grained reactivity |
+| Preact | `.tsx` (with Preact plugin) | Yes | Smaller React-compatible islands |
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import svelte from '@astrojs/svelte';
+
+export default defineConfig({
+  integrations: [
+    react({ include: ['**/react/*'] }),
+    svelte(),
+  ],
+});
+```
+
+Rules:
+- Keep to **one primary framework** per project — multi-framework is for migration or specialized components, not default practice.
+- Organize framework-specific components in separate directories (`components/react/`, `components/svelte/`).
+- Shared state between different framework islands requires a framework-agnostic store (nanostores, signals).
+- Do not pass complex objects as island props — islands serialize props through HTML attributes. Use primitive types or simple objects.
+
+```typescript
+// Shared state across frameworks with nanostores
+// src/stores/cart.ts
+import { atom, map } from 'nanostores';
+
+export const cartItems = map<Record<string, CartItem>>({});
+export const cartCount = atom(0);
+```
+
+## 3. Content Collections
+
+Type-safe content management for Markdown, MDX, YAML, and JSON:
+
+```typescript
+// src/content.config.ts (Astro 5 — file-based content config)
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),
+    tags: z.array(z.string()).default([]),
+    draft: z.boolean().default(false),
+  }),
+});
+
+export const collections = { blog };
+```
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { getCollection, render } from 'astro:content';
+
+export async function getStaticPaths() {
+  const posts = await getCollection('blog', ({ data }) => !data.draft);
+  return posts.map(post => ({
+    params: { slug: post.id },
+    props: { post },
+  }));
+}
+
+const { post } = Astro.props;
+const { Content } = await render(post);
+---
+
+<article>
+  <h1>{post.data.title}</h1>
+  <time>{post.data.pubDate.toLocaleDateString()}</time>
+  <Content />
+</article>
+```
+
+Rules:
+- Define schemas for all content collections — untyped content defeats the purpose.
+- Use `z.coerce.date()` for dates — Markdown frontmatter dates are strings.
+- Filter drafts in `getCollection()` calls, not in templates.
+- Use Astro 5's `content.config.ts` (replaces `config.ts` in `src/content/`).
+
+## 4. Rendering Modes: SSG / SSR / Hybrid
+
+| Mode | Config | When to Use |
+|------|--------|-------------|
+| **SSG** (default) | `output: 'static'` | Blog, docs, marketing — content changes infrequently |
+| **SSR** | `output: 'server'` | Auth-gated, personalized, real-time — every request is dynamic |
+| **Hybrid** | `output: 'static'` + per-page `export const prerender = false` | Mostly static site with a few dynamic pages |
+
+```astro
+---
+// src/pages/dashboard.astro — dynamic page in hybrid mode
+export const prerender = false;
+
+const user = await getUser(Astro.cookies.get('session'));
+if (!user) return Astro.redirect('/login');
+---
+
+<h1>Welcome, {user.name}</h1>
+```
+
+Rules:
+- Default to SSG — ship HTML, not a server.
+- Use hybrid mode before full SSR — mark only dynamic pages with `prerender = false`.
+- SSR requires a deployment adapter (`@astrojs/node`, `@astrojs/vercel`, `@astrojs/cloudflare`).
+- Do not use SSR for content that can be statically generated — it adds latency and server cost.
+- Cache SSR responses at the CDN edge when content is user-independent.
+
+### Deployment Adapters
+
+| Adapter | Target | Install |
+|---------|--------|---------|
+| `@astrojs/node` | Node.js server (Docker, VPS) | `npx astro add node` |
+| `@astrojs/vercel` | Vercel (edge/serverless) | `npx astro add vercel` |
+| `@astrojs/cloudflare` | Cloudflare Workers/Pages | `npx astro add cloudflare` |
+| `@astrojs/netlify` | Netlify Functions | `npx astro add netlify` |
+| _(none)_ | Static output (default) | No adapter needed for SSG |
+
+### Performance Characteristics
+
+| Metric | Astro 5 | Next.js 16 | SvelteKit 2 |
+|--------|---------|------------|-------------|
+| Default JS shipped | 0 KB (static pages) | Framework runtime (~80 KB) | ~2 KB (compiled) |
+| Hydration model | Islands (opt-in per component) | Full page (RSC partial) | Full page |
+| Multi-framework | Yes (React + Svelte + Vue) | React only | Svelte only |
+| Content layer | Built-in Collections + Zod | MDX (plugin) | mdsvex (plugin) |
+| Build tool | Vite | Turbopack/Webpack | Vite |
+| Best for | Content-heavy, docs, marketing | Full-stack apps | Interactive apps |
+
+## 5. Anti-Patterns
+
+| Banned | Symptom | Fix |
+|--------|---------|-----|
+| `client:load` on everything | Full React/Vue/Svelte runtime shipped on every page | Use `client:visible` or `client:idle`; most components need no JS |
+| Multiple frameworks without justification | Bundle bloat — each framework adds its runtime | One primary framework; multi-framework only for migration |
+| Complex objects as island props | Serialization errors, silent data loss | Use primitives or simple objects; fetch data inside the island |
+| SSR for static content | Unnecessary server cost and latency | Use SSG or hybrid mode (§4) |
+| Skipping content collection schemas | Untyped frontmatter, runtime errors on missing fields | Always define Zod schemas for collections (§3) |
+
+## Pre-flight
+
+- [ ] Default rendering is SSG unless dynamic pages are explicitly marked
+- [ ] Islands use appropriate `client:*` directives — no unnecessary `client:load`
+- [ ] Single primary framework chosen; multi-framework justified if present
+- [ ] Content collections have Zod schemas defined
+- [ ] Island prop types are serialization-safe (no functions, classes, or complex objects)
+- [ ] Shared cross-framework state uses nanostores or equivalent