@polymorphism-tech/morph-spec 9.4.0 → 9.5.0

package/framework/standards/STANDARDS.json

@@ -1211,26 +1211,7 @@
         "tokens": "#stagger--timing",
         "principles": "#css-animation-patterns"
       },
-      "digest": "CSS animation library for design-system.css: keyframes (fadeIn/Out, slideIn Up/Down/Left/Right, scaleIn, bounce, pulse, spin, shimmer) exposed as `.animate-*` classes (0.3s fade/scale, 0.5s slides; bounce 1s, pulse 2s, spin 1s infinite) plus `.duration-fast/normal/slow` (150/300/500ms), `.stagger-1..10` (0.1s steps) and `.ease-bounce`. For staggered lists set `animation-delay` AND `animation-fill-mode: backwards` (marked CRITICAL: otherwise elements flash before the delay). Skeletons use `.shimmer` (1.5s infinite). Hover/focus transitions run 0.15s to 0.3s. Always include the `@media (prefers-reduced-motion: reduce)` block (0.01ms durations, one iteration). Beyond CSS: Motion (formerly Framer Motion) for simple enter/exit, layout and gesture transitions (`frontend/nextjs/motion-patterns.md`); GSAP for ScrollTrigger, SVG morph, timelines (`frontend/gsap/gsap-core.md`)."
-    },
-    {
-      "id": "frontend-design-system-naming",
-      "name": "naming",
-      "path": "frontend/design-system/naming.md",
-      "category": "frontend",
-      "subcategory": "design-system",
-      "tags": [
-        "frontend",
-        "design-system"
-      ],
-      "stacks": [
-        "*"
-      ],
-      "anchors": {
-        "blocks": "#bem-for-reusable-components",
-        "tokens": "#css-variables-with-namespace"
-      },
-      "digest": "CSS naming rests on four principles: a page prefix prevents conflicts, BEM for components gives clear hierarchy, namespaced variables avoid library collisions, and state suffixes keep modifiers consistent. Page-specific elements take the page name as prefix (.home-hero, .checkout-form, .dashboard-stats, .auth-form); reusable components use BEM: block .card, element .card__header, modifier .card--featured. Rule: BEM for reusable components, page prefix for page-specific elements. Custom properties go in :root under the --app- namespace (--app-primary, --app-spacing-md, --app-font-heading). State modifiers use fixed suffixes: --active, --disabled, --loading, --error (.button, .button--active, .button--disabled)."
+      "digest": "CSS animation library for design-system.css (keyframes and the `.animate-*`/`.stagger-*` utility classes live in the file, not in a rule). For staggered lists set `animation-delay` AND `animation-fill-mode: backwards` (marked CRITICAL: otherwise elements flash before the delay). Always include the `@media (prefers-reduced-motion: reduce)` block (0.01ms durations, one iteration). Beyond CSS: Motion (formerly Framer Motion) for simple enter/exit, layout and gesture transitions (`frontend/nextjs/motion-patterns.md`); GSAP for ScrollTrigger, SVG morph, timelines (`frontend/gsap/gsap-core.md`)."
     },
     {
       "id": "frontend-design-system-premium-finish",
@@ -1341,7 +1322,7 @@
         "layout": "#root-layout--required-providers",
         "routing": "#app-directory-structure"
       },
-      "digest": "Next.js 15 App Router, TypeScript only (no .js/.jsx). Server Components by default; add `'use client'` only for interaction (onClick, useState/useEffect/useRef), browser APIs, TanStack Query hooks and interactive shadcn/ui. `app/` is for routing only: business logic goes to `features/`, never in `page.tsx`. Never fetch data in a Client Component when a Server Component can, and never fetch in `useEffect`: use a Server Component or TanStack Query. Co-locate `loading.tsx` and `error.tsx` (`error.tsx` must be a Client Component) beside `page.tsx`. Server Components call the .NET backend directly using the dedicated `BACKEND_API_PREFIX` from `@/lib/api/prefixes`, never the same-origin proxy prefix used by Client Components; always check `res.ok`. Avoid `route.ts` API routes (use the .NET API). The root `layout.tsx` wraps children in `QueryProvider` and the sonner `Toaster`."
+      "digest": "Next.js 15 App Router, TypeScript only (no .js/.jsx). Server Components by default; add `'use client'` only for interaction (onClick, useState/useEffect/useRef), browser APIs, TanStack Query hooks and interactive shadcn/ui. `app/` is for routing only: business logic goes to `features/`, never in `page.tsx`. Never fetch data in a Client Component when a Server Component can,. Co-locate `loading.tsx` and `error.tsx` beside `page.tsx`. Server Components call the .NET backend directly using the dedicated `BACKEND_API_PREFIX` from `@/lib/api/prefixes`, never the same-origin proxy prefix used by Client Components; always check `res.ok`. Avoid `route.ts` API routes (use the .NET API). The root `layout.tsx` wraps children in `QueryProvider` and the sonner `Toaster`. Fetch in `useEffect` and `'use client'` in the root layout are lint errors (frontend-nextjs-lint)."
     },
     {
       "id": "frontend-nextjs-components",
@@ -1360,7 +1341,7 @@
         "patterns": "#three-tier-hierarchy",
         "shadcn": "#tier-1--shadcnui-primitives"
       },
-      "digest": "Three tiers (Next.js 16 + shadcn 4 CLI): `components/ui/` is shadcn CLI output (add via `npx shadcn@latest add`, NEVER edit because the CLI regenerates it; wrap it in `components/` instead); `components/` holds shared composed components with no business logic and NEVER imports from `features/`; `features/*/components/` is feature-scoped and may know the domain. Add `'use client'` only if the component uses hooks, events or browser APIs (not on every component: unnecessary client JS). Never pass raw API/fetch data as props: transform it into typed props and validate with Zod first. Props interfaces always accept an optional `className` for Tailwind override. The shared data table is specified once in `admin-app/data-table.md`: do not write a second `components/data-table.tsx`; a feature list is a Tier 3 component that owns the columns and the URL-to-table mapping."
+      "digest": "Three tiers (Next.js 16 + shadcn 4 CLI): `components/ui/` is shadcn CLI output (add via `npx shadcn@latest add`, NEVER edit because the CLI regenerates it; wrap it in `components/` instead); `components/` holds shared composed components with no business logic (importing `features/` is a lint error, frontend-nextjs-lint); `features/*/components/` is feature-scoped and may know the domain. Add `'use client'` only if the component uses hooks, events or browser APIs (not on every component: unnecessary client JS). Never pass raw API/fetch data as props: the feature maps it to typed props. The shared data table is specified once in `admin-app/data-table.md`: do not write a second `components/data-table.tsx`; a feature list is a Tier 3 component that owns the columns and the URL-to-table mapping."
     },
     {
       "id": "frontend-nextjs-data-fetching",
@@ -1379,7 +1360,7 @@
         "server": "#server-component--tanstack-query-handoff",
         "client": "#usequery-hook-pattern"
       },
-      "digest": "Server Components do the initial load and call the .NET backend directly with BACKEND_API_PREFIX; Client Components never call the backend — they hit a same-origin proxy route with PROXY_API_PREFIX. Two named constants, never one shared API_PREFIX: the side that drifts breaks silently at runtime. Client data is TanStack Query 5: useQuery for reads, useMutation for writes, then invalidateQueries({ queryKey: userKeys.lists() }) (object syntax). Keys come from a per-feature key factory, never hardcoded ['users']. Every response is parsed with a Zod schema. QueryClient: staleTime 60s, retry 1, created once in useState; the Server Component passes initialData to the client hook. FORBIDDEN: useEffect(() => fetch…, []) and fetching a whole collection to page/sort/filter in the browser — page on the server, query in the URL."
+      "digest": "Server Components do the initial load and call the .NET backend directly with BACKEND_API_PREFIX; Client Components never call the backend — they hit a same-origin proxy route with PROXY_API_PREFIX. Two named constants, never one shared API_PREFIX: the side that drifts breaks silently at runtime. Client data is TanStack Query 5: useQuery for reads, useMutation for writes, then invalidateQueries({ queryKey: userKeys.lists() }) (object syntax). Keys come from a per-feature key factory, never hardcoded ['users']. Every response is parsed with a Zod schema. QueryClient is created once in useState; the Server Component passes initialData to the client hook. FORBIDDEN: fetching a whole collection to page/sort/filter in the browser — page on the server, query in the URL. Fetch in useEffect and a DB driver in Next are lint errors (frontend-nextjs-lint)."
     },
     {
       "id": "frontend-nextjs-forms",
@@ -1420,7 +1401,7 @@
         "scroll": "#section-3-scroll-animations",
         "accessibility": "#section-7-wcag-accessibility-mandatory"
       },
-      "digest": "Component-level motion with Motion for React (the stack table's 'Framer Motion', its former name; motion 12+, current npm major 14): npm install motion and import from 'motion/react'. framer-motion is not deprecated (motion depends on it and re-exports it), but a codebase keeps one import path, motion/react, and never adds framer-motion alongside it. Variants live in motion/variants.ts (fadeIn, slideInUp/Down/Left/Right, scaleIn, staggerContainer, staggerItem, pageTransition) and take durations and easings from @/lib/design-tokens (fast 0.15, base 0.3); never hardcode duration numbers or easing arrays. Scroll reveals: whileInView with viewport once: true for simple cases, useInView for control. Page transitions: AnimatePresence mode='wait' keyed by usePathname(), subtle (y: 8), inside a 'use client' PageTransition provider -- the root app/layout.tsx stays a Server Component (no 'use client', keeps metadata) and just renders the provider. WCAG is mandatory: useReducedMotion() strips x/y/scale and keeps opacity, plus a prefers-reduced-motion CSS fallback. Skeletons use CSS animate-pulse, not motion. Limit motion to 3-5 moments per page. Scroll-driven scenes (ScrollTrigger, Lenis) belong to GSAP; never share an element with it."
+      "digest": "Component-level motion with Motion for React (the stack table's 'Framer Motion', its former name; motion 12+, current npm major 14): npm install motion and import from 'motion/react'. framer-motion is not deprecated (motion depends on it and re-exports it), but a codebase keeps one import path, motion/react (a framer-motion import is a lint error, frontend-nextjs-lint). Variants live in motion/variants.ts (fadeIn, slideInUp/Down/Left/Right, scaleIn, staggerContainer, staggerItem, pageTransition) and take durations and easings from @/lib/design-tokens (fast 0.15, base 0.3); never hardcode duration numbers or easing arrays. Scroll reveals: whileInView with viewport once: true for simple cases, useInView for control. Page transitions: AnimatePresence mode='wait' keyed by usePathname(), inside a 'use client' PageTransition provider -- the root app/layout.tsx stays a Server Component (no 'use client', keeps metadata) and just renders the provider. WCAG is mandatory: useReducedMotion() strips x/y/scale and keeps opacity, plus a prefers-reduced-motion CSS fallback. Scroll-driven scenes (ScrollTrigger, Lenis) belong to GSAP; never share an element with it."
     },
     {
       "id": "frontend-nextjs-naming-conventions",
@@ -1439,7 +1420,7 @@
         "files": "#complete-reference-table",
         "components": "#complete-reference-table"
       },
-      "digest": "Next.js naming (prevents Linux case-sensitivity bugs). File names are ALWAYS kebab-case (`user-card.tsx`, never `UserCard.tsx`); exports are PascalCase for components (`UserCard`) and camelCase with a `use` prefix for hooks, whose files are kebab-case too (`use-users.ts` -> `useUsers`, `use-user.ts` for a single GET, `use-create-user.ts`, `use-update-user.ts`, `use-delete-user.ts`). Zod schema files end in `.schemas.ts` (`createUserSchema`) and type files in `.types.ts`, with types derived via `z.infer` instead of hand-written duplicates. Components use named exports (`export function UserCard`, not `export default`); `page.tsx` exports `default`. A feature `index.ts` re-exports. Never mix cases within a category (no `UserCard.tsx` next to `user-profile.tsx`)."
+      "digest": "Next.js naming (prevents Linux case-sensitivity bugs). File names are ALWAYS kebab-case (`user-card.tsx`, never `UserCard.tsx`); components export PascalCase (`UserCard`); hook files are kebab-case too (`use-users.ts` -> `useUsers`, `use-user.ts` for a single GET, `use-create-user.ts`, `use-update-user.ts`, `use-delete-user.ts`). Zod schema files end in `.schemas.ts` (`createUserSchema`) and type files in `.types.ts`, with types derived via `z.infer` instead of hand-written duplicates. A feature `index.ts` re-exports. Named exports and the hook `use` prefix are lint errors, not prose (frontend-nextjs-lint). Never mix cases within a category (no `UserCard.tsx` next to `user-profile.tsx`)."
     },
     {
       "id": "frontend-nextjs-nextjs-patterns",
@@ -1458,7 +1439,7 @@
         "auth": "#route-handlers-bff-pattern",
         "caching": "#react-query--neon"
       },
-      "digest": "Next.js 15 App Router (not Pages Router): Server Components by default, `'use client'` only for state, effects, events or browser APIs; colocate `loading.tsx` and `error.tsx` (the latter MUST be `'use client'`) with `page.tsx`. Route Handlers act as a BFF: check `auth.getSession()` (401 if absent) and delegate to the .NET API; database access lives in the .NET backend via EF Core, NEVER in Next.js route handlers. Validate input with Zod on client and server (`safeParse`, 400). Fetch with TanStack Query (`useQuery`/`useMutation`, `staleTime: 60_000`, `retry: 1`, `invalidateQueries` on success), never `useEffect` for data fetching. Forms: react-hook-form + `zodResolver`. shadcn is copied via `npx shadcn@latest add`, not an npm dependency. Keep `\"strict\": true` plus `noUncheckedIndexedAccess` (agents self-correct from compiler errors); no `any` for API responses (Zod schema + `z.infer`)."
+      "digest": "Next.js 15 App Router (not Pages Router): Server Components by default, `'use client'` only for state, effects, events or browser APIs; colocate `loading.tsx` and `error.tsx` with `page.tsx`. Route Handlers act as a BFF: check `auth.getSession()` (401 if absent) and delegate to the .NET API; database access lives in the .NET backend via EF Core (a DB driver in Next is a lint error, frontend-nextjs-lint). Validate input with Zod on client and server (`safeParse`, 400). Fetch with TanStack Query (`useQuery`/`useMutation`, `invalidateQueries` on success). Forms: react-hook-form + `zodResolver`. shadcn is copied via `npx shadcn@latest add`, not an npm dependency. Keep `\"strict\": true` plus `noUncheckedIndexedAccess` (agents self-correct from compiler errors); API responses are a Zod schema + `z.infer`."
     },
     {
       "id": "frontend-nextjs-project-structure",
@@ -1477,7 +1458,7 @@
         "structure": "#canonical-folder-tree",
         "organization": "#feature-index-pattern"
       },
-      "digest": "Next.js 15 App Router, src/ layout with the @/ alias, feature-based. src/app/ is routing only (layout, page, loading, error) and imports from features/, never the reverse. Each src/features/{feature-name}/ holds components/, hooks/ (TanStack Query hooks such as use-users.ts, use-create-user.ts), types/ (*.types.ts plus *.schemas.ts with Zod and z.infer) and an index.ts that is the explicit public API: import from '@/features/users', never from deep paths. NEVER import one feature from another (extract to components/ or lib/); components/ must not import features/, is presentation only with NO business logic, and components/ui/ is shadcn, never edited directly. Shared hooks/ make no API calls. lib/ holds api-client.ts (typed fetch wrapper for the .NET API) and query-client.tsx; types/api.ts has PaginatedResponse<T> and ApiError; env.mjs validates env vars with Zod."
+      "digest": "Next.js 15 App Router, src/ layout with the @/ alias, feature-based. src/app/ is routing only (layout, page, loading, error); screen logic lives in features/. Each src/features/{feature-name}/ holds components/, hooks/ (TanStack Query hooks such as use-users.ts, use-create-user.ts), types/ (*.types.ts plus *.schemas.ts with Zod and z.infer) and an index.ts that is the explicit public API. NEVER import one feature from another (extract to components/ or lib/); components/ is presentation only with NO business logic, and components/ui/ is shadcn, never edited directly. Deep imports from outside a feature, components/ -> features/, features/ -> app/ and shared hooks/ -> the API client are lint errors (frontend-nextjs-lint). lib/ holds api-client.ts (typed fetch wrapper for the .NET API) and query-client.tsx; types/api.ts has PaginatedResponse<T> and ApiError; env.mjs validates env vars with Zod."
     },
     {
       "id": "frontend-nextjs-state-management",
@@ -1496,7 +1477,7 @@
         "patterns": "#state-decision-tree",
         "server": "#server-state-tanstack-query"
       },
-      "digest": "Server state (anything from the .NET API) lives in TanStack Query, never copied into `useState` via `useEffect`; derive state from server data instead of syncing it. Local UI state (modal open, form step, selected id) uses `useState`. A list's page, sort and filters, and a page's active tab, go in the URL (`searchParams`), never `useState`, so a refresh or shared link reopens the same view. Do not use React Context for server state (no caching or dedup); Context is for truly global theme, auth user or locale, and prop drilling 2-3 levels is fine. NEVER install Zustand or Redux before exhausting Server Components + TanStack Query. Zustand is justified only if ALL hold: state needed in 5+ unrelated components, complex update logic, Context causes measurable re-render problems, and the state is not from the server."
+      "digest": "Server state (anything from the .NET API) lives in TanStack Query, never copied into `useState` via `useEffect`; derive state from server data instead of syncing it. Local UI state (modal open, form step, selected id) uses `useState`. A list's page, sort and filters, and a page's active tab, go in the URL (`searchParams`), never `useState`, so a refresh or shared link reopens the same view. Do not use React Context for server state (no caching or dedup); Context is for truly global theme, auth user or locale. Zustand/Redux imports are lint errors (frontend-nextjs-lint); the one exception is an eslint-disable-next-line with the reason in a single store file, only if ALL hold: state needed in 5+ unrelated components, complex update logic, Context causes measurable re-render problems, and the state is not from the server."
     },
     {
       "id": "frontend-nextjs-testing",
@@ -1830,7 +1811,7 @@
         "not-worth": "#o-que-não-merece",
         "size": "#tamanho"
       },
-      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and plan.md (## Decisões); in a test the link to the postcondition goes in the test NAME), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, a block over 3 lines or a doc-comment outside a published package; the verify validators node (code-budget) warns on added comments that cite process and on added comment density."
+      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and plan.md (## Decisões); in a test the link to the postcondition goes in the test NAME), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, commented-out code, a block over 3 lines or a doc-comment outside a published package; the verify validators node (code-budget) warns on added comments that cite process and on added comment density."
     },
     {
       "id": "ai-agents-tool-adapters",
@@ -1926,6 +1907,28 @@
         "not-a-rule": "#o-que-não-é-regra"
       },
       "digest": "Rules with a reason that must never break are build errors, not prose: three files at the solution root, no .csproj change. Directory.Build.props adds Microsoft.CodeAnalysis.BannedApiAnalyzers 5.6.0 (PrivateAssets=all), BannedSymbols.txt as AdditionalFiles and morph.globalconfig as GlobalAnalyzerConfigFiles (with Central Package Management the version goes to Directory.Packages.props). BannedSymbols.txt bans M:System.Guid.NewGuid (use Guid.CreateVersion7(): time-ordered, does not fragment the Postgres PK index). morph.globalconfig sets RS0030 and CA2016 (a CancellationToken received and not forwarded) to error. A new banned API is one BannedSymbols.txt line with the reason after the semicolon, never a prose rule. sealed, primary constructors, var, expression bodies and using order are taste: neither prose nor analyzer; follow the neighbouring file."
+    },
+    {
+      "id": "frontend-nextjs-lint",
+      "name": "lint",
+      "path": "frontend/nextjs/lint.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs",
+        "lint",
+        "eslint"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "anchors": {
+        "files": "#arquivos",
+        "rules": "#o-que-cada-regra-compra",
+        "not-a-rule": "#o-que-não-é-regra"
+      },
+      "digest": "Rules with a reason that a machine can see are lint errors, not prose: one eslint.config.mjs at the Next app root, flat config spreading eslint-config-next/core-web-vitals and eslint-config-next/typescript, no new plugin. ESLint 9 (eslint-plugin-import/react peer range; the bundled typescript-eslint wants TypeScript <6.1); Next 16 next build no longer lints; the verify build node runs eslint --quiet on the files the feature changed (legacy lint debt never reddens a feature), from the app root, when eslint.config.* and eslint are present. no-restricted-imports bans framer-motion (one import path, motion/react), zustand/redux/@reduxjs/toolkit (server state is TanStack Query, page and filters in the URL), DB drivers pg/@neondatabase/serverless/@prisma/client/drizzle-orm/postgres (Next never touches the database; the .NET API does), the legacy shadcn @/components/ui/form, and @/features/*/* deep imports outside src/features (use the feature index.ts). import/no-restricted-paths: src/components never imports src/features, src/features never imports src/app, src/hooks never imports the API client (lib/api-client.ts, lib/api). no-restricted-syntax: fetch or apiClient called inside useEffect, and 'use client' in the root app/layout.tsx. import/no-default-export except Next convention files (page, layout, loading, error, not-found, template, default, route, sitemap, robots, icons, OG images) and *.config.*. @typescript-eslint/no-explicit-any error, no-console warn. A new restriction is one line in this file with the reason in its message; a one-off exception is eslint-disable-next-line with the reason. CSS class naming, animation class catalogs, optional className, Zod on props, motion counts and offsets, QueryClient defaults and prop-drilling depth are taste: neither prose nor lint."
     }
   ]
 }

package/framework/standards/STANDARDS.meta.json

@@ -819,17 +819,6 @@
       "verifiedAgainst": "CSS animations/transitions (language-level, no framework).",
       "provedBy": []
     },
-    "frontend-design-system-naming": {
-      "aliases": [
-        "BEM",
-        "CSS naming",
-        "class naming",
-        "design token naming",
-        "component naming"
-      ],
-      "verifiedAgainst": "CSS (BEM + custom properties — language-level, no framework).",
-      "provedBy": []
-    },
     "frontend-design-system-premium-finish": {
       "aliases": [
         "premium finish",
@@ -1251,6 +1240,19 @@
       ],
       "verifiedAgainst": ".NET SDK 10.0.402, Microsoft.CodeAnalysis.BannedApiAnalyzers 5.6.0 (sonda: `Guid.NewGuid()` → erro RS0030, token não repassado → erro CA2016, código conforme → 0 erros).",
       "provedBy": []
+    },
+    "frontend-nextjs-lint": {
+      "aliases": [
+        "eslint",
+        "eslint.config.mjs",
+        "lint rule",
+        "no-restricted-imports",
+        "no-restricted-paths",
+        "eslint-config-next",
+        "default export"
+      ],
+      "verifiedAgainst": "eslint 9.39.5, eslint-config-next 16.4.2 (typescript-eslint 8.71.2, eslint-plugin-import 2.32.0), next 16.4.2, typescript 6.0.3 (sonda: um arquivo ruim por regra → erro da regra esperada, `no-console` → aviso, arquivos conformes e o scaffold `morph-spec scaffold nextjs` → 0 problemas).",
+      "provedBy": []
     }
   },
   "sharedAliases": {
@@ -1323,10 +1325,6 @@
       "architecture-vertical-slice-vertical-slice",
       "backend-dotnet-vsa-handler-patterns"
     ],
-    "component naming": [
-      "frontend-design-system-naming",
-      "frontend-nextjs-naming-conventions"
-    ],
     "video generation": [
       "ai-agents-media-video",
       "frontend-design-system-ai-video-generation"

package/framework/standards/architecture/code-comments.md

@@ -93,7 +93,7 @@ await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
 ## Na revisão
 
 Na hora da edição, o hook `comment-guard` bloqueia o comentário **adicionado** que é história de
-processo, banner/`#region`, bloco de mais de 3 linhas ou `///`/JSDoc em projeto que não é pacote
+processo, banner/`#region`, código comentado, bloco de mais de 3 linhas ou `///`/JSDoc em projeto que não é pacote
 publicado. Comentário que o arquivo já tinha nunca é acusado. Repetir o código em uma linha não é
 detectável por forma: fica com a revisão abaixo.
 

package/framework/standards/frontend/admin-app/data-table.md

@@ -82,9 +82,7 @@ The page parses the query, renders the toolbar, and wraps the results in a `Susp
 // app/(admin)/products/page.tsx
 import { Suspense } from 'react';
 import { DataTableSkeleton } from '@/components/data-table-skeleton';
-import { ProductResults } from '@/features/products/components/product-results';
-import { ProductToolbar } from '@/features/products/components/product-toolbar';
-import { productListQuerySchema } from '@/features/products/types/product-list.schemas';
+import { ProductResults, ProductToolbar, productListQuerySchema } from '@/features/products';
 
 export default async function ProductsPage({
   searchParams,

package/framework/standards/frontend/admin-app/page-structure.md

@@ -35,10 +35,14 @@ The page reads `tab` from `searchParams` and renders only that tab's content on
 
 ```tsx
 // app/(admin)/products/[id]/page.tsx
-import { ProductTabs, PRODUCT_TABS, type ProductTab } from '@/features/products/components/product-tabs';
-import { ProductDetailsTab } from '@/features/products/components/product-details-tab';
-import { ProductVariantsTab } from '@/features/products/components/product-variants-tab';
-import { ProductHistoryTab } from '@/features/products/components/product-history-tab';
+import {
+  PRODUCT_TABS,
+  ProductDetailsTab,
+  ProductHistoryTab,
+  ProductTabs,
+  ProductVariantsTab,
+  type ProductTab,
+} from '@/features/products';
 
 export default async function ProductPage({
   params,

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

@@ -16,9 +16,9 @@ Next.js App Router with TypeScript strict mode. Server Components by default, Cl
 - 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
+- Fetch inside `useEffect` and `'use client'` in the root `layout.tsx` are lint errors (`frontend-nextjs-lint`)
 
 ## Server vs Client Components
 
@@ -68,7 +68,7 @@ src/app/
 | `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** |
+| `error.tsx` | Error boundary | Client Component |
 | `not-found.tsx` | 404 page | Server Component |
 | `route.ts` | API route (avoid — use .NET API) | — |
 
@@ -80,7 +80,7 @@ the same-origin proxy prefix Client Components use. See `frontend/nextjs/data-fe
 
 ```tsx
 // app/(dashboard)/users/page.tsx
-import { UserList } from '@/features/users/components/user-list';
+import { UserList } from '@/features/users';
 import { BACKEND_API_PREFIX } from '@/lib/api/prefixes'; // server-direct prefix ONLY
 
 async function getUsers(): Promise<User[]> {
@@ -123,7 +123,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 | 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 |
 

package/framework/standards/frontend/nextjs/components.md

@@ -14,10 +14,10 @@ Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edi
 ## Core Rules
 
 - NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
-- NEVER import from `features/` inside `components/` — components know nothing about domain
 - ALWAYS compose shadcn primitives in `components/` instead of editing them
 - ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
 - NEVER pass raw API data directly to a component — transform to props first
+- `components/` importing `features/` and the legacy `@/components/ui/form` are lint errors (`frontend-nextjs-lint`)
 
 ## Three-Tier Hierarchy
 
@@ -89,26 +89,13 @@ export function UsersPageHeader({ canInvite }: { canInvite: boolean }) {
 
 A feature **list** is a Tier 3 component too: the feature owns the columns and the URL ⇄ table mapping, the shared table owns the rendering — `admin-app/data-table.md` → "The Feature Table".
 
-## Component Props Conventions
-
-```tsx
-interface UserCardProps {
-  user: User;
-  onEdit?: (id: string) => void;
-  className?: string; // Always allow className for Tailwind override
-}
-
-export function UserCard({ user, onEdit, className }: UserCardProps) {}
-```
-
 ## Common Mistakes
 
 | Wrong | Right | Why |
 |-------|-------|-----|
 | Edit `components/ui/button.tsx` | Wrap in `components/action-button.tsx` | shadcn CLI overwrites it |
-| `import { useUsers } from '@/features/users'` in `components/` | Move to a feature component | Breaks tier isolation |
 | `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
-| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
+| Pass raw fetch response as prop | Map it to typed props in the feature | The component stops depending on the API shape |
 
 ---
 

package/framework/standards/frontend/nextjs/data-fetching.md

@@ -9,16 +9,16 @@
 
 ---
 
-Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
+Server Components for initial page load. TanStack Query for client mutations and interactive data.
 
 ## Core Rules
 
 - ALWAYS use Server Components for initial data that doesn't require interactivity
 - ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
-- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
 - ALWAYS validate API responses with Zod before using them
 - ALWAYS use query key factories for consistent cache invalidation
 - NEVER fetch a whole collection to page, sort or filter it in the browser — a list is paged on the server, with the query in the URL (`admin-app/data-table.md`)
+- Fetch inside `useEffect` and a DB driver in Next are lint errors (`frontend-nextjs-lint`)
 
 ## TanStack Query Setup
 
@@ -134,7 +134,6 @@ export function UserListClient({ initialData }: { initialData: User[] }) {
 
 | Wrong | Right | Why |
 |-------|-------|-----|
-| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
 | No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
 | Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
 | `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |

package/framework/standards/frontend/nextjs/lint.md

@@ -0,0 +1,141 @@
+# ESLint Next.js — o lint cobra, a prosa não repete
+
+> **Scope:** nextjs
+> **Layer:** 0 (resumo injetado pela rule `nextjs-standards` (`**/*.ts`, `**/*.tsx`); o `stack-scan` acusa o projeto sem este arquivo)
+> **Keywords:** eslint, lint, eslint.config.mjs, no-restricted-imports, no-restricted-paths, no-restricted-syntax, no-default-export, no-explicit-any, framer-motion, zustand
+> **Load When:** projeto Next.js sem `eslint.config.mjs` com `no-restricted-imports`, ou o lint acusou uma destas regras
+
+**Verified against:** eslint 9.39.5, eslint-config-next 16.4.2 (typescript-eslint 8.71.2, eslint-plugin-import 2.32.0), next 16.4.2, typescript 6.0.3 (sonda: um arquivo ruim por regra → erro da regra esperada, `no-console` → aviso, arquivos conformes e o scaffold `morph-spec scaffold nextjs` → 0 problemas). Last-verified: 2026-10-18.
+
+---
+
+Regra de código que tem motivo e que uma máquina enxerga vira **erro de lint**, não frase que o
+agente relê a cada sessão. Um arquivo na raiz do app Next basta, e só usa o que o
+`eslint-config-next` já instala (typescript-eslint e eslint-plugin-import): nenhum plugin novo.
+
+## Arquivos
+
+Dependências (`npm i -D eslint@9 eslint-config-next typescript`). ESLint 9 é a faixa que
+`eslint-plugin-import` e `eslint-plugin-react` declaram como peer; o typescript-eslint do
+`eslint-config-next` pede TypeScript `<6.1`.
+
+No Next 16 o `next build` não roda mais o lint. O nó de build do `morph-spec verify` roda o
+eslint (`--quiet`: só erro reprova) **só nos arquivos que a feature mudou**, na raiz do app, quando
+acha `eslint.config.*` e o pacote `eslint` instalado: dívida de lint antiga nunca deixa a feature
+vermelha. As zonas são relativas a essa raiz.
+
+`eslint.config.mjs`:
+
+```js
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+const BANNED = [
+  [['framer-motion'], 'Motion entra por motion/react: um único caminho de import.'],
+  [['zustand', 'redux', '@reduxjs/toolkit'], 'Estado de servidor é do TanStack Query; página e filtro vão na URL.'],
+  [['pg', '@neondatabase/serverless', '@prisma/client', 'drizzle-orm', 'postgres'], 'O Next nunca fala com o banco: o dado vem da API .NET.'],
+]
+
+const DEEP_FEATURE = {
+  group: ['@/features/*/*'],
+  message: 'Fora da feature, importe a API pública (@/features/x), nunca um caminho interno.',
+}
+
+const restrictedImports = (...extraPatterns) => ['error', {
+  paths: [
+    ...BANNED.flatMap(([names, message]) => names.map((name) => ({ name, message }))),
+    { name: '@/components/ui/form', message: 'Form legado do shadcn: Controller + Field (frontend-nextjs-forms).' },
+  ],
+  patterns: [
+    ...BANNED.map(([names, message]) => ({ group: names.map((n) => `${n}/*`), message })),
+    ...extraPatterns,
+  ],
+}]
+
+const FETCH_IN_EFFECT = {
+  selector:
+    "CallExpression[callee.name='useEffect'] CallExpression:matches([callee.name='fetch'], [callee.name='apiClient'], [callee.object.name='apiClient'])",
+  message: 'Dado do servidor vem de Server Component ou TanStack Query, nunca de fetch em useEffect.',
+}
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
+  {
+    rules: {
+      'no-restricted-imports': restrictedImports(DEEP_FEATURE),
+      'import/no-restricted-paths': ['error', {
+        zones: [
+          { target: './src/components', from: './src/features', message: 'components/ é apresentação: não conhece feature.' },
+          { target: './src/features', from: './src/app', message: 'app/ importa de features/, nunca o contrário.' },
+          { target: './src/hooks', from: ['./src/lib/api-client.ts', './src/lib/api'], message: 'Hook compartilhado não chama API: isso é hook de feature.' },
+        ],
+      }],
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT],
+      'import/no-default-export': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      'no-console': 'warn',
+    },
+  },
+  {
+    files: ['src/features/**'],
+    rules: { 'no-restricted-imports': restrictedImports() },
+  },
+  {
+    files: ['app/layout.tsx', 'src/app/layout.tsx'],
+    rules: {
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT, {
+        selector: "Program > ExpressionStatement[directive='use client']",
+        message: "O layout raiz é Server Component (metadata): o 'use client' vai no provider que ele renderiza.",
+      }],
+    },
+  },
+  {
+    files: [
+      '**/app/**/{page,layout,loading,error,global-error,not-found,forbidden,unauthorized,template,default,route}.{ts,tsx}',
+      '**/app/**/{sitemap,robots,manifest,icon,apple-icon,opengraph-image,twitter-image}.{ts,tsx}',
+      '**/*.config.{js,mjs,cjs,ts}',
+    ],
+    rules: { 'import/no-default-export': 'off' },
+  },
+])
+```
+
+Cada override de `no-restricted-imports` e `no-restricted-syntax` substitui a lista inteira da
+regra naquele arquivo, por isso o bloco do layout repete `FETCH_IN_EFFECT` e o de `features/`
+repete os pacotes banidos.
+
+## O que cada regra compra
+
+| Regra | Bloqueia | Por quê |
+|---|---|---|
+| `no-restricted-imports` `@/features/*/*` (fora de `src/features/`) | `app/`, `components/` e `lib/` lendo arquivo interno de uma feature | o `index.ts` é a API pública: refatorar dentro da feature não quebra quem está fora |
+| `no-restricted-imports` `framer-motion` | o segundo caminho de import do Motion | `motion/react` e `framer-motion` juntos duplicam o runtime no bundle e dividem o código em duas APIs |
+| `no-restricted-imports` `zustand`, `redux`, `@reduxjs/toolkit` | store global | cópia do estado do servidor fica velha sem o cache do TanStack Query; página e filtro na URL sobrevivem a refresh e link |
+| `no-restricted-imports` `pg`, `@neondatabase/serverless`, `@prisma/client`, `drizzle-orm`, `postgres` | driver de banco no Next | regra de negócio e acesso a dados moram no .NET (EF Core); um segundo caminho ao banco pula a autorização dele |
+| `no-restricted-imports` `@/components/ui/form` | o `Form` legado do shadcn | a documentação do shadcn é escrita em `Controller` + `Field`; a tela legada migra quando é tocada |
+| `import/no-restricted-paths` `src/components` ↛ `src/features` | componente compartilhado que conhece domínio | ele deixa de ser compartilhável e cria ciclo feature → components → feature |
+| `import/no-restricted-paths` `src/features` ↛ `src/app` | feature importando rota | a dependência é de mão única: a rota compõe a feature |
+| `import/no-restricted-paths` `src/hooks` ↛ cliente da API | hook compartilhado chamando o backend | chamada à API é de feature, com a key factory dela; hook compartilhado é só de UI |
+| `no-restricted-syntax` fetch/`apiClient` dentro de `useEffect` | busca de dado no efeito | sem cache, sem dedup, corrida entre requisições e cascata de render; Server Component ou TanStack Query resolvem |
+| `no-restricted-syntax` `'use client'` em `app/layout.tsx` | layout raiz no cliente | perde `metadata` e manda a árvore inteira para o bundle do cliente |
+| `import/no-default-export` (exceto arquivos de rota e `*.config.*`) | `export default` em componente e hook | nome único em todo import: busca e rename acham todos os usos; o Next exige `default` só nos arquivos de convenção |
+| `@typescript-eslint/no-explicit-any` | `any` | desliga o tipo no ponto onde o dado da API entra; o certo é schema Zod + `z.infer` |
+| `no-console` (aviso) | `console.log` esquecido | ruído no console do usuário e dado vazando; aviso, porque o diagnóstico local é legítimo |
+
+Restrição nova entra como linha neste arquivo, com o porquê na `message`. Nunca uma regra nova
+em prosa. Exceção pontual é `// eslint-disable-next-line <regra> -- <motivo>` na linha, nunca o
+desligamento da regra no projeto.
+
+## O que não é regra
+
+Nome de classe CSS (BEM, prefixo de página, namespace `--app-`, sufixo de estado), catálogo de
+classes `.animate-*`/`.stagger-*`, `className` opcional em toda prop, Zod em props, quantos
+momentos de motion uma página tem, o deslocamento de uma transição, o skeleton com
+`animate-pulse`, os defaults de `staleTime`/`retry` do `QueryClient` e quantos níveis de prop
+drilling são aceitáveis são gosto: nem prosa nem lint. Siga o arquivo vizinho, e o formatter do
+projeto decide a forma. Também saíram da prosa o `'use client'` no `error.tsx` (o `next build`
+recusa sem ele) e o prefixo `use` do hook (o `react-hooks/rules-of-hooks` que vem no
+`eslint-config-next` acusa hook chamado fora de função `useX`).

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -221,14 +221,11 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 - `mode="wait"` ensures the exit animation completes before the entering page renders.
 - The `key` prop must change on navigation — use `usePathname()` from `next/navigation`.
-- Keep page transitions subtle (`y: 8`, fast duration) — aggressive transitions hurt perceived performance.
 
 ---
 
 ## Section 6: Loading Patterns
 
-Prefer CSS `animate-pulse` for skeleton loaders over Motion — CSS animations run off the main thread and have lower performance overhead.
-
 ```tsx
 // components/skeleton.tsx
 import { cn } from '@/lib/utils';
@@ -315,11 +312,8 @@ This CSS fallback catches animations outside Motion (Tailwind `animate-*`, third
 | `duration: 0.8` for UI interactions | `duration: durations.fast` (0.15) for micro-interactions |
 | Hardcoded easing `[0.4, 0, 0.2, 1]` | `ease: easings.standard` (from design-tokens) |
 | No `useReducedMotion()` check | Always check or use CSS media query |
-| Animating everything on the page | Reserve motion for 3-5 meaningful moments per page |
 | Forgetting `animation-fill-mode: backwards` in stagger | Will cause a flash before the animation starts |
 | `AnimatePresence` without `key` changes | Exit animations will never fire |
-| Using `motion` for skeleton loaders | Use CSS `animate-pulse` — lower performance cost |
-| `npm install framer-motion` / `import ... from 'framer-motion'` | `npm install motion` / `import ... from 'motion/react'` — same code underneath, but one import path per codebase |
 | Need ScrollTrigger, SVG morph, or complex timelines | Use GSAP — see `frontend/gsap/gsap-core.md` |
 
 ---
@@ -333,7 +327,8 @@ npm install motion
 > The package is `motion` and components import from `motion/react`. `framer-motion`
 > is not deprecated: it is published with the same version and `motion` depends on
 > it. New code still depends on `motion` and imports from `motion/react`, so the
-> codebase has a single import path; do not add `framer-motion` alongside it.
+> codebase has a single import path; a `framer-motion` import is a lint error
+> (`frontend-nextjs-lint`).
 
 Verify the installed version supports the features used here (requires motion >= 11; current major on npm is 14):
 

package/framework/standards/frontend/nextjs/naming-conventions.md

@@ -15,9 +15,9 @@ Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps th
 
 - ALWAYS use kebab-case for file names — never PascalCase or camelCase
 - ALWAYS use PascalCase for React component exports
-- ALWAYS use camelCase starting with `use` for hook exports
 - ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
 - NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
+- Named exports, the hook `use` prefix and `default` only in route files are lint errors (`frontend-nextjs-lint`), not rules to reread
 
 ## Complete Reference Table
 
@@ -63,7 +63,6 @@ export type UpdateUserInput = z.infer<typeof updateUserSchema>;
 |-------|-------|-----|
 | `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
 | `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
-| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
 | `type User = { id: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
 
 ---

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -16,7 +16,8 @@ Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 - ALWAYS use App Router (not Pages Router)
 - Default to Server Components -- add `'use client'` only when needed
 - ALWAYS colocate loading.tsx and error.tsx with page.tsx
-- NEVER call the database directly from client -- use Route Handlers as BFF
+- Route Handlers are a BFF that delegates to the .NET API
+- A DB driver, `any`, fetch inside `useEffect` and `'use client'` in the root layout are lint errors (`frontend-nextjs-lint`)
 - ALWAYS validate inputs with Zod on both client and server
 - Use TypeScript strict mode (`"strict": true`)
 
@@ -58,7 +59,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 // loading.tsx
 export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
 
-// error.tsx — MUST be 'use client'
+// error.tsx
 'use client';
 export default function Error({ error, reset }: { error: Error; reset: () => void }) {
   return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
@@ -187,7 +188,7 @@ export function DocumentForm() {
 
 ## shadcn/ui
 
-Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
+Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog field`.
 Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
 
 ## TypeScript Strict Patterns
@@ -195,7 +196,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Pattern | Approach |
 |---------|----------|
 | API responses | Zod schema + `z.infer<typeof schema>` |
-| Props | Explicit interface, no `any` |
+| Props | Explicit interface |
 | Event handlers | `React.ChangeEvent<HTMLInputElement>` |
 | Null safety | `?.` over type assertions, `if (!data) return null` |
 
@@ -204,10 +205,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
-| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
-| `any` for API responses | Zod schema + infer | No runtime safety |
 | Missing loading.tsx | Colocate with page.tsx | Blank page during load |
-| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |