diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..0820376 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Mark generated files so they are collapsed by default in GitHub diffs +assets/css/compiled/main.css linguist-generated=true +docs/hugo_stats.json linguist-generated=true diff --git a/.github/workflows/accessibility.yml b/.github/workflows/accessibility.yml new file mode 100644 index 0000000..9964b1b --- /dev/null +++ b/.github/workflows/accessibility.yml @@ -0,0 +1,62 @@ +name: Accessibility Tests + +on: + pull_request: + branches: [main] + +concurrency: + group: accessibility-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + +defaults: + run: + shell: bash + +jobs: + a11y: + runs-on: ubuntu-latest + environment: accessibility + env: + HUGO_VERSION: 0.147.7 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: recursive + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.24" + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "22" + cache: npm + + - name: Setup Hugo + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + + - name: Install dependencies + run: npm ci + + - name: Install Playwright Chromium + run: npx playwright install chromium + + - name: Build site + run: npm run build + + - name: Run accessibility tests + run: npm run test:a11y + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: accessibility-report + path: playwright-report/ + retention-days: 14 diff --git a/.gitignore b/.gitignore index 35c3c4e..7377a08 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,7 @@ public/ resources/ .hugo_build.lock + +# Playwright +playwright-report/ +test-results/ diff --git a/AGENTS.md b/AGENTS.md index 14dc5fb..c0bbe14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,6 +94,28 @@ The `docs/` directory serves as both documentation and testing ground: - Chroma syntax highlighting themes in `assets/css/chroma/` - CSS compilation requires Node.js dependencies (PostCSS, Tailwind CSS v4+) +#### Rebuilding CSS after template changes + +Tailwind CSS relies on `docs/hugo_stats.json` to know which HTML tags, classes, and IDs are actually used in the built site, so it can tree-shake unused styles. When you modify layouts, partials, or shortcodes you must **regenerate `hugo_stats.json` first**, then rebuild the CSS: + +1. **Generate `docs/hugo_stats.json`** — Run Hugo with the `dev.toml` config (which sets `build.buildStats.enable = true`): + + ```bash + # Using npm (starts a dev server that writes hugo_stats.json on every rebuild): + npm run dev:theme + + # Or a one-shot build using the raw Hugo command: + hugo --config=hugo.yaml,../dev.toml --themesDir=../.. --source=docs + ``` + +2. **Build the CSS** — With an up-to-date `hugo_stats.json` in place, compile the stylesheet: + + ```bash + npm run build:css + ``` + +> **Why two steps?** `dev.toml` mounts `docs/hugo_stats.json` into the Hugo asset pipeline (`assets/notwatching/hugo_stats.json`) and configures a cache-buster so that changes to the stats file trigger a CSS recompile during `dev:theme`. When running outside the dev server you need to perform these steps manually in order. + ### Customization Points - Custom partials: `layouts/_partials/custom/` @@ -147,6 +169,22 @@ The `docs/` directory serves as both documentation and testing ground: - Compiled output goes to `assets/css/compiled/main.css` - Prettier formatting for Go templates and code consistency +### Accessibility (WCAG Compliance) + +All new features and UI changes must follow the [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) at the **AA** conformance level. Key requirements: + +- **Semantic HTML**: Use appropriate elements (`