diff --git a/widgets/table.md b/widgets/table.md
new file mode 100644
index 0000000..5e948a5
--- /dev/null
+++ b/widgets/table.md
@@ -0,0 +1,63 @@
+# Table
+
+The table widget is a configurable data grid: typed columns, sorting, filtering, footer totals and
+inline editing — either static or bound to a data source.
+
+## Live preview
+
+<w4c-widget-preview type="table" height="360"></w4c-widget-preview>
+
+## Embedding a preview in documentation
+
+Pages embed a live widget with the `<w4c-widget-preview>` block. Without a body the widget
+self-seeds its default data, exactly like a freshly dropped widget:
+
+```html
+<w4c-widget-preview type="table" height="360"></w4c-widget-preview>
+```
+
+Pass JSON metadata as the block body to preview specific data:
+
+```html
+<w4c-widget-preview type="table" height="320">
+{ "title": "Deployments", "columns": [ ... ], "rows": [ ... ] }
+</w4c-widget-preview>
+```
+
+`type` is any widget type key, and `height` is the preview height in pixels (160–900).
+
+## Data-driven preview
+
+<w4c-widget-preview type="table" height="300">
+{
+  "title": "Deployments",
+  "columns": [
+    { "key": "env", "label": "Environment", "sortable": true },
+    { "key": "status", "label": "Status", "type": "badge", "badgeMap": { "ok": "#2e7d32", "fail": "#c62828" } },
+    { "key": "latency", "label": "Latency (ms)", "type": "number" }
+  ],
+  "rows": [
+    { "env": "dev", "status": "ok", "latency": 42 },
+    { "env": "staging", "status": "ok", "latency": 57 },
+    { "env": "production", "status": "fail", "latency": 380 }
+  ]
+}
+</w4c-widget-preview>
+
+## Columns
+
+| Field | Meaning |
+| --- | --- |
+| `key` | Property read from each row |
+| `label` | Header text |
+| `type` | `auto`, `text`, `number`, `date`, `bool` or `badge` |
+| `align` | `left`, `center` or `right` (numbers are right-aligned by default) |
+| `width` | Fixed column width in pixels |
+| `sortable`, `hidden`, `frozen` | Interaction flags |
+| `format` | Number/date format applied to the cell |
+| `badgeMap` | Value → colour map used by `badge` columns |
+
+## Presentation
+
+`display` toggles the grid chrome: `header`, `striped`, `borders`, `compact`, `rowNumbers`, `wrap`,
+`footerTotals` and `filterRow`.