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: `` });
+ 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
? `