Build the unified True Christian Church theme foundation

.github/workflows/validate.yml

@@ -0,0 +1,21 @@
+name: Validate theme
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm run check
+      - run: git diff --exit-code -- dist/

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.log

AGENTS.md

@@ -0,0 +1,138 @@
+# Agent instructions for `trueChristian/theme`
+
+## Purpose
+
+This repository defines the unified visual identity and mandatory global page chrome for **all True Christian Church websites**. It is not a page-specific website and must not be narrowed to one ministry, project, event, or location.
+
+The words **MUST**, **MUST NOT**, **SHOULD**, and **SHOULD NOT** in this file are requirements.
+
+## Read before editing
+
+Before changing this repository, read:
+
+1. this file;
+2. `docs/source-inventory.md` for evidence and provenance;
+3. `docs/header.md` and `docs/footer.md` for the global chrome contract;
+4. `docs/component-inventory.md` before changing page-body component styles;
+5. `src/data/site-chrome.json` for canonical labels, URLs, grouping, and order;
+6. `src/data/main-site-navigation.json` when working on the canonical main-site menu;
+7. the supplied header/footer evidence in `docs/source/`;
+8. the visual references in `docs/reference/`.
+
+Do not infer a redesign from a single project page. The shared header and footer belong to the church-wide theme.
+
+## Sources of truth
+
+When sources disagree, use this order:
+
+1. Explicit instructions from the repository owner.
+2. `src/data/site-chrome.json` for navigation and footer content.
+3. `src/html/site-header.html` and `src/html/site-footer.html` for structure and accessibility.
+4. `src/css/` for visual implementation.
+5. `docs/reference/header-desktop.png` and `docs/reference/footer-desktop.png` for visual comparison.
+6. Human-readable documentation under `docs/`.
+
+Do not silently change fixed labels, destinations, group order, logo proportions, footer layers, or brand colors.
+
+## Mandatory global header
+
+Every site MUST include a responsive header with the following behavior:
+
+- The source logo is `assets/brand/logo.jpg`.
+- Render the logo at its native aspect ratio, nominally `288px × 77px`.
+- The logo alternative text MUST be `A True Christian Church`.
+- The logo MUST link to the applicable True Christian Church home page.
+- A visible `Home` link MUST be the first textual navigation entry.
+- Navigation entries belonging to the site or page being built MUST follow `Home` and use the same visual treatment.
+- On the main church site, the canonical entries are `The Holy Scriptures`, `Sermons`, `Articles`, `Daily`, and `Services` with the `Join us` subtitle. Preserve the full extracted menu data in `src/data/main-site-navigation.json`.
+- Desktop navigation MUST use the white bar, thin cyan top rule, uppercase widely spaced labels, and active/hover contrast shown in the reference screenshot.
+- The desktop header SHOULD be sticky and reveal on upward scroll when the host framework supports it.
+- Below the desktop breakpoint, use a menu toggle and off-canvas or equivalent accessible navigation. Keep the logo centered and never squeeze the complete desktop menu into a narrow row.
+- Dropdown triggers MUST be keyboard operable and expose `aria-expanded`; the mobile menu MUST have an accessible close control.
+- Portable implementations MUST load `dist/truechristian-theme.js` (built from `src/js/site-header.js`) or provide equivalent menu, submenu, Escape-key, focus, and breakpoint behavior.
+- Set `aria-current="page"` only on the actual current route. Never hardcode `Home` as active in a reusable template.
+- Do not replace the logo with plain text, a generic church icon, or a project logo.
+
+When a satellite site needs different page-specific links, change only the site-specific navigation data. Preserve the logo, home link, header silhouette, typography, spacing, responsive behavior, and accessible menu pattern.
+
+## Mandatory footer assembly
+
+Every site MUST finish with the complete footer assembly, directly after the page content. It has two visible bands and three named responsibilities:
+
+1. **Directory/link footer** — the light `tm-bottom` band containing all grouped links and social outreach.
+2. **Copyright footer** — the dark band containing the copyright statement and legal/project links.
+3. **Bottom footer assembly** — the complete page-bottom unit formed by the directory footer followed immediately by the copyright footer. Nothing page-specific may be placed between those two bands.
+
+This terminology prevents the YOOtheme region name `tm-bottom` from being confused with the entire footer.
+
+### Directory/link footer requirements
+
+- Use four desktop columns in this exact order: `Church Info`, `Projects`, `Welcome`, `Social Outreach`.
+- Use the exact labels, URLs, order, and external-link behavior in `src/data/site-chrome.json`.
+- The data preserves the source's root-relative URLs. On a different domain, resolve every root-relative global-footer URL against `https://truechristian.church`; the portable HTML template already does this.
+- `Social Outreach` MUST contain X/Twitter, Facebook, GitHub, and Telegram icon links.
+- The source skyline file is `/images/city-skyline-skyscrapers-top.jpg`. It was not supplied separately; `assets/footer/city-skyline-reference.png` is an exact-size reference crop from the owner-supplied screenshot. Preserve its `270px × 180px` slot and do not substitute unrelated stock imagery.
+- On medium layouts, the four columns MAY become a two-by-two grid. On narrow layouts, stack them and center headings, links, and social controls.
+- Keep the generous light-grey spacing, uppercase headings and links, circular social buttons, rounded image treatment, and subdued shadow shown in `docs/reference/footer-desktop.png`.
+
+### Copyright footer requirements
+
+- Render the copyright footer immediately after the directory footer.
+- Use the exact text and link sequence from `src/data/site-chrome.json`:
+  `Copyright © trueChristian.Church free distribution only | Privacy Policy | Mission | Revival | We Fear God | Why we believe the Bible | Trousseau Chest`.
+- `free distribution only` links to `/copyright`.
+- Preserve the vertical-bar separators on wide layouts. Allow wrapping on small screens without clipping or horizontal scrolling.
+- Use the dark charcoal background and light text shown in the reference.
+
+### Footer prohibitions
+
+- MUST NOT omit either visible footer band.
+- MUST NOT collapse all footer content into a single undifferentiated paragraph.
+- MUST NOT replace the directory with a project-specific footer.
+- MUST NOT move legal links out of the copyright band.
+- MUST NOT reorder or rename groups or fixed links without explicit owner instruction.
+- MUST NOT place a newsletter signup, advertisement, unrelated logo, or promotional call-to-action into the global footer unless explicitly requested.
+
+## CSS and visual tokens
+
+- `src/css/` is the authoritative implementation.
+- `src/css/theme.css` defines module order; the files in `dist/` are generated.
+- Preserve the measured flat colors documented in `docs/brand-guide.md`.
+- Keep the header and footer selectors usable without Joomla while retaining compatibility selectors for the supplied YOOtheme/UIkit structure.
+- Do not paste or vendor proprietary YOOtheme CSS. Record framework references and implement church-specific CSS here.
+- The supplied HTML does not expose its compiled `@font-face` declarations. Montserrat and Raleway are forensic screenshot matches, not declarations extracted from the HTML; keep that provenance explicit.
+- Maintain visible keyboard focus, reduced-motion behavior, print-safe output, and documented contrast behavior. The measured inactive-nav color reproduces the source but is below WCAG AA for small text; do not claim otherwise.
+- Do not use CSS to hide missing required content.
+
+## Assets
+
+- Do not stretch, recolor, crop, redraw, or add effects to `assets/brand/logo.jpg`.
+- Preserve `assets/favicons/favicon.ico` byte-for-byte unless the owner supplies a replacement.
+- Generated YOOtheme cache files are outputs, not source assets.
+- Do not introduce unrelated page photography into the theme package.
+
+## Documentation expectations
+
+Any change to header/footer structure, links, colors, typography, or assets MUST update the corresponding documentation and reference data in the same pull request.
+
+If a value cannot be proven from the supplied files, document the uncertainty. Never present a guess as extracted fact.
+
+## Required validation
+
+Before committing:
+
+```sh
+npm run check
+```
+
+Also verify:
+
+- both reference screenshots remain present;
+- the logo and favicon remain present;
+- the example contains the global header, directory footer, and copyright footer;
+- the portable header script is present and syntax-valid;
+- all fixed labels and URLs match `src/data/site-chrome.json`;
+- no horizontal overflow is introduced at narrow widths;
+- `dist/` was regenerated after any source CSS change.
+
+Keep commits coherent. Do not merge a pull request unless the owner asks for the merge.

README.md

@@ -1,2 +1,69 @@
-# theme
-Unified Theme for Building Sites for TrueChristian Church
+# True Christian Church unified theme
+
+This repository is the shared visual and structural source of truth for websites built for **A True Christian Church**.
+
+It records the church-wide brand, CSS, header, navigation, link directory, copyright footer, favicon, and implementation rules so a person or an automated agent can reproduce the same site chrome consistently.
+
+## Non-negotiable site chrome
+
+Every site using this theme must render both of these assemblies:
+
+1. The global header: the `A True Christian Church` logo links home, followed by `Home`, the navigation belonging to the site being built, and the services entry where applicable.
+2. The complete footer stack:
+   - the light directory/link footer with `Church Info`, `Projects`, `Welcome`, and `Social Outreach`;
+   - the dark copyright/legal footer beneath it.
+
+The exact contracts are in [AGENTS.md](AGENTS.md), [docs/header.md](docs/header.md), and [docs/footer.md](docs/footer.md). Future agents must read `AGENTS.md` before changing this repository or applying the theme elsewhere.
+
+## Repository map
+
+| Path | Purpose |
+| --- | --- |
+| `src/css/` | Authoritative modular CSS source |
+| `src/js/` | Accessible portable header behavior |
+| `src/html/` | Reusable document-head, header, and footer markup |
+| `src/data/site-chrome.json` | Canonical labels, URLs, grouping, and order |
+| `src/data/main-site-navigation.json` | Full static menu data extracted from the supplied main-site header |
+| `assets/brand/logo.jpg` | Source church logo, 288 × 77 |
+| `assets/favicons/favicon.ico` | Supplied browser favicon |
+| `assets/footer/city-skyline-reference.png` | 270 × 180 screenshot-derived footer image reference |
+| `dist/` | Built, directly consumable CSS and header JavaScript |
+| `docs/` | Human-readable brand and implementation guide |
+| `docs/component-inventory.md` | Supplied page-source framework/CSS roles and evidence limits |
+| `docs/reference/` | Supplied desktop header/footer screenshots |
+| `examples/style-guide.html` | Working reference page using the package |
+
+## Use
+
+Load the built stylesheet and use the supplied structural templates:
+
+```html
+<link rel="icon" href="/assets/favicons/favicon.ico">
+<link rel="stylesheet" href="/dist/truechristian-theme.css">
+<script defer src="/dist/truechristian-theme.js"></script>
+```
+
+The templates deliberately carry both portable `tcc-*` classes and the relevant YOOtheme/UIkit class names from the supplied page source.
+
+`src/html/site-header.html` is the generic portable shell: logo, Home, a main-site top-level example, dropdown behavior, and the insertion point for the links belonging to the site being built. It is not a pre-rendered copy of the main site's content-heavy Articles mega-menu. Main-site renderers must use `src/data/main-site-navigation.json` or the retained YOOtheme source excerpt.
+
+## Build and validate
+
+The package has no npm dependencies.
+
+```sh
+npm run build
+npm run check
+```
+
+`npm run check` rebuilds the distribution files and verifies mandatory assets, exact fixed labels/URLs/order, source-to-template parity, key selectors, and JavaScript syntax.
+
+## Evidence and provenance
+
+The implementation was derived from the supplied True Christian Church page source, supplied header HTML, the source `logo.jpg`, the supplied favicon, and the supplied desktop header/footer screenshots. See [docs/source-inventory.md](docs/source-inventory.md).
+
+The supplied page source references Joomla, YOOtheme Pro 5.0.35, UIkit, and a compiled site stylesheet named `theme.13.css`. Third-party framework code is not copied into this repository. This package implements the reusable church-specific layer and records the external integration points.
+
+## Software license
+
+No software license was supplied for this repository. The website phrase `free distribution only` is preserved as required footer content; it is not treated as a software license. The repository owner should add the intended code/assets license explicitly before third-party distribution.