@lamgig/booking-kit
v0.8.0
Published
Online booking for a LamGig business's Next.js website: the four booking steps, the booking's own page, and the customer's account with My appointments, on the LamGig APIs.
Maintainers
Readme
@lamgig/booking-kit
Online booking for a LamGig business's Next.js App Router website: the four booking steps
(/book), the booking's own page (/appointment/{id}), the customer's account with My
appointments (/account) and the privacy notice for bookings (/book/privacy), on the LamGig
APIs. Built for LamGig's website templates, which LamGig runs for each business.
0.3.0 — a guest books in four steps, changes or cancels from the email's link, and a signed-in
customer books with their details filled in and finds every booking in My appointments. 0.3.0 adds
deposits: a service that asks shows it, the customer ticks the policy, pays in Stripe's form, and
is booked. A business that asks none sees no change, and its pages load nothing from Stripe. 0.x
while its first template settles the API; 1.0.0 after. A website takes 0.3.0 before its business
turns deposits on: 0.2.0 meets a service that asks with its generic words and books nothing.
0.4.0 gives the account's pages their own look — the sign-in pages, the account page and its
member card ("The account's look", below). Nothing they say, store or call changed, and the booking
steps look as before; a template that sets --lgk-* may add --lgk-heading-weight. 0.4.1 draws
Cloudflare's security box ("Verify you are human", when it shows) light or dark to match the page it
sits on, where it used to follow the visitor's system setting — a black box on a light page for anyone
in dark mode. Nothing else changed. 0.5.0 makes the kit restyled by variables alone: every shadow,
the member card's gradient and its inner frame are variables a template can set to none; the
hairline frames that were drawn as shadows (the monogram, the date tiles, the email tabs' track, the
member card's edge) are real borders, so they stay when the shadows go; and the line width, the small
capitals, a status's pill, a face's circle and a photo's corner are variables too ("Restyle it",
below). Its defaults draw what 0.4.1 drew, measured element by element in Chromium and WebKit. The
differences: the member card's edge is the monogram's and the upcoming date tile's colour (the button
22% into the page, was 20%); the chosen email tab's ring is a border just inside the tab where it was a
ring just outside it; and under forced colours only the chosen tab is ringed, where none was.
0.6.0 lets a template lay /book out its own way, each piece opt-in through BookPage's new
layout prop ("Lay out /book", below): the appointment card — the business's photo (a new
photo prop), name and address, the visit so far, the total and the step's one action — beside the
steps on a wide container, and on a narrow one a bar pinned at the foot that raises the card as a
sheet (or the card itself under the step); named steps (Services, With, When, Details, the done
ones a way back); times under Morning, Afternoon and Evening; and the cancellation policy
folded. A template that passes no layout sees 0.5.0's page: the same markup, rules and look
(measured: every element's computed style and box), with one exception — every heading's last word is now its own element, <span
class="lgk-last-word">, unstyled, so a template can set it apart (its brand's italic, say). That
splits a heading's text across two nodes: a template's test that finds a kit heading by its exact
text (getByText('Choose a time')) finds it by its role instead (getByRole('heading', { name:
'Choose a time' })); the accessible name is unchanged. The four steps, their addresses, the
policy's words, the API calls and the script policy are 0.5.0's. The new variables and class names
are below, in the variables table and "Class names (0.6.0)".
0.7.0 lets a signed-in member use their points on a deposit, where the business lets points be
used: the details step shows Use your points (what they have, what a step takes off, a box never
ticked for them, and how many when more than one step fits); the policy's words name the points, so the
deposit's box is asked again; the card pays only what is left, and a deposit paid entirely in points is
booked at once with no card. The booking's page says what was paid in points and by card, and what a
cancel gives back. The account says how points are used here, in place of "For now points can only be
collected", and its history names points used and given back. Nothing to install: BookPage gets
the member's checkout pass through its own server action (the session never reaches the browser); a
template adds no route file and no policy source. A guest's page is 0.6.0's. It needs a LamGig platform
that serves points on deposits (P3); against one that doesn't, the page books as 0.6.0 did and the account
keeps the old sentence. 0.7.0 also brings a customer back after signing in: a template's own page (its
checkout, say) links to signInHref('/order/checkout') — /account/sign-in?return=%2Forder%2Fcheckout — and
every way in (an emailed code, a password, Google, Apple) ends there instead of on /account; only a path of
this site is followed, anything else lands on /account as before ("What it does").
0.8.0 follows two of the business's settings on the account page. Points at the counter is now a switch,
off unless the business turns it on: Earn at the counter and How you earn's "At the counter: …" line show only
while it is on, a waiting change that only turns it off or on says so with its date, and asking for a code after it
went off reads "Points aren't given at the counter here right now, so there is no code to show. You still earn
online." (or, when the page is read again first, the button is simply gone). A visit booked online earns once the
business marks it done: where the business takes bookings online, How you earn adds "… for each $1 of a visit booked
online, before tax, once it's done", and the history names such a visit "Your appointment on November 21, 2026 · $45.00".
Nothing to install — move your range to 0.8.0 (~0.7.0 and ^0.7.0 never reach it); nothing else changes for a
template. Against a platform that says nothing of either (before P3 CS), the counter shows as before and no visit line.
Install it in a template
A template already has its site id and the platform's address, and already loads the published file. The kit needs nothing else.
npm install @lamgig/booking-kit1. The stylesheet — once, in the root layout:
import '@lamgig/booking-kit/styles.css';2. The two pages — each route file hands the kit the published file the template already loads (its tolerant parse) and the two values:
// app/book/page.tsx
import { BookPage } from '@lamgig/booking-kit';
export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
const content = await loadPublishedFile();
return <BookPage config={{ siteId: LAMGIG_SITE_ID, platformOrigin: LAMGIG_POINTER_BASE }} content={content} searchParams={searchParams} />;
}// app/appointment/[id]/page.tsx — the address every booking email links to
import { AppointmentPage, appointmentMetadata } from '@lamgig/booking-kit';
export const metadata = appointmentMetadata; // noindex, nofollow; no-referrer
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
return <AppointmentPage config={{ siteId: LAMGIG_SITE_ID, platformOrigin: LAMGIG_POINTER_BASE }} content={await loadPublishedFile()} bookingId={id} />;
}BookPage also takes layout and photo, and AppointmentPage layout (0.6.0, "Lay out /book"
below); leave them out and the pages are 0.5.0's.
Both pages render per request (they call connection()): a nonce policy needs it, and
neither has anything worth caching — the browser reads the open times and the booking itself.
// app/book/privacy/page.tsx — the privacy notice for bookings, linked from the details step
// and the booking's page
import { BookPrivacyPage, bookPrivacyMetadata } from '@lamgig/booking-kit';
export const metadata = bookPrivacyMetadata;
export default async function Page() {
return <BookPrivacyPage config={{ siteId: LAMGIG_SITE_ID, platformOrigin: LAMGIG_POINTER_BASE }} content={await loadPublishedFile()} />;
}The notice's words are the platform's, filled with the business's name, contact and cutoff and
served on /booking-page — the kit holds no copy. The page reads them on the site's server through
the fetch cache for a minute, runs no script of its own (so it needs no policy), and is a 404
where booking was never set up.
3. Headers and the script policy. Send Referrer-Policy: no-referrer on /appointment and
below. If the template enforces a Content-Security-Policy on these pages (it should — they take a
name, an email and a phone), merge bookingCspSources(...) into it:
import { bookingCspSources } from '@lamgig/booking-kit';
const sources = bookingCspSources({ platformOrigin: LAMGIG_POINTER_BASE, contentOrigin });
// script-src and frame-src: https://challenges.cloudflare.com (Turnstile, the bot check), Stripe's
// connect-src: the platform's origin (the booking API), https://api.stripe.com
// img-src: the published file's content host (photos), https://*.stripe.comStripe's sources are there for a deposit; nothing loads from Stripe until the customer reaches the pay step, so a page with no deposit requests nothing from it.
Don't forbid the browser's payment API on /book. A Permissions-Policy with payment=() leaves
cards working and quietly removes Apple Pay and Google Pay from Stripe's form. Wallets also need the
site on HTTPS and its host registered on the business's Stripe account, which turning deposits on
does.
The kit inserts Turnstile's and Stripe's scripts from its own code, so a nonce policy needs
'strict-dynamic' (or the hosts) on script-src. contentOrigin is the origin of the pointer's contentUrl. The
proxy.ts of LamGig's bare test site (apps/booking-kit-site in the platform repository) is a
complete example, proved with zero violations by the suite below.
4. Links into the kit are full page loads (<a href="/book">, not next/link): a
client-side move from a page without a policy keeps that page's document, which has none.
Install the account
Customer accounts are the business's switch on the platform. While it is off, /config answers
{ accounts: null }: every account page is a 404 and a template shows no Account link — so a
template installs the account files whether or not a business uses them.
5. The account's files — one per address, each handing the kit the request or the published
file and the template's two values (kitConfig() below stands for them). The addresses are the
contract: the platform's sign-in returns to /account/callback, its password email links to
/account/new-password.
// app/account/layout.tsx — per request, noindex, a 404 while accounts are off
import { AccountLayout, accountMetadata } from '@lamgig/booking-kit';
export const metadata = accountMetadata;
export default function Layout({ children }: { children: React.ReactNode }) {
return <AccountLayout config={kitConfig()}>{children}</AccountLayout>;
}
// app/account/page.tsx — likewise sign-in/, new-password/, delete/, deleted/, and
// app/rewards/terms/, app/rewards/notice/ (AccountPage, SignInPage, NewPasswordPage,
// DeletePage, DeletedPage, RewardsTermsPage, RewardsNoticePage; titles in ACCOUNT_TITLES)
import { ACCOUNT_TITLES, AccountPage } from '@lamgig/booking-kit';
export const metadata = { title: ACCOUNT_TITLES.account };
export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
return <AccountPage config={kitConfig()} content={await loadPublishedFile()} searchParams={searchParams} />;
}
// app/account/callback/route.ts — likewise begin/ (POST), expired/, oauth/[provider]/,
// and appointments/[id]/ (POST): accountBegin, accountCallback, accountExpired,
// accountOAuth(request, config, provider), openAppointment(request, config, id)
import { accountCallback } from '@lamgig/booking-kit';
import type { NextRequest } from 'next/server';
export function GET(request: NextRequest) {
return accountCallback(request, kitConfig());
}LamGig's bare test site (apps/booking-kit-site/app/account/ and app/rewards/ in the platform
repository) is the complete reference install: eleven /account files and the two rewards pages.
6. The script policy on /account and below — accountCspSources, the same shape without
Stripe, since nothing there pays (Turnstile for the four sign-in sends, connect-src the platform:
the browser signs in there directly), with form-action 'self'. /rewards/* needs no policy of its
own.
7. The Account link — loadAccountsConfig(kitConfig()) answers what the platform offers, or
null: show "Account" only when it answers. It reads /config through the fetch cache for a
minute, so a cached page stays cached.
Where the session lives. Sign-in ends at the site's own /account/callback, whose server sets
the session cookie itself: lg_session — host-only, HttpOnly, SameSite=Lax, Secure on https, 30
days. The browser never holds the session; every signed-in call is the site's server calling the
platform with it. The PKCE verifier waits in lg_pkce (/account only, ten minutes) while a
sign-in is in flight. The account's forms are server actions written inside the kit's pages,
closing over the template's config, so the platform's address never comes from a request.
Addresses
| Address | What it is |
|---|---|
| /book | The four steps: services → who → when → your details |
| /book?service={serviceId} | Starts with that service chosen — a service page's Book link |
| /book?with={teamMemberId} | Starts with that person: only their services, everyone's one press away |
| /appointment/{bookingId}#{token} | The booking's page. The token is the whole fragment and never reaches the website's server |
| /book/privacy | The privacy notice for bookings, as the platform serves it |
| /account | The account: My appointments, name and birthday, rewards, devices, password, Delete |
| /account/sign-in, /account/new-password, /account/delete, /account/deleted | Sign-in (an emailed code, a password, Google, Apple) and the rest of the account |
| /account/begin, /account/callback, /account/expired, /account/oauth/{provider} | The sign-in's route handlers |
| /account/appointments/{bookingId} (POST) | My appointments' Change or cancel: a fresh link, then a 303 to the booking's page |
| /rewards/terms, /rewards/notice | The rewards texts, as the platform serves them |
The full query — the kit's one contract with a template's links — keeps the visit, never the
person's details: service={serviceId}[.{addOnId}…] (repeated, in the visit's order; an add-on
stays tied to its service), with={teamMemberId}|anyone, date=YYYY-MM-DD (the business's day),
at={startsAt}, step=who|when|details. Back and a reload keep every choice; an id the
published file no longer offers is dropped; a step whose choices are missing falls back to the
first one that is. The name, email and phone live in the form only.
The look
Each template has its own design; the kit takes the business's colours, fonts and logo from the published branding and leaves the rest to the template.
Variables, two deep. The kit's root (.lgk) carries --lgk-brand-* from the published
branding (brandStyle(branding), which the pages apply themselves). styles.css draws with
--lgk-* only, each defined from a brand value. A template maps the kit onto its own tokens by
setting --lgk-* on .lgk — never the brand ones. The defaults are in :where(.lgk), so a
template's own value for any of them wins, wherever its stylesheet loads.
| Variable | Default | Used for |
|---|---|---|
| --lgk-text | --lgk-brand-text, else #111111 | All text |
| --lgk-background | --lgk-brand-background, else #ffffff | The page behind the kit |
| --lgk-button, --lgk-button-text | the contrast pick below | The main button, a chosen day or time, a ticked box |
| --lgk-accent | --lgk-brand-accent, else the button's | (reserved) |
| --lgk-muted, --lgk-line, --lgk-surface, --lgk-chosen | mixed from text and background | Secondary text, borders, panels, a chosen row |
| --lgk-problem, --lgk-done | #b42318, #067647 | The edge of a notice — on the account's pages a dot before its words and a faint tint (0.4.0) — never the words, which stay in --lgk-text |
| --lgk-font-heading, --lgk-font-body | the brand's fonts, else the page's | Headings, everything else |
| --lgk-radius, --lgk-target, --lgk-gap, --lgk-max-width | 10px, 44px, 16px, 720px | Shape and size (--lgk-radius is a registered length since 0.5.0, so 0 works) |
| --lgk-hairline, --lgk-tint | text 10% into the background; the button's colour 7% into it | The account (0.4.0): the rule between sections; the monogram, an upcoming date and the chosen deletion |
| --lgk-radius-card | --lgk-radius × 1.6 | The account's larger shapes: the member card, the counter's code, the rewards notice |
| --lgk-heading-weight | 500 | The account's headings and figures — set it to your template's (a light serif's 300, say) |
| --lgk-border-width | 1px | Every border, hairline and frame (0.5.0), Stripe's fields too; the drawn checkbox is 1.5× it, a wrong field 2×, the stepper 2×. A control's edge and the chosen tab's ring never go under 1px; 0 takes the rest away |
| --lgk-input-line | text 45% into the background | A field's edge |
| --lgk-tint-line | the button's colour 22% into the background | The edge of a tinted shape: the monogram, an upcoming date tile, the member card |
| --lgk-radius-pill, --lgk-radius-avatar, --lgk-radius-photo | 999px, 50%, 8px | A status, a face (a person's initials or photo, the monogram), a service's photo |
| --lgk-label-case, --lgk-label-tracking | uppercase, 0.14em | The account's small capitals: the business's name over a title, a section's sub-heading, the member card's labels, a date tile's month (the first a little wider, the last a little narrower) |
| --lgk-shadow-card | a hairline shadow and a soft one in the button's colour | Under the member card — none turns it off |
| --lgk-shadow-hover | a soft shadow in the button's colour | Under the account's main button while a pointer is over it — none turns it off |
| --lgk-shadow-tab | a small shadow in the text's colour | Under the chosen email tab — none turns it off; its ring stays |
| --lgk-card-background | the button's colour 13% → 4% into the background, corner to corner | The member card's ground — any background, a flat var(--lgk-tint) for one |
| --lgk-card-frame | a --lgk-border-width line, the button's colour at 16% | The member card's inner frame, 6px in — any border, none to remove it |
| --lgk-ease | cubic-bezier(0.2, 0, 0, 1) | The easing of every movement and change |
| --lgk-duration | 150ms | A state change: a choice filling, a border, a colour |
| --lgk-duration-slide | 250ms | A mark moving: the stepper's next hairline filling, a ticked box's check drawing in |
| --lgk-duration-enter, --lgk-rise | 300ms, 6px | A step opening: its content rises this far into place; the sheet rising (0.6.0) takes the duration too |
| --lgk-max-width-wide | 1120px | /book's width with the appointment card (0.6.0, layout.summary: 'card') — in place of --lgk-max-width |
| --lgk-aside-width, --lgk-aside-gap | 360px, 48px | The card's width beside the steps, and the space between them (0.6.0) |
| --lgk-aside-top | 24px | How far under the window's top the card holds while the choices scroll — clear a sticky header of the template's with it (0.6.0) |
| --lgk-aside-padding | 24px | The space inside the card, around its words (0.6.0) |
| --lgk-aside-border | a --lgk-border-width line in --lgk-line | The card's edge — any border, none to remove it (0.6.0) |
| --lgk-aside-background, --lgk-aside-radius | --lgk-background, --lgk-radius | The card's ground and corner (0.6.0). On a tinted ground, check the small capitals' --lgk-muted still reaches 4.5:1 |
| --lgk-shadow-aside | none | Under the card (0.6.0) — any shadow |
| --lgk-visit-photo-height, --lgk-visit-photo-position | 180px, center | The photo at the card's head, beside the steps and in the sheet: its height and which part of it shows (object-position) (0.6.0) |
| --lgk-bar-photo-size | 44px | The photo's square in the pinned bar (0.6.0) |
| --lgk-sheet-radius, --lgk-sheet-max-height | --lgk-radius-card, the window less 32px | The sheet's top corners, and how tall it grows before it scrolls (0.6.0) |
| --lgk-scrim | the text colour at 50% | The dim over the page behind the sheet (0.6.0) |
| --lgk-group-font, --lgk-group-size, --lgk-group-style, --lgk-group-weight | the heading font, 1rem, normal, 650 | A part of the day's heading — Morning, Afternoon, Evening (0.6.0, layout.times: 'parts-of-day'); italic for a style |
| --lgk-group-mark | 0px | A short rule in the button's colour before each part of the day's heading, this long — 0px draws none (0.6.0; a registered length) |
A business's colour is never trusted to be legible. The button's ground is the primary when it
reaches 3:1 against the background (WCAG 1.4.11), else the text colour; its words are white or the
text colour, whichever reaches 4.5:1 (WCAG 1.4.3), else whichever of white and near-black is
higher. buttonColours and contrastRatio are exported for a template's own buttons.
Restyle it (0.5.0). Every look the kit chooses — colour, line, corner, shadow, gradient, the
small capitals, fonts, motion — reads one of the variables above, so a template restyles the kit by
setting them on .lgk and nothing else, and every decoration can be turned off. A flat, square
template, for example — no shadows, the member card one flat tint without its inner frame, labels in
ordinary case:
.lgk {
--lgk-shadow-card: none;
--lgk-shadow-hover: none;
--lgk-shadow-tab: none;
--lgk-shadow-aside: none;
--lgk-card-background: var(--lgk-tint);
--lgk-card-frame: none;
--lgk-radius: 0px;
--lgk-radius-pill: 0px;
--lgk-radius-avatar: 0px;
--lgk-radius-photo: 0px;
--lgk-label-case: none;
--lgk-label-tracking: 0em;
}Write every length with its unit (0px, 0em): a bare 0 is a number inside the kit's calc(),
and the declaration that uses it fails. The line width and the radius are registered lengths
(@property), so a bare 0 works for those two in today's browsers — a unit still works everywhere.
Put these rules outside any @layer. The kit's stylesheet is in no cascade layer, and an unlayered
rule beats every layered one whatever its selector — a template that writes its CSS inside @layer
(Tailwind 4's @layer base, say) sees none of its kit rules take effect. The kit stays unlayered on
purpose: in a layer, a template's own reset (* { margin: 0 }, Tailwind's preflight) would beat the
kit's every rule.
The frames stay with the shadows off: they are borders. A control's edge (a field, a checkbox, an
outlined choice, a way in) and the chosen email tab's ring never go under 1px, whatever
--lgk-border-width says — they are how a control and a choice are seen (WCAG 1.4.11's 3:1), not
decoration. The kit's tests hold this (test/restyle.test.ts): no shadow, gradient or colour is
written into a rule, every line reads --lgk-border-width, the small capitals read the label
variables, and this recipe turns every shadow off with every length in it carrying a unit.
What is not a variable: sizes and spacing beyond the four in the table, the weights of the booking
steps' headings and of labels and buttons, the focus rings (2px, in the text or the button colour),
the dots before a notice's or a field's problem, the strokes of the marks and the check, how strongly
a notice or a hover is tinted (mixed from the variables, by fixed amounts), Google's mark, and the
widths where the appointment card goes beside the steps (840px) and named steps show every name
(520px) — container queries, which can't read a variable (0.6.0). A
template changes those with a rule of its own on the kit's classes. The class names (.lgk-*) are
the kit's API as much as the variables: a rename or a removal is a breaking change, made only in a
new minor version while the kit is 0.x, and said here. A rule outranks the kit's wherever the
stylesheets load when it puts :root in front of the kit's own selector — :root .lgk-member-card {
min-height: 0; }, :root .lgk-account .lgk-h1 { font-size: 3rem; } (outside any @layer, as
above). Two things win over any such rule, on purpose: the reduced-motion rules, and the few margins
the kit marks !important to space its own paragraphs and lists.
Lay out /book (0.6.0). BookPage takes layout, an object whose every key is optional;
a key left out keeps 0.5.0's drawing. AppointmentPage takes the same object and uses times (its
Change) and policy, so a template can define it once:
// app/book/page.tsx
import { BookPage, type BookLayout } from '@lamgig/booking-kit';
const layout: BookLayout = { summary: 'card', narrow: 'bar', stepper: 'named', times: 'parts-of-day', policy: 'folded' };
export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
const content = await loadPublishedFile();
return (
<BookPage
config={kitConfig()}
content={content}
searchParams={searchParams}
layout={layout}
photo={{ src: 'https://…/front-desk.jpg', alt: '' }}
/>
);
}| Key | Values (default first) | What it draws |
|---|---|---|
| summary | 'below', 'card' | Where the visit so far stands. 'below': under each step's choices, Continue in a footer on Services (0.5.0). 'card': the appointment card — the photo, the business's name and address (from the published file), "Your appointment", a row per choice with its Change, the total, and the step's one action (Continue; Book appointment or Pay and book) — beside the steps, held at the top while the choices scroll (--lgk-aside-top). With 'card', choosing a person or a time no longer moves on by itself: it is chosen, the card shows it, and the card's Continue moves on; looking at another day lets the chosen time go (a time belongs to its day), and a time the day no longer offers is let go once its times are read. While a deposit is being paid, the card shows what is due and offers no Change: Stripe's own button pays |
| narrow | 'bar', 'stack' | With summary: 'card', the card on a narrow container. 'bar': a bar pinned at the foot — the photo small, "Your appointment", what and when, the total, ⌃ — over the step's action; pressing it raises the whole card as a sheet, a modal <dialog>: × , Escape and a press on the dimmed page close it, focus stays inside while it is open and returns to the bar, the bar says whether it is open (aria-expanded), and under reduced motion it appears without sliding. 'stack': the card itself, under the step |
| stepper | 'bars', 'named' | 'bars': four hairlines over "Step 2 of 4" (0.5.0). 'named': the same hairlines, each over its step's number and name — 01 Services, 02 With, 03 When, 04 Details — in a list (nav "Booking steps", the current step aria-current="step"); a done step is a button back to it (not while a deposit is being paid: leaving would end the hold). On a stepper narrower than 520px only the current step's name shows; the others are still read out. "Step 2 of 4" stays, for screen readers (.lgk-progress-named) |
| times | 'grid', 'parts-of-day' | A day's times in one grid (0.5.0), or under Morning (before noon), Afternoon (noon until 5 PM) and Evening (from 5 PM), on the business's clock — each a heading (--lgk-group-*) with its count ("10 times") over its own grid; a part with no times is left out, and a day that runs past midnight keeps its late times in the evening |
| policy | 'open', 'folded' | The cancellation policy on Details (and on the booking's page): its words in full (0.5.0), or its heading a button that opens them (aria-expanded). Never folded while a deposit asks the customer to tick the box: what they agree to stays open. The words are the platform's either way |
The card's photo — photo={{ src, alt, srcSet?, sizes? }}, the business's own photo or one from
the template's library. src is https: or a path on the site itself (/photos/desk.jpg from its
public/, or a static import's /_next/static/media/…); anything else (http:, data:, //host/…) draws no image area, and neither
does no photo. A srcSet with any candidate refused is dropped whole, src still stands. alt
describes it, or is '' when it only decorates. The bar shows it as a small square; the sheet and
the card at full width (--lgk-visit-photo-height). Allow its host in img-src — a path on the site
is 'self'; the published file's content host is already in bookingCspSources.
Wide and narrow are the kit's own width, not the window's: the card stands beside the steps
from 840px of /book's width (a container query, so a template that sets the kit in a narrow
column gets the narrow layout). The number itself is not a variable — a container query can't read
one — but the width is the template's: --lgk-max-width-wide and the page around the kit. With the
card, /book is --lgk-max-width-wide wide (1120px), not --lgk-max-width.
The bar is sticky inside the steps' column, so it rides the foot of the screen while the
choices scroll and rests under them at the end — like the Services footer, it needs no ancestor of
the kit with overflow: hidden. A control reached by Tab is scrolled clear of it (a bottom scroll
margin on the step's controls), never left under it. The sheet is in the browser's top layer: no
z-index of the template's reaches over or under it; its dim (--lgk-scrim on ::backdrop) needs a
browser that passes variables to a backdrop (Chrome 122, Firefox 120, Safari 17.4 and later) —
before them the sheet still opens, undimmed.
With the card the kit takes the full width it is given (width: 100% up to
--lgk-max-width-wide), so it draws the same as the child of a block, a flex or a grid page.
Recolour the card — a dark card on a light page, say. The card beside the steps and the sheet
are drawn on --lgk-aside-background with the card's own --lgk-text; set the colour variables on
both, outside any @layer. The mixed ones (--lgk-muted, --lgk-hairline, --lgk-line) are mixed
once on .lgk, so give the card its own too, and a border and a button that read on the new ground:
:root .lgk-aside,
:root .lgk-sheet {
--lgk-aside-background: #30154e;
--lgk-aside-border: 0px solid transparent;
--lgk-text: #ffffff;
--lgk-muted: #d8cdea;
--lgk-hairline: #4a2f6b;
--lgk-button: #ffffff;
--lgk-button-text: #30154e;
}Check the pairs you choose reach 4.5:1 for words (3:1 for the button's ground): the kit's own contrast pick is made once, for the page.
Every heading's last word is <span class="lgk-last-word"> — the steps' headings, the card's
"Your appointment", a category's name, the booking's page and the account's pages alike. Set it
apart with one rule, scoped by the heading's class (.lgk-h1 the page titles, .lgk-h2 the
sections' and the card's, .lgk-h3/.lgk-h4 the small ones) — outside any @layer, as above:
:root .lgk-h1 .lgk-last-word,
:root .lgk-visit-heading .lgk-last-word {
font-style: italic;
color: var(--lgk-button);
}A one-word heading is that word, whole. "Step 2 of 4" with named steps is read out only; to show it as well:
:root .lgk .lgk-progress-named {
position: static;
width: auto;
height: auto;
overflow: visible;
clip: auto;
clip-path: none;
white-space: normal;
}Class names (0.6.0) — API, as every .lgk-* name is:
| Class | What it is |
|---|---|
| .lgk-wide | The kit's root on /book with summary: 'card' (--lgk-max-width-wide) |
| .lgk-book, .lgk-book-layout | The card layout's container (the query's, lgk-book) and its grid; data-narrow on the grid says bar or stack |
| .lgk-book-head, .lgk-book-main | Across the top: the stepper (and a notice when the booking page can't load); then the step, with the bar under it |
| .lgk-aside | The card beside the steps (an aside labelled "Your appointment") |
| .lgk-visit, .lgk-visit-no-photo | The card's content, beside the steps and in the sheet alike; -no-photo when there is none |
| .lgk-visit-photo, .lgk-visit-body | The photo at its head; everything under it |
| .lgk-visit-business, .lgk-visit-name, .lgk-visit-address, .lgk-visit-dot | The business's name and address in small capitals; the · between two parts (hidden from screen readers) |
| .lgk-visit-heading | "Your appointment" (also .lgk-h2) |
| .lgk-visit-rows, .lgk-visit-row, .lgk-visit-label, .lgk-visit-value, .lgk-visit-change | The choices: a dl, a row each — Services, With, When — its label, what is chosen, its Change |
| .lgk-visit-date, .lgk-visit-time | The When row's day and time, on two lines |
| .lgk-visit-empty | "No services chosen yet" |
| .lgk-visit-total, .lgk-visit-figures, .lgk-visit-duration, .lgk-visit-price | The total: its label ("Total", .lgk-visit-label), then how long and how much |
| .lgk-visit-action | The step's action in the card and in the bar (also .lgk-button .lgk-button-wide) |
| .lgk-bar, .lgk-bar-toggle | The pinned bar, and the button that raises the sheet |
| .lgk-bar-photo, .lgk-bar-text, .lgk-bar-label, .lgk-bar-line, .lgk-bar-what, .lgk-bar-dot, .lgk-bar-when, .lgk-bar-total, .lgk-bar-chevron | Inside it: the photo's square; "Your appointment"; what (a service's name, "2 services") and when (the start, or the person before a time is chosen); the total's price; the ⌃ |
| .lgk-sheet, .lgk-sheet-content, .lgk-sheet-close | The sheet (a <dialog>; its dim is .lgk-sheet::backdrop), its content, its × |
| .lgk-steps, .lgk-steps-list, .lgk-steps-item | The named stepper (nav, its container query's lgk-steps), its list, a step — data-state done, current or ahead; each holds the step's hairline (.lgk-stepper-step, as 0.5.0's) |
| .lgk-steps-label, .lgk-steps-number, .lgk-steps-name, .lgk-steps-check | A step's number and name — a button on a done step — and the ✓ after a done one |
| .lgk-progress-named | "Step 2 of 4" with named steps (also .lgk-progress), for screen readers |
| .lgk-times-group, .lgk-times-head, .lgk-times-mark, .lgk-times-heading, .lgk-times-count | A part of the day's times: its section, its heading row, the rule before it (--lgk-group-mark), its heading, its count; the times are .lgk-times as before |
| .lgk-policy-folded, .lgk-policy-heading, .lgk-policy-toggle, .lgk-policy-chevron, .lgk-policy-words | The folded policy (also .lgk-policy), its heading, the button in it, its chevron, the words it opens |
| .lgk-last-word | Every heading's last word |
Class names (0.7.0) — points on a deposit, on the details step:
| Class | What it is |
|---|---|
| .lgk-points | Use your points: a fieldset whose legend is a .lgk-label; inside it the kit's own .lgk-muted line (what the member has, a step's value), a .lgk-check box, and How many points — a .lgk-field with a .lgk-select list, or an .lgk-input past 60 steps |
Motion (0.2.0). Quiet and short by default; a template sets its own pace with the five motion variables above, and nothing else. What moves:
- The stepper — one hairline per step over the words "Step 2 of 4", filled in the button's
colour up to the current step (each segment's
data-stateisdone,currentorahead). It stays while the steps change, so the next hairline fills as a step opens and empties on Back. It is drawn for the eye only (aria-hidden); the words are what a screen reader reads. Square with--lgk-radius: 0. - A step opening — its content rises
--lgk-riseinto place, the stepper and the words above it still. The booking's page does the same between its states. Each step's heading still takes focus as it opens. - A choice — a chosen service, add-on, person, day or time fills, and its border and colour
change, over
--lgk-duration; a ticked box fills with the button's colour while its check draws in. The kit draws its checkboxes for this (the input is still the box: labelled, focusable, clicked); radios stay the browser's, and under forced colours the checkboxes do too. Buttons and links take the same transitions; with a pointer, an outlined choice's border darkens under it.
Movement only: nothing fades in from nothing — an animation a background tab never runs must
leave everything visible — and nothing follows the scroll. Under prefers-reduced-motion:
reduce every animation and transition is off, and the durations and the rise are set to
nothing over whatever a template set. A template's slower pace, for example:
.lgk {
--lgk-duration: 300ms;
--lgk-duration-slide: 650ms;
--lgk-duration-enter: 1.1s;
--lgk-rise: 14px;
}The account's look (0.4.0). Light and quiet, in the business's own colours and fonts — the same pages serve a café, a restaurant, a shop or a salon:
- The sign-in pages (sign in, a new password, deleted) are one centred column, at most 400px, under the business's name in small capitals. The three ways in still weigh the same; each carries its mark at its left — an envelope, Google's "G" in its own colours, Apple's logo in the text's colour. Email's two kinds sit in one track, the chosen one lifted out of it; the six digits are large and spaced. "One LamGig account works at every business…" sits under a hairline at the foot.
- The account page opens on the business's name, "Your account", and a monogram (the initials of the account's name, else its email's first letter) beside the name and address. Sections are divided by hairlines, never grey boxes. Each appointment has a date tile — month and day on the business's clock, tinted while it is upcoming — and its button drops under its words while the list is narrower than 520px (a container query).
- The member card is the one boxed thing: the business's colour faintly over the page, an inset
hairline frame like the edge of a printed card, the business's name, and the points large in the
heading font. With
--lgk-radius: 0it is square, like a gift card. - Every colour is mixed from the five brand values; nothing new is hard-coded but Google's mark (its four colours on a white disc, which Google's guidelines allow on any ground). The tints only ever carry words in the text colour — never the muted grey, which can fall under 4.5:1 on them — so a word on a tint keeps nearly the business's own text contrast; the chosen email tab is ringed in the text colour (WCAG 1.4.11's 3:1). The one muted figure on the card, On the way, is large text (26px), where 3:1 is the rule.
- The text pages — the rewards terms and notice, and the booking's privacy notice, which draws
inside
.lgk-accounttoo — take the same type.
Fonts are named, not loaded. The template loads them; the kit only names them.
Photos are plain <img>, lazy, with their size set — not next/image, which fails a whole
route with a 500 on a host the template's remotePatterns lacks. Allow the content host in
img-src.
Rules every page keeps: phone first; every control at least 44px tall; focus always visible;
everything by keyboard; each step's heading takes focus as it opens; prefers-reduced-motion
honoured; motion that moves, never fades in; text in the business's own colours.
What it does
- Times on the business's clock. Every day and time is shown in the business's published time zone; when the visitor's differs, the When step says so ("Times are in New York time").
- One booking per press. The
Idempotency-Keybelongs to the booking's body: a retry after an outage or a lost answer reuses it, so the platform answers the one booking again (Idempotent-Replayed); a changed detail, a conflict or a success makes a new one. Nothing retries a booking by itself. - Every refusal has words (
refusals.ts): a time just taken returns to When with the day kept and its times read again; a refused service or person names it and returns to its step; the bot check runs again with what was typed kept; a rate limit counts its wait down; booking off says so with the business's phone, and the booking's page keeps working. - Nothing in the browser's storage but the account's two cookies, which only the site's server
reads (
lg_session, andlg_pkcewhile a sign-in is in flight — since 0.7.0 holding, beside its verifier, the page to come back to): no localStorage, sessionStorage or IndexedDB — measured by the suite. "Your appointment is booked" travels in memory: a reload reads the booking afresh. Cloudflare's check keeps one record of its own (cf.turnstile.u) in localStorage inside its own frame — measured with a real key. From the press of Pay on a deposit, Stripe's fraud check sets its own cookies:__stripe_midand__stripe_sidon the site's host,mon m.stripe.com, and in Chromium__cf_bmon.hcaptcha.com, from the frame the check runs in — measured. The privacy notice says all of this; change what the kit stores, and the notice's words change with it. - Signed in, the details step is the account's. The address is shown as "Booking as {email}", not asked, and sent as the booking's; the names start from the account's one name split at its last space, and stay editable. The booking still goes from the browser to the public booking API, as a guest's — My appointments finds every booking at the business under the account's verified address, a guest booking included.
- My appointments lists upcoming bookings soonest first, then the last 20 past ones. Change or cancel asks the platform for a fresh link and opens the booking's own page by a full page load — the one place a booking is changed or cancelled. With nothing to list and online booking closed, the section is left out.
- The token is read from the fragment and sent only as
Authorization: Bearerto the booking API — never in an address, a log or storage. - Back after signing in (0.7.0).
/account/sign-in?return=<a path of this site>(signInHref) ends the sign-in there: the path is checked (one leading/, never//or\, no control character, at most 512 characters, never the sign-in's own routes; the fragment dropped), kept inside the sign-in's own short cookie (lg_pkce: no new cookie, the same ten minutes), checked again at/account/callback, and kept on a failed sign-in so trying again still comes back. Signed in already, the sign-in page sends straight there — so a template's page that links tosignInHref(itself)shows that link only to a visitor the kit would read as signed out (nolg_session), never on a test of its own that could disagree, or the two pages would bounce. - The counter and visits (0.8.0).
/config's program sayscounter(Points at the counter — absent reads on) andvisits(the business takes bookings online — absent reads no); a waitingchangesays its owncounter. The counter's code answers409 counter_offonce it is off. - Points on a deposit (0.7.0). Signed in, where the visit may ask a deposit,
/bookasks the site's server for a checkout pass (POST …/rewards/checkout-pass, with the session fromlg_session) and sends it with the quote and the booking. It proves who is booking, holds no points, is good for 30 minutes and one deposit, and lives in the page's memory only — never an address, storage or a log; a new one is asked after a hold ends or when the platform refuses it. It never joins the booking'sIdempotency-Key, so a retry with a fresh pass is the same booking.
Build and test (in the LamGig platform repository)
npm run build -w @lamgig/booking-kit # tsup, one file per source file
npm run test -w @lamgig/booking-kit # vitest (jsdom per file)
npm run typecheck -w @lamgig/booking-kitBuilt one file per source file, on purpose (tsup.config.ts): a bundled build drops each
client file's "use client", and a template's next build then refuses its hooks. Relative
imports are written with .js so Node's own resolution works too.
End to end: the bare test site apps/booking-kit-site installs the kit exactly as a template
would; apps/e2e/booking-kit.config.ts says how to run the guest and signed-in suites against its
production build on the local stack (npm run e2e:booking-kit) — the signed-in ones through the
platform's local test WorkOS, in Chromium and WebKit.
