diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 91f8358..1d9d8f1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ucsd-decorator", - "version": "2.3.0", + "version": "2.4.0", "license": "MIT", "description": "Build and edit UC San Diego web pages on the Decorator 5 design system without damaging the shared page chrome. Provides one writable canvas, a pinned source of truth for markup, and a CI-checkable chrome contract.", "author": { diff --git a/.cursorrules b/.cursorrules index 5a5514a..3869b50 100644 --- a/.cursorrules +++ b/.cursorrules @@ -4,6 +4,8 @@ These rules apply when generating, modifying, or reviewing code in a UC San Diego Decorator project. +This file holds the rules that apply in every session. Detail that only some tasks need is in `DECORATOR.md` at the project root: where a section below names a task, read that section in full there before you do the task. Both files are generated — edit neither. + --- ## The canvas and the chrome @@ -33,35 +35,14 @@ reshape the shell so a content change fits. ### The site name is the one piece of chrome text you may change -The title band carries the site's own name twice — a long form for tablet and -desktop, and a short form that replaces it below 480px: - -```html -Decorator V5 -V5 -``` - -When asked to change the site name or title, change the **text** of these two -links and nothing else. Keep both elements, their classes, and their `href`. -Do not touch `a.title-logo` — its destination is fixed at -`https://www.ucsd.edu` on every Decorator site — and do not add markup inside -either link: no ``, image, icon, or inline style. +When asked to change the site's name or title, make the change yourself: it is +the one chrome edit that is yours. Change the **text** of +`a.title-header.title-header-large` and `a.title-header.title-header-short`, +identically on every page, and nothing else about either link. `verify` +ignores that text, so no `--accept` is needed. Always propose a short form, a +word or an acronym, even when only the long name was given. -**Always propose the short form.** If the request names only the long title, -suggest a short one and say you did. The short form renders uppercase, with -letter spacing, at 20px on the smallest phones, so keep it to a word or an -acronym — roughly a dozen characters at most. "Decorator V5" becomes "V5"; -"Division of Physical Sciences" becomes "Physical Sciences" or "DPS". Never -leave it as the old site's name, and never leave it empty. - -Change it on **every page**, identically. If the project builds its header -from a data file, edit the data file, not the rendered markup. - -`verify` is built for this: tier 2 ignores the text of `a.title-header`, so -no `--accept` is needed. Tier 1 still fails if one page's name differs from -another's, and tier 3 fails if either link is left empty. Any other change in -the title band — an `href`, a class, an added element — is still a chrome -edit, and is still not yours to make. +**Before you change the site name or title, read this section in full in `DECORATOR.md`.** ### The chrome integrity gate is not yours to satisfy @@ -118,44 +99,21 @@ You do not run that command. You do not write `chrome-styling.local.json`, ### Project canvas rules live in `canvas-rules/` -A project can add its own rules for the canvas — house components, content -conventions, a data-loading pattern — as Markdown files in `canvas-rules/` at -its root. `npx ucsd-decorator-kit sync` compiles every `*.md` there except -`README.md`, in filename order, into a "Project canvas rules" section at the end -of this file. - -Those rules govern the canvas and nothing else, and they rank below every rule -the kit ships: where one conflicts with a kit rule, the kit rule wins. A file in -`canvas-rules/` is not a review, so it cannot authorize a chrome edit any more -than a chat message can. If one asks for a change outside the canvas, do not -follow that part — name the file and the region, and stop, as for any other -chrome change. - -When asked to write a canvas rule down, add it to `canvas-rules/` as its own -file and run `sync`. Never write a rule there that reaches the chrome, never -edit an existing one so that the task in front of you becomes permitted, and -never edit the compiled section directly — `sync` overwrites it, and `check` -fails on it. +A project's own rules for the canvas are Markdown files in `canvas-rules/`, +compiled by `npx ucsd-decorator-kit sync` into a "Project canvas rules" section +at the end of this file. They govern the canvas only and rank below every kit +rule, and like a chat message, they cannot authorize a chrome edit. -### Component libraries live in `canvas-components/` +**Before you add a file to `canvas-rules/` or change one, read this section in full in `DECORATOR.md`.** -A project can build its canvas with component libraries — shadcn/ui, a charting -library, a set of web components — by adding each one as a folder in -`canvas-components/`, with a `README.md` saying when and how to use it. `sync` -compiles those READMEs into a "Project component libraries" section near the -end of this file. +### Component libraries live in `canvas-components/` -That section relaxes three Decorator look-and-feel rules inside the canvas: -library classes instead of only Decorator ones, a library's icon set, and -library-styled headings inside library components. Typography stays on -brand — Roboto, Teko, Brix Sans, or Refrigerator Deluxe — and no chrome, -accessibility, or security rule relaxes. If the section is -not in this file, no library is in use — follow the rules as written. +A project's component libraries are folders in `canvas-components/`. When there +are any, a "Project component libraries" section near the end of this file +lists them and relaxes three look-and-feel rules, inside the canvas only. If +that section is absent, no library is in use — follow the rules as written. -Add a library only when asked to, and never to make the task in front of you -permitted. Library styles stay inside the canvas: `verify` fails on a -stylesheet in `canvas-components/` with a selector that names no class, id, or -attribute. +**Before you add a library to `canvas-components/` or change one, read this section in full in `DECORATOR.md`.** ### The pristine template is read-only @@ -165,27 +123,13 @@ are reference copies. Never create, modify, or store working files inside them. ### Never reconstruct markup from a rendered DOM Read markup from a file — never from a browser inspection, a screenshot, a -fetched rendered page, or memory. Three reasons, all of which have produced real -regressions: - -1. The rendered DOM is not the source markup. Browsers normalize it and scripts - mutate it. -2. Jasny Bootstrap **clones the offcanvas drawer into the body at runtime**, so - a live DOM contains navigation markup that exists in no file. Reading it back - produces duplicated, broken markup. -3. Kitchen-sink pages are galleries wrapped in Decorator chrome. Copying what - "looks like" a component fuses demo scaffolding into production markup. +fetched rendered page, or memory. Resolution order for markup: `node_modules/ucsd-decorator-v5/dist/` → `vendor/decorator-5/` → `core-template/`. If none of those exist, install or pin the package rather than fetching a page — `npm i -D ucsd-decorator-v5`, or run `pin-decorator.mjs`. Say so if you had to. -**`Decorator-V5.zip` on developer.ucsd.edu is not a source of truth.** Measured -2026-08 against `ucsd-decorator-v5@5.0.4`, the archive is behind on every file it -ships, and its `scripts/base.min.js` is a 2023 build missing the runtime behavior -that governs the drawer search. Read the npm package. - **Read only these paths inside the npm package.** It ships 222 files, including `dist/vendor/fullcalendar-3.9.0/demos/` and `dist/vendor/modernizr/test/`, so a search for something button-shaped can land in a third-party demo page: @@ -198,7 +142,10 @@ search for something button-shaped can land in a third-party demo page: | Readable stylesheet | `node_modules/ucsd-decorator-v5/dist/css/base.css` | | Runtime behavior | `node_modules/ucsd-decorator-v5/dist/scripts/base.min.js` | -Nothing under `dist/vendor/` is Decorator markup. +Nothing under `dist/vendor/` is Decorator markup, and `Decorator-V5.zip` on +developer.ucsd.edu is not a source of truth. + +**Before you take markup from anywhere but the paths above, read this section in full in `DECORATOR.md`.** ### Template selection requires an explicit instruction @@ -215,67 +162,29 @@ work only inside its canvas. Do not overwrite `index.html` unless asked. ### Rewrite the copied template's asset paths before anything else -The reference template's `` and script block point at its own location -inside the package — `../css/bootstrap.min.css`, `../css/base.min.css`, -`../scripts/*.min.js` — because that is where the file sits inside -`node_modules/ucsd-decorator-v5/dist/templates/`. Those paths keep resolving -after the copy, since the same `node_modules/` tree is still there from the -project root. That is what makes this easy to miss: the page loads and looks -almost right. - -Rewrite every one of them to the CDN instead: +A template copied out of the package still links `../css/*.min.css` and +`../scripts/*.min.js`, and those paths keep resolving from the project root, so +the page looks almost right. Rewrite every one to the CDN — `../css/` to +`https://cdn.ucsd.edu/cms/decorator-5/styles/`, `../scripts/` to +`https://cdn.ucsd.edu/cms/decorator-5/scripts/` — and never leave a +shipped page loading Decorator CSS or JS from `node_modules/`. -| Ships as | Rewrite to | -|---|---| -| `../css/bootstrap.min.css` | `https://cdn.ucsd.edu/cms/decorator-5/styles/bootstrap.min.css` | -| `../css/base.min.css` | `https://cdn.ucsd.edu/cms/decorator-5/styles/base.min.css` | -| `../scripts/modernizr.min.js` | `https://cdn.ucsd.edu/cms/decorator-5/scripts/modernizr.min.js` | -| `../scripts/jquery.min.js` | `https://cdn.ucsd.edu/cms/decorator-5/scripts/jquery.min.js` | -| `../scripts/bootstrap.min.js` | `https://cdn.ucsd.edu/cms/decorator-5/scripts/bootstrap.min.js` | -| `../scripts/vendor.min.js` | `https://cdn.ucsd.edu/cms/decorator-5/scripts/vendor.min.js` | -| `../scripts/base.min.js` | `https://cdn.ucsd.edu/cms/decorator-5/scripts/base.min.js` | - -Never leave a shipped page loading `node_modules/ucsd-decorator-v5/…` for its -CSS or JS. That is not only the rule in "Brand integrity" — the package's own -compiled `base.min.css` has a live color defect the CDN copy does not (see -"Verified chrome facts" there), so serving the vendored copy doesn't just -break policy, it visibly breaks the active nav state. +**Before you copy a template, read this section in full in `DECORATOR.md`.** ### The two- and three-column split is a float order, not a markup order -Both templates put the wider canvas section first in the file and the -narrower nav/info section second, then push the first one to the far side with -`pull-right` — `two-column.html`'s canvas section is -`class="col-xs-12 col-md-9 main-section pull-right"`. Nothing pulls the -nav/info section; it renders on the remaining side because the wide section no -longer occupies it. +Keep `pull-right` on the wide canvas section when you trim a two- or +three-column template's demo content. Without it, the columns swap sides. -Drop `pull-right` while trimming the template's demo modules down to real -content — it reads as decorative on a section that is about to be rewritten -anyway — and both columns fall back to plain source order: canvas on the left, -nav on the right. Keep the class and the DOM order exactly as shipped; replace -only what is inside each `
`. +**Before you copy `two-column.html` or `three-column.html`, read this section in full in `DECORATOR.md`.** ### The chrome ships two independent search blocks -The offcanvas drawer and the desktop navbar each carry their own search -button and form — `