srcdev-nuxt-components 9.1.48 → 9.1.50

package/app/components/01.atoms/card/CONSUMER-STYLING.md

@@ -0,0 +1,175 @@
+# CardCore — Consumer Styling Guide
+
+## Public token API
+
+All `--card-core-*` tokens are the stable override surface. Set them at any scope (global, page,
+or instance) without touching the component itself.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--card-core-row-gap` | `1rem` | Gap between card rows |
+| `--card-core-inner-padding` | `1rem` | Internal padding (applied per row by the consumer) |
+| `--card-core-border-radius` | `0.5rem` | Corner rounding |
+| `--card-core-border` | `0.2rem solid var(--slate-08)` | Full border shorthand |
+| `--card-core-box-shadow` | `0.1rem 0.1rem 0.4rem oklch(from var(--slate-08) l c h / 0.45)` | Box shadow shorthand |
+| `--card-core-background-color` | `transparent` | Main background colour |
+| `--card-core-background-image` | `none` | Main background image |
+| `--card-core-lower-background-color` | `transparent` | Blurred backdrop layer colour |
+| `--card-core-lower-background-image` | `none` | Blurred backdrop layer image |
+| `--card-core-lower-background-position` | `center` | Backdrop image position |
+| `--card-core-lower-background-blur` | `16px` | Backdrop blur amount |
+| `--card-core-lower-scale` | `1.1` | Backdrop scale (zoom to hide blur edges) |
+
+> **Variant note**: The `solid`, `subtle`, `soft`, and `outline` variants directly override the
+> internal `--_card-background-color` and `--_card-border` tokens, bypassing the public tokens
+> for those properties. To override a variant's colours, target the variant class directly (see
+> [Per-variant overrides](#per-variant-overrides) below).
+
+---
+
+## Global theming — app-level CSS file
+
+Create `assets/styles/setup/07.components/card-core.css` in the consuming app and set tokens on
+`:root`. These values apply to every `CardCore` instance across the site.
+
+```css
+/* assets/styles/setup/07.components/card-core.css */
+:root {
+  --card-core-border-radius: 1rem;
+  --card-core-border: 0.1rem solid var(--brand-border);
+  --card-core-box-shadow: 0 0.2rem 1.2rem rgb(0 0 0 / 8%);
+  --card-core-row-gap: 0;
+}
+```
+
+---
+
+## Per-variant overrides
+
+Variants override internal tokens directly, so target the variant class to change their colours:
+
+```css
+/* assets/styles/setup/07.components/card-core.css */
+:root {
+  /* shared geometry */
+  --card-core-border-radius: 0.8rem;
+}
+
+/* variant colour overrides — set on the variant class, not :root */
+.card-core {
+  &.solid {
+    --_card-background-color: var(--brand-surface);
+    --_card-border: 0.1rem solid var(--brand-border);
+  }
+
+  &.subtle {
+    --_card-background-color: color-mix(in oklab, var(--brand-surface) 50%, transparent);
+    --_card-border: 0.1rem solid var(--brand-border);
+  }
+
+  &.outline {
+    --_card-border: 0.15rem solid var(--brand-primary);
+  }
+}
+```
+
+---
+
+## Blurred backdrop pattern
+
+Set `--card-core-lower-background-image` and `--card-core-lower-background-color` to create a
+blurred translucent layer behind the card content. The `::before` pseudo-element handles the blur
+and the scale hides the blur-edge artefact.
+
+```css
+.card-core {
+  &.hero-card {
+    --card-core-lower-background-image: url("/images/hero.jpg");
+    --card-core-lower-background-blur: 24px;
+    --card-core-lower-scale: 1.15;
+    --card-core-lower-background-color: rgb(0 0 0 / 30%); /* tint over image */
+    --card-core-background-color: transparent;
+  }
+}
+```
+
+Or inline for a single instance:
+
+```vue
+<CardCore
+  variant="solid"
+  style="
+    --card-core-lower-background-image: url('/images/hero.jpg');
+    --card-core-lower-background-blur: 20px;
+  "
+>
+  ...
+</CardCore>
+```
+
+---
+
+## Page-scoped overrides
+
+When a card appears in a specific page context, scope overrides under the page wrapper. No
+`:deep()` is required (component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.services-page {
+  .card-core {
+    --card-core-border-radius: 1.2rem;
+    --card-core-row-gap: 0;
+
+    &.solid {
+      --_card-background-color: var(--brand-surface-alt);
+    }
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+```vue
+<CardCore :style-class-passthrough="['featured']">
+  ...
+</CardCore>
+```
+
+```css
+.card-core {
+  &.featured {
+    --card-core-border: 0.2rem solid var(--brand-primary);
+    --card-core-box-shadow: 0 0.4rem 2rem rgb(0 0 0 / 15%);
+    --card-core-border-radius: 1.6rem;
+  }
+}
+```
+
+---
+
+## Card row targeting
+
+Slot content is wrapped in `.card-row.card-row-{name}`. Target rows for padding, borders, or
+backgrounds without modifying the component:
+
+```css
+.card-core {
+  .card-row-header {
+    padding: 1.6rem;
+    background-color: var(--brand-primary);
+    color: white;
+  }
+
+  .card-row-body {
+    padding: 1.6rem;
+  }
+
+  .card-row-footer {
+    padding: 1.2rem 1.6rem;
+    border-top: 0.1rem solid var(--brand-border);
+  }
+}
+```

package/app/components/01.atoms/card/CardCore.vue

@@ -41,50 +41,77 @@ watch(
 <style lang="css">
 @layer components {
   .card-core {
-    --_inner-padding: 1rem;
-    --_background-color: white;
-    --_border-color: green;
-    --_border-width: 0.2rem;
-    --_box-shadow-color: transparent;
+    --_card-row-gap: var(--card-core-row-gap, 1rem);
+    --_card-padding: var(--card-core-inner-padding, 1rem);
+    --_card-lower-background-image: var(--card-core-lower-background-image, none);
+    --_card-lower-background-position: var(--card-core-lower-background-position, center);
+    --_card-lower-background-color: var(--card-core-lower-background-color, transparent);
+    --_card-lower-background-blur: var(--card-core-lower-background-blur, 16px);
+    --_card-lower-scale: var(--card-core-lower-scale, 1.1);
+    --_card-background-image: var(--card-core-background-image, none);
+    --_card-background-color: var(--card-core-background-color, transparent);
+    --_card-border: var(--card-core-border, 0.2rem solid var(--slate-08));
+    --_card-border-radius: var(--card-core-border-radius, 0.5rem);
+    --_card-box-shadow: var(--card-core-box-shadow, 0.1rem 0.1rem 0.4rem oklch(from var(--slate-08) l c h / 0.45));
 
     display: grid;
     grid-auto-flow: row;
-    /* gap: 1rem; */
-    border-radius: 0.5rem;
+    gap: var(--_card-row-gap);
+    border-radius: var(--_card-border-radius);
     overflow: hidden;
+    position: relative;
 
-    background-color: var(--_background-color, transparent);
-    border: var(--_border-width) solid var(--_border-color, transparent);
-    box-shadow: 0 0 0.4rem var(--_border-width) var(--_box-shadow-color, transparent);
+    background-color: var(--_card-background-color, transparent);
+    border: var(--_card-border);
+    box-shadow: var(--_card-box-shadow);
+
+    &::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      background-color: var(--_card-lower-background-color);
+      background-image: var(--_card-lower-background-image);
+      background-position: var(--_card-lower-background-position, center);
+      background-size: cover;
+      background-repeat: no-repeat;
+      filter: blur(var(--_card-lower-background-blur));
+      scale: var(--_card-lower-scale);
+      z-index: 0;
+    }
+
+    > * {
+      position: relative;
+      z-index: 1;
+    }
 
     &.no-outline {
-      --_border-width: 0;
+      --_card-border: 0 solid transparent;
+      --_card-box-shadow: none;
     }
 
     &.solid {
-      --_background-color: light-dark(var(--slate-00), var(--slate-10));
-      --_border-color: red;
+      --_card-background-color: light-dark(var(--slate-00), var(--slate-10));
+      --_card-border: 0.2rem solid var(--slate-08);
     }
 
     &.subtle {
-      --_background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 50%, transparent);
-      --_border-color: red;
+      --_card-background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 50%, transparent);
+      --_card-border: 0.2rem solid var(--slate-08);
     }
 
     &.soft {
-      --_background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 20%, transparent);
-      --_box-shadow-color: color-mix(in oklab, light-dark(var(--slate-02), var(--slate-08)) 80%, transparent);
+      --_card-background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 20%, transparent);
+      --_card-box-shadow-color: color-mix(in oklab, light-dark(var(--slate-02), var(--slate-08)) 80%, transparent);
     }
 
     &.outline {
-      --_background-color: transparent;
-      --_border-color: green;
+      --_card-background-color: transparent;
+      --_card-border: 0.2rem solid var(--slate-08);
     }
 
     &.has-dividers {
       .card-row + .card-row {
-        /* border-top: 0.2rem solid var(--_border-color); */
-        border-top: 0.2rem solid green;
+        border-top: 0.2rem solid var(--slate-08);
       }
     }
   }

package/app/components/01.atoms/display-dialog/CONSUMER-STYLING.md

@@ -0,0 +1,163 @@
+# DisplayDialog — Consumer Styling Guide
+
+## Public token API
+
+All `--display-dialog-*` tokens are the stable override surface. Because dialogs are site-wide UI
+elements — not inline components — the recommended approach is to set tokens once in a **global CSS
+file** rather than per-instance via `styleClassPassthrough`.
+
+### Overlay
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-dialog-backdrop-blur` | `blur(0.5rem)` | CSS filter applied to content behind the overlay |
+| `--display-dialog-backdrop-background` | `rgba(0, 0, 0, 0.5)` | Overlay scrim colour |
+| `--display-dialog-z-index` | `999999` | Stacking order of the overlay |
+| `--display-dialog-transition-duration` | `200ms` | Open/close transition speed (opacity, display, close-button hover) |
+
+### Dialog panel
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-dialog-inner-border-radius` | `0.8rem` | Panel corner rounding |
+| `--display-dialog-inner-border` | `0.1rem solid light-dark(var(--slate-10), var(--slate-02))` | Panel border shorthand |
+| `--display-dialog-inner-outline` | `0.1rem solid light-dark(var(--slate-10), var(--slate-00))` | Panel outer outline (sits outside the border) |
+| `--display-dialog-inner-background` | `light-dark(var(--slate-00), var(--slate-10))` | Panel background colour |
+
+### Header
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-dialog-header-padding` | `1.2rem` | Header area padding |
+| `--display-dialog-header-button-margin` | `0` | Close button margin |
+| `--display-dialog-header-button-padding` | `0.4rem` | Close button padding |
+| `--display-dialog-header-button-border` | `0.1rem solid transparent` | Close button border (resting) |
+| `--display-dialog-header-button-border-radius` | `0.4rem` | Close button corner rounding |
+| `--display-dialog-header-button-outline` | `0.1rem solid transparent` | Close button outline (resting) |
+| `--display-dialog-header-button-border-hover` | `0.1rem solid light-dark(var(--slate-08), var(--slate-04))` | Close button border on hover/focus |
+| `--display-dialog-header-button-outline-hover` | `0.1rem solid light-dark(var(--slate-08), var(--slate-04))` | Close button outline on hover/focus |
+| `--display-dialog-header-button-icon-color` | `light-dark(var(--slate-09), var(--slate-02))` | Close button icon colour |
+| `--display-dialog-header-button-icon-size` | `2.4rem` | Close button icon size |
+
+### Content & footer
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-dialog-content-padding` | `1.2rem` | Content area padding |
+| `--display-dialog-footer-gap` | `1.2rem` | Gap between footer action buttons |
+| `--display-dialog-footer-padding` | `1.2rem` | Footer area padding |
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/display-dialog.css` in the consuming app and set tokens
+on `:root`. This applies to every `DisplayDialog` across the site.
+
+```css
+/* assets/styles/setup/07.components/display-dialog.css */
+:root {
+  --display-dialog-backdrop-background: rgba(0, 0, 0, 0.6);
+  --display-dialog-inner-border-radius: 1.2rem;
+  --display-dialog-inner-background: var(--brand-surface);
+  --display-dialog-inner-border: 0.1rem solid var(--brand-border);
+  --display-dialog-inner-outline: none;
+  --display-dialog-transition-duration: 250ms;
+
+  --display-dialog-header-button-icon-color: var(--brand-text-muted);
+  --display-dialog-footer-gap: 0.8rem;
+}
+```
+
+---
+
+## Per-variant overrides
+
+The `fullscreen` variant bypasses `--_inner-border-radius`, `--_inner-border`, and
+`--_inner-outline` directly (setting them to `0`/`none`). To restyle the fullscreen panel,
+target the private tokens on `.inner.fullscreen`:
+
+```css
+.display-dialog {
+  .inner {
+    &.confirm {
+      /* e.g. constrain confirm panel width further */
+      max-width: 40rem;
+    }
+
+    &.alert {
+      --display-dialog-inner-border: 0.2rem solid var(--color-danger);
+    }
+
+    &.fullscreen {
+      /* private tokens are the only lever here */
+      --_inner-background: var(--brand-surface-alt);
+    }
+  }
+}
+```
+
+---
+
+## Section targeting
+
+Target `.header`, `.dialog-content`, and `.footer` directly to adjust layout within the panel:
+
+```css
+.display-dialog {
+  .header {
+    border-bottom: 0.1rem solid var(--brand-border);
+  }
+
+  .dialog-content {
+    /* content area uses --display-dialog-content-padding */
+  }
+
+  .footer {
+    border-top: 0.1rem solid var(--brand-border);
+    justify-content: space-between; /* override default flex-end */
+  }
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Because `<DisplayDialog>` renders inside the page's DOM tree (even though it is `position: fixed`),
+you can scope overrides to a specific page without affecting the rest of the site:
+
+```css
+/* In the consuming page's unscoped <style> block */
+.checkout-page {
+  .display-dialog {
+    --display-dialog-inner-border-radius: 0;
+    --display-dialog-backdrop-background: rgba(0, 0, 0, 0.8);
+
+    .footer {
+      justify-content: stretch;
+    }
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+Use sparingly — prefer global or page-scoped CSS for dialogs. When a single instance genuinely
+needs a different look, pass a modifier class and target it alongside `.display-dialog`:
+
+```vue
+<DisplayDialog :style-class-passthrough="['danger-dialog']" ...>
+```
+
+```css
+.display-dialog.danger-dialog {
+  --display-dialog-backdrop-background: rgba(180, 0, 0, 0.4);
+
+  .inner {
+    --display-dialog-inner-border: 0.2rem solid var(--color-danger);
+  }
+}
+```