feat(design): apply Fast Forward documentation design system

.github/workflows/tests.yml

@@ -0,0 +1,54 @@
+name: Template validation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Run Tests (${{ matrix.php-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ['8.3', '8.4', '8.5']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: dom, mbstring, intl, xml, zip
+          coverage: none
+          tools: composer:v2
+      - run: composer validate --strict
+      - run: composer install --no-scripts --no-interaction --prefer-dist --no-progress
+      - name: Validate rendered checkout
+        run: php tests/generate-fixture.php
+      - name: Validate rendered release archive
+        run: |
+          mkdir -p "$RUNNER_TEMP/template-archive"
+          git archive HEAD | tar -x -C "$RUNNER_TEMP/template-archive"
+          php tests/generate-fixture.php "$RUNNER_TEMP/template-archive"
+
+  actions:
+    name: Analyze (actions)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Install verified actionlint
+        run: |
+          curl --fail --location --retry 3 -o "$RUNNER_TEMP/actionlint.tar.gz" https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz
+          curl --fail --location --retry 3 -o "$RUNNER_TEMP/actionlint_checksums.txt" https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_checksums.txt
+          cd "$RUNNER_TEMP"
+          mv actionlint.tar.gz actionlint_1.7.12_linux_amd64.tar.gz
+          grep ' actionlint_1.7.12_linux_amd64.tar.gz$' actionlint_checksums.txt | sha256sum --check --strict
+          tar -xzf actionlint_1.7.12_linux_amd64.tar.gz actionlint
+      - run: '"$RUNNER_TEMP/actionlint"'

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 2.1.0 - 2026-10-09
+
+### Added
+
+- Fast Forward documentation identity, with the approved fox signature and Dash reading companion.
+- Light and navy reading themes with a compact accessible theme control and saved preference.
+- Code windows with language labels, decorative window dots and an accessible copy button.
+- Responsive guide outlines, improved navigation, search labels, focus states and print styles.
+- PHP 8.3, 8.4 and 8.5 checks that generate real guide/API fixtures from both checkout and release archive.
+
+### Changed
+
+- Apply the shared design system's typography, colors and reading surfaces while preserving Bootstrap and phpDocumentor integration.

DESIGN.md

@@ -0,0 +1,49 @@
+# Fast Forward documentation design
+
+This template implements the approved documentation pattern from the [Fast Forward brand kit](https://github.com/php-fast-forward/.github). Twig and Bootstrap 5 remain the runtime foundation.
+
+## Token mapping
+
+| Role | Value | Template use |
+| --- | --- | --- |
+| Primary | `#6d28d9` | Active navigation, actions and light-surface links |
+| Primary hover | `#5b21b6` | Interactive hover and pressed states |
+| Navy | `#050b20` | Toolbar, navigation rail, code and navy reading surface |
+| Cyan | `#22d3ee` | Dark-surface links, keyboard focus and Copy outline |
+| Ink | `#142033` | Light-surface text |
+| Neutral | `#f6f8ff` | Light reading surround and alternating table rows |
+| Border | `#cbd5e1` | Light borders and dark secondary text |
+
+Body and heading fonts use the system stack; code uses the system monospace stack. Heading sizes follow the kit's 3rem/2rem scale. Cards use 12px and 20px radii. Bootstrap variables and component-specific states are adapted in `css/base.css.twig`; no Tailwind processing is required.
+
+## Behavior
+
+Light is the default reading surface. The navy navigation rail stays consistent in both themes. A compact sun/moon toolbar button progressively enables theme switching, labels the next action for assistive technology and stores the preference when local storage is available. Denied storage never blocks reading. Navigation uses native details on mobile. Code blocks progressively gain a window header with three decorative dots and a centered language label; an icon Copy control appears only with a secure Clipboard API. Copied feedback uses a tooltip and live region. Clipboard failures leave a visible instruction to select the code. The header stays separate from horizontally scrolling code, and copying preserves the exact example text. Skip navigation, focus outlines, search labels, active-page semantics and reduced-motion/print styles are included.
+
+Existing phpDocumentor destination-depth handling, Bootstrap collapse menus, Fuse search hooks and UML hooks remain intact. Required images are copied by FileIo transformations; consumers do not need to host the central kit.
+
+## Assets
+
+- `data/fast-forward-logo-dark.svg` copies the approved native outlined fox signature from `assets/brand/fast-forward-logo-dark.svg`.
+- `data/dash-reading.png` copies the developer reading pose from `assets/mascot/dash-developer-reading.png`.
+- Source repository: [php-fast-forward/.github](https://github.com/php-fast-forward/.github).
+
+Runtime images live in `data/` so excluding consumer documentation from a Composer archive still preserves the generated site's identity assets.
+
+## Validation
+
+Install the development tool with `composer install --no-scripts`, then run `php tests/generate-fixture.php`. Composer allows only the official `phpdocumentor/shim` plugin, which installs the signed phpDocumentor PHAR; no runtime dependency is added to template consumers. The CI matrix renders the fixture with PHP 8.3, 8.4 and 8.5 from both the checkout and a Git archive, and actionlint validates the workflow. The PHAR's bundled dependencies are outside Composer's dependency-audit coverage; use this build tool only with trusted project sources.
+
+Generate the fixture from `tests/fixture` with phpDocumentor 3:
+
+```sh
+phpdoc --config phpdoc.xml
+```
+
+The fixture includes root and nested guides, a PHP API class, admonitions, source examples and cross-document links. Generated HTML, CSS, JavaScript and copied images can then be inspected together.
+
+Run `php tests/verify-output.php /path/to/ff-template-preview` from the template checkout. It uses PHP's DOM extension to check shared local assets, same-page reading anchors and the accessible icon theme control across every generated HTML page, including nested guides and API pages. It also checks unchanged guide/API code examples and that copied identity images match the template files byte for byte. Optional graph rendering belongs to the consumer's phpDocumentor configuration.
+
+The implementation was generated with phpDocumentor 3.9.1 and visually compared with the kit's `profile/assets/docs-installation.png`: navy rail and purple active navigation, three-column desktop reading, system heading hierarchy, important callouts, and navy code panels with cyan Copy controls. Browser validation covered light/navy switching and persistence, guide outline anchors, code copy status, API search results, a 1440px desktop viewport and a 390px mobile viewport with no horizontal page overflow.
+
+Deliberate adaptations: the generated site's project name appears beneath the framework signature; API/navigation content comes from phpDocumentor; guide outlines are progressively generated from rendered headings. The template keeps Bootstrap collapse and existing search/UML dependencies.

README.md

@@ -23,6 +23,14 @@ A clean and modern Bootstrap-based template for phpDocumentor, designed to impro
 - Improved tables of contents and element listings
 - Designed for documentation sets that provide guides
 
+## Fast Forward design system
+
+The template implements the [approved documentation pattern](https://php-fast-forward.github.io/.github/docs/brand/documentation.html): a navy navigation rail, neutral reading surface, purple active states, system typography, navy code blocks, the fox signature and Dash as a reading companion. Bootstrap 5 remains the layout and navigation foundation.
+
+The toolbar offers light and navy reading surfaces through a compact sun/moon button. The preference is stored locally when storage is available; reading works without JavaScript. Code blocks gain a window header with a language label. An icon Copy control appears when the browser supports the Clipboard API. Mobile navigation can be collapsed without JavaScript.
+
+See [DESIGN.md](DESIGN.md) for token mappings, assets and PHP validation. Generated sites receive the required images through the template transformations, including nested guide and API pages.
+
 ## Installation
 
 Install the template with Composer:

components/header.html.twig

@@ -1,21 +1,21 @@
-<header id="header" class="sticky-top">
-    <nav class="navbar bg-primary navbar-expand-lg">
-        <div class="container-fluid">
-            <a class="navbar-brand text-bg-primary" href="{{ path('/') }}" title="{{ project.name }}">{{ project.name }}</a>
-
-            <button class="navbar-toggler ms-auto" type="button" data-bs-toggle="collapse" data-bs-target="#header-nav" aria-controls="header-nav" aria-expanded="false" aria-label="Toggle navigation">
+<header id="header" class="sticky-top" data-bs-theme="dark">
+    <nav class="navbar ff-docs-header navbar-expand-lg" aria-label="Documentation toolbar">
+        <div class="container-fluid gap-3">
+            <a class="navbar-brand ff-docs-brand" href="{{ path('/') }}" title="{{ project.name }}">
+                <img src="{{ path('images/fast-forward-logo-dark.svg') }}" alt="PHP Fast Forward" width="200" height="80">
+                <span class="ff-docs-project">{{ project.name }}</span>
+            </a>
+            <button class="navbar-toggler ms-auto" type="button" data-bs-toggle="collapse" data-bs-target="#header-nav" aria-controls="header-nav" aria-expanded="false" aria-label="Toggle toolbar">
                 <span class="navbar-toggler-icon"></span>
             </button>
-
-            <div id="header-nav" class="collapse navbar-collapse">
-                <ul class="navbar-nav me-auto">
-                    {% include 'components/topnav.html.twig' %}
-                </ul>
-
-                <div class="navbar-nav ms-lg-3">
-                    {% include 'components/search.html.twig' %}
-                </div>
+            <div id="header-nav" class="collapse navbar-collapse gap-3">
+                <div class="me-auto">{% include 'components/topnav.html.twig' %}</div>
+                {% include 'components/search.html.twig' %}
+                <button class="ff-docs-theme" type="button" data-reading-theme-toggle aria-label="Switch to navy theme" title="Switch to navy theme" hidden>
+                    <svg class="ff-theme-moon" aria-hidden="true" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 0 1 11.21 3 9 9 0 1 0 21 12.79Z" /></svg>
+                    <svg class="ff-theme-sun" aria-hidden="true" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4" /><path d="M12 2v2m0 16v2M2 12h2m16 0h2M4.93 4.93l1.42 1.42m11.3 11.3 1.42 1.42M4.93 19.07l1.42-1.42m11.3-11.3 1.42-1.42" /></svg>
+                </button>
             </div>
         </div>
     </nav>
-</header>
+</header>

components/menu.html.twig

@@ -62,6 +62,7 @@
     <div class="d-flex align-items-center">
         <a
             href="{{ entryPath }}"
+            {% if isActive %}aria-current="page"{% endif %}
             class="nav-link flex-grow-1 px-3 py-1 rounded-2{% if isActive %} active{% else %} link-body-emphasis{% endif %}{% if depth > 1 %} small{% endif %}"
         >
             {{ entry.title | shortFQSEN }}
@@ -75,6 +76,7 @@
                 data-bs-target="#{{ collapseId }}"
                 aria-expanded="{{ isOpen ? 'true' : 'false' }}"
                 aria-controls="{{ collapseId }}"
+                aria-label="Toggle {{ entry.title | shortFQSEN }} sections"
             >
                 <i class="fas fa-chevron-down small"></i>
             </button>
@@ -88,4 +90,4 @@
             </ul>
         </div>
     {% endif %}
-</li>
+</li>

components/search.html.twig

@@ -1,4 +1,4 @@
-<li class="nav-item ml-lg-auto">
+<div class="nav-item">
     <section data-search-form class="phpdocumentor-search">
         <div class="input-group">
             <span class="input-group-text bg-body border-end-0">
@@ -8,7 +8,8 @@
             <input
                 type="search"
                 class="form-control border-start-0"
-                placeholder="Search..."
+                placeholder="Search documentation..."
+                aria-label="Search documentation"
                 autocomplete="off"
             >
 
@@ -22,4 +23,4 @@
             </button>
         </div>
     </section>
-</li>
+</div>

components/source-modal.html.twig

@@ -34,6 +34,17 @@
 
             const code = document.createElement('code');
             code.className = 'language-' + language;
+            let loaded = false;
+
+            function scrollToSourceLine() {
+                const requestedLine = Number(line);
+                if (!loaded || !code.isConnected || !pre.clientHeight || !Number.isInteger(requestedLine) || requestedLine < 1) return;
+                const style = window.getComputedStyle(code);
+                const lineHeight = parseFloat(style.lineHeight) || parseFloat(style.fontSize) * 1.6;
+                const paddingTop = parseFloat(style.paddingTop) || 0;
+                pre.scrollTop = Math.max(0, (requestedLine - 1) * lineHeight + paddingTop - pre.clientHeight / 2);
+            }
+            el.addEventListener('shown.bs.modal', scrollToSourceLine, { once: true });
 
             pre.textContent = '';
             if (line) {
@@ -52,14 +63,11 @@
 
                 if (xhr.status < 400 && xhr.responseText) {
                     code.textContent = xhr.responseText;
-                    Prism.highlightElement(code);
+                    if (window.hljs) window.hljs.highlightElement(code);
+                    pre.dispatchEvent(new Event('ff-code-ready', { bubbles: true }));
 
-                    if (line) {
-                        const lineElement = pre.querySelector('.line-numbers-rows > span:nth-child(' + line + ')');
-                        if (lineElement) {
-                            pre.scrollTop = lineElement.offsetTop - (pre.offsetHeight / 2);
-                        }
-                    }
+                    loaded = true;
+                    scrollToSourceLine();
 
                     return;
                 }
@@ -101,4 +109,4 @@
         });
     })();
 </script>
-{% endblock %}
+{% endblock %}

composer.json

@@ -32,5 +32,13 @@
         "php": "^8.3"
     },
     "minimum-stability": "stable",
-    "prefer-stable": true
-}
+    "prefer-stable": true,
+    "config": {
+        "allow-plugins": {
+            "phpdocumentor/shim": true
+        }
+    },
+    "require-dev": {
+        "phpdocumentor/shim": "^3.9"
+    }
+}