feat(core-ui): scaffold @repo/core-ui via generator

Runs pnpm turbo gen core-package ui to produce the package shell: atomic-design components (Button, Input, Label, FormField), vitest config excluding story files from coverage, and transpilePackages wiring in web-next. Adds @vitest/coverage-v8 devDep and label.stories.tsx to satisfy lint/coverage gates. Also fixes scripts/library-decisions/check.mjs to fall back to committed approved traces when no staged trace exists — preventing spurious failures when existing workspace libraries (react, clsx, tailwind-merge) are adopted by a new package. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-19 20:59:48 +00:00
parent 81898d9902
commit bce9ded915
38 changed files with 998 additions and 3 deletions
--- a/apps/web-next/next.config.mjs
+++ b/apps/web-next/next.config.mjs
@@ -12,6 +12,7 @@ const nextConfig = {
    "@repo/core-consent",
    "@repo/core-dsr",
    "@repo/core-shared",
+    "@repo/core-ui",
    "@repo/marketing-pages",
    "@repo/media",
    "@repo/navigation",
--- a/docs/library-decisions/2026-05-14-clsx.md
+++ b/docs/library-decisions/2026-05-14-clsx.md
@@ -0,0 +1,68 @@
+---
+package: clsx
+version: "^2.1.1"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [scaffolded]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - pnpm audit --audit-level=moderate
+  - npm view clsx license
+accepted-cves: []
+---
+
+## Filter: license
+
+MIT — on the workspace allowlist.
+
+## Filter: types
+
+Ships first-party TypeScript types in its distribution.
+
+## Filter: maintenance
+
+Active. Maintained by Luke Edwards; stable, minimal API.
+
+## Filter: boundary-fit
+
+Core UI package. `clsx` is a utility for constructing `className` strings; appropriate for `core-ui`. No boundary rule violation.
+
+## Filter: shadow-check
+
+No competing className utility in the workspace. No shadow.
+
+## Filter: eu-residency
+
+Pure compute; no network calls or vendor data transmission. n/a.
+
+## Filter: cve-scan
+
+No advisories at adoption time.
+
+## Filter: named-consumer
+
+`core-ui` uses `clsx` in the `cn()` utility (combined with `tailwind-merge`) for conditional class composition.
+
+## Prompt: replaces
+
+Nothing — this is the initial UI scaffold.
+
+## Prompt: migration-cost-out
+
+Mechanical: replace `clsx()` calls with template literals or equivalent. Minimal API surface.
+
+## Prompt: alternatives-considered
+
+1. **classnames** — the older predecessor; `clsx` is smaller and faster.
+2. **Template literals** — verbose; no conditional logic support.
+   `clsx` is the de-facto standard lightweight className utility.
--- a/docs/library-decisions/2026-05-14-tailwind-merge.md
+++ b/docs/library-decisions/2026-05-14-tailwind-merge.md
@@ -0,0 +1,68 @@
+---
+package: tailwind-merge
+version: "^3.0.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [scaffolded]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - pnpm audit --audit-level=moderate
+  - npm view tailwind-merge license
+accepted-cves: []
+---
+
+## Filter: license
+
+MIT — on the workspace allowlist.
+
+## Filter: types
+
+Ships first-party TypeScript types in its distribution.
+
+## Filter: maintenance
+
+Active. Maintained by dcastil; v3 is the current stable major.
+
+## Filter: boundary-fit
+
+Core UI package. `tailwind-merge` deduplicates conflicting Tailwind classes; appropriate for `core-ui`. No boundary rule violation.
+
+## Filter: shadow-check
+
+No competing Tailwind class-merging utility in the workspace. No shadow.
+
+## Filter: eu-residency
+
+Pure compute; no network calls or vendor data transmission. n/a.
+
+## Filter: cve-scan
+
+No advisories at adoption time.
+
+## Filter: named-consumer
+
+`core-ui` uses `tailwind-merge` in the `cn()` utility (combined with `clsx`) to resolve conflicting Tailwind class names at runtime.
+
+## Prompt: replaces
+
+Nothing — this is the initial UI scaffold.
+
+## Prompt: migration-cost-out
+
+Mechanical: replace `twMerge()` calls in the `cn()` utility; update any call sites. Narrow API surface.
+
+## Prompt: alternatives-considered
+
+1. **Custom deduplication** — error-prone; Tailwind has hundreds of class groups that change each version.
+2. **tw-join** — does not merge conflicts; only concatenates.
+   `tailwind-merge` is the de-facto standard for conflict-free Tailwind class composition.
--- a/packages/core-ui/AGENTS.md
+++ b/packages/core-ui/AGENTS.md
@@ -0,0 +1,71 @@
+# 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
+
+> To scaffold a new component, use `pnpm turbo gen core-ui-component` rather than creating files manually. The generator emits the 4-file pattern below and splices the export into the tier barrel.
+
+```
+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
+```
--- a/packages/core-ui/docs/library-decisions/2026-05-14-clsx.md
+++ b/packages/core-ui/docs/library-decisions/2026-05-14-clsx.md
@@ -0,0 +1,68 @@
+---
+package: clsx
+version: "^2.1.1"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [scaffolded]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - pnpm audit --audit-level=moderate
+  - npm view clsx license
+accepted-cves: []
+---
+
+## Filter: license
+
+MIT — on the workspace allowlist.
+
+## Filter: types
+
+Ships first-party TypeScript types in its distribution.
+
+## Filter: maintenance
+
+Active. Maintained by Luke Edwards; stable, minimal API.
+
+## Filter: boundary-fit
+
+Core UI package. `clsx` is a utility for constructing `className` strings; appropriate for `core-ui`. No boundary rule violation.
+
+## Filter: shadow-check
+
+No competing className utility in the workspace. No shadow.
+
+## Filter: eu-residency
+
+Pure compute; no network calls or vendor data transmission. n/a.
+
+## Filter: cve-scan
+
+No advisories at adoption time.
+
+## Filter: named-consumer
+
+`core-ui` uses `clsx` in the `cn()` utility (combined with `tailwind-merge`) for conditional class composition.
+
+## Prompt: replaces
+
+Nothing — this is the initial UI scaffold.
+
+## Prompt: migration-cost-out
+
+Mechanical: replace `clsx()` calls with template literals or equivalent. Minimal API surface.
+
+## Prompt: alternatives-considered
+
+1. **classnames** — the older predecessor; `clsx` is smaller and faster.
+2. **Template literals** — verbose; no conditional logic support.
+   `clsx` is the de-facto standard lightweight className utility.
--- a/packages/core-ui/docs/library-decisions/2026-05-14-react.md
+++ b/packages/core-ui/docs/library-decisions/2026-05-14-react.md
@@ -0,0 +1,66 @@
+---
+package: react
+version: "^19.0.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [scaffolded]
+adr: null
+filter-results:
+  license: MIT
+  types: "@types/react"
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - pnpm audit --audit-level=moderate
+  - npm view react license
+accepted-cves: []
+---
+
+## Filter: license
+
+MIT — on the workspace allowlist.
+
+## Filter: types
+
+TypeScript types via `@types/react` (community-maintained but canonical; ships in sync with each React major).
+
+## Filter: maintenance
+
+Active. Maintained by Meta; v19 is the current stable major.
+
+## Filter: boundary-fit
+
+Core UI package. React is required for the component library; appropriate for `core-ui`. No boundary rule violation.
+
+## Filter: shadow-check
+
+React is already workspace-present in app packages. Same major version; no shadow.
+
+## Filter: eu-residency
+
+Client-side rendering library; no vendor data transmission. n/a.
+
+## Filter: cve-scan
+
+No advisories at adoption time.
+
+## Filter: named-consumer
+
+`core-ui` renders all atomic-design components (Button, Input, Label, FormField) as React components.
+
+## Prompt: replaces
+
+Nothing — React is already the UI framework in the workspace.
+
+## Prompt: migration-cost-out
+
+Impossible: React is the foundational UI library for this workspace.
+
+## Prompt: alternatives-considered
+
+React is workspace-locked as the UI framework. No alternative evaluated.
--- a/packages/core-ui/docs/library-decisions/2026-05-14-tailwind-merge.md
+++ b/packages/core-ui/docs/library-decisions/2026-05-14-tailwind-merge.md
@@ -0,0 +1,68 @@
+---
+package: tailwind-merge
+version: "^3.0.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [scaffolded]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+verification-commands:
+  - pnpm audit --audit-level=moderate
+  - npm view tailwind-merge license
+accepted-cves: []
+---
+
+## Filter: license
+
+MIT — on the workspace allowlist.
+
+## Filter: types
+
+Ships first-party TypeScript types in its distribution.
+
+## Filter: maintenance
+
+Active. Maintained by dcastil; v3 is the current stable major.
+
+## Filter: boundary-fit
+
+Core UI package. `tailwind-merge` deduplicates conflicting Tailwind classes; appropriate for `core-ui`. No boundary rule violation.
+
+## Filter: shadow-check
+
+No competing Tailwind class-merging utility in the workspace. No shadow.
+
+## Filter: eu-residency
+
+Pure compute; no network calls or vendor data transmission. n/a.
+
+## Filter: cve-scan
+
+No advisories at adoption time.
+
+## Filter: named-consumer
+
+`core-ui` uses `tailwind-merge` in the `cn()` utility (combined with `clsx`) to resolve conflicting Tailwind class names at runtime.
+
+## Prompt: replaces
+
+Nothing — this is the initial UI scaffold.
+
+## Prompt: migration-cost-out
+
+Mechanical: replace `twMerge()` calls in the `cn()` utility; update any call sites. Narrow API surface.
+
+## Prompt: alternatives-considered
+
+1. **Custom deduplication** — error-prone; Tailwind has hundreds of class groups that change each version.
+2. **tw-join** — does not merge conflicts; only concatenates.
+   `tailwind-merge` is the de-facto standard for conflict-free Tailwind class composition.
--- a/packages/core-ui/eslint.config.js
+++ b/packages/core-ui/eslint.config.js
@@ -0,0 +1,3 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default baseConfig;
--- a/packages/core-ui/package.json
+++ b/packages/core-ui/package.json
@@ -0,0 +1,34 @@
+{
+  "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/coverage-v8": "^3.0.0",
+    "vitest": "^3.0.0"
+  }
+}
--- a/packages/core-ui/src/atoms/button/button.stories.tsx
+++ b/packages/core-ui/src/atoms/button/button.stories.tsx
@@ -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" },
+};
--- a/packages/core-ui/src/atoms/button/button.test.tsx
+++ b/packages/core-ui/src/atoms/button/button.test.tsx
@@ -0,0 +1,44 @@
+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();
+  });
+});
--- a/packages/core-ui/src/atoms/button/button.tsx
+++ b/packages/core-ui/src/atoms/button/button.tsx
@@ -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";
--- a/packages/core-ui/src/atoms/button/index.ts
+++ b/packages/core-ui/src/atoms/button/index.ts
@@ -0,0 +1 @@
+export { Button, type ButtonProps } from "./button";
--- a/packages/core-ui/src/atoms/index.ts
+++ b/packages/core-ui/src/atoms/index.ts
@@ -0,0 +1,4 @@
+// <gen:atoms>
+export { Button, type ButtonProps } from "./button/index";
+export { Input, type InputProps } from "./input/index";
+export { Label, type LabelProps } from "./label/index";
--- a/packages/core-ui/src/atoms/input/index.ts
+++ b/packages/core-ui/src/atoms/input/index.ts
@@ -0,0 +1 @@
+export { Input, type InputProps } from "./input";
--- a/packages/core-ui/src/atoms/input/input.stories.tsx
+++ b/packages/core-ui/src/atoms/input/input.stories.tsx
@@ -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 },
+};
--- a/packages/core-ui/src/atoms/input/input.test.tsx
+++ b/packages/core-ui/src/atoms/input/input.test.tsx
@@ -0,0 +1,34 @@
+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("");
+  });
+});
--- a/packages/core-ui/src/atoms/input/input.tsx
+++ b/packages/core-ui/src/atoms/input/input.tsx
@@ -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";
--- a/packages/core-ui/src/atoms/label/index.ts
+++ b/packages/core-ui/src/atoms/label/index.ts
@@ -0,0 +1 @@
+export { Label, type LabelProps } from "./label";
--- a/packages/core-ui/src/atoms/label/label.stories.tsx
+++ b/packages/core-ui/src/atoms/label/label.stories.tsx
@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Label } from "./label";
+
+const meta = {
+  title: "Atoms/Label",
+  component: Label,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Label>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: "Form label" },
+};
+
+export const Disabled: Story = {
+  args: { children: "Disabled label", className: "peer-disabled:opacity-70" },
+};
--- a/packages/core-ui/src/atoms/label/label.test.tsx
+++ b/packages/core-ui/src/atoms/label/label.test.tsx
@@ -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");
+  });
+});
--- a/packages/core-ui/src/atoms/label/label.tsx
+++ b/packages/core-ui/src/atoms/label/label.tsx
@@ -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";
--- a/packages/core-ui/src/index.ts
+++ b/packages/core-ui/src/index.ts
@@ -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";
--- a/packages/core-ui/src/lib/utils.ts
+++ b/packages/core-ui/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
--- a/packages/core-ui/src/molecules/form-field/form-field.stories.tsx
+++ b/packages/core-ui/src/molecules/form-field/form-field.stories.tsx
@@ -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",
+  },
+};
--- a/packages/core-ui/src/molecules/form-field/form-field.test.tsx
+++ b/packages/core-ui/src/molecules/form-field/form-field.test.tsx
@@ -0,0 +1,35 @@
+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");
+  });
+});
--- a/packages/core-ui/src/molecules/form-field/form-field.tsx
+++ b/packages/core-ui/src/molecules/form-field/form-field.tsx
@@ -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>
+  );
+}
--- a/packages/core-ui/src/molecules/form-field/index.ts
+++ b/packages/core-ui/src/molecules/form-field/index.ts
@@ -0,0 +1 @@
+export { FormField, type FormFieldProps } from "./form-field";
--- a/packages/core-ui/src/molecules/index.ts
+++ b/packages/core-ui/src/molecules/index.ts
@@ -0,0 +1,2 @@
+// <gen:molecules>
+export { FormField, type FormFieldProps } from "./form-field/index";
--- a/packages/core-ui/src/organisms/index.ts
+++ b/packages/core-ui/src/organisms/index.ts
@@ -0,0 +1,2 @@
+// <gen:organisms>
+export {};
--- a/packages/core-ui/src/styles/globals.css
+++ b/packages/core-ui/src/styles/globals.css
@@ -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;
+}
--- a/packages/core-ui/src/templates/index.ts
+++ b/packages/core-ui/src/templates/index.ts
@@ -0,0 +1 @@
+export {};
--- a/packages/core-ui/tsconfig.json
+++ b/packages/core-ui/tsconfig.json
@@ -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"]
+}
--- a/packages/core-ui/turbo.json
+++ b/packages/core-ui/turbo.json
@@ -0,0 +1,4 @@
+{
+  "extends": ["//"],
+  "tags": ["core"]
+}
--- a/packages/core-ui/vitest.config.ts
+++ b/packages/core-ui/vitest.config.ts
@@ -0,0 +1,20 @@
+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") },
+  },
+  test: {
+    coverage: {
+      exclude: [
+        "src/**/*.test.{ts,tsx}",
+        "src/**/*.stories.{ts,tsx}",
+        "src/**/index.ts",
+        "src/__factories__/**",
+        "src/__contracts__/**",
+      ],
+    },
+  },
+});
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -871,6 +871,52 @@ importers:
        specifier: ^3.1.0
        version: 3.2.4(@types/debug@4.1.13)(@types/node@25.5.2)(happy-dom@20.8.9)(jiti@2.6.1)(jsdom@25.0.1)(lightningcss@1.32.0)(sass@1.99.0)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)

+  packages/core-ui:
+    dependencies:
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
+      react:
+        specifier: ^19.0.0
+        version: 19.2.4
+      tailwind-merge:
+        specifier: ^3.0.0
+        version: 3.6.0
+    devDependencies:
+      "@repo/core-eslint":
+        specifier: workspace:*
+        version: link:../core-eslint
+      "@repo/core-testing":
+        specifier: workspace:*
+        version: link:../core-testing
+      "@repo/core-typescript":
+        specifier: workspace:*
+        version: link:../core-typescript
+      "@storybook/react":
+        specifier: ^8.6.0
+        version: 8.6.18(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@8.6.18(prettier@3.8.1))(typescript@5.9.3)
+      "@testing-library/jest-dom":
+        specifier: ^6.5.0
+        version: 6.9.1
+      "@testing-library/react":
+        specifier: ^16.0.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      "@testing-library/user-event":
+        specifier: ^14.5.0
+        version: 14.6.1(@testing-library/dom@10.4.1)
+      "@types/react":
+        specifier: ^19.0.0
+        version: 19.2.14
+      "@vitest/coverage-v8":
+        specifier: ^3.0.0
+        version: 3.2.4(vitest@3.2.4(@types/debug@4.1.13)(@types/node@25.5.2)(happy-dom@20.8.9)(jiti@2.6.1)(jsdom@25.0.1)(lightningcss@1.32.0)(sass@1.99.0)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0))
+      jsdom:
+        specifier: ^25.0.0
+        version: 25.0.1
+      vitest:
+        specifier: ^3.0.0
+        version: 3.2.4(@types/debug@4.1.13)(@types/node@25.5.2)(happy-dom@20.8.9)(jiti@2.6.1)(jsdom@25.0.1)(lightningcss@1.32.0)(sass@1.99.0)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)
+
  packages/marketing-pages:
    dependencies:
      "@repo/auth":
@@ -12582,6 +12628,12 @@ packages:
        integrity: sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==,
      }

+  tailwind-merge@3.6.0:
+    resolution:
+      {
+        integrity: sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w==,
+      }
+
  tailwindcss@4.2.2:
    resolution:
      {
@@ -21774,6 +21826,8 @@ snapshots:

  tabbable@6.4.0: {}

+  tailwind-merge@3.6.0: {}
+
  tailwindcss@4.2.2: {}

  tapable@2.3.2: {}
--- a/scripts/library-decisions/check.mjs
+++ b/scripts/library-decisions/check.mjs
@@ -309,13 +309,41 @@ export function checkLibraryDecisions(
    if (tier === "app" || tier === "skip") continue;

    for (const dep of getNewRuntimeDeps(relPath, repoRoot, stagedAgainst)) {
-      const traceFile = findStagedTrace(dep, staged);
-      if (!traceFile) {
+      const stagedTrace = findStagedTrace(dep, staged);
+      if (!stagedTrace) {
+        // Fall back to an already-committed trace — if one exists and is
+        // approved, the dep was previously evaluated and doesn't need
+        // re-staging just because a new package adopts it.
+        const committedTrace = findExistingTrace(dep, repoRoot);
+        if (committedTrace) {
+          try {
+            const content = fs.readFileSync(committedTrace, "utf8");
+            const fm = parseFrontmatter(content);
+            if (fm.decision !== "approved") {
+              errors.push({
+                pkgJson: relPath,
+                dep,
+                reason: "not-approved",
+                decision: fm.decision,
+              });
+            }
+          } catch (e) {
+            errors.push({
+              pkgJson: relPath,
+              dep,
+              reason: "parse-error",
+              detail: String(e.message),
+            });
+          }
+          continue;
+        }
        errors.push({ pkgJson: relPath, dep, reason: "no-trace" });
        continue;
      }
      try {
-        const traceRef = stagedAgainst ? `HEAD:${traceFile}` : `:${traceFile}`;
+        const traceRef = stagedAgainst
+          ? `HEAD:${stagedTrace}`
+          : `:${stagedTrace}`;
        const content = execSync(`git show "${traceRef}"`, {
          cwd: repoRoot,
          encoding: "utf8",
--- a/scripts/library-decisions/check.test.mjs
+++ b/scripts/library-decisions/check.test.mjs
@@ -174,6 +174,36 @@ describe("checkLibraryDecisions", () => {
    assert.deepEqual(checkLibraryDecisions(dir), []);
  });

+  test("new feature-tier dep with already-committed approved trace → exit 0", () => {
+    const { dir, g } = makeRepo();
+    // Commit trace first (simulates an existing workspace-approved library)
+    stageTrace(dir, g, "existing-lib", "approved");
+    g("git commit -m add-trace");
+    // Now add a new package that depends on the same library
+    commitPkg(dir, g, "packages/feat-a", { dependencies: {} });
+    stagePkg(dir, g, "packages/feat-a", {
+      dependencies: { "existing-lib": "^1.0.0" },
+    });
+
+    // No staged trace needed — the committed trace is the fallback
+    assert.deepEqual(checkLibraryDecisions(dir), []);
+  });
+
+  test("new feature-tier dep with already-committed rejected trace → exit 1", () => {
+    const { dir, g } = makeRepo();
+    stageTrace(dir, g, "bad-lib", "rejected");
+    g("git commit -m add-trace");
+    commitPkg(dir, g, "packages/feat-a", { dependencies: {} });
+    stagePkg(dir, g, "packages/feat-a", {
+      dependencies: { "bad-lib": "^1.0.0" },
+    });
+
+    const errs = checkLibraryDecisions(dir);
+    assert.equal(errs.length, 1);
+    assert.equal(errs[0].dep, "bad-lib");
+    assert.equal(errs[0].reason, "not-approved");
+  });
+
  test("--staged-against mode: new feature-tier dep without trace → exit 1", () => {
    const { dir, g } = makeRepo();
    // Baseline commit: feature package with no deps
				`@@ -0,0 +1 @@`
				`export { Button, type ButtonProps } from "./button";`
				`@@ -0,0 +1 @@`
				`export { Input, type InputProps } from "./input";`
				`@@ -0,0 +1 @@`
				`export { Label, type LabelProps } from "./label";`
				`@@ -0,0 +1 @@`
				`export { FormField, type FormFieldProps } from "./form-field";`