Phase 2

Base app architecture:

    Route groups for customer, staff and owner.
* Reusable design system with around 20 UI components.
* Complete Prisma schema.
* Authentication with email/password and Google.
* Role and permission model.
* Protected routes.
* Clean separation between features, services, components and shared utilities.

src/components/feedback/coming-soon.tsx

@@ -0,0 +1,27 @@
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * Placeholder for routes that exist to prove the layout/navigation/auth
+ * architecture works, but whose real feature is out of Phase 2's scope
+ * (booking, appointments, loyalty, staff/owner tools — see the Phase 2
+ * brief). Every nav destination renders one of these rather than 404ing.
+ */
+export function ComingSoon({
+  icon: Icon,
+  title,
+  phase,
+}: {
+  icon: LucideIcon;
+  title: string;
+  phase: string;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center px-6 py-24 text-center">
+      <div className="mb-5 flex h-16 w-16 items-center justify-center rounded-full border border-line bg-white text-muted">
+        <Icon className="h-6 w-6" aria-hidden="true" />
+      </div>
+      <h1 className="mb-1 text-lg font-bold">{title}</h1>
+      <p className="max-w-xs text-sm text-muted">Coming in {phase}. This route exists today to prove the layout, navigation and auth gating around it.</p>
+    </div>
+  );
+}

src/components/feedback/empty-state.tsx

@@ -0,0 +1,27 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface EmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  description?: string;
+  action?: ReactNode;
+}
+
+/**
+ * Not represented anywhere in the templates (see
+ * docs/implementation-plan.md §6/§8) — every list screen needs one of
+ * these for the zero-items case.
+ */
+export function EmptyState({ icon: Icon, title, description, action }: EmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center px-6 py-16 text-center">
+      <div className="mb-5 flex h-16 w-16 items-center justify-center rounded-full border border-line bg-white text-muted">
+        <Icon className="h-6 w-6" aria-hidden="true" />
+      </div>
+      <h3 className="mb-1 text-base font-bold">{title}</h3>
+      {description && <p className="mb-6 text-sm text-muted">{description}</p>}
+      {action}
+    </div>
+  );
+}

src/components/feedback/error-state.tsx

@@ -0,0 +1,30 @@
+import { TriangleAlert } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+export interface ErrorStateProps {
+  title?: string;
+  description?: string;
+  onRetry?: () => void;
+}
+
+/** Not represented anywhere in the templates — the generic "something went wrong" state for a failed fetch/action. */
+export function ErrorState({
+  title = "Something went wrong",
+  description = "Please try again in a moment.",
+  onRetry,
+}: ErrorStateProps) {
+  return (
+    <div role="alert" className="flex flex-col items-center px-6 py-16 text-center">
+      <div className="mb-5 flex h-16 w-16 items-center justify-center rounded-full bg-red-50 text-red-500">
+        <TriangleAlert className="h-6 w-6" aria-hidden="true" />
+      </div>
+      <h3 className="mb-1 text-base font-bold">{title}</h3>
+      <p className="mb-6 text-sm text-muted">{description}</p>
+      {onRetry && (
+        <Button variant="secondary" size="md" onClick={onRetry}>
+          Try again
+        </Button>
+      )}
+    </div>
+  );
+}

src/components/feedback/loading-state.tsx

@@ -0,0 +1,17 @@
+import { Loader2 } from "lucide-react";
+
+/**
+ * Full-region loading indicator for cases a skeleton doesn't fit (route
+ * transitions, full-page Suspense fallbacks). Prefer `ListSkeleton`/
+ * `CardSkeleton` (skeleton.tsx) for known list/card shapes — a skeleton
+ * that mirrors the eventual layout reduces perceived load time more than
+ * a spinner does.
+ */
+export function LoadingState({ label = "Loading…" }: { label?: string }) {
+  return (
+    <div role="status" className="flex flex-col items-center justify-center gap-3 px-6 py-16 text-muted">
+      <Loader2 className="h-6 w-6 animate-spin" aria-hidden="true" />
+      <span className="text-sm">{label}</span>
+    </div>
+  );
+}

src/components/feedback/skeleton.tsx

@@ -0,0 +1,31 @@
+import { cn } from "@/lib/utils/cn";
+
+/** Base skeleton block — not represented anywhere in the templates. Compose into loading states for specific cards below. */
+export function Skeleton({ className }: { className?: string }) {
+  return <div className={cn("animate-pulse rounded-lg bg-line/60", className)} />;
+}
+
+export function CardSkeleton() {
+  return (
+    <div className="rounded-jumbo border border-line bg-white p-5">
+      <div className="mb-4 flex items-center gap-3">
+        <Skeleton className="h-10 w-10 rounded-full" />
+        <div className="flex-1 space-y-2">
+          <Skeleton className="h-3.5 w-2/3" />
+          <Skeleton className="h-3 w-1/3" />
+        </div>
+      </div>
+      <Skeleton className="h-3 w-full" />
+    </div>
+  );
+}
+
+export function ListSkeleton({ count = 3 }: { count?: number }) {
+  return (
+    <div className="space-y-3" aria-hidden="true">
+      {Array.from({ length: count }, (_, i) => (
+        <CardSkeleton key={i} />
+      ))}
+    </div>
+  );
+}

src/components/navigation/bottom-nav.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { CalendarCheck, CalendarDays, House, Scissors, Settings, User, Users } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+import { cn } from "@/lib/utils/cn";
+
+/**
+ * Icons are looked up by name, not passed as component references. A
+ * Server Component layout (see (customer)/layout.tsx, (staff)/layout.tsx)
+ * can only pass serializable props to a Client Component like this one —
+ * a Lucide icon is a forwardRef object, not a plain value, so passing it
+ * directly fails at the RSC boundary ("Only plain objects can be passed
+ * to Client Components from Server Components"). A string key sidesteps
+ * that entirely.
+ */
+const ICON_MAP = {
+  house: House,
+  "calendar-check": CalendarCheck,
+  user: User,
+  "calendar-days": CalendarDays,
+  scissors: Scissors,
+  users: Users,
+  settings: Settings,
+} satisfies Record<string, LucideIcon>;
+
+export type BottomNavIconName = keyof typeof ICON_MAP;
+
+export interface BottomNavItem {
+  href: string;
+  label: string;
+  icon: BottomNavIconName;
+}
+
+export interface BottomNavProps {
+  items: BottomNavItem[];
+  /**
+   * Customer nav is light; staff/owner nav is dark. This single prop
+   * replaces the four slightly-different bottom-nav markups found across
+   * the templates (see docs/implementation-plan.md §7/§8) with one
+   * role-aware component.
+   */
+  variant?: "customer" | "staff";
+}
+
+/**
+ * Client Component so the active tab is derived from the real current
+ * route (`usePathname`) instead of every parent layout having to compute
+ * and pass it down — one less thing to get out of sync as routes are
+ * added in later phases.
+ */
+export function BottomNav({ items, variant = "customer" }: BottomNavProps) {
+  const pathname = usePathname();
+  const isStaff = variant === "staff";
+
+  return (
+    <nav
+      aria-label="Primary"
+      className={cn(
+        "fixed inset-x-0 bottom-0 z-50 flex items-center justify-between border-t px-5 py-2",
+        "pb-[max(0.5rem,env(safe-area-inset-bottom))]",
+        isStaff ? "border-white/5 bg-[#0c0c0c] text-gray-400" : "border-line bg-white text-muted",
+      )}
+    >
+      {items.map(({ href, label, icon }) => {
+        const Icon = ICON_MAP[icon];
+        const active = pathname === href || pathname.startsWith(`${href}/`);
+        return (
+          <Link
+            key={href}
+            href={href}
+            aria-current={active ? "page" : undefined}
+            className={cn(
+              "flex flex-col items-center gap-1 rounded-lg px-3 py-1 transition-colors",
+              active ? (isStaff ? "text-white" : "text-ink") : "hover:text-ink",
+              isStaff && !active && "hover:text-white",
+            )}
+          >
+            <Icon className="h-5 w-5" aria-hidden="true" />
+            <span className="text-[10px] font-bold uppercase tracking-widest">{label}</span>
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}

src/components/navigation/top-nav.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { ArrowLeft } from "lucide-react";
+import { useRouter } from "next/navigation";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface TopNavProps {
+  title: string;
+  /** Show a back button that calls router.back(), or a custom href/handler. */
+  onBack?: (() => void) | true;
+  action?: ReactNode;
+  sticky?: boolean;
+  className?: string;
+}
+
+/**
+ * The [back button] + title + [action] header repeated, with small visual
+ * variations, across nearly every template screen — consolidated into one
+ * component (see docs/implementation-plan.md §7, "TopHeader").
+ */
+export function TopNav({ title, onBack, action, sticky = true, className }: TopNavProps) {
+  const router = useRouter();
+
+  return (
+    <header
+      className={cn(
+        "flex items-center justify-between border-b border-line bg-white px-6 py-5",
+        sticky && "sticky top-0 z-40",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-4">
+        {onBack && (
+          <button
+            type="button"
+            onClick={onBack === true ? () => router.back() : onBack}
+            aria-label="Go back"
+            className="flex h-10 w-10 items-center justify-center rounded-full border border-line"
+          >
+            <ArrowLeft className="h-4 w-4" aria-hidden="true" />
+          </button>
+        )}
+        <h1 className="text-xl font-bold tracking-tight">{title}</h1>
+      </div>
+      {action}
+    </header>
+  );
+}

src/components/providers.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { SessionProvider } from "next-auth/react";
+import type { ReactNode } from "react";
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <SessionProvider>{children}</SessionProvider>;
+}

src/components/ui/appointment-card.tsx

@@ -0,0 +1,60 @@
+import Image from "next/image";
+import type { ReactNode } from "react";
+import { Card } from "@/components/ui/card";
+import { StatusPill } from "@/components/ui/status-pill";
+import type { AppointmentStatus, StaffSummary } from "@/types/domain";
+
+export interface AppointmentCardProps {
+  status: AppointmentStatus;
+  serviceName: string;
+  staff: StaffSummary;
+  /** Pre-formatted for display, e.g. "Sat, Oct 12". */
+  formattedDate: string;
+  /** Pre-formatted for display, e.g. "2:00 PM". */
+  formattedTime: string;
+  /** Reschedule/Cancel/Book again buttons — left to the caller so this
+   * component stays agnostic of which actions apply to which status. */
+  actions?: ReactNode;
+  href?: string;
+}
+
+export function AppointmentCard({
+  status,
+  serviceName,
+  staff,
+  formattedDate,
+  formattedTime,
+  actions,
+}: AppointmentCardProps) {
+  return (
+    <Card className="p-5">
+      <div className="mb-4 flex items-start justify-between">
+        <StatusPill status={status} />
+        <div className="text-right">
+          <p className="text-sm font-bold">{formattedDate}</p>
+          <p className="text-xs text-muted">{formattedTime}</p>
+        </div>
+      </div>
+      <div className="mb-4 flex items-center gap-3">
+        {staff.avatarUrl ? (
+          <Image
+            src={staff.avatarUrl}
+            alt=""
+            width={40}
+            height={40}
+            className="h-10 w-10 rounded-full object-cover"
+          />
+        ) : (
+          <div className="flex h-10 w-10 items-center justify-center rounded-full bg-stone text-xs font-bold text-muted">
+            {staff.name.charAt(0)}
+          </div>
+        )}
+        <div>
+          <h3 className="text-sm font-bold">{serviceName}</h3>
+          <p className="text-xs text-muted">with {staff.name}</p>
+        </div>
+      </div>
+      {actions && <div className="flex gap-2 border-t border-line pt-4">{actions}</div>}
+    </Card>
+  );
+}

src/components/ui/barber-card.tsx

@@ -0,0 +1,60 @@
+import Image from "next/image";
+import { Check } from "lucide-react";
+import { cn } from "@/lib/utils/cn";
+import type { StaffSummary } from "@/types/domain";
+
+export interface BarberCardProps {
+  staff: StaffSummary;
+  isPreferred?: boolean;
+  selected?: boolean;
+  onSelect?: () => void;
+}
+
+/** Avatar-and-name barber picker, used in the booking flow and "Your Barbers" home section. */
+export function BarberCard({ staff, isPreferred, selected, onSelect }: BarberCardProps) {
+  const Comp = onSelect ? "button" : "div";
+
+  return (
+    <Comp
+      type={onSelect ? "button" : undefined}
+      onClick={onSelect}
+      aria-pressed={onSelect ? selected : undefined}
+      className="flex w-20 shrink-0 flex-col items-center gap-2 text-center"
+    >
+      <div className="relative">
+        {staff.avatarUrl ? (
+          <Image
+            src={staff.avatarUrl}
+            alt=""
+            width={64}
+            height={64}
+            className={cn(
+              "h-16 w-16 rounded-full border object-cover",
+              selected ? "border-2 border-accent" : "border-line",
+            )}
+          />
+        ) : (
+          <div
+            className={cn(
+              "flex h-16 w-16 items-center justify-center rounded-full border bg-stone text-lg font-bold text-muted",
+              selected ? "border-2 border-accent" : "border-line",
+            )}
+          >
+            {staff.name.charAt(0)}
+          </div>
+        )}
+        {selected && (
+          <span className="absolute -right-0.5 -top-0.5 flex h-5 w-5 items-center justify-center rounded-full border-2 border-white bg-accent">
+            <Check className="h-2.5 w-2.5 text-white" aria-hidden="true" />
+          </span>
+        )}
+        {isPreferred && !selected && (
+          <span className="absolute -bottom-1 right-1 rounded-full bg-accent px-1.5 py-0.5 text-[7px] font-bold uppercase text-white">
+            Fave
+          </span>
+        )}
+      </div>
+      <span className="text-xs font-medium">{staff.name}</span>
+    </Comp>
+  );
+}

src/components/ui/bottom-sheet.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface BottomSheetProps {
+  open: boolean;
+  onClose: () => void;
+  title?: string;
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Same native-<dialog> foundation as Modal (see modal.tsx) — the mobile
+ * bottom-sheet pattern the customer templates imply (e.g. an appointment
+ * action sheet) but never actually build. Anchored to the viewport bottom
+ * with a drag handle instead of centered, everything else — focus
+ * trapping, Escape, backdrop click — comes from <dialog> the same way.
+ */
+export function BottomSheet({ open, onClose, title, children, className }: BottomSheetProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    if (open && !node.open) node.showModal();
+    if (!open && node.open) node.close();
+  }, [open]);
+
+  return (
+    <dialog
+      ref={ref}
+      onClose={onClose}
+      onCancel={onClose}
+      onClick={(event) => {
+        if (event.target === ref.current) onClose();
+      }}
+      aria-labelledby={title ? "bottom-sheet-title" : undefined}
+      className={cn(
+        "m-0 mt-auto w-full max-w-none rounded-t-jumbo rounded-b-none border-0 border-t border-line bg-white p-0 shadow-xl backdrop:bg-ink/40 backdrop:backdrop-blur-sm",
+        "max-h-[85vh]",
+        className,
+      )}
+    >
+      <div className="mx-auto mt-3 h-1.5 w-10 shrink-0 rounded-full bg-line" aria-hidden="true" />
+      {title && (
+        <div className="px-6 pt-4 pb-2">
+          <h2 id="bottom-sheet-title" className="text-lg font-bold tracking-tight">
+            {title}
+          </h2>
+        </div>
+      )}
+      <div className="overflow-y-auto px-6 pb-[max(1.5rem,env(safe-area-inset-bottom))] pt-2">
+        {children}
+      </div>
+    </dialog>
+  );
+}

src/components/ui/button.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Loader2 } from "lucide-react";
+import { forwardRef } from "react";
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap font-bold uppercase tracking-widest transition-all disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        // Primary CTA — matches the black-pill button used for the main
+        // action on nearly every template (Sign In, Confirm Booking, Done…).
+        primary: "bg-ink text-white shadow-lg shadow-ink/10 hover:bg-black",
+        // Save-in-place action inside settings/config screens — matches
+        // the accent "Save" pill used on the Loyalty Configuration screen.
+        accent: "bg-accent text-white hover:brightness-95",
+        secondary: "bg-white text-ink border border-line hover:bg-stone",
+        ghost: "text-ink hover:bg-stone",
+        destructive: "border border-red-200 text-red-500 hover:bg-red-50",
+      },
+      size: {
+        sm: "h-9 rounded-full px-4 text-[10px]",
+        md: "h-12 rounded-full px-6 text-xs",
+        lg: "h-[52px] rounded-full px-8 text-xs",
+        icon: "h-10 w-10 rounded-full",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "lg",
+    },
+  },
+);
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  /** Render the styling onto the single child element instead of a <button> (e.g. a Next <Link>). */
+  asChild?: boolean;
+  isLoading?: boolean;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, isLoading = false, children, disabled, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        ref={ref}
+        className={cn(buttonVariants({ variant, size }), className)}
+        disabled={disabled || isLoading}
+        aria-busy={isLoading || undefined}
+        {...props}
+      >
+        {isLoading ? (
+          <>
+            <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
+            <span className="sr-only">Loading</span>
+            {children}
+          </>
+        ) : (
+          children
+        )}
+      </Comp>
+    );
+  },
+);
+Button.displayName = "Button";

src/components/ui/card.tsx

@@ -0,0 +1,28 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "@/lib/utils/cn";
+
+/**
+ * The single most-repeated visual pattern across the templates: a white
+ * surface, hairline border, jumbo radius. See docs/implementation-plan.md
+ * §7 ("Cards" — strongest, most reusable element across the set).
+ */
+export function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("rounded-jumbo border border-line bg-white shadow-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("p-6 pb-0", className)} {...props} />;
+}
+
+export function CardContent({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("p-6", className)} {...props} />;
+}
+
+export function CardFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex items-center gap-3 p-6 pt-0", className)} {...props} />;
+}

src/components/ui/checkbox.tsx

@@ -0,0 +1,36 @@
+import { forwardRef, useId } from "react";
+import type { InputHTMLAttributes, ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+  label: ReactNode;
+  description?: ReactNode;
+}
+
+/**
+ * Native checkbox styled via `accent-*` rather than a hand-drawn box — full
+ * built-in keyboard/screen-reader support, no extra ARIA required.
+ */
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
+  ({ className, label, description, id, ...props }, ref) => {
+    const generatedId = useId();
+    const checkboxId = id ?? generatedId;
+
+    return (
+      <label htmlFor={checkboxId} className="flex cursor-pointer items-start gap-3">
+        <input
+          ref={ref}
+          type="checkbox"
+          id={checkboxId}
+          className={cn("mt-1 h-4 w-4 shrink-0 rounded border-line accent-accent", className)}
+          {...props}
+        />
+        <span>
+          <span className="block text-sm font-bold">{label}</span>
+          {description && <span className="block text-xs text-muted">{description}</span>}
+        </span>
+      </label>
+    );
+  },
+);
+Checkbox.displayName = "Checkbox";

src/components/ui/input.tsx

@@ -0,0 +1,66 @@
+import { forwardRef, useId } from "react";
+import type { InputHTMLAttributes, ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  label?: string;
+  error?: string;
+  hint?: string;
+  /** Icon rendered inside the field, left-aligned — matches the icon-in-input pattern used across the auth templates. */
+  icon?: ReactNode;
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ className, label, error, hint, icon, id, required, ...props }, ref) => {
+    const generatedId = useId();
+    const inputId = id ?? generatedId;
+    const hintId = hint ? `${inputId}-hint` : undefined;
+    const errorId = error ? `${inputId}-error` : undefined;
+
+    return (
+      <div className="w-full">
+        {label && (
+          <label
+            htmlFor={inputId}
+            className="mb-2 ml-1 block text-[10px] font-bold uppercase tracking-widest text-muted"
+          >
+            {label}
+            {required && <span aria-hidden="true"> *</span>}
+          </label>
+        )}
+        <div className="relative">
+          {icon && (
+            <span className="pointer-events-none absolute left-5 top-1/2 -translate-y-1/2 text-muted">
+              {icon}
+            </span>
+          )}
+          <input
+            ref={ref}
+            id={inputId}
+            required={required}
+            aria-invalid={!!error || undefined}
+            aria-describedby={cn(hintId, errorId) || undefined}
+            className={cn(
+              "w-full rounded-xl border border-line bg-white px-5 py-4 text-sm outline-none transition-all placeholder:text-muted focus:ring-2 focus:ring-ink",
+              icon && "pl-12",
+              error && "border-red-300 focus:ring-red-400",
+              className,
+            )}
+            {...props}
+          />
+        </div>
+        {hint && !error && (
+          <p id={hintId} className="mt-1.5 ml-1 text-xs text-muted">
+            {hint}
+          </p>
+        )}
+        {error && (
+          <p id={errorId} role="alert" className="mt-1.5 ml-1 text-xs font-medium text-red-500">
+            {error}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+Input.displayName = "Input";

src/components/ui/loyalty-card.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { Scissors } from "lucide-react";
+import { useState } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface LoyaltyCardProps {
+  businessName: string;
+  memberNumber: string;
+  stampsRequired: number;
+  stampsEarned: number;
+  rewardLabel: string;
+  termsLine?: string;
+}
+
+/**
+ * Ports the 3D flip loyalty card from templates/11 — the best-executed
+ * visual in the whole template set (see docs/implementation-plan.md §2) —
+ * but fixes the gap flagged in §8: the original had no actual flip
+ * trigger wired up. Here the card is a real <button> with
+ * `aria-pressed`, and the flip transition is skipped for users who
+ * prefer reduced motion.
+ */
+export function LoyaltyCard({
+  businessName,
+  memberNumber,
+  stampsRequired,
+  stampsEarned,
+  rewardLabel,
+  termsLine,
+}: LoyaltyCardProps) {
+  const [flipped, setFlipped] = useState(false);
+
+  return (
+    <button
+      type="button"
+      onClick={() => setFlipped((v) => !v)}
+      aria-pressed={flipped}
+      aria-label={flipped ? "Show stamp side" : "Show card back"}
+      className="w-full [perspective:1000px]"
+      style={{ aspectRatio: "1.65 / 1" }}
+    >
+      <div
+        className={cn(
+          "relative h-full w-full rounded-2xl shadow-[0_30px_60px_rgba(0,0,0,0.45)] transition-transform duration-700 [transform-style:preserve-3d] motion-reduce:transition-none",
+          "ring-[3px] ring-accent-loyalty",
+        )}
+        style={{ transform: flipped ? "rotateY(180deg)" : "rotateY(0deg)" }}
+      >
+        {/* Front — stamps */}
+        <div className="absolute inset-0 flex flex-col justify-between overflow-hidden rounded-2xl bg-[#141414] p-4 [backface-visibility:hidden]">
+          <div className="flex items-center justify-between">
+            <h2 className="text-lg font-black italic tracking-tight text-white">Loyalty Card</h2>
+            <span className="rounded border border-accent-loyalty/30 px-2 py-0.5 text-[8px] font-bold uppercase tracking-widest text-accent-loyalty">
+              Member #{memberNumber}
+            </span>
+          </div>
+          <div className="grid grid-cols-5 gap-2">
+            {Array.from({ length: stampsRequired }, (_, i) => {
+              const earned = i < stampsEarned;
+              const isRewardSlot = i === stampsRequired - 1;
+              return (
+                <div
+                  key={i}
+                  className={cn(
+                    "flex aspect-square items-center justify-center rounded-full",
+                    isRewardSlot
+                      ? "scale-[1.08] bg-accent-loyalty shadow-lg"
+                      : earned
+                        ? "bg-white shadow-inner"
+                        : "border-2 border-dashed border-white/20 bg-[#2a2a2a]",
+                  )}
+                >
+                  {isRewardSlot ? (
+                    <span className="text-center text-[7px] font-black leading-tight text-ink">
+                      {rewardLabel}
+                    </span>
+                  ) : earned ? (
+                    <Scissors className="h-3.5 w-3.5 text-ink" aria-hidden="true" />
+                  ) : null}
+                </div>
+              );
+            })}
+          </div>
+          {termsLine && (
+            <p className="text-center text-[7px] font-bold uppercase tracking-widest text-white/40">
+              {termsLine}
+            </p>
+          )}
+        </div>
+
+        {/* Back — brand */}
+        <div className="absolute inset-0 flex items-center justify-center rounded-2xl bg-ink [backface-visibility:hidden] [transform:rotateY(180deg)]">
+          <div className="text-center">
+            <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-2xl bg-white text-3xl text-ink">
+              <Scissors className="h-7 w-7" aria-hidden="true" />
+            </div>
+            <h3 className="text-2xl font-black uppercase tracking-tighter text-white">{businessName}</h3>
+          </div>
+        </div>
+      </div>
+    </button>
+  );
+}

src/components/ui/modal.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { X } from "lucide-react";
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Built on the native <dialog> element rather than a hand-rolled focus
+ * trap: `showModal()` gives us focus containment, Escape-to-close, and
+ * top-layer stacking from the browser for free, and `<dialog>` is
+ * implicitly `role="dialog"` + `aria-modal="true"`. This is the more
+ * maintainable choice than reimplementing that behaviour in JS.
+ */
+export function Modal({ open, onClose, title, children, className }: ModalProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    if (open && !node.open) node.showModal();
+    if (!open && node.open) node.close();
+  }, [open]);
+
+  return (
+    <dialog
+      ref={ref}
+      onClose={onClose}
+      onCancel={onClose}
+      onClick={(event) => {
+        if (event.target === ref.current) onClose();
+      }}
+      aria-labelledby="modal-title"
+      className={cn(
+        "m-auto w-[calc(100%-2rem)] max-w-md rounded-jumbo border border-line bg-white p-0 shadow-xl backdrop:bg-ink/40 backdrop:backdrop-blur-sm",
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between border-b border-line px-6 py-5">
+        <h2 id="modal-title" className="text-lg font-bold tracking-tight">
+          {title}
+        </h2>
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close"
+          className="flex h-9 w-9 items-center justify-center rounded-full text-muted hover:bg-stone"
+        >
+          <X className="h-4 w-4" aria-hidden="true" />
+        </button>
+      </div>
+      <div className="p-6">{children}</div>
+    </dialog>
+  );
+}

src/components/ui/month-calendar.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { cn } from "@/lib/utils/cn";
+
+export interface MonthCalendarProps {
+  /** Any date within the month being displayed. */
+  month: Date;
+  selectedDate?: Date;
+  onMonthChange?: (nextMonth: Date) => void;
+  onSelectDate?: (date: Date) => void;
+  /** Return true to disable a given day (e.g. outside booking rules). */
+  isDateDisabled?: (date: Date) => boolean;
+  className?: string;
+}
+
+const WEEKDAY_LABELS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+function isSameDay(a: Date, b: Date) {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+
+function buildGrid(month: Date): Date[] {
+  const year = month.getFullYear();
+  const monthIndex = month.getMonth();
+  const firstOfMonth = new Date(year, monthIndex, 1);
+  const startOffset = firstOfMonth.getDay(); // 0 = Sunday
+  const gridStart = new Date(year, monthIndex, 1 - startOffset);
+
+  return Array.from({ length: 42 }, (_, i) => {
+    const date = new Date(gridStart);
+    date.setDate(gridStart.getDate() + i);
+    return date;
+  });
+}
+
+/**
+ * The month date-picker used in the booking and reschedule flows. This is
+ * the one calendar surface that's well-defined by the templates; the
+ * staff/owner day-agenda calendar is intentionally NOT built here — it
+ * depends on the booking engine's availability model (Phase 3), and the
+ * templates themselves disagree on its layout (see
+ * docs/implementation-plan.md §14, "Calendar UI complexity").
+ */
+export function MonthCalendar({
+  month,
+  selectedDate,
+  onMonthChange,
+  onSelectDate,
+  isDateDisabled,
+  className,
+}: MonthCalendarProps) {
+  const today = new Date();
+  const days = buildGrid(month);
+  const monthLabel = month.toLocaleDateString("en-GB", { month: "long", year: "numeric" });
+
+  return (
+    <div className={cn("rounded-tile border border-line bg-white p-4", className)}>
+      <div className="mb-6 flex items-center justify-between">
+        <h3 className="text-base font-semibold">{monthLabel}</h3>
+        <div className="flex gap-2">
+          <button
+            type="button"
+            aria-label="Previous month"
+            onClick={() => onMonthChange?.(new Date(month.getFullYear(), month.getMonth() - 1, 1))}
+            className="flex h-8 w-8 items-center justify-center rounded-full border border-line text-xs"
+          >
+            <ChevronLeft className="h-3.5 w-3.5" aria-hidden="true" />
+          </button>
+          <button
+            type="button"
+            aria-label="Next month"
+            onClick={() => onMonthChange?.(new Date(month.getFullYear(), month.getMonth() + 1, 1))}
+            className="flex h-8 w-8 items-center justify-center rounded-full border border-line text-xs"
+          >
+            <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
+          </button>
+        </div>
+      </div>
+
+      <div className="mb-3 grid grid-cols-7 text-center" role="row">
+        {WEEKDAY_LABELS.map((day) => (
+          <span key={day} className="text-[10px] font-bold uppercase text-muted">
+            {day}
+          </span>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-7 gap-y-2 text-center">
+        {days.map((date) => {
+          const inMonth = date.getMonth() === month.getMonth();
+          const isToday = isSameDay(date, today);
+          const isSelected = selectedDate ? isSameDay(date, selectedDate) : false;
+          const disabled = !inMonth || (isDateDisabled?.(date) ?? false);
+
+          return (
+            <button
+              key={date.toISOString()}
+              type="button"
+              disabled={disabled}
+              aria-current={isToday ? "date" : undefined}
+              aria-pressed={isSelected}
+              onClick={() => onSelectDate?.(date)}
+              className={cn(
+                "mx-auto flex h-9 w-9 items-center justify-center rounded-lg text-sm transition-colors",
+                !inMonth && "text-line",
+                inMonth && !isSelected && "text-ink hover:bg-stone",
+                isToday && !isSelected && "font-medium border border-line",
+                isSelected && "border-2 border-accent bg-accent/10 font-bold text-ink",
+                disabled && inMonth && "cursor-not-allowed text-muted opacity-40 hover:bg-transparent",
+              )}
+            >
+              {date.getDate()}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

src/components/ui/profile-card.tsx

@@ -0,0 +1,46 @@
+import Image from "next/image";
+import { Pencil } from "lucide-react";
+import type { ReactNode } from "react";
+import { Card } from "@/components/ui/card";
+
+export interface ProfileCardProps {
+  name: string;
+  meta?: ReactNode;
+  avatarUrl?: string;
+  onEdit?: () => void;
+}
+
+/** Avatar + name + meta + edit-pencil pattern reused across nearly every settings/profile screen. */
+export function ProfileCard({ name, meta, avatarUrl, onEdit }: ProfileCardProps) {
+  return (
+    <Card className="flex items-center gap-4 p-5">
+      {avatarUrl ? (
+        <Image
+          src={avatarUrl}
+          alt=""
+          width={64}
+          height={64}
+          className="h-16 w-16 rounded-full border border-line object-cover"
+        />
+      ) : (
+        <div className="flex h-16 w-16 items-center justify-center rounded-full border border-line bg-stone text-xl font-bold text-muted">
+          {name.charAt(0)}
+        </div>
+      )}
+      <div className="flex-1">
+        <h2 className="text-lg font-bold">{name}</h2>
+        {meta && <div className="mt-0.5 text-xs text-muted">{meta}</div>}
+      </div>
+      {onEdit && (
+        <button
+          type="button"
+          onClick={onEdit}
+          aria-label={`Edit ${name}`}
+          className="flex h-10 w-10 items-center justify-center rounded-full bg-stone text-ink"
+        >
+          <Pencil className="h-3.5 w-3.5" aria-hidden="true" />
+        </button>
+      )}
+    </Card>
+  );
+}

src/components/ui/select.tsx

@@ -0,0 +1,63 @@
+import { ChevronDown } from "lucide-react";
+import { forwardRef, useId } from "react";
+import type { SelectHTMLAttributes } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+  label?: string;
+  error?: string;
+}
+
+/**
+ * Native <select> rather than a custom listbox — on iOS/Android this gets
+ * the OS's own picker UI for free, which a hand-built listbox can't match,
+ * and it's accessible by default. See docs/implementation-plan.md §7.
+ */
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(
+  ({ className, label, error, id, required, children, ...props }, ref) => {
+    const generatedId = useId();
+    const selectId = id ?? generatedId;
+    const errorId = error ? `${selectId}-error` : undefined;
+
+    return (
+      <div className="w-full">
+        {label && (
+          <label
+            htmlFor={selectId}
+            className="mb-2 ml-1 block text-[10px] font-bold uppercase tracking-widest text-muted"
+          >
+            {label}
+            {required && <span aria-hidden="true"> *</span>}
+          </label>
+        )}
+        <div className="relative">
+          <select
+            ref={ref}
+            id={selectId}
+            required={required}
+            aria-invalid={!!error || undefined}
+            aria-describedby={errorId}
+            className={cn(
+              "w-full appearance-none rounded-xl border border-line bg-white px-4 py-3 pr-10 text-sm font-medium outline-none transition-all focus:ring-2 focus:ring-ink",
+              error && "border-red-300 focus:ring-red-400",
+              className,
+            )}
+            {...props}
+          >
+            {children}
+          </select>
+          <ChevronDown
+            aria-hidden="true"
+            className="pointer-events-none absolute right-4 top-1/2 h-4 w-4 -translate-y-1/2 text-muted"
+          />
+        </div>
+        {error && (
+          <p id={errorId} role="alert" className="mt-1.5 ml-1 text-xs font-medium text-red-500">
+            {error}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+Select.displayName = "Select";

src/components/ui/service-card.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { ServiceSummary } from "@/types/domain";
+
+export interface ServiceCardProps {
+  service: ServiceSummary;
+  action?: ReactNode;
+}
+
+/** Row layout matching the service lists on the business page and Services & Categories screens. */
+export function ServiceCard({ service, action }: ServiceCardProps) {
+  return (
+    <div className="flex items-center justify-between gap-4 py-4">
+      <div className="flex-1">
+        <h4 className="text-sm font-medium">{service.name}</h4>
+        <p className="mt-1 text-xs text-muted">{service.durationMinutes}m</p>
+      </div>
+      <div className="flex items-center gap-4">
+        <span className="font-bold">{service.formattedPrice}</span>
+        {action}
+      </div>
+    </div>
+  );
+}

src/components/ui/status-pill.tsx

@@ -0,0 +1,27 @@
+import type { AppointmentStatus } from "@/types/domain";
+import { cn } from "@/lib/utils/cn";
+
+const STATUS_CONFIG: Record<AppointmentStatus, { label: string; className: string }> = {
+  pending_approval: { label: "Pending Approval", className: "bg-amber-100 text-amber-700" },
+  confirmed: { label: "Confirmed", className: "bg-accent/10 text-accent" },
+  arrived: { label: "Arrived", className: "bg-accent/10 text-accent" },
+  in_progress: { label: "In Progress", className: "bg-blue-100 text-blue-700" },
+  completed: { label: "Completed", className: "bg-stone text-muted" },
+  cancelled: { label: "Cancelled", className: "bg-red-50 text-red-500" },
+  no_show: { label: "No-show", className: "bg-red-50 text-red-500" },
+};
+
+export function StatusPill({ status, className }: { status: AppointmentStatus; className?: string }) {
+  const config = STATUS_CONFIG[status];
+  return (
+    <span
+      className={cn(
+        "inline-block rounded-full px-3 py-1 text-[10px] font-bold uppercase tracking-widest",
+        config.className,
+        className,
+      )}
+    >
+      {config.label}
+    </span>
+  );
+}

src/components/ui/switch.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+import { forwardRef, useId } from "react";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface SwitchProps extends SwitchPrimitive.SwitchProps {
+  label?: ReactNode;
+  description?: ReactNode;
+}
+
+/**
+ * Radix Switch rather than a hand-rolled checkbox-as-toggle: gets correct
+ * `role="switch"` + `aria-checked` semantics and keyboard handling without
+ * re-deriving them. The templates never implemented a real toggle
+ * (settings screens just re-styled plain buttons) — this is the first
+ * functional one, used everywhere a boolean setting appears.
+ */
+export const Switch = forwardRef<HTMLButtonElement, SwitchProps>(
+  ({ className, label, description, id, ...props }, ref) => {
+    const generatedId = useId();
+    const switchId = id ?? generatedId;
+
+    const control = (
+      <SwitchPrimitive.Root
+        ref={ref}
+        id={switchId}
+        className={cn(
+          "relative h-6 w-11 shrink-0 cursor-pointer rounded-full bg-line outline-none transition-colors",
+          "data-[state=checked]:bg-accent",
+          "focus-visible:ring-2 focus-visible:ring-ink focus-visible:ring-offset-2 focus-visible:ring-offset-stone",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+        {...props}
+      >
+        <SwitchPrimitive.Thumb className="block h-5 w-5 translate-x-0.5 rounded-full bg-white shadow transition-transform data-[state=checked]:translate-x-[22px]" />
+      </SwitchPrimitive.Root>
+    );
+
+    if (!label) return control;
+
+    return (
+      <label htmlFor={switchId} className="flex cursor-pointer items-center justify-between gap-4">
+        <span>
+          <span className="block text-sm font-bold">{label}</span>
+          {description && <span className="mt-0.5 block text-xs text-muted">{description}</span>}
+        </span>
+        {control}
+      </label>
+    );
+  },
+);
+Switch.displayName = "Switch";

src/components/ui/tabs.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import * as TabsPrimitive from "@radix-ui/react-tabs";
+import { cn } from "@/lib/utils/cn";
+
+/**
+ * Radix Tabs for correct roving-tabindex/arrow-key navigation and
+ * automatic aria-selected/aria-controls wiring — replaces the hand-rolled
+ * `switchTab()` DOM-manipulation script duplicated across several
+ * templates (business page, appointments) with one accessible component.
+ */
+export const Tabs = TabsPrimitive.Root;
+
+export function TabsList({ className, ...props }: TabsPrimitive.TabsListProps) {
+  return (
+    <TabsPrimitive.List
+      className={cn("flex gap-2 rounded-full bg-stone p-1", className)}
+      {...props}
+    />
+  );
+}
+
+export function TabsTrigger({ className, ...props }: TabsPrimitive.TabsTriggerProps) {
+  return (
+    <TabsPrimitive.Trigger
+      className={cn(
+        "flex-1 rounded-full px-4 py-2.5 text-xs font-bold uppercase tracking-widest text-muted transition-all",
+        "data-[state=active]:bg-ink data-[state=active]:text-white",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ink focus-visible:ring-offset-2 focus-visible:ring-offset-stone",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function TabsContent({ className, ...props }: TabsPrimitive.TabsContentProps) {
+  return (
+    <TabsPrimitive.Content
+      className={cn(
+        "mt-6 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ink",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

src/components/ui/textarea.tsx

@@ -0,0 +1,57 @@
+import { forwardRef, useId } from "react";
+import type { TextareaHTMLAttributes } from "react";
+import { cn } from "@/lib/utils/cn";
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: string;
+  error?: string;
+  hint?: string;
+}
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, label, error, hint, id, required, rows = 4, ...props }, ref) => {
+    const generatedId = useId();
+    const textareaId = id ?? generatedId;
+    const hintId = hint ? `${textareaId}-hint` : undefined;
+    const errorId = error ? `${textareaId}-error` : undefined;
+
+    return (
+      <div className="w-full">
+        {label && (
+          <label
+            htmlFor={textareaId}
+            className="mb-2 ml-1 block text-[10px] font-bold uppercase tracking-widest text-muted"
+          >
+            {label}
+            {required && <span aria-hidden="true"> *</span>}
+          </label>
+        )}
+        <textarea
+          ref={ref}
+          id={textareaId}
+          rows={rows}
+          required={required}
+          aria-invalid={!!error || undefined}
+          aria-describedby={cn(hintId, errorId) || undefined}
+          className={cn(
+            "w-full resize-none rounded-xl border border-line bg-white p-4 text-sm outline-none transition-all placeholder:text-muted focus:ring-2 focus:ring-ink",
+            error && "border-red-300 focus:ring-red-400",
+            className,
+          )}
+          {...props}
+        />
+        {hint && !error && (
+          <p id={hintId} className="mt-1.5 ml-1 text-xs text-muted">
+            {hint}
+          </p>
+        )}
+        {error && (
+          <p id={errorId} role="alert" className="mt-1.5 ml-1 text-xs font-medium text-red-500">
+            {error}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+Textarea.displayName = "Textarea";