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 Astro version: Astro 7 with TypeScript and Tailwind CSS v4, no UI framework, and a static build that runs on
any host. It matches the HTML version page for page, uses US spelling and US dollars, and works out of time zone
America/New_York. This guide covers version 1.0.1. The template page, with a link to the live demo, is at
freeframe.dev/templates/soiree.
Quick start#
Requirements: Node.js 24 or newer and pnpm (npm works too).
pnpm install
pnpm dev # http://localhost:4321With npm: npm install, then npm run dev.
| 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/soiree into demo/ (only used for the demo on freeframe.dev) |
Google Fonts load from the internet, so the fonts need a connection.
Pages#
| File | Route | Purpose | Notable sections and features |
|---|---|---|---|
src/pages/index.astro |
/ |
Home | Magazine-cover hero with 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 |
src/pages/services.astro |
/services |
Services & packages | One section per package (#full, #partial, #dayof), comparison table (#compare), corporate and private events, add-on prices, FAQ (<details>) |
src/pages/estimator.astro |
/estimator |
Budget estimator | 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 |
src/pages/portfolio.astro |
/portfolio |
Portfolio | Filter by type, eight case studies rendered from data, case-study dialog with previous/next, client quotes |
src/pages/process.astro |
/process |
Process | Seven planning steps with timing and a "Where would you start?" date checker |
src/pages/venues.astro |
/venues |
Venue guide | Ten venues rendered from data; filter by area, setting and guest count; sort; save a shortlist; "shortlist only" toggle |
src/pages/journal.astro |
/journal |
Journal | Feature article on costs, notes on rain plans, Thursday weddings and tipping (with a table), press and kind words |
src/pages/inquire.astro |
/inquire |
Inquiry form | Prefilled from the estimator or a case study, saved venues as checkboxes, validation with an error summary, confirmation with a reference |
src/pages/404.astro |
/404 |
Not found | Friendly message and links to every page |
Project structure#
soiree/
astro.config.mjs site URL, base path, file-style output, Tailwind plugin
package.json scripts and dependencies
tsconfig.json Astro's strict TypeScript preset
eslint.config.mjs ESLint flat config (typescript-eslint, eslint-plugin-astro)
public/img/
favicon.svg the "&" monogram favicon
og-image.svg source of the social sharing image
og-image.png the social sharing image (1200x630) used by og:image
hero-piazza.svg home page illustration (480x600)
art-*.svg line-art illustrations (400x500) for celebrations, venues and packages
src/
pages/*.astro one file per page (see Pages)
layouts/Layout.astro <html>, <head> metadata, header, <main>, footer, toast, script imports
components/
SiteHeader.astro top bar with the "Now booking" years, logo, both menus, "Inquire", mobile menu
SiteFooter.astro footer columns, contact details, copyright year
data/
site.ts content and prices: packages, seasons, add-ons, venues, celebrations
nav.ts the header, mobile menu and footer links
process.ts the seven planning steps on the Process page
lib/site.ts site name, theme color and the url() helper
scripts/main.ts all behavior: menu, reveals, estimator, portfolio, venues, process, inquiry form
scripts/back-to-top.ts the back-to-top button
styles/global.css Tailwind source: @theme tokens and the small component layer
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 live in the @theme block of src/styles/global.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:
@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. If you
change the page background, also change themeColor in src/lib/site.ts (the browser's toolbar color).
Typography#
Two Google Fonts are loaded by one <link> in the <head> of src/layouts/Layout.astro: Playfair Display
(display serif, with italics) and Mulish (body text). The families are set in src/styles/global.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, change the Google Fonts <link> in Layout.astro and the matching 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 .astro files in src/pages/. Data that the script renders or calculates with lives in
src/data/site.ts, as typed exports:
| Name | Shape | Used by |
|---|---|---|
TIME_ZONE |
"America/New_York" |
The years in the header and footer, date checks on Process and Inquire |
PACKAGES |
{ full, partial, dayof } each { name, base, perGuest, blurb } |
Estimator fee |
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 |
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 |
SETTINGS |
{ indoor, outdoor, both } → label |
Venue labels |
VENUES |
Venue[]: { id, name, area, setting, min, max, priceFrom, art, note } |
Venue guide, inquiry shortlist |
EVENT_TYPE_LABELS |
{ wedding, corporate, private } → label |
Portfolio filter and labels |
CELEBRATIONS |
Celebration[]: { id, title, type, date, venue, guests, pkg, art, headline, summary, story, details, quote, by } |
Portfolio grid and dialog |
src/data/process.ts exports STEPS ({ from, when, title, text }), which process.astro renders, and
src/data/nav.ts exports the menus (see Navigation, header and footer).
To add a venue, append an object to VENUES (its art is the middle of a public/img/art-*.svg file name):
{ 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. If you
add an area, also add an <option> to the Area select in src/pages/venues.astro. Celebrations work the same
way; their type must be a key of EVENT_TYPE_LABELS. Package prices are also written in the pages (home,
services and estimator pages and the comparison table): update both when you change PACKAGES.
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. Decorative images have alt=""; give real photos meaningful alt
text. Write image paths with the url() helper so they work under a base path:
<img src={url("/img/hero-piazza.svg")} alt="…" width="480" height="600">The social image is public/img/og-image.png (1200x630), generated from og-image.svg. The favicon is
public/img/favicon.svg.
Navigation, header and footer#
The header is src/components/SiteHeader.astro and the footer src/components/SiteFooter.astro; both are
included once, by the layout. Their links come from src/data/nav.ts: MAIN is the list left of the centered
logo, SECONDARY the list on its right, and MENU (home, both lists, then Inquire) fills the numbered
full-screen mobile menu (#mobile-menu) and the footer list. To add a page, create
src/pages/<name>.astro and add one line to MAIN or SECONDARY:
export const SECONDARY: NavItem[] = [
{ href: "/process", label: "Process" },
{ href: "/venues", label: "Venues" },
{ href: "/journal", label: "Journal" },
{ href: "/gallery", label: "Gallery" },
];Each page tells the layout which link is its own with current (current="/venues"), and the header marks
that link with aria-current="page". Internal links in pages go through url() from src/lib/site.ts
(href={url("/inquire?type=wedding")}), without .html or a trailing slash.
The years in the top bar ("Now booking 2027 & 2028") and the footer copyright are filled in by
src/scripts/main.ts from today's date in Charleston: <span data-year> shows this year and
<span data-year-ahead="1"> / data-year-ahead="2" show next year and the year after, so the demo never
advertises a season that has passed. The numbers written in the components are what visitors see without
JavaScript. To show fixed years, replace the spans with plain text.
Features#
Every interaction is plain TypeScript in src/scripts/main.ts, imported once by the layout and bundled by Astro
into one module. Each block starts by looking for its own markup (data-estimator, data-portfolio-grid...)
and does nothing on pages that don't have it.
Budget estimator#
src/pages/estimator.astro, code under "Budget estimator" in src/scripts/main.ts. The visitor picks an event
type, guest count, season, package and add-ons; the panel updates at once.
- Planning fee = (
base+perGuestx guests above 50) x seasonfeeFactor+ add-on prices. The range is the fee timesSPREAD.fee, rounded to $100. - Vendor spend = guests x event type
perGuestx seasonspendFactor. The whole-celebration range is spend timesSPREAD.spendplus 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
BREAKDOWNshare. - "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.
- The number field updates the estimate as you type whole numbers from 20 to 400; leaving the field rounds and
clamps anything else. The slider moves in steps of 10 (
GUEST_LIMITS.step). ?package=full|partial|dayof(used by the Services page) selects a package. Choices are saved undersoiree-estimate. "Start over" restores the defaults and clears the saved value.- "Send this with an inquiry" links to
/inquire?package=…&guests=…&type=…. window.SOIREE_ESTIMATE(state)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#
src/pages/portfolio.astro, code under "Portfolio" in main.ts. 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#
src/pages/venues.astro, code under "Venue guide" in main.ts. 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 and appears on the inquiry form.
Where would you start?#
src/pages/process.astro, code under "Process" in main.ts. The visitor enters an event date; the script works
out the whole months between today in Charleston (America/New_York) and that date, then marks the first step
whose data-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 from in src/data/process.ts, which the page writes to
each step's data-from attribute.
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 reveal fade in on scroll
(IntersectionObserver), and everything shows at once with reduced motion; a small inline script in the layout's
<head> swaps the no-js class on <html> for js, so content is never hidden when JavaScript is off. The
back-to-top button is created by src/scripts/back-to-top.ts and styled by the .back-to-top rules in
src/styles/global.css; delete the file, its import in Layout.astro and those rules to remove it.
Forms#
Inquiry form#
src/pages/inquire.astro, code under "Inquiry form" in main.ts. It validates when submitted, then live as
the visitor corrects fields:
| Field | Rule |
|---|---|
| Your name | Required |
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. The site is
static, so it needs an outside form service (or your own API) to receive the data. With a service such as
Formspree, add the endpoint to the form in src/pages/inquire.astro:
<form class="grid gap-9" data-inquiry-form action="https://formspree.io/f/your-id" method="POST" novalidate>Then, in src/scripts/main.ts, find the comment "Connect your form here" and send the data before showing the
success block:
fetch(form.action, { method: "POST", body: new FormData(form), headers: { Accept: "application/json" } })
.then((res) => { if (!res.ok) throw new Error("Send failed"); /* show the success block */ })
.catch(() => { /* show an error message and keep 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: [] } |
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", ...] |
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 one safeStorage object in src/scripts/main.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 passes its title and description to <Layout>, which writes the description, theme-color, a
canonical URL, Open Graph tags (og:title, og:description, og:url, og:image) and a Twitter card.
Canonical, og:url and og:image are absolute URLs built from site in astro.config.mjs, which reads
SITE_URL:
SITE_URL=https://ivyandash.example pnpm buildThe 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 structured data (JSON-LD) with your address and phone number.
Most static hosts serve 404.html for missing pages on their own.
Accessibility#
- Skip link, landmarks (
header, labelednavs,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 usesaria-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 # static site in dist/
pnpm preview # preview dist/ locallydist/ 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, including the ones written in strings in
src/scripts/main.ts, so keep them as whole class names. Pages are written as services.html rather than
services/index.html (build.format: "file" in astro.config.mjs), and links point to /services without a
trailing slash. Netlify, Cloudflare Pages and GitHub Pages serve /services from services.html automatically;
Vercel does with cleanUrls (below).
- Netlify / Cloudflare Pages: build command
pnpm build, publish directorydist. - Vercel: import the repository; it detects Astro and static output needs no adapter. Add a
vercel.jsonwith{ "cleanUrls": true }so/servicesservesservices.html. - GitHub Pages: use the official Astro GitHub Action.
For a project site (
username.github.io/repo), build withDEMO_BASE_PATH=/repo. - Any static host: upload the contents of
dist/. If the host doesn't map/servicestoservices.html, changebuild.formatto"directory"inastro.config.mjs.
To serve the site from a sub-folder, set DEMO_BASE_PATH when building, e.g.
DEMO_BASE_PATH=/soiree pnpm build. It becomes Astro's base, and every link and image written with url()
(including the ones the script writes) 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#
- A new class has no effect. Tailwind only sees whole class names in
src/. Write"lg:col-span-7", not"lg:col-span-" + n. - Links 404 on the host. The host doesn't map
/servicestoservices.html. UsecleanUrlson Vercel, or switchbuild.formatto"directory". - 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 inVENUESare dropped. Keep ids stable when renaming venues. - A date is rejected as "after today" near midnight. Dates use Charleston time (
America/New_York). ChangeTIME_ZONEinsrc/data/site.tsif 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, or the wrong address. Build with
SITE_URLset to your live domain and checkog-image.pngis deployed. - Portfolio or venue lists are empty. They are rendered by the script from
src/data/site.ts; runpnpm checkand look at the browser console for an error after editing the data.
License#
MIT. The code and all included artwork are free for personal and commercial use; see LICENSE.txt in the
download.
The fonts Playfair Display and Mulish are provided by Google Fonts under the SIL Open Font License.
Ivy & Ash Events, its people, clients, venues and publications are fictional placeholders.