From d974bb626770304b1f87f3ef479794f1fe9c0f39 Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Sat, 9 May 2026 14:17:47 +0200
Subject: [PATCH] feat(generators): capture core-ui as verbatim template files

28 .hbs files mirror packages/core-ui verbatim:
atoms (Button, Input, Label + stories + tests), molecules (FormField),
organisms/templates (empty barrels), lib/utils, styles/globals.css,
plus all root config files (package.json, tsconfig.json, vitest.config.ts,
eslint.config.js, turbo.json, AGENTS.md).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../templates/core-package/ui/AGENTS.md.hbs   | 67 +++++++++++++++++++
 .../core-package/ui/eslint.config.js.hbs      |  3 +
 .../core-package/ui/package.json.hbs          | 33 +++++++++
 .../src/atoms/button/button.stories.tsx.hbs   | 38 +++++++++++
 .../ui/src/atoms/button/button.test.tsx.hbs   | 42 ++++++++++++
 .../ui/src/atoms/button/button.tsx.hbs        | 41 ++++++++++++
 .../ui/src/atoms/button/index.ts.hbs          |  1 +
 .../core-package/ui/src/atoms/index.ts.hbs    |  3 +
 .../ui/src/atoms/input/index.ts.hbs           |  1 +
 .../ui/src/atoms/input/input.stories.tsx.hbs  | 19 ++++++
 .../ui/src/atoms/input/input.test.tsx.hbs     | 31 +++++++++
 .../ui/src/atoms/input/input.tsx.hbs          | 21 ++++++
 .../ui/src/atoms/label/index.ts.hbs           |  1 +
 .../ui/src/atoms/label/label.test.tsx.hbs     | 16 +++++
 .../ui/src/atoms/label/label.tsx.hbs          | 20 ++++++
 .../core-package/ui/src/index.ts.hbs          |  5 ++
 .../core-package/ui/src/lib/utils.ts.hbs      |  6 ++
 .../form-field/form-field.stories.tsx.hbs     | 31 +++++++++
 .../form-field/form-field.test.tsx.hbs        | 33 +++++++++
 .../molecules/form-field/form-field.tsx.hbs   | 31 +++++++++
 .../ui/src/molecules/form-field/index.ts.hbs  |  1 +
 .../ui/src/molecules/index.ts.hbs             |  1 +
 .../ui/src/organisms/index.ts.hbs             |  1 +
 .../ui/src/styles/globals.css.hbs             | 26 +++++++
 .../ui/src/templates/index.ts.hbs             |  1 +
 .../core-package/ui/tsconfig.json.hbs         | 13 ++++
 .../templates/core-package/ui/turbo.json.hbs  |  4 ++
 .../core-package/ui/vitest.config.ts.hbs      |  9 +++
 28 files changed, 499 insertions(+)
 create mode 100644 turbo/generators/templates/core-package/ui/AGENTS.md.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/eslint.config.js.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/package.json.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/button/button.stories.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/button/button.test.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/button/button.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/button/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/input/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/input/input.stories.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/input/input.test.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/input/input.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/label/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/label/label.test.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/atoms/label/label.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/lib/utils.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.stories.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.test.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.tsx.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/molecules/form-field/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/molecules/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/organisms/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/styles/globals.css.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/src/templates/index.ts.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/tsconfig.json.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/turbo.json.hbs
 create mode 100644 turbo/generators/templates/core-package/ui/vitest.config.ts.hbs

diff --git a/turbo/generators/templates/core-package/ui/AGENTS.md.hbs b/turbo/generators/templates/core-package/ui/AGENTS.md.hbs
new file mode 100644
index 0000000..a984ec8
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/AGENTS.md.hbs
@@ -0,0 +1,67 @@
+# AGENTS.md — core-ui
+
+Design-system primitives organized by Atomic Design. Only **generic components** (atoms, molecules, generic organisms) live here. Feature-specific components live in their respective feature packages.
+
+## Responsibilities
+
+- **Atoms** — Single HTML elements: Button, Input, Label, Card
+- **Molecules** — Combinations: FormField (Label + Input), Badge, Avatar
+- **Generic Organisms** — Reusable complex layouts: Modal, Tabs, NavigationMenu, CommandPalette
+- **Templates** — Page layouts: AuthLayout, DashboardLayout, LandingLayout
+- **Utilities** — `cn()` for className merging, design tokens, Tailwind config
+
+## Feature-specific boundary
+
+Feature-specific organisms (e.g., `ArticleCard`, `ArticleList`, `HeaderNavMenu`) live in their feature's `ui/` folder, NOT here. This boundary keeps `core-ui` framework-agnostic and reusable.
+
+## Must NOT import
+
+- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`
+
+> Note: `@repo/core-trpc` is an optional package scaffolded via `pnpm turbo gen core-package trpc`. If not present, this constraint still applies to any future installation.
+
+## Public exports
+
+From `package.json`:
+- `.` — all atoms, molecules, organisms, templates
+
+Example usage:
+```typescript
+import { Button, Input, Label } from "@repo/core-ui";
+import { FormField } from "@repo/core-ui";
+import { Modal, Tabs } from "@repo/core-ui";
+```
+
+## Test conventions
+
+- Tests colocated: `src/atoms/button/button.tsx` → `src/atoms/button/button.test.tsx`
+- Vitest environment: `jsdom` (React component testing)
+- Alias: `@/` resolves to `src/`
+- Run: `pnpm test --filter @repo/core-ui`
+- Storybook stories colocated: `src/atoms/button/button.stories.tsx`
+
+## Structure
+
+```
+src/
+  atoms/
+    {name}/
+      {name}.tsx             # Component
+      {name}.test.tsx        # Tests
+      {name}.stories.tsx     # Storybook story
+      index.ts               # Barrel export
+  molecules/
+    {name}/
+      ...
+  organisms/
+    {name}/
+      ...
+  templates/
+    {name}/
+      ...
+  lib/
+    utils.ts                 # cn() and helpers
+  index.ts                   # Re-exports everything
+```
diff --git a/turbo/generators/templates/core-package/ui/eslint.config.js.hbs b/turbo/generators/templates/core-package/ui/eslint.config.js.hbs
new file mode 100644
index 0000000..7440d8f
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/eslint.config.js.hbs
@@ -0,0 +1,3 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default baseConfig;
diff --git a/turbo/generators/templates/core-package/ui/package.json.hbs b/turbo/generators/templates/core-package/ui/package.json.hbs
new file mode 100644
index 0000000..e9354e2
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/package.json.hbs
@@ -0,0 +1,33 @@
+{
+  "name": "@repo/core-ui",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles/globals.css": "./src/styles/globals.css"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "react": "^19.0.0",
+    "tailwind-merge": "^3.0.0"
+  },
+  "devDependencies": {
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@storybook/react": "^8.6.0",
+    "@testing-library/jest-dom": "^6.5.0",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.0",
+    "vitest": "^3.0.0"
+  }
+}
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/button/button.stories.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/button/button.stories.tsx.hbs
new file mode 100644
index 0000000..094736a
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/button/button.stories.tsx.hbs
@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+
+const meta = {
+  title: "Atoms/Button",
+  component: Button,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "secondary", "destructive", "outline", "ghost"],
+    },
+    size: { control: "select", options: ["sm", "default", "lg"] },
+  },
+} satisfies Meta<typeof Button>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: "Button", variant: "default" },
+};
+
+export const Secondary: Story = {
+  args: { children: "Secondary", variant: "secondary" },
+};
+
+export const Destructive: Story = {
+  args: { children: "Destructive", variant: "destructive" },
+};
+
+export const Outline: Story = {
+  args: { children: "Outline", variant: "outline" },
+};
+
+export const Ghost: Story = {
+  args: { children: "Ghost", variant: "ghost" },
+};
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/button/button.test.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/button/button.test.tsx.hbs
new file mode 100644
index 0000000..bcf664f
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/button/button.test.tsx.hbs
@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderWithProviders } from "@repo/core-testing/react";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Button } from "./button";
+
+describe("Button", () => {
+  it("renders children inside a button", () => {
+    renderWithProviders(<Button>Click me</Button>);
+    expect(screen.getByRole("button", { name: "Click me" })).toBeInTheDocument();
+  });
+
+  it("calls onClick when activated", async () => {
+    const handleClick = vi.fn();
+    renderWithProviders(<Button onClick={handleClick}>Go</Button>);
+    await userEvent.click(screen.getByRole("button", { name: "Go" }));
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+
+  it("applies the destructive variant class", () => {
+    renderWithProviders(<Button variant="destructive">X</Button>);
+    expect(screen.getByRole("button")).toHaveClass(/destructive/);
+  });
+
+  it("applies the lg size class", () => {
+    renderWithProviders(<Button size="lg">X</Button>);
+    expect(screen.getByRole("button")).toHaveClass(/h-11/);
+  });
+
+  it("disabled prop sets the attribute and prevents click handler", async () => {
+    const handleClick = vi.fn();
+    renderWithProviders(
+      <Button disabled onClick={handleClick}>
+        X
+      </Button>,
+    );
+    const button = screen.getByRole("button");
+    expect(button).toBeDisabled();
+    await userEvent.click(button);
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+});
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/button/button.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/button/button.tsx.hbs
new file mode 100644
index 0000000..38564ed
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/button/button.tsx.hbs
@@ -0,0 +1,41 @@
+import { forwardRef, type ButtonHTMLAttributes } from "react";
+import { cn } from "../../lib/utils";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "default" | "secondary" | "destructive" | "outline" | "ghost";
+  size?: "sm" | "default" | "lg";
+}
+
+const variantStyles: Record<NonNullable<ButtonProps["variant"]>, string> = {
+  default: "bg-primary text-primary-foreground hover:bg-primary/90",
+  secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+  destructive:
+    "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+  outline:
+    "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+  ghost: "hover:bg-accent hover:text-accent-foreground",
+};
+
+const sizeStyles: Record<NonNullable<ButtonProps["size"]>, string> = {
+  sm: "h-9 px-3 text-sm",
+  default: "h-10 px-4 py-2",
+  lg: "h-11 px-8 text-lg",
+};
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant = "default", size = "default", ...props }, ref) => {
+    return (
+      <button
+        className={cn(
+          "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+          variantStyles[variant],
+          sizeStyles[size],
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = "Button";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/button/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/atoms/button/index.ts.hbs
new file mode 100644
index 0000000..f4ea832
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/button/index.ts.hbs
@@ -0,0 +1 @@
+export { Button, type ButtonProps } from "./button";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/atoms/index.ts.hbs
new file mode 100644
index 0000000..51482ab
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/index.ts.hbs
@@ -0,0 +1,3 @@
+export { Button, type ButtonProps } from "./button/index";
+export { Input, type InputProps } from "./input/index";
+export { Label, type LabelProps } from "./label/index";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/input/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/atoms/input/index.ts.hbs
new file mode 100644
index 0000000..af6d92a
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/input/index.ts.hbs
@@ -0,0 +1 @@
+export { Input, type InputProps } from "./input";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/input/input.stories.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/input/input.stories.tsx.hbs
new file mode 100644
index 0000000..74b69af
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/input/input.stories.tsx.hbs
@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Input } from "./input";
+
+const meta = {
+  title: "Atoms/Input",
+  component: Input,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Input>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { placeholder: "Enter text..." },
+};
+
+export const Disabled: Story = {
+  args: { placeholder: "Disabled", disabled: true },
+};
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/input/input.test.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/input/input.test.tsx.hbs
new file mode 100644
index 0000000..aa49087
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/input/input.test.tsx.hbs
@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { renderWithProviders } from "@repo/core-testing/react";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Input } from "./input";
+
+describe("Input", () => {
+  it("renders an input with the given placeholder", () => {
+    renderWithProviders(<Input placeholder="email" />);
+    expect(screen.getByPlaceholderText("email")).toBeInTheDocument();
+  });
+
+  it("forwards the type attribute", () => {
+    renderWithProviders(<Input type="email" placeholder="email" />);
+    expect(screen.getByPlaceholderText("email")).toHaveAttribute("type", "email");
+  });
+
+  it("accepts user input", async () => {
+    renderWithProviders(<Input placeholder="email" />);
+    const input = screen.getByPlaceholderText("email");
+    await userEvent.type(input, "hi@example.com");
+    expect(input).toHaveValue("hi@example.com");
+  });
+
+  it("disabled prop blocks user input", async () => {
+    renderWithProviders(<Input placeholder="email" disabled />);
+    const input = screen.getByPlaceholderText("email");
+    await userEvent.type(input, "hi");
+    expect(input).toHaveValue("");
+  });
+});
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/input/input.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/input/input.tsx.hbs
new file mode 100644
index 0000000..b925986
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/input/input.tsx.hbs
@@ -0,0 +1,21 @@
+import { forwardRef, type InputHTMLAttributes } from "react";
+import { cn } from "../../lib/utils";
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Input.displayName = "Input";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/label/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/atoms/label/index.ts.hbs
new file mode 100644
index 0000000..7d4a6c5
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/label/index.ts.hbs
@@ -0,0 +1 @@
+export { Label, type LabelProps } from "./label";
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/label/label.test.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/label/label.test.tsx.hbs
new file mode 100644
index 0000000..d48b31d
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/label/label.test.tsx.hbs
@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { renderWithProviders } from "@repo/core-testing/react";
+import { screen } from "@testing-library/react";
+import { Label } from "./label";
+
+describe("Label", () => {
+  it("renders the label text", () => {
+    renderWithProviders(<Label htmlFor="email">Email</Label>);
+    expect(screen.getByText("Email")).toBeInTheDocument();
+  });
+
+  it("forwards htmlFor to associate with an input", () => {
+    renderWithProviders(<Label htmlFor="email">Email</Label>);
+    expect(screen.getByText("Email")).toHaveAttribute("for", "email");
+  });
+});
diff --git a/turbo/generators/templates/core-package/ui/src/atoms/label/label.tsx.hbs b/turbo/generators/templates/core-package/ui/src/atoms/label/label.tsx.hbs
new file mode 100644
index 0000000..afc57b1
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/atoms/label/label.tsx.hbs
@@ -0,0 +1,20 @@
+import { forwardRef, type LabelHTMLAttributes } from "react";
+import { cn } from "../../lib/utils";
+
+export type LabelProps = LabelHTMLAttributes<HTMLLabelElement>;
+
+export const Label = forwardRef<HTMLLabelElement, LabelProps>(
+  ({ className, ...props }, ref) => {
+    return (
+      <label
+        className={cn(
+          "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Label.displayName = "Label";
diff --git a/turbo/generators/templates/core-package/ui/src/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/index.ts.hbs
new file mode 100644
index 0000000..2ec687a
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/index.ts.hbs
@@ -0,0 +1,5 @@
+export { cn } from "./lib/utils";
+export * from "./atoms/index";
+export * from "./molecules/index";
+export * from "./organisms/index";
+export * from "./templates/index";
diff --git a/turbo/generators/templates/core-package/ui/src/lib/utils.ts.hbs b/turbo/generators/templates/core-package/ui/src/lib/utils.ts.hbs
new file mode 100644
index 0000000..a5ef193
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/lib/utils.ts.hbs
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
diff --git a/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.stories.tsx.hbs b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.stories.tsx.hbs
new file mode 100644
index 0000000..de769e3
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.stories.tsx.hbs
@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FormField } from "./form-field";
+
+const meta = {
+  title: "Molecules/FormField",
+  component: FormField,
+  tags: ["autodocs"],
+} satisfies Meta<typeof FormField>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: "Email", placeholder: "you@example.com", type: "email" },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: "Username",
+    placeholder: "johndoe",
+    description: "Must be 3-31 characters",
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    label: "Password",
+    type: "password",
+    error: "Password must be at least 6 characters",
+  },
+};
diff --git a/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.test.tsx.hbs b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.test.tsx.hbs
new file mode 100644
index 0000000..925ecf3
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.test.tsx.hbs
@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { renderWithProviders } from "@repo/core-testing/react";
+import { screen } from "@testing-library/react";
+import { FormField } from "./form-field";
+
+describe("FormField", () => {
+  it("renders label associated with input via auto-derived id", () => {
+    renderWithProviders(<FormField label="Email Address" />);
+    const input = screen.getByLabelText("Email Address");
+    expect(input).toBeInTheDocument();
+    expect(input).toHaveAttribute("id", "email-address");
+  });
+
+  it("uses an explicit id over the derived one", () => {
+    renderWithProviders(<FormField label="Email" id="custom-id" />);
+    expect(screen.getByLabelText("Email")).toHaveAttribute("id", "custom-id");
+  });
+
+  it("renders a description when provided", () => {
+    renderWithProviders(<FormField label="Email" description="We never share it." />);
+    expect(screen.getByText("We never share it.")).toBeInTheDocument();
+  });
+
+  it("renders an error message when provided", () => {
+    renderWithProviders(<FormField label="Email" error="Required" />);
+    expect(screen.getByText("Required")).toBeInTheDocument();
+  });
+
+  it("forwards input props (e.g., type) to the underlying input", () => {
+    renderWithProviders(<FormField label="Email" type="email" />);
+    expect(screen.getByLabelText("Email")).toHaveAttribute("type", "email");
+  });
+});
diff --git a/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.tsx.hbs b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.tsx.hbs
new file mode 100644
index 0000000..d7d9322
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/molecules/form-field/form-field.tsx.hbs
@@ -0,0 +1,31 @@
+import { Label } from "../../atoms/label/index";
+import { Input, type InputProps } from "../../atoms/input/index";
+import { cn } from "../../lib/utils";
+
+export interface FormFieldProps extends InputProps {
+  label: string;
+  error?: string;
+  description?: string;
+}
+
+export function FormField({
+  label,
+  error,
+  description,
+  className,
+  id,
+  ...inputProps
+}: FormFieldProps) {
+  const fieldId = id ?? label.toLowerCase().replace(/\s+/g, "-");
+
+  return (
+    <div className={cn("space-y-2", className)}>
+      <Label htmlFor={fieldId}>{label}</Label>
+      <Input id={fieldId} {...inputProps} />
+      {description && (
+        <p className="text-sm text-muted-foreground">{description}</p>
+      )}
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}
diff --git a/turbo/generators/templates/core-package/ui/src/molecules/form-field/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/molecules/form-field/index.ts.hbs
new file mode 100644
index 0000000..58d4e76
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/molecules/form-field/index.ts.hbs
@@ -0,0 +1 @@
+export { FormField, type FormFieldProps } from "./form-field";
diff --git a/turbo/generators/templates/core-package/ui/src/molecules/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/molecules/index.ts.hbs
new file mode 100644
index 0000000..5ad534d
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/molecules/index.ts.hbs
@@ -0,0 +1 @@
+export { FormField, type FormFieldProps } from "./form-field/index";
diff --git a/turbo/generators/templates/core-package/ui/src/organisms/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/organisms/index.ts.hbs
new file mode 100644
index 0000000..cb0ff5c
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/organisms/index.ts.hbs
@@ -0,0 +1 @@
+export {};
diff --git a/turbo/generators/templates/core-package/ui/src/styles/globals.css.hbs b/turbo/generators/templates/core-package/ui/src/styles/globals.css.hbs
new file mode 100644
index 0000000..2eb4936
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/styles/globals.css.hbs
@@ -0,0 +1,26 @@
+@import "tailwindcss";
+
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(240 10% 3.9%);
+  --color-card: hsl(0 0% 100%);
+  --color-card-foreground: hsl(240 10% 3.9%);
+  --color-popover: hsl(0 0% 100%);
+  --color-popover-foreground: hsl(240 10% 3.9%);
+  --color-primary: hsl(240 5.9% 10%);
+  --color-primary-foreground: hsl(0 0% 98%);
+  --color-secondary: hsl(240 4.8% 95.9%);
+  --color-secondary-foreground: hsl(240 5.9% 10%);
+  --color-muted: hsl(240 4.8% 95.9%);
+  --color-muted-foreground: hsl(240 3.8% 46.1%);
+  --color-accent: hsl(240 4.8% 95.9%);
+  --color-accent-foreground: hsl(240 5.9% 10%);
+  --color-destructive: hsl(0 84.2% 60.2%);
+  --color-destructive-foreground: hsl(0 0% 98%);
+  --color-border: hsl(240 5.9% 90%);
+  --color-input: hsl(240 5.9% 90%);
+  --color-ring: hsl(240 5.9% 10%);
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+}
diff --git a/turbo/generators/templates/core-package/ui/src/templates/index.ts.hbs b/turbo/generators/templates/core-package/ui/src/templates/index.ts.hbs
new file mode 100644
index 0000000..cb0ff5c
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/src/templates/index.ts.hbs
@@ -0,0 +1 @@
+export {};
diff --git a/turbo/generators/templates/core-package/ui/tsconfig.json.hbs b/turbo/generators/templates/core-package/ui/tsconfig.json.hbs
new file mode 100644
index 0000000..741720b
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/tsconfig.json.hbs
@@ -0,0 +1,13 @@
+{
+  "extends": "@repo/core-typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.stories.tsx", "**/*.stories.ts"]
+}
diff --git a/turbo/generators/templates/core-package/ui/turbo.json.hbs b/turbo/generators/templates/core-package/ui/turbo.json.hbs
new file mode 100644
index 0000000..dcb8fb3
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/turbo.json.hbs
@@ -0,0 +1,4 @@
+{
+  "extends": ["//"],
+  "tags": ["core"]
+}
diff --git a/turbo/generators/templates/core-package/ui/vitest.config.ts.hbs b/turbo/generators/templates/core-package/ui/vitest.config.ts.hbs
new file mode 100644
index 0000000..8f3f7d7
--- /dev/null
+++ b/turbo/generators/templates/core-package/ui/vitest.config.ts.hbs
@@ -0,0 +1,9 @@
+import path from "node:path";
+import { mergeConfig } from "vitest/config";
+import { jsdomVitestConfig } from "@repo/core-typescript/vitest.base.jsdom";
+
+export default mergeConfig(jsdomVitestConfig, {
+  resolve: {
+    alias: { "@": path.resolve(__dirname, "./src") },
+  },
+});