Documentation

This page is the curated overview. The single source of truth lives in the repository: SKILL.md (machine-readable reference with all rules and recipes) and the README. Whenever this page and the repo disagree, the repo wins.

Quick start

# Scaffold a new project from the template
npm create astro@latest my-site -- --template JUNGHERZ/GlassKit-Web
cd my-site && npm install

npm run dev      # develop
npm run build    # build to dist/
npm test         # Playwright smoke suite (builds + previews itself)

Alternatively use “Use this template” on GitHub. First steps in a derived project: delete site/ (this product page), set base in astro.config.mjs to your repo name — or remove it for a custom domain and add public/CNAME. Deployment ships as a GitHub Actions workflow; set Pages Source to “GitHub Actions” once.

Architecture

Two layers, two references:

The files you touch when deriving a project:

• src/data/site.ts — site name, titles, contact-form endpoint, languages, and the href() helper every link goes through.
• src/components/*.astro — one file per section; the copy lives next to its markup.
• src/styles/brand.css — the only place for client colors (token overrides, loads last).
• src/pages/index.astro — composes the one-pager from the section catalog.

Section catalog

Compose src/pages/index.astro from these sections and delete what the project doesn’t need. Demo links jump straight into the live page.

Full notes per section (arrays, opt-in flags, accessibility rules): SKILL.md §2.

Branding

Client colors never touch glasskit.css or the glw- rules. src/styles/brand.css is the single place for brand overrides — one :root block of token values that loads last and therefore wins against both themes:

:root {
  --gl-primary: #7c5cff;
  --gl-primary-2: #4d34d8;
  /* … more --gl-* tokens; commented example themes ship in the file */
}

Opt-ins

• Blog — Markdown posts via content collection, overview page, RSS feed. Only ship it for clients who will publish; exact removal steps in SKILL.md §3.
• Multilingual (DE/EN) — language branches: the default language lives at the root, each additional one under /<code>/ with its own pages and components, same slugs everywhere. hreflang, sitemap alternates and the switcher derive automatically. Details in SKILL.md §3b.
• Contact form providers — the same form POST works against an n8n webhook, Web3Forms or Formspree; configured in site.ts, empty endpoint = demo mode. Provider matrix in SKILL.md §4b.

Recipes

Three step-by-step recipes cover the whole lifecycle — summarized here, executable in SKILL.md:

• New website from the template — base/site.ts, choose the hero variant, replace copy, pick sections, legal pages, verify with the smoke suite. SKILL.md §5
• Convert an existing website — map old content blocks to catalog sections, migrate copy without porting old CSS. SKILL.md §6
• Pull template updates into a derived project — template as second git remote, work through the CHANGELOG since the last sync, take mechanics files wholesale and bump GlassKit in the same pass — npm run check then names the remaining manual fixes; never overwrite project copy. SKILL.md §7

AI workflow

The template is built to be derived by AI assistants: hand the repo URL to Claude Code, Cursor & Co. and point them at SKILL.md — it contains the catalog, the rules and the recipes in machine-readable form (“build the new site following this scheme”). The deployed demo additionally serves llms.txt, and derived projects generate their own from their content.

The ready-made prompt

Works the same in Claude Code, Cursor, VS Code / Copilot or a plain chat — copy, fill in the placeholders, done:

Build a new website based on the GlassKit Web template:
https://github.com/JUNGHERZ/GlassKit-Web

First read the SKILL.md in that repo, then follow its recipe §5
("New Website From This Template").

Project:        <company / product / industry>
Audiences:      <B2C, B2B, or both>
Languages:      <German only / German + English>
Brand colors:   <hex values — or "suggest something">
Sections:       <e.g. hero, features, pricing, FAQ, contact — or "you pick">

For converting an existing site, swap the recipe reference to §6 and add the old site’s URL. In an already derived project, “update this site from the template — follow SKILL.md recipe §7” is all it takes.