Freeframe

Documentation

Soiree

v1.0.0Updated Nov 15, 2026An editorial wedding and event planner website with a budget estimator and venue guide.

Overview#

Soiree is an editorial, magazine-style website for wedding and event planners. The demo brand is Ivy & Ash Events, a fictional planning studio at 112 Church Street in Charleston, South Carolina, that offers full planning, partial planning and day-of coordination for weddings, corporate events and private parties. This is the Next.js version: Next.js 16 with the App Router, React 19, TypeScript and Tailwind CSS v4, exported as a fully static site. It has the same pages, design and interactions as the HTML version, uses US spelling and US dollars, and works out of time zone America/New_York. This guide covers version 1.0.0. The template page, with a link to the live demo, is at freeframe.dev/templates/soiree.

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 and notable features
/ src/app/page.tsx Home: magazine-cover hero with a line-art "plate", "In this issue" contents, press names, founder's letter with studio numbers, the three packages, a pull quote, recent celebrations, process summary, estimator call to action, journal links
/services src/app/services/page.tsx One section per package (#full, #partial, #dayof), comparison table (#compare), corporate and private events, add-on prices, FAQ (<details>)
/estimator src/app/estimator/page.tsx Event type, guest count slider and number field, season, package, add-ons; live fee range, whole-celebration range, per-guest figure and spending breakdown; "Send this with an inquiry" link
/portfolio src/app/portfolio/page.tsx Filter by type, eight case studies rendered from data, case-study dialog with previous/next, client quotes
/process src/app/process/page.tsx Seven planning steps with timing and a "Where would you start?" date checker
/venues src/app/venues/page.tsx Ten venues rendered from data; filter by area, setting and guest count; sort; save a shortlist; "Shortlist only" toggle
/journal src/app/journal/page.tsx Feature article on costs, notes on rain plans, Thursday weddings and tipping (with a table), press and kind words
/inquire src/app/inquire/page.tsx Inquiry form prefilled from the estimator or a case study, saved venues as checkboxes, validation with an error summary, confirmation with a reference
404 src/app/not-found.tsx Friendly message and links to every page

Project structure#

soiree/
  src/
    app/
      layout.tsx            <html>, fonts, header, footer, toast, back to top, metadata defaults
      fonts.ts              next/font/local setup for Playfair Display and Mulish
      globals.css           Tailwind import, @theme tokens and the small component layer
      icon.svg              the "&" monogram favicon
      page.tsx              home page
      <route>/page.tsx      one folder per page: services, estimator, portfolio, process, venues, journal, inquire
      not-found.tsx         404 page
    components/
      SiteHeader.tsx        top bar, sticky header and the mobile menu
      SiteFooter.tsx        footer
      Estimator.tsx         budget estimator form and result panel
      Portfolio.tsx         portfolio filter, grid and case-study dialog
      ProcessPlanner.tsx    "Where would you start?" and the seven steps
      VenueGuide.tsx        venue filters, list and shortlist
      InquiryForm.tsx       inquiry form, error summary and confirmation
      Year.tsx              rolling years (top bar and copyright); YearPrefill.tsx fills them in before React starts
      Reveal.tsx            scroll reveals
      BackToTop.tsx         back-to-top button
      Toast.tsx             the toast element
      SamePageTop.tsx       makes a link to the current page start it over
      WithAddress.tsx       gives a component the address (?type=…) once it runs in the browser
      PageBody.tsx          <body> with data-page
      icons.tsx             the arrow icon
    data/
      site.ts               content and prices: packages, seasons, add-ons, venues, celebrations
      process.ts            the seven planning steps and their thresholds
      nav.ts                header, menu and footer links
    lib/
      estimate.ts           estimator calculation and validation
      dates.ts              dates in Charleston time
      shortlist.ts          reading and saving the venue shortlist
      store.ts              storage keys and JSON helpers
      safe-storage.ts       localStorage with an in-memory fallback
      visit.ts              "page opened again" counter, setParam() and useHydrated()
      toast.ts              toast() and its state
      format.ts             money(), plural(), own(), delay()
      metadata.ts           pageMetadata() for titles and Open Graph tags
      asset.ts              asset() adds the base path to files in public/
    fonts/                  the woff2 files and their license texts
  public/img/
    og-image.svg            source of the social sharing image
    og-image.png            the social sharing image (1200x630)
    hero-piazza.svg         home page illustration (480x600)
    art-*.svg               line-art illustrations (400x500) for celebrations, venues and packages
    favicon.svg             a copy of the favicon for your own use
  next.config.ts            static export and optional base path
  package.json, tsconfig.json, eslint.config.mjs, postcss.config.mjs, pnpm-workspace.yaml
  README.md, DOCS.md, CHANGELOG.md
  LICENSE.txt               license (in the download)

Customizing#

Brand and colors#

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

Token Value Used for
--color-ink #16130f Text, rules, dark sections, buttons
--color-cream #f4ede1 Page background
--color-paper #fbf7ef Cards, form fields, alternate sections
--color-bone / --color-rule #ebe2d3 / #cdbfa8 Fine rules and dividers
--color-muted #5f574d Secondary text
--color-blush / --color-blush-soft #e8cfc3 / #f3e3db The accent surfaces
--color-rose / --color-rose-deep #8f4c3e / #763c30 Accent text, italics, focus rings, bars
--color-gold / --color-champagne #a88654 / #d9c39a Line-art details, accents on ink

Each token becomes Tailwind utilities (bg-ink, text-rose, border-rule...). To change the accent, edit the rose and blush tokens; the development server picks the change up at once:

css
@theme {
  --color-rose: #2f5d50;      /* deep green instead of rose */
  --color-rose-deep: #244a40;
  --color-blush: #cfe0d6;
  --color-blush-soft: #e4eee8;
}

Keep --color-rose dark enough for text on cream (at least 4.5:1). The illustrations in public/img/ have their colors written into the SVG files; search and replace #8f4c3e, #a88654 and #f3e3db there too. The browser's toolbar color is themeColor in src/app/layout.tsx.

Typography#

Two fonts are self-hosted with next/font/local in src/app/fonts.ts: Playfair Display (display serif, with italics) and Mulish (body text). The woff2 files are in src/fonts/. Each face keeps its plain family name, so the tokens in src/app/globals.css name them directly:

css
--font-sans: "Mulish", ui-sans-serif, system-ui, ...;
--font-display: "Playfair Display", "Didot", "Bodoni 72", Georgia, "Times New Roman", serif;

To swap a font, put the new woff2 files in src/fonts/, change src, weight, fallback and the font-family declaration in src/app/fonts.ts, and use the same family name in the token. Headings use the display, headline, pull-quote and font-display classes; small uppercase labels use kicker and smallcaps.

Content#

Page text lives in the page files under src/app/. Data that the components render or calculate with lives in src/data/site.ts, as typed constants:

Name Shape Used by
TIME_ZONE "America/New_York" Dates on Process and Inquire, the rolling years
PACKAGES { full, partial, dayof } each { name, base, perGuest, blurb } Estimator fee and package list
EVENT_TYPES { wedding, corporate, private } each { name, perGuest } Estimator vendor spend
SEASONS { peak, summer, winter } each { name, months, feeFactor, spendFactor } Estimator
ADDONS { welcome, rehearsal, brunch, transport, design } each { name, price } Estimator fee and add-on list
BREAKDOWN [{ name, share }], shares adding up to 1 Estimator breakdown
GUEST_LIMITS { min: 20, max: 400, step: 10, initial: 120 } Estimator guests
SPREAD { fee: [0.95, 1.1], spend: [0.85, 1.2] } Low and high ends of each range
AREAS { downtown, "mount-pleasant", islands, rural, north } → label Venue filter and labels
SETTINGS { indoor, outdoor, both } → label Venue filter and labels
VENUES [{ id, name, area, setting, min, max, priceFrom, art, note }] Venue guide, inquiry shortlist
EVENT_TYPE_LABELS { wedding, corporate, private } → label Portfolio labels
CELEBRATIONS [{ id, title, type, date, venue, guests, pkg, art, headline, summary, story, details, quote, by }] Portfolio grid and dialog

src/data/process.ts has STEPS, the seven planning steps ({ from, when, title, text }).

To add a venue, append an object to VENUES (its art is the middle of a public/img/art-*.svg file name):

ts
{ id: "magnolia-hall", name: "Magnolia Hall", area: "downtown", setting: "indoor", min: 40, max: 180,
  priceFrom: 7200, art: "loft", note: "A restored 1890s meeting hall with a sprung dance floor." },

Use a new, URL-safe id, an area that exists in AREAS and a setting that exists in SETTINGS. The Area and Setting selects are built from AREAS and SETTINGS, so a new area appears there by itself. Celebrations work the same way; their type must be a key of EVENT_TYPE_LABELS. The estimator's package and add-on lists read their names and prices from PACKAGES and ADDONS, but package prices are also written in the page text (home, services and the comparison table): update both when you change them.

Images and artwork#

All artwork is SVG line art drawn for this template: hero-piazza.svg (480x600) on the home page and eight art-*.svg files (400x500, a 4:5 ratio) for celebrations, venues and packages, all in public/img/. To use photos instead, keep a similar ratio (4:5 portrait) and point the <img> tags or the art values at your files; frames crop with object-fit: cover. Images are plain <img> tags with asset() from src/lib/asset.ts, which adds the base path. Decorative images have alt=""; give real photos meaningful alt text.

The social image is public/img/og-image.png (1200x630), generated from og-image.svg. The favicon is src/app/icon.svg.

The links are in src/data/nav.ts: MAIN (left of the logo), SECONDARY (right of it) and MENU (the mobile menu and the footer list, in order). src/components/SiteHeader.tsx renders the top bar, both header lists, the "Inquire" button and the full-screen mobile menu (#mobile-menu) with numbered links, and marks the current page with aria-current="page"; src/components/SiteFooter.tsx renders the footer. To add a page, create src/app/<route>/page.tsx and add { href: "/<route>", label: "…" } to MAIN or SECONDARY (and so to MENU), and to PAGES in src/components/PageBody.tsx if you style pages by data-page.

The years in the top bar ("Now booking 2027 & 2028") and the footer copyright come from <Year /> in src/components/Year.tsx, which reads today's date in Charleston: <Year /> shows this year and <Year ahead={1} /> / <Year ahead={2} /> show next year and the year after, so the site never advertises a season that has passed. The static HTML carries the year in WRITTEN (in Year.tsx), and YearPrefill.tsx corrects it while the page is still loading. To show fixed years, replace the components with plain text and remove <YearPrefill /> from src/app/layout.tsx.

Features#

Budget estimator#

/estimator, in src/components/Estimator.tsx with the calculation in src/lib/estimate.ts. The visitor picks an event type, guest count, season, package and add-ons; the panel updates at once.

  • Planning fee = (base + perGuest x guests above 50) x season feeFactor + add-on prices. The range is the fee times SPREAD.fee, rounded to $100.
  • Vendor spend = guests x event type perGuest x season spendFactor. The whole-celebration range is spend times SPREAD.spend plus the fee range, rounded to $500. The per-guest figure is the midpoint divided by guests, rounded to $10.
  • The breakdown multiplies the spend range by each BREAKDOWN share.
  • "Full design and styling" is part of full planning, so it is checked and disabled for that package.
  • With the defaults (wedding, 120 guests, spring or fall, full planning, no add-ons) it shows $18,100 – $20,900 for the fee and $50,500 – $67,000 for the whole celebration, about $490 per guest.
  • ?package=full|partial|dayof (used by the Services page) selects a package. Choices are saved under soiree-estimate. "Start over" restores the defaults and clears the saved value.
  • "Send this with an inquiry" links to /inquire?package=…&guests=…&type=….
  • computeEstimate(cleanEstimate(state)) from src/lib/estimate.ts returns the calculation, for testing or reuse.

Every figure is labeled as an estimate only, not a quote. Accessibility: native radio buttons and checkboxes in fieldsets with legends; the slider and number field are labeled; a polite live region announces the new ranges half a second after the last change.

Portfolio filter and case studies#

/portfolio, in src/components/Portfolio.tsx. Cards are rendered from CELEBRATIONS in a staggered seven/five column grid. The filter buttons (data-filter) use aria-pressed, show counts and update a polite status ("Showing 2 celebrations"). The filter is kept in the URL as ?type=wedding|corporate|private.

Each card title is a button that opens a native <dialog> with the full story. ?case=<id> opens a story directly (if it's hidden by the filter, the filter resets to All). In the dialog, previous/next buttons and the Left/Right arrow keys move through the visible stories, Esc or a click on the backdrop closes it, and focus returns to the story's card. "Plan something like this" links to /inquire?type=<type>.

Venue guide and shortlist#

/venues, in src/components/VenueGuide.tsx. Filters: Area (?area= in the URL), Setting, Guests (venues whose minimum and maximum include the number) and Sort (name ignoring a leading "The", lowest price, largest capacity). "Shortlist only" (aria-pressed) shows saved venues. Each "Save" button is a toggle with aria-pressed and a toast confirms the change. When nothing matches, an empty state offers "Clear filters". The shortlist is saved under soiree-shortlist (src/lib/shortlist.ts) and appears on the inquiry form.

Where would you start?#

/process, in src/components/ProcessPlanner.tsx. The visitor enters an event date; the component works out the whole months between today in Charleston (America/New_York) and that date, then marks the first step whose from (months ahead) is at or below it with "Start here" (is-current), dims earlier steps (is-past) and explains the result ("Your date is 14 months away: perfect timing."). Dates must be after today and within three years. Change the thresholds with the from values in src/data/process.ts.

Header, reveals and back to top#

The mobile menu button uses aria-expanded and aria-controls, Esc closes the menu and returns focus, and it closes when the screen grows to desktop width. Elements with the reveal class fade in on scroll (src/components/Reveal.tsx, an IntersectionObserver), with an optional delay from style={delay(80)}, and everything shows at once with reduced motion. The back-to-top button is src/components/BackToTop.tsx, styled by the .back-to-top rules in src/app/globals.css; remove it from src/app/layout.tsx and delete both to drop it. Toasts come from toast("…") in src/lib/toast.ts.

Dates, addresses and the static build#

The pages are built once as static HTML, so anything that depends on today's date, the address (?type=, ?package=…) or saved data is filled in by the browser. The estimator, portfolio, venue guide and inquiry form are wrapped in <WithAddress> (src/components/WithAddress.tsx): the static HTML gets their plain starting state, and the browser builds them again with the address, so they can read it and storage as they start; that avoids hydration warnings. Date limits on the Process page wait for useHydrated() from src/lib/visit.ts. Keep one of those patterns when you add a component that reads the address, localStorage or the clock.

Components change the address with setParam() from src/lib/visit.ts, never with history.replaceState directly, so the site can tell its own changes from navigation.

On a static site a link to the current page reloads it. Here src/components/SamePageTop.tsx gives such links (Portfolio in the header while a filter is on, Inquire after the form was sent) the same result: the page scrolls to the top and <StartOver> in src/app/layout.tsx rebuilds the page content, so filters, forms and open FAQ answers start over and read the new address.

Forms#

Inquiry form#

/inquire, in src/components/InquiryForm.tsx. It validates when submitted, then live as the visitor corrects fields:

Field Rule
Your name Required
Email Required, name@domain.tld shape
Phone Optional; if filled, at least 10 digits
Type of event Required (wedding, corporate or private)
Event date A real date after today and within three years, in Charleston time; may be empty if "Our date is flexible" is checked
Guest count Required whole number from 10 to 500
Overall budget Required band
Message At least 20 characters (2,000 maximum, with a counter)

Errors appear under each field (aria-invalid and aria-describedby) and in an error summary that takes focus and links to each field. The form reads ?package=, ?guests= and ?type= from the URL (validated against the data), shows a note when it came from the estimator, and lists shortlisted venues as checked checkboxes. On success it shows a reference (IA- and four characters, made in the browser by makeRef()), the reply promise from the "What happens next" list and a summary of the inquiry. "Start a new inquiry" brings back an empty form.

Connecting a real backend#

The form doesn't send anything until you connect it, although its confirmation reads as if it had. In src/components/InquiryForm.tsx, find the comment "Connect your form here" in onSubmit. With a service such as Formspree, make onSubmit async and send the data before showing the confirmation:

ts
const response = await fetch("https://formspree.io/f/your-id", {
  method: "POST",
  body: new FormData(el),
  headers: { Accept: "application/json" },
});
if (!response.ok) {
  setProblems([{ id: "inq-name", text: "We couldn’t send your inquiry. Please try again." }]);
  focusNext.current = "summary";
  return;
}

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

The date checker on the Process page is not a form submission and sends nothing.

Saved data (localStorage)#

Key Shape Validation on read Reset
soiree-estimate { type, guests, season, pkg, addons: [] } cleanEstimate in src/lib/estimate.ts: each value checked with an own-key lookup against EVENT_TYPES, SEASONS, PACKAGES and ADDONS; guests rounded and clamped to 20–400; duplicate or unknown add-ons dropped; invalid JSON removed "Start over" on the estimator
soiree-shortlist ["venue-id", ...] readShortlist in src/lib/shortlist.ts: must be an array; unknown or duplicate ids are dropped and the cleaned list saved back Unsave venues, or localStorage.removeItem("soiree-shortlist")

All storage goes through safeStorage in src/lib/safe-storage.ts (with the JSON helpers and key names in src/lib/store.ts). When the browser blocks localStorage (a sandboxed iframe or strict privacy settings), it uses an in-memory stand-in, so the estimator and shortlist still work for the rest of the page view.

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 home page's and the defaults. Set NEXT_PUBLIC_SITE_URL to your domain when you build (NEXT_PUBLIC_SITE_URL=https://ivyandash.example 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 structured data (JSON-LD) with your address and phone number.

Accessibility#

  • Skip link, landmarks (header, labeled navs, main, footer), one <h1> per page and a logical heading order.
  • Visible focus rings (rose on light, champagne on ink), AA contrast for text, and a light color scheme only.
  • Toggle buttons use aria-pressed; the menu uses aria-expanded; status text uses polite live regions; the case study uses a native modal <dialog> with focus return.
  • Form fields have labels, hints and errors linked with aria-describedby; radio groups are fieldsets.
  • Scroll reveals, dialog animation and smooth scrolling are off with prefers-reduced-motion.
  • The comparison and tipping tables scroll inside a labeled, focusable region on small screens.

When editing, keep one <h1> per page, label every new input, and keep every aria-controls, aria-labelledby and aria-describedby pointing 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/, and set the host to serve 404.html for missing pages.

To serve from a sub-folder, build with DEMO_BASE_PATH=/events 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 `col-span-${n}`), 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.

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.

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 the Tailwind palette ships as written instead of being converted to lab() and hex, which rounds some colors slightly differently. Add older browsers there if you need them; the build then adds color fallbacks.

Troubleshooting#

  • New Tailwind classes have no effect. Class names built from pieces aren't generated; write them out in full.
  • The estimator keeps old choices. They're saved under soiree-estimate; press "Start over" or clear the site's storage.
  • A shortlisted venue disappeared after editing src/data/site.ts. Saved ids that no longer exist in VENUES are dropped. Keep ids stable when renaming venues.
  • A date is rejected as "after today" near midnight. Dates use Charleston time (America/New_York). Change TIME_ZONE in src/data/site.ts if your business is elsewhere.
  • The inquiry form says it's done but no email arrives. It sends nothing until connected; follow Connecting a real backend.
  • Shared links show no image. Build with NEXT_PUBLIC_SITE_URL set to your domain so og:image is an absolute URL.
  • Images break under a sub-folder. Use asset() for files in public/ and build with DEMO_BASE_PATH.
  • A hydration warning after editing a component. Values that depend on the clock, the URL or storage must be read in the browser only; follow the patterns in Dates, addresses and the static build.

License#

MIT. The code and all included artwork are free for personal and commercial use; see LICENSE.txt in the download.

Playfair Display and Mulish are included under the SIL Open Font License (see src/fonts/).

Ivy & Ash Events, its people, clients, venues and publications are fictional placeholders.

Search documentation

Search the guides and every template's documentation