Pull along Tailwind configuration, generating CSS again

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/main.yml

@@ -47,6 +47,11 @@ jobs:
           ghc-version: ${{ matrix.ghc }}
           stack-version: ${{ matrix.stack }}
 
+      - uses: actions/setup-node@v6
+        name: Setup NodeJS
+        with:
+          node-version: 24
+
       - uses: actions/cache/restore@v4
         id: cache
         name: Cache ~/.stack
@@ -72,6 +77,26 @@ jobs:
       - name: Build site
         run:  stack exec --system-ghc site rebuild
 
+      - name: Build CSS
+        # The Node/Tailwind toolchain lives in tools/tailwind/; its npm scripts
+        # cd back to the repo root before invoking postcss.
+        working-directory: tools/tailwind
+        run:  |
+          npm ci
+          npm run build:production
+
+      # Gate every push/PR: dev.css is a checked-in snapshot of `npm run build`
+      # (concatenated onto tailwind.css by site.hs for Node-less previews).
+      # Regenerate it and fail if the committed copy has drifted.
+      - name: Check dev.css is in sync with Tailwind output
+        run: |
+          npm --prefix tools/tailwind run build:dev-snapshot
+          if ! git diff --quiet -- dev.css; then
+            echo "::error file=dev.css::dev.css is out of date. Regenerate it with 'cd tools/tailwind && npm run build:dev-snapshot' and commit the result."
+            git --no-pager diff -- dev.css
+            exit 1
+          fi
+
       - name: Deploy
         # Deploy only from non-pull-request changes to hakyll branch
         if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/hakyll'}}

.gitignore

@@ -22,6 +22,11 @@ _site/
 stack.yaml.lock
 dist-newstyle/
 
+### NodeJS ###
+node_modules/
+
 ### General ###
 *~
 .DS_Store
+
+/.direnv/

README.md

@@ -13,51 +13,95 @@ This repository is for the [haskell.foundation](https://haskell.foundation) webs
 - [The Haskell Foundation Website](#the-haskell-foundation-website)
   - [Table Of Contents](#table-of-contents)
   - [Building](#building)
+  - [Styling (CSS / Tailwind)](#styling-css--tailwind)
   - [CI](#ci)
   - [License](#license)
 
-
 ## Building
 
+The site can be built with either [Stack](https://docs.haskellstack.org) or
+[Cabal](https://www.haskell.org/cabal/) — use whichever you prefer.
+
 To build the project:
 
 ```bash
-stack build
-# alternatively: cabal build
+stack build   # with Stack
+cabal build   # with Cabal
 ```
 
 Once the project has built (which can take a while due to the dependencies for Hakyll), generate the site with:
 
 ```bash
-stack exec -- site build
-# alternatively: cabal run -- site build
+stack exec -- site build   # with Stack
+cabal run site -- build    # with Cabal
 ```
 
-and for development use:
+and for development (a server that rebuilds on change):
 
 ```bash
-stack run -- site watch
-# alternatively: cabal run -- site watch
+stack exec -- site watch   # with Stack
+cabal run site -- watch    # with Cabal
 ```
 
-The site will be build in the `_site` directory, and you can open the files in your browser of choice. Due to a Hakyll issue, some sponsor logos will not show up correctly. This is expected behavior, and should be fine for the deployed site.
+The site will be built in the `_site` directory, and you can open the files in your browser of choice. Due to a Hakyll issue, some sponsor logos will not show up correctly. This is expected behavior, and should be fine for the deployed site.
 
 For further information, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) at the root of this project.
 
+## Styling (CSS / Tailwind)
+
+The site is styled with [Tailwind CSS](https://tailwindcss.com) (v4). Tailwind is a CSS framework whose classes are short abbreviations for inline styles (e.g. `pt-4`, `text-center`), scattered directly across the HTML templates and content. At build time the Tailwind compiler acts as a kind of "CSS tree-shaker": it scans the site for the Tailwind classes actually in use and emits only the CSS needed for them.
+
+Two files matter:
+
+- `assets/css/tailwind.css` — the Tailwind entry point. It holds the v4 CSS-native configuration (`@theme` colors/fonts, `@plugin`, and the `@source` lines that tell the compiler which directories to scan). **New pages that use Tailwind classes must add an `@source` line here**, or those classes will be dropped from the production build.
+- `assets/css/main.css` — hand-written CSS that is *not* processed by Tailwind. This is the place for ordinary, non-Tailwind styles.
+
+### Do I need Node installed?
+
+**No, if you are only editing content or Haskell code.** Hakyll concatenates a checked-in snapshot, `dev.css`, onto `assets/css/tailwind.css` at build time (see the `match "assets/css/tailwind.css"` rule in `site.hs`). `dev.css` is a pre-generated copy of the real Tailwind output, so `stack exec -- site build` on its own produces a site that looks close enough to preview — no Node toolchain required. This keeps the site accessible to contributors of all skill sets.
+
+**Yes, if you are changing the appearance.** Because `dev.css` is only a snapshot, it does *not* reflect edits to `assets/css/tailwind.css`, `assets/css/main.css`, `tools/tailwind/postcss.config.js`, or any *newly used* Tailwind class. To regenerate the real CSS you need [Node.js](https://nodejs.org). The Node/Tailwind toolchain lives in [`tools/tailwind/`](tools/tailwind/) (see its README), separate from the Hakyll project, so run npm from there:
+
+```bash
+cd tools/tailwind
+npm ci                     # once, to install the toolchain
+npm run build              # compile -> _site/assets/css/tailwind.css
+npm run build:production   # minified build (NODE_ENV=production)
+```
+
+If you do not want to install `npm` globally and have `nix` available, drop into
+the Nix development shell which provides `npm` and a basic Haskell toolchain.
+
+If your change alters the CSS, regenerate the checked-in `dev.css` snapshot and
+commit it:
+
+```bash
+cd tools/tailwind
+npm run build:dev-snapshot   # recompile the dev.css snapshot in place
+```
+
+CI runs this same command and fails the build if the committed `dev.css` is out
+of date, so a stale snapshot cannot slip through review.
+
+> **Note:** `dev.css` is only an *unminified* snapshot of `npm run build`; it still differs from the minified `npm run build:production` output shipped to production, so verify appearance-critical changes against a real production build.
+
 ## CI
 
 We use GitHub Actions `.github/workflows/main.yml` to build the site for production.
 
 The general steps are:
 
 1. Check out the `hakyll` branch
-2. Install Haskell
+2. Install Haskell and Node.js
 3. Restore the cached build artefacts
 4. Build the `site` executable
 5. Rebuild the site contents using the `site` executable
-6. Check out the main branch
-7. Copy the `_site` directory over the `main` branch contents
-8. Commit and push the site contents to the `main` branch.
+6. Build the production CSS (`cd tools/tailwind && npm ci && npm run build:production`)
+7. Check out the `main` branch
+8. Copy the `_site` directory over the `main` branch contents
+9. Commit and push the site contents to the `main` branch.
+
+Steps 7–9 (the deploy) run only on non-PR pushes to `hakyll`; pull requests build and stop after step 6.
 
 ## License
 

assets/css/tailwind.css

@@ -0,0 +1,109 @@
+/**
+ * This is the Tailwind entry point (source). It is NOT overwritten by the
+ * build — its compiled *output* lands at _site/assets/css/tailwind.css (see
+ * steps below). Only put Tailwind config/directives here; hand-written CSS
+ * belongs in assets/css/main.css.
+ *
+ * NOTE: The underlying implementation details of how this works are as follows
+ * 1. tailwindcss needs these directives in order to know where to generate the
+ *    output
+ * 2. first, hakyll is run and copies this source file verbatim to
+ *    _site/assets/css/tailwind.css
+ * 3. then, after hakyll is done, postcss is run on _this_ source
+ *    assets/css/tailwind.css file. Postcss will, during execution, invoke
+ *    tailwindcss. tailwindcss (the compiler) will scan all the files in the
+ *    site for tailwind classes (including _this_ source file).
+ * 4. postcss's output file is configured to be _site/assets/css/tailwind.css,
+ *    so postcss overwrites the copy hakyll made in step 2 with the real,
+ *    compiled CSS. This source file is never modified.
+ */
+
+/*
+ * Tailwind v4 config lives here (CSS-native), not in tailwind.config.js.
+ * `source(none)` disables automatic content detection so only the
+ * @source paths below are scanned — mirrors the old
+ * topLevelFoldersWithTailwind/topLevelFilesWithTailwind purge.content list.
+ * New pages using Tailwind utility classes must add an @source line here,
+ * or their classes will be missing from the production build.
+ */
+/*
+ * The Node/Tailwind toolchain lives in tools/tailwind/ (see its README), so
+ * `node_modules` is not an ancestor of this file and Tailwind's bare-specifier
+ * resolution (`@import "tailwindcss"`) can't find it. We therefore point
+ * @import/@plugin at the toolchain's node_modules via a relative path. The
+ * build itself still runs from the repo root (required — Tailwind's @source
+ * only scans at/below the working directory), see tools/tailwind/package.json.
+ */
+@import "../../tools/tailwind/node_modules/tailwindcss/index.css" source(none);
+
+@source "../../board-nominations/**/*.html";
+@source "../../contact/**/*.html";
+@source "../../guidelines-for-respectful-communication/**/*.html";
+@source "../../resources/**/*.html";
+@source "../../templates/**/*.html";
+@source "../../vision/**/*.html";
+@source "../../whitepaper/**/*.html";
+@source "../../who-we-are/**/*.html";
+@source "../../404.html";
+
+@plugin "../../tools/tailwind/node_modules/@tailwindcss/typography";
+
+/*
+ * fontFamily/colors below are the literal values from the Tailwind v2
+ * palette this site was designed against (v2's `gray`/`blue`/`trueGray`
+ * colors and `violet`-as-`purple`) — v3/v4 changed the default gray/blue
+ * scales and dropped trueGray entirely, so these must be hardcoded rather
+ * than aliased to Tailwind's current built-in scales, or the site's colors
+ * would shift. main.css's hand-written rgba() values (e.g. `a` link color)
+ * are also drawn from this same palette, so keep them in sync.
+ */
+@theme {
+  --font-sans: 'Maven Pro', sans-serif;
+  --font-serif: 'Playfair Display', serif;
+
+  --border-width-3: 3px;
+
+  --color-gray-50: #fafafa;
+  --color-gray-100: #f4f4f5;
+  --color-gray-200: #e4e4e7;
+  --color-gray-300: #d4d4d8;
+  --color-gray-400: #a1a1aa;
+  --color-gray-500: #71717a;
+  --color-gray-600: #52525b;
+  --color-gray-700: #3f3f46;
+  --color-gray-800: #27272a;
+  --color-gray-900: #18181b;
+
+  --color-blue-50: #eff6ff;
+  --color-blue-100: #dbeafe;
+  --color-blue-200: #bfdbfe;
+  --color-blue-300: #93c5fd;
+  --color-blue-400: #60a5fa;
+  --color-blue-500: #3b82f6;
+  --color-blue-600: #2563eb;
+  --color-blue-700: #1d4ed8;
+  --color-blue-800: #1e40af;
+  --color-blue-900: #1e3a8a;
+
+  --color-trueGray-50: #fafafa;
+  --color-trueGray-100: #f5f5f5;
+  --color-trueGray-200: #e5e5e5;
+  --color-trueGray-300: #d4d4d4;
+  --color-trueGray-400: #a3a3a3;
+  --color-trueGray-500: #737373;
+  --color-trueGray-600: #525252;
+  --color-trueGray-700: #404040;
+  --color-trueGray-800: #262626;
+  --color-trueGray-900: #171717;
+
+  --color-purple-50: #f5f3ff;
+  --color-purple-100: #ede9fe;
+  --color-purple-200: #ddd6fe;
+  --color-purple-300: #c4b5fd;
+  --color-purple-400: #a78bfa;
+  --color-purple-500: #8b5cf6;
+  --color-purple-600: #7c3aed;
+  --color-purple-700: #6d28d9;
+  --color-purple-800: #5b21b6;
+  --color-purple-900: #4c1d95;
+}