Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | 4x 4x 4x 4x 7x 7x 7x 6x 6x 5x 5x 5x 5x 3x 3x 3x 3x 5x 3x 3x 3x 5x 4x 4x 4x 4x 4x 3x 4x 3x 4x 4x 16x 16x 9x 7x 7x 2x 5x 5x 1x 4x | /**
* LBC-alignment check: surfaces recorded drift between the
* design-system-2 hook surface and a `lightning-*` LBC element.
*
* **Why this check exists.** Most LBCs render via Synthetic Shadow DOM
* and consume the design-system-2 CSS directly — the design-system-2
* hook surface IS the customization surface for the customer. For
* those, no recording is needed; this check passes silently.
*
* The narrow drift cases this check captures are integration risks
* the customer surface can't paper over:
*
* - **`primitiveBakedHooks`** — the LBC embeds a primitive (e.g.
* `lightning-primitive-icon`) whose own CSS bakes hook reads that
* escape the wrapping LBC's surface. A customer overriding the
* wrapping LBC's hooks doesn't reach the primitive's reads; the
* primitive paints with values the customer can't influence.
* - **`hookCompositionMismatch`** — the LBC's compiled CSS reads a
* hook that doesn't exist on the design-system-2 surface
* (renamed, moved, or never opened). The hook is part of the
* LBC's API but not part of ours, so the customer's override
* against our surface has no read site to flow through.
*
* **Why static metadata.** The LBC source is owned upstream and only
* changes when the LBC pipeline ships new CSS. The recording is
* captured at uplift time on the SLDS UIF
* (`extensions['com.salesforce-ux.lbc-contract']`) and only changes
* when the LBC source genuinely changes, which we control.
*
* **Schema** (under `extensions['com.salesforce-ux.lbc-contract']`):
*
* ```jsonc
* {
* "tag": "lightning-progressbar-basic", // required: the LBC tag this contract describes
* "recordedAt": "2026-05-31", // optional, informational
* "primitiveBakedHooks": [
* {
* "hook": "--slds-c-primitive-icon-color-foreground",
* "primitive": "lightning-primitive-icon",
* "reason": "lightning-primitive-icon embeds its own SVG paint; customer overrides on --slds-c-progressbar-color-foreground do not reach the primitive's icon."
* }
* ],
* "hookCompositionMismatch": [
* {
* "hook": "--slds-c-button-text-color",
* "reason": "LBC reads this name; design-system-2 renamed it to --slds-c-button-color-foreground. Customer override on the new name has no read site in the LBC's CSS."
* }
* ]
* }
* ```
*
* **Status mapping.**
* - `info`: no UIF supplied (browser-only path).
* - `pass`: UIF present but no contract recorded (default for the
* synthetic-shadow case — the LBC consumes our CSS directly,
* no integration drift expected).
* - `pass`: contract recorded, but both drift lists empty.
* - `review`: contract has at least one entry. Each offender names
* the LBC tag, the offending hook, the primitive (when
* applicable), and a one-line reason.
*/
import type { ComplianceCheck, ComplianceRow, Offender } from '../types.js';
const ID = 'lbc-design-system-alignment';
const LABEL = 'LBC integrates cleanly with the design-system-2 hook surface';
const CATEGORY = 'lbc-alignment' as const;
const EXTENSION_KEY = 'com.salesforce-ux.lbc-contract';
interface PrimitiveBakedHook {
/** Hook name the primitive bakes, escaping the wrapping LBC's surface. */
hook?: string;
/** Primitive tag (e.g. `lightning-primitive-icon`). */
primitive?: string;
/** One-line explanation of why this is customer-impacting. */
reason?: string;
}
interface HookCompositionMismatch {
/** Hook name the LBC reads. */
hook?: string;
/** One-line explanation of the mismatch with design-system-2. */
reason?: string;
}
interface LbcContract {
/** The LBC tag this contract describes (e.g. `lightning-button`). */
tag?: string;
recordedAt?: string;
primitiveBakedHooks?: PrimitiveBakedHook[];
hookCompositionMismatch?: HookCompositionMismatch[];
}
function readContract(uif: Record<string, unknown> | null | undefined): LbcContract | null {
Iif (!uif || typeof uif !== 'object') return null;
const extensions = (uif.extensions ?? null) as Record<string, unknown> | null;
if (!extensions) return null;
const block = extensions[EXTENSION_KEY];
if (!block || typeof block !== 'object') return null;
return block;
}
function offendersFromContract(contract: LbcContract): Offender[] {
const out: Offender[] = [];
const tagPrefix = contract.tag ? `\`${contract.tag}\`` : 'the LBC';
for (const entry of contract.primitiveBakedHooks ?? []) {
const hook = entry.hook ?? '<hook>';
const primitive = entry.primitive ? `\`${entry.primitive}\`` : 'an embedded primitive';
const reasonSuffix = entry.reason ? ` ${entry.reason}` : '';
out.push({
hook: entry.hook,
note: `${tagPrefix} embeds ${primitive}, which bakes \`${hook}\` outside the wrapping LBC's surface.${reasonSuffix}`,
fix:
`Customer overrides on the wrapping LBC's hooks don't reach this primitive's reads. ` +
`Either expose the primitive's hook on the design-system-2 surface (so customers override it directly) ` +
`or migrate the primitive to read a hook the wrapping LBC reassigns.`,
});
}
for (const entry of contract.hookCompositionMismatch ?? []) {
const hook = entry.hook ?? '<hook>';
const reasonSuffix = entry.reason ? ` ${entry.reason}` : '';
out.push({
hook: entry.hook,
note: `${tagPrefix} reads \`${hook}\`, which is not on the design-system-2 hook surface.${reasonSuffix}`,
fix:
`Migrate the LBC source to read the design-system-2 public hook, OR open the LBC's hook on the design-system-2 surface. ` +
`Until alignment lands, the customer's override against the design-system-2 surface has no read site in the LBC's CSS.`,
});
}
return out;
}
function summaryDetail(contract: LbcContract, offenderCount: number): string {
const primCount = contract.primitiveBakedHooks?.length ?? 0;
const compCount = contract.hookCompositionMismatch?.length ?? 0;
const tagLabel = contract.tag ? `\`${contract.tag}\`` : 'the LBC';
const parts: string[] = [];
if (primCount > 0) {
parts.push(`${primCount} primitive-baked hook${primCount === 1 ? '' : 's'}`);
}
if (compCount > 0) {
parts.push(`${compCount} hook-composition mismatch${compCount === 1 ? '' : 'es'}`);
}
return (
`${parts.join(', ')} recorded for ${tagLabel} ` +
`(${offenderCount} offender${offenderCount === 1 ? '' : 's'}). ` +
`The LBC's customization surface and the design-system-2 hook surface diverge on these entries; ` +
`customer overrides against design-system-2 won't reach the rendered DOM until alignment lands.`
);
}
export const lbcDesignSystemAlignment: ComplianceCheck = (input): ComplianceRow => {
const { componentSystemUif } = input;
if (!componentSystemUif) {
return {
id: ID,
label: LABEL,
category: CATEGORY,
status: 'info',
count: 0,
detail:
'Component system UIF was not supplied to this check (browser-only run). The CLI build path always supplies it; this row stays informational on browser/themeData paths.',
};
}
const contract = readContract(componentSystemUif);
if (!contract) {
// No `lbc-contract` extension recorded. The component either has
// no LBC consumer, OR its LBC renders via Synthetic Shadow DOM
// and consumes design-system-2 CSS directly (the default path).
// Either way, no integration drift to surface.
return {
id: ID,
label: LABEL,
category: CATEGORY,
status: 'pass',
count: 0,
detail:
'No LBC integration drift recorded. ' +
'Most LBCs render via Synthetic Shadow DOM and consume design-system-2 CSS directly, so no recording is needed; ' +
"drift is recorded only when an embedded primitive bakes its own hooks or the LBC reads a hook design-system-2 doesn't expose.",
};
}
const offenders = offendersFromContract(contract);
if (offenders.length === 0) {
return {
id: ID,
label: LABEL,
category: CATEGORY,
status: 'pass',
count: 0,
detail:
'LBC integration contract is recorded but empty — the LBC composes cleanly against the design-system-2 hook surface.',
};
}
return {
id: ID,
label: LABEL,
category: CATEGORY,
status: 'review',
count: offenders.length,
detail: summaryDetail(contract, offenders.length),
offenders,
};
};
|