From 5f9a43441f07f8cadcece0fcc52015f21dcfa0a8 Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Mon, 11 May 2026 09:21:52 +0200
Subject: [PATCH] docs(scaffolding): core-ui component generator reference

---
 .../core-ui-component-generator.md            | 62 +++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/scaffolding/core-ui-component-generator.md

diff --git a/docs/scaffolding/core-ui-component-generator.md b/docs/scaffolding/core-ui-component-generator.md
new file mode 100644
index 0000000..74e209a
--- /dev/null
+++ b/docs/scaffolding/core-ui-component-generator.md
@@ -0,0 +1,62 @@
+# core-ui component generator
+
+`pnpm turbo gen core-ui-component` scaffolds an atomic-design component (atom / molecule / organism) into `packages/core-ui/` using the established 4-file pattern.
+
+**Prerequisite:** `packages/core-ui/` must exist. If your project started from the slim template, scaffold core-ui first via `pnpm turbo gen core-package ui`.
+
+## Usage
+
+```bash
+pnpm turbo gen core-ui-component
+# → Tier: (use arrow keys)
+#     ❯ atom
+#       molecule
+#       organism
+# → Component name (PascalCase, e.g. Spinner):
+#     › Spinner
+```
+
+The generator emits 4 files into `packages/core-ui/src/<tier>s/<kebab-name>/`:
+
+| File | Purpose |
+|---|---|
+| `<kebab-name>.tsx` | Component implementation (forwardRef + cn + className passthrough) |
+| `<kebab-name>.stories.tsx` | Storybook stories (Meta + StoryObj + one Default story; tier-prefixed title) |
+| `<kebab-name>.test.tsx` | Vitest + Testing Library smoke tests (renders, className passthrough, ref forwarding) |
+| `index.ts` | Barrel that re-exports the component + Props type |
+
+The new export is also spliced into `packages/core-ui/src/<tier>s/index.ts` immediately after the `// <gen:<tier>s>` anchor, so the component is reachable from the tier barrel (and transitively from the root `@repo/core-ui` export) without any manual wiring.
+
+## Generated scaffold (example: `pnpm turbo gen core-ui-component` → atom → Spinner)
+
+```
+packages/core-ui/src/atoms/spinner/
+├── spinner.tsx           # forwardRef<HTMLDivElement, SpinnerProps>
+├── spinner.stories.tsx   # title: "Atoms/Spinner"
+├── spinner.test.tsx      # 3 smoke tests
+└── index.ts              # export { Spinner, type SpinnerProps }
+```
+
+And in `packages/core-ui/src/atoms/index.ts`:
+
+```ts
+// <gen:atoms>
+export { Spinner, type SpinnerProps } from "./spinner/index";
+export { Button, type ButtonProps } from "./button/index";
+// ...
+```
+
+## Customizing the scaffold
+
+The generated component is a minimal `<div>` passthrough — change the element/type and add variants/sizes to fit. The existing `button.tsx` in `src/atoms/button/` is the canonical reference for a richer component with `variant` and `size` props plus variant lookup tables.
+
+## Verification
+
+After scaffolding:
+
+```bash
+pnpm --filter @repo/core-ui lint typecheck test
+pnpm dev --filter @repo/storybook   # view the new component in Storybook
+```
+
+The Storybook stories glob (`packages/core-ui/src/**/*.stories.@(ts|tsx)`) picks up the new file automatically — no Storybook config changes needed.