ima2-gen 2.0.15 → 2.0.16

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

@@ -0,0 +1,264 @@
+# React Stack — Development Rules
+
+Rules specific to React projects. Read `core/aesthetics.md`, `core/anti-slop.md`, and `core/visual-verification.md` first.
+
+---
+
+## Domain Routing
+
+Before choosing component libraries, read the core references that match the surface:
+
+- Korean-first UI → `korea-2026.md`, `ux-writing-ko.md`
+- Tool/dashboard → `product-density.md`
+- Visual/product surface → `asset-requirements.md`
+- Soft 3D/mascot/miniature visuals → `soft-3d-asset-gates.md`
+- Substantial UI change → `visual-verification.md`
+
+## Behavior-First Components
+
+Prefer proven behavior primitives for complex interactive components:
+
+- Radix / Headless UI for dialog, popover, menu, tabs, combobox-like behavior
+- The project dropdown design layer (`references/core/dropdown-layer.md`
+  FE-DROPDOWN-LAYER-01) supplies the SKIN over these primitives; the skin never
+  replaces the primitive
+- shadcn/ui as source code scaffolding, not as a final visual design
+- Existing repo components before adding a new dependency
+
+Customize tokens, radius, shadows, density, and typography. Do not ship default shadcn visuals.
+
+## Korean Mobile Patterns
+
+React apps targeting Korean mobile flows should support:
+
+- bottom sheets for lightweight choices
+- full-screen funnels for complex steps
+- sticky bottom action bars
+- snackbar/toast for reversible confirmations
+- safe-area insets
+- `100dvh` instead of `100vh`
+- long Korean label stress tests
+
+## AI Tool States
+
+AI features must expose state clearly:
+
+- pending / queued
+- streaming or partial result
+- cancel
+- retry
+- undo or revert
+- source/provenance when applicable
+- permission boundary before sensitive actions
+- rate limit or failure recovery
+
+Do not hide AI uncertainty behind decorative gradients.
+
+## Architecture
+
+### Server Components When Supported By The Framework
+Use Server Components only in Next App Router or another RSC-enabled framework. In Vite, SPA-only React, React Native Web, or client-only embeds, do not introduce RSC assumptions or `'use client'` boundaries.
+
+When the framework supports RSC, default non-interactive route content to Server Components. Add `'use client'` ONLY when you need:
+- Event handlers (`onClick`, `onChange`)
+- State (`useState`, `useReducer`)
+- Effects (`useEffect`)
+- Browser APIs (`window`, `document`)
+
+```tsx
+// Server Component (default) — no 'use client'
+async function ProductPage({ params }) {
+  const product = await getProduct(params.id);
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton productId={product.id} />
+    </div>
+  );
+}
+
+// Client Component — only what MUST be interactive
+'use client';
+function AddToCartButton({ productId }) {
+  const [adding, setAdding] = useState(false);
+  return <button onClick={() => addToCart(productId)}>Add</button>;
+}
+```
+
+### RSC Safety Rules
+- Global state ONLY in Client Components
+- In Next.js, wrap providers in a `'use client'` wrapper component
+- If motion/interactivity needed, extract the interactive part as an **isolated leaf** Client Component
+
+### Interactivity Isolation
+Any component using `useMotionValue`, `useTransform`, or perpetual animations MUST be extracted as a dedicated Client Component in RSC-enabled frameworks. Server Components render static layouts only.
+
+---
+
+## State Management
+
+| Need                | Solution                                                |
+| ------------------- | ------------------------------------------------------- |
+| Local UI state      | `useState` / `useReducer`                               |
+| Form state          | React Hook Form + Zod validation                        |
+| Server-fetched data | TanStack Query (`@tanstack/react-query`)                |
+| Global shared state | Zustand (minimal, flat store)                           |
+| Deep prop drilling  | React Context (for dependency injection, NOT data flow) |
+
+**Anti-patterns**:
+- Don't use Context for frequently changing data (causes subtree re-renders)
+- Don't reach for global state when local state suffices
+- Don't use `useEffect` for data fetching — use TanStack Query or Server Components
+
+---
+
+## Component Patterns
+
+### Compound Components
+```tsx
+const Tabs = ({ children }) => {
+  const [active, setActive] = useState(0);
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      {children}
+    </TabsContext.Provider>
+  );
+};
+Tabs.List = TabList;
+Tabs.Panel = TabPanel;
+```
+
+### Custom Hooks (extract reusable logic)
+```tsx
+function useDebounce<T>(value: T, delay = 500): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+```
+
+### Generic List Component
+```tsx
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => React.ReactNode;
+}
+function List<T>({ items, renderItem }: ListProps<T>) {
+  return <ul>{items.map(renderItem)}</ul>;
+}
+```
+
+---
+
+## Styling
+
+### Tailwind CSS
+- Check `package.json` for Tailwind version. Do NOT mix v3/v4 syntax.
+- **T4 CONFIG GUARD**: For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or Vite plugin.
+- Use `cn()` utility for conditional classes:
+```tsx
+import { cn } from '@/lib/utils';
+<button className={cn(
+  'px-4 py-2 rounded',
+  variant === 'primary' && 'bg-emerald-500 text-white',
+  disabled && 'opacity-50 cursor-not-allowed'
+)} />
+```
+
+### shadcn/ui
+- MUST customize defaults — never ship generic appearance
+- Override `--radius`, color palette, shadow depth
+- All components should match project's aesthetic direction
+
+### CSS Variables for Design Tokens
+```css
+:root {
+  --color-primary: oklch(0.7 0.15 160);
+  --color-surface: oklch(0.98 0 0);
+  --radius-default: 0.75rem;
+  --shadow-card: 0 20px 40px -15px rgba(0,0,0,0.05);
+}
+```
+
+---
+
+## Dependency Verification [MANDATORY]
+
+Before importing ANY 3rd party library:
+1. Check `package.json`
+2. If missing, output `npm install <package>` BEFORE providing code
+3. **Never assume** a library exists
+
+---
+
+## Icons
+
+Use EXACTLY `@phosphor-icons/react` or `@radix-ui/react-icons` as import paths.
+Standardize `strokeWidth` globally (e.g., exclusively `1.5` or `2.0`).
+**NEVER** use emoji — see `anti-slop.md`.
+
+---
+
+## Performance
+
+### Bundle Optimization
+| Heavy Package | Size  | Alternative                    |
+| ------------- | ----- | ------------------------------ |
+| moment        | 290KB | date-fns (12KB) or dayjs (2KB) |
+| lodash        | 71KB  | lodash-es with tree-shaking    |
+| axios         | 14KB  | Native fetch or ky (3KB)       |
+| @mui/material | Large | shadcn/ui or Radix UI          |
+
+### Rendering
+- Parallel fetch: `Promise.all([getUser(), getStats()])`
+- Streaming: `<Suspense fallback={<Skeleton />}>`
+- Avoid waterfall: never fetch sequentially in nested components
+- `React.memo` for expensive pure components
+- `useMemo` / `useCallback` only when measured, not preemptively
+
+### Image Optimization
+```tsx
+// Above fold — load immediately
+<Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />
+
+// Responsive fill
+<div className="relative aspect-video">
+  <Image src="/product.jpg" alt="Product" fill
+    sizes="(max-width: 768px) 100vw, 50vw"
+    className="object-cover" />
+</div>
+```
+
+---
+
+## Testing
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('button triggers action', async () => {
+  const onClick = vi.fn();
+  render(<Button onClick={onClick}>Click</Button>);
+  await userEvent.click(screen.getByRole('button'));
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+
+test('dialog is accessible', () => {
+  render(<Dialog open title="Confirm" />);
+  expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
+});
+```
+
+---
+
+## Responsiveness
+
+- Standardize breakpoints: `sm`, `md`, `lg`, `xl`
+- Contain layouts: `max-w-[1400px] mx-auto` or `max-w-7xl`
+- **NEVER** `h-screen` for full-height. ALWAYS `min-h-[100dvh]`
+- **NEVER** `w-[calc(33%-1rem)]`. ALWAYS CSS Grid
+- DESIGN_VARIANCE levels 4-10: aggressive single-column fallback on `< 768px`

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

@@ -0,0 +1,235 @@
+# Svelte 5 / SvelteKit 2 Stack
+
+Last reviewed: 2026-06-16
+Applies to: Svelte 5.x (Runes), SvelteKit 2.x
+When to read: Building or modifying Svelte/SvelteKit projects
+Canonical owner: dev-frontend
+
+Read `core/aesthetics.md` + `core/anti-slop.md` first.
+
+## 1. Runes (Svelte 5)
+
+Svelte 5 replaces stores and reactive declarations with **Runes** — explicit reactivity primitives:
+
+| Rune | Replaces | Purpose |
+|------|----------|---------|
+| `$state()` | `let x = 0` (reactive) | Declare reactive state |
+| `$derived()` | `$: doubled = x * 2` | Computed value from state |
+| `$effect()` | `$: { sideEffect() }` | Side effect on state change |
+| `$props()` | `export let prop` | Declare component props |
+| `$bindable()` | `export let value` (two-way) | Two-way bindable prop |
+| `$inspect()` | `console.log` debugging | Dev-only reactive logging (stripped in prod) |
+
+```svelte
+<script>
+  let { title, onSave } = $props();
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+
+  $effect(() => {
+    console.log(`count changed to ${count}`);
+    return () => { /* cleanup */ };
+  });
+</script>
+
+<button onclick={() => count++}>
+  {title}: {count} (doubled: {doubled})
+</button>
+```
+
+Rules:
+- Use `$state()` for all mutable reactive values — bare `let` is no longer reactive in Svelte 5.
+- Prefer `$derived()` over `$effect()` for computed values — effects are for side effects only.
+- `$effect()` runs after DOM update. Use `$effect.pre()` only when you need pre-DOM-update timing.
+- Use `$inspect()` for debugging, never `console.log` inside `$effect()` — `$inspect` is stripped from production builds.
+- Destructure `$props()` at the top of `<script>` — do not access `$$props` or `$$restProps` (Svelte 4 patterns).
+
+## 2. SvelteKit 2
+
+### Routing & Data Loading
+
+```
+src/routes/
+├── +layout.svelte          # root layout
+├── +layout.server.ts       # root layout data (runs on server)
+├── +page.svelte            # home page
+├── +page.server.ts         # home page data (runs on server)
+├── blog/
+│   ├── +page.svelte        # blog list
+│   ├── +page.server.ts     # blog list data
+│   └── [slug]/
+│       ├── +page.svelte    # blog post
+│       └── +page.server.ts # blog post data
+└── api/
+    └── posts/
+        └── +server.ts      # API endpoint
+```
+
+| File | Runs On | Purpose |
+|------|---------|---------|
+| `+page.server.ts` → `load()` | Server only | Fetch data, access DB, read secrets |
+| `+page.ts` → `load()` | Server + client | Universal data loading (no secrets) |
+| `+page.svelte` | Client (hydrated) | Render UI with loaded data |
+| `+server.ts` | Server only | API endpoints (GET, POST, PUT, DELETE) |
+| `+layout.server.ts` | Server only | Shared layout data (auth, user session) |
+
+### Form Actions
+
+```typescript
+// +page.server.ts
+export const actions = {
+  create: async ({ request, locals }) => {
+    const data = await request.formData();
+    const title = data.get('title');
+
+    if (!title) {
+      return fail(400, { title, missing: true });
+    }
+
+    await db.posts.create({ data: { title, author: locals.user.id } });
+    redirect(303, '/blog');
+  }
+};
+```
+
+```svelte
+<!-- +page.svelte -->
+<script>
+  import { enhance } from '$app/forms';
+  let { form } = $props();
+</script>
+
+<form method="POST" action="?/create" use:enhance>
+  <input name="title" value={form?.title ?? ''} />
+  {#if form?.missing}<p class="error">Title required</p>{/if}
+  <button>Create</button>
+</form>
+```
+
+Rules:
+- Always use `+page.server.ts` for data that requires secrets, DB access, or auth checks.
+- Use form actions for mutations — progressive enhancement works without JavaScript.
+- Validate server-side in form actions — client validation is UX, not security.
+- Use `redirect()` and `error()` from `@sveltejs/kit`, not manual response construction.
+- Use `$app/stores` sparingly in Svelte 5 — prefer `$props()` data flow from `load()`.
+
+### SvelteKit Adapters
+
+| Adapter | Target | Install |
+|---------|--------|---------|
+| `@sveltejs/adapter-auto` | Auto-detect (Vercel, Netlify, Cloudflare) | Default — included in new projects |
+| `@sveltejs/adapter-node` | Node.js server (Docker, VPS) | `npm i -D @sveltejs/adapter-node` |
+| `@sveltejs/adapter-static` | Static site (GitHub Pages, S3) | `npm i -D @sveltejs/adapter-static` |
+| `@sveltejs/adapter-vercel` | Vercel (edge/serverless) | `npm i -D @sveltejs/adapter-vercel` |
+| `@sveltejs/adapter-cloudflare` | Cloudflare Workers/Pages | `npm i -D @sveltejs/adapter-cloudflare` |
+
+### Performance Characteristics
+
+| Metric | Svelte 5 | React 19 | Vue 3.5 |
+|--------|----------|----------|---------|
+| Bundle size (hello world) | ~2 KB | ~45 KB | ~30 KB |
+| Reactivity model | Compile-time (runes) | Runtime (fiber + hooks) | Runtime (proxy) |
+| Virtual DOM | No — direct DOM updates | Yes | Yes |
+| SSR streaming | SvelteKit `+page.server.ts` | React Server Components | Nuxt `useAsyncData` |
+| Built-in transitions | Yes (`svelte/transition`) | No (need library) | Yes (`<Transition>`) |
+| Scoped CSS | Default (`<style>`) | No (need CSS modules/Tailwind) | Default (`<style scoped>`) |
+
+## 3. Component Patterns
+
+### Snippets (Svelte 5 — replaces slots)
+
+```svelte
+<!-- Parent -->
+<Card>
+  {#snippet header()}
+    <h2>Title</h2>
+  {/snippet}
+  {#snippet footer()}
+    <button>Action</button>
+  {/snippet}
+  <p>Default content</p>
+</Card>
+
+<!-- Card.svelte -->
+<script>
+  let { header, footer, children } = $props();
+</script>
+
+<div class="card">
+  {#if header}{@render header()}{/if}
+  {@render children()}
+  {#if footer}{@render footer()}{/if}
+</div>
+```
+
+### Transitions & Animations
+
+```svelte
+<script>
+  import { fly, fade } from 'svelte/transition';
+  import { flip } from 'svelte/animate';
+
+  let items = $state([]);
+</script>
+
+{#each items as item (item.id)}
+  <div
+    animate:flip={{ duration: 300 }}
+    in:fly={{ y: 20, duration: 200 }}
+    out:fade={{ duration: 150 }}
+  >
+    {item.name}
+  </div>
+{/each}
+```
+
+Rules:
+- Use Snippets instead of slots — slots are deprecated in Svelte 5.
+- Use `{@render}` for snippet rendering, not `<svelte:component>`.
+- Scoped `<style>` is default — use `:global()` only when intentionally escaping scope.
+- Prefer CSS transitions for simple effects; use Svelte transitions for enter/exit/list animations.
+- Always provide `(key)` in `{#each}` blocks for stable identity.
+
+## 4. Migration from Svelte 4
+
+| Svelte 4 | Svelte 5 | Migration |
+|----------|----------|-----------|
+| `export let prop` | `let { prop } = $props()` | Destructure from `$props()` |
+| `$: derived = x * 2` | `let derived = $derived(x * 2)` | Wrap in `$derived()` |
+| `$: { sideEffect() }` | `$effect(() => { sideEffect() })` | Wrap in `$effect()` |
+| `<slot />` | `{@render children()}` | Replace slots with snippets |
+| `<slot name="x" />` | `{@render x()}` | Named slots → named snippets |
+| `$$props` / `$$restProps` | `let { ...rest } = $props()` | Destructure with rest |
+| Writable stores | `$state()` in `.svelte.ts` | Move to Rune-based state |
+| `createEventDispatcher()` | Callback props | Pass functions via `$props()` |
+
+```bash
+# Automated migration (partial — review output manually)
+npx svelte-migrate svelte-5
+```
+
+Rules:
+- Migrate one component at a time — Svelte 5 components can coexist with Svelte 4 in the same project.
+- Test each migrated component individually before proceeding.
+- Stores in `.js`/`.ts` files still work — migrate to `.svelte.ts` Rune-based state when touching the file.
+- `createEventDispatcher` → callback props is the biggest behavioral change; verify all event consumers.
+
+## 5. Anti-Patterns
+
+| Banned | Symptom | Fix |
+|--------|---------|-----|
+| `$effect()` for derived values | Unnecessary re-runs, stale value bugs | Use `$derived()` instead |
+| Missing `(key)` in `{#each}` | Animation glitches, wrong element updates | Always provide a stable key |
+| `$$props` in Svelte 5 | Deprecated, loses type safety | Destructure from `$props()` |
+| Bare `let` expecting reactivity | Value does not update in template | Use `$state()` for reactive values |
+| `on:click` syntax in Svelte 5 | Deprecated event directive | Use `onclick` attribute |
+
+## Pre-flight
+
+- [ ] All reactive state uses `$state()`, not bare `let`
+- [ ] Computed values use `$derived()`, not `$effect()`
+- [ ] Components use `$props()` destructuring, not `export let`
+- [ ] `{#each}` blocks have stable keys
+- [ ] Server-only data in `+page.server.ts`, not `+page.ts`
+- [ ] Form actions validate server-side
+- [ ] Slots migrated to Snippets (`{@render}`) in new/updated components