@goldencomm/create-baseline 0.0.1 → 0.1.0

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -1,65 +0,0 @@
----
-title: Avoid Duplicate Serialization in RSC Props
-impact: LOW
-impactDescription: reduces network payload by avoiding duplicate serialization
-tags: server, rsc, serialization, props, client-components
----
-
-## Avoid Duplicate Serialization in RSC Props
-
-**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
-
-RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
-
-**Incorrect (duplicates array):**
-
-```tsx
-// RSC: sends 6 strings (2 arrays × 3 items)
-<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
-```
-
-**Correct (sends 3 strings):**
-
-```tsx
-// RSC: send once
-<ClientList usernames={usernames} />
-
-// Client: transform there
-'use client'
-const sorted = useMemo(() => [...usernames].sort(), [usernames])
-```
-
-**Nested deduplication behavior:**
-
-Deduplication works recursively. Impact varies by data type:
-
-- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
-- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
-
-```tsx
-// string[] - duplicates everything
-usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
-
-// object[] - duplicates array structure only
-users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
-```
-
-**Operations breaking deduplication (create new references):**
-
-- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
-- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
-
-**More examples:**
-
-```tsx
-// ❌ Bad
-<C users={users} active={users.filter(u => u.active)} />
-<C product={product} productName={product.name} />
-
-// ✅ Good
-<C users={users} />
-<C product={product} />
-// Do filtering/destructuring in client
-```
-
-**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-hoist-static-io.md

@@ -1,149 +0,0 @@
----
-title: Hoist Static I/O to Module Level
-impact: HIGH
-impactDescription: avoids repeated file/network I/O per request
-tags: server, io, performance, next.js, route-handlers, og-image
----
-
-## Hoist Static I/O to Module Level
-
-**Impact: HIGH (avoids repeated file/network I/O per request)**
-
-When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
-
-**Incorrect (reads font file on every request):**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-
-export async function GET(request: Request) {
-  // Runs on EVERY request - expensive!
-  const fontData = await fetch(
-    new URL('./fonts/Inter.ttf', import.meta.url)
-  ).then(res => res.arrayBuffer())
-
-  const logoData = await fetch(
-    new URL('./images/logo.png', import.meta.url)
-  ).then(res => res.arrayBuffer())
-
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logoData} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: fontData }] }
-  )
-}
-```
-
-**Correct (loads once at module initialization):**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-
-// Module-level: runs ONCE when module is first imported
-const fontData = fetch(
-  new URL('./fonts/Inter.ttf', import.meta.url)
-).then(res => res.arrayBuffer())
-
-const logoData = fetch(
-  new URL('./images/logo.png', import.meta.url)
-).then(res => res.arrayBuffer())
-
-export async function GET(request: Request) {
-  // Await the already-started promises
-  const [font, logo] = await Promise.all([fontData, logoData])
-
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logo} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: font }] }
-  )
-}
-```
-
-**Correct (synchronous fs at module level):**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-import { readFileSync } from 'fs'
-import { join } from 'path'
-
-// Synchronous read at module level - blocks only during module init
-const fontData = readFileSync(
-  join(process.cwd(), 'public/fonts/Inter.ttf')
-)
-
-const logoData = readFileSync(
-  join(process.cwd(), 'public/images/logo.png')
-)
-
-export async function GET(request: Request) {
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logoData} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: fontData }] }
-  )
-}
-```
-
-**Incorrect (reads config on every call):**
-
-```typescript
-import fs from 'node:fs/promises'
-
-export async function processRequest(data: Data) {
-  const config = JSON.parse(
-    await fs.readFile('./config.json', 'utf-8')
-  )
-  const template = await fs.readFile('./template.html', 'utf-8')
-
-  return render(template, data, config)
-}
-```
-
-**Correct (hoists config and template to module level):**
-
-```typescript
-import fs from 'node:fs/promises'
-
-const configPromise = fs
-  .readFile('./config.json', 'utf-8')
-  .then(JSON.parse)
-const templatePromise = fs.readFile('./template.html', 'utf-8')
-
-export async function processRequest(data: Data) {
-  const [config, template] = await Promise.all([
-    configPromise,
-    templatePromise,
-  ])
-
-  return render(template, data, config)
-}
-```
-
-When to use this pattern:
-
-- Loading fonts for OG image generation
-- Loading static logos, icons, or watermarks
-- Reading configuration files that don't change at runtime
-- Loading email templates or other static templates
-- Any static asset that's the same across all requests
-
-When not to use this pattern:
-
-- Assets that vary per request or user
-- Files that may change during runtime (use caching with TTL instead)
-- Large files that would consume too much memory if kept loaded
-- Sensitive data that shouldn't persist in memory
-
-With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
-
-In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md

@@ -1,50 +0,0 @@
----
-title: Avoid Shared Module State for Request Data
-impact: HIGH
-impactDescription: prevents concurrency bugs and request data leaks
-tags: server, rsc, ssr, concurrency, security, state
----
-
-## Avoid Shared Module State for Request Data
-
-For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
-
-Treat module scope on the server as process-wide shared memory, not request-local state.
-
-**Incorrect (request data leaks across concurrent renders):**
-
-```tsx
-let currentUser: User | null = null
-
-export default async function Page() {
-  currentUser = await auth()
-  return <Dashboard />
-}
-
-async function Dashboard() {
-  return <div>{currentUser?.name}</div>
-}
-```
-
-If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
-
-**Correct (keep request data local to the render tree):**
-
-```tsx
-export default async function Page() {
-  const user = await auth()
-  return <Dashboard user={user} />
-}
-
-function Dashboard({ user }: { user: User | null }) {
-  return <div>{user?.name}</div>
-}
-```
-
-Safe exceptions:
-
-- Immutable static assets or config loaded once at module scope
-- Shared caches intentionally designed for cross-request reuse and keyed correctly
-- Process-wide singletons that do not store request- or user-specific mutable data
-
-For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -1,83 +0,0 @@
----
-title: Parallel Data Fetching with Component Composition
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, composition
----
-
-## Parallel Data Fetching with Component Composition
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect (Sidebar waits for Page's fetch to complete):**
-
-```tsx
-export default async function Page() {
-  const header = await fetchHeader()
-  return (
-    <div>
-      <div>{header}</div>
-      <Sidebar />
-    </div>
-  )
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-```
-
-**Correct (both fetch simultaneously):**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-export default function Page() {
-  return (
-    <div>
-      <Header />
-      <Sidebar />
-    </div>
-  )
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-function Layout({ children }: { children: ReactNode }) {
-  return (
-    <div>
-      <Header />
-      {children}
-    </div>
-  )
-}
-
-export default function Page() {
-  return (
-    <Layout>
-      <Sidebar />
-    </Layout>
-  )
-}
-```

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md

@@ -1,34 +0,0 @@
----
-title: Parallel Nested Data Fetching
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, promise-chaining
----
-
-## Parallel Nested Data Fetching
-
-When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
-
-**Incorrect (a single slow item blocks all nested fetches):**
-
-```tsx
-const chats = await Promise.all(
-  chatIds.map(id => getChat(id))
-)
-
-const chatAuthors = await Promise.all(
-  chats.map(chat => getUser(chat.author))
-)
-```
-
-If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
-
-**Correct (each item chains its own nested fetch):**
-
-```tsx
-const chatAuthors = await Promise.all(
-  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
-)
-```
-
-Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.

package/templates/next/.claude/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -1,38 +0,0 @@
----
-title: Minimize Serialization at RSC Boundaries
-impact: HIGH
-impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
----
-
-## Minimize Serialization at RSC Boundaries
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect (serializes all 50 fields):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()  // 50 fields
-  return <Profile user={user} />
-}
-
-'use client'
-function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>  // uses 1 field
-}
-```
-
-**Correct (serializes only 1 field):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()
-  return <Profile name={user.name} />
-}
-
-'use client'
-function Profile({ name }: { name: string }) {
-  return <div>{name}</div>
-}
-```

package/templates/next/.claude/skills/web-design-guidelines/SKILL.md

@@ -1,39 +0,0 @@
----
-name: web-design-guidelines
-description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
-metadata:
-  author: vercel
-  version: "1.0.0"
-  argument-hint: <file-or-pattern>
----
-
-# Web Interface Guidelines
-
-Review files for compliance with Web Interface Guidelines.
-
-## How It Works
-
-1. Fetch the latest guidelines from the source URL below
-2. Read the specified files (or prompt user for files/pattern)
-3. Check against all rules in the fetched guidelines
-4. Output findings in the terse `file:line` format
-
-## Guidelines Source
-
-Fetch fresh guidelines before each review:
-
-```
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
-
-## Usage
-
-When a user provides a file or pattern argument:
-1. Fetch guidelines from the source URL above
-2. Read the specified files
-3. Apply all rules from the fetched guidelines
-4. Output findings using the format specified in the guidelines
-
-If no files specified, ask the user which files to review.

package/templates/next/CLAUDE.md

@@ -1,42 +0,0 @@
-# CLAUDE.md — Baseline Next.js starter
-
-The cloneable Next.js baseline for GoldenComm projects — the starter for a new
-client project. See the repo-root `CLAUDE.md` for the design-system non-negotiables
-(when this directory is used standalone, those rules ship with `@goldencomm/ds-react`'s
-docs instead). Component docs/demos live in the monorepo's **`apps/docs`** app, NOT
-here — keep this starter lean (no demo-only dependencies).
-
-## Conventions
-- **Consume, don't restyle**: components come from `@goldencomm/ds-react`; look comes
-  from tokens. Per-client branding = override semantic `--gcds-color-*` custom
-  properties (code-side), never fork component CSS.
-- **Tailwind v4 is wired** (`app/globals.css`): Baseline sits in `layer(components)`
-  so utilities beat DS styles; `@goldencomm/ds-core/tailwind-theme` maps the semantic
-  tokens into utility namespaces (`border-border`, `text-muted-foreground`, …) as
-  live var() refs — scheme flips and brand overrides carry into utilities. Use
-  utilities for layout/one-off tweaks; component look still comes from gcds classes.
-- Color scheme: tokens are `light-dark()`; the cookie + inline head script in
-  `app/layout.tsx` is the whole theming mechanism. Keep the modern `browserslist` in
-  `package.json` — transpiling `light-dark()` away breaks the scheme toggle.
-- Heavy deps (TanStack Table, Streamdown, shiki, zxcvbn, Swiper) belong in app code
-  when a project needs them, never in the design system. The docs app carries them
-  for its demos; this starter deliberately does not.
-
-## Skills upkeep
-`.claude/skills/` vendors maintained skills for React/design/AI work:
-`vercel-react-best-practices`, `vercel-composition-patterns`,
-`web-design-guidelines`, `frontend-design`, `ai-sdk`, `ai-elements`,
-`migrate-ai-sdk-v6-to-v7`. AI features are built on **Vercel's AI SDK + AI
-Elements** — use those skills when working on chat/agent UI.
-
-They're copies tracked by this directory's `skills-lock.json` — when asked to
-update skills (or roughly monthly), refresh from upstream:
-
-```
-npx skills update -p -y
-```
-
-(Inside the design-system monorepo, run `pnpm skills:update` at the repo root
-instead — it refreshes and redistributes everywhere.) Review the diff before
-committing. New skills: `npx skills add <owner/repo> --skill <name> --agent
-claude-code --copy -y`.

package/templates/next/README.md

@@ -1,30 +0,0 @@
-# @goldencomm/baseline-next
-
-The **Next.js baseline** — runs the Baseline design system in a real App Router app,
-and doubles as the starter template for new Next.js projects (Phase 5 `create-baseline`).
-
-## What it shows
-- `@goldencomm/ds-core/baseline` loaded once in `app/layout.tsx` (tokens + reset + elements).
-- `@goldencomm/ds-react` `Button` and `IconButton` rendered in a **Server Component**
-  (`app/page.tsx`) — no `'use client'` needed for presentational components.
-- Icons composed as **children** (leading/trailing) via `lucide-react`; `IconButton`
-  for icon-only.
-
-## Run
-
-```bash
-pnpm install            # from the repo root
-pnpm --filter @goldencomm/baseline-next dev   # http://localhost:3100
-```
-
-> Consumes the workspace `ds-core`/`ds-react` `dist` output — run `pnpm build` at the
-> root first (or `pnpm --filter @goldencomm/ds-core --filter @goldencomm/ds-react build`)
-> so the packages are built.
-
-## Notes
-- Per `docs/component-design-principles.md`: keep pages/layouts as Server Components and
-  push `'use client'` to the smallest interactive leaf; wrap server content in client
-  components via `children` (donut pattern) when interactivity is needed.
-- The component reference (docs, demos, patterns) lives in the monorepo's **`apps/docs`**
-  app (`pnpm dev:docs` → http://localhost:3200) — it is intentionally NOT part of this
-  starter, so cloned projects stay lean.

package/templates/next/_gitignore

@@ -1,4 +0,0 @@
-/.next/
-/out/
-next-env.d.ts
-*.tsbuildinfo

package/templates/next/app/layout.tsx

@@ -1,44 +0,0 @@
-import "./globals.css";
-import type { ReactNode } from "react";
-
-export const metadata = {
-  title: "Baseline — Next.js starter",
-  description:
-    "A cloneable Next.js starter wired to the Baseline design system (@goldencomm/ds-core + ds-react).",
-};
-
-/** Browser-chrome color = surface-1 per scheme (white / slate-950). */
-export const viewport = {
-  themeColor: [
-    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
-    { media: "(prefers-color-scheme: dark)", color: "#020617" },
-  ],
-};
-
-/**
- * Root layout — deliberately minimal: this app is a cloneable scaffold. The docs
- * live under /docs (dev-only; they 404 in production builds).
- *
- * The inline script applies a persisted color-scheme choice (the `gcds-scheme`
- * cookie, written by SchemeToggle) before first paint — tokens are `light-dark()`,
- * so setting `color-scheme` on <html> is the entire theme switch. No cookie →
- * follow the system. Pages stay fully static.
- */
-export default function RootLayout({ children }: { children: ReactNode }) {
-  return (
-    // suppressHydrationWarning: the inline script sets color-scheme on <html> from
-    // the cookie BEFORE hydration, so its attributes legitimately differ from the
-    // server render. Opts out for THIS element's attributes only — not the subtree.
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script
-          dangerouslySetInnerHTML={{
-            __html:
-              "var m=document.cookie.match(/(?:^|; )gcds-scheme=(dark|light)/);if(m)document.documentElement.style.colorScheme=m[1];",
-          }}
-        />
-      </head>
-      <body id="top">{children}</body>
-    </html>
-  );
-}

package/templates/next/globals.d.ts

@@ -1,8 +0,0 @@
-// The @goldencomm/ds-core CSS subpath exports resolve to .css files (bundled by
-// Next) and carry no type declarations. Declare them so TypeScript 6's
-// `noUncheckedSideEffectImports` doesn't reject the side-effect import in
-// app/layout.tsx (`import "@goldencomm/ds-core/baseline"`).
-declare module "@goldencomm/ds-core/baseline";
-declare module "@goldencomm/ds-core/css";
-declare module "@goldencomm/ds-core/reset";
-declare module "@goldencomm/ds-core/elements";

package/templates/next/next.config.mjs

@@ -1,6 +0,0 @@
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-};
-
-export default nextConfig;

package/templates/next/package.json

@@ -1,38 +0,0 @@
-{
-  "name": "@goldencomm/baseline-next",
-  "version": "0.0.0",
-  "private": true,
-  "description": "Baseline Next.js starter — a cloneable App Router scaffold wired to the design system (ds-core + ds-react). Component docs live in apps/docs.",
-  "type": "module",
-  "browserslist": [
-    "chrome >= 125",
-    "edge >= 125",
-    "firefox >= 125",
-    "safari >= 17.5"
-  ],
-  "scripts": {
-    "dev": "next dev -p 3100",
-    "build": "next build",
-    "start": "next start -p 3100",
-    "typecheck": "tsc --noEmit",
-    "lint": "echo \"(no lint configured yet)\"",
-    "test": "echo \"(no tests yet)\"",
-    "clean": "rm -rf .next"
-  },
-  "dependencies": {
-    "@goldencomm/ds-core": "workspace:*",
-    "@goldencomm/ds-react": "workspace:*",
-    "lucide-react": "^1.23.0",
-    "next": "^16.2.9",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.0",
-    "@types/node": "^26.0.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "tailwindcss": "^4.1.0",
-    "typescript": "^6.0.3"
-  }
-}

package/templates/next/postcss.config.mjs

@@ -1,5 +0,0 @@
-export default {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-};