The design language that makes your AI harness better at design.
JavaScript
Allow documented sidecar shadow colors in shadow contexts (#547)
Abdul Wahab92c857a9ef3c
diff --git a/cli/engine/design-system.mjs b/cli/engine/design-system.mjsindex b9d9f3f69..87320dbe5 100644--- a/cli/engine/design-system.mjs+++ b/cli/engine/design-system.mjs@@ -14,6 +14,10 @@ const FALLBACK_DIRS = ['.agents/context', 'docs'];// boundaries; `.impeccable` is our own project marker.const PROJECT_ROOT_MARKERS = ['.git', 'package.json', '.impeccable'];const COLOR_CHANNEL_TOLERANCE = 6;+// Shadow blacks at different alphas are different tokens (0.28 vs 0.55 is the+// difference between a documented shadow and drift), so shadow matching cannot+// reuse the r/g/b-only channel tolerance.+const SHADOW_ALPHA_TOLERANCE = 0.02;const RADIUS_TOLERANCE_PX = 0.5;const FONT_SIZE_TOLERANCE_PX = 0.5;const FONT_SIZE_LITERAL_RE = /^-?[\d.]+(?:px|rem)$/;@@ -474,6 +478,25 @@ function addSidecarRadii(out, sidecar) {}}+// Sidecar `extensions.shadows` entries ({ name, value, purpose }) carry the+// documented shadow vocabulary that Stitch's frontmatter schema can't hold.+// Their colors go into a separate allowlist — NOT allowedColorKeys — because a+// shadow black is only documented *as a shadow*: feeding it into the general+// color allowlist would legalize #000 as a page ground (alpha is dropped from+// colorKey), which is the hole issue #547 warns against.+function addSidecarShadows(out, sidecar) {+ const shadows = sidecar?.extensions?.shadows;+ if (!Array.isArray(shadows)) return;++ for (const entry of shadows) {+ if (typeof entry?.value !== 'string') continue;+ for (const match of entry.value.matchAll(CSS_COLOR_RE)) {+ const parsed = parseDesignColor(match[0]);+ if (parsed) out.allowedShadowColors.push({ color: parsed });+ }+ }+}+function normalizeDesignSystem(input = {}) {const frontmatter = input.frontmatter || {};const sidecar = input.sidecar || null;@@ -486,6 +509,7 @@ function normalizeDesignSystem(input = {}) {allowedColorKeys: new Map(),allowedRadii: [],allowedFontSizes: [],+ allowedShadowColors: [],hasPillRadius: false,};@@ -495,6 +519,7 @@ function normalizeDesignSystem(input = {}) {addSidecarColors(out, sidecar);addRoundedScale(out, frontmatter.rounded);addSidecarRadii(out, sidecar);+ addSidecarShadows(out, sidecar);out.hasFonts = out.allowedFonts.size > 0;out.hasColors = out.allowedColorKeys.size > 0;@@ -614,6 +639,20 @@ function isAllowedColorRaw(raw, designSystem) {return false;}+// A color is a documented shadow color only when both the r/g/b channels AND+// the alpha match a sidecar shadow token's color. Alpha has to be compared+// here because colorKey()/colorsClose() drop it, and a match on r/g/b alone+// would let every black at every alpha through.+function isAllowedShadowColorRaw(raw, designSystem) {+ if (!designSystem?.allowedShadowColors?.length) return false;+ const parsed = parseDesignColor(String(raw || '').trim().toLowerCase());+ if (!parsed) return false;+ return designSystem.allowedShadowColors.some(entry =>+ colorsClose(parsed, entry.color) &&+ Math.abs((parsed.a ?? 1) - (entry.color.a ?? 1)) <= SHADOW_ALPHA_TOLERANCE,+ );+}+function isAllowedRadiusRaw(raw, designSystem) {if (!designSystem?.hasRadii) return true;const text = String(raw || '').trim().toLowerCase();@@ -691,6 +730,23 @@ function isProbablyColorLiteral(line, match) {return styleContext || cssFunctionContext || jsColorKeyContext;}+// True when the color literal sits inside a box-shadow / text-shadow value —+// the only contexts where a documented shadow color is legal. Anchored to the+// end of `before` (no ; } { or quote in between) so a shadow property earlier+// on the line can't leak the allowance into a later declaration. Kept separate+// from isProbablyColorLiteral(), which stays a boolean for its existing call+// sites and deliberately discards which property matched.+function isShadowPropertyContext(line, match) {+ const index = match.index ?? -1;+ if (index < 0) return false;+ const before = line.slice(0, index);+ // Unlike jsColorKeyContext, the JS tail admits commas: a multi-layer shadow+ // string is comma-separated, and a later property on the same line is still+ // blocked because it sits past the string's closing quote.+ return /(?:^|[{\s;"'`(,])(?:box-shadow|text-shadow)\s*:\s*[^;{}"'`]*$/i.test(before)+ || /(?:^|[,{]\s*)(?:boxShadow|textShadow)\s*[:=]\s*["'`]?[^"'`}]*$/i.test(before);+}+function isInsideCssAttributeSelector(line, index) {if (index < 0) return false;const before = line.slice(0, index);@@ -824,6 +880,7 @@ function checkSourceDesignSystem(content, filePath, options = {}) {if (!isProbablyColorLiteral(line, match)) continue;const raw = cssColorLabel(match[0]);if (isAllowedColorRaw(raw, designSystem)) continue;+ if (isShadowPropertyContext(line, match) && isAllowedShadowColorRaw(raw, designSystem)) continue;findings.push(makeDesignFinding('design-system-color',filePath,@@ -1038,6 +1095,7 @@ export {loadDesignSystemForCwd,isAllowedFont,isAllowedColorRaw,+ isAllowedShadowColorRaw,isAllowedRadiusRaw,isAllowedFontSizeRaw,checkSourceDesignSystem,diff --git a/tests/design-system.test.mjs b/tests/design-system.test.mjsindex 7999df940..6dc3bcffa 100644--- a/tests/design-system.test.mjs+++ b/tests/design-system.test.mjs@@ -13,6 +13,7 @@ import {checkSourceDesignSystem,collectStaticDesignSystemFindings,isAllowedColorRaw,+ isAllowedShadowColorRaw,isAllowedFont,isAllowedRadiusRaw,isAllowedFontSizeRaw,@@ -282,6 +283,9 @@ rounded:roundedMeta: {lg: { canonical: '24px' },},+ shadows: [+ { name: 'ambient-low', value: '0 4px 24px rgba(0,0,0,0.12)', purpose: 'Diffuse hover glow.' },+ ],},}));@@ -296,6 +300,8 @@ rounded:assert.equal(isAllowedColorRaw('#d55a42', loaded), true);assert.equal(isAllowedRadiusRaw('80px', loaded), true);assert.equal(isAllowedRadiusRaw('24px', loaded), true);+ assert.equal(isAllowedShadowColorRaw('rgba(0, 0, 0, 0.12)', loaded), true);+ assert.equal(isAllowedShadowColorRaw('rgba(0, 0, 0, 0.5)', loaded), false);});it('unescapes YAML-escaped quotes around multi-word font families (issue #428)', () => {@@ -474,6 +480,106 @@ const badge = { className: "text-[10px]" };});});+describe('sidecar shadow tokens (issue #547)', () => {+ // Mirrors the sidecar `extensions.shadows` schema from document.md Step 4b.+ function shadowDesignSystem() {+ return normalizeDesignSystem({+ frontmatter: {+ colors: { ink: '#241f1a', paper: '#f7f4ee' },+ },+ sidecar: {+ extensions: {+ shadows: [+ {+ name: 'outset',+ value: 'inset 0 1px 0 oklch(1 0 0 / 0.07), 0 1px 2px oklch(0 0 0 / 0.28), 0 4px 12px oklch(0 0 0 / 0.22)',+ purpose: 'Default card shadow.',+ },+ ],+ },+ },+ });+ }++ it('matches documented shadow colors on alpha, not just r/g/b', () => {+ const designSystem = shadowDesignSystem();+ assert.equal(isAllowedShadowColorRaw('oklch(0 0 0 / 0.28)', designSystem), true);+ assert.equal(isAllowedShadowColorRaw('rgba(0, 0, 0, 0.28)', designSystem), true);+ assert.equal(isAllowedShadowColorRaw('oklch(1 0 0 / 0.07)', designSystem), true);+ // Same black, undocumented alpha: the r/g/b channels alone must not match.+ assert.equal(isAllowedShadowColorRaw('oklch(0 0 0 / 55%)', designSystem), false);+ assert.equal(isAllowedShadowColorRaw('#000', designSystem), false);+ // Shadow tokens must not switch the general color rule's allowlist on.+ assert.equal(isAllowedColorRaw('oklch(0 0 0 / 0.28)', designSystem), false);+ });++ it('allows documented shadow colors in shadow contexts only', () => {+ const designSystem = shadowDesignSystem();+ const findings = checkSourceDesignSystem(`+.a { box-shadow: 0 1px 2px oklch(0 0 0 / 0.28); }+.b { box-shadow: 0 20px 50px oklch(0 0 0 / 55%); }+.c { background: #000; }+.d { background: oklch(0 0 0 / 0.28); }+.e { text-shadow: 0 1px 2px oklch(0 0 0 / 0.28); }+.f { box-shadow: inset 0 1px 0 oklch(1 0 0 / 0.07), 0 4px 12px oklch(0 0 0 / 0.22); }+const card = { boxShadow: "0 1px 2px rgba(0, 0, 0, 0.28)" };+const layered = { boxShadow: "0 1px 2px rgba(0, 0, 0, 0.28), 0 4px 12px rgba(0, 0, 0, 0.22)" };+const bad = { color: "rgba(0, 0, 0, 0.28)" };+const leak = { boxShadow: "0 1px 2px rgba(0, 0, 0, 0.28)", color: "rgba(0, 0, 0, 0.28)" };+`, '/tmp/shadows.css', { designSystem });+ const colors = findings.filter((item) => item.antipattern === 'design-system-color');++ // .a, .e, .f, and both JS boxShadow strings (including the second layer+ // past the comma) pass; .b (undocumented alpha), .c (forbidden ground),+ // .d (documented alpha outside a shadow), and both JS color keys still+ // fire — the `leak` line proves the closing quote stops the shadow+ // context from reaching a later property. A fix that silences .d has+ // stopped discriminating between shadow usage and page grounds.+ assert.deepEqual(+ colors.map((item) => [item.line, item.ignoreValue]),+ [+ [3, 'oklch(0 0 0 / 55%)'],+ [4, '#000'],+ [5, 'oklch(0 0 0 / 0.28)'],+ [10, 'rgba(0, 0, 0, 0.28)'],+ [11, 'rgba(0, 0, 0, 0.28)'],+ ],+ );+ });++ it('abstains from the color rule entirely when only shadows are documented', () => {+ // A shadows-only sidecar must not switch hasColors on: with no palette to+ // measure against, the engine abstains rather than guesses, same as every+ // other design-system rule.+ const designSystem = normalizeDesignSystem({+ sidecar: {+ extensions: {+ shadows: [{ name: 'outset', value: '0 1px 2px oklch(0 0 0 / 0.28)' }],+ },+ },+ });+ assert.equal(designSystem.hasColors, false);+ const findings = checkSourceDesignSystem(+ '.c { background: #000; }',+ '/tmp/shadows-only.css',+ { designSystem },+ );+ assert.equal(findings.some((item) => item.antipattern === 'design-system-color'), false);+ });++ it('does not allow a later declaration to inherit shadow context from earlier on the line', () => {+ const designSystem = shadowDesignSystem();+ const findings = checkSourceDesignSystem(+ '.x { box-shadow: 0 1px 2px oklch(0 0 0 / 0.28); background: oklch(0 0 0 / 0.28); }',+ '/tmp/one-line.css',+ { designSystem },+ );+ const colors = findings.filter((item) => item.antipattern === 'design-system-color');+ assert.equal(colors.length, 1);+ assert.equal(colors[0].ignoreValue, 'oklch(0 0 0 / 0.28)');+ });+});+describe('collectStaticDesignSystemFindings()', () => {function makeElement(tagName, { text = '', attrs = {}, style = {}, parentElement = null } = {}) {return {