Freeframe

Documentation

Flow

v1.0.1Updated Nov 18, 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 Astro version: Astro 7, TypeScript and Tailwind CSS v4, with no UI framework. It builds to plain static files, 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.1 (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:4321. Edit files in src/ and the page reloads.

Requirements: Node.js 24 or newer and pnpm (npm works too: npm install, npm run dev). The fonts load from Google Fonts, so they need a connection.

Command What it does
pnpm dev Development server at http://localhost:4321 with hot reload
pnpm build Static site in dist/
pnpm preview Serve dist/ locally after a build
pnpm check astro check: type-checks .astro files and TypeScript
pnpm typecheck Generate Astro's types, then type-check with tsc (TypeScript 7)
pnpm lint ESLint (TypeScript and Astro rules)
pnpm build:demo Build for /demos/astro/flow into demo/ (only used for the demo on freeframe.dev)

Pages#

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

Project structure#

flow/
  src/
    pages/
      index.astro           home page; one file per other page (timetable.astro, classes.astro, ...)
      404.astro             the 404 page (builds to 404.html)
    layouts/
      Layout.astro          <html>, <head> metadata, skip link, header, <main>, footer, toast, scripts
    components/
      SiteHeader.astro      logo, menus and the My bookings pill
      SiteFooter.astro      footer links and address
      BookingDialog.astro   the mat picker dialog (home page and schedule)
    data/
      studio.ts             studio, rooms, teachers, styles, levels, weekly schedule, prices, events, topics
      faq.ts                FAQ groups, questions and answers
      nav.ts                the header's menu links
    lib/
      site.ts               site name, toolbar color and the url() helper
    scripts/
      main.ts               every interaction: schedule, booking, calculator, workshops, FAQ search, forms
      back-to-top.ts        the back-to-top button
    styles/
      global.css            Tailwind source: theme tokens and components
  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             browser tab icon (the sun-over-the-sea mark)
  astro.config.mjs          site URL, the optional base path and static output
  package.json              scripts and dependencies
  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/styles/global.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/lib/site.ts.

Typography#

Headings use EB Garamond (--font-serif, classes display, section-title, card-title) and body text uses Mulish (--font-sans). Both load from Google Fonts with the <link> in the <head> of src/layouts/Layout.astro. To swap a font, change the family in that link and the name in the matching token in src/styles/global.css:

css
@theme {
  --font-serif: "EB Garamond", "Garamond", "Iowan Old Style", "Palatino Linotype", Georgia, serif;
  --font-sans: "Mulish", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
}

Content#

Page text lives in the page files in src/pages/. Everything the scripts 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); src/pages/guide.astro renders it.

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/pages/classes.astro or src/pages/teachers.astro 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/pages/timetable.astro.

Prices appear twice: in the cards in src/pages/pricing.astro and in PRICES for the calculator. Change both. Workshops also appear twice: the cards in src/pages/workshops.astro (each has data-event="<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 (data-event-when="<id>"), on the home page teasers (data-event-short="<id>") and in the inquiry form options are filled in from EVENTS by src/scripts/main.ts. The built page reads "Dates on request" (or "coming soon" on the home page) 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/pages/index.astro (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. public/img/favicon.svg is the browser tab icon.

Images are plain <img> tags whose src goes through url() (src/lib/site.ts), which adds the base path when the site is served from a sub-folder: <img src={url("/img/pose-tree.svg")} ...>.

The header is src/components/SiteHeader.astro and the footer src/components/SiteFooter.astro; both are used once, in src/layouts/Layout.astro. The menu links are in src/data/nav.ts (mainNav, and mobileNav, which adds Home). To add a page, create src/pages/<name>.astro, pass current="<name>" to its <Layout> and add it to mainNav:

ts
{ key: "retreats", label: "Retreats", href: "/retreats" },

The link whose key matches the page's current gets aria-current="page". Add the page to a list in the footer too, if you like. Write every internal link with url() and without .html or a trailing slash: href={url("/pricing#intro")}. The desktop menu shows from 1280px (xl:); below that the menu button opens the mobile menu.

Features#

All interactions are in src/scripts/main.ts, a plain TypeScript module that src/layouts/Layout.astro loads on every page. Each block looks for its own markup (a data- attribute) and does nothing on pages without it.

Dates and the static build#

The built pages can't know the visitor's date, the address or saved bookings, so everything that depends on them is filled in by the browser when the page loads. studioNow() reads the current time in STUDIO.timeZone once per page view (NOW), so a list never changes under the visitor's hands; every link is a full page load, which reads it again. Until the script has run, the page shows its written text ("This week", "Dates on request").

Today's classes and next class#

On the home page the script fills [data-today-list] with today's classes and their state, and [data-next-class] with 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, drawn by renderTimetable() 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.

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.astro ([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(), 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 on the home page and the schedule (<BookingDialog /> at the end of those two pages); add it to any other page where you use 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] in src/layouts/Layout.astro).

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 the [data-book-confirm] click handler and in cancelBooking() in src/scripts/main.ts, before bookingsChanged(), or link the "Reserve a mat" buttons that actionHtml() writes to its booking pages.

Class styles and teachers#

On /classes and /teachers, elements with data-next-of="style:<key>" or data-next-of="teacher:<key>" show the next class of that style or teacher, and data-weekly-of="style:<key>" (or teacher:<key>) shows how many classes a week they have, both computed from CLASSES.

Intro-offer calculator#

[data-price-calc] on /pricing takes classes a week (1–6, a range input) and a discount checkbox. paintCalc() 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#

Each card in src/pages/workshops.astro has data-event="<id>". 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 ([data-kind-filter]) use aria-pressed. An "Inquire" button (data-enquire="<id>") preselects the event in the form, and /workshops?event=scilly#enquire does the same from another page (only ids in EVENTS are accepted).

On /guide the script 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 and without JavaScript.

Small extras#

  • Header gets a hairline when you scroll; mobile menu with aria-expanded, Esc and click-outside to close.
  • Scroll reveal (.reveal), off with reduced motion; style="--d:80ms" staggers a row. Gentle drifting cards and tide lines in the hero.
  • /contact shows today's first door-opening time and last class end ([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/scripts/back-to-top.ts).

Forms#

There are two forms, both with novalidate, data-validate-form, inline errors and a success state:

Form Page Validates
Booking inquiry ([data-enquiry-form]) src/pages/workshops.astro Event chosen, name, valid email, optional phone format, terms checked
Message ([data-contact-form]) src/pages/contact.astro 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; 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 the form[data-validate-form] submit handler in src/scripts/main.ts, just before form.hidden = true, and only show the confirmation when the service answers OK:

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

Make the submit listener async for this. Give each form an action with the same URL and method="post" if you also want it to work without JavaScript. The site is static, so the forms need an outside service (or your own API) to receive the data.

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 (readBookings() in src/scripts/main.ts).

All access goes through the safeStorage object in src/scripts/main.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 page view. To reset, run localStorage.removeItem("flow.bookings") in the browser console or cancel each booking under My bookings.

SEO and sharing#

Each page passes its title and description to <Layout>, which writes the description, a canonical URL, Open Graph tags and twitter:card. Canonical, og:url and og:image are absolute URLs built from site in astro.config.mjs, which reads SITE_URL:

sh
SITE_URL=https://www.example.com pnpm build

The 404 page passes noindex. Add a sitemap with @astrojs/sitemap and a public/robots.txt if your host doesn't create them, 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#

sh
pnpm build        # static site in dist/
pnpm preview      # preview dist/ locally

dist/ is plain HTML, CSS and JavaScript. Tailwind is compiled by @tailwindcss/vite during the build, so there is no separate CSS step; it scans src/ for class names, so keep each class name whole (not built from pieces such as `bg-${color}`), or it won't be generated. Pages are written as pricing.html rather than pricing/index.html (build.format: "file" in astro.config.mjs), and links point to /pricing without a trailing slash. Netlify, Cloudflare Pages and GitHub Pages serve /pricing from pricing.html automatically; Vercel does with cleanUrls (below).

  • Netlify / Cloudflare Pages: build command pnpm build, publish directory dist.
  • Vercel: import the repository; it detects Astro and static output needs no adapter. Add a vercel.json with { "cleanUrls": true } so /pricing serves pricing.html.
  • GitHub Pages: use the official Astro GitHub Action. For a project site (username.github.io/repo), build with DEMO_BASE_PATH=/repo.
  • Any static host: upload the contents of dist/. If the host doesn't map /pricing to pricing.html, change build.format to "directory" in astro.config.mjs.

To serve the site from a sub-folder, set DEMO_BASE_PATH when building, e.g. DEMO_BASE_PATH=/yoga pnpm build. It becomes Astro's base, and every link written with url() (including the class and teacher links the script writes into the schedule) includes it.

demo/ (if present) is the build used for the freeframe.dev demo; you can delete it.

TypeScript 7 setup#

package.json installs two TypeScript packages on purpose. @typescript/native is TypeScript 7 and provides the tsc that pnpm typecheck runs. typescript is an alias for @typescript/typescript6, the TypeScript 6 API that astro check and typescript-eslint load. When those tools support TypeScript 7, replace both with a single typescript@7. tsconfig.json extends Astro's strict preset.

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/scripts/main.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 page view.
  • 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 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.
  • Links 404 on the host. The host doesn't map /pricing to pricing.html. Use cleanUrls on Vercel, or switch build.format to "directory".
  • The social preview shows no image. Build with 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 provided by Google Fonts under the SIL Open Font License. Salt & Sage Yoga, its teachers, students, reviews, events and prices are fictional.

Search documentation

Search the guides and every template's documentation