create-ginko 0.4.0 → 0.6.0

package/template-files.mjs

@@ -0,0 +1,377 @@
+// What create-ginko does to the files of a copied template: pick its languages and move its sample dates to today.
+// scripts/templates.ts (the monorepo's template gates and `sync --check`) uses the same functions.
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/** Lockfiles: a template commits none (it installs from the repository root), and a new site makes its own. */
+export const lockfiles = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json']
+/** Build output, installs, secrets, lockfiles and test results: never copied out of a template into a new site. */
+export const notCopied = new Set(['node_modules', '.nuxt', '.output', '.data', '.env', 'test-results', ...lockfiles])
+
+/** File types that `@lupinum/ginko-content` reads and whose top-level keys this module can find (no JSON, no CSV). */
+const textTypes = ['md', 'yml', 'yaml']
+
+/** Task prefills that fill in a week (`@workWeek`, `@nextWorkWeek`): the brick holds a current week, such as lunch. */
+const weekly = (brick) => (brick.tasks ?? []).some((task) => Object.values(task.prefill ?? {}).some((value) => /^@(next)?workWeek$/i.test(String(value))))
+
+/**
+ * What create-ginko needs to know about a template's config, computed in the monorepo (build.mjs), where the config
+ * can be imported: its locales, and per brick the date fields to move. A brick's dates move when the brick hides
+ * entries after a date (`visible: { mode: 'until' }`), shows the next date on the Studio's Today page
+ * (`status: { next }`) or has a weekly task (the lunch week's `weekOf`), and for the `sessions` brick. Other dates
+ * (a post's date, holidays, a changelog) stay.
+ */
+export function manifestOf(site) {
+  const shift = {}
+  for (const [key, brick] of Object.entries(site.bricks)) {
+    const timed = brick.visible?.mode === 'until' || brick.status?.next !== undefined || weekly(brick) || key === 'sessions'
+    if (!timed) continue
+    const fields = Object.entries(brick.fields).filter(([, field]) => field.type === 'date' || field.type === 'daterange').map(([name]) => name)
+    if (fields.length) shift[key] = fields
+  }
+  return { locales: [...site.locales], shift }
+}
+
+const day = 24 * 60 * 60 * 1000
+const isoDay = (time) => new Date(time).toISOString().slice(0, 10)
+const timeOf = (iso) => Date.parse(`${iso}T00:00:00Z`)
+
+/** Days from `anchor` to `today` (both `YYYY-MM-DD`), rounded towards zero to whole weeks, so weekdays stay. */
+export function weeksShift(anchor, today) {
+  return Math.trunc((timeOf(today) - timeOf(anchor)) / day / 7) * 7
+}
+
+export const addDays = (iso, days) => isoDay(timeOf(iso) + days * day)
+
+/** The content files of one brick: `content/<brick>.<ext>` (a single, with translations) and all files below `content/<brick>/`. */
+function brickFiles(dir, brick) {
+  const content = join(dir, 'content')
+  if (!existsSync(content)) return []
+  const files = readdirSync(content).filter((name) => name.split('.')[0] === brick && textTypes.includes(name.split('.').at(-1))).map((name) => join(content, name))
+  const folder = join(content, brick)
+  if (existsSync(folder) && statSync(folder).isDirectory()) {
+    for (const name of readdirSync(folder, { recursive: true })) {
+      const path = join(folder, String(name))
+      if (textTypes.includes(path.split('.').at(-1)) && statSync(path).isFile()) files.push(path)
+    }
+  }
+  return files
+}
+
+const DATE = /\b(\d{4}-\d{2}-\d{2})\b/g
+
+/**
+ * Calls `edit` on the lines of the given top-level keys: a Markdown file's frontmatter or a whole YAML file. A key's
+ * value is its own line plus the indented lines below it (`when:` with `from:` and `to:`). The Markdown body is never
+ * touched, so a date in running text stays as written.
+ */
+function editFields(text, isMarkdown, fields, edit) {
+  const lines = text.split('\n')
+  let start = 0
+  let end = lines.length
+  if (isMarkdown) {
+    if (lines[0]?.trim() !== '---') return text
+    start = 1
+    end = lines.findIndex((line, i) => i > 0 && line.trim() === '---')
+    if (end < 0) return text
+  }
+  let inField = false
+  for (let i = start; i < end; i++) {
+    const line = lines[i]
+    if (/^\S/.test(line)) inField = fields.some((field) => line.startsWith(`${field}:`))
+    if (inField) lines[i] = edit(line)
+  }
+  return lines.join('\n')
+}
+
+/** Moves every date of the manifest's fields by `days`. Returns the content files it changed (relative paths). */
+export function shiftDates(dir, shift, days) {
+  const changed = []
+  if (!days) return changed
+  for (const [brick, fields] of Object.entries(shift)) {
+    for (const path of brickFiles(dir, brick)) {
+      const text = readFileSync(path, 'utf8')
+      const next = editFields(text, path.endsWith('.md'), fields, (line) => line.replace(DATE, (iso) => addDays(iso, days)))
+      if (next !== text) {
+        writeFileSync(path, next)
+        changed.push(relative(dir, path))
+      }
+    }
+  }
+  return changed
+}
+
+/** Every date in the manifest's fields, for the check that a template still has enough future samples. */
+export function sampleDates(dir, shift) {
+  const dates = []
+  for (const [brick, fields] of Object.entries(shift)) {
+    for (const path of brickFiles(dir, brick)) {
+      editFields(readFileSync(path, 'utf8'), path.endsWith('.md'), fields, (line) => {
+        dates.push(...(line.match(DATE) ?? []))
+        return line
+      })
+    }
+  }
+  return dates.sort()
+}
+
+/** Removes `<locale>: '…'` entries (one-line string values) from the object literals of a source fragment. */
+function pruneMaps(source, locale) {
+  const key = `(?<q>['"]?)${locale}\\k<q>\\s*:\\s*(?:'[^'\\n]*'|"[^"\\n]*")`
+  return source
+    // a later entry, with the comma before it: `{ en: '/a', de: '/b' }`, or `'/a',\n  de: '/b',`
+    .replace(new RegExp(`\\s*,\\s*${key}(?=\\s*[,}\\n])`, 'g'), '')
+    // the first entry, with the comma after it: `{ de: '/b', en: '/a' }`
+    .replace(new RegExp(`(\\{\\s*)${key}\\s*,\\s*`, 'g'), '$1')
+    // the only entry
+    .replace(new RegExp(`\\{\\s*${key}\\s*\\}`, 'g'), '{}')
+}
+
+/**
+ * Applies pruneMaps only inside the locale maps of ginko.config.ts: the object after `languages:`, `route:` and
+ * `pages:` (whose values are paths or path maps). Other objects there, such as a field label `{ de: '…', en: '…' }`
+ * in the Studio's languages, stay whole.
+ */
+function pruneConfigMaps(source, locale) {
+  let out = ''
+  let from = 0
+  for (const match of source.matchAll(/\b(?:languages|route|pages)\s*:\s*\{/g)) {
+    const open = match.index + match[0].length - 1
+    if (open < from) continue
+    let depth = 0
+    let close = open
+    for (; close < source.length; close++) {
+      if (source[close] === '{') depth++
+      else if (source[close] === '}' && --depth === 0) break
+    }
+    out += source.slice(from, open) + pruneMaps(source.slice(open, close + 1), locale)
+    from = close + 1
+  }
+  return out + source.slice(from)
+}
+
+/** The top-level keys of a Markdown frontmatter or YAML file, each with its lines (a key's own line and the indented
+ *  lines below it); lines before the first key form a block without key. Undefined for other files. */
+function fieldBlocks(text, isMarkdown) {
+  const lines = text.split('\n')
+  let start = 0
+  let end = lines.length
+  if (isMarkdown) {
+    // No frontmatter: no fields yet. Fields it gets (the main-only ones of a main-language swap) open a frontmatter.
+    if (lines[0]?.trim() !== '---') return { blocks: [], join: (list) => (list.length ? ['---', ...list.flatMap((b) => b.lines), '---', '', ...lines] : lines).join('\n') }
+    start = 1
+    end = lines.findIndex((line, i) => i > 0 && line.trim() === '---')
+    if (end < 0) return undefined
+  }
+  const blocks = []
+  for (let i = start; i < end; i++) {
+    const key = /^([^\s#:-][^:]*):/.exec(lines[i])?.[1]
+    if (key !== undefined || !blocks.length) blocks.push({ key, lines: [lines[i]] })
+    else blocks.at(-1).lines.push(lines[i])
+  }
+  const join = (list) => [...lines.slice(0, start), ...list.flatMap((b) => b.lines), ...lines.slice(end)].join('\n')
+  return { blocks, join }
+}
+
+// A small reader and writer for the nested values of a frontmatter field: maps (`key: value`, `key:` with indented
+// lines), lists (`- ` items, a map item starts on the dash line) and scalars kept as written (quotes, `[A, C]`, block
+// text with `|` or `>`). Enough for content files, which tools and people write in this plain form.
+const indentOf = (line) => line.length - line.trimStart().length
+const isList = (line) => /^\s*-(\s|$)/.test(line)
+const isBlank = (line) => line.trim() === '' || line.trim().startsWith('#')
+
+function readNested(lines) {
+  const rows = [...lines]
+  let i = 0
+  const skip = () => { while (i < rows.length && isBlank(rows[i])) i++ }
+  const value = () => {
+    skip()
+    if (i >= rows.length) return { raw: '' }
+    return isList(rows[i]) ? list(indentOf(rows[i])) : map(indentOf(rows[i]))
+  }
+  const map = (indent) => {
+    const out = new Map()
+    for (skip(); i < rows.length && indentOf(rows[i]) === indent && !isList(rows[i]); skip()) {
+      const match = /^\s*([^:#\s][^:]*):(?:\s(.*))?$/.exec(rows[i])
+      if (!match) throw new Error(`Cannot read the line "${rows[i].trim()}"`)
+      i++
+      const raw = (match[2] ?? '').trim()
+      if (/^[|>]/.test(raw)) {
+        const text = []
+        while (i < rows.length && (rows[i].trim() === '' || indentOf(rows[i]) > indent)) text.push(rows[i++])
+        out.set(match[1], { raw, text })
+      }
+      else if (raw) out.set(match[1], { raw })
+      else {
+        skip()
+        const nested = i < rows.length && (indentOf(rows[i]) > indent || (indentOf(rows[i]) === indent && isList(rows[i])))
+        out.set(match[1], nested ? value() : { raw: '' })
+      }
+    }
+    return out
+  }
+  const list = (indent) => {
+    const out = []
+    for (skip(); i < rows.length && indentOf(rows[i]) === indent && isList(rows[i]); skip()) {
+      const rest = rows[i].slice(indent + 1).trimStart()
+      if (/^[^:#\s'"[{][^:]*:(\s|$)/.test(rest)) {
+        // A map item: read its first key as if it stood on its own line, aligned with the keys below it.
+        rows[i] = `${' '.repeat(indent + 2)}${rest}`
+        out.push(map(indent + 2))
+      }
+      else {
+        i++
+        out.push({ raw: rest })
+      }
+    }
+    return out
+  }
+  return value()
+}
+
+function writeNested(value, indent) {
+  const pad = ' '.repeat(indent)
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => {
+      if (!(item instanceof Map) && !Array.isArray(item)) return [`${pad}- ${item.raw}`]
+      const lines = writeNested(item, indent + 2)
+      return [`${pad}- ${lines[0].slice(indent + 2)}`, ...lines.slice(1)]
+    })
+  }
+  return [...value].flatMap(([key, v]) => {
+    if (v instanceof Map || Array.isArray(v)) return [`${pad}${key}:`, ...writeNested(v, indent + 2)]
+    return [`${pad}${key}:${v.raw ? ` ${v.raw}` : ''}`, ...(v.text ?? [])]
+  })
+}
+
+const nested = (v) => v instanceof Map || Array.isArray(v)
+
+/** The main value with the translation's texts in it: maps by key, lists by position. */
+function overlay(main, translated) {
+  if (Array.isArray(main) && Array.isArray(translated)) return main.map((item, i) => (i < translated.length ? overlay(item, translated[i]) : item))
+  if (main instanceof Map && translated instanceof Map) {
+    const out = new Map([...main].map(([key, v]) => [key, translated.has(key) ? overlay(v, translated.get(key)) : v]))
+    for (const [key, v] of translated) if (!out.has(key)) out.set(key, v)
+    return out
+  }
+  return translated
+}
+
+/** The main value cut to the shape of the translation: the main language's texts for the new translation file. */
+function project(main, translated) {
+  if (Array.isArray(translated)) return translated.map((item, i) => project(Array.isArray(main) ? main[i] : undefined, item))
+  if (translated instanceof Map) {
+    const out = new Map()
+    for (const [key, v] of translated) {
+      const own = main instanceof Map ? project(main.get(key), v) : undefined
+      if (own !== undefined) out.set(key, own)
+    }
+    return out
+  }
+  return main === undefined || nested(main) ? undefined : main
+}
+
+/**
+ * A field that both files have and whose value is nested: the two blocks after the swap, or undefined. A field the
+ * small reader cannot read stops the copy with the file and field named: swapped as a whole, a nested field would lose
+ * its photo or prices in the new main file and fail the build later, far from the cause.
+ */
+function swapNested(mainBlock, translatedBlock, name) {
+  if (mainBlock.lines.length < 2 && translatedBlock.lines.length < 2) return undefined
+  const key = mainBlock.key
+  let main, translated
+  try {
+    [main, translated] = [mainBlock, translatedBlock].map((block) => readNested(block.lines))
+  }
+  catch (error) {
+    throw new Error(`content/${name}: cannot swap the field "${key}" for the new main language (${error.message}). Write it in plain YAML (one "key: value" per line, lists with "- "), or copy the template with its own main language.`)
+  }
+  const [m, t] = [main.get(key), translated.get(translatedBlock.key)]
+  if (!nested(m) || !nested(t)) return undefined
+  return {
+    main: { key, lines: writeNested(new Map([[key, project(m, t)]]), 0) },
+    translated: { key, lines: writeNested(new Map([[key, overlay(m, t)]]), 0) },
+  }
+}
+
+/**
+ * The texts of a main file and its translation after they swap roles (a new main language). Fields only the main file
+ * has (the language-independent ones, such as a date or a choice, which a translation must not repeat, and any field
+ * the translation left to the main text) move to the new main file, so both pages show what they showed before. A
+ * nested field both have (a photo with its alt text, a list of days with their dishes) is merged inside: the new main
+ * file gets the whole value with the translated texts, the new translation only the texts. When the translation sets
+ * its own `slug`, the old main file keeps its address from the file name as `slug`.
+ */
+function swapFields(mainText, translatedText, name) {
+  const isMarkdown = name.endsWith('.md')
+  const main = fieldBlocks(mainText, isMarkdown)
+  const translated = fieldBlocks(translatedText, isMarkdown)
+  if (!textTypes.includes(name.split('.').at(-1)) || !main || !translated) return [mainText, translatedText]
+  const own = new Set(translated.blocks.map((b) => b.key))
+  const moved = main.blocks.filter((b) => b.key !== undefined && !own.has(b.key))
+  let kept = main.blocks.filter((b) => !moved.includes(b))
+  let theirs = translated.blocks
+  for (const block of theirs) {
+    const mine = block.key === undefined ? undefined : kept.find((b) => b.key === block.key)
+    const swapped = mine && swapNested(mine, block, name)
+    if (!swapped) continue
+    kept = kept.map((b) => (b === mine ? swapped.main : b))
+    theirs = theirs.map((b) => (b === block ? swapped.translated : b))
+  }
+  if (own.has('slug') && !main.blocks.some((b) => b.key === 'slug')) {
+    kept.push({ key: 'slug', lines: [`slug: ${name.split('/').at(-1).split('.').at(-2)}`] })
+  }
+  return [main.join(kept), translated.join([...theirs, ...moved])]
+}
+
+/** The locale suffix of a content path (`1.about.de.md` → `de`), if it is one of `locales`. */
+function suffixOf(name, locales) {
+  const parts = name.split('.')
+  return parts.length > 2 && locales.includes(parts.at(-2)) ? parts.at(-2) : undefined
+}
+const withSuffix = (path, locale) => path.replace(/(\.[^./]+)$/, `.${locale}$1`)
+
+/**
+ * Keeps the languages `chosen` (a subset of the template's `authored` locales; the first is the new main language) and
+ * removes the others: their content files, `i18n/<locale>.json`, and their entries in the locale maps: every map
+ * in `app/routes.ts`, and `languages`, `route` and `pages` in `ginko.config.ts`. The `locales` list there (in `app/routes.ts` if it exists, else in
+ * `ginko.config.ts`) becomes `chosen`. When the main language changes, the main files (no suffix) and the new main
+ * language's files (`.<locale>.md`) swap names; a file without a translation stays as it is.
+ * Contract for templates: URL prefixes derive from the locales list in code, so the swap needs no route edits, and
+ * `app/routes.ts` holds only locale maps (route slugs), no other object keyed by a language code.
+ */
+export function pruneLocales(dir, authored, chosen) {
+  const unknown = chosen.filter((locale) => !authored.includes(locale))
+  if (unknown.length) throw new Error(`Unknown locale ${unknown.map((l) => `"${l}"`).join(', ')}. This template has: ${authored.join(', ')}.`)
+  const dropped = authored.filter((locale) => !chosen.includes(locale))
+  const [main] = chosen
+  const [authoredMain] = authored
+  const content = join(dir, 'content')
+  const files = existsSync(content) ? readdirSync(content, { recursive: true }).map(String).filter((name) => statSync(join(content, name)).isFile()) : []
+  for (const name of files) {
+    if (dropped.includes(suffixOf(name, authored))) rmSync(join(content, name))
+  }
+  if (main !== authoredMain) {
+    for (const name of files) {
+      if (suffixOf(name, authored) || !existsSync(join(content, name))) continue
+      const translation = join(content, withSuffix(name, main))
+      if (!existsSync(translation)) continue
+      const [mainText, translated] = swapFields(readFileSync(join(content, name), 'utf8'), readFileSync(translation, 'utf8'), name)
+      writeFileSync(join(content, name), mainText)
+      writeFileSync(translation, translated)
+      if (chosen.includes(authoredMain)) renameSync(join(content, name), join(content, withSuffix(name, authoredMain)))
+      else rmSync(join(content, name))
+      renameSync(translation, join(content, name))
+    }
+  }
+  for (const locale of dropped) rmSync(join(dir, 'i18n', `${locale}.json`), { force: true })
+  const sources = ['app/routes.ts', 'ginko.config.ts'].map((file) => join(dir, file)).filter((path) => existsSync(path))
+  const list = sources.find((path) => /\blocales\s*[:=]\s*\[/.test(readFileSync(path, 'utf8')))
+  if (!list) throw new Error('The template names no locales list (`locales: [...]` or `const locales = [...]`) in app/routes.ts or ginko.config.ts.')
+  for (const path of sources) {
+    let source = readFileSync(path, 'utf8')
+    for (const locale of dropped) source = path.endsWith('routes.ts') ? pruneMaps(source, locale) : pruneConfigMaps(source, locale)
+    if (path === list) source = source.replace(/(\blocales\s*[:=]\s*\[)[^\]]*(\])/, (_, open, close) => `${open}${chosen.map((l) => `'${l}'`).join(', ')}${close}`)
+    writeFileSync(path, source)
+  }
+}

package/templates/blog/.env.example

@@ -0,0 +1,8 @@
+# Copy this file to .env for `nuxt dev` and `nuxt preview`, and set the same variables where the site runs.
+
+# Signs the URLs of the share cards (nuxt-og-image). Any 32 or more random characters (`openssl rand -hex 32`).
+NUXT_APP_SECRET=
+
+# The address of the live site, for canonical links, the sitemap and share cards. A build on Vercel stops
+# while it is still example.com; other builds print a warning. On Vercel, the production address is used when this is empty.
+NUXT_PUBLIC_SITE_URL=

package/templates/blog/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+# Lint, type-check and build on every push and pull request.
+# To use pnpm instead of npm: commit a pnpm-lock.yaml, add `- run: corepack enable pnpm` before the install step,
+# and replace `npm install` with `pnpm install --frozen-lockfile` and `npm run` with `pnpm run`.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 24
+      - run: npm install
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run build

package/templates/blog/DESIGN.md

@@ -0,0 +1,197 @@
+# Design system
+
+The rules behind this site's look. Read them before you change colours, type or components, so the site stays
+consistent and accessible (WCAG 2.2 AA, light and dark). The same system runs every Ginko template; only the accent
+and the fonts differ.
+
+## Principles
+
+- A quiet, neutral base; your content and photos carry the character. One accent colour.
+- Hierarchy from size and weight, not colour. One primary button per view. No gradients, glass, blur or decorative
+  shadows. Separate with a 1px border or a background, never both.
+- Phone first. Every page works at 320 px wide with no horizontal scroll; touch targets are at least 44 px.
+- Only tokens. Tailwind's default palette, type scale, radii and shadows are switched off, so `bg-red-500` or
+  `text-2xl` do nothing. A new value is a new token in the CSS and a row in this file, in the same change.
+
+## Where things live
+
+| What | File |
+|---|---|
+| Your accent and fonts | `app/assets/css/main.css` (`--brand`, `--brand-foreground`, `--font-body`, optional `--font-heading`); the light accent again as `seo.color` in `ginko.config.ts` (share cards) |
+| Neutral colours, type scale, spacing, radii, shadow, focus, motion | `app/assets/css/tokens.css` (shared by all templates; do not edit) |
+| Name, logo, navigation, footer links, profiles | `app/app.config.ts` |
+| Components | `app/components/ui/` (shadcn-vue), `app/components/site/`, `app/components/block/` |
+
+`tokens.css` and the components are copied from the Ginko repository (`templates/_features/`). You can change them in
+your own site; in the Ginko repository, change the source there instead.
+
+## Colours
+
+shadcn names, so shadcn-vue components work unchanged. Light / dark:
+
+| Token | Light | Dark | Use |
+|---|---|---|---|
+| `--background` | `#ffffff` | `#0b0b0c` | page |
+| `--foreground` | `#18181b` | `#f4f4f5` | text (17.7:1 / 17.0:1) |
+| `--muted` | `#f4f4f5` | `#18181b` | footer, notice bar, image placeholders |
+| `--muted-foreground` | `#52525b` | `#a1a1aa` | secondary text (7.7:1 / 7.9:1) |
+| `--accent` | `#f4f4f5` | `#27272a` | hover of quiet controls |
+| `--border` | `#e4e4e7` | `#27272a` | dividers, never text |
+| `--input` | `#8a8a93` | `#71717a` | borders of controls (3:1 non-text) |
+| `--primary` | `--brand` | `--brand` | primary button, links in text, focus ring |
+| `--primary-foreground` | `--brand-foreground` | `--brand-foreground` | text on the accent |
+| `--ring` | = `--primary` | = `--primary` | focus |
+| `--success` / `--warning` / `--destructive` | `#15803d` / `#a16207` / `#b42318` | `#4ade80` / `#facc15` / `#f87171` | status text, always with an icon or a word |
+| `--scrim` | zinc-950 at 60 % | black at 72 % | behind the nav sheet and dialogs; the lightbox is opaque dark `--background`, so no page text shows behind a photo |
+
+**Your accent.** `--brand` and `--brand-foreground` in `main.css`, once in `:root` (light) and once in `.dark`. The
+values and their contrast are written next to them. Rules: text on the accent ≥ 4.5:1; the accent on the background
+≥ 4.5:1 in both modes, because links in text use it; in dark mode use a light tint of the accent. Set the light value
+as `seo.color` in `ginko.config.ts` too: it fills the share cards. The accents of the Ginko templates:
+
+| Template | Light | Text on it | Dark | Text on it | Headings |
+|---|---|---|---|---|---|
+| starter | `#18181b` | `#ffffff` | `#f4f4f5` | `#18181b` | Inter |
+| blog | `#4f46e5` | `#ffffff` | `#a5b4fc` | `#1e1b4b` | Inter |
+| portfolio | `#1c1917` | `#ffffff` | `#f5f5f4` | `#1c1917` | Instrument Serif, `text-h3` 22–28 px |
+| company | `#0369a1` | `#ffffff` | `#7dd3fc` | `#082f49` | Inter |
+| saas | `#6d28d9` | `#ffffff` | `#c4b5fd` | `#2e1065` | Inter |
+| restaurant | `#c2410c` | `#ffffff` | `#fdba74` | `#431407` | Fraunces |
+| local-business | `#0f766e` | `#ffffff` | `#5eead4` | `#042f2e` | Inter |
+| nonprofit | `#15803d` | `#ffffff` | `#86efac` | `#052e16` | Inter |
+| events | `#be123c` | `#ffffff` | `#fda4af` | `#4c0519` | Inter |
+
+`.surface-primary` turns a band into the accent colour and swaps text, buttons and the focus ring, so everything in
+it keeps its contrast (used by `BlockCta`). A template may give the band its own colour with `--brand-surface` and
+`--brand-surface-foreground` in `main.css` (text on it ≥ 4.5:1). Use it in `.dark` when the dark accent is a light
+tint: a full-width band of it is the loudest surface on a near-black page. nonprofit: `#14532d` with `#f0fdf4`
+(8.7:1) in dark mode; buttons and links keep `#86efac`.
+
+Dark mode: `@nuxtjs/color-mode` puts `.dark` on `<html>` (first visit: the system setting); `dark:` utilities and
+`color-scheme` follow it. Printing always uses the light neutrals (paper is white). The navigation, notices, controls and closing band are left
+out (`print:hidden`); the footer prints only the name, address, email and phone, so any page prints as its content
+with whose it is.
+
+## Type
+
+Inter (variable, latin and latin-ext) through `@nuxt/fonts`, served from the site itself. A display face for headings
+is optional (`--font-heading`); a narrow one may set `--text-h3` larger in an `@theme` block of `main.css`, so titles
+still lead the body text (the portfolio). Right-to-left languages add their own face on `:lang(…)`.
+
+| Utility | Size | Line height |
+|---|---|---|
+| `text-h1` | `clamp(2.25rem, 1.5rem + 3.2vw, 4rem)` | 1.05, tracking −0.025em; one per page |
+| `text-h2` | `clamp(1.75rem, 1.35rem + 1.7vw, 2.75rem)` | 1.1, tracking −0.02em; sentences such as the `BlockCta` title |
+| `text-h3` | `clamp(1.2rem, 1.1rem + 0.45vw, 1.45rem)` | 1.3; section labels and `##` in Markdown |
+| `text-lead` | `clamp(1.125rem, 1.06rem + 0.3vw, 1.3125rem)` | 1.5 |
+| `text-body` | `1.0625rem` | 1.6 |
+| `text-small` | `0.9375rem` | 1.5 |
+| `text-xs` | `0.8125rem` | 1.4; the smallest size |
+
+Headings balance their lines and hyphenate (the page sets `lang`). Prices, times and dates use `tabular-nums`
+(`<time>` gets it by default). Text runs at most `max-w-prose` (43.5rem, about 65 characters of body text; in rem so the line width does not
+change when the web font replaces its fallback).
+
+## Space, size, radius, shadow
+
+| Token | Value | Use |
+|---|---|---|
+| `pt-section` (`--spacing-section`) | `clamp(3.5rem, 2.25rem + 5.5vw, 7rem)` | space above each section |
+| `px-gutter` (`--spacing-gutter`) | `clamp(1rem, 0.5rem + 2.4vw, 2rem)` | page edges (16 px on phones) |
+| `max-w-page` | `76rem` | page width |
+| `max-w-prose` | `43.5rem` | text width (about 65 characters) |
+| `rounded-md` (`--radius`) | `0.625rem` | buttons, controls |
+| `rounded-block` | `1rem` | images, cards, the CTA band |
+| `shadow-overlay` | one soft shadow | nav sheet, dialog, menus; nothing else |
+
+Tailwind's spacing steps (`p-4`, `gap-6`) stay available.
+
+## Focus and motion
+
+Every interactive element shows a 2px ring in `--ring`, 3px away (`:focus-visible` in `tokens.css`); components do
+not draw their own. Motion only for a change of state: 150 ms for colours, 200–300 ms for the sheet, accordion and
+dialog, `ease-out`. With `prefers-reduced-motion`, transitions and animations are switched off.
+
+## Components
+
+`app/components/ui/`: shadcn-vue components, copied with the shadcn-vue CLI and trimmed to these:
+
+| Component | Variants |
+|---|---|
+| `Button` | shadcn-vue's names: `default` (the main action), `outline`, `secondary`, `destructive`, `ghost`, `link`; sizes `default` (44 px), `sm` (36 px with a mouse, 44 px on touch), `lg` (48 px), `icon` (44 px), `icon-sm`, `icon-lg` |
+| `Sheet` | `side="start"` (default) or `end`: logical sides, so it opens from the right in right-to-left languages |
+| `Accordion` | as in shadcn-vue, on these tokens; only in templates with questions and answers (`BlockFaq`) |
+
+Nothing else until a feature needs it. To add one: `npx shadcn-vue@latest add <name>`, then:
+
+1. Change `import { cn } from 'cn'` to `import { cn } from '@/lib/utils'` and remove the `cn` package the CLI adds.
+2. Replace Tailwind default classes (`text-sm`, `shadow-lg`, `rounded-lg`, `bg-black/80`) with the tokens above. In
+   the browser they give no error, they just do nothing.
+3. Run `npm run lint` and `npm run typecheck`, and look at the component in light and dark. Lint fails on every class
+   the theme does not have (`eslint.tailwind.mjs`, which reads `main.css`). A class that is on purpose not Tailwind
+   (a hook for plain CSS) goes into the explicit list at the top of that file, with a comment saying why.
+
+Icons come from `@lucide/vue` (what the CLI installs; `lucide-vue-next` is deprecated).
+
+`cn` (`app/lib/utils.ts`) joins classes and resolves conflicts with tailwind-merge, as in shadcn: a
+`class="text-small"` on a component that sets `text-h3` wins. tailwind-merge is configured for the theme of
+tokens.css (`text-small`, `p-gutter`, `max-w-page`, `rounded-block`…); a new token in `@theme` gets its line there too.
+
+`app/components/site/`: `SiteHeader` (name or logo, up to 6 links, language switch, theme toggle; the links move into
+`SiteNavSheet` below `md`, or below `xl` when there are more than 4), `SiteFooter`, `SiteSkipLink`, `SiteLogo`,
+`SiteNavLink`, `SiteThemeToggle`, `SiteLanguageSwitch` (the same page in each language), `SiteNotice` (up to two
+notices above the header).
+
+`app/components/block/` and two more:
+
+| Component | Use |
+|---|---|
+| `BlockHero` | home only: the page's h1, a lead, one primary and one secondary action, an optional photo (16:9) |
+| `BlockPageHeader` | every other page: h1, lead, optional meta line |
+| `BlockSection` | a short label as heading (`text-h3`, the size of a Markdown `##`), optional lead, content; from `lg` heading 4 and content 8 of 12 columns, or full width |
+| `BlockCards` | 2–4 per row; the whole card is one link; photos 3:2 |
+| `BlockFeatures` | 2–6 items divided by lines, no cards |
+| `BlockCta` | a closing band on the accent; one per page, not on legal, contact or error pages |
+| `BlockEmpty` | an empty list: what to add, and where (`content/…`) |
+| `ProseBody` | a Markdown body (headings start at `##`); with `@lupinum/ginko-components` installed, its components too |
+| `InitialsAvatar` | a person without a photo: initials, never a stock face |
+
+## Page patterns
+
+- Home starts with `BlockHero`; other pages with `BlockPageHeader`.
+- Section titles are short labels without a full stop; hero and CTA titles are sentences.
+- Lists show the date or status a visitor needs, in tabular numbers.
+- Every image has a real width, height and alt text, and a fixed ratio per block, so nothing jumps while loading.
+- Right-to-left: only logical utilities (`ms-`, `pe-`, `start-`, `text-start`); arrows get `rtl:-scale-x-100`.
+
+## Patterns of the features
+
+In templates that have these features (`templates/_features/` in the Ginko repository):
+
+- **Open now** (`hours`): `HoursToday` says open or closed in words, the dot only repeats it. It stands above the h1 on
+  the home page, under the call and email buttons on a page for getting in touch, and at the top of the footer's
+  contact column on every page (`app/components/site/FooterStatus.vue`). Opening times never break inside a span:
+  a narrow screen breaks between "11:30–14:00 and" and "17:30–22:00".
+- **Where** (home): one quiet line under the hero's actions: a pin icon, the address, and an "Open in maps" link
+  (`text-small`, muted, the link at least 44 px tall). No embedded map.
+- **Getting in touch** (a reservations page): right under `BlockPageHeader`, one primary button (call) and one
+  secondary (email), `size="lg"`, full width below `sm`; the open-now line under them; text and the opening hours
+  below.
+- **A long list** (the menu): under the header, a row of links to its sections (`text-small`, accent, at least 44 px
+  tall), so a phone reaches the desserts in one tap; each section has an `id`.
+- **Reading** (`blog`): a post's date and reading time in one muted line under the lead, the authors with their
+  initials under it; tags as quiet bordered links (at least 44 px tall) after the text; the older and the newer post
+  as two bordered links side by side (stacked on phones). In a Markdown text, a photo's caption is an emphasised line
+  right under the image (`![Alt text](./photo.jpg)`, then `*The caption*` on the next line); long lines in code
+  blocks wrap.
+- **Photos on phones** (`gallery`): one column at full width, each photo 3:2; justified rows from `sm`.
+
+## Do and don't
+
+| Do | Don't |
+|---|---|
+| `text-muted-foreground` for secondary text | pick a grey by hand |
+| add a token to the CSS and this file | arbitrary values (`p-[13px]`, `bg-[#…]`) |
+| one primary button per view, one CTA band per page | the accent behind body text |
+| status with a word or an icon, plus colour | colour alone |
+| initials for people without a photo | stock faces for named people |

package/templates/blog/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Lupinum OG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.