From 1c28f63555dea5c797bcf1cfee48511cd9b91170 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89mile=20R=C3=A9?= <emile@probo.com>
Date: Mon, 20 Jul 2026 14:27:51 +0200
Subject: [PATCH] Extract bordered list into UI List
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents and data requests duplicated the same card and
row chrome. A shared List primitive keeps those surfaces
consistent across the portal.

Signed-off-by: Émile Ré <emile@probo.com>
---
 .../pages/documents/DocumentsPageSkeleton.tsx |  8 +-
 .../documents/_components/DocumentEntry.tsx   | 13 ++--
 .../documents/_components/DocumentSection.tsx |  5 +-
 .../pages/documents/_components/variants.ts   | 13 +---
 .../src/pages/requests/RequestsPage.tsx       |  7 +-
 .../pages/requests/RequestsPageSkeleton.tsx   | 14 +---
 .../_components/RightsRequestListItem.tsx     | 12 +--
 .../pages/requests/_components/variants.ts    |  7 +-
 packages/ui/src/v2/List/List.stories.tsx      | 73 +++++++++++++++++++
 packages/ui/src/v2/List/List.tsx              | 34 +++++++++
 packages/ui/src/v2/List/ListItem.tsx          | 34 +++++++++
 packages/ui/src/v2/List/ListItemContent.tsx   | 33 +++++++++
 packages/ui/src/v2/List/ListItemSkeleton.tsx  | 34 +++++++++
 packages/ui/src/v2/List/ListSkeleton.tsx      | 46 ++++++++++++
 packages/ui/src/v2/List/variants.ts           | 32 ++++++++
 15 files changed, 313 insertions(+), 52 deletions(-)
 create mode 100644 packages/ui/src/v2/List/List.stories.tsx
 create mode 100644 packages/ui/src/v2/List/List.tsx
 create mode 100644 packages/ui/src/v2/List/ListItem.tsx
 create mode 100644 packages/ui/src/v2/List/ListItemContent.tsx
 create mode 100644 packages/ui/src/v2/List/ListItemSkeleton.tsx
 create mode 100644 packages/ui/src/v2/List/ListSkeleton.tsx
 create mode 100644 packages/ui/src/v2/List/variants.ts

diff --git a/apps/compliance-portal/src/pages/documents/DocumentsPageSkeleton.tsx b/apps/compliance-portal/src/pages/documents/DocumentsPageSkeleton.tsx
index eed51dab9..6af78fcc2 100644
--- a/apps/compliance-portal/src/pages/documents/DocumentsPageSkeleton.tsx
+++ b/apps/compliance-portal/src/pages/documents/DocumentsPageSkeleton.tsx
@@ -18,6 +18,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+import { ListSkeleton } from "@probo/ui/src/v2/List/ListSkeleton";
 import { TabsSkeleton } from "@probo/ui/src/v2/Tabs/TabsSkeleton";
 import { HeadingSkeleton } from "@probo/ui/src/v2/typography/HeadingSkeleton";
 import { TextSkeleton } from "@probo/ui/src/v2/typography/TextSkeleton";
@@ -27,7 +28,6 @@ import { HeaderBand } from "#/components/HeaderBand/HeaderBand";
 import { documentsLayout } from "./variants";
 
 const SECTION_PLACEHOLDERS = ["a", "b"];
-const ROW_PLACEHOLDERS = ["x", "y", "z"];
 
 export function DocumentsPageSkeleton() {
   const { page, results } = documentsLayout();
@@ -45,11 +45,7 @@ export function DocumentsPageSkeleton() {
           {SECTION_PLACEHOLDERS.map(section => (
             <div key={section} className="flex flex-col gap-3">
               <TextSkeleton size={3} className="w-40" />
-              <div className="overflow-hidden rounded-4 border border-sand-a4 bg-sand-1">
-                {ROW_PLACEHOLDERS.map(row => (
-                  <div key={row} className="h-16 animate-pulse border-b border-sand-a3 bg-sand-2 last:border-b-0" />
-                ))}
-              </div>
+              <ListSkeleton count={3} />
             </div>
           ))}
         </div>
diff --git a/apps/compliance-portal/src/pages/documents/_components/DocumentEntry.tsx b/apps/compliance-portal/src/pages/documents/_components/DocumentEntry.tsx
index e96567e6c..6bccef884 100644
--- a/apps/compliance-portal/src/pages/documents/_components/DocumentEntry.tsx
+++ b/apps/compliance-portal/src/pages/documents/_components/DocumentEntry.tsx
@@ -18,11 +18,12 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+import { ListItem } from "@probo/ui/src/v2/List/ListItem";
+import { ListItemContent } from "@probo/ui/src/v2/List/ListItemContent";
 import { Text } from "@probo/ui/src/v2/typography/Text";
 import type { ReactNode } from "react";
 
 import { DocumentAccessAction } from "./DocumentAccessAction";
-import { documentListItem } from "./variants";
 
 interface DocumentEntryProps {
   // Primary line (document title, file name, or framework name).
@@ -53,18 +54,16 @@ export function DocumentEntry({
   onGetAccess,
   isRequesting,
 }: DocumentEntryProps) {
-  const { root, content } = documentListItem();
-
   return (
-    <div className={root()}>
-      <div className={content()}>
+    <ListItem>
+      <ListItemContent>
         <Text size={2} weight="medium" color="neutral" highContrast className="truncate">
           {title}
         </Text>
         <Text size={1} color="gold" className="truncate">
           {meta}
         </Text>
-      </div>
+      </ListItemContent>
       <DocumentAccessAction
         isAuthorized={isAuthorized}
         requested={requested}
@@ -72,6 +71,6 @@ export function DocumentEntry({
         onGetAccess={onGetAccess}
         isRequesting={isRequesting}
       />
-    </div>
+    </ListItem>
   );
 }
diff --git a/apps/compliance-portal/src/pages/documents/_components/DocumentSection.tsx b/apps/compliance-portal/src/pages/documents/_components/DocumentSection.tsx
index a332a1b82..80b841aa1 100644
--- a/apps/compliance-portal/src/pages/documents/_components/DocumentSection.tsx
+++ b/apps/compliance-portal/src/pages/documents/_components/DocumentSection.tsx
@@ -18,6 +18,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+import { List } from "@probo/ui/src/v2/List/List";
 import { Text } from "@probo/ui/src/v2/typography/Text";
 import type { ReactNode } from "react";
 
@@ -32,7 +33,7 @@ interface DocumentSectionProps {
 
 // One category group: a localized header above a bordered list of rows.
 export function DocumentSection({ title, description, children }: DocumentSectionProps) {
-  const { root, header, list } = documentSection();
+  const { root, header } = documentSection();
 
   return (
     <section className={root()}>
@@ -46,7 +47,7 @@ export function DocumentSection({ title, description, children }: DocumentSectio
           </Text>
         )}
       </div>
-      <div className={list()}>{children}</div>
+      <List>{children}</List>
     </section>
   );
 }
diff --git a/apps/compliance-portal/src/pages/documents/_components/variants.ts b/apps/compliance-portal/src/pages/documents/_components/variants.ts
index b9baa8f13..6700cb482 100644
--- a/apps/compliance-portal/src/pages/documents/_components/variants.ts
+++ b/apps/compliance-portal/src/pages/documents/_components/variants.ts
@@ -20,22 +20,13 @@
 
 import { tv } from "tailwind-variants/lite";
 
-// Document list: category sections, each a titled block above a bordered list.
-// Entries share a common layout (title + accent metadata + trailing access
-// action).
+// Document list: category section chrome (title + description). The bordered
+// list surface and row layout live in @probo/ui List.
 
 export const documentSection = tv({
   slots: {
     root: "flex flex-col gap-3",
     header: "flex flex-col gap-0.5",
-    list: "overflow-hidden rounded-4 border border-sand-a4 bg-sand-1",
-  },
-});
-
-export const documentListItem = tv({
-  slots: {
-    root: "flex items-center gap-4 border-b border-sand-a3 px-4 py-3 last:border-b-0",
-    content: "flex min-w-0 flex-1 flex-col gap-0.5",
   },
 });
 
diff --git a/apps/compliance-portal/src/pages/requests/RequestsPage.tsx b/apps/compliance-portal/src/pages/requests/RequestsPage.tsx
index cc4232afa..45fc20976 100644
--- a/apps/compliance-portal/src/pages/requests/RequestsPage.tsx
+++ b/apps/compliance-portal/src/pages/requests/RequestsPage.tsx
@@ -20,6 +20,7 @@
 
 import { NoteIcon, PlusIcon } from "@phosphor-icons/react";
 import { Button } from "@probo/ui/src/v2/Button/Button";
+import { List } from "@probo/ui/src/v2/List/List";
 import { useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import type { PreloadedQuery } from "react-relay";
@@ -37,7 +38,6 @@ import type { RequestsPageQuery } from "./__generated__/RequestsPageQuery.graphq
 import type { RequestsPageRefetchQuery } from "./__generated__/RequestsPageRefetchQuery.graphql";
 import { NewRequestDialog } from "./_components/NewRequestDialog";
 import { RightsRequestListItem } from "./_components/RightsRequestListItem";
-import { rightsRequestList } from "./_components/variants";
 import { requestsLayout } from "./variants";
 
 export const requestsPageQuery = graphql`
@@ -116,7 +116,6 @@ export function RequestsPage({ queryRef }: RequestsPageProps) {
   };
 
   const { page, results, loadMore } = requestsLayout();
-  const { card } = rightsRequestList();
 
   const newRequestButton = (
     <Button
@@ -149,11 +148,11 @@ export function RequestsPage({ queryRef }: RequestsPageProps) {
                 )
               : (
                   <>
-                    <div className={card()}>
+                    <List>
                       {requests.map(request => (
                         <RightsRequestListItem key={request.id} rightsRequestKey={request} />
                       ))}
-                    </div>
+                    </List>
                     {hasNext && (
                       <div className={loadMore()}>
                         <Button
diff --git a/apps/compliance-portal/src/pages/requests/RequestsPageSkeleton.tsx b/apps/compliance-portal/src/pages/requests/RequestsPageSkeleton.tsx
index 1633e4908..98da02dcd 100644
--- a/apps/compliance-portal/src/pages/requests/RequestsPageSkeleton.tsx
+++ b/apps/compliance-portal/src/pages/requests/RequestsPageSkeleton.tsx
@@ -18,18 +18,15 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+import { ListSkeleton } from "@probo/ui/src/v2/List/ListSkeleton";
 import { HeadingSkeleton } from "@probo/ui/src/v2/typography/HeadingSkeleton";
 
 import { HeaderBand } from "#/components/HeaderBand/HeaderBand";
 
-import { rightsRequestList } from "./_components/variants";
 import { requestsLayout } from "./variants";
 
-const ROW_PLACEHOLDERS = ["a", "b", "c", "d"];
-
 export function RequestsPageSkeleton() {
   const { page, results } = requestsLayout();
-  const { card } = rightsRequestList();
 
   return (
     <>
@@ -41,14 +38,7 @@ export function RequestsPageSkeleton() {
       </HeaderBand>
       <div className={page()}>
         <div className={results()}>
-          <div className={card()}>
-            {ROW_PLACEHOLDERS.map(row => (
-              <div
-                key={row}
-                className="h-16 animate-pulse border-b border-sand-a3 bg-sand-2 last:border-b-0"
-              />
-            ))}
-          </div>
+          <ListSkeleton count={4} />
         </div>
       </div>
     </>
diff --git a/apps/compliance-portal/src/pages/requests/_components/RightsRequestListItem.tsx b/apps/compliance-portal/src/pages/requests/_components/RightsRequestListItem.tsx
index eed5403cd..eecfc1499 100644
--- a/apps/compliance-portal/src/pages/requests/_components/RightsRequestListItem.tsx
+++ b/apps/compliance-portal/src/pages/requests/_components/RightsRequestListItem.tsx
@@ -19,6 +19,8 @@
 // SOFTWARE.
 
 import { Badge } from "@probo/ui/src/v2/Badge/Badge";
+import { ListItem } from "@probo/ui/src/v2/List/ListItem";
+import { ListItemContent } from "@probo/ui/src/v2/List/ListItemContent";
 import { Text } from "@probo/ui/src/v2/typography/Text";
 import { useTranslation } from "react-i18next";
 import { graphql, useFragment } from "react-relay";
@@ -56,14 +58,14 @@ export function RightsRequestListItem({ rightsRequestKey }: RightsRequestListIte
 
   const badge = getRightsRequestStatusBadge(request.requestState);
   const reference = formatRightsRequestReference(request.id, request.createdAt);
-  const { item, icon, content, subline, trailing } = rightsRequestList();
+  const { icon, subline, trailing } = rightsRequestList();
 
   return (
-    <div className={item()}>
+    <ListItem>
       <span className={icon()}>
         {getRightsRequestTypeIcon(request.requestType)}
       </span>
-      <div className={content()}>
+      <ListItemContent>
         <Text size={2} weight="medium" color="neutral" highContrast className="truncate">
           {t(`types.${request.requestType}`)}
         </Text>
@@ -77,7 +79,7 @@ export function RightsRequestListItem({ rightsRequestKey }: RightsRequestListIte
             </Text>
           )}
         </div>
-      </div>
+      </ListItemContent>
       <div className={trailing()}>
         <Text size={1} color="faint">
           {formatRelativeTime(request.createdAt, i18n.language)}
@@ -86,6 +88,6 @@ export function RightsRequestListItem({ rightsRequestKey }: RightsRequestListIte
           {t(`status.${request.requestState}`)}
         </Badge>
       </div>
-    </div>
+    </ListItem>
   );
 }
diff --git a/apps/compliance-portal/src/pages/requests/_components/variants.ts b/apps/compliance-portal/src/pages/requests/_components/variants.ts
index 703ccea37..8bed95dd2 100644
--- a/apps/compliance-portal/src/pages/requests/_components/variants.ts
+++ b/apps/compliance-portal/src/pages/requests/_components/variants.ts
@@ -20,14 +20,11 @@
 
 import { tv } from "tailwind-variants/lite";
 
-// Data request list: a bordered card of rows, each with a leading type icon, a
-// title + reference/message subline, and a trailing time + status badge.
+// Data request row chrome beyond the shared list surface: leading type icon,
+// reference/message subline, and trailing time + status badge.
 export const rightsRequestList = tv({
   slots: {
-    card: "overflow-hidden rounded-4 border border-sand-a4 bg-sand-1",
-    item: "flex items-center gap-4 border-b border-sand-a3 px-4 py-3 last:border-b-0",
     icon: "flex size-9 shrink-0 items-center justify-center rounded-3 bg-sand-3 text-sand-a11 [&_svg]:size-4",
-    content: "flex min-w-0 flex-1 flex-col gap-0.5",
     subline: "flex min-w-0 items-center gap-1.5",
     trailing: "flex shrink-0 items-center gap-3",
   },
diff --git a/packages/ui/src/v2/List/List.stories.tsx b/packages/ui/src/v2/List/List.stories.tsx
new file mode 100644
index 000000000..4994a330a
--- /dev/null
+++ b/packages/ui/src/v2/List/List.stories.tsx
@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Badge } from "../Badge/Badge";
+import { Text } from "../typography/Text";
+
+import { List } from "./List";
+import { ListItem } from "./ListItem";
+import { ListItemContent } from "./ListItemContent";
+import { ListSkeleton } from "./ListSkeleton";
+
+const entries = [
+  { title: "Information Security Policy", meta: "Policy" },
+  { title: "Access Control Procedure", meta: "Procedure" },
+  { title: "Vendor Risk Assessment", meta: "Report" },
+] as const;
+
+export default {
+  title: "v2/List",
+  component: List,
+  render: () => (
+    <div className="w-96">
+      <List>
+        {entries.map(entry => (
+          <ListItem key={entry.title}>
+            <ListItemContent>
+              <Text size={2} weight="medium" color="neutral" highContrast>
+                {entry.title}
+              </Text>
+              <Text size={1} color="gold">
+                {entry.meta}
+              </Text>
+            </ListItemContent>
+            <Badge color="neutral" variant="soft">
+              View
+            </Badge>
+          </ListItem>
+        ))}
+      </List>
+    </div>
+  ),
+} satisfies Meta<typeof List>;
+
+type Story = StoryObj<typeof List>;
+
+export const Playground: Story = {};
+
+export const Skeleton: Story = {
+  render: () => (
+    <div className="w-96">
+      <ListSkeleton count={3} />
+    </div>
+  ),
+};
diff --git a/packages/ui/src/v2/List/List.tsx b/packages/ui/src/v2/List/List.tsx
new file mode 100644
index 000000000..ec6ca1a39
--- /dev/null
+++ b/packages/ui/src/v2/List/List.tsx
@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { ComponentProps } from "react";
+
+import { list } from "./variants";
+
+export type ListProps = ComponentProps<"ul">;
+
+// Bordered list surface for divided rows (documents, data requests, …). Pair
+// with ListItem / ListItemContent; use ListSkeleton while loading.
+export function List(props: ListProps) {
+  const { className, ...rest } = props;
+  const { root } = list();
+
+  return <ul className={root({ className })} {...rest} />;
+}
diff --git a/packages/ui/src/v2/List/ListItem.tsx b/packages/ui/src/v2/List/ListItem.tsx
new file mode 100644
index 000000000..d20ddaf8c
--- /dev/null
+++ b/packages/ui/src/v2/List/ListItem.tsx
@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { ComponentProps } from "react";
+
+import { list } from "./variants";
+
+export type ListItemProps = ComponentProps<"li">;
+
+// One divided row inside a List. Put leading chrome, ListItemContent, and
+// trailing actions as children.
+export function ListItem(props: ListItemProps) {
+  const { className, ...rest } = props;
+  const { item } = list();
+
+  return <li className={item({ className })} {...rest} />;
+}
diff --git a/packages/ui/src/v2/List/ListItemContent.tsx b/packages/ui/src/v2/List/ListItemContent.tsx
new file mode 100644
index 000000000..3f1ff1f53
--- /dev/null
+++ b/packages/ui/src/v2/List/ListItemContent.tsx
@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { ComponentProps } from "react";
+
+import { list } from "./variants";
+
+export type ListItemContentProps = ComponentProps<"div">;
+
+// Flexible primary column inside a ListItem (title + metadata stack).
+export function ListItemContent(props: ListItemContentProps) {
+  const { className, ...rest } = props;
+  const { content } = list();
+
+  return <div className={content({ className })} {...rest} />;
+}
diff --git a/packages/ui/src/v2/List/ListItemSkeleton.tsx b/packages/ui/src/v2/List/ListItemSkeleton.tsx
new file mode 100644
index 000000000..229e585c8
--- /dev/null
+++ b/packages/ui/src/v2/List/ListItemSkeleton.tsx
@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { ComponentProps } from "react";
+
+import { list } from "./variants";
+
+export type ListItemSkeletonProps = Omit<ComponentProps<"li">, "children">;
+
+// Loading placeholder paired with ListItem: a pulse bar that keeps the row
+// dividers of a List.
+export function ListItemSkeleton(props: ListItemSkeletonProps) {
+  const { className, ...rest } = props;
+  const { skeletonItem } = list();
+
+  return <li className={skeletonItem({ className })} aria-hidden {...rest} />;
+}
diff --git a/packages/ui/src/v2/List/ListSkeleton.tsx b/packages/ui/src/v2/List/ListSkeleton.tsx
new file mode 100644
index 000000000..37a632b21
--- /dev/null
+++ b/packages/ui/src/v2/List/ListSkeleton.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import type { ComponentProps } from "react";
+
+import { ListItemSkeleton } from "./ListItemSkeleton";
+import { list } from "./variants";
+
+export type ListSkeletonProps = Omit<ComponentProps<"ul">, "children"> & {
+  // Number of pulse rows to render inside the list surface.
+  count?: number;
+};
+
+// Loading placeholder paired with List: the bordered surface filled with
+// ListItemSkeleton rows. Imports only variants + ListItemSkeleton so it stays
+// out of any interactive List consumer graph.
+export function ListSkeleton(props: ListSkeletonProps) {
+  const { count = 3, className, ...rest } = props;
+  const rows = Array.from({ length: count }, (_, index) => index);
+  const { root } = list();
+
+  return (
+    <ul className={root({ className })} {...rest}>
+      {rows.map(row => (
+        <ListItemSkeleton key={row} />
+      ))}
+    </ul>
+  );
+}
diff --git a/packages/ui/src/v2/List/variants.ts b/packages/ui/src/v2/List/variants.ts
new file mode 100644
index 000000000..a8138cefd
--- /dev/null
+++ b/packages/ui/src/v2/List/variants.ts
@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import { tv } from "tailwind-variants/lite";
+
+// Bordered list surface: a soft sand card of divided rows, with a flexible
+// primary column for title + metadata. Border treatment matches Card `soft`.
+export const list = tv({
+  slots: {
+    root: "list-none overflow-hidden rounded-4 border border-sand-a3 bg-sand-1",
+    item: "flex items-center gap-4 border-b border-sand-a3 px-4 py-3 last:border-b-0",
+    content: "flex min-w-0 flex-1 flex-col gap-0.5",
+    skeletonItem: "h-16 animate-pulse border-b border-sand-a3 bg-sand-2 last:border-b-0",
+  },
+});