SRCDEV Hair Treatments

Note: Although this repo is private and developed for use with websites we develop, you are welcome to use it.

A standalone Vue 3 component library providing a hair treatment consultation wizard. Distributed via npm — no Nuxt or framework dependency required.

Post-install Setup

Run these once after initial install, then add a postinstall script so they stay in sync automatically on every npm install.

Images

The component uses swatch and hair-type images that must be served from your app's public/ directory. Add this script to your package.json:

"setup:assets": "cp -r node_modules/srcdev-hair-treatments/public/images/. public/images/"

Then run it after install:

npm run setup:assets

Images are copied into public/images/treatment-consultant/. Re-running after a package update picks up any new or changed images.

Claude Code Skills

This package ships consumer-facing Claude Code skills — reference docs for using the component in your app — in .claude/skills/public/.

To make them available in your project, add this script to your package.json:

"setup:claude": "cp -r node_modules/srcdev-hair-treatments/.claude/skills/public/. .claude/skills/srcdev-hair-treatments"

Then run it after install:

npm run setup:claude

Skills are copied into .claude/skills/srcdev-hair-treatments/ so they never conflict with or overwrite skills your own project defines. Re-running the script after a package update is safe.

Automating with postinstall

Once both scripts are defined, wire them into a postinstall hook so they run automatically on every npm install. For a Nuxt app this looks like:

"postinstall": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude && npm run setup:assets"

Adjust the leading command (nuxt prepare, vite build, etc.) to match your framework's own post-install needs, or omit it entirely if your app doesn't need one.

Install

npm install srcdev-hair-treatments

Peer dependency

Vue 3.4+ must be installed in the consuming app:

npm install vue@^3.4

Basic Usage

Import the component and its bundled stylesheet:

import { TreatmentConsultant } from "srcdev-hair-treatments";
import "srcdev-hair-treatments/dist/style.css";

<template>
  <TreatmentConsultant />
</template>

App-level Configuration (Recommended)

For most projects you'll want to configure the component once — at app level — rather than repeating :config on every usage. Use createHairTreatments to register a plugin when your app starts:

// e.g. plugins/hair-treatments.ts (Nuxt) or main.ts (plain Vue)
import { createHairTreatments, defaultConfig } from "srcdev-hair-treatments";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(
    createHairTreatments({
      behaviour: {
        currency: "£",
        allowMultipleTreatments: true,
      },
      treatments: defaultConfig.treatments.map((t) => ({
        ...t,
        display: !["perm", "relaxer", "japanese-straightening"].includes(t.id),
      })),
      text: {
        cta: {
          bookHref: "/book",
          bookLabel: "Book Your Appointment",
        },
      },
    })
  );
});

For a plain Vue app (no Nuxt), register the plugin in main.ts:

import { createApp } from "vue";
import { createHairTreatments } from "srcdev-hair-treatments";
import App from "./App.vue";

const app = createApp(App);

app.use(
  createHairTreatments({
    behaviour: { currency: "£" },
  })
);

app.mount("#app");

Every <TreatmentConsultant /> in your app automatically picks up this config. The :config prop still works on individual instances and always wins — so you can set site-wide defaults via the plugin and fine-tune specific pages with the prop.

Consumer Requirements

The component intentionally does not impose colour tokens on your app. You must supply them yourself — either import the defaults or provide your own:

Colour tokens

@import "srcdev-hair-treatments/dist/tokens.css";

Or define the four semantic ramps yourself as CSS custom properties on :root:

:root {
  --brand-00: oklch(98% 0.0086 75);
  /* ... --brand-01 through --brand-10 */

  --success-00: oklch(98% 0.0086 157);
  /* ... --success-01 through --success-10 */

  --warning-00: oklch(98% 0.0099 50);
  /* ... --warning-01 through --warning-10 */

  --error-00: oklch(98% 0.0108 30);
  /* ... --error-01 through --error-10 */
}

Default token values are generated from ramps.config.mjs — see src/tokens.css for the full set.

No html { font-size: 62.5% } rem reset is needed. The component sizes itself via a local --_unit custom property (default 1px) rather than raw rem, so it renders at the same intended pixel sizes regardless of your app's root font-size. If you want the component to scale with your page's root font-size / browser text-zoom setting instead, opt in with:

.treatment-consultant {
  --_unit: 0.0625rem; /* 1px at a default 16px root */
}

Per-instance Configuration

You can also pass a :config prop directly to any <TreatmentConsultant />. This merges on top of the plugin config (if registered) and always wins. Pass any subset — you don't need to repeat defaults:

<TreatmentConsultant
  :config="{
    behaviour: { autoAdvance: true },
    text: {
      cta: {
        bookHref: '/book',
        bookLabel: 'Book Your Appointment',
      },
    },
  }"
/>

Behaviour flags

| Key | Type | Default | Description | | ------------------------- | --------- | ------- | ------------------------------------------------------------ | | autoAdvance | boolean | false | Auto-advance to the next step on selection | | allowMultipleTreatments | boolean | false | Allow selecting multiple treatments with conflict detection | | showTreatmentsStep | boolean | true | Show or hide the Treatments step (step 5) entirely | | currency | string | "£" | Currency symbol used in price display |

Text

All UI copy lives under config.text. The full shape is exported as TextConfig:

import type { TextConfig } from "srcdev-hair-treatments";

Key sections:

| Path | Description | | ---- | ----------- | | text.navigation.steps | Step label array (7 items for the default 7-step flow) | | text.navigation.back / next / viewResults / backToResults | Navigation button labels | | text.progress.stepFormat | Progress counter format string — use {step}, {total}, {label} as placeholders. Default: "Step {step} of {total} — {label}" | | text.steps.* | Step headings and subtitles | | text.results.* | Results section headings, no-colour / no-treatment messages, suitability labels | | text.summary.* | Summary panel column labels | | text.cta.bookHref | Booking link URL | | text.cta.bookLabel / disclaimer / resetLabel | CTA copy |

Text config is deep-merged — override only the keys you need.

i18n

The config prop is reactive — passing a computed() that reads from your i18n library means the component re-renders automatically when the locale changes. No special integration is needed.

// Nuxt + @nuxtjs/i18n
const { t } = useI18n();

const config = computed(() => ({
  text: {
    progress: { stepFormat: t("wizard.progress") }, // e.g. "Étape {step} sur {total} — {label}"
    steps: {
      hairType: t("wizard.steps.hairType"),
      naturalColour: t("wizard.steps.naturalColour"),
      // ... only override the keys you need
    },
    cta: {
      bookLabel: t("wizard.cta.bookLabel"),
      bookHref: "/book",
    },
  },
}));

<TreatmentConsultant :config="config" />

The {step}, {total}, and {label} placeholders in text.progress.stepFormat can appear in any order, which matches how most i18n libraries handle interpolation.

Treatments — showing and hiding

Each treatment has an optional display field. Set it to false to hide that treatment from the wizard without removing it from the data:

import { defaultConfig } from "srcdev-hair-treatments";

const config = {
  treatments: defaultConfig.treatments.map((t) => ({
    ...t,
    display: !["perm", "relaxer", "japanese-straightening"].includes(t.id),
  })),
};

This is the preferred approach over .filter() because it keeps all the treatment data intact (notes, compatibility rules, conflict exclusions) while simply hiding specific options from the UI.

Other data arrays

hairTypes, naturalColours, desiredColours, applicationTypes, and cuts are replaced wholesale when provided. Always use defaultConfig as a base:

import { defaultConfig } from "srcdev-hair-treatments";

const config = {
  naturalColours: [
    ...defaultConfig.naturalColours,
    { id: "custom", label: "Custom Blend", colour: "#abc123" },
  ],
};

Events

The component emits two events, both with the same ConsultationSelections payload shape:

| Event | When | | ----- | ---- | | change | Every time any selection changes (hair type, colour, cut, treatments, etc.) | | complete | Once, when the user reaches the Results step |

<script setup lang="ts">
import { TreatmentConsultant } from "srcdev-hair-treatments";
import type { ConsultationSelections } from "srcdev-hair-treatments";

function onChange(selections: ConsultationSelections) {
  // { hairType, naturalColour, desiredColour, applicationType, cut, treatments }
}

function onComplete(selections: ConsultationSelections) {
  // fires once, when the results step is first reached
}
</script>

<template>
  <TreatmentConsultant @change="onChange" @complete="onComplete" />
</template>

Overriding Styles

The component root class is .treatment-consultant. All internal CSS custom properties are scoped to it and can be overridden in your stylesheet:

.treatment-consultant {
  /* Fonts — default to system fonts, zero setup required */
  --treatment-consultant-font-body: "My Font", sans-serif; /* body, default: system-ui, sans-serif */
  --treatment-consultant-font-heading: "My Heading Font", serif; /* headings, default: Georgia, serif */
  --treatment-consultant-font-label: "My Label Font", sans-serif; /* small uppercase UI labels, default: same as font-body */

  /* Check badge */
  --treatment-consultant-checked-surface-colour: hsl(220 80% 40%);
  --treatment-consultant-checked-stroke-colour: hsl(220 80% 80%);

  /* Colour swatch circles (hair type, colour steps, results summary) */
  --circle-swatch-size: 80px; /* default */
  --circle-swatch-border-width: 3px;
  --circle-swatch-border-color: var(--_border-active);
  --circle-swatch-outline-width: 1px;
  --circle-swatch-outline-color: transparent;
  --circle-swatch-img-scale: 1.1;
}

You can also pass additional classes to the root element:

<TreatmentConsultant style-class-passthrough="my-custom-theme" />

Exported API

import {
  TreatmentConsultant,        // Vue component
  createHairTreatments,       // plugin factory — register once at app level
  HAIR_TREATMENTS_CONFIG_KEY, // advanced: the raw injection key, if you need to provide()/inject() manually
  defaultConfig,               // full default config object
  mergeConfig,                 // utility: mergeConfig(defaultConfig, partialOverride)
} from "srcdev-hair-treatments";

import type {
  // Config
  TreatmentConsultantConfig,
  TextConfig,
  DeepPartial,

  // ID types
  HairTypeId,
  NaturalColourId,
  DesiredColourId,
  TreatmentId,
  ApplicationTypeId,
  CutId,

  // Data shape types
  HairTypeOption,
  ColourOption,
  DesiredColourOption,
  Treatment,
  ApplicationTypeOption,
  CutOption,
  CutWarning,

  // Result types
  Recommendation,
  Suitability,
  SuitabilityEntry,

  // Event payload — see "Events" above
  ConsultationSelections,
} from "srcdev-hair-treatments";

Development

Prerequisites

• Node 20–22
• npm 10+

Commands

# Install dependencies
npm install

# Start Storybook dev server (http://localhost:6006)
npm run storybook

# Type check
npm run typecheck

# Lint
npm run lint

# Build library output (dist/)
npm run build

Testing

Unit Tests (Vitest)

Unit tests cover the colour recommendation matrix, config merge logic, and all composable behaviour (navigation, step skipping, treatment conflict logic, cut warnings, and computed values).

# Watch mode
npm run test

# Single run
npm run test:run

# Browser UI
npm run test:ui

# Update snapshots
npm run test:update

Visual Regression Tests (Playwright)

Requires Storybook to be built and served first.

# 1. Build and serve Storybook
npm run storybook:serve

# 2. In a separate terminal, run visual tests
npm run playwright

# Update visual baselines after an intentional change
npm run playwright:update

Visual tests run across Chromium, Firefox, and WebKit.

What Each Layer Catches

| Change | Unit tests | Visual tests | | ------------------------------- | :--------: | :----------: | | Config / behaviour logic broken | ✅ | ❌ | | Colour recommendation wrong | ✅ | ❌ | | Font / colour / spacing changed | ❌ | ✅ | | Layout or visual regression | ❌ | ✅ |

Storybook

# Dev server
npm run storybook

# Build static output
npm run storybook:build

# Build and serve (used before Playwright)
npm run storybook:serve

# Clear caches (if styles appear stale)
npm run storybook:cache:clean

After clearing the cache, restart with npm run storybook. Useful when @layer CSS changes aren't reflected in the running dev server.

Fonts

Fonts are served from local files in .storybook/public/_fonts/ and declared in .storybook/fonts.css.

| Font | Format | | ---------------- | ------ | | Inter | woff2 | | Playfair Display | woff2 |

Architecture

src/
├── components/
│   └── treatment-consultant/
│       ├── TreatmentConsultant.vue       # Template + CSS only
│       └── stories/
│           └── TreatmentConsultant.stories.ts
├── composables/
│   └── useTreatmentConsultant.ts        # All reactive state and actions
├── config/
│   ├── types.ts                          # All types — IDs, data shapes, TextConfig, TreatmentConsultantConfig
│   ├── defaults.ts                       # defaultConfig + mergeConfig
│   └── matrix.ts                         # Colour recommendation logic (private)
└── index.ts                              # Public API exports

The recommendation matrix (natural colour × desired colour → suitability) is private to the package and not part of the public API.

Known Issues

Vercel deploy fails with missing @oxc-transform arm binding (Nuxt apps)

Symptom: Build passes locally on macOS but fails on Vercel with an npm error about @oxc-transform/binding-linux-arm-gnueabihf.

Cause: npm on macOS can write an incomplete stub entry for @oxc-transform/binding-linux-arm-gnueabihf (no version field) into the lock file. On Vercel's Linux x64 environment the OS name matches the arm package name, so npm tries to process the entry, hits the missing version, and errors out.

Fix: Pin your consuming app to Node 24+ so both local and Vercel use the same npm version, which generates correct lock file stubs. Add an engines field to your package.json:

"engines": {
  "node": ">= 24"
}

If you use .nvmrc, set it to 24 as well — but engines is what Vercel reads to select the runtime. You may also need to delete package-lock.json and re-run npm install locally to regenerate a clean lock file before redeploying.

This is a Nuxt / oxc-transform interaction and is likely to be resolved in a future Nuxt release.