@sonordev/site-kit 7.0.1 → 7.0.2

package/src/articles/README.md

@@ -0,0 +1,325 @@
+# Articles — `@sonordev/site-kit/articles`
+
+## Publication routes and artwork (5.4.0)
+
+Use one routing object for the stock components and their SEO helpers. Existing
+sites keep `/article/slug` unless they opt in. `basePath` remains supported as a
+metadata alias; `basePath` takes precedence when both are provided.
+
+```tsx
+import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'
+import {
+  createPublicationRoutes, generateArticleMetadata, generateArticleSchema,
+  generateArticleSitemap, generateArticleStaticParams, generateRssFeed,
+  getArticle,
+} from '@sonordev/site-kit/articles/server'
+import type { PublicationRoutingOptions } from '@sonordev/site-kit/articles/server'
+
+const siteUrl = 'https://example.com'
+const routing = {
+  basePath: '/theforge',
+  includeCategoryInPath: true,
+  categoryPath: (slug: string) => `/theforge?category=${encodeURIComponent(slug)}`,
+} satisfies PublicationRoutingOptions
+
+// Cards, related stories and cluster links now use /theforge/category/slug.
+const article = <Article slug="build-first" routing={routing} />
+const archive = <ArticleList routing={routing} />
+
+// Use these helpers from their corresponding Next.js route exports.
+const metadata = await generateArticleMetadata('build-first', { siteUrl, ...routing })
+const post = await getArticle('build-first')
+const schema = post ? generateArticleSchema(post, { siteUrl, ...routing }) : null
+// In app/theforge/[category]/[slug]/page.tsx, wrap it to pass the routing:
+// export function generateStaticParams() { return generateArticleStaticParams(routing) }
+const params = await generateArticleStaticParams(routing) // { category, slug }[]
+const sitemap = await generateArticleSitemap(siteUrl, {
+  ...routing,
+  includeCategories: false, // category filters don't need separate sitemap entries
+  includeClusters: false, // enable when your site implements cluster routes
+})
+const rss = await generateRssFeed({ siteUrl, siteName: 'The Forge', ...routing })
+const href = createPublicationRoutes(routing).post({ slug: 'build-first', category: 'guides' })
+```
+
+`routing` also works on `PublicationLayout`, `PublicationSidebar`, `RelatedPosts`, `AuthorPage`,
+`ClusterLandingPage`, and `ClusterNavigation`. To support another article shape,
+provide `postPath: post => '/articles/' + encodeURIComponent(post.slug)`.
+Callbacks return local paths; generated metadata, feeds, and sitemaps separately
+honor a valid `canonical_url`. The same routes apply to Atom and generated
+breadcrumb/cluster schemas. Supplied `schema`/`schema_json` objects stay intact.
+
+For custom layouts, `resolveArticleArtwork(post, 'article')` prefers
+`editorial_image`, preserving an empty decorative `editorial_image_alt`.
+`resolveArticleArtwork(post, 'card')` keeps the complete `featured_image`. Older API
+responses fall back to the featured image for both. The stock UI keeps generated
+Sonor cards fully visible, while manually selected photos keep their existing
+layout. Social metadata and RSS enclosures use the featured share card.
+
+The stock article renders accessible table scroll regions automatically. Custom
+renderers can call `wrapArticleTables(html)` and include `articleTableCss` within their
+`.sk-article-content` scope. Both exports are available from `article/server` and
+`article/server-ui`. The wrapper preserves the original table and is safe to apply
+twice. It's a layout transform, not a sanitizer; keep your existing content trust
+policy. Scrollbars and keyboard focus use `--sk-*` tokens.
+
+## Import server components from `article/server-ui`
+
+`Article`, `ArticleList`, `PublicationLayout`, `PublicationSidebar` and `RelatedPosts` are async
+server components. The `@sonordev/site-kit/articles` barrel is stamped `'use client'`
+at build time, and an async component inside a client module is not something Next
+can render — the route returns a 500.
+
+```tsx
+import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'  // ✅
+import { Article } from '@sonordev/site-kit/articles'                      // ❌ 500s
+```
+
+The barrel still re-exports them for backwards compatibility and they will move out
+in the next major. Reach for `@sonordev/site-kit/articles` only for genuine client
+components: `TableOfContents`, `ArticleFAQ`, `AuthorCard`, `ServiceCallout`,
+`NewsletterWidget`.
+
+`NewsletterWidget` needs either an `onSubmit` callback or a `formSlug`
+pointing at a managed Sonor form (newsletter routing) — with neither it
+renders nothing rather than a form that discards emails. `Article` mounts a
+childless `ArticleViewTracker` client island that counts real readers (one POST
+per post per session, deferred to idle); it needs `SiteKitLayout`'s globals
+and silently no-ops without them.
+
+Data helpers live in `@sonordev/site-kit/articles/server`, which is `server-only` — a
+client import there is a build error rather than a runtime one.
+
+Sonor-managed article with SSG, topic clusters, E-E-A-T author profiles, and full SEO integration. Create posts in the Sonor dashboard — they appear on your site automatically.
+
+## Quick Start
+
+### Articles Index
+
+```tsx
+// app/article/page.tsx
+import { ArticleList, PublicationLayout } from '@sonordev/site-kit/articles/server-ui'
+import { generatePublicationMetadata } from '@sonordev/site-kit/articles/server'
+
+export async function generateMetadata() {
+  return generatePublicationMetadata({ siteName: 'My Site', siteUrl: 'https://example.com' })
+}
+
+export default function PublicationPage() {
+  return (
+    <PublicationLayout hero={{ title: 'The Forge', subtitle: 'Latest articles' }}>
+      <ArticleList showCategoryFilter showPagination />
+    </PublicationLayout>
+  )
+}
+```
+
+### Single Post
+
+```tsx
+// app/article/[slug]/page.tsx
+import { Article } from '@sonordev/site-kit/articles/server-ui'
+import {
+  generateArticleStaticParams,
+  generateArticleMetadata,
+  requireArticle,
+} from '@sonordev/site-kit/articles/server'
+
+export const generateStaticParams = generateArticleStaticParams
+
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props) {
+  const { slug } = await params
+  await requireArticle(slug) // 404 for an unknown slug, before anything streams
+  return generateArticleMetadata(slug, { siteName: 'My Site', siteUrl: 'https://example.com' })
+}
+
+export default async function Post({ params }: Props) {
+  const { slug } = await params
+  return <Article slug={slug} showRelated showToc showAuthor />
+}
+```
+
+**A missing post is a 404.** `requireArticle`, `generateArticleMetadata` and
+`Article` all call Next's `notFound()` when the post doesn't exist, so a
+mistyped or deleted post URL answers 404 with `noindex`. They used to render a
+"Post Not Found" page on a 200 with an indexable title, which is a soft 404.
+Calling `requireArticle` from `generateMetadata` is what guarantees the status:
+metadata resolves before the page streams. To render your own missing-post
+state instead, pass `notFound: false` to `generateArticleMetadata` (its
+placeholder is marked `noindex`) and `notFound={false}` to `Article`.
+
+**A post with its own social card.** If the post route has an
+`opengraph-image.tsx` beside the page (see `@sonordev/site-kit/og/route`), pass
+`images: false`:
+
+```ts
+return generateArticleMetadata(slug, { siteName: 'My Site', images: false })
+```
+
+Otherwise the featured image is declared as `openGraph.images`, and Next lets
+declared images beat the file convention: the card never ships. `images: false`
+leaves the keys out entirely (Next checks `hasOwnProperty('images')`, so even
+`images: undefined` would hide the card). `sonor-setup doctor` flags a post
+route that has a card but still declares the image.
+
+### Topic Cluster Landing
+
+```tsx
+// app/article/topics/[slug]/page.tsx
+// From `article/server-ui`, not `article` — it's an async server component that fetches
+// the cluster, so it must stay out of the client-side `article` barrel.
+import { ClusterLandingPage } from '@sonordev/site-kit/articles/server-ui'
+
+export default function ClusterPage({ params }: { params: { slug: string } }) {
+  return <ClusterLandingPage slug={params.slug} basePath="/article" />
+}
+```
+
+## Components
+
+| Component | Import | Purpose |
+|-----------|--------|---------|
+| `Article` | `article/server-ui` | Single post with content, TOC, author, related |
+| `ArticleList` | `article/server-ui` | Post grid with pagination and category filter |
+| `PublicationLayout` | `article/server-ui` | Full layout with optional sidebar |
+| `PublicationSidebar` | `article/server-ui` | Categories, recent posts, tags |
+| `RelatedPosts` | `article/server-ui` | Related articles widget |
+| `PublicationPage` | `article/server-ui` | Drop-in publication index page (layout + list) |
+| `ArticlePage` | `article/server-ui` | Drop-in single-post page |
+| `CategoryPage` | `article/server-ui` | Drop-in category archive page |
+| `ClusterLandingPage` | `article/server-ui` | Topic cluster overview with pillar + support articles |
+| `ClusterNavigation` | `article` | Breadcrumb-style cluster nav |
+| `AuthorCard` | `article` | Author profile with E-E-A-T fields |
+| `TableOfContents` | `article` | Auto-generated from H2-H4 headings |
+| `ArticleFAQ` | `article` | FAQ section with schema |
+| `ServiceCallout` | `article` | CTA callout for related services |
+| `NewsletterWidget` | `article` | Email capture; needs `onSubmit` or `formSlug` |
+
+## Server Functions (`article/server`)
+
+```ts
+// Data fetching
+getArticle(slug)                    // Single post with full data, or null
+requireArticle(slug)                // Same, but calls notFound() when there's no post
+getAllArticleSlugs()                     // All published slugs (for generateStaticParams)
+getArticleCategories()                  // Categories with post counts
+getTopicCluster(slug)                // Cluster with pillar + support articles
+getTopicClusters()                   // All clusters
+
+// Next.js integration
+generateArticleStaticParams(routing?)   // [{ slug }], or [{ category, slug }] with includeCategoryInPath
+generateCategoryStaticParams()       // Returns [{ category }]
+generateAuthorStaticParams()         // Returns [{ slug }]
+// With no routing options, all three can be exported directly as
+// `generateStaticParams`; the props Next passes are ignored.
+generateArticleMetadata(slug, opts) // Next.js Metadata object; notFound() for a missing post.
+                                     // opts.images: false when the route has its own opengraph-image card
+generatePublicationMetadata(opts)      // Index page metadata
+generateArticleCategoryMetadata(name, opts)
+
+// Schema & SEO
+generateArticleSchema(post, opts)   // JSON-LD Article with FAQ
+generateArticleListSchema()             // JSON-LD for publication index
+generateFaqSchema(items)             // FAQ Page schema
+generateArticleSitemap(siteUrl)         // Sitemap entries for article
+
+// Validation
+validateArticleSeo(post)            // Returns field-by-field SEO audit
+validateSeoTitle(title, keyphrase?)  // Title length + keyword checks
+validateMetaDescription(desc)        // Description length check
+```
+
+## Multi-site projects
+
+One Sonor project can serve many domains (example.com plus its city
+microsites), each with its own article. A post with no site is project-wide and
+shows on every host; a post tagged `charlotte.example.com` shows only there.
+
+Every article read sends the site host automatically, as `?site=` on GETs and a
+`site` field on the related-posts and view-count POSTs. The host resolves from
+`NEXT_PUBLIC_SITE_URL`, which every microsite already sets, so most sites
+change nothing. To pin a host explicitly, pass `site`:
+
+```tsx
+<ArticleList site="charlotte.example.com" />           // also Article, PublicationSidebar, PublicationLayout, RelatedPosts, ClusterLandingPage
+await getArticle(slug, { site: 'charlotte.example.com' })
+await getAllArticles({ site: 'charlotte.example.com' })
+```
+
+`getAllArticleSlugs()` and `getAllAuthorSlugs()` take no arguments, so they can
+still be exported as `generateStaticParams`. They always use
+`NEXT_PUBLIC_SITE_URL`. Single-site projects and older API servers ignore
+`site`.
+
+## Article Props
+
+```ts
+interface ArticleProps {
+  slug: string
+  showRelated?: boolean    // Related posts section
+  showToc?: boolean        // Table of contents
+  showAuthor?: boolean     // Author card
+  unstyled?: boolean       // Skip default styles
+  notFound?: boolean       // Default true: notFound() when the post is missing. false renders a message.
+  className?: string
+  children?: (props: { post, toc, related }) => ReactNode  // Render prop
+}
+```
+
+## ArticleList Props
+
+```ts
+interface ArticleListProps {
+  category?: string           // Filter by category slug
+  tag?: string                // Filter by tag
+  author?: string             // Filter by author
+  featured?: boolean          // Featured posts only
+  search?: string             // Search posts
+  page?: number               // Default: 1
+  perPage?: number            // Default: 12
+  orderBy?: 'published_at' | 'title' | 'view_count'
+  order?: 'asc' | 'desc'
+  showCategoryFilter?: boolean
+  showPagination?: boolean
+  unstyled?: boolean
+  className?: string
+  children?: (props: { posts, pagination, categories }) => ReactNode
+}
+```
+
+## Key Types
+
+```ts
+interface Article {
+  slug: string; title: string; excerpt?: string; content: string;
+  featured_image?: string; author?: ArticleAuthor; category?: ArticleCategory;
+  tags?: string[]; meta_title?: string; meta_description?: string;
+  faq_items?: { question: string; answer: string }[];
+  article_type?: 'pillar' | 'support' | 'comparison' | 'faq' | 'glossary' | 'checklist';
+  cluster_slug?: string; reading_time?: number; // the API column ('X min read')
+  published_at?: string; status: 'draft' | 'published' | 'scheduled' | 'archived';
+}
+
+interface ArticleAuthor {
+  name: string; slug: string; bio?: string; avatar_url?: string;
+  title?: string; credentials?: string[]; expertise_areas?: string[];
+  years_experience?: number; is_subject_matter_expert?: boolean;
+}
+
+interface TopicCluster {
+  cluster_name: string; cluster_slug: string; core_topic: string;
+  geo_target?: string; target_service_page?: string; article_count: number;
+  pillar: Article | null; supports: Article[];
+}
+```
+
+## Styling
+
+Components use `.sk-article-*` and `.sk-article-list-*` classes. Import default styles:
+
+```tsx
+```
+
+Or use `unstyled` prop + `children` render prop for complete control.

package/src/commerce/README.md

@@ -0,0 +1,109 @@
+# Commerce — `@sonordev/site-kit/commerce`
+
+Products, services, classes, events, and checkout flows — all managed from the Sonor dashboard.
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `OfferingCard` | Card display for any offering type |
+| `OfferingList` | Grid/list of offerings with filtering |
+| `ProductPage` / `ProductDetail` | Full product page with gallery, sizes, variants |
+| `ProductGrid` / `ProductEmbed` | Product showcase widgets |
+| `SizeChart` | Clothing size chart display |
+| `EventTile` / `UpcomingEvents` | Event display widgets |
+| `EventCalendar` / `EventModal` | Calendar view + detail modal |
+| `EventEmbed` / `EventsWidget` | Embeddable event components |
+| `CheckoutForm` | Payment checkout flow |
+| `RegistrationForm` | Event/class registration |
+| `CalendarView` | Date-based calendar component |
+
+## Usage
+
+```tsx
+import { OfferingList, ProductPage } from '@sonordev/site-kit/commerce'
+
+// List all offerings
+export default function ShopPage() {
+  return <OfferingList type="product" />
+}
+
+// Single product page
+export default function Product({ params }) {
+  return <ProductPage slug={params.slug} />
+}
+```
+
+## API Functions
+
+```ts
+import {
+  fetchOfferings, fetchOffering,
+  fetchProducts, fetchProductBySlug,
+  fetchUpcomingEvents, fetchNextEvent,
+  fetchCategories, fetchServices,
+  createCheckoutSession, createPaymentIntent,
+  validateDiscountCode, registerForEvent,
+  fetchShippingRates, validateAddress,
+} from '@sonordev/site-kit/commerce'
+```
+
+## Offering Types
+
+```ts
+type OfferingType = 'product' | 'service' | 'class' | 'event' | 'subscription'
+
+interface CommerceOffering {
+  name: string; slug: string; type: OfferingType;
+  description?: string; featured_image_url?: string;
+  price_type: 'fixed' | 'variable' | 'quote' | 'free';
+  price?: number; compare_at_price?: number; currency: string;
+  track_inventory?: boolean; inventory_count?: number;
+  is_clothing?: boolean; size_chart?: SizeChart;
+  duration_minutes?: number; capacity?: number;
+  location?: string; is_virtual?: boolean;
+  schedules?: CommerceSchedule[]; variants?: CommerceVariant[];
+}
+```
+
+## Per-category styling (`data-category` / `data-offering-type`)
+
+Event and offering surfaces expose the offering's category slug and type as
+data attributes, so sites can theme categories with plain CSS — no custom
+components needed. `data-category` is only present when the offering has a
+category; `data-offering-type` is always present.
+
+Elements carrying the attributes:
+
+- `CalendarView` / `EventCalendar` — `.site-kit-calendar-event` chips (both
+  `title` and `image` display modes) and the image-mode wrapper
+- `EventTile` (both variants — also covers `UpcomingEvents` and `EventEmbed`)
+- `EventsWidget` — `.site-kit-event-card` in list and grid views
+- `OfferingCard` (all variants — also covers `OfferingList` / `ProductGrid`)
+
+```css
+/* e.g. two color schemes on one calendar: PTO vs school district */
+.site-kit-calendar-event[data-category="pto"] {
+  background: rgba(16, 185, 129, 0.15);
+  color: #059669;
+}
+.site-kit-calendar-event[data-category="school-district"] {
+  background: rgba(59, 130, 246, 0.15);
+  color: #2563eb;
+}
+```
+
+## Size Charts (clothing products)
+
+```ts
+interface SizeChart {
+  unit: 'inches' | 'cm'
+  fit_note?: string                // e.g., "Runs small. Order one size up."
+  measurements: string[]           // ['Chest', 'Length', 'Sleeve']
+  rows: Array<{
+    size: string                   // 'S', 'M', 'L', 'XL'
+    values: number[]               // Primary unit values
+    values_alt?: number[]          // Auto-converted alternate unit
+  }>
+}
+```

package/src/cta-bar/README.md

@@ -0,0 +1,154 @@
+# @sonordev/site-kit/cta-bar
+
+The Liquid Glass mobile CTA bar (6.1.0). A floating frosted capsule that
+keeps a site's one or two highest-intent actions a thumb away on phones.
+
+It replaces every hand-rolled sticky mobile bar in the fleet. Those eleven
+copies had each solved part of the same problem set; this one does all of it:
+
+| Behaviour | Before | Here |
+|---|---|---|
+| Hide while the form it points at is on screen | two sites, hand-built | `hideOver` |
+| Stay off the hero until the hero CTA scrolls away | one site | `showAfter` |
+| Get out from under the Echo launcher | two sites (`body:has`, a 72px dead corner) | automatic |
+| Ride out the iOS toolbar collapsing | one site (a GSAP tween) | `--sk-vv-layout-gap` |
+| Get out of the way of the keyboard | nobody | `hideWhileTyping` |
+| Tell Sonor which action converts | one site (hand-wired) | `cta_click` event |
+
+## Use it
+
+```tsx
+// app/layout.tsx (a server component)
+import Link from 'next/link'
+import { Phone, ClipboardCheck } from 'lucide-react'
+import { CtaBar, CtaBarAction } from '@sonordev/site-kit/cta-bar'
+
+<SiteKitLayout>
+  <Header />
+  <main>{children}</main>
+  <Footer />
+  <CtaBar label="Call or request a quote" hideOver="#quote">
+    <CtaBarAction href="tel:+15135550100" variant="secondary" icon={<Phone />}>
+      Call now
+    </CtaBarAction>
+    <CtaBarAction as={Link} href="/quote" icon={<ClipboardCheck />}>
+      Free quote
+    </CtaBarAction>
+  </CtaBar>
+</SiteKitLayout>
+```
+
+Rules:
+
+- **Render it once per page:** at the layout root for a site-wide bar, or
+  inside the page for a page-specific one. It's a labelled `<aside>`, valid
+  at either depth; the kit's axe gate covers both placements.
+- **Never inside a blurred header.** `backdrop-filter` on an ancestor becomes
+  the containing block for this fixed bar and clips it.
+- **Delete the site's own bar and its compensating `padding-bottom`.** The
+  kit renders a spacer that reserves the bar's height at the end of the page.
+- **Better: pad the footer instead of adding a strip after it.** A spacer
+  after a dark footer is a blank band in the page colour. Pass
+  `spacer={false}` and let the footer's own background run under the bar:
+
+  ```css
+  footer { padding-bottom: calc(2rem + var(--sk-cta-bar-space, 0px)); }
+  ```
+
+  `--sk-cta-bar-space` is set on `<html>` only while a bar is present and
+  below its breakpoint, so desktop and bar-less pages get `0px`.
+- **Delete any `--sk-echo-offset-bottom` rule written for the old bar.** The
+  kit sets it while the bar is on screen.
+
+`CtaBar` and `CtaBarAction` are plain components with no hooks, so a server
+layout can pass `as={Link}` and Link children without crossing a client
+boundary. The only client code is a childless behaviour island the bar
+mounts itself (about 4.4 KB gzipped for the whole module, glass and
+analytics included).
+
+## `<CtaBar>`
+
+| Prop | Default | |
+|---|---|---|
+| `label` | `"Quick actions"` | Accessible name of the landmark. |
+| `breakpoint` | `"lg"` | Hidden at this width and up: `sm` 640, `md` 768, `lg` 1024, `xl` 1280, `none` = every width. |
+| `layout` | `"fill"` | `fill` stretches actions across the capsule. `fit` hugs a single action in a centred capsule (the old floating "Request a quote" button). |
+| `showAfter` | | Selector. Hidden until that element scrolls off the top (the hero CTA). Server-rendered hidden, so it never slides in over the hero during hydration. No match = shown. |
+| `hideOver` | | Selector or selectors. Steps aside while any match is on screen: the form it points at, the footer. |
+| `hideWhileTyping` | `true` | Hidden while a text field has focus, so it never sits on the keyboard. |
+| `compactOnScroll` | `true` | Tightens while scrolling down; an icon-bearing secondary action folds to its icon. Scrolling up restores it. |
+| `echoClearance` | `true` | Lifts the Echo launcher above the bar while the bar is on screen, below the breakpoint only. |
+| `spacer` | `true` | Reserves the bar's height at the end of the page. |
+| `track` | `true` | Sends `cta_click` (`category: engagement`, `label`, `properties.href`, `properties.variant`, `properties.location = "cta_bar"`) through the standalone analytics dispatch. |
+
+Client navigation re-finds `showAfter` and `hideOver` targets on each route.
+
+## `<CtaBarAction>`
+
+| Prop | Default | |
+|---|---|---|
+| `as` | `a` with an `href`, else `button` | Any element or component, e.g. Next's `Link`. Polymorphic since 6.1.3: the action then takes that component's own props (required ones included), so `<CtaBarAction as={ScheduleTourButton} values={unit}>` type-checks and a missing required prop doesn't. |
+| `variant` | `"primary"` | `primary`: solid brand. `secondary`: tinted glass. `plain`: layout only, bring your own classes. |
+| `icon` | | Leading icon, hidden from assistive tech. Lucide icons are sized to 18px. |
+| `collapse` | secondary + icon | Fold to icon-only while compact. The label stays in the accessible name. |
+
+Everything else (`href`, `onClick`, `target`, `aria-*`, `data-*`) passes
+through. A `button` without an explicit `type` gets `type="button"`.
+
+## Theme it
+
+Colours and geometry are custom properties. Set them on `:root` so the bar,
+its spacer and the Echo clearance all read the same values.
+
+```css
+:root {
+  --sk-cta-primary-bg: var(--brand-primary);   /* default: --sk-primary, then #2563eb */
+  --sk-cta-primary-text: #fff;
+  --sk-cta-bar-text: var(--ink-900);           /* secondary label colour */
+}
+```
+
+**A dark bar: scope the tint to the bar, not `:root`.** The Echo window
+reads the same `--sk-glass-tint`, and its text follows `--sk-text-primary`
+(dark by default). A dark tint on `:root` puts that dark text on dark glass.
+Either scope the bar's colours to the bar:
+
+```css
+.sk-cta-bar {
+  --sk-glass-tint: #0b0a09;
+  --sk-cta-bar-text: #fff;
+  --sk-cta-primary-bg: #fff;
+  --sk-cta-primary-text: #0b0a09;
+}
+```
+
+or theme the whole kit dark with `--sk-bg` and `--sk-text-primary` on
+`:root`, which both surfaces (and site-kit forms) read.
+
+| Token | Default |
+|---|---|
+| `--sk-cta-bar-inset` | `12px` from the screen edges |
+| `--sk-cta-bar-padding` | `6px` between glass and buttons |
+| `--sk-cta-bar-action-height` | `48px` (44px tap target minimum; don't go lower) |
+| `--sk-cta-bar-max-width` | `520px` |
+| `--sk-cta-bar-z` | `40` |
+| `--sk-cta-bar-text` | `--sk-text-primary`, then `#111827` |
+| `--sk-cta-primary-bg` / `--sk-cta-primary-text` | `--sk-primary` / `#fff` |
+| `--sk-cta-secondary-bg` / `--sk-cta-secondary-text` | 8% of the text colour / the text colour |
+| `--sk-glass-*` | the shared glass recipe (`--sk-glass-tint`, `--sk-glass-opacity`, `--sk-glass-blur`, `--sk-glass-saturate`) |
+
+## The glass
+
+The surface is the kit's one Liquid Glass recipe (`src/shared/glass.tsx`),
+the same material as the Echo launcher and chat window, so the bar and the
+chat always match. The tint is mostly opaque (72%): the tint carries the
+contrast, and the blur only softens what shows through. Browsers without
+`backdrop-filter`, and visitors who ask their OS for reduced transparency
+or more contrast, get the same surface solid. Reduced motion turns the
+transitions off. JS-off visitors get the bar, visible, through
+`@media (scripting: none)`.
+
+On phones where the layout viewport runs taller than the visible one
+(in-app browsers, toolbar animations), mount `VisualViewportGap` from
+`@sonordev/site-kit/client`; the bar already adds `--sk-vv-layout-gap` to
+its `bottom`.