From 0b4eac0f94eb56d1d40a813045448a655a62d33f Mon Sep 17 00:00:00 2001 From: rdrew Date: Thu, 7 May 2026 09:24:58 -0300 Subject: [PATCH] Add CLAUDE.md with theme architecture and dev workflow notes Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7cba393 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +A Drupal 9/10/11 custom theme for the Roblib ILL (interlibrary loan) site. Based on the `stable9` base theme. It's a fork/customization of "The X" base theme (see `README.txt`, `changelog.txt`, `credit.txt`). + +Key naming gotcha: the directory is `roblib_ill_theme` but the theme's machine name is **`ill`**. All the config files (`ill.info.yml`, `ill.libraries.yml`, `ill.theme`, `ill.breakpoints.yml`) and the Twig namespace (`@ill/...`) use `ill`. Don't rename one without the other. + +## Common commands + +### Local dev with browser-sync +The intended local workflow proxies a DDEV site and live-reloads on CSS/JS changes: +``` +node bs.js +``` +`bs.js` is hardcoded to proxy `https://drupal-theme-dev.ddev.site` and watch `css/**/*.css` and `js/**/*.js`. Edit `bs.js` if your local Drupal URL differs. + +### Deploy +`./deploy.sh "commit message"` does the full deploy: `git add --all`, commit, push, then SSH to the production server (`137.149.52.34`), `git pull` in the theme dir, and run `drush cr`. Edit the `SERVER`/`THEME_DIR`/`SITE_ROOT`/`DRUSH_PATH` constants at the top for new environments. Requires SSH key auth set up in advance. + +### Drupal cache +After Twig template, library, or `.theme` changes on a running site, the cache must be cleared (`drush cr`). The deploy script does this automatically; locally you'll need to run it yourself. + +### Build/lint scripts (currently non-functional) +`package.json` declares yarn scripts for PostCSS / Babel builds, stylelint, and prettier (e.g. `yarn build`, `yarn watch:css`, `yarn lint:css`). **These scripts reference `./scripts/css/...` and `./scripts/js/...` which do not exist in this repo.** Don't run them expecting them to work; CSS and JS in `css/` and `js/` are edited and shipped directly. If a build step gets restored later, the package.json declarations show what was intended. + +## Architecture + +### Theme entry points +- `ill.info.yml` — declares regions (header_top_left/right, header, primary_menu, search_box, page_header, highlighted, content, content_top/bottom, content_home_top/bottom, sidebar_first/second, footer_top, footer_one..four, footer_bottom_left/right/last, hidden) and pulls in the `ill/global-styling` library. +- `ill.libraries.yml` — defines the libraries. `global-styling` lists every CSS file in `css/` individually (base, layout, then ~15 component files); `js/ill.js` is the only JS, and it depends on `core/jquery`. Additional libraries are defined for `book`, `fontawesome4`, `fontawesome5`, `bootstrap-icons`, and `maintenance`. +- `ill.theme` — only three preprocess hooks: `ill_preprocess_page` (exposes `site_name`, `site_slogan`, `base_path`, `scrolltotop_on`), `ill_preprocess_breadcrumb` (appends current page title to the breadcrumb trail and sets `breadcrumb_icon_style = '/'`), and `ill_preprocess_html` (exposes `is_front`). +- `ill.breakpoints.yml` — three breakpoints: `mobile`, `narrow` (560–850px), `wide` (≥851px). + +### Template structure +`templates/layout/page.html.twig` is the assembly point: it conditionally `{% include %}`s partials from `templates/template-parts/{header,footer,sidebar,content-parts,components}/` using the `@ill` namespace. When adding regions or restructuring page chrome, edit `page.html.twig` and add the matching partial under `template-parts/`. + +Other template subdirectories (`block/`, `content/`, `content-edit/`, `dataset/`, `field/`, `form/`, `misc/`, `navigation/`) hold standard Drupal template overrides (e.g. `breadcrumb.html.twig`, `menu.html.twig`, `book-navigation.html.twig`). + +### CSS organization +Many small files in `css/`, each loaded explicitly by `ill.libraries.yml` (so adding a new CSS file requires registering it there or it won't load). Roughly organized by page region (`header.css`, `footer.css`, `sidebar.css`, `node.css`) and concern (`base.css`, `layout.css`, `responsive.css`, `components.css`, `shortcodes.css`). Several large vendor files are vendored in (`bootstrap-icons.css`, `font-awesome.css`, `font-awesome5.css`, `fontawesome5.css`). + +### JS +`js/ill.js` is jQuery-based (`jQuery(document).ready(...)`) and handles: mobile menu toggle, header search box open/close (with click-outside and Esc handling), and scroll-to-top button visibility. No build pipeline — edit and ship. + +### Block placement config +`config/optional/block.block.ill_*.yml` defines default block placements (branding, breadcrumbs, content, footer, help, local actions/tasks, main menu, messages, page title, powered, search, tools, account menu) so that a fresh install of the theme has a sane out-of-the-box layout.