From 9dce8999202c3ed1488af95683f77d9db4928ad2 Mon Sep 17 00:00:00 2001
From: rdrew <rdrew@upei.ca>
Date: Tue, 5 May 2026 11:24:53 -0300
Subject: [PATCH] Add CLAUDE.md with codebase guidance for Claude Code

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..965fe2b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A Drupal 10+ custom theme named "Olivesnews" — a fork of Drupal's Olivero theme, customized for the Island Newspapers project (newspapers2.islandarchives.ca). It includes extensive PHP hook implementations, Twig template overrides, and a Babel + PostCSS build pipeline.
+
+## Commands
+
+```bash
+yarn build          # Build both CSS and JS
+yarn watch          # Watch both CSS and JS (parallel)
+yarn build:css      # PostCSS only
+yarn build:js       # Babel transpile only
+yarn watch:js-dev   # JS watch in development mode (NODE_ENV=development)
+yarn lint:css       # Stylelint
+yarn prettier       # Format ES6 and test files
+```
+
+BrowserSync for local dev is configured in `bs.js` (proxies a local Drupal instance).
+
+Deployment is via `deploy.sh` — it pushes to Git remote, then SSHes into the server to pull and run `drush cr`.
+
+## Architecture
+
+### Drupal integration layer
+
+- **`olivesnews.theme`** — all PHP hook implementations: `hook_preprocess_*`, `hook_theme_suggestions_*`, `hook_form_alter`, etc. This is the primary PHP entry point.
+- **`theme-settings.php`** — admin UI form for theme settings (color schemes, header utilities).
+- **`src/OlivesnewsPreRender.php`** — trusted prerender callbacks (must be a class method in Drupal to be trusted).
+- **`olivesnews.libraries.yml`** — defines ~25 named asset libraries; controls which CSS/JS files load and their dependencies. Edit this when adding new assets.
+- **`olivesnews.info.yml`** — theme metadata, region definitions, and library overrides (replaces core Drupal CSS/JS with theme versions).
+- **`olivesnews.breakpoints.yml`** — responsive breakpoints used by Drupal's responsive image module.
+- **`config/`** — exported Drupal configuration; `install/` runs on theme enable, `optional/` is applied conditionally.
+
+### Frontend assets
+
+- **`css/`** — PostCSS source, organized as `base/` (variables, fonts, reset), `components/` (buttons, nav, forms, etc.), `layout/`, and `theme/`.
+- **`js/`** — ES6 source files, one per behavior. Key files: `navigation.js`, `second-level-navigation.js`, `nav-resize.js`, `search.js`. Transpiled by Babel to ES5.
+- Compiled output goes alongside source (Drupal loads the compiled files referenced in `olivesnews.libraries.yml`).
+
+### Templates
+
+`templates/` mirrors Drupal's template suggestion hierarchy. Subdirectories map to entity/element types: `block/`, `content/`, `field/`, `layout/`, `navigation/`, `views/`, etc.
+
+### Mirador integration
+
+The theme includes custom config and JS (`js/mirador-mods.js`, `config/mirador_config/`) for the Islandora Mirador IIIF image viewer.
+
+## Key conventions
+
+- Node is pinned to 12.22.12 (see `.nvmrc`). Use `nvm use` before running yarn commands.
+- Yarn 4.0.2 is used (`.yarnrc.yml`). Run `yarn` not `npm`.
+- CSS uses px-to-rem conversion via PostCSS — write in `px`, output is `rem`.
+- JS targets ES5 (legacy browser support). Babel config in `package.json` (`@babel/preset-env` with `targets: "defaults"`).
+- After any PHP or template change in Drupal, a cache clear (`drush cr`) is required before changes are visible.