create-clientkit 0.1.0

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "create-clientkit",
+  "version": "0.1.0",
+  "description": "Create the boring foundation of your next client website in seconds.",
+  "keywords": [
+    "cli",
+    "scaffold",
+    "generator",
+    "client-website",
+    "freelance",
+    "agency",
+    "astro",
+    "starter"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Joseph K Anoj",
+    "email": "josephkanoj@gmail.com",
+    "url": "https://github.com/JosuK22"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "bin": {
+    "create-clientkit": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "third-party": "node scripts/generate-third-party.mjs",
+    "third-party:check": "node scripts/generate-third-party.mjs --check",
+    "check:package": "node scripts/check-package.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:quick": "node scripts/smoke.mjs --quick",
+    "smoke:audit": "node scripts/smoke.mjs --audit",
+    "audit": "node scripts/audit-site.mjs",
+    "preflight": "node scripts/preflight.mjs",
+    "verify": "npm run typecheck && npm run lint && npm run format:check && npm run test && npm run build",
+    "prepublishOnly": "npm run preflight",
+    "cancel-check": "node scripts/cancel-check.mjs",
+    "drift": "node scripts/drift-probe.mjs",
+    "drift:report": "node scripts/drift-probe.mjs --report"
+  },
+  "devDependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.15.0",
+    "axe-core": "^4.13.0",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "lighthouse": "^13.4.1",
+    "picocolors": "^1.1.1",
+    "prettier": "^3.5.3",
+    "prettier-plugin-astro": "^0.14.1",
+    "puppeteer": "^25.10.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^3.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JosuK22/create-clientkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JosuK22/create-clientkit/issues"
+  },
+  "homepage": "https://github.com/JosuK22/create-clientkit#readme"
+}

package/templates/astro-tailwind/base/README.md

@@ -0,0 +1,131 @@
+# {{siteName}}
+
+{{description}}
+
+Scaffolded with [create-clientkit](https://www.npmjs.com/package/create-clientkit).
+This is your code now - edit anything.
+
+## Getting started
+
+```sh
+npm install
+npm run dev
+```
+
+| Script            | What it does                           |
+| ----------------- | -------------------------------------- |
+| `npm run dev`     | Start the dev server                   |
+| `npm run check`   | Type-check `.astro` files and the site |
+| `npm run build`   | Build the production site to `dist/`   |
+| `npm run preview` | Preview the production build           |
+
+## Where to start
+
+1. **`src/config/site.config.ts`** - the single source of truth, and the only
+   file you need for most client changes:
+   - `SITE` - name, description, production URL, locale, author
+   - `NAV` - header links (empty means no menu is rendered at all)
+   - `SOCIAL` - social profiles (empty means no links are rendered)
+   - `CONTACT` - email, phone, location; each is optional
+   - `LAUNCH` - optional launch date and countdown
+   - `THEME` - `appearance` (`system`/`light`/`dark`) and a brand `accent` hex
+   - `SEO` - social preview `image`, `twitterCard`, and `noindex`
+
+   An empty string or empty array means "not set", and the UI omits that piece
+   rather than showing a placeholder. Nothing is ever invented for you.
+
+2. **`src/pages/index.astro`** - the home page.
+3. **`src/pages/404.astro`** - the custom not-found page.
+4. **`src/layouts/BaseLayout.astro`** - the shared shell: `<head>`, skip link,
+   header, footer, and the `measure` prop that sets the page column width.
+5. **`src/components/`** - `Header`, `Footer`, `Brand`, `SocialLinks`,
+   `LaunchNotice`.
+6. **`src/styles/global.css`** - the design system. Tailwind v4 is configured in
+   CSS via `@theme`; there is no `tailwind.config.js`. Colours, type scale,
+   radii, shadows and spacing all live here, and light/dark are one block of
+   custom properties rather than duplicated components.
+7. **`public/favicon.svg`** - replace with the client's mark.
+
+## SEO
+
+Metadata is generated into the static HTML at build time - nothing depends on
+JavaScript, so crawlers and social platforms get the full picture from the
+source.
+
+`src/components/Seo.astro` is the single place that emits `<title>`,
+description, canonical, robots, Open Graph and Twitter tags, and
+`src/layouts/BaseLayout.astro` renders it for every page. A page only passes
+what it needs to override:
+
+```astro
+<BaseLayout title="About" description="Something specific to this page." />
+```
+
+**Everything derives from `SITE`.** You never repeat the site name,
+description or URL.
+
+### Before you have a domain
+
+`SITE.url` starts empty and that is a supported state, not a broken one. While
+it is empty the site omits every absolute tag - canonical, `og:url`, the
+sitemap and the sitemap line in `robots.txt` - rather than pointing them at a
+domain nobody owns yet. Fill `SITE.url` in and they all appear. Only the
+origin is used; a subpath deployment also needs Astro's `base` option.
+
+### Indexing
+
+`SEO.noindex` controls it, and it is `false` by default so a launched site is
+findable. Set it to `true` while a holding page is up if you would rather it
+stayed out of search - and remember to switch it back at launch.
+
+| `SITE.url` | `SEO.noindex` | Result                                                       |
+| ---------- | ------------- | ------------------------------------------------------------ |
+| set        | `false`       | Canonical, `og:url`, sitemap, `Sitemap:` line in robots.txt  |
+| set        | `true`        | `noindex, nofollow`, no canonical, no sitemap, `Disallow: /` |
+| empty      | `false`       | No absolute tags, no sitemap, permissive robots.txt          |
+| empty      | `true`        | No absolute tags, no sitemap, `Disallow: /`                  |
+
+The 404 page is always `noindex, nofollow` and carries no structured data,
+whatever the site setting says.
+
+### Social preview image
+
+`SEO.image` is empty by default, so no `og:image` is emitted at all - better
+than pointing Facebook and X at a file that isn't there. Drop a 1200x630 PNG
+into `public/` and set `image: '/og.png'`.
+
+### Structured data
+
+`src/components/StructuredData.astro` emits a schema.org `Organization` block
+built only from values you have actually configured. No logo, address, rating
+or review is invented - fields you leave empty simply do not appear.
+
+## Design notes
+
+- **Zero client-side JavaScript by default.** The only script in the project is
+  a ~20-line countdown, and it ships only when you set a launch date. Without
+  JavaScript the launch date still renders; only the ticking numbers are lost.
+- **Dark mode needs no JavaScript.** It follows the visitor's system preference,
+  or you can force one via `THEME.appearance`.
+- **Set `THEME.accent`** to the client's brand hex and buttons, focus rings and
+  the background wash all follow. Readable text on the accent is chosen for you.
+- **Motion is opt-out-aware**: entrance animation only runs under
+  `prefers-reduced-motion: no-preference`, so content is never hidden behind an
+  animation that may not play.
+
+## Stack
+
+- [Astro](https://astro.build) 7 - static output, zero client JS by default
+- [Tailwind CSS](https://tailwindcss.com) 4 - loaded through `@tailwindcss/vite`
+- TypeScript in strict mode
+
+Requires Node.js 22.12 or newer.
+
+## Notes
+
+`.client-site.json` records how this project was generated. Leave it in place -
+future `create-clientkit` tooling reads it. It contains no secrets.
+
+This project is private and unlicensed by default (`"private": true`,
+`"license": "UNLICENSED"`), because client work is normally proprietary. Change
+that in `package.json` if the site is meant to be open source.

package/templates/astro-tailwind/base/_gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.ico binary
+*.woff2 binary

package/templates/astro-tailwind/base/_gitignore

@@ -0,0 +1,23 @@
+# build output
+dist/
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment
+.env
+.env.production
+
+# editors and OS
+.vscode/*
+!.vscode/extensions.json
+.idea/
+.DS_Store
+Thumbs.db

package/templates/astro-tailwind/base/_package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": ["astro", "client-site"],
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "check": "astro check",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/sitemap": "3.7.4",
+    "astro": "7.3.2"
+  },
+  "devDependencies": {
+    "@astrojs/check": "0.9.10",
+    "@tailwindcss/vite": "4.3.3",
+    "tailwindcss": "4.3.3",
+    "typescript": "5.9.3"
+  }
+}

package/templates/astro-tailwind/base/astro.config.mjs

@@ -0,0 +1,32 @@
+import { defineConfig } from 'astro/config';
+import sitemap from '@astrojs/sitemap';
+import tailwindcss from '@tailwindcss/vite';
+
+import { SEO, SITE } from './src/config/site.config.ts';
+import { siteOrigin } from './src/lib/seo.ts';
+
+// '' when no production URL is configured. Astro rejects an empty or malformed
+// `site`, and an absolute sitemap cannot exist without a real domain, so both
+// are switched on by the same condition rather than guessing a URL.
+const origin = siteOrigin(SITE.url);
+
+// A site asking not to be indexed should not also publish a sitemap listing
+// every page it wants ignored.
+const wantsSitemap = origin !== '' && !SEO.noindex;
+
+export default defineConfig({
+  ...(origin ? { site: origin } : {}),
+  integrations: [
+    ...(wantsSitemap
+      ? [
+          sitemap({
+            // 404 is a status page, not content to be crawled.
+            filter: (page) => !page.includes('/404'),
+          }),
+        ]
+      : []),
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});

package/templates/astro-tailwind/base/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Site icon">
+  <rect width="64" height="64" rx="14" fill="#0f172a" />
+  <path d="M20 40V24h6.4c4.8 0 7.6 2.7 7.6 7s-2.8 7-7.6 7H20Zm4.4-3.4h1.9c2.6 0 4-1.4 4-3.6s-1.4-3.6-4-3.6h-1.9v7.2Z" fill="#f8fafc" />
+  <circle cx="42" cy="38" r="3" fill="#38bdf8" />
+</svg>

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

@@ -0,0 +1,89 @@
+---
+import { SITE } from '../config/site.config.ts';
+
+interface Props {
+  /** 'sm' for header and footer, 'lg' for a page's own brand lockup. */
+  size?: 'sm' | 'lg';
+  /** Wrap in a link home. Off when the brand already sits on the home page. */
+  href?: string;
+}
+
+const { size = 'sm', href } = Astro.props;
+
+// A compact mark derived from the site name: up to two initials. It is a
+// neutral stand-in until the client's real logo is dropped in.
+const initials = SITE.name
+  .split(/\s+/)
+  .filter((word) => /[a-z0-9]/i.test(word))
+  .slice(0, 2)
+  .map((word) => word[0]?.toUpperCase() ?? '')
+  .join('');
+
+const Tag = href ? 'a' : 'div';
+---
+
+<Tag class:list={['brand', size]} href={href} aria-label={href ? SITE.name : undefined}>
+  <span class="mark" aria-hidden="true">{initials}</span>
+  <span class="name">{SITE.name}</span>
+</Tag>
+
+<style>
+  .brand {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.625rem;
+    color: var(--color-foreground);
+    text-decoration: none;
+    min-width: 0;
+  }
+
+  .mark {
+    display: grid;
+    place-items: center;
+    flex: none;
+    border: 1px solid var(--color-border-strong);
+    border-radius: var(--radius-md);
+    background-color: var(--color-surface);
+    font-weight: 600;
+    letter-spacing: -0.02em;
+  }
+
+  .name {
+    font-weight: 600;
+    letter-spacing: -0.015em;
+    /* Long names truncate in the header rather than pushing the layout apart. */
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .sm .mark {
+    width: 1.875rem;
+    height: 1.875rem;
+    font-size: 0.75rem;
+  }
+
+  .sm .name {
+    font-size: 0.9375rem;
+  }
+
+  .lg {
+    gap: 0.875rem;
+  }
+
+  .lg .mark {
+    width: 2.75rem;
+    height: 2.75rem;
+    font-size: 1rem;
+    border-radius: var(--radius-lg);
+  }
+
+  .lg .name {
+    font-size: 1.0625rem;
+    white-space: normal;
+  }
+
+  a.brand:hover .mark {
+    border-color: var(--color-foreground);
+  }
+</style>

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

@@ -0,0 +1,88 @@
+---
+import SocialLinks from './SocialLinks.astro';
+import { CONTACT, SITE, SOCIAL } from '../config/site.config.ts';
+
+// Computed at build time rather than frozen in at scaffold time, so the notice
+// stays correct for as long as the site is rebuilt.
+const year = new Date().getFullYear();
+
+const hasSocial = SOCIAL.some((link) => link.label !== '' && link.href !== '');
+const hasContact = CONTACT.email !== '' || CONTACT.phone !== '';
+---
+
+<footer class="site-footer">
+  <div class="container-page inner">
+    <p class="copyright">
+      &copy; {year}
+      {SITE.name}
+    </p>
+
+    {
+      (hasContact || hasSocial) && (
+        <div class="links">
+          {CONTACT.email !== '' && (
+            <a href={`mailto:${CONTACT.email}`} class="contact">
+              {CONTACT.email}
+            </a>
+          )}
+          {CONTACT.phone !== '' && (
+            <a href={`tel:${CONTACT.phone.replace(/[^+\d]/g, '')}`} class="contact">
+              {CONTACT.phone}
+            </a>
+          )}
+          {hasSocial && <SocialLinks label="Social links in the footer" />}
+        </div>
+      )
+    }
+  </div>
+</footer>
+
+<style>
+  .site-footer {
+    margin-top: auto;
+    border-top: 1px solid var(--color-border);
+    padding-block: 2rem;
+  }
+
+  .inner {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem 2rem;
+  }
+
+  .copyright {
+    margin: 0;
+    color: var(--color-muted);
+    font-size: var(--text-small);
+  }
+
+  .links {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem 1.25rem;
+  }
+
+  .contact {
+    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;
+  }
+
+  .contact:hover {
+    color: var(--color-foreground);
+  }
+
+  @media (max-width: 40rem) {
+    .inner {
+      flex-direction: column;
+      align-items: flex-start;
+    }
+  }
+</style>

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

@@ -0,0 +1,104 @@
+---
+import Brand from './Brand.astro';
+import type { NavItem } from '../config/site.config.ts';
+
+interface Props {
+  items?: NavItem[];
+}
+
+const { items = [] } = Astro.props;
+const currentPath = Astro.url.pathname;
+const isHome = currentPath === '/' || currentPath === '';
+
+// No links means no menu. A header with an invented nav is worse than none.
+const hasNav = items.length > 0;
+---
+
+<header class="site-header">
+  <div class="container-page inner">
+    <Brand size="sm" href={isHome ? undefined : '/'} />
+
+    {
+      hasNav && (
+        <nav aria-label="Primary">
+          <ul>
+            {items.map((item) => (
+              <li>
+                <a href={item.href} aria-current={item.href === currentPath ? 'page' : undefined}>
+                  {item.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )
+    }
+  </div>
+</header>
+
+<style>
+  .site-header {
+    border-bottom: 1px solid var(--color-border);
+    background-color: color-mix(in oklab, var(--color-background) 88%, transparent);
+    backdrop-filter: saturate(1.4) blur(8px);
+    position: sticky;
+    top: 0;
+    z-index: 20;
+  }
+
+  .inner {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    min-height: 4rem;
+  }
+
+  nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    align-items: center;
+    gap: 0.25rem 1.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  nav a {
+    display: inline-flex;
+    align-items: center;
+    min-height: 2.5rem;
+    padding: 0.25rem 0;
+    color: var(--color-muted);
+    font-size: var(--text-small);
+    font-weight: 500;
+    text-decoration: none;
+    transition: color 160ms ease;
+  }
+
+  nav a:hover,
+  nav a[aria-current='page'] {
+    color: var(--color-foreground);
+  }
+
+  nav a[aria-current='page'] {
+    box-shadow: inset 0 -1px 0 0 var(--color-accent);
+  }
+
+  /* Below 480px the brand keeps the top line to itself and the links wrap
+     underneath, which reads better than squeezing both onto one row. */
+  @media (max-width: 30rem) {
+    .inner {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 0.25rem;
+      padding-block: 0.75rem;
+    }
+
+    nav ul {
+      justify-content: flex-start;
+      gap: 0.25rem 1rem;
+    }
+  }
+</style>