diff --git a/CHANGELOG.md b/CHANGELOG.md index a108d818..cabc91cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,8 @@ Releases up to 2.63.0 are listed in and the .vscode allowlist ([#2093]) - The backend-quality template is retired; its general rules move to the HTTP template ([#2102]) +- The frontend-static-site template is retired; its theme, trailing-slash and + 404 rules move to frontend-quality and frontend-content ([#2103]) ### Added @@ -209,6 +211,7 @@ Releases up to 2.63.0 are listed in [#2100]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2100 [#2101]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2101 [#2102]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2102 +[#2103]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2103 ## [2.90.0] - 2026-09-12 diff --git a/docs/architecture/05-building-block-view.md b/docs/architecture/05-building-block-view.md index 47097af0..5ad885ec 100644 --- a/docs/architecture/05-building-block-view.md +++ b/docs/architecture/05-building-block-view.md @@ -62,8 +62,8 @@ The core tier, as the manifest states it today: - `templates/core/review.md` - `templates/core/oop.md` -Measured: 9 `[DEPENDS ON]` tokens across 6 templates name one of these -files, and 6 manifest entries name a core id in `depends_on`. Declaring one +Measured: 8 `[DEPENDS ON]` tokens across 5 templates name one of these +files, and 5 manifest entries name a core id in `depends_on`. Declaring one is redundant rather than forbidden — the seeding reaches the file either way, and the directive documents a dependency a reader would otherwise infer. Reached by the seeding alone: `base-review`, `base-oop`. A chain diff --git a/docs/migrating-to-v3.md b/docs/migrating-to-v3.md index 62181381..68a69afe 100644 --- a/docs/migrating-to-v3.md +++ b/docs/migrating-to-v3.md @@ -65,6 +65,8 @@ receives nothing (ADR-051). | `backend-quality`: the handler, service and repository layering and its pattern catalogue | `backend-quality` | removed with the template; declare a stack's own architecture in a fork | | `backend-quality`: process lifecycle, admin processes, outbound timeouts, auth before logic, rate limits | `backend-quality` | `backend-http` | | `backend-quality`: N+1, async I/O, API deprecation, circuit breaker, outbox | `backend-quality` | already in `backend-database`, `backend-concurrency`, `backend-api`, `backend-errors`, `backend-messaging` | +| `frontend-static-site`: one stylesheet, BEM naming, system fonts, the `localStorage` theme snippet, the page table, lint and format files | `frontend-static-site` | removed with the template; a fork's static-site stack carries its choices | +| `static-site-theme`, `static-site-trailing-slash`, the custom 404 page, build-time rendering by default | `frontend-static-site` | `frontend-quality` and `frontend-content`, IDs kept | | The numbered-document check after concurrent merges, the first-CI-run rule for a check on its own change | `base-git` | this repository's playbook; the `check-heading-numbers` hook still ships | | The submodule update after a pin bump, the base64 bundle mask, the `.vscode` allowlist | `base-git` | removed; a neutral editor-settings rule remains | | Factory classmethods; `*-overlay.png` naming | `base-oop`, `base-measurement` | neutral rules remain | diff --git a/templates/frontend/content.md b/templates/frontend/content.md index 570ce732..bd0d531f 100644 --- a/templates/frontend/content.md +++ b/templates/frontend/content.md @@ -4,7 +4,7 @@ Abstract rules for authored web content — content and code separation, assets, SEO and structured data — whatever builds and serves it. Extended -by a layer that builds the site, or picked alone by a project whose content +by a stack that builds the site, or picked alone by a project whose content another system builds and serves. ## Content structure @@ -58,6 +58,16 @@ to change. `apple-touch-icon` for iOS home-screen bookmarks - Answer engines retrieve passages, not whole pages — lead each section with a direct answer and keep paragraphs self-contained +- Serve a custom 404 page that links back into the site + +## Trailing slash +[ID: static-site-trailing-slash] + +- MUST verify the trailing slash convention matches the hosting platform's + behavior (e.g. GitHub Pages forces trailing slashes, Netlify and Vercel + are configurable) +- SHOULD add a CI check that scans built HTML output for internal hrefs + violating the convention ## Structured data (if applicable) [ID: frontend-content-structured-data] diff --git a/templates/frontend/quality.md b/templates/frontend/quality.md index 2fbe7f5b..839d79b3 100644 --- a/templates/frontend/quality.md +++ b/templates/frontend/quality.md @@ -76,11 +76,21 @@ Rules: ## Performance - Preload critical above-the-fold assets +- Render pages at build or on the server by default; render on the client + only where a page needs client-side state - Keep client-side JS minimal — every dependency adds to bundle size - Avoid unnecessary dependencies - Defer non-critical scripts - Monitor Core Web Vitals (LCP, CLS, INP) — treat regressions as bugs +## Theme persistence (if applicable) +[ID: static-site-theme] + +- Apply a persisted theme before first paint (MUST): render it on the + server, or set it from a blocking `` script if the browser stores it +- Never set the theme from a body or deferred script (MUST NOT); the page + flashes the wrong theme on every load + ## Analytics (if applicable) - No third-party tracking scripts without explicit user consent diff --git a/templates/frontend/static-site.md b/templates/frontend/static-site.md deleted file mode 100644 index d69acaa6..00000000 --- a/templates/frontend/static-site.md +++ /dev/null @@ -1,101 +0,0 @@ -# Frontend — Static Site -[ID: frontend-static-site] -[DEPENDS ON: templates/core/git.md, templates/security/security.md] -[DEPENDS ON: templates/frontend/content.md, templates/frontend/ux.md] -[DEPENDS ON: templates/frontend/quality.md] - -Abstract rules for any static site generated at build time and served as -plain HTML, CSS, and minimal JavaScript. Never used directly — always -extended by a framework-specific stack (Astro, Hugo, Eleventy, etc.). - -## Stack -[ID: static-site-stack] - -- Output: static HTML generated at build time -- Serving: CDN or plain web server — no server-side runtime required -- JavaScript: minimal and opt-in — zero-JS by default where possible - -## Architecture principle -[ID: static-site-architecture] - -``` -data files → components → build output (HTML) - ↑ ↓ -Edit here Deployed here -``` - -- Separation of content and code — editable content lives in a data directory -- Default to static components; only reach for an interactive framework when - client-side state is genuinely required -- One stylesheet — no inline styles except dynamic/computed values - -## Pages -[ID: static-site-pages] - -| Page | Path | Notes | -|----------|---------|-------------------| -| Homepage | `/` | The site's entry page | -| 404 | `/404` | Custom error page | - -## Code conventions -[ID: static-site-code] - -- Lint any JS/TS code with the stack's linter, configured in the repository - and run on save; skip it where the project has no JS/TS -- Let one formatter own all formatting, with its configuration committed; - no style debates in code review - -## CSS conventions -[EXTEND: frontend-quality] - -- All CSS in a single global stylesheet -- Use CSS custom properties from `:root` for all colours and spacing -- BEM-like naming: `.component-element` (e.g. `.hero-grid`, `.nav-link`) -- No CSS-in-JS, no utility frameworks unless explicitly chosen in stack - -## Typography -[ID: static-site-typography] - -- Prefer system font stacks over web fonts — eliminates font FOUC and - external dependencies: - ```css - --font-text: system-ui, -apple-system, sans-serif; - --font-code: ui-monospace, "Cascadia Code", "Fira Code", monospace; - ``` -- If web fonts are required, self-host them as woff2 files in the directory - the build serves statically - and declare `@font-face` in CSS — never depend on external CDNs at runtime -- Use `font-display: block` for self-hosted fonts to prevent layout shift - -## Theme persistence -[ID: static-site-theme] - -- If the site supports dark mode via a `data-theme` attribute, initialize - the theme from `localStorage` in a ` - ``` -- MUST NOT set the theme in a body script or deferred module — this causes - a visible flash from light to dark on every page load - -## Performance -[EXTEND: frontend-quality] - -- Preload critical above-the-fold assets (hero image, primary font) -- Static generation by default — no client-side rendering unless necessary -- Defer non-critical scripts - -## Trailing slash -[ID: static-site-trailing-slash] - -- MUST verify the trailing slash convention matches the hosting platform's - behavior (e.g. GitHub Pages forces trailing slashes, Netlify and Vercel - are configurable) -- SHOULD add a CI check that scans built HTML output for internal hrefs - violating the convention diff --git a/templates/manifest.yaml b/templates/manifest.yaml index 70c022f9..ddd49c09 100644 --- a/templates/manifest.yaml +++ b/templates/manifest.yaml @@ -101,17 +101,12 @@ frontend: depends_on: [base-quality] - id: frontend-quality file: templates/frontend/quality.md - description: CSS conventions, performance, analytics + description: CSS conventions, performance, theme persistence, analytics depends_on: [base-quality] - id: frontend-content file: templates/frontend/content.md description: Build-agnostic content rules — content, assets, SEO, structured data depends_on: [base-docs, base-quality] - - id: frontend-static-site - file: templates/frontend/static-site.md - description: Abstract SSG rules — build, serving, CSS, typography, theme, performance - depends_on: - [base-git, base-security, frontend-content, frontend-ux, frontend-quality] backend: - id: backend-http diff --git a/tests/baselines/template-quality.txt b/tests/baselines/template-quality.txt index 3acae237..514b8f45 100644 --- a/tests/baselines/template-quality.txt +++ b/tests/baselines/template-quality.txt @@ -33,9 +33,8 @@ templates/data/data-governance.md 100.0 templates/data/data-migration.md 100.0 templates/data/data-modeling.md 100.0 templates/data/data-quality.md 84.2 -templates/frontend/content.md 87.6 -templates/frontend/quality.md 93.6 -templates/frontend/static-site.md 84.2 +templates/frontend/content.md 90.7 +templates/frontend/quality.md 93.5 templates/frontend/ux.md 94.3 templates/infra/cicd.md 95.7 templates/infra/containers.md 95.2