@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-realtime/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: stacks-realtime
+description: Use when implementing real-time features in Stacks — WebSocket broadcasting, public/private/presence channels, emit to users, the Channel class, broadcast discovery, server lifecycle, or realtime configuration. Covers @stacksjs/realtime and config/realtime.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Realtime
+
+WebSocket broadcasting via `ts-broadcasting` with channel-based messaging. Provides a Laravel-like API for real-time features.
+
+## Key Paths
+- Core package: `storage/framework/core/realtime/src/`
+- Configuration: `config/realtime.ts`
+- Application broadcasts: `app/Broadcasts/`
+
+## Source Files
+```
+realtime/src/
+  index.ts            # re-exports ts-broadcasting + all Stacks-specific exports
+  emit.ts             # emit(), emitToUser(), emitToUsers()
+  channel.ts          # Channel class + channel() factory
+  broadcast.ts        # Broadcast class + runBroadcast() + broadcast()
+  ws.ts               # WebSocket request handler (legacy, kept for backward compat)
+  server-instance.ts  # server lifecycle (createServer/getServer/setServer/stopServer)
+```
+
+## Exports (from index.ts)
+
+The package re-exports everything from `ts-broadcasting` plus Stacks-specific APIs:
+
+```typescript
+// Re-exported from ts-broadcasting
+export * from 'ts-broadcasting'
+
+// Server instance management
+export { getServer, setServer, createServer, stopServer } from './server-instance'
+
+// Stacks-specific exports
+export { emit, emitToUser, emitToUsers } from './emit'
+export type { EmitOptions } from './emit'
+export { channel as createChannel, Channel as StacksChannel } from './channel'
+export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } from './broadcast'
+export type { BroadcastInstance } from './broadcast'
+export { setBunSocket, handleWebSocketRequest, storeWebSocketEvent } from './ws'
+```
+
+Note the renamed exports:
+- `channel()` is exported as `createChannel`
+- `Channel` class is exported as `StacksChannel`
+- `broadcast()` is exported as `dispatchBroadcast`
+- `Broadcast` class is exported as `LegacyBroadcast`
+
+---
+
+## Emit Functions
+
+The primary API for broadcasting events.
+
+### `emit(channel, event, data?, options?)` - Broadcast to a channel
+
+```typescript
+import { emit, emitToUser, emitToUsers } from '@stacksjs/realtime'
+
+// Broadcast to a public channel
+emit('chat-room', 'new-message', { text: 'Hello', sender: 'John' })
+
+// Broadcast to a private channel (auto-prefixes 'private-')
+emit('orders', 'updated', { status: 'shipped' }, { private: true })
+
+// Broadcast to a presence channel (auto-prefixes 'presence-')
+emit('room-1', 'user-joined', { userId: 42 }, { presence: true })
+
+// Exclude specific socket(s) from receiving
+// NOTE: BroadcastServer only supports single socket exclusion;
+//       if array is passed, only the first element is used
+emit('chat', 'typing', data, { exclude: 'socket-id-1' })
+emit('chat', 'typing', data, { exclude: ['socket-id-1', 'socket-id-2'] })
+```
+
+### EmitOptions interface
+
+```typescript
+interface EmitOptions {
+  private?: boolean     // prefix channel with 'private-'
+  presence?: boolean    // prefix channel with 'presence-'
+  exclude?: string | string[]  // socket IDs to exclude (only first used)
+  driver?: string       // broadcast driver override
+}
+```
+
+### `emitToUser(userId, event, data?, options?)` - Emit to specific user
+
+Sends to `private-user.{userId}` channel. The target user must be subscribed to their own private user channel.
+
+```typescript
+// Emit to a specific user (sends to 'private-user.42')
+emitToUser(42, 'notification', { message: 'You have a new order' })
+emitToUser('user-123', 'alert', { type: 'warning', text: 'Session expiring' })
+```
+
+### `emitToUsers(userIds, event, data?, options?)` - Emit to multiple users
+
+Iterates over userIds and calls `emitToUser` for each.
+
+```typescript
+// Emit to multiple users
+emitToUsers([42, 43, 44], 'announcement', { text: 'Server maintenance at 3pm' })
+```
+
+---
+
+## Channel Class
+
+Provides a fluent API for broadcasting to channels with explicit channel types.
+
+### `channel(name)` - Factory function
+
+```typescript
+import { createChannel } from '@stacksjs/realtime'
+// or within the package: import { channel } from './channel'
+
+const ch = createChannel('orders')
+
+// Broadcast to public channel (no prefix)
+await ch.public('new-order', { id: 1, total: 99.99 })
+
+// Broadcast to private channel (auto-prefixes 'private-')
+await ch.private('status-update', { status: 'shipped' })
+
+// Broadcast to presence channel (auto-prefixes 'presence-')
+await ch.presence('user-online', { userId: 42 })
+
+// Broadcast with explicit type
+await ch.broadcast('event', data, 'private')   // type: 'public' | 'private' | 'presence'
+await ch.broadcast('event', data)              // defaults to 'public'
+```
+
+### Channel class internals
+
+```typescript
+class Channel {
+  private channelName: string
+
+  constructor(channel: string)
+
+  async private(event: string, data?: any): Promise<void>
+  // Prefixes with 'private-' if not already prefixed
+
+  async public(event: string, data?: any): Promise<void>
+  // Uses channelName as-is
+
+  async presence(event: string, data?: any): Promise<void>
+  // Prefixes with 'presence-' if not already prefixed
+
+  async broadcast(event: string, data?: any, type: ChannelType = 'public'): Promise<void>
+  // Dispatches to private(), presence(), or public() based on type
+}
+```
+
+All methods throw `Error('Broadcast server not initialized')` if `getServer()` returns null.
+
+---
+
+## Server Lifecycle
+
+The server instance is stored as a module-level singleton (`serverInstance`).
+
+```typescript
+import { createServer, getServer, setServer, stopServer } from '@stacksjs/realtime'
+import type { ServerConfig, BroadcastServer } from 'ts-broadcasting'
+
+// Create and start a new broadcast server
+// Internally: new BroadcastServer(config) -> server.start() -> setServer(server)
+const server: BroadcastServer = await createServer(config)
+
+// Get existing server instance (or null)
+const server: BroadcastServer | null = getServer()
+
+// Set server instance manually
+setServer(server)
+
+// Stop server and set instance to null
+await stopServer()
+```
+
+`createServer()` dynamically imports `ts-broadcasting`, instantiates `BroadcastServer`, calls `start()`, stores the instance via `setServer()`, and returns it.
+
+---
+
+## Broadcast Discovery
+
+Dynamically loads broadcast files from `app/Broadcasts/` and executes them.
+
+### `runBroadcast(name, payload?)` - Run a broadcast file
+
+```typescript
+import { runBroadcast, dispatchBroadcast } from '@stacksjs/realtime'
+
+// Loads app/Broadcasts/OrderStatusChanged.ts and executes it
+await runBroadcast('OrderStatusChanged', { orderId: 1 })
+
+// Alias - identical to runBroadcast
+await dispatchBroadcast('NewMessage', { text: 'Hello' })
+```
+
+### Broadcast file interface
+
+```typescript
+interface BroadcastInstance {
+  channel?: () => string | string[]       // channels to broadcast on
+  broadcastOn?: () => string | string[]   // alias for channel()
+  event?: () => string                     // event name
+  broadcastAs?: () => string              // alias for event()
+  data?: () => any                         // data payload
+  broadcastWith?: () => any               // alias for data()
+  handle?: (payload?: any) => Promise<void> | void  // custom handler
+}
+```
+
+### How broadcast discovery works
+
+1. Scans `app/Broadcasts/**/*.ts` using `bun.globSync()`
+2. Finds file ending with `{name}.ts`
+3. Imports the module and reads its `default` export
+4. If `handle()` exists, calls it with the payload and returns
+5. Otherwise, reads channel/event/data from the interface methods
+6. Constructs a `BroadcastEvent` and calls `server.broadcaster.broadcast(event)`
+
+### Example broadcast file
+
+```typescript
+// app/Broadcasts/OrderCreated.ts
+export default {
+  broadcastOn: () => ['orders', 'private-admin'],
+  broadcastAs: () => 'order.created',
+  broadcastWith: () => ({ orderId: 123, total: 99.99 }),
+}
+```
+
+Or with a custom handler:
+
+```typescript
+// app/Broadcasts/UserNotification.ts
+export default {
+  handle: async (payload) => {
+    const { emit } = await import('@stacksjs/realtime')
+    emit(`private-user.${payload.userId}`, 'notification', {
+      message: payload.message,
+    }, { private: true })
+  },
+}
+```
+
+---
+
+## Legacy/Backward Compatibility
+
+### Broadcast class (exported as `LegacyBroadcast`)
+
+```typescript
+class Broadcast {
+  async connect(): Promise<void>       // no-op
+  async disconnect(): Promise<void>    // no-op
+  subscribe(channel, callback): void   // warns: use BroadcastClient instead
+  unsubscribe(channel): void           // warns: use BroadcastClient instead
+  broadcast(channel, event, data?, type?): void  // delegates to server.broadcast()
+  isConnected(): boolean               // returns getServer() !== null
+}
+```
+
+### WebSocket handler (ws.ts)
+
+```typescript
+// Deprecated - handled by ts-broadcasting internally
+setBunSocket(server: BroadcastServer | null): void      // calls setServer()
+storeWebSocketEvent(type, socket, details): Promise<void> // no-op
+handleWebSocketRequest(req, server): Promise<Response | undefined>  // delegates to server.upgrade()
+```
+
+---
+
+## config/realtime.ts
+
+Full configuration with all options and their defaults:
+
+```typescript
+export default {
+  enabled: true,
+
+  // Deployment mode
+  mode: 'server' as 'server' | 'serverless',
+  // 'server': ts-broadcasting (high-performance Bun WebSocket server)
+  // 'serverless': API Gateway WebSocket + Lambda + DynamoDB
+
+  // Legacy driver option (backward compat)
+  driver: 'bun' as 'socket' | 'pusher' | 'bun' | 'reverb' | 'ably',
+
+  // Server mode config (ts-broadcasting)
+  server: {
+    host: env.BROADCAST_HOST || '0.0.0.0',
+    port: Number(env.BROADCAST_PORT || 6001),
+    scheme: 'ws' as 'ws' | 'wss',
+    driver: 'bun',
+
+    redis: {
+      enabled: Boolean(env.BROADCAST_REDIS_ENABLED || false),
+      host: env.REDIS_HOST || 'localhost',
+      port: Number(env.REDIS_PORT || 6379),
+      password: env.REDIS_PASSWORD || '',
+      prefix: env.BROADCAST_REDIS_PREFIX || 'stacks:realtime:',
+    },
+
+    rateLimit: {
+      enabled: true,                    // env.BROADCAST_RATE_LIMIT_ENABLED
+      maxConnectionsPerIp: 100,
+      maxMessagesPerSecond: 50,
+      maxPayloadSize: 65536,            // 64KB
+      banDuration: 300,                 // seconds
+    },
+
+    loadManagement: {
+      maxConnections: 10000,
+      backpressureThreshold: 1000,
+      messageQueueSize: 10000,
+      gracefulShutdownTimeout: 30000,   // 30s
+    },
+
+    autoScaling: {
+      min: 1,
+      max: 10,
+      targetCPU: 70,                    // percentage
+    },
+
+    healthCheck: {
+      enabled: true,
+      path: '/health',
+      interval: 30,                     // seconds
+    },
+
+    metrics: {
+      enabled: Boolean(env.BROADCAST_METRICS_ENABLED || false),
+      port: 9090,
+      path: '/metrics',
+    },
+  },
+
+  // Serverless mode config (API Gateway WebSocket)
+  serverless: {
+    connectionTimeout: 3600,            // 1 hour
+    idleTimeout: 600,                   // 10 minutes
+    stageName: env.APP_ENV || 'production',
+    memorySize: 256,                    // MB
+    timeout: 30,                        // seconds
+  },
+
+  // Channel configuration
+  channels: {
+    public: true,
+    private: true,
+    presence: {
+      enabled: true,
+      maxMembersPerChannel: 100,
+      memberInfoTtl: 60,               // seconds
+    },
+  },
+
+  // App credentials (Pusher-compatible)
+  app: {
+    id: env.BROADCAST_APP_ID || 'stacks',
+    key: env.BROADCAST_APP_KEY || '',
+    secret: env.BROADCAST_APP_SECRET || '',
+  },
+
+  // Legacy socket config
+  socket: {
+    port: Number(env.BROADCAST_PORT || 6001),
+    host: env.BROADCAST_HOST || 'localhost',
+    cors: {
+      origin: env.BROADCAST_CORS_ORIGIN || env.APP_URL || 'http://localhost:3000',
+      methods: ['GET', 'POST'],
+    },
+  },
+
+  // Legacy Pusher config
+  pusher: {
+    appId: env.PUSHER_APP_ID || '',
+    key: env.PUSHER_APP_KEY || '',
+    secret: env.PUSHER_APP_SECRET || '',
+    cluster: env.PUSHER_APP_CLUSTER || 'mt1',
+    useTLS: Boolean(env.PUSHER_APP_USE_TLS ?? true),
+  },
+
+  debug: Boolean(env.BROADCAST_DEBUG || false),
+} satisfies RealtimeConfig
+```
+
+### Environment Variables
+| Variable | Default | Description |
+|---|---|---|
+| `REALTIME_MODE` | `server` | Deployment mode: server or serverless |
+| `BROADCAST_DRIVER` | `bun` | Broadcasting driver |
+| `BROADCAST_HOST` | `0.0.0.0` | Server bind host |
+| `BROADCAST_PORT` | `6001` | Server port |
+| `BROADCAST_SCHEME` | `ws` | WebSocket scheme (ws/wss) |
+| `BROADCAST_REDIS_ENABLED` | `false` | Enable Redis adapter |
+| `REDIS_HOST` | `localhost` | Redis host |
+| `REDIS_PORT` | `6379` | Redis port |
+| `REDIS_PASSWORD` | (empty) | Redis password |
+| `BROADCAST_REDIS_PREFIX` | `stacks:realtime:` | Redis key prefix |
+| `BROADCAST_RATE_LIMIT_ENABLED` | `true` | Enable rate limiting |
+| `BROADCAST_METRICS_ENABLED` | `false` | Enable metrics endpoint |
+| `BROADCAST_APP_ID` | `stacks` | App ID |
+| `BROADCAST_APP_KEY` | (empty) | App key |
+| `BROADCAST_APP_SECRET` | (empty) | App secret |
+| `BROADCAST_CORS_ORIGIN` | APP_URL | CORS origin |
+| `BROADCAST_DEBUG` | `false` | Debug mode |
+| `PUSHER_APP_ID` | (empty) | Pusher app ID |
+| `PUSHER_APP_KEY` | (empty) | Pusher app key |
+| `PUSHER_APP_SECRET` | (empty) | Pusher app secret |
+| `PUSHER_APP_CLUSTER` | `mt1` | Pusher cluster |
+| `PUSHER_APP_USE_TLS` | `true` | Pusher TLS |
+
+---
+
+## Gotchas
+- The server must be created via `createServer()` before `emit()` works -- otherwise it silently logs a warning and returns
+- Channel and Broadcast methods throw errors if the server is not initialized (unlike `emit()` which only warns)
+- Private channels auto-prefix `private-` -- don't add it yourself (the code checks `channel.startsWith('private-')`)
+- Presence channels auto-prefix `presence-` -- same logic applies
+- `emitToUser()` sends to `private-user.{userId}` -- users must subscribe to this channel pattern
+- When using `emit()` with `exclude`, only the first socket ID in an array is used (BroadcastServer limitation)
+- Broadcast files are dynamically imported from `app/Broadcasts/` using `bun.globSync`
+- The `Broadcast` class is legacy -- new code should use `emit()` and `channel()` directly
+- `handleWebSocketRequest()` and `storeWebSocketEvent()` are deprecated -- ws events are tracked internally by ts-broadcasting
+- `setBunSocket()` is deprecated -- use `setServer()` instead
+- Serverless mode uses API Gateway WebSocket for AWS Lambda with DynamoDB for connection management
+- Rate limiting defaults: 100 connections per IP, 50 messages/second, 64KB max payload, 300s ban duration
+- Redis adapter enables horizontal scaling across multiple server instances
+- Auto-scaling config (min/max/targetCPU) is for cloud deployment orchestration
+- The `satisfies RealtimeConfig` type annotation ensures the config matches the expected type from `@stacksjs/types`

package/ai/skills/stacks-redesign/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: stacks-redesign
+description: Use when auditing and upgrading an existing Stacks UI to premium quality - finding AI-slop and generic patterns in stx templates, then fixing layout, spacing, hierarchy, type, color, states, and copy without breaking functionality or migrating the stack. Composes with stacks-design-taste as the audit-first companion, working in stx + Crosswind + composables.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Redesign an Existing Stacks UI
+
+**Related skills:** the audit-first companion to [`stacks-design-taste`](../stacks-design-taste/SKILL.md) (the flagship anti-slop skill). Apply an aesthetic preset with [`stacks-design-soft`](../stacks-design-soft/SKILL.md), [`stacks-design-minimalist`](../stacks-design-minimalist/SKILL.md), or [`stacks-design-brutalist`](../stacks-design-brutalist/SKILL.md). Work in [`stacks-stx`](../stacks-stx/SKILL.md), [`stacks-crosswind`](../stacks-crosswind/SKILL.md), [`stacks-ui`](../stacks-ui/SKILL.md), and [`stacks-composables`](../stacks-composables/SKILL.md).
+
+## How This Works
+
+When applied to an existing Stacks project, follow this sequence:
+
+1. **Scan** - Read the codebase. Confirm the stack is stx + Crosswind + composables. Locate `resources/views/*.stx`, `resources/components/*.stx`, `resources/layouts/*.stx`, `config/ui.ts`, `config/crosswind.ts`, and the `fonts` config. Note current design patterns.
+2. **Diagnose** - Run through the audit below. List every generic pattern, weak point, and missing state you find.
+3. **Fix** - Apply targeted upgrades working with the existing stx + Crosswind stack. Do not rewrite from scratch and do not migrate frameworks. Improve what is there.
+
+## Design Audit
+
+### Typography
+
+Check for these problems and fix them:
+- **Browser default fonts or Inter everywhere.** Replace with a font that has character (`Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`). Register the choice in the `fonts` config and load it with `@font-face` / `<link>` + `font-display: swap` in the layout `.stx` head. For editorial/creative projects, pair a serif header with a sans-serif body.
+- **Headlines lack presence.** Increase size for display text, tighten letter-spacing, reduce line-height. Headlines should feel heavy and intentional.
+- **Body text too wide.** Limit paragraph width to roughly 65 characters (`max-w-prose` / `max-w-2xl`). Increase line-height for readability.
+- **Only Regular (400) and Bold (700) weights used.** Introduce Medium (500) and SemiBold (600) for subtler hierarchy.
+- **Numbers in proportional font.** Use a monospace font or enable tabular figures (`tabular-nums` / `font-variant-numeric: tabular-nums`) for data-heavy interfaces.
+- **Missing letter-spacing adjustments.** Negative tracking for large headers, positive tracking for small caps or labels.
+- **All-caps subheaders everywhere.** Try lowercase italics, sentence case, or small-caps instead.
+- **Orphaned words.** Single words alone on the last line. Fix with `text-wrap: balance` or `text-wrap: pretty`.
+
+### Color and Surfaces
+
+- **Pure `#000000` background.** Replace with off-black, dark charcoal, or tinted dark (`#0a0a0a`, `#121212`, or a dark navy).
+- **Oversaturated accent colors.** Keep saturation below 80%. Desaturate accents so they blend with neutrals instead of screaming.
+- **More than one accent color.** Pick one. Remove the rest. Consistency beats variety.
+- **Mixing warm and cool grays.** Stick to one gray family; tint all grays with a consistent hue.
+- **Purple/blue "AI gradient" aesthetic.** The most common AI design fingerprint. Replace with neutral bases and a single, considered accent.
+- **Generic `box-shadow`.** Tint shadows to match the background hue. Use colored shadows instead of pure black at low opacity.
+- **Flat design with zero texture.** Add subtle noise, grain, or micro-patterns to backgrounds. Pure flat vectors feel sterile.
+- **Perfectly even gradients.** Break uniformity with radial gradients, noise overlays, or mesh gradients instead of standard linear 45-degree fades.
+- **Inconsistent lighting direction.** Audit all shadows to suggest a single, consistent light source.
+- **Random dark sections in a light-mode page (or vice versa).** A single dark-background section breaking an otherwise light page looks like a copy-paste accident. Either commit to full dark mode (`dark:` + `useColorMode()` / `useDark()`) or keep a consistent tone throughout. If contrast is needed, use a slightly darker shade of the same palette, not a sudden jump to `#111` in the middle of a cream page.
+- **Empty, flat sections with no visual depth.** Add high-quality background imagery (blurred, overlaid, or masked), subtle patterns, or ambient gradients. Use `<img>` with explicit `width`/`height` via the stx asset pipeline; placeholder source `https://picsum.photos/seed/{name}/1920/1080`. Even a subtle full-width photo at low opacity adds presence.
+
+### Layout
+
+- **Everything centered and symmetrical.** Break symmetry with offset margins, mixed aspect ratios, or left-aligned headers over centered content.
+- **Three equal card columns as feature row.** The most generic AI layout. Replace with a 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry layout.
+- **Using `height: 100vh` for full-screen sections.** Replace with `min-h-[100dvh]` to prevent layout jumping on mobile browsers (iOS Safari viewport bug).
+- **Complex flexbox percentage math.** Replace with CSS Grid (`grid` utilities) for reliable multi-column structures.
+- **No max-width container.** Add a container constraint (around `max-w-7xl`, 1200-1440px) with `mx-auto` so content does not stretch edge-to-edge on wide screens.
+- **Cards of equal height forced by flexbox.** Allow variable heights or use masonry when content varies.
+- **Uniform border-radius on everything.** Vary the radius: tighter on inner elements, softer on containers.
+- **No overlap or depth.** Use negative margins to create layering and visual depth.
+- **Symmetrical vertical padding.** Adjust optically; bottom padding often needs to be slightly larger.
+- **Dashboard always has a left sidebar.** Try top navigation, a floating command menu, or a collapsible panel instead.
+- **Missing whitespace.** Double the spacing. Let the design breathe. Dense layouts work for data dashboards, not for marketing pages.
+- **Buttons not bottom-aligned in card groups.** Pin CTAs to the bottom of each card so they form a clean horizontal line regardless of content above.
+- **Feature lists starting at different vertical positions.** In pricing tables or comparison cards, feature lists should start at the same Y position across columns.
+- **Inconsistent vertical rhythm in side-by-side elements.** Align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken.
+- **Mathematical alignment that looks optically wrong.** Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right.
+
+### Interactivity and States
+
+- **No hover states on buttons.** Add background shift, slight scale, or translate on `hover:`.
+- **No active/pressed feedback.** Add `active:scale-[0.98]` or `active:translate-y-px` to simulate a physical click.
+- **Instant transitions with zero duration.** Add smooth transitions (200-300ms) to all interactive elements.
+- **Missing focus ring.** Ensure visible `focus-visible:` indicators for keyboard navigation. An accessibility requirement, not optional.
+- **No loading states.** Replace generic circular spinners with skeleton loaders that match the layout shape. Drive async state with `useAsync` / `useFetch` / `useQuery`.
+- **No empty states.** Design a composed "getting started" view instead of a blank dashboard.
+- **No error states.** Add clear, inline error messages for forms. Do NOT use `window.alert()` (and never bare `window.*` in stx scripts).
+- **Dead links.** Buttons that link to `#`. Either link to real destinations or visually disable them.
+- **No indication of current page in navigation.** Style the active nav link differently (use `useRoute()` / `useRouter()` to detect it).
+- **Scroll jumping.** Anchor clicks jump instantly. Add `scroll-behavior: smooth`.
+- **Animations using `top`, `left`, `width`, `height`.** Switch to `transform` and `opacity` for GPU-accelerated, smooth animation.
+
+### Content
+
+- **Generic names like "John Doe" or "Jane Smith".** Use diverse, realistic-sounding names.
+- **Fake round numbers like `99.99%`, `50%`, `$100.00`.** Use organic, messy data: `47.2%`, `$99.00`, `+1 (312) 847-1928`.
+- **Placeholder company names like "Acme Corp", "Nexus", "SmartFlow".** Invent contextual, believable brand names.
+- **AI copywriting cliches.** Never use "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", "Tapestry", or "In the world of...". Write plain, specific language.
+- **Exclamation marks in success messages.** Remove them. Be confident, not loud.
+- **"Oops!" error messages.** Be direct: "Connection failed. Please try again."
+- **Passive voice.** Use active voice: "We couldn't save your changes" instead of "Mistakes were made."
+- **All blog post dates identical.** Randomize dates to appear real.
+- **Same avatar image for multiple users.** Use unique assets for every distinct person.
+- **Lorem Ipsum.** Never use placeholder latin text. Write real draft copy.
+- **Title Case On Every Header.** Use sentence case instead.
+
+### Component Patterns
+
+- **Generic card look (border + shadow + white background).** Remove the border, or use only background color, or use only spacing. Cards should exist only when elevation communicates hierarchy.
+- **Always one filled button + one ghost button.** Add text links or tertiary styles to reduce visual noise.
+- **Pill-shaped "New" and "Beta" badges.** Try square badges, flags, or plain text labels.
+- **Accordion FAQ sections.** Use a side-by-side list, searchable help, or inline progressive disclosure. When you do keep a disclosure, use the headless `Disclosure` from [`stacks-ui`](../stacks-ui/SKILL.md).
+- **3-card carousel testimonials with dots.** Replace with a masonry wall, embedded social posts, or a single rotating quote.
+- **Pricing table with 3 towers.** Highlight the recommended tier with color and emphasis, not just extra height.
+- **Modals for everything.** Use inline editing, slide-over panels, or expandable sections instead of popups for simple actions. For real modals reach for the headless `Dialog`/`Modal` in [`stacks-ui`](../stacks-ui/SKILL.md).
+- **Avatar circles exclusively.** Try squircles or rounded squares for a less generic look.
+- **Light/dark toggle always a sun/moon switch.** Use a dropdown, system preference detection (`useColorMode()` / `useDark()`), or integrate it into settings.
+- **Footer link farm with 4 columns.** Simplify. Focus on main navigational paths and legally required links.
+
+### Iconography
+
+- **Lucide or Feather icons exclusively.** The "default" AI icon choice. Use Iconify `i-*` classes (Phosphor `i-ph-*`, Heroicons, or the hugeicons default) for differentiation. NEVER hand-roll SVG icon paths and NEVER `npm install` an icon library.
+- **Rocketship for "Launch", shield for "Security".** Replace cliche metaphors with less obvious icons (bolt, fingerprint, spark, vault).
+- **Inconsistent stroke widths across icons.** Standardize to one stroke weight and one Iconify collection per project.
+- **Missing favicon.** Always include a branded favicon.
+- **Stock "diverse team" photos.** Use real team photos, candid shots, or a consistent illustration style instead of uncanny stock imagery.
+
+### Code Quality
+
+- **Div soup.** Use semantic stx markup: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`.
+- **Inline styles mixed with utility classes.** Move styling into Crosswind utilities or the `.stx` `<style>` block.
+- **Hardcoded pixel widths.** Use relative units (`%`, `rem`, `em`, `max-w-*`) for flexible layouts.
+- **Missing alt text on images.** Describe image content for screen readers. Never leave `alt=""` or `alt="image"` on meaningful images.
+- **Arbitrary z-index values like `9999`.** Establish a clean z-index scale in the theme/tokens.
+- **Commented-out dead code.** Remove all debug artifacts before shipping.
+- **Import hallucinations.** Check that every import actually exists. Composables are auto-imported (no import line); do not invent composable names. Verify components exist in `resources/components`.
+- **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta via the `@seo` / `@meta` directives or `useHead` / `useSeoMeta`.
+- **Vanilla JS in stx scripts.** Replace any `var`, `document.*`, or `window.*` with signals + composables + directives.
+
+### Strategic Omissions (What AI Typically Forgets)
+
+- **No legal links.** Add privacy policy and terms of service links in the footer.
+- **No "back" navigation.** Every page needs a way back.
+- **No custom 404 page.** Design a helpful, branded "page not found" experience.
+- **No form validation.** Add client-side validation for emails, required fields, and format checks.
+- **No "skip to content" link.** Add a hidden skip-link for keyboard users.
+- **No cookie consent.** If required by jurisdiction, add a compliant consent banner.
+
+## Upgrade Techniques
+
+Pull from these high-impact techniques to replace generic patterns. All motion is built with Crosswind transitions, CSS keyframes, and composables; Stacks ships no animation library, so do NOT import `motion`, `gsap`, or `framer-motion`.
+
+### Typography Upgrades
+- **Variable font animation.** Interpolate weight or width on scroll or hover for text that feels alive.
+- **Outlined-to-fill transitions.** Text starts as a stroke outline and fills with color on scroll entry or interaction.
+- **Text mask reveals.** Large typography acting as a window to video or animated imagery behind it.
+
+### Layout Upgrades
+- **Broken grid / asymmetry.** Elements that deliberately ignore column structure: overlapping, bleeding off-screen, or offset with calculated randomness.
+- **Whitespace maximization.** Aggressive negative space to force focus on a single element.
+- **Parallax card stacks.** Sections that stick and physically stack over each other during scroll. Build with `position: sticky` + `top: 0` and CSS scroll-driven animations (`animation-timeline: view()` / `scroll()`), not GSAP ScrollTrigger.
+- **Split-screen scroll.** Two halves of the screen sliding in opposite directions via CSS scroll-driven animations.
+
+### Motion Upgrades
+- **Smooth scroll with inertia.** Use `scroll-behavior: smooth`; keep it CSS-driven, never a `requestAnimationFrame` loop writing signal state every frame.
+- **Staggered entry.** Elements cascade in with slight delays, combining Y-axis translation with opacity fade. Toggle with `useIntersectionObserver` / `useElementVisibility`. Never mount everything at once.
+- **Spring physics.** Replace linear easing with custom cubic-bezier motion (for example `ease-[cubic-bezier(0.32,0.72,0,1)]`) for a natural, weighty feel.
+- **Scroll-driven reveals.** Content entering through expanding masks, wipes, or draw-on SVG paths tied to scroll progress via CSS scroll-driven animations. NEVER `window.addEventListener('scroll', ...)`.
+
+### Surface Upgrades
+- **True glassmorphism.** Go beyond `backdrop-blur`. Add a 1px inner border and a subtle inner shadow to simulate edge refraction. Apply blur only to fixed/sticky elements.
+- **Spotlight borders.** Card borders that illuminate under the cursor. Track the pointer with `useMouse()` and drive a CSS custom property from an `effect`.
+- **Grain and noise overlays.** A fixed, `pointer-events-none` overlay with subtle noise to break digital flatness.
+- **Colored, tinted shadows.** Shadows that carry the hue of the background rather than generic black.
+
+## Fix Priority
+
+Apply changes in this order for maximum visual impact with minimum risk:
+1. **Font swap** - biggest instant improvement, lowest risk
+2. **Color palette cleanup** - remove clashing or oversaturated colors
+3. **Hover and active states** - makes the interface feel alive
+4. **Layout and spacing** - proper grid, max-width, consistent padding
+5. **Replace generic components** - swap cliche patterns for modern alternatives
+6. **Add loading, empty, and error states** - makes it feel finished
+7. **Polish typography scale and spacing** - the premium final touch
+
+## Rules
+
+- Work with the existing stx + Crosswind + composables stack. Do not migrate frameworks or styling libraries.
+- Do not break existing functionality. Test after every change.
+- Before importing any new library, check `package.json` first. Composables are auto-imported; do not invent composable names (defer to [`stacks-composables`](../stacks-composables/SKILL.md) for the real list).
+- Respect CLAUDE.md hard bans: no `var`, no `document.*`, no `window.*` in stx scripts; lint with pickier (`bunx --bun pickier .`), never eslint.
+- Keep changes reviewable and focused. Small, targeted improvements over big rewrites.
+- Ship complete stx; never a skeleton or placeholder comment.