create-apppaaaul 2.0.46 → 2.0.48

package/dist/templates/nextjs-ts-landing-prisma/project/.agents/skills/interface-design/references/principles.md

@@ -0,0 +1,235 @@
+# Core Craft Principles
+
+These apply regardless of design direction. This is the quality floor.
+
+---
+
+## Surface & Token Architecture
+
+Professional interfaces don't pick colors randomly — they build systems. Understanding this architecture is the difference between "looks okay" and "feels like a real product."
+
+### The Primitive Foundation
+
+Every color in your interface should trace back to a small set of primitives:
+
+- **Foreground** — text colors (primary, secondary, muted)
+- **Background** — surface colors (base, elevated, overlay)
+- **Border** — edge colors (default, subtle, strong)
+- **Brand** — your primary accent
+- **Semantic** — functional colors (destructive, warning, success)
+
+Don't invent new colors. Map everything to these primitives.
+
+### Surface Elevation Hierarchy
+
+Surfaces stack. A dropdown sits above a card which sits above the page. Build a numbered system:
+
+```
+Level 0: Base background (the app canvas)
+Level 1: Cards, panels (same visual plane as base)
+Level 2: Dropdowns, popovers (floating above)
+Level 3: Nested dropdowns, stacked overlays
+Level 4: Highest elevation (rare)
+```
+
+In dark mode, higher elevation = slightly lighter. In light mode, higher elevation = slightly lighter or uses shadow. The principle: **elevated surfaces need visual distinction from what's beneath them.**
+
+### The Subtlety Principle
+
+This is where most interfaces fail. Study Vercel, Supabase, Linear — their surfaces are **barely different** but still distinguishable. Their borders are **light but not invisible**.
+
+**For surfaces:** The difference between elevation levels should be subtle — a few percentage points of lightness, not dramatic jumps. In dark mode, surface-100 might be 7% lighter than base, surface-200 might be 9%, surface-300 might be 12%. You can barely see it, but you feel it.
+
+**For borders:** Borders should define regions without demanding attention. Use low opacity (0.05-0.12 alpha for dark mode, slightly higher for light). The border should disappear when you're not looking for it, but be findable when you need to understand the structure.
+
+**The test:** Squint at your interface. You should still perceive the hierarchy — what's above what, where regions begin and end. But no single border or surface should jump out at you. If borders are the first thing you notice, they're too strong. If you can't find where one region ends and another begins, they're too subtle.
+
+**Common AI mistakes to avoid:**
+- Borders that are too visible (1px solid gray instead of subtle rgba)
+- Surface jumps that are too dramatic (going from dark to light instead of dark to slightly-less-dark)
+- Using different hues for different surfaces (gray card on blue background)
+- Harsh dividers where subtle borders would do
+
+### Text Hierarchy via Tokens
+
+Don't just have "text" and "gray text." Build four levels:
+
+- **Primary** — default text, highest contrast
+- **Secondary** — supporting text, slightly muted
+- **Tertiary** — metadata, timestamps, less important
+- **Muted** — disabled, placeholder, lowest contrast
+
+Use all four consistently. If you're only using two, your hierarchy is too flat.
+
+### Border Progression
+
+Borders aren't binary. Build a scale:
+
+- **Default** — standard borders
+- **Subtle/Muted** — softer separation
+- **Strong** — emphasis, hover states
+- **Stronger** — maximum emphasis, focus rings
+
+Match border intensity to the importance of the boundary.
+
+### Dedicated Control Tokens
+
+Form controls (inputs, checkboxes, selects) have specific needs. Don't just reuse surface tokens — create dedicated ones:
+
+- **Control background** — often different from surface backgrounds
+- **Control border** — needs to feel interactive
+- **Control focus** — clear focus indication
+
+This separation lets you tune controls independently from layout surfaces.
+
+### Context-Aware Bases
+
+Different areas of your app might need different base surfaces:
+
+- **Marketing pages** — might use darker/richer backgrounds
+- **Dashboard/app** — might use neutral working backgrounds
+- **Sidebar** — might differ from main canvas
+
+The surface hierarchy works the same way — it just starts from a different base.
+
+### Alternative Backgrounds for Depth
+
+Beyond shadows, use contrasting backgrounds to create depth. An "alternative" or "inset" background makes content feel recessed. Useful for:
+
+- Empty states in data grids
+- Code blocks
+- Inset panels
+- Visual grouping without borders
+
+---
+
+## Spacing System
+
+Pick a base unit (4px and 8px are common) and use multiples throughout. The specific number matters less than consistency — every spacing value should be explainable as "X times the base unit."
+
+Build a scale for different contexts:
+- Micro spacing (icon gaps, tight element pairs)
+- Component spacing (within buttons, inputs, cards)
+- Section spacing (between related groups)
+- Major separation (between distinct sections)
+
+## Symmetrical Padding
+
+TLBR must match. If top padding is 16px, left/bottom/right must also be 16px. Exception: when content naturally creates visual balance.
+
+```css
+/* Good */
+padding: 16px;
+padding: 12px 16px; /* Only when horizontal needs more room */
+
+/* Bad */
+padding: 24px 16px 12px 16px;
+```
+
+## Border Radius Consistency
+
+Sharper corners feel technical, rounder corners feel friendly. Pick a scale that fits your product's personality and use it consistently.
+
+The key is having a system: small radius for inputs and buttons, medium for cards, large for modals or containers. Don't mix sharp and soft randomly — inconsistent radius is as jarring as inconsistent spacing.
+
+## Depth & Elevation Strategy
+
+Match your depth approach to your design direction. Choose ONE and commit:
+
+**Borders-only (flat)** — Clean, technical, dense. Works for utility-focused tools where information density matters more than visual lift. Linear, Raycast, and many developer tools use almost no shadows — just subtle borders to define regions.
+
+**Subtle single shadows** — Soft lift without complexity. A simple `0 1px 3px rgba(0,0,0,0.08)` can be enough. Works for approachable products that want gentle depth.
+
+**Layered shadows** — Rich, premium, dimensional. Multiple shadow layers create realistic depth. Stripe and Mercury use this approach. Best for cards that need to feel like physical objects.
+
+**Surface color shifts** — Background tints establish hierarchy without any shadows. A card at `#fff` on a `#f8fafc` background already feels elevated.
+
+```css
+/* Borders-only approach */
+--border: rgba(0, 0, 0, 0.08);
+--border-subtle: rgba(0, 0, 0, 0.05);
+border: 0.5px solid var(--border);
+
+/* Single shadow approach */
+--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+
+/* Layered shadow approach */
+--shadow-layered:
+  0 0 0 0.5px rgba(0, 0, 0, 0.05),
+  0 1px 2px rgba(0, 0, 0, 0.04),
+  0 2px 4px rgba(0, 0, 0, 0.03),
+  0 4px 8px rgba(0, 0, 0, 0.02);
+```
+
+## Card Layouts
+
+Monotonous card layouts are lazy design. A metric card doesn't have to look like a plan card doesn't have to look like a settings card.
+
+Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography.
+
+## Isolated Controls
+
+UI controls deserve container treatment. Date pickers, filters, dropdowns — these should feel like crafted objects.
+
+**Never use native form elements for styled UI.** Native `<select>`, `<input type="date">`, and similar elements render OS-native dropdowns that cannot be styled. Build custom components instead:
+
+- Custom select: trigger button + positioned dropdown menu
+- Custom date picker: input + calendar popover
+- Custom checkbox/radio: styled div with state management
+
+Custom select triggers must use `display: inline-flex` with `white-space: nowrap` to keep text and chevron icons on the same row.
+
+## Typography Hierarchy
+
+Build distinct levels that are visually distinguishable at a glance:
+
+- **Headlines** — heavier weight, tighter letter-spacing for presence
+- **Body** — comfortable weight for readability
+- **Labels/UI** — medium weight, works at smaller sizes
+- **Data** — often monospace, needs `tabular-nums` for alignment
+
+Don't rely on size alone. Combine size, weight, and letter-spacing to create clear hierarchy. If you squint and can't tell headline from body, the hierarchy is too weak.
+
+## Monospace for Data
+
+Numbers, IDs, codes, timestamps belong in monospace. Use `tabular-nums` for columnar alignment. Mono signals "this is data."
+
+## Iconography
+
+Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Choose a consistent icon set and stick with it throughout the product.
+
+Give standalone icons presence with subtle background containers. Icons next to text should align optically, not mathematically.
+
+## Animation
+
+Keep it fast and functional. Micro-interactions (hover, focus) should feel instant — around 150ms. Larger transitions (modals, panels) can be slightly longer — 200-250ms.
+
+Use smooth deceleration easing (ease-out variants). Avoid spring/bounce effects in professional interfaces — they feel playful, not serious.
+
+## Contrast Hierarchy
+
+Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently.
+
+## Color Carries Meaning
+
+Gray builds structure. Color communicates — status, action, emphasis, identity. Unmotivated color is noise. Color that reinforces the product's world is character.
+
+## Navigation Context
+
+Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including:
+
+- **Navigation** — sidebar or top nav showing where you are in the app
+- **Location indicator** — breadcrumbs, page title, or active nav state
+- **User context** — who's logged in, what workspace/org
+
+When building sidebars, consider using the same background as the main content area. Rely on a subtle border for separation rather than different background colors.
+
+## Dark Mode
+
+Dark interfaces have different needs:
+
+**Borders over shadows** — Shadows are less visible on dark backgrounds. Lean more on borders for definition.
+
+**Adjust semantic colors** — Status colors (success, warning, error) often need to be slightly desaturated for dark backgrounds.
+
+**Same structure, different values** — The hierarchy system still applies, just with inverted values.

package/dist/templates/nextjs-ts-landing-prisma/project/.agents/skills/interface-design/references/validation.md

@@ -0,0 +1,48 @@
+# Memory Management
+
+When and how to update `.interface-design/system.md`.
+
+## When to Add Patterns
+
+Add to system.md when:
+- Component used 2+ times
+- Pattern is reusable across the project
+- Has specific measurements worth remembering
+
+## Pattern Format
+
+```markdown
+### Button Primary
+- Height: 36px
+- Padding: 12px 16px
+- Radius: 6px
+- Font: 14px, 500 weight
+```
+
+## Don't Document
+
+- One-off components
+- Temporary experiments
+- Variations better handled with props
+
+## Pattern Reuse
+
+Before creating a component, check system.md:
+- Pattern exists? Use it.
+- Need variation? Extend, don't create new.
+
+Memory compounds: each pattern saved makes future work faster and more consistent.
+
+---
+
+# Validation Checks
+
+If system.md defines specific values, check consistency:
+
+**Spacing** — All values multiples of the defined base?
+
+**Depth** — Using the declared strategy throughout? (borders-only means no shadows)
+
+**Colors** — Using defined palette, not random hex codes?
+
+**Patterns** — Reusing documented patterns instead of creating new?

package/dist/templates/nextjs-ts-landing-prisma/project/.agents/skills/next-best-practices/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: next-best-practices
+description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
+user-invocable: false
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See [file-conventions.md](./file-conventions.md) for:
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](./rsc-boundaries.md) for:
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See [async-patterns.md](./async-patterns.md) for:
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](./runtime-selection.md) for:
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](./directives.md) for:
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](./functions.md) for:
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](./error-handling.md) for:
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](./data-patterns.md) for:
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](./route-handlers.md) for:
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](./metadata.md) for:
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](./image.md) for:
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](./font.md) for:
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](./bundling.md) for:
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](./scripts.md) for:
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](./hydration-error.md) for:
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](./suspense-boundaries.md) for:
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](./parallel-routes.md) for:
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](./self-hosting.md) for:
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](./debug-tricks.md) for:
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`
+

package/dist/templates/nextjs-ts-landing-prisma/project/.agents/skills/next-best-practices/async-patterns.md

@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>
+  searchParams: Promise<{ query?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params
+  const { query } = await searchParams
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from 'react'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params)
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  return { title: slug }
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from 'next/headers'
+
+export default async function Page() {
+  const cookieStore = await cookies()
+  const headersList = await headers()
+
+  const theme = cookieStore.get('theme')
+  const userAgent = headersList.get('user-agent')
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```

package/dist/templates/nextjs-ts-landing-prisma/project/.agents/skills/next-best-practices/bundling.md

@@ -0,0 +1,180 @@
+# Bundling
+
+Fix common bundling issues with third-party packages.
+
+## Server-Incompatible Packages
+
+Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
+
+### Error Signs
+
+```
+ReferenceError: window is not defined
+ReferenceError: document is not defined
+ReferenceError: localStorage is not defined
+Module not found: Can't resolve 'fs'
+```
+
+### Solution 1: Mark as Client-Only
+
+If the package is only needed on client:
+
+```tsx
+// Bad: Fails - package uses window
+import SomeChart from 'some-chart-library'
+
+export default function Page() {
+  return <SomeChart />
+}
+
+// Good: Use dynamic import with ssr: false
+import dynamic from 'next/dynamic'
+
+const SomeChart = dynamic(() => import('some-chart-library'), {
+  ssr: false,
+})
+
+export default function Page() {
+  return <SomeChart />
+}
+```
+
+### Solution 2: Externalize from Server Bundle
+
+For packages that should run on server but have bundling issues:
+
+```js
+// next.config.js
+module.exports = {
+  serverExternalPackages: ['problematic-package'],
+}
+```
+
+Use this for:
+- Packages with native bindings (sharp, bcrypt)
+- Packages that don't bundle well (some ORMs)
+- Packages with circular dependencies
+
+### Solution 3: Client Component Wrapper
+
+Wrap the entire usage in a client component:
+
+```tsx
+// components/ChartWrapper.tsx
+'use client'
+
+import { Chart } from 'chart-library'
+
+export function ChartWrapper(props) {
+  return <Chart {...props} />
+}
+
+// app/page.tsx (server component)
+import { ChartWrapper } from '@/components/ChartWrapper'
+
+export default function Page() {
+  return <ChartWrapper data={data} />
+}
+```
+
+## CSS Imports
+
+Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
+
+```tsx
+// Bad: Manual link tag
+<link rel="stylesheet" href="/styles.css" />
+
+// Good: Import CSS
+import './styles.css'
+
+// Good: CSS Modules
+import styles from './Button.module.css'
+```
+
+## Polyfills
+
+Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
+
+Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
+
+```tsx
+// Bad: Redundant polyfills
+<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
+
+// Good: Next.js includes these automatically
+```
+
+## ESM/CommonJS Issues
+
+### Error Signs
+
+```
+SyntaxError: Cannot use import statement outside a module
+Error: require() of ES Module
+Module not found: ESM packages need to be imported
+```
+
+### Solution: Transpile Package
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ['some-esm-package', 'another-package'],
+}
+```
+
+## Common Problematic Packages
+
+| Package | Issue | Solution |
+|---------|-------|----------|
+| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
+| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
+| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
+| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
+| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
+| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
+| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
+| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
+
+## Bundle Analysis
+
+Analyze bundle size with the built-in analyzer (Next.js 16.1+):
+
+```bash
+next experimental-analyze
+```
+
+This opens an interactive UI to:
+- Filter by route, environment (client/server), and type
+- Inspect module sizes and import chains
+- View treemap visualization
+
+Save output for comparison:
+
+```bash
+next experimental-analyze --output
+# Output saved to .next/diagnostics/analyze
+```
+
+Reference: https://nextjs.org/docs/app/guides/package-bundling
+
+## Migrating from Webpack to Turbopack
+
+Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
+
+```js
+// next.config.js
+module.exports = {
+  // Good: Works with Turbopack
+  serverExternalPackages: ['package'],
+  transpilePackages: ['package'],
+
+  // Bad: Webpack-only - migrate away from this
+  webpack: (config) => {
+    // custom webpack config
+  },
+}
+```
+
+Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack