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.