diff --git a/AGENTS.md b/AGENTS.md index a06118c..b8244f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ This is a **Turborepo + pnpm monorepo** organized by vertical features. Each fea | Package | Tag | Purpose | |---|---|---| | `@repo/core-shared` | core | Generic primitives (Zod, env, Payload hooks/fields/blocks, tRPC init/context) | -| `@repo/core-ui` | core | Design system (atoms, molecules, generic organisms, templates) | +| `@repo/core-ui` | core | Design system (atoms, molecules, generic organisms, templates) — **optional**, scaffold via `pnpm turbo gen core-package ui` | | `@repo/core-api` | core-composition | tRPC router aggregator — imports `@repo//api` only | | `@repo/core-cms` | core-composition | Payload config aggregator — imports `@repo//cms` only | | `@repo/core-trpc` | core-composition | Frontend tRPC client + framework-specific providers (Next.js, TanStack) | @@ -30,7 +30,7 @@ This is a **Turborepo + pnpm monorepo** organized by vertical features. Each fea - **app** (4 packages) — `apps/web-next`, `apps/web-tanstack`, `apps/cms`, `apps/storybook` - **core-composition** (3 packages) — `packages/core-api`, `core-cms`, `core-trpc` -- **core** (2 packages) — `packages/core-shared`, `core-ui` +- **core** (1–2 packages) — `packages/core-shared`; `core-ui` is optional (scaffold with `pnpm turbo gen core-package ui`) - **feature** (5 packages) — `packages/auth`, `blog`, `media`, `marketing-pages`, `navigation` - **tooling** (3 packages) — `packages/core-eslint`, `core-typescript`, `core-testing` @@ -505,7 +505,7 @@ Feature packages MUST NOT `import "@sentry/*"`. Allowlist: Per-package documentation lives in each `AGENTS.md`: - `packages/core-shared/AGENTS.md` - `packages/core-api/AGENTS.md`, `core-cms/AGENTS.md`, `core-trpc/AGENTS.md` -- `packages/core-ui/AGENTS.md` +- `packages/core-ui/AGENTS.md` (optional — generated by `pnpm turbo gen core-package ui`; see `turbo/generators/templates/core-package/ui/AGENTS.md.hbs`) - `packages/auth/AGENTS.md`, `blog/AGENTS.md`, `media/AGENTS.md`, `marketing-pages/AGENTS.md`, `navigation/AGENTS.md` - `packages/core-eslint/AGENTS.md`, `core-typescript/AGENTS.md`, `core-testing/AGENTS.md` - `apps/cms/AGENTS.md`, `web-next/AGENTS.md`, `web-tanstack/AGENTS.md`, `storybook/AGENTS.md` diff --git a/apps/storybook/AGENTS.md b/apps/storybook/AGENTS.md index eb4b6c1..15fbd4c 100644 --- a/apps/storybook/AGENTS.md +++ b/apps/storybook/AGENTS.md @@ -1,10 +1,12 @@ # AGENTS.md — apps/storybook -Centralized Storybook instance pulling stories from `@repo/core-ui`. Provides visual component development, documentation, and MCP integration for AI agents. +Centralized Storybook instance for visual component development, documentation, and MCP integration for AI agents. Currently ships with an empty stories list — scaffold `@repo/core-ui` first to populate it. ## Purpose -Visual testing and documentation hub for the design system. All stories live colocated with their components in `@repo/core-ui`. Storybook serves as the single source of truth for component usage. +Visual testing and documentation hub for the design system. When `@repo/core-ui` is scaffolded, stories live colocated with their components there. Storybook serves as the single source of truth for component usage. + +> **core-ui is optional.** Scaffold it with `pnpm turbo gen core-package ui`, then add the stories glob and CSS import (see next-steps printed by the generator). ## Port: 6006 @@ -16,7 +18,7 @@ pnpm dev --filter @repo/storybook # http://localhost:6006 ### `.storybook/main.ts` -Stories are discovered from `@repo/core-ui`: +Stories are empty by default. After scaffolding `@repo/core-ui`, add the glob: ```typescript const config: StorybookConfig = { @@ -35,17 +37,17 @@ const config: StorybookConfig = { ``` Key settings: -- **`stories` glob** — reaches into `packages/core-ui/src/` for all `*.stories.tsx` files +- **`stories` glob** — empty by default; add `"../../../packages/core-ui/src/**/*.stories.@(ts|tsx)"` after scaffolding core-ui - **`viteFinal`** — adds Tailwind v4 plugin so classes render in Storybook - **`autodocs: "tag"`** — auto-generates docs for tagged stories ### `.storybook/preview.ts` -Imports global styles: +After scaffolding `@repo/core-ui`, import global styles here: ```typescript import type { Preview } from "@storybook/react"; -import "../../../packages/core-ui/src/styles/globals.css"; +import "@repo/core-ui/styles/globals.css"; const preview: Preview = { parameters: { @@ -70,7 +72,7 @@ Stories are organized by Atomic Design level via the `title` field: | Organism | `"Organisms/{ComponentName}"` | Organisms > ComponentName | | Template | `"Templates/{ComponentName}"` | Templates > ComponentName | -Example story file (`packages/core-ui/src/atoms/button/button.stories.tsx`): +Example story file (after scaffolding core-ui at `packages/core-ui/src/atoms/button/button.stories.tsx`): ```typescript import type { Meta, StoryObj } from "@storybook/react"; @@ -118,7 +120,7 @@ http://localhost:6006/mcp | Dependency | Purpose | |---|---| -| `@repo/core-ui` | Component source + stories | +| `@repo/core-ui` | Component source + stories (optional — scaffold with `pnpm turbo gen core-package ui`) | | `@storybook/react-vite` | Storybook with Vite bundler | | `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds | | `@tailwindcss/vite` | Vite plugin for Tailwind v4 | @@ -129,5 +131,6 @@ http://localhost:6006/mcp ## Cross-References -- **Component source:** `packages/core-ui/AGENTS.md` +- **Component source (when scaffolded):** `packages/core-ui/AGENTS.md` +- **Scaffold core-ui:** `pnpm turbo gen core-package ui` - **Storybook docs:** `.storybook/` folder diff --git a/apps/web-next/AGENTS.md b/apps/web-next/AGENTS.md index 86bde98..5dd5cb0 100644 --- a/apps/web-next/AGENTS.md +++ b/apps/web-next/AGENTS.md @@ -108,4 +108,4 @@ Run: `pnpm test:e2e` starts the dev server and runs all `.spec.ts` files. - **Feature packages:** `packages/{auth,blog,media,marketing-pages,navigation}/` - **tRPC composition:** `packages/core-api/AGENTS.md` - **tRPC client + provider (optional):** scaffold `@repo/core-trpc` first, then see `turbo/generators/templates/core-package/trpc/AGENTS.md.hbs` -- **UI components (optional):** scaffold `@repo/core-ui` first, then see `packages/core-ui/AGENTS.md` +- **UI components (optional):** scaffold with `pnpm turbo gen core-package ui`, then see `turbo/generators/templates/core-package/ui/AGENTS.md.hbs` diff --git a/apps/web-tanstack/AGENTS.md b/apps/web-tanstack/AGENTS.md index da4d722..32cdb6c 100644 --- a/apps/web-tanstack/AGENTS.md +++ b/apps/web-tanstack/AGENTS.md @@ -110,5 +110,5 @@ Parallel to `apps/web-next` e2e: validates that features work across frameworks. - **Feature packages:** `packages/{auth,blog,media,marketing-pages,navigation}/` - **tRPC composition:** `packages/core-api/AGENTS.md` - **tRPC client + provider (optional):** scaffold `@repo/core-trpc` first, then see `turbo/generators/templates/core-package/trpc/AGENTS.md.hbs` -- **UI components (optional):** scaffold `@repo/core-ui` first, then see `packages/core-ui/AGENTS.md` +- **UI components (optional):** scaffold with `pnpm turbo gen core-package ui`, then see `turbo/generators/templates/core-package/ui/AGENTS.md.hbs` - **Next.js app (serves tRPC):** `apps/web-next/AGENTS.md` diff --git a/docs/architecture/data-flow-explainer.html b/docs/architecture/data-flow-explainer.html index 0e1b952..2445be0 100644 --- a/docs/architecture/data-flow-explainer.html +++ b/docs/architecture/data-flow-explainer.html @@ -2284,7 +2284,7 @@ footer .colophon {
Pros
  • Apps depend on the feature's UI surface explicitly — clear separation from contracts
  • Query builders sit next to the data they query — refactoring is local
    • -
  • Components for feature-specific UI (e.g. ArticleCard) live with the feature, not in core-ui
    • +
  • Components for feature-specific UI (e.g. ArticleCard) live with the feature, not in core-ui (optional package — scaffold via pnpm turbo gen core-package ui)
Cons
  • Features without UI today (auth, media) still need a placeholder export {}