From e1107157110e8f57b491f8337acde456accf6f60 Mon Sep 17 00:00:00 2001 From: Branimir Georgiev <66906831+braboj@users.noreply.github.com> Date: Wed, 21 Oct 2026 17:07:24 +0300 Subject: [PATCH 1/3] refactor(frontend): retire frontend-static-site; keep its general rules (#2086) One stylesheet, BEM naming, system fonts, the theme snippet and the page table are one site's choices and leave with the template. The theme flash rule and the trailing-slash check move to frontend-quality and frontend-content with their IDs; a custom 404 page and build-time rendering by default join them. Co-Authored-By: Claude Opus 5.5 --- docs/architecture/05-building-block-view.md | 4 +- docs/migrating-to-v3.md | 2 + templates/frontend/content.md | 12 ++- templates/frontend/quality.md | 10 ++ templates/frontend/static-site.md | 101 -------------------- templates/manifest.yaml | 7 +- tests/baselines/template-quality.txt | 5 +- 7 files changed, 28 insertions(+), 113 deletions(-) delete mode 100644 templates/frontend/static-site.md diff --git a/docs/architecture/05-building-block-view.md b/docs/architecture/05-building-block-view.md index 8a1d0553..69846426 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: 11 `[DEPENDS ON]` tokens across 7 templates name one of these -files, and 7 manifest entries name a core id in `depends_on`. Declaring one +Measured: 10 `[DEPENDS ON]` tokens across 6 templates name one of these +files, and 6 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`. A chain assembled by diff --git a/docs/migrating-to-v3.md b/docs/migrating-to-v3.md index d12d1498..c45fb7ca 100644 --- a/docs/migrating-to-v3.md +++ b/docs/migrating-to-v3.md @@ -59,6 +59,8 @@ receives nothing (ADR-051). | `quality-exemption-doc-duty`, the exit-3 and readings rules, the immutable-corpus sweep | `base-quality` | this repository's playbook | | Language porting rules; `inspect.getattr_static`; Python `__init__` and extras wording | `base-quality` | removed or neutral | | The eight-stage pipeline order, its push and tag triggers, the three-environment minimum, the post-publish deploy hook | `base-cicd` | removed; the gates, packaging once, DAST before production and artifact promotion remain | +| `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..81ed9fbf 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 from a blocking script in ``, before any + content renders (MUST) +- 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 d63d95e3..0226d386 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 f8ab5f40..abd5589d 100644 --- a/tests/baselines/template-quality.txt +++ b/tests/baselines/template-quality.txt @@ -34,9 +34,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 94.2 templates/frontend/ux.md 94.3 templates/infra/cicd.md 95.7 templates/infra/containers.md 90.8 From 86839392a7486d1e89da6f751b14e2380aa25fab Mon Sep 17 00:00:00 2001 From: Branimir Georgiev <66906831+braboj@users.noreply.github.com> Date: Wed, 21 Oct 2026 17:12:02 +0300 Subject: [PATCH 2/3] docs(changelog): note #2103 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 939946d9..298b27a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,8 @@ Releases up to 2.63.0 are listed in check-harness rules ([#2082]) - The git template drops its submodule, numbered-document and base64 rules and the .vscode allowlist ([#2093]) +- The frontend-static-site template is retired; its theme, trailing-slash and + 404 rules move to frontend-quality and frontend-content ([#2103]) ### Added @@ -197,6 +199,7 @@ Releases up to 2.63.0 are listed in [#2096]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2096 [#2097]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2097 [#2098]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2098 +[#2103]: https://github.com/solid-ai-dev/solid-ai-templates/pull/2103 ## [2.90.0] - 2026-09-12 From 47a2f46d8a1048552bdcbcc3c5e23d9072d6a53b Mon Sep 17 00:00:00 2001 From: Branimir Georgiev <66906831+braboj@users.noreply.github.com> Date: Wed, 21 Oct 2026 17:50:58 +0300 Subject: [PATCH 3/3] fix(frontend): require the theme before first paint, by any means The rule mandated a blocking head script, but a server-rendered page that emits the stored theme avoids the flash without one. The script is now required only where the browser stores the theme. The score row drops from 94.2 to 93.5 for the added qualifier. Co-Authored-By: Claude Opus 5.5 --- templates/frontend/quality.md | 4 ++-- tests/baselines/template-quality.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/templates/frontend/quality.md b/templates/frontend/quality.md index 81ed9fbf..839d79b3 100644 --- a/templates/frontend/quality.md +++ b/templates/frontend/quality.md @@ -86,8 +86,8 @@ Rules: ## Theme persistence (if applicable) [ID: static-site-theme] -- Apply a persisted theme from a blocking script in ``, before any - content renders (MUST) +- 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 diff --git a/tests/baselines/template-quality.txt b/tests/baselines/template-quality.txt index abd5589d..7c81ef6a 100644 --- a/tests/baselines/template-quality.txt +++ b/tests/baselines/template-quality.txt @@ -35,7 +35,7 @@ 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 90.7 -templates/frontend/quality.md 94.2 +templates/frontend/quality.md 93.5 templates/frontend/ux.md 94.3 templates/infra/cicd.md 95.7 templates/infra/containers.md 90.8