From 8f4b9811d9e59a6c95147b8d28cde0a0c6f97b0f Mon Sep 17 00:00:00 2001 From: Cristian Horta Date: Wed, 23 Sep 2026 10:13:56 -0700 Subject: [PATCH] Let sites set their own site name; prepare 2.2.0 Renaming the site in the title band failed verify at tier 2, so every rename needed a human --accept. The site-title region now declares ignoreTextOf: ["a.title-header"], which drops only the text inside the two title links before the golden comparison and keeps their elements, classes, and href pinned. Tier 1 still compares the text across pages, and a new tier 3 hasText requirement keeps either link from being emptied. Tier 2 now re-canonicalizes the recorded golden tree under the current region options, so goldens accepted with 2.1.0 keep passing after upgrade. Rules, skill, and user guide tell agents to change only the text, on every page, and to always propose a short form for the link shown below 480px. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/plugin.json | 2 +- .cursorrules | 35 +++++++- .github/copilot-instructions.md | 35 +++++++- AGENTS.md | 35 +++++++- CHANGELOG.md | 36 ++++++++ CLAUDE.md | 35 +++++++- checks/README.md | 11 +++ checks/lib/chrome-contract.mjs | 71 ++++++++++++--- contracts/chrome-regions.json | 6 +- contracts/chrome-regions.schema.json | 5 ++ contracts/chrome-selectors.schema.json | 6 +- contracts/ucsd-decorator-5.json | 5 +- library/tritonai/ucsd-decorator/SKILL.md | 9 ++ .../references/canvas-contract.md | 9 +- .../references/protected-regions.md | 28 ++++++ package.json | 2 +- rules/00-canvas.md | 35 +++++++- skills/ucsd-decorator/SKILL.md | 9 ++ .../references/canvas-contract.md | 9 +- .../references/protected-regions.md | 28 ++++++ test/chrome-contract.test.mjs | 86 +++++++++++++++++++ test/fixtures/decorator-page.mjs | 20 ++++- user-guide/index.html | 3 +- 23 files changed, 492 insertions(+), 28 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 95e9ca0..ff0a586 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ucsd-decorator", - "version": "2.1.0", + "version": "2.2.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 8767f20..839719f 100644 --- a/.cursorrules +++ b/.cursorrules @@ -24,12 +24,45 @@ All new content, components, markup, and application logic go inside the canvas. **Chrome is not yours to edit.** That means the header, the title band, the `#uc-emergency` container, the desktop navbar, the mobile offcanvas drawer, both -search forms, the footer, and any embedded campus widget. +search forms, the footer, and any embedded campus widget. The one exception is +the wording of the site name in the title band, below. If a task appears to require a chrome change: **stop and say so.** Name the region, explain why the task seems to need it, and let a human decide. Do not 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. + +**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. + ### The chrome integrity gate is not yours to satisfy A separate automated check — `verify` (`checks/chrome-contract.mjs`, or diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4911f68..3d86c44 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -24,12 +24,45 @@ All new content, components, markup, and application logic go inside the canvas. **Chrome is not yours to edit.** That means the header, the title band, the `#uc-emergency` container, the desktop navbar, the mobile offcanvas drawer, both -search forms, the footer, and any embedded campus widget. +search forms, the footer, and any embedded campus widget. The one exception is +the wording of the site name in the title band, below. If a task appears to require a chrome change: **stop and say so.** Name the region, explain why the task seems to need it, and let a human decide. Do not 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. + +**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. + ### The chrome integrity gate is not yours to satisfy A separate automated check — `verify` (`checks/chrome-contract.mjs`, or diff --git a/AGENTS.md b/AGENTS.md index 747eff2..4c4d89e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,12 +24,45 @@ All new content, components, markup, and application logic go inside the canvas. **Chrome is not yours to edit.** That means the header, the title band, the `#uc-emergency` container, the desktop navbar, the mobile offcanvas drawer, both -search forms, the footer, and any embedded campus widget. +search forms, the footer, and any embedded campus widget. The one exception is +the wording of the site name in the title band, below. If a task appears to require a chrome change: **stop and say so.** Name the region, explain why the task seems to need it, and let a human decide. Do not 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. + +**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. + ### The chrome integrity gate is not yours to satisfy A separate automated check — `verify` (`checks/chrome-contract.mjs`, or diff --git a/CHANGELOG.md b/CHANGELOG.md index dbc5cdd..8f10e65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,41 @@ # Changelog +## 2.2.0 + +### Changed + +- **Sites can change their own site name.** Renaming the site — the text of + `a.title-header.title-header-large` and `a.title-header.title-header-short` + in the title band — used to fail `verify` at tier 2, so every rename needed + a human `--accept`. The `site-title` region now declares + `ignoreTextOf: ["a.title-header"]`: tier 2 drops the text inside those two + links and still pins their elements, classes, and `href`, and everything + else in the band, `a.title-logo` included. Tier 1 still compares the text, + so the name must match on every page. +- **Rule: "The site name is the one piece of chrome text you may change"** in + `rules/00-canvas.md`, with matching guidance in the skill and in + `references/protected-regions.md`. Agents change only the text, on every + page, and always propose a short form for the link that shows below 480px — + a word or an acronym ("Decorator V5" → "V5") — even when only the long name + was given. + +### Added + +- **`ignoreTextOf` on a chrome region** (`contracts/chrome-regions.json` and + its schema, and `chrome-regions.local.json` overlays). Like + `ignoreChildrenOf`, but drops only text, so an element added inside a + matching node still fails tier 2. +- **`hasText` requirement in tier 3 rules.** `site-title.branding` now + requires exactly one long and one short title link, each with text. An + emptied site name fails, and `--accept` cannot clear it. + +### Fixed + +- Tier 2 now re-canonicalizes the golden's recorded tree under the current + region options instead of comparing its stored hash. A golden accepted with + 2.1.0 or earlier keeps passing after the upgrade, and its recorded site name + no longer pins the new one. No project needs to re-run `--accept`. + ## 2.1.0 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 7f36c95..7b5d5c7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,12 +24,45 @@ All new content, components, markup, and application logic go inside the canvas. **Chrome is not yours to edit.** That means the header, the title band, the `#uc-emergency` container, the desktop navbar, the mobile offcanvas drawer, both -search forms, the footer, and any embedded campus widget. +search forms, the footer, and any embedded campus widget. The one exception is +the wording of the site name in the title band, below. If a task appears to require a chrome change: **stop and say so.** Name the region, explain why the task seems to need it, and let a human decide. Do not 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. + +**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. + ### The chrome integrity gate is not yours to satisfy A separate automated check — `verify` (`checks/chrome-contract.mjs`, or diff --git a/checks/README.md b/checks/README.md index 837f382..eed6cbf 100644 --- a/checks/README.md +++ b/checks/README.md @@ -273,6 +273,17 @@ project added its first one. `contracts/chrome-regions.json` already declares `ignoreChildrenOf` for the drawer's and navbar's nav-link lists, so this is handled by default rather than something each project has to discover. +**Drop site-owned text, not the markup around it.** The site name in the title +band is the site's to set, but the two `a.title-header` links carrying it are +chrome. The `site-title` region declares `ignoreTextOf: ["a.title-header"]`: +tier 2 drops the text inside those links and keeps everything else, so a +rename passes without `--accept` while an added `` or a changed `href` +still fails. Tier 1 compares the text, so every page must agree, and tier 3's +`hasText` requirement keeps either link from being emptied. Tier 2 also +re-canonicalizes the recorded tree under the current region options instead +of trusting its stored hash, so a golden accepted before a region gained an +ignore option keeps passing. + **Exclude routes that carry no chrome.** Standalone pages (a presentation deck, a bare redirect) will otherwise report total chrome loss. `discoverRoutes` only walks `*.html`; a route with no chrome markup at all needs to live diff --git a/checks/lib/chrome-contract.mjs b/checks/lib/chrome-contract.mjs index dc83913..a298b36 100644 --- a/checks/lib/chrome-contract.mjs +++ b/checks/lib/chrome-contract.mjs @@ -104,10 +104,13 @@ export function normalizeUrl(value, basePath) { * attributes emitted as a name-sorted array of pairs. `ignoreChildrenOf` * empties the children of any descendant (relative to `root`) matching one of * the given selectors — for build-generated content, like a data-driven nav - * list, whose wrapper is chrome but whose contents are not. + * list, whose wrapper is chrome but whose contents are not. `ignoreTextOf` + * drops only the text inside a matching descendant and keeps its elements — + * for a link whose wording belongs to the site but whose markup does not, + * like the title band's site name. */ -export function canonicalize(root, { basePath = "", ignoreChildrenOf = [] } = {}) { - function canonElement(node) { +export function canonicalize(root, { basePath = "", ignoreChildrenOf = [], ignoreTextOf = [] } = {}) { + function canonElement(node, inIgnoredText = false) { const attrs = []; for (const [name, rawValue] of node.attrs) { if (DROP_ATTRS.has(name)) continue; @@ -125,20 +128,45 @@ export function canonicalize(root, { basePath = "", ignoreChildrenOf = [] } = {} } attrs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)); const emptied = ignoreChildrenOf.some((selector) => matches(node, selector)); - const children = emptied ? [] : node.children.map(canonAny).filter(Boolean); + const textIgnored = inIgnoredText || ignoreTextOf.some((selector) => matches(node, selector)); + const children = emptied ? [] : node.children.map((child) => canonAny(child, textIgnored)).filter(Boolean); return { tag: node.tag, attrs, children }; } - function canonAny(node) { + function canonAny(node, inIgnoredText) { if (node.type === "comment") return null; if (node.type === "text") { + if (inIgnoredText) return null; const text = node.value.replace(/\s+/g, " ").trim(); return text ? { text } : null; } - return canonElement(node); + return canonElement(node, inIgnoredText); } return canonElement(root); } +/** + * Rebuild a parsed-element tree from a canonical one, so a golden recorded by + * an earlier release can be canonicalized again under today's region options. + * Without this, adding an ignore option to a region would fail every existing + * project's golden on the day it upgraded. + */ +export function fromCanonical(canonical, parent = null) { + if (canonical.text !== undefined) return { type: "text", value: canonical.text, parent }; + const node = { type: "element", tag: canonical.tag, attrs: canonical.attrs.map(([k, v]) => [k, v]), children: [], parent }; + node.children = canonical.children.map((child) => fromCanonical(child, node)); + return node; +} + +/** Tier 1 compares routes with each other, so it keeps text a site owns: the site name must still match on every page. */ +function consistencyOptions(region) { + return { ignoreChildrenOf: region.ignoreChildrenOf ?? [] }; +} + +/** Tier 2 compares against a recorded golden, so it also drops text a site owns. */ +function goldenOptions(region) { + return { ignoreChildrenOf: region.ignoreChildrenOf ?? [], ignoreTextOf: region.ignoreTextOf ?? [] }; +} + export function hashCanonical(canonical) { return createHash("sha256").update(JSON.stringify(canonical)).digest("hex"); } @@ -208,12 +236,12 @@ export function checkConsistency(pages, regions) { for (const region of regions) { const refNode = reference.found[region.id]; if (!refNode) continue; - const refCanon = canonicalize(refNode, { ignoreChildrenOf: region.ignoreChildrenOf ?? [] }); + const refCanon = canonicalize(refNode, consistencyOptions(region)); const refHash = hashCanonical(refCanon); for (const page of rest) { const node = page.found[region.id]; if (!node) continue; - const canon = canonicalize(node, { ignoreChildrenOf: region.ignoreChildrenOf ?? [] }); + const canon = canonicalize(node, consistencyOptions(region)); if (hashCanonical(canon) !== refHash) { findings.push({ kind: "chrome/consistent", @@ -234,7 +262,7 @@ export function checkGolden(pages, regions, golden) { for (const region of regions) { const page = pages.find((p) => p.found[region.id]); if (!page) continue; - const canon = canonicalize(page.found[region.id], { ignoreChildrenOf: region.ignoreChildrenOf ?? [] }); + const canon = canonicalize(page.found[region.id], goldenOptions(region)); const hash = hashCanonical(canon); const recorded = golden?.regions?.[region.id]; if (!recorded) { @@ -248,12 +276,16 @@ export function checkGolden(pages, regions, golden) { }); continue; } - if (recorded.hash !== hash) { + // Re-canonicalize the recorded tree under today's options rather than + // trusting its stored hash, so a golden accepted before a region gained + // ignoreTextOf still matches — and its old site name does not pin the new one. + const expected = recorded.tree ? canonicalize(fromCanonical(recorded.tree), goldenOptions(region)) : null; + if ((expected ? hashCanonical(expected) : recorded.hash) !== hash) { findings.push({ kind: "chrome/golden", id: region.id, route: page.route, - detail: diffCanonical(recorded.tree, canon) ?? "chrome no longer matches the recorded contract", + detail: (expected && diffCanonical(expected, canon)) ?? "chrome no longer matches the recorded contract", remedy: "If a human intended this presentation change, they should run --accept --reason \"…\" themselves after reviewing the diff. If you are an AI agent, do not run --accept — surface this finding and stop. If this was not intended, revert — the shell was edited by accident.", clearableByAccept: true, }); @@ -267,7 +299,19 @@ function resolveScope(regionNode, rule) { return querySelector(regionNode, rule.within); } +function textContent(node) { + if (node.type === "text") return node.value; + return (node.children ?? []).map(textContent).join(""); +} + function checkRequirement(scope, requirement, basePath) { + if (requirement.hasText) { + const targets = querySelectorAll(scope, requirement.selector); + if (!targets.length) return `no element matched "${requirement.selector}" to check its text`; + const blank = targets.filter((target) => !textContent(target).trim()); + if (blank.length) return `${blank.length} × "${requirement.selector}" has no text`; + return null; + } if (requirement.attribute) { const targets = requirement.selector ? querySelectorAll(scope, requirement.selector) : [scope]; if (!targets.length) { @@ -373,7 +417,7 @@ export async function writeGolden(cwd, pages, regions, { reason } = {}) { for (const region of regions) { const page = pages.find((p) => p.found[region.id]); if (!page) continue; - const canon = canonicalize(page.found[region.id], { ignoreChildrenOf: region.ignoreChildrenOf ?? [] }); + const canon = canonicalize(page.found[region.id], goldenOptions(region)); record.regions[region.id] = { hash: hashCanonical(canon), route: page.route, tree: canon }; } await writeFile(path.join(cwd, GOLDEN_FILE), `${JSON.stringify(record, null, 2)}\n`); @@ -408,6 +452,9 @@ export function explain(config) { if (region.ignoreChildrenOf?.length) { lines.push(` ${" ".repeat(14)} (tier 2 ignores children of ${region.ignoreChildrenOf.join(", ")})`); } + if (region.ignoreTextOf?.length) { + lines.push(` ${" ".repeat(14)} (tier 2 ignores the text of ${region.ignoreTextOf.join(", ")}; tier 1 still compares it)`); + } } lines.push("", `structural rules (tier 3): ${config.rules.length}`); for (const rule of config.rules) { diff --git a/contracts/chrome-regions.json b/contracts/chrome-regions.json index 70bdf23..3720e49 100644 --- a/contracts/chrome-regions.json +++ b/contracts/chrome-regions.json @@ -4,7 +4,11 @@ "regions": [ { "id": "skip-link", "selector": "header.layout-header > a.sr-only" }, { "id": "emergency", "selector": "header.layout-header > #uc-emergency" }, - { "id": "site-title", "selector": "header.layout-header > section.layout-title" }, + { + "id": "site-title", + "selector": "header.layout-header > section.layout-title", + "ignoreTextOf": ["a.title-header"] + }, { "id": "mobile-drawer", "selector": ".navmenu.navmenu-default.navmenu-fixed-left.offcanvas:not(.offcanvas-clone)", diff --git a/contracts/chrome-regions.schema.json b/contracts/chrome-regions.schema.json index fe3047c..e79986f 100644 --- a/contracts/chrome-regions.schema.json +++ b/contracts/chrome-regions.schema.json @@ -32,6 +32,11 @@ "type": "array", "items": { "type": "string" }, "description": "Selectors (relative to this region) whose children are emptied before tier 2 hashing. For content rendered from a data file — e.g. the page-navigation
    inside the drawer and navbar — the wrapper is chrome but its per-project contents are not, so hashing them would make every project's golden fail on its own nav links." + }, + "ignoreTextOf": { + "type": "array", + "items": { "type": "string" }, + "description": "Selectors (relative to this region) whose text is dropped before tier 2 hashing, while their elements and attributes stay pinned. For wording a site owns inside chrome markup it does not — the long and short site name in a.title-header. Tier 1 still compares the text, so the name must match on every page." } } } diff --git a/contracts/chrome-selectors.schema.json b/contracts/chrome-selectors.schema.json index 5414ab6..70755b1 100644 --- a/contracts/chrome-selectors.schema.json +++ b/contracts/chrome-selectors.schema.json @@ -55,7 +55,7 @@ }, "requirement": { "type": "object", - "description": "Either a count assertion (selector + count) or an attribute assertion (attribute + equals/equalsUrl/absent, optionally targeted by selector).", + "description": "A count assertion (selector + count), an attribute assertion (attribute + equals/equalsUrl/absent, optionally targeted by selector), or a text assertion (selector + hasText).", "properties": { "selector": { "type": "string" }, "count": { @@ -75,6 +75,10 @@ "absent": { "type": "boolean", "description": "The attribute must not be present." + }, + "hasText": { + "type": "boolean", + "description": "Every element matching selector must contain non-whitespace text. Pairs with a region's ignoreTextOf: tier 2 lets the wording change, and this keeps it from being emptied." } }, "anyOf": [{ "required": ["selector"] }, { "required": ["attribute"] }] diff --git a/contracts/ucsd-decorator-5.json b/contracts/ucsd-decorator-5.json index fd23a68..1025ae2 100644 --- a/contracts/ucsd-decorator-5.json +++ b/contracts/ucsd-decorator-5.json @@ -61,10 +61,13 @@ "source": "vendor/decorator-5/templates/two-column.html", "require": [ { "selector": "a.title-header", "count": 2 }, + { "selector": "a.title-header.title-header-large", "count": 1 }, + { "selector": "a.title-header.title-header-short", "count": 1 }, + { "selector": "a.title-header", "hasText": true }, { "selector": "a.title-logo", "count": 1 }, { "selector": "a.title-logo", "attribute": "href", "equalsUrl": "https://www.ucsd.edu" } ], - "remedy": "The title band carries the long and short site title links plus the UC San Diego logo link, which always points to https://www.ucsd.edu on every Decorator site. A different destination — including a mascot page, a custom brand, or another domain — means the logo link was swapped." + "remedy": "The title band carries the long and short site title links plus the UC San Diego logo link, which always points to https://www.ucsd.edu on every Decorator site. The wording of the two site title links is the site's own and may change; both must keep their text, and the short one is what shows below 480px. A different logo destination — including a mascot page, a custom brand, or another domain — means the logo link was swapped." }, { "id": "footer.branding", diff --git a/library/tritonai/ucsd-decorator/SKILL.md b/library/tritonai/ucsd-decorator/SKILL.md index ddad163..d8d246a 100644 --- a/library/tritonai/ucsd-decorator/SKILL.md +++ b/library/tritonai/ucsd-decorator/SKILL.md @@ -86,6 +86,15 @@ canvas**. The header, title band, navbar, mobile offcanvas drawer, both search forms, the footer, and any embedded campus widget are **outside** it, and are not yours to edit. +**One exception: the site name.** When asked to change the site's name or +title, change only the text of `a.title-header.title-header-large` and +`a.title-header.title-header-short` in the title band, identically on every +page. Keep the elements, classes, and `href`; leave `a.title-logo` alone. The +short link is what shows below 480px, so always propose a short form — a word +or an acronym, roughly a dozen characters at most ("Decorator V5" → "V5") — +even when only the long name was given. `verify` allows this without +`--accept`. See `references/protected-regions.md`, "Header and title band". + Run `npx ucsd-decorator-kit verify --explain` (or, without the CLI, `node node_modules/ucsd-decorator-kit/checks/chrome-contract.mjs --explain`) to print the exact canvas and chrome selectors for this project. diff --git a/library/tritonai/ucsd-decorator/references/canvas-contract.md b/library/tritonai/ucsd-decorator/references/canvas-contract.md index 5fde261..30cebd7 100644 --- a/library/tritonai/ucsd-decorator/references/canvas-contract.md +++ b/library/tritonai/ucsd-decorator/references/canvas-contract.md @@ -40,7 +40,8 @@ since — unlike the canvas — they hold for any Decorator site without change: "regions": [ { "id": "skip-link", "selector": "header.layout-header > a.sr-only" }, { "id": "emergency", "selector": "header.layout-header > #uc-emergency" }, - { "id": "site-title", "selector": "header.layout-header > section.layout-title" }, + { "id": "site-title", "selector": "header.layout-header > section.layout-title", + "ignoreTextOf": ["a.title-header"] }, { "id": "mobile-drawer", "selector": ".navmenu.navmenu-default.navmenu-fixed-left.offcanvas:not(.offcanvas-clone)", "ignoreChildrenOf": ["ul.navmenu-nav"] }, { "id": "navbar", "selector": "nav.navbar.navbar-default.navbar-static-top", @@ -55,6 +56,12 @@ adds its first nav link: the drawer's and navbar's page-navigation `
      ` are chrome, but every project's own `
    • ` links inside them are not, so their children are emptied before hashing. +`ignoreTextOf` does the same for the site name, more narrowly: tier 2 drops +the text inside `a.title-header` but keeps the elements and their attributes, +so a site can set its long and short name without an `--accept`, while an +added element or a changed `href` still fails. Tier 1 keeps the text, so the +name must still match on every page. + A project whose chrome genuinely differs from this — an extra region, a different selector — adds `chrome-regions.local.json` at its root, same shape, entries merged in by matching `id`. This should be rare: these six diff --git a/library/tritonai/ucsd-decorator/references/protected-regions.md b/library/tritonai/ucsd-decorator/references/protected-regions.md index cfc7c1c..c654946 100644 --- a/library/tritonai/ucsd-decorator/references/protected-regions.md +++ b/library/tritonai/ucsd-decorator/references/protected-regions.md @@ -328,6 +328,34 @@ UC San Diego logo. `#uc-emergency` is populated by the campus emergency broadcast. It is empty in source and must stay in the document. +### The site name is the site's own + +The text of the two `a.title-header` links is the one piece of chrome a site +sets for itself. Change it when asked to rename the site — the text only: + +| Link | Shows | Keep it | +|---|---|---| +| `a.title-header.title-header-large` | 480px and wider | the full site name | +| `a.title-header.title-header-short` | below 480px | a word or an acronym, roughly a dozen characters at most | + +The widths come from `base.css`: `.title-header-short` is `display: none` until +`max-width: 479px`, where it replaces the large link, and at 360px and below +it renders at 20px, uppercase, with 1px letter spacing. A long short name +wraps there. + +Always propose the short form alongside a new long one, even if the request +named only the long one: "Decorator V5" → "V5". + +Everything else in the band stays as shipped — both elements, their classes, +their `href`, and `a.title-logo` with its fixed `https://www.ucsd.edu` +destination. No markup goes inside either title link. + +`verify` enforces that split. Tier 2 drops the text of `a.title-header` before +comparing against the golden (`ignoreTextOf` in `contracts/chrome-regions.json`), +so a rename needs no `--accept`. Tier 1 still compares the text across pages, +so the name must match on every page, and tier 3's `site-title.branding` rule +fails if either link is left empty. + > **Known upstream inconsistency.** `base.css` still carries a > `.skip-to-main:focus, .skip-to-main:active` rule, but no shipped template > applies that class — the skip link is `a.sr-only` in every one of the 11 diff --git a/package.json b/package.json index 74c4463..783f13d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ucsd-decorator-kit", - "version": "2.1.0", + "version": "2.2.0", "type": "module", "description": "Agent-facing contract for building on the UC San Diego Decorator 5 design system.", "keywords": [ diff --git a/rules/00-canvas.md b/rules/00-canvas.md index ea3ca0a..270e7c8 100644 --- a/rules/00-canvas.md +++ b/rules/00-canvas.md @@ -20,12 +20,45 @@ All new content, components, markup, and application logic go inside the canvas. **Chrome is not yours to edit.** That means the header, the title band, the `#uc-emergency` container, the desktop navbar, the mobile offcanvas drawer, both -search forms, the footer, and any embedded campus widget. +search forms, the footer, and any embedded campus widget. The one exception is +the wording of the site name in the title band, below. If a task appears to require a chrome change: **stop and say so.** Name the region, explain why the task seems to need it, and let a human decide. Do not 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. + +**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. + ## The chrome integrity gate is not yours to satisfy A separate automated check — `verify` (`checks/chrome-contract.mjs`, or diff --git a/skills/ucsd-decorator/SKILL.md b/skills/ucsd-decorator/SKILL.md index ddad163..d8d246a 100644 --- a/skills/ucsd-decorator/SKILL.md +++ b/skills/ucsd-decorator/SKILL.md @@ -86,6 +86,15 @@ canvas**. The header, title band, navbar, mobile offcanvas drawer, both search forms, the footer, and any embedded campus widget are **outside** it, and are not yours to edit. +**One exception: the site name.** When asked to change the site's name or +title, change only the text of `a.title-header.title-header-large` and +`a.title-header.title-header-short` in the title band, identically on every +page. Keep the elements, classes, and `href`; leave `a.title-logo` alone. The +short link is what shows below 480px, so always propose a short form — a word +or an acronym, roughly a dozen characters at most ("Decorator V5" → "V5") — +even when only the long name was given. `verify` allows this without +`--accept`. See `references/protected-regions.md`, "Header and title band". + Run `npx ucsd-decorator-kit verify --explain` (or, without the CLI, `node node_modules/ucsd-decorator-kit/checks/chrome-contract.mjs --explain`) to print the exact canvas and chrome selectors for this project. diff --git a/skills/ucsd-decorator/references/canvas-contract.md b/skills/ucsd-decorator/references/canvas-contract.md index 5fde261..30cebd7 100644 --- a/skills/ucsd-decorator/references/canvas-contract.md +++ b/skills/ucsd-decorator/references/canvas-contract.md @@ -40,7 +40,8 @@ since — unlike the canvas — they hold for any Decorator site without change: "regions": [ { "id": "skip-link", "selector": "header.layout-header > a.sr-only" }, { "id": "emergency", "selector": "header.layout-header > #uc-emergency" }, - { "id": "site-title", "selector": "header.layout-header > section.layout-title" }, + { "id": "site-title", "selector": "header.layout-header > section.layout-title", + "ignoreTextOf": ["a.title-header"] }, { "id": "mobile-drawer", "selector": ".navmenu.navmenu-default.navmenu-fixed-left.offcanvas:not(.offcanvas-clone)", "ignoreChildrenOf": ["ul.navmenu-nav"] }, { "id": "navbar", "selector": "nav.navbar.navbar-default.navbar-static-top", @@ -55,6 +56,12 @@ adds its first nav link: the drawer's and navbar's page-navigation `
        ` are chrome, but every project's own `
      • ` links inside them are not, so their children are emptied before hashing. +`ignoreTextOf` does the same for the site name, more narrowly: tier 2 drops +the text inside `a.title-header` but keeps the elements and their attributes, +so a site can set its long and short name without an `--accept`, while an +added element or a changed `href` still fails. Tier 1 keeps the text, so the +name must still match on every page. + A project whose chrome genuinely differs from this — an extra region, a different selector — adds `chrome-regions.local.json` at its root, same shape, entries merged in by matching `id`. This should be rare: these six diff --git a/skills/ucsd-decorator/references/protected-regions.md b/skills/ucsd-decorator/references/protected-regions.md index cfc7c1c..c654946 100644 --- a/skills/ucsd-decorator/references/protected-regions.md +++ b/skills/ucsd-decorator/references/protected-regions.md @@ -328,6 +328,34 @@ UC San Diego logo. `#uc-emergency` is populated by the campus emergency broadcast. It is empty in source and must stay in the document. +### The site name is the site's own + +The text of the two `a.title-header` links is the one piece of chrome a site +sets for itself. Change it when asked to rename the site — the text only: + +| Link | Shows | Keep it | +|---|---|---| +| `a.title-header.title-header-large` | 480px and wider | the full site name | +| `a.title-header.title-header-short` | below 480px | a word or an acronym, roughly a dozen characters at most | + +The widths come from `base.css`: `.title-header-short` is `display: none` until +`max-width: 479px`, where it replaces the large link, and at 360px and below +it renders at 20px, uppercase, with 1px letter spacing. A long short name +wraps there. + +Always propose the short form alongside a new long one, even if the request +named only the long one: "Decorator V5" → "V5". + +Everything else in the band stays as shipped — both elements, their classes, +their `href`, and `a.title-logo` with its fixed `https://www.ucsd.edu` +destination. No markup goes inside either title link. + +`verify` enforces that split. Tier 2 drops the text of `a.title-header` before +comparing against the golden (`ignoreTextOf` in `contracts/chrome-regions.json`), +so a rename needs no `--accept`. Tier 1 still compares the text across pages, +so the name must match on every page, and tier 3's `site-title.branding` rule +fails if either link is left empty. + > **Known upstream inconsistency.** `base.css` still carries a > `.skip-to-main:focus, .skip-to-main:active` rule, but no shipped template > applies that class — the skip link is `a.sr-only` in every one of the 11 diff --git a/test/chrome-contract.test.mjs b/test/chrome-contract.test.mjs index 09496e3..be3c37c 100644 --- a/test/chrome-contract.test.mjs +++ b/test/chrome-contract.test.mjs @@ -11,6 +11,7 @@ import { canonicalize, diffCanonical, discoverRoutes, + fromCanonical, hashCanonical, loadConfig, readGolden, @@ -103,6 +104,91 @@ describe("canonicalize", () => { }); }); +describe("canonicalize: ignoreTextOf", () => { + it("drops text inside a matching descendant and keeps its elements and attributes", () => { + const doc = parseHTML(`
        Long name

        kept

        `); + const canon = canonicalize(querySelector(doc, "section"), { ignoreTextOf: ["a.t"] }); + assert.deepEqual(canon.children[0], { + tag: "a", + attrs: [["class", "t"], ["href", "/"]], + children: [{ tag: "b", attrs: [], children: [] }], + }); + assert.deepEqual(canon.children[1].children, [{ text: "kept" }]); + }); + + it("fromCanonical round-trips, so a recorded tree can be canonicalized again", () => { + const doc = parseHTML(``); + const canon = canonicalize(querySelector(doc, "nav")); + assert.deepEqual(canonicalize(fromCanonical(canon)), canon); + }); +}); + +describe("site-title: the site name is the site's to set", () => { + async function accepted() { + const dir = await project(); + await writePages(dir); + const clean = await runStructural(dir); + await writeGolden(dir, clean.pages, clean.config.regions); + return dir; + } + + it("renaming the long and short title on every page leaves all tiers green", async () => { + const dir = await accepted(); + await writePages(dir, { siteName: "Decorator V5", siteShort: "V5" }); + const { findings } = await runStructural(dir); + assert.deepEqual(findings, []); + }); + + it("tier 1 still requires the same site name on every page", async () => { + const dir = await accepted(); + await writeFile(path.join(dir, "about.html"), decoratorPage("About", { siteName: "Decorator V5" })); + const { findings } = await runStructural(dir); + assert.ok(findings.some((f) => f.kind === "chrome/consistent" && f.id === "site-title")); + assert.ok(!findings.some((f) => f.kind === "chrome/golden")); + }); + + it("an element inside a title link is still a golden change", async () => { + const dir = await accepted(); + await writePages(dir, { siteNameMarkup: `Brand` }); + const { findings } = await runStructural(dir); + assert.ok(findings.some((f) => f.kind === "chrome/golden" && f.id === "site-title")); + }); + + it("a changed title link href is still a golden change", async () => { + const dir = await accepted(); + const page = decoratorPage("Home").replace(`href="index.html" class="title-header title-header-short"`, `href="/elsewhere/" class="title-header title-header-short"`); + await writeFile(path.join(dir, "index.html"), page); + await writeFile(path.join(dir, "about.html"), page); + const { findings } = await runStructural(dir); + assert.ok(findings.some((f) => f.kind === "chrome/golden" && f.id === "site-title")); + }); + + it("an emptied title link fails tier 3, which --accept cannot clear", async () => { + const dir = await accepted(); + await writePages(dir, { siteShort: "" }); + const { findings } = await runStructural(dir); + const hit = findings.find((f) => f.id === "site-title.branding"); + assert.ok(hit); + assert.match(hit.detail, /has no text/); + assert.equal(hit.clearableByAccept, false); + }); + + it("a golden recorded before ignoreTextOf existed still passes, before and after a rename", async () => { + const dir = await project(); + await writePages(dir); + const { pages, config } = await runStructural(dir); + // What 2.1.0 wrote: the site-title tree with its text still in it. + const legacyRegions = config.regions.map(({ ignoreTextOf, ...region }) => region); + await writeGolden(dir, pages, legacyRegions); + const legacy = await readGolden(dir); + assert.match(JSON.stringify(legacy.regions["site-title"].tree), /Site Name/); + + assert.deepEqual((await runStructural(dir)).findings, []); + await writePages(dir, { siteName: "Decorator V5", siteShort: "V5" }); + assert.deepEqual((await runStructural(dir)).findings, []); + }); +}); + describe("diffCanonical", () => { it("names the node and the attribute that changed", () => { const a = canonicalize(querySelector(parseHTML(`
        `), "form")); diff --git a/test/fixtures/decorator-page.mjs b/test/fixtures/decorator-page.mjs index 3ec38b6..3401235 100644 --- a/test/fixtures/decorator-page.mjs +++ b/test/fixtures/decorator-page.mjs @@ -9,8 +9,22 @@ // href without touching its count, and `footerBroken` drops the footer-links // list and the wordmark image entirely. Both defaults match the real markup // pinned into vendor/decorator-5/templates/two-column.html on 2026-08-19. +// +// `siteName` and `siteShort` set the text of the long and short title links, +// which a site owns; `siteNameMarkup` replaces the long link's contents with +// raw markup, to prove that only text — not elements — is exempt. -export function decoratorPage(title, { searchAsLink = false, logoHref = "https://www.ucsd.edu", footerBroken = false } = {}) { +export function decoratorPage( + title, + { + searchAsLink = false, + logoHref = "https://www.ucsd.edu", + footerBroken = false, + siteName = "Site Name", + siteShort = "Short", + siteNameMarkup = null, + } = {}, +) { const footerContent = footerBroken ? `

        © 2026 UC San Diego

        ` : ` @@ -34,8 +48,8 @@ export function decoratorPage(title, { searchAsLink = false, logoHref = "https:/ Skip to main content
        - Site Name - Short + ${siteNameMarkup ?? siteName} + ${siteShort}
        diff --git a/user-guide/index.html b/user-guide/index.html index 390197d..25f7a07 100644 --- a/user-guide/index.html +++ b/user-guide/index.html @@ -1297,6 +1297,7 @@

        Do

      • Update the drawer, the navbar, and the side nav when you add a page.
      • Give each module images at its documented size, with alt text.
      • Keep both search forms, in the drawer and the navbar, as shipped.
      • +
      • Change the site name as text only, in both title links, with a short form for phones.
      @@ -1306,7 +1307,7 @@

      Don't

      • Use *-success, *-info, *-warning, or *-danger classes.
      • Use pagination, progress-bar, label-*, or list-group. They render in stock Bootstrap colors.
      • -
      • Edit the header, title band, navbar, drawer, search, or footer.
      • +
      • Edit the header, title band, navbar, drawer, search, or footer, apart from the site name's wording.
      • Add <style> blocks or style="" attributes.
      • Paint the page background or stretch a color past the canvas.
      • Add Font Awesome or any font besides Roboto, Teko, Brix Sans, or Refrigerator Deluxe.