From 307639eca02cbe24e97a7f2b365604014c4a50cc Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Sat, 28 Feb 2026 22:12:04 +0000
Subject: [PATCH] feat(web): add teams settings page (MS21-UI-005) (#576)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>
---
 .../src/app/(authenticated)/settings/page.tsx |  25 ++
 .../settings/teams/page.test.tsx              |  76 ++++++
 .../(authenticated)/settings/teams/page.tsx   | 244 +++++++++++++++++
 .../workspaces/[id]/teams/[teamId]/page.tsx   | 137 +---------
 .../settings/workspaces/[id]/teams/page.tsx   | 109 +++++---
 apps/web/src/lib/api/teams.ts                 | 250 ++++++------------
 6 files changed, 513 insertions(+), 328 deletions(-)
 create mode 100644 apps/web/src/app/(authenticated)/settings/teams/page.test.tsx
 create mode 100644 apps/web/src/app/(authenticated)/settings/teams/page.tsx

diff --git a/apps/web/src/app/(authenticated)/settings/page.tsx b/apps/web/src/app/(authenticated)/settings/page.tsx
index 1138c01..403a2ed 100644
--- a/apps/web/src/app/(authenticated)/settings/page.tsx
+++ b/apps/web/src/app/(authenticated)/settings/page.tsx
@@ -221,6 +221,31 @@ const categories: CategoryConfig[] = [
       </svg>
     ),
   },
+  {
+    title: "Teams",
+    description: "Create and manage teams within your active workspace.",
+    href: "/settings/teams",
+    accent: "var(--ms-blue-400)",
+    iconBg: "rgba(47, 128, 255, 0.12)",
+    icon: (
+      <svg
+        width="20"
+        height="20"
+        viewBox="0 0 20 20"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <circle cx="7" cy="7" r="2.25" />
+        <circle cx="13" cy="7" r="2.25" />
+        <path d="M3 15c0-2.2 1.8-4 4-4s4 1.8 4 4" />
+        <path d="M9 15c0-2.2 1.8-4 4-4s4 1.8 4 4" />
+      </svg>
+    ),
+  },
   {
     title: "Workspaces",
     description:
diff --git a/apps/web/src/app/(authenticated)/settings/teams/page.test.tsx b/apps/web/src/app/(authenticated)/settings/teams/page.test.tsx
new file mode 100644
index 0000000..c55418c
--- /dev/null
+++ b/apps/web/src/app/(authenticated)/settings/teams/page.test.tsx
@@ -0,0 +1,76 @@
+import type { ReactElement, ReactNode } from "react";
+import type { TeamRecord } from "@/lib/api/teams";
+
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { fetchTeams } from "@/lib/api/teams";
+
+import TeamsSettingsPage from "./page";
+
+vi.mock("next/link", () => ({
+  default: function LinkMock({
+    children,
+    href,
+  }: {
+    children: ReactNode;
+    href: string;
+  }): ReactElement {
+    return <a href={href}>{children}</a>;
+  },
+}));
+
+vi.mock("@/lib/api/teams", () => ({
+  fetchTeams: vi.fn(),
+  createTeam: vi.fn(),
+}));
+
+const fetchTeamsMock = vi.mocked(fetchTeams);
+
+const baseTeam: TeamRecord = {
+  id: "team-1",
+  workspaceId: "workspace-1",
+  name: "Platform Team",
+  description: "Owns platform services",
+  metadata: {},
+  createdAt: "2026-02-01T00:00:00.000Z",
+  updatedAt: "2026-02-01T00:00:00.000Z",
+  _count: {
+    members: 3,
+  },
+};
+
+describe("TeamsSettingsPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("loads and renders teams from the API", async () => {
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(screen.getByText("Loading teams...")).toBeInTheDocument();
+
+    expect(await screen.findByText("Your Teams (1)")).toBeInTheDocument();
+    expect(screen.getByText("Platform Team")).toBeInTheDocument();
+    expect(fetchTeamsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows empty state when the API returns no teams", async () => {
+    fetchTeamsMock.mockResolvedValue([]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Your Teams (0)")).toBeInTheDocument();
+    expect(screen.getByText("No teams yet")).toBeInTheDocument();
+  });
+
+  it("shows error state and does not show empty state", async () => {
+    fetchTeamsMock.mockRejectedValue(new Error("Unable to load teams"));
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Unable to load teams")).toBeInTheDocument();
+    expect(screen.queryByText("No teams yet")).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/app/(authenticated)/settings/teams/page.tsx b/apps/web/src/app/(authenticated)/settings/teams/page.tsx
new file mode 100644
index 0000000..29b792a
--- /dev/null
+++ b/apps/web/src/app/(authenticated)/settings/teams/page.tsx
@@ -0,0 +1,244 @@
+"use client";
+
+import type { ReactElement, SyntheticEvent } from "react";
+
+import { useCallback, useEffect, useState } from "react";
+import Link from "next/link";
+import { createTeam, fetchTeams, type CreateTeamDto, type TeamRecord } from "@/lib/api/teams";
+
+function getErrorMessage(error: unknown, fallback: string): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return fallback;
+}
+
+export default function TeamsSettingsPage(): ReactElement {
+  const [teams, setTeams] = useState<TeamRecord[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [isCreateDialogOpen, setIsCreateDialogOpen] = useState(false);
+  const [isCreating, setIsCreating] = useState(false);
+  const [newTeamName, setNewTeamName] = useState("");
+  const [newTeamDescription, setNewTeamDescription] = useState("");
+  const [createError, setCreateError] = useState<string | null>(null);
+
+  const loadTeams = useCallback(async (): Promise<void> => {
+    setIsLoading(true);
+
+    try {
+      const data = await fetchTeams();
+      setTeams(data);
+      setLoadError(null);
+    } catch (error) {
+      setLoadError(getErrorMessage(error, "Failed to load teams"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadTeams();
+  }, [loadTeams]);
+
+  const handleCreateTeam = async (e: SyntheticEvent<HTMLFormElement>): Promise<void> => {
+    e.preventDefault();
+
+    const teamName = newTeamName.trim();
+    if (!teamName) return;
+
+    setIsCreating(true);
+    setCreateError(null);
+
+    try {
+      const description = newTeamDescription.trim();
+      const dto: CreateTeamDto = { name: teamName };
+      if (description.length > 0) {
+        dto.description = description;
+      }
+
+      await createTeam(dto);
+      setNewTeamName("");
+      setNewTeamDescription("");
+      setIsCreateDialogOpen(false);
+      await loadTeams();
+    } catch (error) {
+      setCreateError(getErrorMessage(error, "Failed to create team"));
+    } finally {
+      setIsCreating(false);
+    }
+  };
+
+  return (
+    <main className="container mx-auto px-4 py-8 max-w-5xl">
+      <div className="mb-8">
+        <div className="flex items-center justify-between mb-2">
+          <h1 className="text-3xl font-bold text-gray-900">Teams</h1>
+          <Link href="/settings" className="text-sm text-blue-600 hover:text-blue-700">
+            {"<-"} Back to Settings
+          </Link>
+        </div>
+        <p className="text-gray-600">Manage teams in your active workspace</p>
+      </div>
+
+      <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6 mb-6">
+        <div className="flex items-center justify-between gap-4">
+          <div>
+            <h2 className="text-lg font-semibold text-gray-900">Create New Team</h2>
+            <p className="text-sm text-gray-600 mt-1">
+              Add a team to organize members and permissions.
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={() => {
+              setCreateError(null);
+              setIsCreateDialogOpen(true);
+            }}
+            className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
+          >
+            Create Team
+          </button>
+        </div>
+      </div>
+
+      {isCreateDialogOpen && (
+        <div
+          className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 px-4"
+          role="dialog"
+        >
+          <div className="w-full max-w-lg rounded-lg border border-gray-200 bg-white p-6 shadow-xl">
+            <h3 className="text-lg font-semibold text-gray-900">Create New Team</h3>
+            <p className="mt-1 text-sm text-gray-600">
+              Enter a team name and optional description.
+            </p>
+
+            <form onSubmit={handleCreateTeam} className="mt-4 space-y-4">
+              <div>
+                <label htmlFor="team-name" className="mb-1 block text-sm font-medium text-gray-700">
+                  Team Name
+                </label>
+                <input
+                  id="team-name"
+                  type="text"
+                  value={newTeamName}
+                  onChange={(e) => {
+                    setNewTeamName(e.target.value);
+                  }}
+                  placeholder="Enter team name..."
+                  disabled={isCreating}
+                  className="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
+                  autoFocus
+                />
+              </div>
+
+              <div>
+                <label
+                  htmlFor="team-description"
+                  className="mb-1 block text-sm font-medium text-gray-700"
+                >
+                  Description (optional)
+                </label>
+                <textarea
+                  id="team-description"
+                  value={newTeamDescription}
+                  onChange={(e) => {
+                    setNewTeamDescription(e.target.value);
+                  }}
+                  placeholder="Describe this team's purpose..."
+                  disabled={isCreating}
+                  rows={3}
+                  className="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
+                />
+              </div>
+
+              {createError !== null && (
+                <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700">
+                  {createError}
+                </div>
+              )}
+
+              <div className="flex justify-end gap-3">
+                <button
+                  type="button"
+                  onClick={() => {
+                    if (!isCreating) {
+                      setIsCreateDialogOpen(false);
+                    }
+                  }}
+                  disabled={isCreating}
+                  className="px-4 py-2 rounded-lg border border-gray-300 text-gray-700 hover:bg-gray-50 disabled:cursor-not-allowed"
+                >
+                  Cancel
+                </button>
+                <button
+                  type="submit"
+                  disabled={isCreating || !newTeamName.trim()}
+                  className="px-5 py-2 rounded-lg bg-blue-600 text-white font-medium hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-50"
+                >
+                  {isCreating ? "Creating..." : "Create Team"}
+                </button>
+              </div>
+            </form>
+          </div>
+        </div>
+      )}
+
+      <div className="space-y-4">
+        <h2 className="text-xl font-semibold text-gray-900">
+          Your Teams ({isLoading ? "..." : teams.length})
+        </h2>
+        {loadError !== null ? (
+          <div className="rounded-md border border-red-200 bg-red-50 px-4 py-3 text-red-700">
+            {loadError}
+          </div>
+        ) : isLoading ? (
+          <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-12 text-center text-gray-600">
+            Loading teams...
+          </div>
+        ) : teams.length === 0 ? (
+          <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-12 text-center">
+            <svg
+              className="mx-auto h-12 w-12 text-gray-400 mb-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M17 20h5V8H2v12h5m10 0v-4a3 3 0 10-6 0v4m6 0H7"
+              />
+            </svg>
+            <h3 className="text-lg font-medium text-gray-900 mb-2">No teams yet</h3>
+            <p className="text-gray-600">Create your first team to get started</p>
+          </div>
+        ) : (
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            {teams.map((team) => (
+              <article
+                key={team.id}
+                className="rounded-lg border border-gray-200 bg-white p-5 shadow-sm"
+                data-testid="team-card"
+              >
+                <h3 className="text-lg font-semibold text-gray-900">{team.name}</h3>
+                {team.description ? (
+                  <p className="mt-1 text-sm text-gray-600">{team.description}</p>
+                ) : (
+                  <p className="mt-1 text-sm text-gray-400 italic">No description</p>
+                )}
+                <div className="mt-4 flex items-center gap-3 text-xs text-gray-500">
+                  <span>{team._count?.members ?? 0} members</span>
+                  <span>|</span>
+                  <span>Created {new Date(team.createdAt).toLocaleDateString()}</span>
+                </div>
+              </article>
+            ))}
+          </div>
+        )}
+      </div>
+    </main>
+  );
+}
diff --git a/apps/web/src/app/settings/workspaces/[id]/teams/[teamId]/page.tsx b/apps/web/src/app/settings/workspaces/[id]/teams/[teamId]/page.tsx
index e0c1af9..3439626 100644
--- a/apps/web/src/app/settings/workspaces/[id]/teams/[teamId]/page.tsx
+++ b/apps/web/src/app/settings/workspaces/[id]/teams/[teamId]/page.tsx
@@ -2,136 +2,25 @@
 
 import type { ReactElement } from "react";
 
-import { useState } from "react";
-import { useParams, useRouter } from "next/navigation";
-import { TeamSettings } from "@/components/team/TeamSettings";
-import { TeamMemberList } from "@/components/team/TeamMemberList";
-import { mockTeamWithMembers } from "@/lib/api/teams";
-import type { User } from "@mosaic/shared";
-import type { TeamMemberRole } from "@mosaic/shared";
+import { useParams } from "next/navigation";
+import { ComingSoon } from "@/components/ui/ComingSoon";
 import Link from "next/link";
 
-// Mock available users for adding to team
-const mockAvailableUsers: User[] = [
-  {
-    id: "user-3",
-    email: "alice@example.com",
-    name: "Alice Johnson",
-    emailVerified: true,
-    image: null,
-    authProviderId: null,
-    preferences: {},
-    deactivatedAt: null,
-    isLocalAuth: false,
-    passwordHash: null,
-    invitedBy: null,
-    invitationToken: null,
-    invitedAt: null,
-    createdAt: new Date("2026-01-17"),
-    updatedAt: new Date("2026-01-17"),
-  },
-  {
-    id: "user-4",
-    email: "bob@example.com",
-    name: "Bob Wilson",
-    emailVerified: true,
-    image: null,
-    authProviderId: null,
-    preferences: {},
-    deactivatedAt: null,
-    isLocalAuth: false,
-    passwordHash: null,
-    invitedBy: null,
-    invitationToken: null,
-    invitedAt: null,
-    createdAt: new Date("2026-01-18"),
-    updatedAt: new Date("2026-01-18"),
-  },
-];
-
 export default function TeamDetailPage(): ReactElement {
   const params = useParams();
-  const router = useRouter();
   const workspaceId = params.id as string;
-  // const teamId = params.teamId as string; // Will be used for API calls
-
-  // TODO: Replace with real API call when backend is ready
-  // const { data: team, isLoading } = useQuery({
-  //   queryKey: ["team", workspaceId, params.teamId],
-  //   queryFn: () => fetchTeam(workspaceId, params.teamId as string),
-  // });
-
-  const [team] = useState(mockTeamWithMembers);
-  const [isLoading] = useState(false);
-
-  const handleUpdateTeam = (data: { name?: string; description?: string }): Promise<void> => {
-    // TODO: Replace with real API call
-    // await updateTeam(workspaceId, teamId, data);
-    console.log("Updating team:", data);
-    // TODO: Refetch team data
-    return Promise.resolve();
-  };
-
-  const handleDeleteTeam = (): Promise<void> => {
-    // TODO: Replace with real API call
-    // await deleteTeam(workspaceId, teamId);
-    console.log("Deleting team");
-
-    // Navigate back to teams list
-    router.push(`/settings/workspaces/${workspaceId}/teams`);
-    return Promise.resolve();
-  };
-
-  const handleAddMember = (userId: string, role?: TeamMemberRole): Promise<void> => {
-    // TODO: Replace with real API call
-    // await addTeamMember(workspaceId, teamId, { userId, role });
-    console.log("Adding member:", { userId, role });
-    // TODO: Refetch team data
-    return Promise.resolve();
-  };
-
-  const handleRemoveMember = (userId: string): Promise<void> => {
-    // TODO: Replace with real API call
-    // await removeTeamMember(workspaceId, teamId, userId);
-    console.log("Removing member:", userId);
-    // TODO: Refetch team data
-    return Promise.resolve();
-  };
-
-  if (isLoading) {
-    return (
-      <main className="container mx-auto px-4 py-8">
-        <div className="flex justify-center items-center p-8">
-          <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900"></div>
-          <span className="ml-3 text-gray-600">Loading team...</span>
-        </div>
-      </main>
-    );
-  }
 
   return (
-    <main className="container mx-auto px-4 py-8">
-      <div className="mb-8">
-        <Link
-          href={`/settings/workspaces/${workspaceId}/teams`}
-          className="text-blue-600 hover:text-blue-700 text-sm mb-2 inline-block"
-        >
-          ← Back to Teams
-        </Link>
-        <h1 className="text-3xl font-bold text-gray-900">{team.name}</h1>
-        {team.description && <p className="text-gray-600 mt-2">{team.description}</p>}
-      </div>
-
-      <div className="space-y-6">
-        <TeamSettings team={team} onUpdate={handleUpdateTeam} onDelete={handleDeleteTeam} />
-
-        <TeamMemberList
-          members={team.members}
-          onAddMember={handleAddMember}
-          onRemoveMember={handleRemoveMember}
-          availableUsers={mockAvailableUsers}
-        />
-      </div>
-    </main>
+    <ComingSoon
+      feature="Team Details"
+      description="Team member management is being migrated to live API-backed data."
+    >
+      <Link
+        href={`/settings/workspaces/${workspaceId}/teams`}
+        className="text-sm text-blue-600 hover:text-blue-700"
+      >
+        {"<-"} Back to Teams
+      </Link>
+    </ComingSoon>
   );
 }
diff --git a/apps/web/src/app/settings/workspaces/[id]/teams/page.tsx b/apps/web/src/app/settings/workspaces/[id]/teams/page.tsx
index 8a16d36..338fc3e 100644
--- a/apps/web/src/app/settings/workspaces/[id]/teams/page.tsx
+++ b/apps/web/src/app/settings/workspaces/[id]/teams/page.tsx
@@ -2,63 +2,90 @@
 
 import type { ReactElement } from "react";
 
-import { useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useParams } from "next/navigation";
 import { TeamCard } from "@/components/team/TeamCard";
 import { ComingSoon } from "@/components/ui/ComingSoon";
 import { Button, Input, Modal } from "@mosaic/ui";
-import { mockTeams } from "@/lib/api/teams";
+import { createTeam, fetchTeams, type CreateTeamDto, type TeamRecord } from "@/lib/api/teams";
 import Link from "next/link";
 
-// Check if we're in development mode
 const isDevelopment = process.env.NODE_ENV === "development";
 
-/**
- * Teams Page Content - Development Only
- * Shows mock team data for development purposes
- */
+function getErrorMessage(error: unknown, fallback: string): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return fallback;
+}
+
 function TeamsPageContent(): ReactElement {
   const params = useParams();
   const workspaceId = params.id as string;
 
-  // TODO: Replace with real API call when backend is ready
-  // const { data: teams, isLoading } = useQuery({
-  //   queryKey: ["teams", workspaceId],
-  //   queryFn: () => fetchTeams(workspaceId),
-  // });
-
-  const [teams] = useState(mockTeams);
-  const [isLoading] = useState(false);
+  const [teams, setTeams] = useState<TeamRecord[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
   const [isCreating, setIsCreating] = useState(false);
   const [showCreateModal, setShowCreateModal] = useState(false);
   const [newTeamName, setNewTeamName] = useState("");
   const [newTeamDescription, setNewTeamDescription] = useState("");
+  const [createError, setCreateError] = useState<string | null>(null);
 
-  const handleCreateTeam = (): void => {
-    if (!newTeamName.trim()) return;
+  const loadTeams = useCallback(async (): Promise<void> => {
+    setIsLoading(true);
+
+    try {
+      const data = await fetchTeams(workspaceId);
+      setTeams(data);
+      setLoadError(null);
+    } catch (error) {
+      setLoadError(getErrorMessage(error, "Failed to load teams"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [workspaceId]);
+
+  useEffect(() => {
+    void loadTeams();
+  }, [loadTeams]);
+
+  const handleCreateTeam = async (): Promise<void> => {
+    const teamName = newTeamName.trim();
+    if (!teamName) return;
 
     setIsCreating(true);
-    try {
-      // TODO: Replace with real API call
-      // await createTeam(workspaceId, {
-      //   name: newTeamName,
-      //   description: newTeamDescription || undefined,
-      // });
+    setCreateError(null);
+
+    try {
+      const description = newTeamDescription.trim();
+      const dto: CreateTeamDto = {
+        name: teamName,
+      };
+      if (description.length > 0) {
+        dto.description = description;
+      }
+
+      await createTeam(dto, workspaceId);
 
-      // Reset form
       setNewTeamName("");
       setNewTeamDescription("");
       setShowCreateModal(false);
-
-      // TODO: Refresh teams list
-    } catch (_error) {
-      console.error("Failed to create team:", _error);
-      alert("Failed to create team. Please try again.");
+      await loadTeams();
+    } catch (error) {
+      setCreateError(getErrorMessage(error, "Failed to create team"));
     } finally {
       setIsCreating(false);
     }
   };
 
+  const teamsForCards = teams.map((team) => ({
+    ...team,
+    createdAt: new Date(team.createdAt),
+    updatedAt: new Date(team.updatedAt),
+  }));
+
   if (isLoading) {
     return (
       <main className="container mx-auto px-4 py-8">
@@ -80,6 +107,7 @@ function TeamsPageContent(): ReactElement {
         <Button
           variant="primary"
           onClick={() => {
+            setCreateError(null);
             setShowCreateModal(true);
           }}
         >
@@ -87,7 +115,11 @@ function TeamsPageContent(): ReactElement {
         </Button>
       </div>
 
-      {teams.length === 0 ? (
+      {loadError !== null ? (
+        <div className="rounded-md border border-red-200 bg-red-50 px-4 py-3 text-red-700">
+          {loadError}
+        </div>
+      ) : teamsForCards.length === 0 ? (
         <div className="text-center p-12 bg-gray-50 rounded-lg">
           <p className="text-lg text-gray-500 mb-4">No teams yet</p>
           <p className="text-sm text-gray-400 mb-6">
@@ -96,6 +128,7 @@ function TeamsPageContent(): ReactElement {
           <Button
             variant="primary"
             onClick={() => {
+              setCreateError(null);
               setShowCreateModal(true);
             }}
           >
@@ -104,13 +137,12 @@ function TeamsPageContent(): ReactElement {
         </div>
       ) : (
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-          {teams.map((team) => (
+          {teamsForCards.map((team) => (
             <TeamCard key={team.id} team={team} workspaceId={workspaceId} />
           ))}
         </div>
       )}
 
-      {/* Create Team Modal */}
       {showCreateModal && (
         <Modal
           isOpen={showCreateModal}
@@ -143,6 +175,11 @@ function TeamsPageContent(): ReactElement {
               fullWidth
               disabled={isCreating}
             />
+            {createError !== null && (
+              <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700">
+                {createError}
+              </div>
+            )}
             <div className="flex gap-2 justify-end pt-4">
               <Button
                 variant="ghost"
@@ -155,7 +192,7 @@ function TeamsPageContent(): ReactElement {
               </Button>
               <Button
                 variant="primary"
-                onClick={handleCreateTeam}
+                onClick={() => void handleCreateTeam()}
                 disabled={!newTeamName.trim() || isCreating}
               >
                 {isCreating ? "Creating..." : "Create Team"}
@@ -168,12 +205,7 @@ function TeamsPageContent(): ReactElement {
   );
 }
 
-/**
- * Teams Page Entry Point
- * Shows development content or Coming Soon based on environment
- */
 export default function TeamsPage(): ReactElement {
-  // In production, show Coming Soon placeholder
   if (!isDevelopment) {
     return (
       <ComingSoon
@@ -187,6 +219,5 @@ export default function TeamsPage(): ReactElement {
     );
   }
 
-  // In development, show the full page with mock data
   return <TeamsPageContent />;
 }
diff --git a/apps/web/src/lib/api/teams.ts b/apps/web/src/lib/api/teams.ts
index 18e4dc8..1127e98 100644
--- a/apps/web/src/lib/api/teams.ts
+++ b/apps/web/src/lib/api/teams.ts
@@ -1,14 +1,53 @@
 /**
  * Teams API Client
- * Handles team-related API requests
+ * Handles workspace-scoped team API requests.
  */
 
-import type { Team, TeamMember, User } from "@mosaic/shared";
-import { TeamMemberRole } from "@mosaic/shared";
-import { apiGet, apiPost, apiPatch, apiDelete, type ApiResponse } from "./client";
+import type { TeamMemberRole } from "@mosaic/shared";
+import { apiDelete, apiGet, apiPost } from "./client";
 
-export interface TeamWithMembers extends Team {
-  members: (TeamMember & { user: User })[];
+const WORKSPACE_STORAGE_KEY = "mosaic-workspace-id";
+
+function resolveWorkspaceId(explicitWorkspaceId?: string): string {
+  if (explicitWorkspaceId !== undefined) {
+    return explicitWorkspaceId;
+  }
+
+  if (typeof window === "undefined") {
+    throw new Error("Workspace context is unavailable outside the browser");
+  }
+
+  const workspaceId = window.localStorage.getItem(WORKSPACE_STORAGE_KEY);
+  if (!workspaceId) {
+    throw new Error("No active workspace selected");
+  }
+
+  return workspaceId;
+}
+
+export interface TeamRecord {
+  id: string;
+  workspaceId: string;
+  name: string;
+  description: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  _count?: {
+    members: number;
+  };
+}
+
+export interface TeamMemberRecord {
+  teamId: string;
+  userId: string;
+  role: TeamMemberRole;
+  joinedAt: string;
+  user?: {
+    id: string;
+    name: string;
+    email: string;
+  };
 }
 
 export interface CreateTeamDto {
@@ -16,200 +55,81 @@ export interface CreateTeamDto {
   description?: string;
 }
 
-export interface UpdateTeamDto {
-  name?: string;
-  description?: string;
-}
-
 export interface AddTeamMemberDto {
   userId: string;
   role?: TeamMemberRole;
 }
 
 /**
- * Fetch all teams for a workspace
+ * Fetch all teams in the active workspace.
  */
-export async function fetchTeams(workspaceId: string): Promise<Team[]> {
-  const response = await apiGet<ApiResponse<Team[]>>(`/api/workspaces/${workspaceId}/teams`);
-  return response.data;
+export async function fetchTeams(workspaceId?: string): Promise<TeamRecord[]> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  return apiGet<TeamRecord[]>(`/api/workspaces/${resolvedWorkspaceId}/teams`, resolvedWorkspaceId);
 }
 
 /**
- * Fetch a single team with members
+ * Create a team in the active workspace.
  */
-export async function fetchTeam(workspaceId: string, teamId: string): Promise<TeamWithMembers> {
-  const response = await apiGet<ApiResponse<TeamWithMembers>>(
-    `/api/workspaces/${workspaceId}/teams/${teamId}`
+export async function createTeam(dto: CreateTeamDto, workspaceId?: string): Promise<TeamRecord> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  return apiPost<TeamRecord>(
+    `/api/workspaces/${resolvedWorkspaceId}/teams`,
+    dto,
+    resolvedWorkspaceId
   );
-  return response.data;
 }
 
 /**
- * Create a new team
+ * Fetch team members for a team in the active workspace.
+ * The current backend route shape is workspace-scoped team membership.
  */
-export async function createTeam(workspaceId: string, data: CreateTeamDto): Promise<Team> {
-  const response = await apiPost<ApiResponse<Team>>(`/api/workspaces/${workspaceId}/teams`, data);
-  return response.data;
-}
-
-/**
- * Update a team
- */
-export async function updateTeam(
-  workspaceId: string,
+export async function fetchTeamMembers(
   teamId: string,
-  data: UpdateTeamDto
-): Promise<Team> {
-  const response = await apiPatch<ApiResponse<Team>>(
-    `/api/workspaces/${workspaceId}/teams/${teamId}`,
-    data
+  workspaceId?: string
+): Promise<TeamMemberRecord[]> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  return apiGet<TeamMemberRecord[]>(
+    `/api/workspaces/${resolvedWorkspaceId}/teams/${teamId}/members`,
+    resolvedWorkspaceId
   );
-  return response.data;
 }
 
 /**
- * Delete a team
+ * Delete a team in the active workspace.
  */
-export async function deleteTeam(workspaceId: string, teamId: string): Promise<void> {
-  await apiDelete(`/api/workspaces/${workspaceId}/teams/${teamId}`);
+export async function deleteTeam(teamId: string, workspaceId?: string): Promise<void> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  await apiDelete(`/api/workspaces/${resolvedWorkspaceId}/teams/${teamId}`, resolvedWorkspaceId);
 }
 
 /**
- * Add a member to a team
+ * Add a member to a team in the active workspace.
  */
 export async function addTeamMember(
-  workspaceId: string,
   teamId: string,
-  data: AddTeamMemberDto
-): Promise<TeamMember> {
-  const response = await apiPost<ApiResponse<TeamMember>>(
-    `/api/workspaces/${workspaceId}/teams/${teamId}/members`,
-    data
+  data: AddTeamMemberDto,
+  workspaceId?: string
+): Promise<TeamMemberRecord> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  return apiPost<TeamMemberRecord>(
+    `/api/workspaces/${resolvedWorkspaceId}/teams/${teamId}/members`,
+    data,
+    resolvedWorkspaceId
   );
-  return response.data;
 }
 
 /**
- * Remove a member from a team
+ * Remove a member from a team in the active workspace.
  */
 export async function removeTeamMember(
-  workspaceId: string,
-  teamId: string,
-  userId: string
-): Promise<void> {
-  await apiDelete(`/api/workspaces/${workspaceId}/teams/${teamId}/members/${userId}`);
-}
-
-/**
- * Update a team member's role
- */
-export async function updateTeamMemberRole(
-  workspaceId: string,
   teamId: string,
   userId: string,
-  role: TeamMemberRole
-): Promise<TeamMember> {
-  const response = await apiPatch<ApiResponse<TeamMember>>(
-    `/api/workspaces/${workspaceId}/teams/${teamId}/members/${userId}`,
-    { role }
+  workspaceId?: string
+): Promise<void> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  await apiDelete(
+    `/api/workspaces/${resolvedWorkspaceId}/teams/${teamId}/members/${userId}`,
+    resolvedWorkspaceId
   );
-  return response.data;
 }
-
-/**
- * Mock teams for development (until backend endpoints are ready)
- */
-export const mockTeams: Team[] = [
-  {
-    id: "team-1",
-    workspaceId: "workspace-1",
-    name: "Engineering",
-    description: "Product development team",
-    metadata: {},
-    createdAt: new Date("2026-01-20"),
-    updatedAt: new Date("2026-01-20"),
-  },
-  {
-    id: "team-2",
-    workspaceId: "workspace-1",
-    name: "Design",
-    description: "UI/UX design team",
-    metadata: {},
-    createdAt: new Date("2026-01-22"),
-    updatedAt: new Date("2026-01-22"),
-  },
-  {
-    id: "team-3",
-    workspaceId: "workspace-1",
-    name: "Marketing",
-    description: null,
-    metadata: {},
-    createdAt: new Date("2026-01-25"),
-    updatedAt: new Date("2026-01-25"),
-  },
-];
-
-/**
- * Mock team with members for development
- */
-const baseTeam = mockTeams[0];
-if (!baseTeam) {
-  throw new Error("Mock team not found");
-}
-export const mockTeamWithMembers: TeamWithMembers = {
-  id: baseTeam.id,
-  workspaceId: baseTeam.workspaceId,
-  name: baseTeam.name,
-  description: baseTeam.description,
-  metadata: baseTeam.metadata,
-  createdAt: baseTeam.createdAt,
-  updatedAt: baseTeam.updatedAt,
-  members: [
-    {
-      teamId: "team-1",
-      userId: "user-1",
-      role: TeamMemberRole.OWNER,
-      joinedAt: new Date("2026-01-20"),
-      user: {
-        id: "user-1",
-        email: "john@example.com",
-        name: "John Doe",
-        emailVerified: true,
-        image: null,
-        authProviderId: null,
-        preferences: {},
-        deactivatedAt: null,
-        isLocalAuth: false,
-        passwordHash: null,
-        invitedBy: null,
-        invitationToken: null,
-        invitedAt: null,
-        createdAt: new Date("2026-01-15"),
-        updatedAt: new Date("2026-01-15"),
-      },
-    },
-    {
-      teamId: "team-1",
-      userId: "user-2",
-      role: TeamMemberRole.MEMBER,
-      joinedAt: new Date("2026-01-21"),
-      user: {
-        id: "user-2",
-        email: "jane@example.com",
-        name: "Jane Smith",
-        emailVerified: true,
-        image: null,
-        authProviderId: null,
-        preferences: {},
-        deactivatedAt: null,
-        isLocalAuth: false,
-        passwordHash: null,
-        invitedBy: null,
-        invitationToken: null,
-        invitedAt: null,
-        createdAt: new Date("2026-01-16"),
-        updatedAt: new Date("2026-01-16"),
-      },
-    },
-  ],
-};