Freeframe

Documentation

Flow

v1.0.0Updated Nov 15, 2026A calm, airy yoga studio website with a live schedule and mat-by-mat class booking.

Overview#

Flow is a multi-page website template for an independent yoga studio, built for Salt & Sage Yoga, a fictional studio above the harbor in Santa Cruz, California. This is the Next.js version: Next.js 16 (App Router), React 19, TypeScript and Tailwind CSS v4, exported as a fully static site, so it runs on any host. The home page lists today's classes from the weekly schedule, the schedule can be filtered and shows what's on now and next, and visitors can reserve a specific mat and see it under My bookings. This guide covers version 1.0.0 (see template.json). Live demo: freeframe.dev/templates/flow.

Quick start#

  1. Unzip the download and open a terminal in the folder.

  2. Install and start the development server:

    sh
    pnpm install
    pnpm dev
  3. Visit http://localhost:3000. Edit files in src/ and the page reloads.

Requirements: Node.js 24 and pnpm (npm works too: npm install, npm run dev). The fonts are bundled, so nothing loads from the internet.

Command What it does
pnpm dev Development server with hot reload
pnpm build Static export to out/
pnpm start Serve out/ locally
pnpm lint ESLint
pnpm typecheck Route types and TypeScript

Pages#

Route File Purpose Notable sections and features
/ src/app/page.tsx Home Hero with a live "next class" card, today's classes (or tomorrow's after the last class), class styles, intro offer band, teachers, testimonials, workshops
/timetable src/app/timetable/page.tsx Schedule and booking My bookings, style/level/teacher filters, seven-day list with "On now" and "Up next", mat booking dialog
/classes src/app/classes/page.tsx Class styles Seven styles with "good if" lists, length, room, teachers, next class and classes a week; level guide; health note
/teachers src/app/teachers/page.tsx Teachers Four profiles with training, styles, next class and a link to their filtered schedule
/pricing src/app/pricing/page.tsx Prices Intro offer, class passes, memberships, intro-offer calculator, short FAQ
/workshops src/app/workshops/page.tsx Workshops and retreats Event cards with spots left, kind filter, booking inquiry form
/guide src/app/guide/page.tsx Beginners' guide and FAQ Five steps, what to bring, health note, searchable FAQ accordion
/contact src/app/contact/page.tsx Contact Illustrated map, address, today's opening times, travel notes, message form
(any unknown address) src/app/not-found.tsx Not found Links back into the site

Project structure#

flow/
  src/
    app/
      layout.tsx            <html>, metadata defaults, skip link, header, <main>, footer, toast
      page.tsx              home page; one folder per other page (timetable/, classes/, ...)
      not-found.tsx         the 404 page
      globals.css           Tailwind source: theme tokens and components
      fonts.ts              EB Garamond and Mulish, loaded with next/font/local
      icon.svg              favicon (the sun-over-the-sea mark)
    components/
      SiteHeader.tsx        logo, menus, the My bookings pill and its count
      SiteFooter.tsx        footer links and address
      ClassRow.tsx          one class in a list, with its tag and booking button; LevelMark
      BookingDialog.tsx     the mat picker dialog (home page and schedule)
      NextClassCard.tsx     home page hero: the next class
      TodayClasses.tsx      home page: today's (or tomorrow's) classes
      Timetable.tsx         schedule: filters, seven-day list, empty state
      MyBookings.tsx        schedule: the visitor's reserved mats
      StudioText.tsx        short clock texts: TimeNow, TodayHours, NextOf
      EventDate.tsx         a workshop's date, long or short
      PriceCalculator.tsx   pricing: the intro-offer calculator
      Workshops.tsx         workshops: kind filter, cards in date order, inquiry form
      Faq.tsx               guide: the searchable FAQ
      ContactForm.tsx       contact: the message form
      use-form.tsx          validation and success state shared by both forms
      StudioPrefill.tsx     fills in clock texts while the page loads
      StudioClock.tsx       reads the clock again on every page change
      Toast.tsx, BackToTop.tsx, RevealObserver.tsx, SamePageTop.tsx, Year.tsx
    data/
      studio.ts             studio, rooms, teachers, styles, levels, weekly schedule, prices, events, topics
      faq.ts                FAQ groups, questions and answers
    lib/
      time.ts               studio time, dates, 12-hour times, plurals, money
      schedule.ts           dated classes, now/next, taken mats, cleaning saved bookings
      events.ts             workshop dates (rolling rules or fixed dates)
      studio-store.ts       the clock and the bookings every component shares (useStudio)
      safe-storage.ts       localStorage with an in-memory fallback
      text.ts               sentences filled in from the clock
      validation.ts         form rules and the confirmation reference
      toast.ts, delay.ts, asset.ts, metadata.ts
    fonts/                  the woff2 files and their license texts
  public/img/
    og-image.svg            social image source; og-image.png is the 1200x630 export
    pose-*.svg              line drawings for the class styles (240x240)
    teacher-*.svg           arch-shaped teacher portraits (240x300)
    map.svg                 illustrated map on the contact page (640x440)
    favicon.svg             the mark as a separate file
  next.config.ts            static export and the optional base path
  package.json              scripts, dependencies and browser targets
  README.md                 short introduction
  DOCS.md                   this guide
  CHANGELOG.md              version history
  LICENSE.txt               MIT license (in the download)

Customizing#

Brand and colors#

All design tokens are in the @theme block at the top of src/app/globals.css:

Token Use
--color-sand, --color-shell, --color-dune, --color-drift, --color-line Page background, cards, soft panels, deeper panels, borders
--color-sea-50 ... --color-sea-900 Brand color: buttons and links (700), dark bands (900)
--color-clay-100 ... --color-clay-700 Warm accent: italic words, "On now", best-value bars
--color-sage-100 ... --color-sage-700 Level dots, check marks and leaves
--color-ink, --color-body, --color-mute Headings, body text, secondary text
--color-error Form errors

To change the brand color, replace the sea scale with your own; the development server picks it up on save:

css
@theme {
  --color-sea-700: #3b4f7a; /* buttons, links */
  --color-sea-900: #1f2a44; /* dark bands and footer */
}

Inline SVG artwork uses hex values directly (for example #2c524d in the logo and #1a3431 for line drawings), so search for the old hex codes in src/ and public/img/ if you change the palette a lot. The browser's toolbar color is themeColor in src/app/layout.tsx.

Typography#

Headings use EB Garamond (--font-serif, classes display, section-title, card-title) and body text uses Mulish (--font-sans). Both are self-hosted: src/app/fonts.ts loads the Latin woff2 files in src/fonts/ with next/font/local, under their plain family names, and src/app/globals.css names them in the two tokens:

ts
const serif = localFont({
  src: [
    { path: "../fonts/EBGaramond-latin.woff2", weight: "400 600", style: "normal" },
    { path: "../fonts/EBGaramond-Italic-latin.woff2", weight: "400 600", style: "italic" },
  ],
  fallback: ["EB Garamond"],
  adjustFontFallback: false,
  declarations: [{ prop: "font-family", value: "EB Garamond" }],
});

To swap a font, put its woff2 files in src/fonts/, change the localFont call (paths, weights, the font-family declaration and fallback) and the family name in --font-serif or --font-sans.

Content#

Page text lives in the page files in src/app/. Everything the components compute from lives in src/data/studio.ts:

Constant What it holds
STUDIO Name, timeZone (America/Los_Angeles), contact details, daysAhead (7), bookingCutoff (minutes before the start when booking closes, 0), demoFill (share of mats shown as taken, 0.45)
ROOMS loft (16 mats, 4 per row) and garden (10 mats, 5 per row)
TEACHERS morwenna, jago, anouk, kerensa: name, short name, role
STYLES vinyasa, hatha, slow, yin, restore, pregnancy, beginners
LEVELS open (All levels, 0 dots), gentle (1), steady (2), strong (3)
CLASSES The weekly schedule: 30 classes with id, day (0 = Sunday), start (24-hour Pacific time, shown on the page in 12-hour form by hhmm()), mins, style, level, teacher, room
PRICES Drop-in price, intro offer ($59 for 3 weeks), discount (concession, 20%), and the five options the calculator compares
EVENTS Workshop and retreat ids, titles, kinds and dates: a rolling rule (for example the 1st Saturday of next month) or fixed date/end in the studio's time zone
TOPICS Contact form topics (the form's options) that ?topic= can preselect

The FAQ is in src/data/faq.ts (FAQ: groups with a title and items of q and a).

To add a class, add a line to CLASSES with a unique id (bookings are saved against it):

ts
{ id: "thu-1230", day: 4, start: "12:30", mins: 45, style: "slow", level: "gentle", teacher: "kerensa", room: "garden" },

To add a style or teacher, add it to STYLES or TEACHERS (the schedule filters list them from there) and add its section to src/app/classes/page.tsx or src/app/teachers/page.tsx with id="<key>": the schedule links to /classes#<style> and /teachers#<teacher>. A new level also needs an <option> in the level filter in src/components/Timetable.tsx.

Prices appear twice: in the cards in src/app/pricing/page.tsx and in PRICES for the calculator. Change both. Workshops also appear twice: the cards in src/app/workshops/page.tsx (each is an <EventCard id="<id>">) and EVENTS, which also gives the inquiry form its options.

Workshop dates: rolling or fixed

So the demo always has upcoming events, each event in EVENTS has a rolling rule, worked out from today's date in Santa Cruz: monthsAhead (1 = next month), weekday (0 = Sunday ... 6 = Saturday) and nth (1–4, or -1 for the last one in the month). days sets how long it lasts (default 1). For your real program, replace the rule with fixed dates; an event with a date ignores its rule:

ts
// Rolling: the 3rd Sunday of next month
inversions: { title: "Arm balances & inversions, step by step", kind: "workshop", rule: { monthsAhead: 1, weekday: 0, nth: 3 } },
// Fixed: a two-day event on March 13–14, 2027 (end is optional)
"new-year": { title: "Beginners’ weekend", kind: "course", date: "2027-03-13", end: "2027-03-14" },

The dates on the cards and on the home page teasers (<EventDate id="<id>" form="when" /> and form="short") and the inquiry form options are filled in from EVENTS. The static page reads "Dates on request" until the browser has worked them out. Keep the ids: ?event=<id> links use them.

Images and artwork#

There are no photos. All artwork is SVG drawn for this template:

  • public/img/pose-*.svg (240x240): a line figure over a colored pebble, used for class styles.
  • public/img/teacher-*.svg (240x300): arch-shaped portraits. To use photos, keep a 4:5 ratio and the arch class on the wrapper so they get the same rounded top.
  • The home hero scene is inline SVG in src/app/page.tsx (460x560, arch frame).
  • public/img/map.svg is an illustration, not a real map. Replace it with a screenshot of your own map or an embedded map.
  • public/img/og-image.svg is the social image source. Export it to og-image.png (1200x630) after editing; social sites don't show SVG. src/app/icon.svg is the browser tab icon.

Images are plain <img> tags whose src goes through asset() (src/lib/asset.ts), which adds the base path when the site is served from a sub-folder.

The header is src/components/SiteHeader.tsx and the footer src/components/SiteFooter.tsx; both are used once, in src/app/layout.tsx. To add a page, create src/app/<name>/page.tsx, then add a <Link> to the <nav aria-label="Main"> list and the mobile menu (#mobile-menu) in the header and, if you like, to the footer. aria-current={current("/<name>")} marks the current page's link. The desktop menu shows from 1280px (xl:); below that the menu button opens the mobile menu.

Features#

Dates and the static build#

The static build can't know the visitor's date, the address or saved bookings, so everything that depends on them is filled in by the browser. useStudio() in src/lib/studio-store.ts returns null while a page is prerendered and, in the browser, the studio's current time and the visitor's bookings ({ now, bookings }); the static HTML shows the written text ("This week", "Dates on request") in the meantime, and there is no hydration mismatch.

The time is read once per page view, like a page load in the HTML version: src/components/StudioClock.tsx reads it again whenever another page opens, so a list never changes under the visitor's hands.

Short texts that come from the clock (workshop dates, each style's and teacher's next class, today's opening times, the time on the schedule page, the home page's "today" heading and the copyright year) are also written into the page by a small inline script while it is still loading, so their placeholders don't flash on a slow device: src/components/StudioPrefill.tsx. It follows the same rules as src/lib/time.ts, src/lib/schedule.ts and src/lib/events.ts and gets the data from src/data/studio.ts and the sentences from src/lib/text.ts, so changes to data and wording apply to both; if you change how a date is worked out in src/lib/, change it in that script too. Lists and everything that needs saved bookings wait for React.

Today's classes and next class#

On the home page TodayClasses.tsx ([data-today-list]) lists today's classes with their state, and NextClassCard.tsx ([data-next-class]) shows the next class that hasn't started yet, with a button to reserve a mat. Times come from CLASSES and the current time in STUDIO.timeZone (America/Los_Angeles), whatever the visitor's own time zone. Once today's last class has finished the list switches to tomorrow ("Tomorrow at the studio"), so the page never looks empty. A class is "On now" between its start and end, and the first class after now is "Up next".

Schedule and filters#

/timetable shows today plus the next six days (STUDIO.daysAhead), one section per day, rendered by src/components/Timetable.tsx inside [data-timetable]. Days with no matching classes are skipped and a count is announced in [data-tt-count]. The three selects in [data-tt-filters] filter by style, level and teacher; their values are kept in the URL (with history.replaceState) so filtered views can be shared:

/timetable?style=yin
/timetable?teacher=jago&level=strong

URL values are only used when they are own keys of STYLES, LEVELS or TEACHERS (has() in src/data/studio.ts), so ?style=constructor is ignored. If nothing matches, [data-tt-empty] appears with a button to clear the filters. A link to the schedule while it is showing (Schedule in the header) clears the filters, like a page load.

Mat booking#

Every bookable class has a button with data-book="<class id>@<YYYY-MM-DD>". A click on any such button opens the native <dialog> in src/components/BookingDialog.tsx ([data-book-dialog]) with a room plan ([data-mat-grid]): one radio button per mat, laid out ROOMS[room].cols per row with the teacher at the front. Mats shown as taken are demo data from takenMats() in src/lib/schedule.ts, a stable hash of the class and date controlled by STUDIO.demoFill; at least two mats are always left free. Set demoFill to 0 when you connect real data.

Reserving saves the booking (see Saved data), updates the header count ([data-booking-count]) on every page, the My bookings list on the schedule ([data-my-bookings]) and the class row ("Mat 7 booked"). Opening a booked class lets you move to another mat or cancel. Classes that have started or finished can't be booked; STUDIO.bookingCutoff closes booking earlier if you set it above 0.

The dialog is rendered on the home page and the schedule (<BookingDialog /> at the end of those two pages); add it to any other page where you use <ClassRow> or a data-book button.

Accessibility: the dialog is a modal <dialog> (focus is trapped, Esc closes it and focus returns to the button that opened it). Mats are a radio group inside a <fieldset> with a legend, taken mats are disabled and announced as "taken", and confirmations appear in a polite live region ([data-toast], src/components/Toast.tsx).

Connecting a booking system#

Bookings live only in the visitor's browser; the note under the mat map tells them reserved mats are listed under My bookings. To take real bookings, connect a booking system (Momence, Mindbody, bsport, TeamUp and others have widgets or APIs): call it in confirm() and cancel() in src/components/BookingDialog.tsx (and cancel() in src/components/MyBookings.tsx) before reserveMat() and cancelBooking(), or link the "Reserve a mat" buttons in src/components/ClassRow.tsx to its booking pages.

Class styles and teachers#

On /classes and /teachers, <NextOf of="style:<key>" /> and <NextOf of="teacher:<key>" /> (src/components/StudioText.tsx) show the next class of that style or teacher, and weeklyOf("style:<key>") (src/lib/schedule.ts) gives how many classes a week they have, both computed from CLASSES.

Intro-offer calculator#

src/components/PriceCalculator.tsx ([data-price-calc]) on /pricing takes classes a week (1–6, a range input) and a discount checkbox. It shows what the intro offer costs per class over three weeks and how much it saves on drop-in prices, then works out a month's cost for every option in PRICES.options (52 weeks / 12 months): drop-in, 5-class pass, 10-class pass, Eight a month (plus extra per class over eight) and Unlimited. The cheapest is highlighted and bars compare the rest. The discount only applies to memberships. Results are announced through aria-live.

Workshops and retreats#

src/components/Workshops.tsx holds the page's parts. Each card in src/app/workshops/page.tsx is an <EventCard id="<id>"> inside <EventGrid>. Dates come from EVENTS (rolling rules or fixed dates, see Workshop dates) and the cards are sorted by date. Events whose end date is before today are hidden, and their option is removed from the inquiry form. The "Everything / Workshops / Retreats" buttons (<KindFilter />, [data-kind-filter]) use aria-pressed. An "Inquire" button (<EnquireLink>) preselects the event in the form, and /workshops?event=scilly#enquire does the same from another page (only ids in EVENTS are accepted).

src/components/Faq.tsx on /guide filters the <details data-faq> items as you type in [data-faq-search], highlights the match in each question with <mark>, opens items whose match is only in the answer, hides empty groups and announces the count. /guide?q=mat pre-fills the search. The accordion uses native <details>/<summary>, so it works with the keyboard.

Small extras#

  • Header gets a hairline when you scroll; mobile menu with aria-expanded, Esc and click-outside to close (src/components/SiteHeader.tsx).
  • Scroll reveal (.reveal, src/components/RevealObserver.tsx), off with reduced motion; delay("80ms") from src/lib/delay.ts staggers a row. Gentle drifting cards and tide lines in the hero.
  • /contact shows today's first door-opening time and last class end (<TodayHours />, [data-today-hours]).
  • /contact?topic=teaching preselects a topic (own keys of TOPICS only).
  • A back-to-top button appears after one screen of scrolling and moves up out of the toast's way (src/components/BackToTop.tsx).
  • A link to the page you are on opens it again from the top with filters, searches and forms reset, as a page load would (src/components/SamePageTop.tsx).

Forms#

There are two forms, both with novalidate, data-validate-form, inline errors and a success state, sharing useForm() in src/components/use-form.tsx (rules in src/lib/validation.ts):

Form Component Validates
Booking inquiry ([data-enquiry-form]) EnquiryForm in src/components/Workshops.tsx Event chosen, name, valid email, optional phone format, terms checked
Message ([data-contact-form]) src/components/ContactForm.tsx Name, valid email, topic chosen, message of at least 10 characters

Each field names its error element with data-error-id and is linked to it with aria-describedby ({...v.field("c-name-error")} and {v.error("c-name-error")}); a field's rule comes from required, data-validate (email, phone or message) and data-label. On submit, the first invalid field gets focus and a summary appears in a role="alert" paragraph. The success state confirms the message or inquiry has reached the studio, shows a short reference in [data-success-ref] (SS- and four characters, made in the browser by makeRef()) and says what happens next: a reply within one business day for messages and within two business days, with a deposit link, for workshop inquiries. If your form service returns its own reference, show that instead, and change the reply times to match how you actually handle messages.

The forms don't send anything until you connect them, although their success states read as if they had. To use Formspree (or any form service that accepts a POST), send the form in onSubmit in src/components/use-form.tsx, just before the flushSync() call that shows the confirmation, and only show it when the service answers OK:

ts
const sending = e.currentTarget;
const response = await fetch("https://formspree.io/f/your-id", {
  method: "POST",
  body: new FormData(sending),
  headers: { Accept: "application/json" },
});
if (!response.ok) {
  setSummary({ text: "Sorry, that didn’t send. Please email hello@saltandsageyoga.example.", shown: true });
  return;
}

Make onSubmit async for this, and pass sending to onSent(). With a server deployment (remove output: "export", see Building and deploying) you can post to a Route Handler instead, for example src/app/api/contact/route.ts with export async function POST(request: Request) that reads await request.formData() and passes it to your email service, or call a Server Action from the form.

Saved data (localStorage)#

Key Shape Validated on read
flow.bookings [{ "c": "mon-0700", "d": "2026-11-16", "m": 7 }]: class id, studio date, mat number Must be an array; c must be an own key of the classes; d must be YYYY-MM-DD on the class's weekday; m a whole number within the room's mats. Duplicates and classes that have finished are dropped and the cleaned list is written back (cleanBookings() in src/lib/schedule.ts).

All access goes through safeStorage() in src/lib/safe-storage.ts, used by src/lib/studio-store.ts. When localStorage is blocked (sandboxed iframes, strict privacy settings) or full, it falls back to an in-memory store, so booking still works for the rest of the visit. To reset, run localStorage.removeItem("flow.bookings") in the browser console or cancel each booking under My bookings.

SEO and sharing#

Each page sets its title, description and Open Graph tags with pageMetadata() from src/lib/metadata.ts (export const metadata = pageMetadata(...) at the top of each page.tsx); the layout has the defaults. Set NEXT_PUBLIC_SITE_URL to your domain when you build (NEXT_PUBLIC_SITE_URL=https://www.example.com pnpm build): metadataBase in src/app/layout.tsx uses it so og:image (/img/og-image.png) gets an absolute URL, which most social sites require. Add src/app/sitemap.ts and src/app/robots.ts if you want them generated, and consider LocalBusiness / ExerciseGym structured data (JSON-LD) with your address and opening hours.

Accessibility#

  • Skip link, landmarks (header, nav, main, footer), one <h1> per page, a logical heading order and aria-current="page" in the menus.
  • Visible focus rings (:focus-visible), WCAG AA color contrast on sand, shell and dune backgrounds.
  • Native <dialog> for booking, a radio group for mats, aria-pressed filter buttons, <details> for accordions.
  • Live regions for schedule counts, FAQ results, the calculator and booking confirmations.
  • prefers-reduced-motion turns off reveals, drifting and the breathing dot.

When editing, keep one <h1> per page, give new inputs a <label>, and make sure every aria-describedby, aria-labelledby and aria-controls points at an id that exists.

Building and deploying#

pnpm build writes a static site to out/ (output: "export" in next.config.ts):

  • Vercel: import the repository; no settings needed.
  • Netlify / Cloudflare Pages: build command pnpm build, publish directory out.
  • Any static host: upload the contents of out/.

To serve from a sub-folder, build with DEMO_BASE_PATH=/yoga pnpm build; next.config.ts passes it to basePath and NEXT_PUBLIC_BASE_PATH, which asset() uses. pnpm build:demo does this for the freeframe.dev demo (demo/, which you can delete).

Tailwind scans the source files for class names; keep each class name whole (not built from pieces such as `bg-${color}`), or it won't be generated.

To use server features (Route Handlers, Server Actions), remove output: "export" and images.unoptimized from next.config.ts and deploy to a Node-capable host such as Vercel.

Browser targets#

The browserslist field in package.json lists the oldest browsers the build supports (Chrome and Edge 111, Firefox 113, Safari 16.4). All of them support oklch() colors, so Tailwind's colors ship as written instead of being converted to lab() and hex, which rounds some of them slightly differently. Add older browsers there if you need them; the build then adds color fallbacks.

TypeScript setup#

package.json installs @typescript/native (TypeScript 7, which provides tsc) and typescript as an alias of @typescript/typescript6, because typescript-eslint and parts of the Next.js toolchain still need the TypeScript 6 API. When typescript-eslint supports TypeScript 7, replace both with typescript@7. eslint.config.mjs pins settings.react.version, because eslint-plugin-react can't detect it under ESLint 10.

Troubleshooting#

  • Classes show at the wrong time. Times are Pacific time (STUDIO.timeZone). If your studio is elsewhere, change the time zone and the "Pacific time" and "Santa Cruz" wording in the pages, src/lib/text.ts and the footer.
  • A booking disappeared. Bookings are removed once the class has finished, and they live in one browser only. In a private window or with storage blocked they last for the current visit.
  • A filter link doesn't filter. The value must match a key in STYLES, LEVELS or TEACHERS exactly (?style=restore, not ?style=restorative).
  • A new class doesn't show. Check its day (0 = Sunday) and that its style, level, teacher and room keys exist in the matching constants; TypeScript reports an unknown key.
  • A date flashes one value, then another, while the page loads. src/components/StudioPrefill.tsx works a date out differently from src/lib/; bring the two back in step (see Dates and the static build).
  • A workshop vanished. Events with a fixed date are hidden once it has passed; update the date, switch back to a rolling rule, or remove the card.
  • A new Tailwind class has no effect. Write the class name whole in the source; names put together in code are not generated.
  • The social preview shows no image. Build with NEXT_PUBLIC_SITE_URL set to your domain so og:image is an absolute URL, and use the PNG, not the SVG.

License#

MIT. The code and all included artwork are free for personal and commercial use, including client work. The full license is in LICENSE.txt in the download. EB Garamond and Mulish are licensed under the SIL Open Font License (the license texts are in src/fonts/). Salt & Sage Yoga, its teachers, students, reviews, events and prices are fictional.

Search documentation

Search the guides and every template's documentation