fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: ui now optional — prerequisite notes + conditional HTML

Browse Source 
- AGENTS.md (root): marks core-ui as optional in the package table and
  boundary rules; points per-package docs to the .hbs template
- apps/storybook/AGENTS.md: rewrites around no-core-ui-by-default;
  stories glob and globals.css import described as post-scaffold steps
- apps/web-next/AGENTS.md: cross-reference updated to template file
- apps/web-tanstack/AGENTS.md: cross-reference updated to template file
- docs/architecture/data-flow-explainer.html: core-ui bullet notes
  optional status + generator command

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Danijel Martinek
2026-05-09 14:23:24 +02:00
parent a4c8f710a6
commit ae456a5436
5 changed files with 18 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
AGENTS.md
View File

@@ -9,7 +9,7 @@ This is a **Turborepo + pnpm monorepo** organized by vertical features. Each fea
| Package | Tag | Purpose | | Package | Tag | Purpose |
|---|---|---| |---|---|---|
| `@repo/core-shared` | core | Generic primitives (Zod, env, Payload hooks/fields/blocks, tRPC init/context) | | `@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/<feature>/api` only | | `@repo/core-api` | core-composition | tRPC router aggregator — imports `@repo/<feature>/api` only |
| `@repo/core-cms` | core-composition | Payload config aggregator — imports `@repo/<feature>/cms` only | | `@repo/core-cms` | core-composition | Payload config aggregator — imports `@repo/<feature>/cms` only |
| `@repo/core-trpc` | core-composition | Frontend tRPC client + framework-specific providers (Next.js, TanStack) | | `@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` - **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-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` - **feature** (5 packages) — `packages/auth`, `blog`, `media`, `marketing-pages`, `navigation`
- **tooling** (3 packages) — `packages/core-eslint`, `core-typescript`, `core-testing` - **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`: Per-package documentation lives in each `AGENTS.md`:
- `packages/core-shared/AGENTS.md` - `packages/core-shared/AGENTS.md`
- `packages/core-api/AGENTS.md`, `core-cms/AGENTS.md`, `core-trpc/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/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` - `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` - `apps/cms/AGENTS.md`, `web-next/AGENTS.md`, `web-tanstack/AGENTS.md`, `storybook/AGENTS.md`

21
apps/storybook/AGENTS.md
View File

@@ -1,10 +1,12 @@
# AGENTS.md — apps/storybook # 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 ## 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 ## Port: 6006
@@ -16,7 +18,7 @@ pnpm dev --filter @repo/storybook # http://localhost:6006
### `.storybook/main.ts` ### `.storybook/main.ts`
Stories are discovered from `@repo/core-ui`: Stories are empty by default. After scaffolding `@repo/core-ui`, add the glob:
```typescript ```typescript
const config: StorybookConfig = { const config: StorybookConfig = {
@@ -35,17 +37,17 @@ const config: StorybookConfig = {
``` ```
Key settings: 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 - **`viteFinal`** — adds Tailwind v4 plugin so classes render in Storybook
- **`autodocs: "tag"`** — auto-generates docs for tagged stories - **`autodocs: "tag"`** — auto-generates docs for tagged stories
### `.storybook/preview.ts` ### `.storybook/preview.ts`
Imports global styles: After scaffolding `@repo/core-ui`, import global styles here:
```typescript ```typescript
import type { Preview } from "@storybook/react"; import type { Preview } from "@storybook/react";
import "../../../packages/core-ui/src/styles/globals.css"; import "@repo/core-ui/styles/globals.css";
const preview: Preview = { const preview: Preview = {
parameters: { parameters: {
@@ -70,7 +72,7 @@ Stories are organized by Atomic Design level via the `title` field:
| Organism | `"Organisms/{ComponentName}"` | Organisms > ComponentName | | Organism | `"Organisms/{ComponentName}"` | Organisms > ComponentName |
| Template | `"Templates/{ComponentName}"` | Templates > 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 ```typescript
import type { Meta, StoryObj } from "@storybook/react"; import type { Meta, StoryObj } from "@storybook/react";
@@ -118,7 +120,7 @@ http://localhost:6006/mcp
| Dependency | Purpose | | 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/react-vite` | Storybook with Vite bundler |
| `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds | | `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds |
| `@tailwindcss/vite` | Vite plugin for Tailwind v4 | | `@tailwindcss/vite` | Vite plugin for Tailwind v4 |
@@ -129,5 +131,6 @@ http://localhost:6006/mcp
## Cross-References ## 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 - **Storybook docs:** `.storybook/` folder

2
apps/web-next/AGENTS.md
View File

@@ -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}/` - **Feature packages:** `packages/{auth,blog,media,marketing-pages,navigation}/`
- **tRPC composition:** `packages/core-api/AGENTS.md` - **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` - **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`

2
apps/web-tanstack/AGENTS.md
View File

@@ -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}/` - **Feature packages:** `packages/{auth,blog,media,marketing-pages,navigation}/`
- **tRPC composition:** `packages/core-api/AGENTS.md` - **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` - **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` - **Next.js app (serves tRPC):** `apps/web-next/AGENTS.md`

2
docs/architecture/data-flow-explainer.html
View File

@@ -2284,7 +2284,7 @@ footer .colophon {
<div class="pros"><h5>Pros</h5><ul> <div class="pros"><h5>Pros</h5><ul>
<li>Apps depend on the feature's UI surface explicitly — clear separation from contracts</li> <li>Apps depend on the feature's UI surface explicitly — clear separation from contracts</li>
<li>Query builders sit next to the data they query — refactoring is local</li> <li>Query builders sit next to the data they query — refactoring is local</li>
<li>Components for feature-specific UI (e.g. <code>ArticleCard</code>) live with the feature, not in <code>core-ui</code></li> <li>Components for feature-specific UI (e.g. <code>ArticleCard</code>) live with the feature, not in <code>core-ui</code> (<em>optional package — scaffold via <code>pnpm turbo gen core-package ui</code></em>)</li>
</ul></div> </ul></div>
<div class="cons"><h5>Cons</h5><ul> <div class="cons"><h5>Cons</h5><ul>
<li>Features without UI today (auth, media) still need a placeholder <code>export {}</code></li> <li>Features without UI today (auth, media) still need a placeholder <code>export {}</code></li>