srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/04.templates/page-hero-highlights/CONSUMER-STYLING.md

@@ -0,0 +1,103 @@
+# PageHeroHighlights / PageHeroHighlightsHeader — Consumer Styling Guide
+
+## Public token API
+
+### Layout
+
+| Token | Default | Controls |
+|---|---|---|
+| `--page-hero-highlights-max-width` | `1064px` | Central column cap (unless `width-constrained`) |
+| `--page-hero-highlights-gutter-mobile` | `16px` | Side gutter |
+| `--page-hero-highlights-gutter-tablet` | `40px` | Side gutter at 768px+ container width |
+| `--page-hero-highlights-gutter-desktop` | `32px` | Side gutter at 1024px+ |
+| `--page-hero-highlights-header-background` | `darkblue` | Header zone background |
+| `--page-hero-highlights-content-background` | `var(--slate-01)` | Content zone background |
+| `--page-hero-highlights-content-start-gap` | `1.2rem` | Space above the content panel |
+| `--page-hero-highlights-content-end-gap` | `1.2rem` | Space below the content zone |
+| `--page-hero-highlights-content-margin-block-start` | `2.4rem` | Space above the content slot |
+| `--page-hero-highlights-content-margin` | the strip inset | Content slot inline/bottom margin |
+
+### Highlights strip and items
+
+| Token | Default | Controls |
+|---|---|---|
+| `--page-hero-highlights-strip-gap` | `1rem` | Gap between highlight items |
+| `--page-hero-highlights-strip-inset` | `1.2rem` | Strip inline inset (with the content panel) |
+| `--page-hero-highlights-title-height` | `1fr` | Title row height |
+| `--page-hero-highlights-title-height-baseline` | `4rem` | Title row height with `highlight-title-baseline` |
+| `--page-hero-highlights-item-padding` | `1.2rem` | Item padding |
+| `--page-hero-highlights-item-padding-block-start` | the item padding | Item top padding |
+| `--page-hero-highlights-item-padding-block-start-baseline` | `0` | Item top padding with `highlight-title-baseline` |
+| `--page-hero-highlights-item-rows-gap` | `1.2rem` | Gap between item title and body |
+| `--page-hero-highlights-item-background` | `white` | Item background |
+| `--page-hero-highlights-item-border` | `1px solid black` | Item border |
+| `--page-hero-highlights-item-border-radius` | `8px` | Item rounding |
+| `--page-hero-highlights-item-colour` | `black` | Item text colour |
+
+### Content panel (`content-panel`, on by default)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--page-hero-highlights-panel-background` | `var(--slate-00)` | Panel background |
+| `--page-hero-highlights-panel-border` | `1px solid var(--slate-06)` | Panel border |
+| `--page-hero-highlights-panel-outline` | `1px solid var(--slate-02)` | Panel outline |
+| `--page-hero-highlights-panel-border-radius` | `0.8rem` | Panel rounding |
+
+### PageHeroHighlightsHeader
+
+| Token | Default | Controls |
+|---|---|---|
+| `--page-hero-highlights-header-gap` | `1.6rem` | Gap between start and end blocks |
+| `--page-hero-highlights-header-end-gap` | `0.8rem` | Gap between items in the end block |
+| `--page-hero-highlights-header-padding-block-mobile` | `1.6rem 3.2rem` | Block padding |
+| `--page-hero-highlights-header-padding-block-tablet` | `2.4rem 4.8rem` | Block padding at 768px+ |
+| `--page-hero-highlights-header-padding-block-desktop` | `3.2rem 6.4rem` | Block padding at 1024px+ |
+
+Private (not public API): `--_max-width`, `--_gutter`, `--_strip-inset`, `--_title-height`,
+`--_item-padding`, `--_item-padding-block-start`, `--_header-slot-grid-row`.
+
+> Changed 2026-09-28: every token used to be declared on the root with its value, under generic
+> names (`--max-width`, `--header-row-background-colour`, `--highlight-*`, `--content-row-*`,
+> `--content-slot-*`, `--phh-*`), so a value set on an ancestor never landed and the names could
+> collide with consumer variables. Both components' styles were also unlayered; they're now in
+> `@layer components` like the rest of the library.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `.content-align-start` / `.content-align-center` | root | `content-align` |
+| `.width-constrained` | root | `width-constrained` |
+| `.has-content-panel` | root | `content-panel` (default on) |
+| `.highlight-title-baseline` | root | `highlight-title-baseline` |
+| `.equal-widths` / `.flexible-widths`, `.justify-*` | `.page-hero-highlights-strip` | `highlights-equal-widths`, `highlights-justify` |
+
+Inner classes: `.page-hero-highlights-header-row`, `.page-hero-highlights-header-slot`,
+`.page-hero-highlights-strip`, `.page-hero-highlights-content-row` (its `::before` is the content
+panel), `.page-hero-highlights-content-slot`; header component `.page-hero-highlights-header-start`,
+`.page-hero-highlights-header-end`.
+
+**Highlight item contract:** give each element in the `#highlights` slot the class
+`page-hero-highlights-item`, with `page-hero-highlights-item-title` and
+`page-hero-highlights-item-body` children, to get the card styling and the title-row alignment.
+
+> Changed 2026-09-28: renamed from `.header-row`, `.header-slot`, `.highlights-row`, `.content-row`,
+> `.content-slot`, root `.start`/`.center`, `.highlight`/`.title`/`.body` and `.phh-start`/`.phh-end`.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to each component's root. Reactive after mount.

package/app/components/04.templates/page-hero-highlights/PageHeroHighlights.vue

@@ -5,16 +5,16 @@
     :class="[elementClasses, componentClasses]"
     :aria-labelledby="ariaLabelledby"
   >
-    <div class="header-row">
-      <div class="header-slot">
+    <div class="page-hero-highlights-header-row">
+      <div class="page-hero-highlights-header-slot">
         <slot name="header" :heading-id="headingId"></slot>
       </div>
     </div>
-    <div class="highlights-row" :class="highlightClasses">
+    <div class="page-hero-highlights-strip" :class="highlightClasses">
       <slot name="highlights"></slot>
     </div>
-    <div class="content-row">
-      <div class="content-slot">
+    <div class="page-hero-highlights-content-row">
+      <div class="page-hero-highlights-content-slot">
         <slot name="content"></slot>
       </div>
     </div>
@@ -47,7 +47,7 @@ const props = withDefaults(defineProps<Props>(), {
 const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
 const componentClasses = computed(() => ({
   "highlight-title-baseline": props.highlightTitleBaseline,
-  [props.contentAlign]: true,
+  [`content-align-${props.contentAlign}`]: true,
   "width-constrained": props.widthConstrained,
   "has-content-panel": props.contentPanel,
 }));
@@ -69,223 +69,174 @@ watch(
 </script>
 
 <style lang="css">
-.page-hero-highlights {
-  /* Layout tokens */
-  --max-width: 1064px;
-  --page-hero-highlights-gutter-mobile: 16px;
-  --page-hero-highlights-gutter-tablet: 40px;
-  --page-hero-highlights-gutter-desktop: 32px;
-
-  /* User themable tokens */
-
-  --header-row-background-colour: darkblue;
-
-  --highlights-row-item-gap: 1rem;
-  --highlights-row-initial-item-offset: 1.2rem;
-
-  --highlight-rows-gap: 1.2rem;
-  --highlight-title-height: 1fr; /* see: highlight-title-baseline class below */
-  --highlight-padding-block-start: 1.2rem;
-  --highlight-padding: 1.2rem;
-
-  --highlight-background-color: white;
-  --highlight-border: 1px solid black;
-  --highlight-border-radius: 8px;
-  --highlight-color: black;
-
-  --content-row-background-color: var(--slate-01); /* transparent */
-  --content-row-start-gap: 1.2rem;
-  --content-row-end-gap: 1.2rem;
-
-  --content-slot-margin-block-start: 2.4rem;
-  --content-slot-margin: var(--highlights-row-initial-item-offset);
-  --content-slot-background-color: var(--slate-00);
-  --content-slot-border: 1px solid var(--slate-06);
-  --content-slot-border-radius: 0.8rem;
-  --content-slot-outline: 1px solid var(--slate-02);
-
-  &.highlight-title-baseline {
-    --highlight-title-height: 4rem; /* We need to manually tweak height, preferrably a proportional value as we're not setting an top padding when not prop.highlight-title-baseline */
-    --highlight-padding-block-start: 0; /* We're setting the title height via row height, so this should be exposed for override in consuming page */
-  }
-
-  /* Internal layout variables */
-  --page-hero-highlights-gutter: var(--page-hero-highlights-gutter-mobile);
-
-  @container (width >= 768px) {
-    --page-hero-highlights-gutter: var(--page-hero-highlights-gutter-tablet);
-  }
-  @container (width >= 1024px) {
-    --page-hero-highlights-gutter: var(--page-hero-highlights-gutter-desktop);
-  }
-
-  /* Private geometry */
-  --header-slot-grid-row: 1;
-  &.highlight-title-baseline {
-    --header-slot-grid-row: 1 / span 2;
-  }
-
-  display: grid;
-  /* grid-template-columns: v-bind(gridColumns); */
-  grid-template-rows: auto var(--highlight-title-height) 1fr auto;
-  gap: 0;
-
-  &.width-constrained {
-    grid-template-columns: var(--page-hero-highlights-gutter) 1fr var(--page-hero-highlights-gutter);
-  }
-
-  &:not(.width-constrained) {
-    &.start {
-      grid-template-columns: var(--page-hero-highlights-gutter) minmax(0, var(--max-width)) minmax(
-          var(--page-hero-highlights-gutter),
-          1fr
-        );
+@layer components {
+  .page-hero-highlights {
+    --_max-width: var(--page-hero-highlights-max-width, 1064px);
+    --_gutter: var(--page-hero-highlights-gutter-mobile, 16px);
+    --_strip-inset: var(--page-hero-highlights-strip-inset, 1.2rem);
+    --_title-height: var(--page-hero-highlights-title-height, 1fr);
+    --_item-padding: var(--page-hero-highlights-item-padding, 1.2rem);
+    --_item-padding-block-start: var(--page-hero-highlights-item-padding-block-start, var(--_item-padding));
+    --_header-slot-grid-row: 1;
+
+    @container (width >= 768px) {
+      --_gutter: var(--page-hero-highlights-gutter-tablet, 40px);
     }
-    &.center {
-      grid-template-columns: max(var(--page-hero-highlights-gutter), (100% - var(--max-width)) / 2) 1fr max(
-          var(--page-hero-highlights-gutter),
-          (100% - var(--max-width)) / 2
-        );
-    }
-  }
-
-  .header-row {
-    /* Element geometry */
-    grid-column: 1 / -1;
-    grid-row: 1 / 3;
-    display: grid;
-    grid-template-columns: subgrid;
-    grid-template-rows: subgrid;
 
-    /* Element theme */
-    background-color: var(--header-row-background-colour);
-
-    .header-slot {
-      grid-column: 2;
-      grid-row: var(--header-slot-grid-row);
-      container-type: inline-size;
+    @container (width >= 1024px) {
+      --_gutter: var(--page-hero-highlights-gutter-desktop, 32px);
     }
-  }
-
-  .highlights-row {
-    /* Element geometry */
-    grid-column: 2;
-    grid-row: 2 / 4; /* rows 2–3: straddles header/content boundary */
 
-    position: relative;
-    z-index: 1;
+    &.highlight-title-baseline {
+      --_title-height: var(--page-hero-highlights-title-height-baseline, 4rem);
+      --_item-padding-block-start: var(--page-hero-highlights-item-padding-block-start-baseline, 0);
+      --_header-slot-grid-row: 1 / span 2;
+    }
 
-    /* Element theme */
-    gap: var(--highlights-row-item-gap);
-    margin-inline-start: 0;
+    display: grid;
+    grid-template-rows: auto var(--_title-height) 1fr auto;
+    gap: 0;
 
-    &.equal-widths {
-      display: grid;
-      grid-auto-columns: 1fr;
-      grid-auto-flow: column;
+    &.width-constrained {
+      grid-template-columns: var(--_gutter) 1fr var(--_gutter);
     }
 
-    &.flexible-widths {
-      display: flex;
-      flex-wrap: wrap;
-      justify-content: center;
-    }
+    &:not(.width-constrained) {
+      &.content-align-start {
+        grid-template-columns: var(--_gutter) minmax(0, var(--_max-width)) minmax(var(--_gutter), 1fr);
+      }
 
-    &.justify-start {
-      justify-content: start;
-    }
-    &.justify-center {
-      justify-content: center;
-    }
-    &.justify-end {
-      justify-content: end;
-    }
-    &.justify-space-between {
-      justify-content: space-between;
-    }
-    &.justify-space-around {
-      justify-content: space-around;
+      &.content-align-center {
+        grid-template-columns:
+          max(var(--_gutter), (100% - var(--_max-width)) / 2)
+          1fr
+          max(var(--_gutter), (100% - var(--_max-width)) / 2);
+      }
     }
 
-    .highlight {
-      /* Element geometry */
+    .page-hero-highlights-header-row {
+      grid-column: 1 / -1;
+      grid-row: 1 / 3;
       display: grid;
+      grid-template-columns: subgrid;
       grid-template-rows: subgrid;
-      grid-auto-flow: row;
+      background-color: var(--page-hero-highlights-header-background, darkblue);
 
-      /* Element theme */
-      padding-block: var(--highlight-padding-block-start) var(--highlight-padding);
-      padding-inline: var(--highlight-padding);
+      .page-hero-highlights-header-slot {
+        grid-column: 2;
+        grid-row: var(--_header-slot-grid-row);
+        container-type: inline-size;
+      }
+    }
 
-      background-color: var(--highlight-background-color);
-      border: var(--highlight-border);
-      border-radius: var(--highlight-border-radius);
-      color: var(--highlight-color);
+    .page-hero-highlights-strip {
+      grid-column: 2;
+      grid-row: 2 / 4;
+      position: relative;
+      z-index: 1;
+      gap: var(--page-hero-highlights-strip-gap, 1rem);
+      margin-inline-start: 0;
 
-      .title {
+      &.equal-widths {
         display: grid;
-        grid-row: 2;
-        align-items: end;
-        height: var(--highlight-title-height);
+        grid-auto-columns: 1fr;
+        grid-auto-flow: column;
       }
-      .body {
-        /* Element geometry */
-        grid-row: 3;
-        margin-block-start: var(--highlight-rows-gap);
 
-        /* Element theme */
+      &.flexible-widths {
+        display: flex;
+        flex-wrap: wrap;
+        justify-content: center;
       }
-    }
-  }
 
-  .content-row {
-    /* Element geometry */
-    grid-column: 1 / span 3;
-    grid-row: 3 / span 2;
-    display: grid;
-    grid-template-columns: subgrid;
-    grid-template-rows: subgrid;
+      &.justify-start {
+        justify-content: start;
+      }
 
-    position: relative;
-    isolation: isolate;
+      &.justify-center {
+        justify-content: center;
+      }
 
-    /* Element theme */
-    background-color: var(--content-row-background-color);
-    padding-block-end: var(--content-row-end-gap);
+      &.justify-end {
+        justify-content: end;
+      }
 
-    .content-slot {
-      grid-column: 2;
-      grid-row: 2;
-      margin-block: var(--content-slot-margin-block-start) var(--content-slot-margin);
-      margin-inline: 0;
-    }
-  }
+      &.justify-space-between {
+        justify-content: space-between;
+      }
 
-  &.has-content-panel {
-    .highlights-row {
-      margin-inline: var(--highlights-row-initial-item-offset);
-    }
-    .content-row {
-      &:before {
-        /* Element geometry */
-        content: "";
-        grid-template-columns: subgrid;
-        grid-template-rows: subgrid;
+      &.justify-space-around {
+        justify-content: space-around;
+      }
+
+      .page-hero-highlights-item {
         display: grid;
-        grid-column: 2;
-        grid-row: 1 / span 2;
+        grid-template-rows: subgrid;
+        grid-auto-flow: row;
+        padding-block: var(--_item-padding-block-start) var(--_item-padding);
+        padding-inline: var(--_item-padding);
+        background-color: var(--page-hero-highlights-item-background, white);
+        border: var(--page-hero-highlights-item-border, 1px solid black);
+        border-radius: var(--page-hero-highlights-item-border-radius, 8px);
+        color: var(--page-hero-highlights-item-colour, black);
+
+        .page-hero-highlights-item-title {
+          display: grid;
+          grid-row: 2;
+          align-items: end;
+          height: var(--_title-height);
+        }
+
+        .page-hero-highlights-item-body {
+          grid-row: 3;
+          margin-block-start: var(--page-hero-highlights-item-rows-gap, 1.2rem);
+        }
+      }
+    }
 
-        /* Element theme */
-        margin-top: var(--content-row-start-gap);
+    .page-hero-highlights-content-row {
+      grid-column: 1 / span 3;
+      grid-row: 3 / span 2;
+      display: grid;
+      grid-template-columns: subgrid;
+      grid-template-rows: subgrid;
+      position: relative;
+      isolation: isolate;
+      background-color: var(--page-hero-highlights-content-background, var(--slate-01));
+      padding-block-end: var(--page-hero-highlights-content-end-gap, 1.2rem);
+
+      .page-hero-highlights-content-slot {
+        grid-column: 2;
+        grid-row: 2;
+        margin-block: var(--page-hero-highlights-content-margin-block-start, 2.4rem)
+          var(--page-hero-highlights-content-margin, var(--_strip-inset));
+        margin-inline: 0;
+      }
+    }
 
-        background-color: var(--content-slot-background-color);
-        border: var(--content-slot-border);
-        outline: var(--content-slot-outline);
-        border-radius: var(--content-slot-border-radius);
+    &.has-content-panel {
+      .page-hero-highlights-strip {
+        margin-inline: var(--_strip-inset);
       }
 
-      .content-slot {
-        margin-inline: var(--content-slot-margin);
+      .page-hero-highlights-content-row {
+        &::before {
+          content: "";
+          display: grid;
+          grid-template-columns: subgrid;
+          grid-template-rows: subgrid;
+          grid-column: 2;
+          grid-row: 1 / span 2;
+          margin-top: var(--page-hero-highlights-content-start-gap, 1.2rem);
+          background-color: var(--page-hero-highlights-panel-background, var(--slate-00));
+          border: var(--page-hero-highlights-panel-border, 1px solid var(--slate-06));
+          outline: var(--page-hero-highlights-panel-outline, 1px solid var(--slate-02));
+          border-radius: var(--page-hero-highlights-panel-border-radius, 0.8rem);
+        }
+
+        .page-hero-highlights-content-slot {
+          margin-inline: var(--page-hero-highlights-content-margin, var(--_strip-inset));
+        }
       }
     }
   }

package/app/components/04.templates/page-hero-highlights/PageHeroHighlightsHeader.vue

@@ -1,9 +1,9 @@
 <template>
   <div class="page-hero-highlights-header" :class="elementClasses">
-    <div class="phh-start">
+    <div class="page-hero-highlights-header-start">
       <slot name="start"></slot>
     </div>
-    <div v-if="hasEndSlot" class="phh-end">
+    <div v-if="hasEndSlot()" class="page-hero-highlights-header-end">
       <slot name="end"></slot>
     </div>
   </div>
@@ -19,7 +19,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const slots = useSlots();
-const hasEndSlot = computed(() => Boolean(slots.end));
+const hasEndSlot = () => Boolean(slots.end);
 
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
@@ -32,45 +32,35 @@ watch(
 </script>
 
 <style lang="css">
-.page-hero-highlights-header {
-  /* User themable tokens */
-  --phh-padding-block-mobile: 1.6rem 3.2rem;
-  --phh-padding-block-tablet: 2.4rem 4.8rem;
-  --phh-padding-block-desktop: 3.2rem 6.4rem;
-  --phh-gap: 1.6rem;
-  --phh-end-gap: 0.8rem;
-
-  display: flex;
-  flex-direction: column;
-  gap: var(--phh-gap);
-
-  padding-block: var(--phh-padding-block-mobile);
-
-  @container (width >= 768px) {
-    padding-block: var(--phh-padding-block-tablet);
-  }
-  @container (width >= 1024px) {
-    padding-block: var(--phh-padding-block-desktop);
-  }
+@layer components {
+  .page-hero-highlights-header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--page-hero-highlights-header-gap, 1.6rem);
+    padding-block: var(--page-hero-highlights-header-padding-block-mobile, 1.6rem 3.2rem);
 
-  &:has(.phh-end) {
     @container (width >= 768px) {
-      display: grid;
-      grid-template-columns: repeat(2, 1fr);
-      align-items: flex-end;
-      justify-content: space-between;
+      padding-block: var(--page-hero-highlights-header-padding-block-tablet, 2.4rem 4.8rem);
     }
-  }
 
-  .phh-start {
-    /* flex: 1; */
-  }
+    @container (width >= 1024px) {
+      padding-block: var(--page-hero-highlights-header-padding-block-desktop, 3.2rem 6.4rem);
+    }
 
-  .phh-end {
-    display: flex;
-    align-items: center;
-    gap: var(--phh-end-gap);
-    /* flex-shrink: 0; */
+    &:has(.page-hero-highlights-header-end) {
+      @container (width >= 768px) {
+        display: grid;
+        grid-template-columns: repeat(2, 1fr);
+        align-items: flex-end;
+        justify-content: space-between;
+      }
+    }
+
+    .page-hero-highlights-header-end {
+      display: flex;
+      align-items: center;
+      gap: var(--page-hero-highlights-header-end-gap, 0.8rem);
+    }
   }
 }
 </style>