Improved table element styles & fixed table styles inside asides (#2064)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Co-authored-by: Eva Decker <itsevadecker@gmail.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Lorenzo Lewis <15347255+lorenzolewis@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

3 files changed, 166 insertions, 6 deletions

diff --git a/.changeset/curly-dolphins-grow.md b/.changeset/curly-dolphins-grow.md
new file mode 100644
index 00000000..113ed658
--- /dev/null
+++ b/.changeset/curly-dolphins-grow.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Improves styling of Markdown tables to work better in different contexts, including against different background colours like when used in asides.
diff --git a/docs/src/content/docs/guides/tables-test.md b/docs/src/content/docs/guides/tables-test.md
new file mode 100644
index 00000000..70f27261
--- /dev/null
+++ b/docs/src/content/docs/guides/tables-test.md
@@ -0,0 +1,132 @@
+---
+title: ⚠️ Table styles test ⚠️
+---
+
+:::danger
+TODO(delucis): Delete me!
+:::
+
+| Framework              | CO₂ per page visit |
+| ---------------------- | ------------------ |
+| [Starlight][sl-carbon] | 0.01g              |
+| [VitePress][vp-carbon] | 0.05g              |
+| [Docus][dc-carbon]     | 0.05g              |
+
+:::note
+| Framework | CO₂ per page visit |
+| ---------------------- | ------------------ |
+| [Starlight][sl-carbon] | 0.01g |
+| [VitePress][vp-carbon] | 0.05g |
+| [Docus][dc-carbon] | 0.05g |
+:::
+
+:::caution
+| Framework | CO₂ per page visit |
+| ---------------------- | ------------------ |
+| [Starlight][sl-carbon] | 0.01g |
+| [VitePress][vp-carbon] | 0.05g |
+| [Docus][dc-carbon] | 0.05g |
+:::
+
+[sl-carbon]: https://www.websitecarbon.com/website/starlight-astro-build-getting-started/
+[vp-carbon]: https://www.websitecarbon.com/website/vitepress-dev-guide-what-is-vitepress/
+[dc-carbon]: https://www.websitecarbon.com/website/docus-dev-introduction-getting-started/
+
+## Unbalanced content example
+
+Taken from [Carbon Design System “Structured List” example](https://carbondesignsystem.com/components/structured-list/usage/#live-demo).
+
+| ColumnA | ColumnB | ColumnC                                                                                                                                                                                                                                    |
+| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Row 1   | Row 1   | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui magna, finibus id tortor sed, aliquet bibendum augue. Aenean posuere sem vel euismod dignissim. Nulla ut cursus dolor. Pellentesque vulputate nisl a porttitor interdum. |
+| Row 2   | Row 2   | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui magna, finibus id tortor sed, aliquet bibendum augue. Aenean posuere sem vel euismod dignissim. Nulla ut cursus dolor. Pellentesque vulputate nisl a porttitor interdum. |
+
+## Small table example
+
+Taken from the [Bootstrap docs](https://getbootstrap.com/docs/5.3/content/tables/#overview).
+
+| #   | First          | Last     | Handle   |
+| --- | -------------- | -------- | -------- |
+| 1   | Mark           | Otto     | @mdo     |
+| 2   | Jacob          | Thornton | @fat     |
+| 3   | Larry the Bird |          | @twitter |
+
+## Kitchen Sink
+
+|         | 1         | 2          | 3       |
+| ------- | --------- | ---------- | ------- |
+| Patrick | 25-30 cm  | 30.1-35 cm | > 35 cm |
+| Samuel  | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+| Anna    | 8-11.9 cm | 12-15.9 cm | 16 cm   |
+| Vianca  | 8-11.9 cm | 12-15.9 cm | 16 cm   |
+| Jacob   | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+
+:::note
+| | 1 | 2 | 3 |
+| ------- | --------- | ---------- | ------- |
+| Patrick | 25-30 cm | 30.1-35 cm | > 35 cm |
+| Samuel | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+| Anna | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Vianca | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Jacob | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+:::
+
+:::tip
+| | 1 | 2 | 3 |
+| ------- | --------- | ---------- | ------- |
+| Patrick | 25-30 cm | 30.1-35 cm | > 35 cm |
+| Samuel | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+| Anna | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Vianca | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Jacob | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+:::
+
+:::caution
+| | 1 | 2 | 3 |
+| ------- | --------- | ---------- | ------- |
+| Patrick | 25-30 cm | 30.1-35 cm | > 35 cm |
+| Samuel | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+| Anna | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Vianca | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Jacob | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+:::
+
+:::danger
+| | 1 | 2 | 3 |
+| ------- | --------- | ---------- | ------- |
+| Patrick | 25-30 cm | 30.1-35 cm | > 35 cm |
+| Samuel | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+| Anna | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Vianca | 8-11.9 cm | 12-15.9 cm | 16 cm |
+| Jacob | 8-11.9 cm | 12-15.9 cm | ≥ 16 cm |
+:::
+
+## Another example
+
+| Destination            | Web | Mobile | Server | Web | Mobile |
+| ---------------------- | --- | ------ | ------ | --- | ------ |
+| 1Flow                  | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+| 1Flow Mobile Plugin ℹ️ | ⬜️  | ✅     | ⬜️     | ⬜️  | ⬜️     |
+| 1Flow Web (Actions) ℹ️ | ✅  | ⬜️     | ⬜️     | ⬜️  | ⬜️     |
+| 2mee                   | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+| Aampe                  | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+| AB Smartly             | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+| AB Tasty client side   | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+| ABsmartly (Actions)    | ✅  | ⬜️     | ✅     | ⬜️  | ⬜️     |
+| Acoustic (Actions) ℹ️  | ✅  | ⬜️     | ✅     | ⬜️  | ⬜️     |
+| Actable Predictive ℹ️  | ✅  | ⬜️     | ✅     | ⬜️  | ⬜️     |
+| Actions Pipedrive ℹ️   | ✅  | ⬜️     | ✅     | ⬜️  | ⬜️     |
+| ActiveCampaign         | ✅  | ✅     | ✅     | ⬜️  | ⬜️     |
+
+## Inside `<details>`
+
+<details open>
+<summary>View data</summary>
+
+| #   | First          | Last     | Handle   |
+| --- | -------------- | -------- | -------- |
+| 1   | Mark           | Otto     | @mdo     |
+| 2   | Jacob          | Thornton | @fat     |
+| 3   | Larry the Bird |          | @twitter |
+
+</details>
diff --git a/packages/starlight/style/markdown.css b/packages/starlight/style/markdown.css
index b1b4bc73..836c5320 100644
--- a/packages/starlight/style/markdown.css
+++ b/packages/starlight/style/markdown.css
@@ -100,17 +100,40 @@
 	padding-inline-start: 1rem;
 }
 
+/* Table styling */
 .sl-markdown-content table:not(:where(.not-content *)) {
 	display: block;
 	overflow: auto;
-	border-collapse: collapse;
-}
-.sl-markdown-content tr:nth-child(2n):not(:where(.not-content *)) {
-	background-color: var(--sl-color-gray-7, var(--sl-color-gray-6));
+	border-spacing: 0;
 }
 .sl-markdown-content :is(th, td):not(:where(.not-content *)) {
-	border: 1px solid var(--sl-color-hairline-light);
-	padding: 0.375rem 0.8125rem;
+	border-bottom: 1px solid var(--sl-color-gray-5);
+	padding: 0.5rem 1rem;
+	/* Align text to the top of the row in multiline tables. */
+	vertical-align: baseline;
+}
+.sl-markdown-content :is(th:first-child, td:first-child):not(:where(.not-content *)) {
+	padding-inline-start: 0;
+}
+.sl-markdown-content :is(th:last-child, td:last-child):not(:where(.not-content *)) {
+	padding-inline-end: 0;
+}
+.sl-markdown-content th:not(:where(.not-content *)) {
+	color: var(--sl-color-white);
+	font-weight: 600;
+}
+/* Align headings to the start of the line unless set by the `align` attribute. */
+.sl-markdown-content th:not([align]):not(:where(.not-content *)) {
+	text-align: start;
+}
+/* Table styles inside asides */
+.sl-markdown-content .starlight-aside :is(th, td):not(:where(.not-content *)) {
+	border-color: var(--sl-color-gray-4);
+}
+@supports (border-color: color-mix(in srgb, var(--sl-color-asides-text-accent) 30%, transparent)) {
+	.sl-markdown-content .starlight-aside :is(th, td):not(:where(.not-content *)) {
+		border-color: color-mix(in srgb, var(--sl-color-asides-text-accent) 30%, transparent);
+	}
 }
 
 .sl-markdown-content hr:not(:where(.not-content *)) {