create-clientkit 0.1.0

package/templates/astro-tailwind/base/src/components/LaunchNotice.astro

@@ -0,0 +1,156 @@
+---
+import { LAUNCH, SITE } from '../config/site.config.ts';
+
+// Render nothing at all unless a launch is configured *and* the date parses.
+// A broken date must never produce an empty box or fail the build.
+const parsed = LAUNCH.enabled && LAUNCH.date !== '' ? new Date(LAUNCH.date) : null;
+const launchDate = parsed !== null && !Number.isNaN(parsed.getTime()) ? parsed : null;
+
+const formatted =
+  launchDate === null
+    ? ''
+    : new Intl.DateTimeFormat(SITE.locale || 'en', {
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric',
+      }).format(launchDate);
+
+const iso = launchDate === null ? '' : launchDate.toISOString();
+---
+
+{
+  launchDate !== null && (
+    <div class="launch">
+      <p class="line">
+        Launching <time datetime={iso}>{formatted}</time>
+      </p>
+
+      {/*
+        The date above is the real content and is always present. The countdown
+        is a progressive enhancement: it stays hidden without JavaScript, and it
+        is hidden from assistive technology because it repeats what the date
+        already says.
+      */}
+      <div class="countdown" data-launch={iso} hidden aria-hidden="true">
+        <span class="unit">
+          <>
+            <b data-unit="days">0</b>
+            <small>days</small>
+          </>
+        </span>
+        <span class="unit">
+          <>
+            <b data-unit="hours">0</b>
+            <small>hrs</small>
+          </>
+        </span>
+        <span class="unit">
+          <>
+            <b data-unit="minutes">0</b>
+            <small>min</small>
+          </>
+        </span>
+        <span class="unit">
+          <>
+            <b data-unit="seconds">0</b>
+            <small>sec</small>
+          </>
+        </span>
+      </div>
+
+      {LAUNCH.note !== '' && <p class="note">{LAUNCH.note}</p>}
+    </div>
+  )
+}
+
+<script>
+  // ~20 lines, no framework, no hydration. Runs once on the page that uses it.
+  const root = document.querySelector<HTMLElement>('.countdown[data-launch]');
+  const target = root ? Date.parse(root.dataset.launch ?? '') : Number.NaN;
+
+  if (root && !Number.isNaN(target)) {
+    const cells = new Map<string, HTMLElement>();
+    for (const cell of root.querySelectorAll<HTMLElement>('[data-unit]')) {
+      cells.set(cell.dataset.unit ?? '', cell);
+    }
+
+    const tick = (): void => {
+      const remaining = target - Date.now();
+      if (remaining <= 0) {
+        root.hidden = true;
+        return;
+      }
+      const seconds = Math.floor(remaining / 1000);
+      const parts: Record<string, number> = {
+        days: Math.floor(seconds / 86400),
+        hours: Math.floor(seconds / 3600) % 24,
+        minutes: Math.floor(seconds / 60) % 60,
+        seconds: seconds % 60,
+      };
+      for (const [unit, cell] of cells) {
+        cell.textContent = String(parts[unit] ?? 0).padStart(2, '0');
+      }
+      root.hidden = false;
+    };
+
+    tick();
+    window.setInterval(tick, 1000);
+  }
+</script>
+
+<style>
+  .launch {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    align-items: flex-start;
+  }
+
+  .line {
+    margin: 0;
+    color: var(--color-foreground);
+    font-size: var(--text-body);
+  }
+
+  time {
+    font-weight: 600;
+  }
+
+  .countdown {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+
+  .unit {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.125rem;
+    min-width: 3.75rem;
+    padding: 0.625rem 0.75rem;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background-color: var(--color-surface);
+  }
+
+  .unit b {
+    font-size: 1.125rem;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    letter-spacing: -0.01em;
+  }
+
+  .unit small {
+    color: var(--color-muted);
+    font-size: 0.6875rem;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  .note {
+    margin: 0;
+    color: var(--color-muted);
+    font-size: var(--text-small);
+  }
+</style>

package/templates/astro-tailwind/base/src/components/Seo.astro

@@ -0,0 +1,73 @@
+---
+import { SEO, SITE } from '../config/site.config.ts';
+import { absoluteUrl, assetUrl, siteOrigin } from '../lib/seo.ts';
+
+/**
+ * Every <head> tag that describes the page lives here, so there is exactly one
+ * place that decides titles, canonical URLs and social metadata - and exactly
+ * one of each tag in the output.
+ *
+ * Everything defaults from src/config/site.config.ts. A page only passes what
+ * it genuinely needs to override.
+ */
+interface Props {
+  /** Page name. Omit on the home page so the title is just the site name. */
+  title?: string;
+  /** Overrides SITE.description for this page. */
+  description?: string;
+  /** Force this page out of the index regardless of the site setting. */
+  noindex?: boolean;
+  /** Open Graph type. 'website' suits every page this template ships. */
+  type?: 'website' | 'article';
+  /** Overrides SEO.image for this page. */
+  image?: string;
+}
+
+const { title, description, noindex = false, type = 'website', image } = Astro.props;
+
+// '' means no production URL is configured. Every absolute tag below is then
+// skipped rather than pointed at a domain nobody has bought yet.
+const origin = siteOrigin(SITE.url);
+
+const pageTitle = title ? `${title} - ${SITE.name}` : SITE.name;
+
+// page description -> site description -> no tag at all. Nothing invented.
+const metaDescription = (description ?? SITE.description).trim();
+
+// A page may opt out on its own (the 404 does); the site setting covers the rest.
+const blocked = noindex || SEO.noindex;
+const robots = blocked ? 'noindex, nofollow' : 'index, follow';
+
+// A canonical tag says "this is the definitive URL for this content" while
+// noindex says "do not index it". Emitting both is contradictory, so a blocked
+// page gets no canonical at all.
+const canonical = origin === '' || blocked ? '' : absoluteUrl(origin, Astro.url.pathname);
+
+const socialImage = assetUrl(origin, image ?? SEO.image);
+
+// og:locale wants language_TERRITORY. A bare 'en' is not valid, so it is
+// omitted rather than emitted in a form crawlers will discard.
+const ogLocale = /^[a-z]{2,3}-[A-Za-z0-9]{2,8}$/.test(SITE.locale)
+  ? SITE.locale.replace('-', '_')
+  : '';
+---
+
+<title>{pageTitle}</title>
+{metaDescription !== '' && <meta name="description" content={metaDescription} />}
+<meta name="robots" content={robots} />
+{canonical !== '' && <link rel="canonical" href={canonical} />}
+
+{/* Open Graph. Only tags whose value actually exists are emitted. */}
+<meta property="og:type" content={type} />
+<meta property="og:title" content={pageTitle} />
+<meta property="og:site_name" content={SITE.name} />
+{metaDescription !== '' && <meta property="og:description" content={metaDescription} />}
+{canonical !== '' && <meta property="og:url" content={canonical} />}
+{ogLocale !== '' && <meta property="og:locale" content={ogLocale} />}
+{socialImage !== '' && <meta property="og:image" content={socialImage} />}
+
+{/* Twitter/X. No handle is required and none is invented. */}
+<meta name="twitter:card" content={socialImage !== '' ? SEO.twitterCard : 'summary'} />
+<meta name="twitter:title" content={pageTitle} />
+{metaDescription !== '' && <meta name="twitter:description" content={metaDescription} />}
+{socialImage !== '' && <meta name="twitter:image" content={socialImage} />}

package/templates/astro-tailwind/base/src/components/SocialLinks.astro

@@ -0,0 +1,75 @@
+---
+import { SOCIAL } from '../config/site.config.ts';
+
+interface Props {
+  /** Accessible name for the list, since a page may show it more than once. */
+  label?: string;
+  align?: 'start' | 'center';
+}
+
+const { label = 'Social links', align = 'start' } = Astro.props;
+
+// Nothing configured means nothing rendered - never an empty container.
+const links = SOCIAL.filter((link) => link.label !== '' && link.href !== '');
+const isExternal = (href: string) => /^https?:\/\//i.test(href);
+---
+
+{
+  links.length > 0 && (
+    <ul class:list={['social', align]} aria-label={label}>
+      {links.map((link) => (
+        <li>
+          <a
+            href={link.href}
+            rel={isExternal(link.href) ? 'me noopener noreferrer' : undefined}
+            target={isExternal(link.href) ? '_blank' : undefined}
+          >
+            {link.label}
+            {isExternal(link.href) && <span class="sr-only"> (opens in a new tab)</span>}
+          </a>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+<style>
+  .social {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem 1.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .center {
+    justify-content: center;
+  }
+
+  a {
+    display: inline-flex;
+    align-items: center;
+    min-height: 2.25rem;
+    color: var(--color-muted);
+    font-size: var(--text-small);
+    text-decoration: none;
+    transition: color 160ms ease;
+  }
+
+  a:hover {
+    color: var(--color-foreground);
+  }
+
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+</style>

package/templates/astro-tailwind/base/src/components/StructuredData.astro

@@ -0,0 +1,39 @@
+---
+import { CONTACT, SITE, SOCIAL } from '../config/site.config.ts';
+import { jsonLdScript, siteOrigin } from '../lib/seo.ts';
+
+/**
+ * schema.org Organization data, built only from values the developer has
+ * actually configured.
+ *
+ * Search engines consume structured data automatically, so a fabricated field
+ * here is worse than a missing one: every property below is omitted unless it
+ * has a real value. No logo, address, rating, review or founding date is
+ * invented, and none is emitted at all until the config carries one.
+ */
+const origin = siteOrigin(SITE.url);
+
+const sameAs = SOCIAL.filter((link) => link.href.trim() !== '').map((link) => link.href.trim());
+
+const organization: Record<string, unknown> = {
+  '@context': 'https://schema.org',
+  '@type': 'Organization',
+  name: SITE.name,
+};
+
+if (origin !== '') organization['url'] = origin;
+if (SITE.description.trim() !== '') organization['description'] = SITE.description.trim();
+if (CONTACT.email.trim() !== '') organization['email'] = CONTACT.email.trim();
+if (CONTACT.phone.trim() !== '') organization['telephone'] = CONTACT.phone.trim();
+if (sameAs.length > 0) organization['sameAs'] = sameAs;
+
+// `location` is free text, so it maps to a plain Place name rather than a
+// PostalAddress - claiming a structured address we do not have would be wrong.
+if (CONTACT.location.trim() !== '') {
+  organization['location'] = { '@type': 'Place', name: CONTACT.location.trim() };
+}
+
+const payload = jsonLdScript(organization);
+---
+
+<script type="application/ld+json" is:inline set:html={payload} />

package/templates/astro-tailwind/base/src/config/site.config.ts

@@ -0,0 +1,141 @@
+/**
+ * The single source of truth for this site.
+ *
+ * Every component reads from here, so updating a client's details is a
+ * one-file change. Nothing below is required to be filled in: an empty string
+ * or an empty array means "not set", and the UI omits that piece entirely
+ * rather than rendering a placeholder.
+ */
+
+export type Appearance = 'light' | 'dark' | 'system';
+export type SiteMode = 'coming-soon' | 'full';
+
+export interface NavItem {
+  label: string;
+  /** Internal path ('/about') or in-page anchor ('#services'). */
+  href: string;
+}
+
+export interface SocialLink {
+  /** Shown as the link text, so name the platform: 'Instagram', 'LinkedIn'. */
+  label: string;
+  href: string;
+}
+
+export interface SiteIdentity {
+  name: string;
+  description: string;
+  /**
+   * Production URL, as an origin: 'https://example.com'.
+   *
+   * Empty until the domain is decided - nothing is invented, and every
+   * absolute tag (canonical, og:url, sitemap) is simply omitted until it is
+   * set. Only the origin is used; to deploy under a subpath such as
+   * example.com/client, also set `base` in astro.config.mjs.
+   */
+  url: string;
+  /** BCP-47 language tag, used for <html lang> and date formatting. */
+  locale: string;
+  author: string;
+  /** How this project was scaffolded. Informational; edit the pages, not this. */
+  mode: SiteMode;
+}
+
+export interface ContactDetails {
+  email: string;
+  phone: string;
+  /** Free text, e.g. 'Manchester, UK'. */
+  location: string;
+}
+
+export interface LaunchSettings {
+  enabled: boolean;
+  /** ISO date or date-time, e.g. '2026-11-01' or '2026-11-01T09:00:00Z'. */
+  date: string;
+  /** Optional line shown beneath the date. */
+  note: string;
+}
+
+export interface ThemeSettings {
+  /** 'system' follows the visitor's OS preference. No JavaScript either way. */
+  appearance: Appearance;
+  /** Brand colour as a hex value, e.g. '#1d4ed8'. Empty keeps the neutral ink. */
+  accent: string;
+}
+
+export type TwitterCard = 'summary' | 'summary_large_image';
+
+export interface SeoSettings {
+  /**
+   * Social preview image, 1200x630 works everywhere. Either a path in
+   * `public/` ('/og.png') or an absolute URL.
+   *
+   * Empty by default and empty is safe: no `og:image` tag is emitted at all,
+   * which is better than pointing social platforms at a file that isn't there.
+   * Drop a real image in `public/` and name it here when you have one.
+   */
+  image: string;
+
+  /** 'summary_large_image' shows a wide preview; 'summary' shows a thumbnail. */
+  twitterCard: TwitterCard;
+
+  /**
+   * Ask search engines to stay away. Also suppresses the sitemap and its
+   * reference in robots.txt, so the site never advertises pages it has asked
+   * not to have indexed.
+   *
+   * Left `false` on purpose, including for coming-soon sites: a placeholder
+   * page that gets indexed is replaced at the next crawl, whereas a `noindex`
+   * left switched on after launch keeps the real site invisible for weeks.
+   * If you would rather the holding page stayed out of search, set this to
+   * true now and remember to turn it off when the real site goes live.
+   */
+  noindex: boolean;
+}
+
+/** Identity. These values are filled in from your answers at scaffold time. */
+export const SITE: SiteIdentity = {
+  name: '{{siteName}}',
+  description: '{{description}}',
+  url: '{{siteUrl}}',
+  locale: '{{locale}}',
+  author: '{{author}}',
+  mode: '{{mode}}',
+};
+
+/**
+ * Site navigation. Empty by default: the header renders no menu at all rather
+ * than inventing links. Add items once real pages or sections exist.
+ */
+export const NAV: NavItem[] = [];
+
+/** Social profiles. Add only accounts that actually exist. */
+export const SOCIAL: SocialLink[] = [];
+
+/** Contact details. Each field is optional and hidden when empty. */
+export const CONTACT: ContactDetails = {
+  email: '',
+  phone: '',
+  location: '',
+};
+
+/**
+ * Launch date. While `enabled` is false, or `date` is empty or unparseable,
+ * no launch information and no countdown is rendered.
+ */
+export const LAUNCH: LaunchSettings = {
+  enabled: false,
+  date: '',
+  note: '',
+};
+
+export const THEME: ThemeSettings = {
+  appearance: 'system',
+  accent: '',
+};
+
+export const SEO: SeoSettings = {
+  image: '',
+  twitterCard: 'summary_large_image',
+  noindex: false,
+};

package/templates/astro-tailwind/base/src/layouts/BaseLayout.astro

@@ -0,0 +1,121 @@
+---
+import Footer from '../components/Footer.astro';
+import Header from '../components/Header.astro';
+import Seo from '../components/Seo.astro';
+import StructuredData from '../components/StructuredData.astro';
+import { NAV, SITE, THEME, type NavItem } from '../config/site.config.ts';
+import '../styles/global.css';
+
+interface Props {
+  /** Page title. The site name is appended automatically. */
+  title?: string;
+  description?: string;
+  /** Keep this page out of search results regardless of the site setting. */
+  noindex?: boolean;
+  /** Emit Organization structured data. On for content pages, off for the 404. */
+  structuredData?: boolean;
+  /** Overrides the navigation from site.config.ts for this page. */
+  nav?: NavItem[];
+  /** Hide the header entirely - used by pages that carry their own branding. */
+  showHeader?: boolean;
+  /**
+   * Column width shared by the header, content and footer.
+   * 'narrow' suits a single focused page; 'wide' suits content pages.
+   */
+  measure?: 'narrow' | 'wide';
+}
+
+const {
+  title,
+  description,
+  noindex = false,
+  structuredData = true,
+  nav = NAV,
+  showHeader = true,
+  measure = 'wide',
+} = Astro.props;
+
+// 'system' means no attribute at all, so the CSS media query decides.
+const appearance = THEME.appearance === 'system' ? undefined : THEME.appearance;
+
+// theme.accent is developer-authored, but it is interpolated into a stylesheet,
+// so only a well-formed hex value is ever emitted.
+const accent = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(THEME.accent) ? THEME.accent : '';
+
+// Pick readable text for the accent using its perceived luminance, so a brand
+// colour can be dropped in without also hand-picking a foreground.
+function accentForeground(hex: string): string {
+  const full = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
+  const value = Number.parseInt(full.slice(1), 16);
+  const r = (value >> 16) & 255;
+  const g = (value >> 8) & 255;
+  const b = value & 255;
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  return luminance > 0.6 ? '#0f1216' : '#ffffff';
+}
+
+const accentCss = accent
+  ? `:root{--ck-accent:${accent};--ck-accent-foreground:${accentForeground(accent)}}`
+  : '';
+---
+
+<!doctype html>
+<html lang={SITE.locale} data-appearance={appearance}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="generator" content={Astro.generator} />
+
+    {
+      /* Every descriptive tag lives in one component, so there is exactly one
+        title, description, canonical and social tag per page. */
+    }
+    <Seo title={title} description={description} noindex={noindex} />
+
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
+    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0b0d10" />
+
+    {structuredData && <StructuredData />}
+    {accentCss && <style is:global set:html={accentCss} />}
+  </head>
+
+  <body>
+    <a href="#main" class="skip-link">Skip to content</a>
+
+    <div class="page-shell" data-measure={measure}>
+      {showHeader && <Header items={nav} />}
+
+      <main id="main" class="flex-1">
+        <slot />
+      </main>
+
+      <Footer />
+    </div>
+
+    <style>
+      .page-shell[data-measure='narrow'] {
+        --ck-measure: 48rem;
+      }
+
+      .skip-link {
+        position: absolute;
+        left: -9999px;
+        top: 0;
+        z-index: 50;
+      }
+
+      .skip-link:focus-visible {
+        left: 1rem;
+        top: 1rem;
+        padding: 0.625rem 1rem;
+        border-radius: var(--radius-md);
+        background-color: var(--color-accent);
+        color: var(--color-accent-foreground);
+        font-size: var(--text-small);
+        font-weight: 500;
+        text-decoration: none;
+      }
+    </style>
+  </body>
+</html>

package/templates/astro-tailwind/base/src/lib/seo.ts

@@ -0,0 +1,87 @@
+/**
+ * Small URL helpers for the site's metadata.
+ *
+ * Deliberately not a general-purpose URL library: it solves exactly what
+ * canonical tags, Open Graph and the sitemap need, and nothing more.
+ */
+
+/**
+ * Returns the site's origin with any trailing slash removed, or '' when no
+ * usable production URL is configured.
+ *
+ * An empty result is the signal used throughout the site to omit absolute
+ * metadata entirely rather than invent a domain.
+ */
+export function siteOrigin(url: string): string {
+  const trimmed = url.trim();
+  if (trimmed === '') return '';
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return '';
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '';
+
+  // Origin only, so there is never a trailing slash to double up on. Astro
+  // resolves absolute routes against the origin, so keeping a path here would
+  // make the canonical tag and the sitemap disagree. Sites deployed under a
+  // subpath need Astro's `base` option too - see the note on SITE.url in
+  // src/config/site.config.ts.
+  return parsed.origin;
+}
+
+/**
+ * Joins a site-relative path onto the configured origin.
+ * Returns '' when there is no origin, so callers can omit the tag entirely.
+ */
+export function absoluteUrl(origin: string, path: string): string {
+  if (origin === '') return '';
+  const suffix = path.startsWith('/') ? path : `/${path}`;
+  // Collapse any accidental double slash in the path portion.
+  return `${origin}${suffix}`.replace(/([^:]\/)\/+/g, '$1');
+}
+
+/**
+ * Resolves a configured asset reference for use in metadata.
+ * Absolute URLs pass through; a site-relative path needs an origin, because
+ * social crawlers reject relative image URLs.
+ */
+export function assetUrl(origin: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === '') return '';
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  return absoluteUrl(origin, trimmed);
+}
+
+/**
+ * The three characters that can end a script element early or open a new tag,
+ * mapped to their JSON unicode escapes.
+ *
+ * Each value must be a six-character sequence starting with a real backslash,
+ * not the character itself. Writing the character instead turns the
+ * replacement below into a silent no-op, which is why `jsonLdScript` is
+ * covered by a test asserting the output contains no bare angle bracket.
+ */
+const JSON_LD_ESCAPES: Readonly<Record<string, string>> = {
+  '<': '\\u003c',
+  '>': '\\u003e',
+  '&': '\\u0026',
+};
+
+/**
+ * Serialises data for a <script type="application/ld+json"> block.
+ *
+ * JSON.stringify alone is not enough: the HTML parser ends a script element at
+ * the first '</script', whatever the JSON quoting says. Escaping '<', '>' and
+ * '&' keeps the payload valid JSON - the escapes decode back to the original
+ * characters when parsed - while making it impossible to close the element or
+ * open a new tag.
+ *
+ * HTML entity escaping must NOT be used here: script content is raw text, so
+ * '&amp;' would survive into the parsed JSON as a literal five-character run.
+ */
+export function jsonLdScript(data: unknown): string {
+  return JSON.stringify(data).replace(/[<>&]/g, (char) => JSON_LD_ESCAPES[char] ?? char);
+}