@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/frontend/design-system/naming.md

@@ -1,64 +1,68 @@
-# CSS Naming Convention
-
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** css, bem, naming, class names, conventions
-> **Load When:** always
-
-## Principles
-
-1. **Page prefix** — Prevents conflicts
-2. **BEM for components** — Clear hierarchy
-3. **Namespaced variables** — No library collisions
-4. **State suffixes** — Consistent modifiers
-
----
-
-## Page Prefixes
-
-| Page | Example |
-|------|---------|
-| Home | `.home-hero`, `.home-features` |
-| Checkout | `.checkout-form`, `.checkout-summary` |
-| Dashboard | `.dashboard-stats`, `.dashboard-chart` |
-| Auth | `.auth-form`, `.auth-social-buttons` |
-
-## BEM for Reusable Components
-
-```css
-.card { }              /* Block */
-.card__header { }      /* Element */
-.card__body { }
-.card--featured { }    /* Modifier */
-```
-
-**Rule:** BEM for reusable components. Page prefix for page-specific elements.
-
-## CSS Variables with Namespace
-
-```css
-:root {
-  --app-primary: #007bff;
-  --app-spacing-md: 1rem;
-  --app-font-heading: 'Segoe UI', sans-serif;
-}
-```
-
-## State Suffixes
-
-| State | Suffix |
-|-------|--------|
-| Active | `--active` |
-| Disabled | `--disabled` |
-| Loading | `--loading` |
-| Error | `--error` |
-
-```css
-.button { }
-.button--active { }
-.button--disabled { }
-```
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# CSS Naming Convention
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** css, bem, naming, class names, conventions
+> **Load When:** always
+
+**Verified against:** CSS (BEM + custom properties — language-level, no framework). Last-verified: 2026-05-20.
+
+---
+
+## Principles
+
+1. **Page prefix** — Prevents conflicts
+2. **BEM for components** — Clear hierarchy
+3. **Namespaced variables** — No library collisions
+4. **State suffixes** — Consistent modifiers
+
+---
+
+## Page Prefixes
+
+| Page | Example |
+|------|---------|
+| Home | `.home-hero`, `.home-features` |
+| Checkout | `.checkout-form`, `.checkout-summary` |
+| Dashboard | `.dashboard-stats`, `.dashboard-chart` |
+| Auth | `.auth-form`, `.auth-social-buttons` |
+
+## BEM for Reusable Components
+
+```css
+.card { }              /* Block */
+.card__header { }      /* Element */
+.card__body { }
+.card--featured { }    /* Modifier */
+```
+
+**Rule:** BEM for reusable components. Page prefix for page-specific elements.
+
+## CSS Variables with Namespace
+
+```css
+:root {
+  --app-primary: #007bff;
+  --app-spacing-md: 1rem;
+  --app-font-heading: 'Segoe UI', sans-serif;
+}
+```
+
+## State Suffixes
+
+| State | Suffix |
+|-------|--------|
+| Active | `--active` |
+| Disabled | `--disabled` |
+| Loading | `--loading` |
+| Error | `--error` |
+
+```css
+.button { }
+.button--active { }
+.button--disabled { }
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/gsap/gsap-core.md

@@ -1,12 +1,14 @@
----
-scope: frontend-nextjs-ui
-layer: 3
-keywords: gsap, animation, timeline, tween, useGSAP, greensock, transform
-load_when: gsap-animator active
----
-
 # GSAP Core & React Integration
 
+> **Scope:** frontend-nextjs-ui
+> **Layer:** 3
+> **Keywords:** gsap, animation, timeline, tween, useGSAP, greensock, transform
+> **Load When:** gsap-animator active
+
+**Verified against:** GSAP 3.13 + @gsap/react. Last-verified: 2026-05-20.
+
+---
+
 Reference guide for implementing animations in Next.js projects using GSAP and the official @gsap/react bindings. Covers core APIs, React integration via useGSAP, timeline sequencing, utility functions, performance, accessibility, and the decision boundary with Framer Motion.
 
 ---
@@ -33,7 +35,11 @@ Reference guide for implementing animations in Next.js projects using GSAP and t
 npm install gsap @gsap/react
 ```
 
-GSAP 3.12+ includes Flip, Observer, and ScrollToPlugin for free. Premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin) require a Club GreenSock license — install via `gsap@npm:@gsap/shockingly`.
+Since the Webflow acquisition, **GSAP and every plugin are free for commercial
+use**. The public `gsap` package includes Flip, Observer, ScrollToPlugin, and the
+formerly-premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath, Draggable,
+InertiaPlugin) — no Club GreenSock membership or private registry needed. See
+`gsap-plugins.md` for the per-plugin API.
 
 ### Plugin Registration
 

package/framework/standards/frontend/gsap/gsap-plugins.md

@@ -1,28 +1,33 @@
----
-scope: frontend-nextjs-gsap
-layer: 3
-keywords: flip, splittext, morphsvg, drawsvg, motionpath, draggable, observer, scrollto, gsap-plugins
-load_when: gsap-animator active
----
-
 # GSAP Plugins
 
-Reference guide for GSAP's plugin ecosystem in Next.js. Covers free plugins (Flip, Observer, ScrollToPlugin) and Club GreenSock premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin).
+> **Scope:** frontend-nextjs-gsap
+> **Layer:** 3
+> **Keywords:** flip, splittext, morphsvg, drawsvg, motionpath, draggable, observer, scrollto, gsap-plugins
+> **Load When:** gsap-animator active
 
-## Plugin Registration & Licensing
+**Verified against:** GSAP 3.13 + @gsap/react. Last-verified: 2026-05-20.
+
+---
 
-Free plugins (included in gsap 3.12+): Flip, Observer, ScrollToPlugin
+Reference guide for GSAP's plugin ecosystem in Next.js. Covers the full plugin set — Flip, Observer, ScrollToPlugin, SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin.
 
-Premium (Club GreenSock): SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin, ScrambleText, CustomEase, CustomWiggle, CustomBounce, Physics2D, PhysicsProps
+## Plugin Registration & Licensing
 
-```bash
-# Free plugins — included with gsap
-npm install gsap
+Since the Webflow acquisition, **GSAP and every plugin are free for commercial
+use** — no Club GreenSock membership, no license key, no auth token, no private
+registry. The formerly-premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath,
+Draggable, InertiaPlugin, ScrambleText, CustomEase, CustomWiggle, CustomBounce,
+Physics2D, PhysicsProps) now ship in the public `gsap` package alongside Flip,
+Observer, and ScrollToPlugin.
 
-# Premium plugins — requires Club GreenSock license
-npm install gsap@npm:@gsap/shockingly
+```bash
+# Everything — core + all plugins — installs from the public package
+npm install gsap @gsap/react
 ```
 
+> Disregard any older instruction to install `gsap@npm:@gsap/shockingly` or
+> configure a private npm registry — that path is obsolete.
+
 Registration pattern (do ONCE at app init):
 
 ```typescript
@@ -70,7 +75,7 @@ function FilterableGrid({ items, filter }: { items: Item[]; filter: string }) {
 
 Use cases: filterable grids, list reordering, expanding cards, shared element transitions.
 
-## SplitText (Premium)
+## SplitText
 
 Split text into chars, words, or lines for staggered reveals:
 
@@ -101,7 +106,7 @@ Key points:
 - The split creates `<div>` wrappers -- this affects layout. Test carefully.
 - useGSAP automatically reverts the split on unmount
 
-## MorphSVG (Premium)
+## MorphSVG
 
 Morph between SVG shapes:
 
@@ -125,7 +130,7 @@ Rules:
 - Match point counts for smoother morphs
 - `type: "rotational"` is smoother for most shapes
 
-## DrawSVG (Premium)
+## DrawSVG
 
 Animate SVG stroke drawing:
 
@@ -151,7 +156,7 @@ gsap.from(paths, {
 
 Requires SVG elements with visible `stroke` and `stroke-width`. Does not work on `fill`.
 
-## MotionPath (Premium)
+## MotionPath
 
 Animate elements along SVG paths:
 
@@ -192,7 +197,7 @@ gsap.to(window, {
 });
 ```
 
-## Draggable (Premium)
+## Draggable
 
 Make elements draggable with optional physics:
 

package/framework/standards/frontend/gsap/gsap-scrolltrigger.md

@@ -1,12 +1,14 @@
----
-scope: frontend-nextjs-gsap
-layer: 3
-keywords: scrolltrigger, scroll-animation, pinning, scrubbing, parallax, scroll-driven, gsap
-load_when: gsap-animator active
----
-
 # GSAP ScrollTrigger — Next.js
 
+> **Scope:** frontend-nextjs-gsap
+> **Layer:** 3
+> **Keywords:** scrolltrigger, scroll-animation, pinning, scrubbing, parallax, scroll-driven, gsap
+> **Load When:** gsap-animator active
+
+**Verified against:** GSAP 3.13 ScrollTrigger + @gsap/react. Last-verified: 2026-05-20.
+
+---
+
 Reference guide for implementing scroll-driven animations in Next.js projects using GSAP ScrollTrigger. Covers plugin setup, scrubbing, pinning, batch processing, responsive breakpoints, SSR considerations, and mandatory cleanup patterns.
 
 ---

package/framework/standards/frontend/nextjs/app-router.md

@@ -1,123 +1,127 @@
-# Next.js App Router Standard
-
-> **Scope:** frontend/nextjs/app-router
-> **Layer:** 2 (on keyword)
-> **Keywords:** next.js, app router, server component, client component, page, layout, route
-> **Load When:** editing files in `app/` or `features/` directories
-
-Next.js App Router with TypeScript strict mode. Server Components by default, Client Components only when interactivity is required.
-
-## Core Rules
-
-- ALWAYS default to Server Components — add `'use client'` only when needed
-- ALWAYS keep `app/` directory for routing only — no business logic in page files
-- NEVER put data fetching in Client Components when a Server Component can do it
-- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
-- ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
-- ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
-
-## Server vs Client Components
-
-| Use Server Component | Use Client Component |
-|---------------------|---------------------|
-| Fetching from .NET API on load | onClick, onChange, form submit |
-| Rendering static or user-specific data | useState, useEffect, useRef |
-| Accessing backend environment variables | Browser APIs (localStorage, geolocation) |
-| SEO-critical content | TanStack Query hooks |
-| No interactivity needed | shadcn/ui interactive components |
-
-## Decision Tree
-
-```
-Does this component need user interaction (click, input, hover state)?
-  YES → 'use client'
-  NO  → Does it fetch data?
-          YES → Server Component (fetch directly)
-          NO  → Server Component (static)
-```
-
-## App Directory Structure
-
-```
-src/app/
-├── (auth)/
-│   ├── login/
-│   │   └── page.tsx           # Server Component — renders login form
-│   └── register/
-│       └── page.tsx
-├── (dashboard)/
-│   ├── layout.tsx             # Shared layout for dashboard routes
-│   ├── page.tsx               # Dashboard home
-│   └── users/
-│       ├── page.tsx           # User list (Server Component)
-│       ├── [id]/
-│       │   └── page.tsx       # User detail
-│       ├── loading.tsx        # Suspense fallback
-│       └── error.tsx          # Error boundary
-└── layout.tsx                 # Root layout — providers, fonts, metadata
-```
-
-## File Conventions
-
-| File | Purpose | Type |
-|------|---------|------|
-| `page.tsx` | Route segment UI | Server Component (default) |
-| `layout.tsx` | Shared UI wrapper | Server Component |
-| `loading.tsx` | Suspense fallback | Server Component |
-| `error.tsx` | Error boundary | **Must be Client Component** |
-| `not-found.tsx` | 404 page | Server Component |
-| `route.ts` | API route (avoid — use .NET API) | — |
-
-## Server Component Data Fetch Pattern
-
-```tsx
-// app/(dashboard)/users/page.tsx
-import { UserList } from '@/features/users/components/user-list';
-
-async function getUsers(): Promise<User[]> {
-  const res = await fetch(`${process.env.API_URL}/api/users`, {
-    next: { revalidate: 60 },
-  });
-  if (!res.ok) throw new Error('Failed to fetch users');
-  return res.json();
-}
-
-export default async function UsersPage() {
-  const users = await getUsers();
-  return <UserList initialUsers={users} />;
-}
-```
-
-## Root Layout — Required Providers
-
-```tsx
-// app/layout.tsx
-import { QueryProvider } from '@/lib/query-client';
-import { Toaster } from '@/components/ui/sonner';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="pt-BR">
-      <body>
-        <QueryProvider>
-          {children}
-          <Toaster />
-        </QueryProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
-| `useEffect(() => { fetch(...) }, [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
-| Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
-| `fetch` without error handling | Always check `res.ok` | Silent failures in production |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Next.js App Router Standard
+
+> **Scope:** frontend/nextjs/app-router
+> **Layer:** 2 (on keyword)
+> **Keywords:** next.js, app router, server component, client component, page, layout, route
+> **Load When:** editing files in `app/` or `features/` directories
+
+**Verified against:** Next.js 15. Last-verified: 2026-05-20.
+
+---
+
+Next.js App Router with TypeScript strict mode. Server Components by default, Client Components only when interactivity is required.
+
+## Core Rules
+
+- ALWAYS default to Server Components — add `'use client'` only when needed
+- ALWAYS keep `app/` directory for routing only — no business logic in page files
+- NEVER put data fetching in Client Components when a Server Component can do it
+- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
+- ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
+- ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
+
+## Server vs Client Components
+
+| Use Server Component | Use Client Component |
+|---------------------|---------------------|
+| Fetching from .NET API on load | onClick, onChange, form submit |
+| Rendering static or user-specific data | useState, useEffect, useRef |
+| Accessing backend environment variables | Browser APIs (localStorage, geolocation) |
+| SEO-critical content | TanStack Query hooks |
+| No interactivity needed | shadcn/ui interactive components |
+
+## Decision Tree
+
+```
+Does this component need user interaction (click, input, hover state)?
+  YES → 'use client'
+  NO  → Does it fetch data?
+          YES → Server Component (fetch directly)
+          NO  → Server Component (static)
+```
+
+## App Directory Structure
+
+```
+src/app/
+├── (auth)/
+│   ├── login/
+│   │   └── page.tsx           # Server Component — renders login form
+│   └── register/
+│       └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx             # Shared layout for dashboard routes
+│   ├── page.tsx               # Dashboard home
+│   └── users/
+│       ├── page.tsx           # User list (Server Component)
+│       ├── [id]/
+│       │   └── page.tsx       # User detail
+│       ├── loading.tsx        # Suspense fallback
+│       └── error.tsx          # Error boundary
+└── layout.tsx                 # Root layout — providers, fonts, metadata
+```
+
+## File Conventions
+
+| File | Purpose | Type |
+|------|---------|------|
+| `page.tsx` | Route segment UI | Server Component (default) |
+| `layout.tsx` | Shared UI wrapper | Server Component |
+| `loading.tsx` | Suspense fallback | Server Component |
+| `error.tsx` | Error boundary | **Must be Client Component** |
+| `not-found.tsx` | 404 page | Server Component |
+| `route.ts` | API route (avoid — use .NET API) | — |
+
+## Server Component Data Fetch Pattern
+
+```tsx
+// app/(dashboard)/users/page.tsx
+import { UserList } from '@/features/users/components/user-list';
+
+async function getUsers(): Promise<User[]> {
+  const res = await fetch(`${process.env.API_URL}/api/users`, {
+    next: { revalidate: 60 },
+  });
+  if (!res.ok) throw new Error('Failed to fetch users');
+  return res.json();
+}
+
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialUsers={users} />;
+}
+```
+
+## Root Layout — Required Providers
+
+```tsx
+// app/layout.tsx
+import { QueryProvider } from '@/lib/query-client';
+import { Toaster } from '@/components/ui/sonner';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <QueryProvider>
+          {children}
+          <Toaster />
+        </QueryProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
+| `useEffect(() => { fetch(...) }, [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
+| Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
+| `fetch` without error handling | Always check `res.ok` | Silent failures in production |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*