From 1f25382e569f3eb3f09556f8c1006f7a2a4a3033 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Mon, 16 Mar 2026 20:27:02 +0100
Subject: [PATCH] Move table cell requirement docs to docs-ui

Move the cell wrapper requirement documentation from the package
README to the docs-ui table component page where it belongs.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 .changeset/document-table-cell-requirement.md |  7 -----
 docs-ui/src/app/components/table/page.mdx     | 13 +++++++++
 docs-ui/src/app/components/table/snippets.ts  | 17 +++++++++++
 packages/ui/README.md                         | 28 -------------------
 4 files changed, 30 insertions(+), 35 deletions(-)
 delete mode 100644 .changeset/document-table-cell-requirement.md

diff --git a/.changeset/document-table-cell-requirement.md b/.changeset/document-table-cell-requirement.md
deleted file mode 100644
index 8a8b82bc90..0000000000
--- a/.changeset/document-table-cell-requirement.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-'@backstage/ui': patch
----
-
-Documented the requirement that `ColumnConfig.cell` and custom `RowRenderFn` renders must return a cell component (`Cell`, `CellText`, or `CellProfile`) as the top-level element.
-
-Affected components: Table, Cell, CellText, CellProfile
diff --git a/docs-ui/src/app/components/table/page.mdx b/docs-ui/src/app/components/table/page.mdx
index 6eb280cbe2..8d0e803bd2 100644
--- a/docs-ui/src/app/components/table/page.mdx
+++ b/docs-ui/src/app/components/table/page.mdx
@@ -42,6 +42,7 @@ import {
   tableCombinedSnippet,
   tableCustomRowSnippet,
   tablePrimitivesSnippet,
+  tableCellRequirementSnippet,
 } from './snippets';
 import { ChangelogComponent } from '@/components/ChangelogComponent';
 import { PageTitle } from '@/components/PageTitle';
@@ -94,6 +95,18 @@ For full control over state, use the controlled props instead:
 - `search` / `onSearchChange`
 - `filter` / `onFilterChange`
 
+### Cell Requirement
+
+Every cell rendered via `ColumnConfig.cell` (or inside a custom `RowRenderFn`) **must** return a cell component as the top-level element. The available cell components are:
+
+- **`CellText`** — displays a title with optional description and icon.
+- **`CellProfile`** — displays an avatar with a name and optional description.
+- **`Cell`** — a generic wrapper for fully custom cell content.
+
+Returning bare text, React fragments, or other elements without wrapping them in one of these cell components will break the table layout.
+
+<CodeBlock code={tableCellRequirementSnippet} />
+
 ## Common Patterns
 
 ### Sorting
diff --git a/docs-ui/src/app/components/table/snippets.ts b/docs-ui/src/app/components/table/snippets.ts
index ab4bf53a58..39f266f2ea 100644
--- a/docs-ui/src/app/components/table/snippets.ts
+++ b/docs-ui/src/app/components/table/snippets.ts
@@ -57,6 +57,23 @@ const {
   filter,      // { value, onChange } for filters
 } = useTable({ ... });`;
 
+// =============================================================================
+// Cell Requirement
+// =============================================================================
+
+export const tableCellRequirementSnippet = `// ✅ Correct — CellText is the top-level element
+cell: item => <CellText title={item.name} />;
+
+// ✅ Correct — Cell wraps custom content
+cell: item => (
+  <Cell>
+    <MyCustomContent value={item.name} />
+  </Cell>
+);
+
+// ❌ Wrong — bare text without a cell wrapper
+cell: item => <span>{item.name}</span>;`;
+
 // =============================================================================
 // Common Patterns
 // =============================================================================
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 25de0f3190..271b78fca4 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -17,34 +17,6 @@ yarn add @backstage/ui
 - [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
 - [Backstage Documentation](https://backstage.io/docs)
 
-## Table Cell Requirement
-
-When using the `Table` component, every cell rendered via `ColumnConfig.cell` (or
-inside a custom `RowRenderFn`) **must** return a cell component as the top-level
-element. The available cell components are:
-
-- **`CellText`** — displays a title with optional description and icon.
-- **`CellProfile`** — displays an avatar with a name and optional description.
-- **`Cell`** — a generic wrapper for fully custom cell content.
-
-Returning bare text, React fragments, or other elements without wrapping them in
-one of these cell components will break the table layout.
-
-```tsx
-// ✅ Correct — CellText is the top-level element
-cell: item => <CellText title={item.name} />;
-
-// ✅ Correct — Cell wraps custom content
-cell: item => (
-  <Cell>
-    <MyCustomContent value={item.name} />
-  </Cell>
-);
-
-// ❌ Wrong — bare text without a cell wrapper
-cell: item => <span>{item.name}</span>;
-```
-
 ## Writing Changesets for Components
 
 When creating changesets for component-specific changes, add component metadata to help maintain documentation: