From 4f3d1ef0cf01134c8638e710bd1cef8081f35106 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sun, 21 Dec 2025 20:51:52 -0800
Subject: [PATCH] So much better

---
 scss/_card.scss                           | 37 ++++++++++++-----
 site/src/content/docs/components/card.mdx | 49 ++++++-----------------
 2 files changed, 41 insertions(+), 45 deletions(-)

diff --git a/scss/_card.scss b/scss/_card.scss
index c7f115d863..5d96a9d32c 100644
--- a/scss/_card.scss
+++ b/scss/_card.scss
@@ -13,7 +13,7 @@ $card-border-color:                 var(--border-color-translucent) !default;
 $card-border-radius:                var(--border-radius-lg) !default;
 $card-box-shadow:                   null !default;
 $card-inner-border-radius:          calc(#{$card-border-radius} - #{$card-border-width}) !default;
-$card-cap-padding-y:                $card-spacer-y !default;
+$card-cap-padding-y:                $card-spacer-y * .75 !default;
 $card-cap-padding-x:                $card-spacer-x !default;
 $card-cap-bg:                       var(--bg-1) !default;
 $card-cap-color:                    null !default;
@@ -76,7 +76,7 @@ $card-body-gap:                     $card-spacer-y * .5 !default;
     align-items: flex-start;
     padding: var(--card-spacer-y) var(--card-spacer-x);
     color: var(--card-color);
-    border: solid var(--card-border-color);
+    border: solid var(--theme-bg, var(--card-border-color));
     border-width: 0 var(--card-border-width);
 
     > * {
@@ -86,8 +86,7 @@ $card-body-gap:                     $card-spacer-y * .5 !default;
 
   .card-body,
   .card-list {
-    // border: var(--card-border-width) solid var(--card-border-color);
-    border: solid var(--card-border-color);
+    border: solid var(--theme-bg, var(--card-border-color));
     border-width: 0 var(--card-border-width);
 
     &:first-child {
@@ -112,9 +111,9 @@ $card-body-gap:                     $card-spacer-y * .5 !default;
   .card-header {
     padding: var(--card-cap-padding-y) var(--card-cap-padding-x);
     margin-bottom: 0; // Removes the default margin-bottom of <hN>
-    color: var(--card-cap-color);
-    background-color: var(--card-cap-bg);
-    border: var(--card-border-width) solid var(--card-border-color);
+    color: var(--theme-contrast, var(--card-cap-color));
+    background-color: var(--theme-bg, var(--card-cap-bg));
+    border: var(--card-border-width) solid var(--theme-bg, var(--card-border-color));
 
     &:first-child {
       @include border-radius(var(--card-inner-border-radius) var(--card-inner-border-radius) 0 0);
@@ -124,14 +123,34 @@ $card-body-gap:                     $card-spacer-y * .5 !default;
   .card-footer {
     padding: var(--card-cap-padding-y) var(--card-cap-padding-x);
     color: var(--card-cap-color);
-    background-color: var(--card-cap-bg);
-    border: var(--card-border-width) solid var(--card-border-color);
+    background-color: var(--theme-bg, var(--card-cap-bg));
+    border: var(--card-border-width) solid var(--theme-bg, var(--card-border-color));
 
     &:last-child {
       @include border-radius(0 0 var(--card-inner-border-radius) var(--card-inner-border-radius));
     }
   }
 
+  .card-subtle {
+    border-color: var(--theme-border, var(--card-border-color));
+
+    .card-header {
+      color: var(--theme-text-emphasis, currentcolor);
+      background-color: var(--theme-bg-subtle, var(--card-cap-bg));
+      border-color: var(--theme-border, var(--card-border-color));
+    }
+
+    .card-footer {
+      color: var(--theme-text-emphasis, currentcolor);
+      background-color: var(--theme-bg-subtle, var(--card-cap-bg));
+      border-color: var(--theme-border, var(--card-border-color));
+    }
+
+    .card-body,
+    .card-list {
+      border-color: var(--theme-border, var(--card-border-color));
+    }
+  }
 
   //
   // Header navs
diff --git a/site/src/content/docs/components/card.mdx b/site/src/content/docs/components/card.mdx
index ada0511170..0419e4b9bb 100644
--- a/site/src/content/docs/components/card.mdx
+++ b/site/src/content/docs/components/card.mdx
@@ -367,48 +367,25 @@ And with the reverse layout:
     <Placeholder width="100%" height="250" text="Image" class="card-img-end" />
   </div>`} />
 
-## Card styles
+## Theme variants
 
-Cards include various options for customizing their backgrounds, borders, and color.
+Customize cards by using our theme color utilities. By default, cards use `bg` for their background and border colors when applying a theme color. Use `.card-subtle` to swap the background and border colors for a more subtle look.
 
-### Background and color
-
-Set a `background-color` with contrasting foreground `color` with [our `.text-bg-{color}` helpers]([[docsref:helpers/color-background]]). Previously it was required to manually pair your choice of [`.text-{color}`]([[docsref:/utilities/colors]]) and [`.bg-{color}`]([[docsref:/utilities/background]]) utilities for styling, which you still may use if you prefer.
-
-<Example code={getData('theme-colors').map((themeColor) => `<div class="card text-bg-${themeColor.name} mb-3" style="max-width: 18rem;">
-    <div class="card-header">Header</div>
+<Example class="d-grid grid grid-cols-md-3" code={getData('theme-colors').map((themeColor) => `<div class="card theme-${themeColor.name}">
+    <div class="card-header">${themeColor.title}</div>
     <div class="card-body">
-      <h4 class="card-title">${themeColor.title} card title</h4>
-      <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card’s content.</p>
+      <h4 class="card-title">Card title</h4>
+      <p class="card-text">Card text…</p>
     </div>
-  </div>`)} />
+  </div>`)} customMarkup={getData('theme-colors').map((themeColor) => `<div class="card card-${themeColor.name}">…</div>`)} />
 
-<Details name="warning-color-assistive-technologies" />
-
-### Border
-
-Use [border utilities]([[docsref:/utilities/border]]) to change just the `border-color` of a card. Note that you can put `.text-{color}` classes on the parent `.card` or a subset of the card’s contents as shown below.
-
-<Example code={getData('theme-colors').map((themeColor) => `<div class="card border-${themeColor.name} mb-3" style="max-width: 18rem;">
-    <div class="card-header">Header</div>
-    <div class="card-body text-${themeColor.name}">
-      <h4 class="card-title">${themeColor.title} card title</h4>
-      <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card’s content.</p>
+<Example class="d-grid grid grid-cols-md-3" code={getData('theme-colors').map((themeColor) => `<div class="card card-subtle theme-${themeColor.name}">
+    <div class="card-header">${themeColor.title}</div>
+    <div class="card-body">
+      <h4 class="card-title">Card title</h4>
+      <p class="card-text">Card text…</p>
     </div>
-  </div>`)} />
-
-### Mixins utilities
-
-You can also change the borders on the card header and footer as needed, and even remove their `background-color` with `.bg-transparent`.
-
-<Example code={`<div class="card border-success mb-3" style="max-width: 18rem;">
-    <div class="card-header bg-transparent border-success">Header</div>
-    <div class="card-body text-success">
-      <h4 class="card-title">Success card title</h4>
-      <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card’s content.</p>
-    </div>
-    <div class="card-footer bg-transparent border-success">Footer</div>
-  </div>`} />
+  </div>`)} customMarkup={getData('theme-colors').map((themeColor) => `<div class="card card-subtle theme-${themeColor.name}">…</div>`)} />
 
 ## Card layout