From 5ccd2fe5e50e651a40198cee47e0082ac9d8f9f8 Mon Sep 17 00:00:00 2001 From: Cristian Horta Date: Tue, 29 Sep 2026 20:22:49 -0700 Subject: [PATCH] Split CLAUDE.md into always-loaded rules and an on-demand DECORATOR.md; prepare 2.4.0 The generated CLAUDE.md had grown to 49,901 characters, past the 40,000 at which Claude Code warns that a memory file will impact performance, and Claude Code loads all of it in every session. An @DECORATOR.md import would not have helped: imported files load at launch too and count toward the same warnings. A marker in a rules/ section, , now moves what follows it to a generated DECORATOR.md. The rule files keep the rule above it and a pointer naming the task. CLAUDE.md drops to 24,739 characters, and AGENTS.md, .cursorrules, and the Copilot instructions shrink the same way. Component library READMEs compile into DECORATOR.md as well. sync adds DECORATOR.md to projects an earlier release set up, and sync and check print a note when a project's canvas rules push CLAUDE.md past 40,000. test/rules.test.mjs holds the kit's CLAUDE.md to 25,000 characters and checks that every pointer lands on a section. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/plugin.json | 2 +- .cursorrules | 643 +++----------------- .github/copilot-instructions.md | 643 +++----------------- AGENTS.md | 643 +++----------------- CHANGELOG.md | 32 + CLAUDE.md | 645 +++----------------- DECORATOR.md | 731 +++++++++++++++++++++++ README.md | 46 +- bin/cli.mjs | 79 ++- library/tritonai/ucsd-decorator/SKILL.md | 18 +- package.json | 2 +- rules/00-canvas.md | 90 ++- rules/10-brand-integrity.md | 44 +- rules/20-components.md | 30 +- rules/60-getting-started.md | 16 +- scripts/compile-rules.mjs | 3 +- scripts/lib/rules.mjs | 279 +++++++-- skills/ucsd-decorator/SKILL.md | 18 +- templates/canvas-components-README.md | 9 +- templates/canvas-rules-README.md | 3 + test/cli.test.mjs | 86 ++- test/package.test.mjs | 2 + test/rules.test.mjs | 209 +++++++ 23 files changed, 1953 insertions(+), 2320 deletions(-) create mode 100644 DECORATOR.md create mode 100644 test/rules.test.mjs 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 — `