srcdev-nuxt-components 9.1.58 → 9.2.0

package/app/components/03.organisms/services/services-section/CONSUMER-STYLING.md

@@ -0,0 +1,149 @@
+# ServicesSection — Consumer Styling Guide
+
+## Public token API
+
+All `--services-section-*` tokens are the stable override surface. Set them globally in a
+theme file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
+
+### Layout & sizing
+
+| Token | Default | Controls |
+|---|---|---|
+| `--services-section-grid-gap` | `2rem` | Gap between image and content columns below the 768px breakpoint |
+| `--services-section-grid-gap-desktop` | `3rem` | Gap between columns at 768px and above |
+| `--services-section-image-border-radius` | `0.8rem` | Corner rounding on the service image |
+| `--services-section-price-duration-gap` | `3rem` | Gap between the duration and price rows |
+| `--services-section-price-duration-item-gap` | `0.8rem` | Gap between icon and text within a single row |
+| `--services-section-price-duration-margin-block-end` | `2rem` | Space below the price/duration row |
+| `--services-section-decorator-size` | `2rem` | Width/height of the duration and price icons |
+| `--services-section-faq-margin-block-end` | `2.4rem` | Space below the FAQ accordion |
+| `--services-section-faq-answer-line-height` | `1.6` | Line height of FAQ answer text |
+
+### Colours
+
+| Token | Default | Controls |
+|---|---|---|
+| `--services-section-faq-divider-color` | `currentColor` | Border colour between FAQ accordion items |
+| `--services-section-faq-divider-opacity` | `0.7` | Opacity of each FAQ accordion item's border |
+
+---
+
+## Text content — props, not CSS
+
+Section headings and the default CTA panel copy are **props**, not hardcoded strings, so
+there is nothing to override in CSS for these:
+
+| Prop | Default |
+|---|---|
+| `processHeading` | `"The Process"` |
+| `idealForHeading` | `"Ideal For"` |
+| `maintenanceHeading` | `"Aftercare & Maintenance"` |
+| `faqsHeading` | `"Frequently Asked Questions"` |
+| `ctaHeading` | `"Ready to book your appointment?"` |
+| `ctaBody` | `"Get in touch to book your appointment."` |
+
+```vue
+<ServicesSection
+  :service-data="service"
+  cta-heading="Ready to book your locs consultation?"
+  cta-body="Mobile service across Bath — I come to you."
+/>
+```
+
+If the CTA needs a different component entirely (not just different text), replace it with
+the `cta-panel` scoped slot instead of styling around the default `GlassPanel`:
+
+```vue
+<ServicesSection :service-data="service">
+  <template #cta-panel="{ serviceData, ctaHeading, ctaBody }">
+    <MyCustomPanel :heading="ctaHeading" :body="ctaBody">
+      <template #cta><button>Enquire Now</button></template>
+    </MyCustomPanel>
+  </template>
+</ServicesSection>
+```
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/services-section.css` in the consuming app and
+set tokens on `:root`. This applies to every `ServicesSection` across the site.
+
+```css
+/* assets/styles/setup/07.components/services-section.css */
+:root {
+  --services-section-grid-gap: 2.4rem;
+  --services-section-grid-gap-desktop: 4rem;
+  --services-section-image-border-radius: 1.2rem;
+  --services-section-faq-divider-color: var(--brand-border);
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Override tokens for a specific section by scoping them under the page or layout wrapper.
+No `:deep()` is required (component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.our-services-page {
+  .services-section {
+    --services-section-decorator-size: 2.4rem;
+    --services-section-faq-answer-line-height: 1.8;
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
+visual style, pass a modifier class:
+
+```vue
+<ServicesSection :style-class-passthrough="['highlight-service']" :service-data="service" />
+```
+
+```css
+.services-section.highlight-service {
+  --services-section-image-border-radius: 2rem;
+  --services-section-faq-divider-color: var(--color-accent);
+}
+```
+
+---
+
+## FAQ accordion styling
+
+The `AccordianCore` inside this component receives `services-section__faq` via
+`styleClassPassthrough`. To target the accordion's own internals (summary, icon rotation,
+content padding), style through that class rather than reaching into `AccordianCore`
+directly — see `.services-section__faq` in the component's own `<style>` block for the
+selectors already scoped this way (`.accordian-item.expanding-panel`,
+`.expanding-panel-summary`, `.services-section__faq-answer`).
+
+```css
+.services-section {
+  .services-section__faq {
+    .expanding-panel-details .expanding-panel-summary {
+      padding-block: 1.6rem;
+    }
+  }
+}
+```
+
+---
+
+## Notes
+
+- `--services-section-grid-gap-desktop` only applies at `768px` and above — the breakpoint
+  itself is not a token, since changing it would affect the grid's `minmax()` column sizing
+  too, not just spacing.
+- The CTA panel is rendered inside a default `<slot name="cta-panel">` — passing that slot
+  bypasses `GlassPanel` and all of its tokens (`--glass-panel-*`) entirely, along with the
+  `ctaHeading`/`ctaBody` props, which are handed to the slot for reuse rather than applied
+  automatically.

package/app/components/03.organisms/services/services-section/ServicesSection.vue

@@ -1,12 +1,19 @@
 <template>
   <component :is="tag" class="services-section" :class="[elementClasses]" :aria-labelledby="ariaLabelledby">
     <div class="services-section__grid" :class="{ 'services-section__grid--reverse': reverse }">
-      <div class="image-wrapper">
-        <NuxtImg :src="serviceData.image" :alt="serviceData.title" :loading="imageLoading" :fetchpriority="imageFetchPriority" class="image" />
+      <div class="services-section__image-wrapper">
+        <NuxtImg
+          :src="serviceData.image"
+          :alt="serviceData.title"
+          :loading="imageLoading"
+          :fetchpriority="imageFetchPriority"
+          class="services-section__image"
+        />
       </div>
-      <div class="info-wrapper" :class="infoWrapperClasses">
+      <div class="services-section__info-wrapper" :class="infoWrapperClasses">
         <EyebrowText font-size="large" :text-content="serviceData.subtitle" />
         <HeroText
+          :id="headingId"
           :tag="headerTag"
           font-size="title"
           :text-content="[
@@ -18,13 +25,13 @@
           :style-class-passthrough="['mb-20']"
         />
 
-        <div class="price-duration">
+        <div class="services-section__price-duration">
           <div class="flex-row">
-            <Icon :name="durationIcon" class="decorator" />
+            <Icon :name="durationIcon" class="services-section__decorator" />
             <span>{{ serviceData.duration }}</span>
           </div>
           <div class="flex-row">
-            <Icon :name="priceIcon" class="decorator" />
+            <Icon :name="priceIcon" class="services-section__decorator" />
             <span>{{ serviceData.price }}</span>
           </div>
         </div>
@@ -50,7 +57,7 @@
           :tag="headerTag"
           axis="horizontal"
           font-size="subheading"
-          :text-content="[{ text: 'The Process ', styleClass: 'normal' }]"
+          :text-content="[{ text: processHeading, styleClass: 'normal' }]"
           :style-class-passthrough="['mb-20']"
         />
 
@@ -72,7 +79,7 @@
           :tag="headerTag"
           axis="horizontal"
           font-size="subheading"
-          :text-content="[{ text: 'Ideal For', styleClass: 'normal' }]"
+          :text-content="[{ text: idealForHeading, styleClass: 'normal' }]"
           :style-class-passthrough="['mb-20']"
         />
 
@@ -90,7 +97,7 @@
           :tag="headerTag"
           axis="horizontal"
           font-size="subheading"
-          :text-content="[{ text: 'Aftercare &amp; Maintenance', styleClass: 'normal' }]"
+          :text-content="[{ text: maintenanceHeading, styleClass: 'normal' }]"
           :style-class-passthrough="['mb-20']"
         />
 
@@ -101,7 +108,7 @@
           :tag="headerTag"
           axis="horizontal"
           font-size="subheading"
-          :text-content="[{ text: 'Frequently Asked Questions', styleClass: 'normal' }]"
+          :text-content="[{ text: faqsHeading, styleClass: 'normal' }]"
           :style-class-passthrough="['mb-20']"
         />
 
@@ -110,7 +117,7 @@
           id="faq"
           :item-count="serviceData.faqs.length"
           :name="`faq-${useId()}`"
-          :style-class-passthrough="['services-faq']"
+          :style-class-passthrough="['services-section__faq']"
         >
           <template v-for="(_, key) in serviceData.faqs" :key="`summary-${key}`" #[`accordian-${key}-summary`]>
             {{ serviceData.faqs[key]?.question }}
@@ -119,21 +126,29 @@
             <Icon name="mdi:chevron-down" />
           </template>
           <template v-for="(_, key) in serviceData.faqs" :key="`content-${key}`" #[`accordian-${key}-content`]>
-            <p>{{ serviceData.faqs[key]?.answer }}</p>
+            <p class="services-section__faq-answer">{{ serviceData.faqs[key]?.answer }}</p>
           </template>
         </AccordianCore>
 
-        <GlassPanel v-if="!isSummary" :style-class-passthrough="['p-24']">
-          <HeroText
-            tag="h2"
-            axis="horizontal"
-            font-size="subheading"
-            :text-content="[{ text: 'Ready to book your highlights appointment?', styleClass: 'normal' }]"
-            :style-class-passthrough="['mbs-0', 'mbe-20']"
-          />
-          <p class="page-body-normal">Mobile service across Bath — I come to you.</p>
-          <slot name="cta" :service-data="serviceData"></slot>
-        </GlassPanel>
+        <slot
+          v-if="!isSummary"
+          name="cta-panel"
+          :service-data="serviceData"
+          :cta-heading="ctaHeading"
+          :cta-body="ctaBody"
+        >
+          <GlassPanel :style-class-passthrough="['services-section__glass-panel', 'p-24']">
+            <HeroText
+              tag="h2"
+              axis="horizontal"
+              font-size="subheading"
+              :text-content="[{ text: ctaHeading, styleClass: 'normal' }]"
+              :style-class-passthrough="['mbs-0', 'mbe-20']"
+            />
+            <p class="page-body-normal">{{ ctaBody }}</p>
+            <slot name="cta" :service-data="serviceData"></slot>
+          </GlassPanel>
+        </slot>
       </div>
     </div>
   </component>
@@ -152,6 +167,12 @@ interface Props {
   reverse?: boolean;
   durationIcon?: string;
   priceIcon?: string;
+  processHeading?: string;
+  idealForHeading?: string;
+  maintenanceHeading?: string;
+  faqsHeading?: string;
+  ctaHeading?: string;
+  ctaBody?: string;
   styleClassPassthrough?: string | string[];
 }
 const props = withDefaults(defineProps<Props>(), {
@@ -162,17 +183,23 @@ const props = withDefaults(defineProps<Props>(), {
   summaryAlignment: "center",
   durationIcon: "mdi:clock-time-four-outline",
   priceIcon: "mdi:currency-gbp",
+  processHeading: "The Process",
+  idealForHeading: "Ideal For",
+  maintenanceHeading: "Aftercare & Maintenance",
+  faqsHeading: "Frequently Asked Questions",
+  ctaHeading: "Ready to book your appointment?",
+  ctaBody: "Get in touch to book your appointment.",
   styleClassPassthrough: () => [],
 });
 
-const { ariaLabelledby } = useAriaLabelledById(() => props.tag);
+const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
 
 const infoWrapperClasses = computed(() => {
   return {
-    "is-summary": props.isSummary,
-    "align-start": props.isSummary && props.summaryAlignment === "start",
-    "align-center": props.isSummary && props.summaryAlignment === "center",
-    "align-end": props.isSummary && props.summaryAlignment === "end",
+    "services-section__info-wrapper--summary": props.isSummary,
+    "services-section__info-wrapper--align-start": props.isSummary && props.summaryAlignment === "start",
+    "services-section__info-wrapper--align-center": props.isSummary && props.summaryAlignment === "center",
+    "services-section__info-wrapper--align-end": props.isSummary && props.summaryAlignment === "end",
   };
 });
 
@@ -199,44 +226,47 @@ watch(
     container-name: services-section;
 
     .services-section__grid {
+      --_grid-gap: var(--services-section-grid-gap, 2rem);
+
       display: grid;
       grid-template-columns: 1fr;
-      gap: 2rem;
+      gap: var(--_grid-gap);
 
       @media (width >= 768px) {
+        --_grid-gap: var(--services-section-grid-gap-desktop, 3rem);
+
         grid-template-columns: repeat(auto-fit, minmax(446px, 1fr));
-        gap: 3rem;
 
         &.services-section__grid--reverse {
-          .image-wrapper {
-            /* The order: 2 on .image-wrapper pushes it after the content div, since by default both children have order: 0 and source order wins — so the content div naturally sits first. */
+          .services-section__image-wrapper {
+            /* The order: 2 on .services-section__image-wrapper pushes it after the content div, since by default both children have order: 0 and source order wins — so the content div naturally sits first. */
             order: 2;
           }
         }
       }
 
-      .info-wrapper {
-        &.is-summary {
+      .services-section__info-wrapper {
+        &.services-section__info-wrapper--summary {
           display: grid;
 
-          &.align-start {
+          &.services-section__info-wrapper--align-start {
             align-content: start;
           }
-          &.align-center {
+          &.services-section__info-wrapper--align-center {
             align-content: center;
           }
-          &.align-end {
+          &.services-section__info-wrapper--align-end {
             align-content: end;
           }
         }
       }
 
-      .image-wrapper {
+      .services-section__image-wrapper {
         align-self: start;
-        border-radius: 8px;
+        border-radius: var(--services-section-image-border-radius, 0.8rem);
         overflow: hidden;
 
-        .image {
+        .services-section__image {
           display: block;
           width: 100%;
           height: 100%;
@@ -244,45 +274,38 @@ watch(
         }
       }
 
-      .price-duration {
+      .services-section__price-duration {
         display: flex;
         flex-direction: row;
-        gap: 3rem;
+        gap: var(--services-section-price-duration-gap, 3rem);
         align-items: center;
-        margin-block-end: 2rem;
+        margin-block-end: var(--services-section-price-duration-margin-block-end, 2rem);
 
         > div {
           display: flex;
           flex-direction: row;
-          gap: 0.8rem;
+          gap: var(--services-section-price-duration-item-gap, 0.8rem);
           align-items: center;
 
-          .decorator {
-            width: 2rem;
-            height: 2rem;
+          .services-section__decorator {
+            width: var(--services-section-decorator-size, 2rem);
+            height: var(--services-section-decorator-size, 2rem);
           }
         }
       }
 
-      .glass-card {
-        background: rgba(255, 255, 255, 0.6);
-        border-radius: 1rem;
-        backdrop-filter: blur(10px);
-      }
-
-      .services-faq {
-        margin-block-end: 24px;
+      .services-section__faq {
+        margin-block-end: var(--services-section-faq-margin-block-end, 2.4rem);
 
         &.display-accordian {
           max-width: none;
-          /* margin: 0; */
 
           .accordian-item.expanding-panel {
-            border-block-end: 1px solid currentColor;
-            opacity: 0.7;
+            border-block-end: 1px solid var(--services-section-faq-divider-color, currentColor);
+            opacity: var(--services-section-faq-divider-opacity, 0.7);
 
             &:first-child {
-              border-block-start: 1px solid currentColor;
+              border-block-start: 1px solid var(--services-section-faq-divider-color, currentColor);
             }
 
             .expanding-panel-details .expanding-panel-summary {
@@ -290,7 +313,9 @@ watch(
             }
 
             .expanding-panel-content .inner {
-              /* padding-block-end: 1.2rem; */
+              .services-section__faq-answer {
+                line-height: var(--services-section-faq-answer-line-height, 1.6);
+              }
             }
           }
         }