Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(ci): reduce the visual baseline to canonical frames (#5950)

Cindy Zhang1b1ef573d4f8
diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.md
index f9635ba825..8fce3327ad 100644
--- a/.github/scripts/visual-gate/README.md
+++ b/.github/scripts/visual-gate/README.md
@@ -130,8 +130,10 @@ written by CI, from the pinned runner label.
The gate asks two things, and only one of them is a screenshot.
-**Did anything move?** — the shot tiers, compared against an accepted baseline.
-Catches any visual regression, in any theme.
+**Did the canonical visual contract move?** — representative and explicitly
+tagged Core stories in Neutral, plus generated Probe coverage, compared against
+an accepted baseline. Theme-specific design still renders in Storybook, but it
+does not multiply the permanent screenshot baseline.
**Did each theming target's override actually reach the pixels?** — `gate.mjs
reach`, and no baseline is involved. A pixel diff cannot answer this: when an
diff --git a/.github/scripts/visual-gate/gate-context.test.mjs b/.github/scripts/visual-gate/gate-context.test.mjs
index 190d3eedc9..45b98549ba 100644
--- a/.github/scripts/visual-gate/gate-context.test.mjs
+++ b/.github/scripts/visual-gate/gate-context.test.mjs
@@ -59,6 +59,19 @@ beforeEach(() => {
afterEach(() => fs.rmSync(root, {recursive: true, force: true}));
+describe('stable release plan authority', () => {
+ it('owns a closed Neutral and Probe baseline without preserving obsolete keys', () => {
+ const source = fs.readFileSync(SCRIPT, 'utf8');
+ expect(source).toContain("const RELEASE_TIERS = ['surface', 'probe'];");
+ expect(source).toContain('storiesInStorybookGroups(');
+ expect(source).not.toContain('shots = withBaselineCoverage(');
+ expect(source).toContain('const baselineManifest = rawBaseline;');
+ expect(source).toContain(
+ 'readThemeCatalog(REPO_ROOT, config.baselineThemes)',
+ );
+ });
+});
+
describe('visual gate capture identity', () => {
it('records the GitHub run identity by default', () => {
expect(
diff --git a/.github/scripts/visual-gate/gate.mjs b/.github/scripts/visual-gate/gate.mjs
index 86fc5405a0..33eb371de1 100644
--- a/.github/scripts/visual-gate/gate.mjs
+++ b/.github/scripts/visual-gate/gate.mjs
@@ -47,8 +47,8 @@ import {
readThemeCatalog,
resolvePrVisualTotalShotLimit,
storiesInPackages,
+ storiesInStorybookGroups,
summarizeBaselineAccounting,
- withBaselineCoverage,
withThemeMetadata,
} from './lib/plan.mjs';
import {READ_TARGETS, emptyAccumulator, fold} from './lib/probe-reach.mjs';
@@ -60,7 +60,7 @@ import {loadConfig, loadThemeOverrides, loadThemingTargets} from './lib/sources.
const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
const EXIT = {clean: 0, crashed: 1, changed: 2};
-const RELEASE_TIERS = ['surface', 'theme-matrix'];
+const RELEASE_TIERS = ['surface', 'probe'];
const argv = process.argv.slice(2);
const command = argv[0];
@@ -78,7 +78,7 @@ const captureIdentity = () => ({
const config = loadConfig(REPO_ROOT);
const releaseMode = command === 'release';
-const themeCatalog = readThemeCatalog(REPO_ROOT);
+const themeCatalog = readThemeCatalog(REPO_ROOT, config.baselineThemes);
const storybookDir = path.resolve(flag('storybook-dir') ?? 'apps/storybook/dist');
const baselineDir = path.resolve(flag('baseline') ?? '.visual-baseline');
let outDir = path.resolve(flag('out') ?? '.visual-run');
@@ -193,7 +193,11 @@ async function plan() {
Object.keys(config.excludeStories),
REPO_ROOT,
);
- const stories = storiesInPackages(indexedStories, storyPackages);
+ const packageStories = storiesInPackages(indexedStories, storyPackages);
+ const stories = storiesInStorybookGroups(
+ packageStories,
+ config.stableStoryGroups,
+ );
const {manifest: baselineManifest} = readBaseline(baselineDir);
const componentThemes = acceptedVisualThemes(
baselineManifest,
@@ -267,11 +271,6 @@ async function plan() {
themeCatalog,
REPO_ROOT,
);
- shots = withBaselineCoverage(shots, {
- stories,
- baselineManifest: baselineAccount.manifest,
- themes: themeCatalog,
- });
}
shots = withThemeMetadata(shots, themeCatalog);
// A sample is for trying the rig out, never for a gate run: it is taken
@@ -449,7 +448,7 @@ async function check() {
];
const {manifest: rawBaseline, exists} = readBaseline(baselineDir);
- const baselineManifest = releaseMode ? baselineAccount.manifest : rawBaseline;
+ const baselineManifest = rawBaseline;
const blocker = exists ? incomparable(baselineManifest, manifest) : null;
if (blocker) {
failures.push({key: 'baseline', error: blocker});
@@ -561,7 +560,7 @@ function summarize(verdict, baselineExists) {
const accounting = verdict.context?.baselineAccounting;
if (accounting) {
lines.push(
- `Baseline accounting: ${accounting.plannedCurrentStable} planned stable · ${accounting.intentionallyExcluded} intentionally excluded · ${accounting.preservedLegacy} preserved legacy · ${accounting.unclassified} unclassified`,
+ `Baseline accounting: ${accounting.plannedCurrentStable} planned stable · ${accounting.policyExcluded} policy-excluded · ${accounting.intentionallyExcluded} intentionally excluded · ${accounting.preservedLegacy} preserved legacy · ${accounting.unclassified} unclassified`,
'',
);
if (accounting.unclassifiedKeys) {
@@ -789,12 +788,15 @@ async function main() {
? JSON.parse(fs.readFileSync(verdictPath, 'utf8'))
: null;
const requested = flag('keys');
+ const removed = new Set(verdict?.removed ?? []);
const named =
!requested || requested === 'all'
- ? Object.keys(currentManifest.shots)
+ ? [
+ ...Object.keys(currentManifest.shots),
+ ...(has('prune') ? removed : []),
+ ]
: requested.split(',').filter(Boolean);
if (new Set(named).size !== named.length) throw new Error('accept repeats a shot key.');
- const removed = new Set(verdict?.removed ?? []);
const prune = has('prune') ? named.filter(key => removed.has(key)) : [];
const keys = named.filter(key => currentManifest.shots[key]);
const unknown = named.filter(key => !currentManifest.shots[key] && !removed.has(key));
diff --git a/.github/scripts/visual-gate/lib/compare.test.mjs b/.github/scripts/visual-gate/lib/compare.test.mjs
index 032b45ac96..83bd5061f4 100644
--- a/.github/scripts/visual-gate/lib/compare.test.mjs
+++ b/.github/scripts/visual-gate/lib/compare.test.mjs
@@ -210,6 +210,66 @@ describe('compareCaptures', () => {
expect(fs.existsSync(path.join(baselineDir, 'shots/c.png'))).toBe(true);
});
+ it('prunes every reviewed removal when keys=all', () => {
+ const gate = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../gate.mjs');
+ const baselineDir = path.join(root, 'all-baseline');
+ const captureDir = path.join(root, 'all-release-capture');
+ fs.mkdirSync(path.join(baselineDir, 'shots'), {recursive: true});
+ fs.mkdirSync(path.join(captureDir, 'shots'), {recursive: true});
+ for (const [key, value] of [
+ ['b', [1, 1, 1]],
+ ['c', [2, 2, 2]],
+ ]) {
+ fs.writeFileSync(
+ path.join(baselineDir, `shots/${key}.png`),
+ png(1, 1, value),
+ );
+ }
+ fs.writeFileSync(
+ path.join(baselineDir, 'manifest.json'),
+ JSON.stringify(manifest({b: {sha256: 'b'}, c: {sha256: 'c'}})),
+ );
+ const current = manifest({a: {sha256: 'a'}});
+ current.context = {releasePlan: createReleasePlan([{key: 'a'}])};
+ fs.writeFileSync(
+ path.join(captureDir, 'manifest.json'),
+ JSON.stringify(current),
+ );
+ fs.writeFileSync(
+ path.join(captureDir, 'verdict.json'),
+ JSON.stringify({
+ status: 'changed',
+ removed: ['b', 'c'],
+ context: current.context,
+ }),
+ );
+
+ execFileSync(
+ process.execPath,
+ [
+ gate,
+ 'accept',
+ '--baseline',
+ baselineDir,
+ '--out',
+ captureDir,
+ '--keys',
+ 'all',
+ '--prune',
+ '--reason',
+ 'Reviewed policy reduction',
+ ],
+ {encoding: 'utf8'},
+ );
+
+ const accepted = JSON.parse(
+ fs.readFileSync(path.join(baselineDir, 'manifest.json'), 'utf8'),
+ );
+ expect(Object.keys(accepted.shots)).toEqual([]);
+ expect(fs.existsSync(path.join(baselineDir, 'shots/b.png'))).toBe(false);
+ expect(fs.existsSync(path.join(baselineDir, 'shots/c.png'))).toBe(false);
+ });
+
it('rejects caller-controlled canonical release scope', () => {
const gate = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../gate.mjs');
expect(() =>
diff --git a/.github/scripts/visual-gate/lib/plan.mjs b/.github/scripts/visual-gate/lib/plan.mjs
index 4f24984687..0d68e12cb5 100644
--- a/.github/scripts/visual-gate/lib/plan.mjs
+++ b/.github/scripts/visual-gate/lib/plan.mjs
@@ -18,19 +18,16 @@
* no longer reflected, cascade order changed) is invisible until someone looks
* at the pixels. That is what this plan aims the camera at.
*
- * Two tiers, both derived rather than hand-listed, so coverage tracks the
- * system instead of drifting from it:
+ * The canonical release baseline is deliberately small and closed:
*
- * theme-matrix — for every component override a theme actually authors, the
- * components declaring that target, in that theme, light and dark. This is
- * the targeted net: one shot per (theme, target, component) the system
- * claims to support.
- * surface — one representative story per component in the default theme.
- * The broad net for ordinary visual regressions, and the reason a
- * component with no theme override still has a before/after.
+ * surface — one representative story per Core component, plus explicit
+ * visual-baseline / visual-theme-matrix stories, in Neutral light and dark.
+ * probe — the smallest story set that renders every theming target, in the
+ * generated Probe fixture light and dark.
*
- * `full` widens `surface` to every story in the index; it is the same tier
- * with the representative-story filter removed.
+ * `theme-matrix` remains available for focused theme evidence, but it does not
+ * own permanent baseline keys. `full` widens `surface` to every story for an
+ * explicit audit.
*/
import * as crypto from 'node:crypto';
@@ -141,8 +138,13 @@ function storyPackageNames(entry, storybookDir, repoRoot, catalog) {
};
}
-export function readThemeCatalog(repoRoot) {
+/**
+ * @param {string} repoRoot
+ * @param {string[]} [fixtureThemes] - private generated themes allowed to own baseline coverage
+ */
+export function readThemeCatalog(repoRoot, fixtureThemes = []) {
const catalog = readPackageCatalog(repoRoot);
+ const fixtures = new Set(fixtureThemes);
const themes = {};
const parent = path.join(repoRoot, 'packages/themes');
if (!fs.existsSync(parent)) return themes;
@@ -152,7 +154,10 @@ export function readThemeCatalog(repoRoot) {
if (!manifest) continue;
themes[entry.name] = {
packageName: manifest.name,
- stableVisual: manifest.private !== true && manifest.astryx?.canaryOnly !== true,
+ stableVisual:
+ fixtures.has(entry.name) ||
+ (manifest.private !== true && manifest.astryx?.canaryOnly !== true),
+ coverageFixture: fixtures.has(entry.name),
};
}
return themes;
@@ -206,12 +211,11 @@ export function accountBaseline(manifest, stories, themes, repoRoot) {
const storedTheme = shot.themePackageName
? catalog.get(shot.themePackageName)
: null;
- const theme = storedTheme
- ? {
- packageName: storedTheme.name,
- stableVisual: eligible(storedTheme),
- }
- : themes[shot.theme];
+ const currentTheme = themes[shot.theme];
+ const theme =
+ storedTheme && currentTheme?.packageName !== storedTheme.name
+ ? null
+ : currentTheme;
if (!owner || !catalog.has(owner.packageName) || !theme) {
categories.unclassified.push(key);
continue;
@@ -245,19 +249,31 @@ export function accountBaseline(manifest, stories, themes, repoRoot) {
export function summarizeBaselineAccounting(account, releaseShots) {
const planned = new Set(releaseShots.map(shot => shot.key));
- const missing = account.categories.currentStable.filter(key => !planned.has(key));
- const unclassified = [...new Set([...account.categories.unclassified, ...missing])].sort();
- const plannedCurrentStable = account.categories.currentStable.length - missing.length;
+ const policyExcluded = account.categories.currentStable.filter(
+ key => !planned.has(key),
+ );
+ const unclassified = [...account.categories.unclassified];
+ const plannedCurrentStable =
+ account.categories.currentStable.length - policyExcluded.length;
const counts = {
total: account.total,
plannedCurrentStable,
+ policyExcluded: policyExcluded.length,
intentionallyExcluded: account.categories.intentionallyExcluded.length,
preservedLegacy: account.categories.preservedLegacy.length,
unclassified: unclassified.length,
};
- const sum = counts.plannedCurrentStable + counts.intentionallyExcluded + counts.preservedLegacy + counts.unclassified;
+ const sum =
+ counts.plannedCurrentStable +
+ counts.policyExcluded +
+ counts.intentionallyExcluded +
+ counts.preservedLegacy +
+ counts.unclassified;
if (sum !== counts.total) throw new Error(`Baseline accounting overlap: ${sum} states for ${counts.total} keys.`);
- return {...counts, ...(unclassified.length ? {unclassifiedKeys: unclassified} : {})};
+ return {
+ ...counts,
+ ...(unclassified.length ? {unclassifiedKeys: unclassified} : {}),
+ };
}
export function stableBaseline(manifest, stories, themes, repoRoot) {
@@ -379,6 +395,13 @@ export function storiesInPackages(stories, packages) {
return stories.filter(story => story.stableVisual && story.packageNames.some(name => wanted.has(name)));
}
+/** Restrict canonical baselines to named Storybook title groups. */
+export function storiesInStorybookGroups(stories, groups) {
+ if (groups.includes('*')) return stories;
+ const wanted = new Set(groups);
+ return stories.filter(story => wanted.has(String(story.title).split('/')[0]));
+}
+
/**
* One story per component: the first match against REPRESENTATIVE_NAMES, else
* the first story in index order (which is source order, so it is stable).
@@ -562,7 +585,14 @@ export function buildPlan({
};
if (tiers.includes('surface') || tiers.includes('full')) {
- const subject = tiers.includes('full') ? stories : [...representatives.values()];
+ const subject = tiers.includes('full')
+ ? stories
+ : stories.filter(
+ story =>
+ representatives.get(story.component)?.id === story.id ||
+ (story.tags ?? []).includes(VISUAL_BASELINE_TAG) ||
+ (story.tags ?? []).includes(VISUAL_THEME_MATRIX_TAG),
+ );
for (const story of subject) {
for (const mode of MODES) {
add({...toShotBase(story), theme: defaultTheme, mode}, 'surface');
@@ -634,6 +664,13 @@ export function buildPlan({
})) {
add(shot, reason);
}
+ for (const story of stories.filter(candidate =>
+ (candidate.tags ?? []).includes(VISUAL_THEME_MATRIX_TAG),
+ )) {
+ for (const mode of MODES) {
+ add({...toShotBase(story), theme: probeTheme, mode}, 'probe:opt-in');
+ }
+ }
}
return [...shots.values()].sort((a, b) => a.key.localeCompare(b.key));
diff --git a/.github/scripts/visual-gate/lib/plan.test.mjs b/.github/scripts/visual-gate/lib/plan.test.mjs
index a5a95f1e7f..92ef495af6 100644
--- a/.github/scripts/visual-gate/lib/plan.test.mjs
+++ b/.github/scripts/visual-gate/lib/plan.test.mjs
@@ -20,6 +20,7 @@ import {
resolvePrVisualTotalShotLimit,
shotKey,
storiesInPackages,
+ storiesInStorybookGroups,
summarizeBaselineAccounting,
uncoveredTargets,
} from './plan.mjs';
@@ -66,6 +67,29 @@ describe('storiesInPackages', () => {
});
});
+describe('storiesInStorybookGroups', () => {
+ it('keeps only canonical title groups even when another group imports Core', () => {
+ const mixed = [
+ ...stories,
+ story({
+ id: 'foundations-button--default',
+ title: 'Foundations/Button',
+ name: 'Default',
+ component: 'Button',
+ }),
+ story({
+ id: 'lab-button--default',
+ title: 'Lab/Button',
+ name: 'Default',
+ component: 'Button',
+ }),
+ ];
+ expect(
+ storiesInStorybookGroups(mixed, ['Core']).map(story => story.id),
+ ).toEqual(stories.map(story => story.id));
+ });
+});
+
describe('representativeStories', () => {
it('prefers a conventionally named story over source order', () => {
expect(representativeStories(stories).get('Button').id).toBe('core-button--default');
@@ -211,6 +235,68 @@ describe('buildPlan', () => {
]);
});
+ it('keeps tagged visual contracts in the neutral surface plan', () => {
+ const tagged = [
+ ...stories,
+ story({
+ id: 'core-button--separator',
+ title: 'Core/Button',
+ name: 'Separator',
+ component: 'Button',
+ tags: ['visual-baseline'],
+ }),
+ story({
+ id: 'core-button--variants',
+ title: 'Core/Button',
+ name: 'Variants',
+ component: 'Button',
+ tags: ['visual-theme-matrix'],
+ }),
+ ];
+ const plan = buildPlan({
+ stories: tagged,
+ targets,
+ themeOverrides,
+ defaultTheme: 'neutral',
+ tiers: ['surface'],
+ });
+ expect(new Set(plan.map(shot => shot.storyId))).toEqual(
+ new Set([
+ 'core-button--default',
+ 'core-badge--solid',
+ 'core-button--separator',
+ 'core-button--variants',
+ ]),
+ );
+ expect(new Set(plan.map(shot => shot.theme))).toEqual(new Set(['neutral']));
+ });
+
+ it('keeps matrix-tagged stories in the probe baseline', () => {
+ const tagged = [
+ ...stories,
+ story({
+ id: 'core-button--variants',
+ title: 'Core/Button',
+ name: 'Variants',
+ component: 'Button',
+ tags: ['visual-theme-matrix'],
+ }),
+ ];
+ const plan = buildPlan({
+ stories: tagged,
+ targets,
+ themeOverrides,
+ observations: {},
+ defaultTheme: 'neutral',
+ tiers: ['probe'],
+ probeTheme: 'probe',
+ });
+ expect(plan.map(shot => shot.key)).toEqual([
+ 'core-button--variants__probe-dark',
+ 'core-button--variants__probe-light',
+ ]);
+ });
+
it('adds a shot for every theme that overrides a component the story renders', () => {
const plan = buildPlan({stories, targets, themeOverrides, defaultTheme: 'neutral', tiers: ['theme-matrix']});
const y2k = plan.filter(shot => shot.theme === 'y2k').map(shot => shot.key);
@@ -388,6 +474,22 @@ describe('readStoryIndex package metadata', () => {
}
});
+ it('allows the private probe theme only as an explicit baseline fixture', () => {
+ const {root} = fixture();
+ try {
+ expect(readThemeCatalog(root).probe).toMatchObject({
+ stableVisual: false,
+ coverageFixture: false,
+ });
+ expect(readThemeCatalog(root, ['probe']).probe).toMatchObject({
+ stableVisual: true,
+ coverageFixture: true,
+ });
+ } finally {
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+ });
+
it('accounts for a live-shaped 974-key baseline without dropping legacy keys', () => {
const {root} = fixture();
for (const [dir, manifest] of [
@@ -448,6 +550,7 @@ describe('readStoryIndex package metadata', () => {
expect(summary).toEqual({
total: 974,
plannedCurrentStable: 882,
+ policyExcluded: 0,
intentionallyExcluded: 92,
preservedLegacy: 0,
unclassified: 0,
@@ -458,6 +561,43 @@ describe('readStoryIndex package metadata', () => {
}
});
+ it('classifies accepted but noncanonical keys as policy exclusions', () => {
+ const {root} = fixture();
+ try {
+ const account = accountBaseline(
+ {
+ shots: {
+ 'core-button--default__neutral-light': {
+ storyId: 'core-button--default',
+ title: 'Core/Button',
+ component: 'Button',
+ theme: 'neutral',
+ mode: 'light',
+ },
+ },
+ },
+ [
+ {
+ id: 'core-button--default',
+ packageName: '@astryxdesign/core',
+ packageNames: ['@astryxdesign/core'],
+ stableVisual: true,
+ },
+ ],
+ readThemeCatalog(root),
+ root,
+ );
+ expect(summarizeBaselineAccounting(account, [])).toMatchObject({
+ total: 1,
+ plannedCurrentStable: 0,
+ policyExcluded: 1,
+ unclassified: 0,
+ });
+ } finally {
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+ });
+
it('preserves a deleted accepted story as a release decision', () => {
const {root} = fixture();
try {
@@ -480,6 +620,7 @@ describe('readStoryIndex package metadata', () => {
expect(summarizeBaselineAccounting(account, [])).toEqual({
total: 1,
plannedCurrentStable: 0,
+ policyExcluded: 0,
intentionallyExcluded: 0,
preservedLegacy: 1,
unclassified: 0,
@@ -514,6 +655,7 @@ describe('readStoryIndex package metadata', () => {
expect(summarizeBaselineAccounting(account, [])).toEqual({
total: 1,
plannedCurrentStable: 0,
+ policyExcluded: 0,
intentionallyExcluded: 0,
preservedLegacy: 0,
unclassified: 1,
diff --git a/.github/scripts/visual-gate/lib/sources.mjs b/.github/scripts/visual-gate/lib/sources.mjs
index 54b2b369fe..0f62877c6e 100644
--- a/.github/scripts/visual-gate/lib/sources.mjs
+++ b/.github/scripts/visual-gate/lib/sources.mjs
@@ -174,7 +174,7 @@ function unreadableTheme(repoRoot, name, built, error, rebuilt) {
/**
* @param {string} repoRoot
- * @returns {{excludeStories: Record<string, string>, viewport: {width: number, height: number}, settleMs: number, scoutConcurrency: number, captureConcurrency: number, compareConcurrency: number, threshold: number, maxDiffPixels: number, defaultTheme: string, probeTheme: string, stableStoryPackages: string[], prVisualShotLimit: number, visualPlanSafetyLimit: number, tiers: string[]}}
+ * @returns {{excludeStories: Record<string, string>, viewport: {width: number, height: number}, settleMs: number, scoutConcurrency: number, captureConcurrency: number, compareConcurrency: number, threshold: number, maxDiffPixels: number, defaultTheme: string, probeTheme: string, baselineThemes: string[], stableStoryPackages: string[], stableStoryGroups: string[], prVisualShotLimit: number, visualPlanSafetyLimit: number, tiers: string[]}}
*/
export function loadConfig(repoRoot) {
const defaults = {
@@ -188,7 +188,9 @@ export function loadConfig(repoRoot) {
maxDiffPixels: 0,
defaultTheme: 'neutral',
probeTheme: 'probe',
+ baselineThemes: ['neutral', 'probe'],
stableStoryPackages: ['Core'],
+ stableStoryGroups: ['Core'],
prVisualShotLimit: 240,
visualPlanSafetyLimit: 5000,
tiers: ['surface', 'theme-matrix', 'probe'],
diff --git a/.github/scripts/visual-gate/publish-pr-report.mjs b/.github/scripts/visual-gate/publish-pr-report.mjs
index ca3e4165d2..cc7d06124a 100644
--- a/.github/scripts/visual-gate/publish-pr-report.mjs
+++ b/.github/scripts/visual-gate/publish-pr-report.mjs
@@ -41,7 +41,7 @@ const REPO_ROOT = path.resolve(
'../../..',
);
const config = loadConfig(REPO_ROOT);
-const themeCatalog = readThemeCatalog(REPO_ROOT);
+const themeCatalog = readThemeCatalog(REPO_ROOT, config.baselineThemes);
const KEY = /^[A-Za-z0-9._-]{1,240}$/;
const NAME = /^[A-Za-z0-9._-]{1,120}$/;
diff --git a/.github/scripts/visual-gate/visual-acceptance.mjs b/.github/scripts/visual-gate/visual-acceptance.mjs
index 850d93e028..c5448fd43d 100644
--- a/.github/scripts/visual-gate/visual-acceptance.mjs
+++ b/.github/scripts/visual-gate/visual-acceptance.mjs
@@ -30,6 +30,7 @@ import {
shotKey,
stableBaseline,
storiesInPackages,
+ storiesInStorybookGroups,
VISUAL_BASELINE_TAG,
withThemeMetadata,
} from './lib/plan.mjs';
@@ -41,7 +42,7 @@ const REPO_ROOT = path.resolve(
'../../..',
);
const config = loadConfig(REPO_ROOT);
-const themeCatalog = readThemeCatalog(REPO_ROOT);
+const themeCatalog = readThemeCatalog(REPO_ROOT, config.baselineThemes);
const args = process.argv.slice(2);
const command = args[0];
@@ -733,10 +734,14 @@ function trustedPlan() {
const storybookDir = path.resolve(flag('storybook-dir'));
const output = path.resolve(flag('output'));
const allIndexed = readStoryIndex(storybookDir, [], REPO_ROOT);
- const indexed = storiesInPackages(
+ const packageStories = storiesInPackages(
allIndexed,
config.stableStoryPackages,
);
+ const indexed = storiesInStorybookGroups(
+ packageStories,
+ config.stableStoryGroups,
+ );
const {baseline} = readTrustedBaseline(allIndexed);
const baselineKeys = new Set(Object.keys(baseline.shots));
diff --git a/.github/scripts/visual-gate/visual-acceptance.test.mjs b/.github/scripts/visual-gate/visual-acceptance.test.mjs
index 2535decc07..c398c95952 100644
--- a/.github/scripts/visual-gate/visual-acceptance.test.mjs
+++ b/.github/scripts/visual-gate/visual-acceptance.test.mjs
@@ -570,10 +570,7 @@ describe('visual acceptance', () => {
});
expect(
JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),
- ).toEqual([
- 'core-button--default__neutral-light',
- 'core-button--default__y2k-light',
- ]);
+ ).toEqual(['core-button--default__neutral-light']);
});
it('fails closed when any touched component has no representative story', () => {
@@ -632,7 +629,7 @@ describe('visual acceptance', () => {
const baseline = JSON.parse(fs.readFileSync(baselineFile, 'utf8'));
for (let index = 0; index < 61; index += 1) {
const storyId = `core-button--story-${index}`;
- for (const theme of ['neutral', 'y2k']) {
+ for (const theme of ['neutral', 'probe']) {
for (const mode of ['light', 'dark']) {
const key = `${storyId}__${theme}-${mode}`;
baseline.shots[key] = {
@@ -641,6 +638,7 @@ describe('visual acceptance', () => {
storyId,
name: entries[`story-${index}`].name,
theme,
+ themePackageName: `@astryxdesign/theme-${theme}`,
mode,
};
}
@@ -720,7 +718,7 @@ describe('visual acceptance', () => {
expect(new Set(plan.map(shot => shot.theme))).toEqual(new Set(['neutral']));
});
- it('includes newly targeted components for an existing changed theme', () => {
+ it('limits changed themes to stories in the canonical baseline', () => {
const storybook = path.join(root, 'storybook-existing-theme');
fs.mkdirSync(storybook);
writeJSON(path.join(storybook, 'index.json'), {
@@ -779,8 +777,6 @@ describe('visual acceptance', () => {
).toEqual([
'core-button--default__y2k-light',
'core-button--default__y2k-dark',
- 'core-card--default__y2k-light',
- 'core-card--default__y2k-dark',
]);
});
diff --git a/.github/scripts/visual-gate/visual-gate.config.json b/.github/scripts/visual-gate/visual-gate.config.json
index 32a0eaf820..e2d16ea9db 100644
--- a/.github/scripts/visual-gate/visual-gate.config.json
+++ b/.github/scripts/visual-gate/visual-gate.config.json
@@ -3,8 +3,12 @@
"defaultTheme": "neutral",
"$probeTheme": "A generated fixture styling every declared target (packages/themes/probe). The gate treats it as the coverage instrument, not a design: it is what makes a NEW theming target verified from the day its doc lands.",
"probeTheme": "probe",
- "$stableStoryPackages": "Only these Storybook package groups participate in the stable baseline. Canary-only packages have no stable visual baseline.",
+ "$baselineThemes": "Themes allowed to own canonical stable baseline frames. Neutral is the default product reference; probe is the generated coverage fixture.",
+ "baselineThemes": ["neutral", "probe"],
+ "$stableStoryPackages": "Only these workspace packages may own stable visual stories.",
"stableStoryPackages": ["Core"],
+ "$stableStoryGroups": "Only these Storybook title groups may own canonical baseline frames, even when another group imports Core components.",
+ "stableStoryGroups": ["Core"],
"$prVisualShotLimit": "Review ceiling for focused component shots and broad shared-infrastructure plans. Theme-only matrices are not component-budgeted.",
"prVisualShotLimit": 240,
"$visualPlanSafetyLimit": "Absolute resource ceiling for every ordinary and trusted visual plan, regardless of scope.",
diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.yml
index b5f184e5fe..cae54e0d0d 100644
--- a/.github/workflows/release-gate.yml
+++ b/.github/workflows/release-gate.yml
@@ -3,8 +3,9 @@
# Release gate — the checks a release must clear, run before the daily cut.
#
# Two of them, and they answer different questions:
-# visual — did anything on screen change, in any theme, since the last
-# accepted baseline? (.github/scripts/visual-gate)
+# visual — did the canonical Neutral component surface or generated Probe
+# coverage fixture change since the last accepted baseline?
+# (.github/scripts/visual-gate)
# a11y — did any NEW accessibility violation appear against the baseline?
# (the same full-suite audit a11y-weekly runs, run daily here)
#
@@ -91,12 +92,11 @@ jobs:
echo "::notice::No baseline on gh-pages yet — this run establishes one."
fi
- # The derived surface/matrix stays representative, but an accepted
- # stable key is a durable release promise: recapture every still-valid
- # baseline key until a reviewed removal prunes it. Package filtering is
- # applied to the baseline too, so legacy canary keys do not block Core.
- # The gate constructs the canonical stable tiers internally. A caller may
- # not expand, rename, or narrow the plan that owns removal authority.
+ # The canonical release plan is a closed policy: representative and
+ # explicitly tagged Core stories in Neutral, plus generated Probe coverage.
+ # Existing keys outside that set are reported as reviewed removals so the
+ # manual baseline workflow can prune them deliberately. A caller may not
+ # expand, rename, or narrow the plan that owns removal authority.
# Exit 2 means "changed", which is a release decision; only a crash (1)
# fails this job mechanically.
- name: Run the visual gate