tech(scss): single machine-readable deprecation registry

[MarcFairbrother]

Description

Deprecation in @lucca-front/scss was expressed four incompatible, machine-unreadable ways: silent // comments, // DEPRECATED section headers, inline value-list annotations, and config flags. None survive Sass compilation, so the VS Code IntelliSense manifest had to reconstruct deprecation from a frozen regex seed (css-api/deprecations.js) — brittle (false positives/negatives), drift-prone, and a split source of truth. It was untrustworthy enough that the extension shipped deprecation flagging off by default.

What this PR does

Introduces one authoritative, colocated, machine-readable deprecation signal that emits zero bytes into the compiled CSS.

The convention: a registry mixin

packages/scss/src/commons/deprecated.scss exposes deprecated.class(), deprecated.cssVariable(), deprecated.selector() and deprecated.sassApi(). Each records metadata into a module-level map and emits no CSS. You call it at the declaration site:

// Before — invisible to tooling, stripped at compile time
// textLeft is deprecated
.pr-u-textLeft { @extend %textLeft; }

// After — authoritative, survives to JSON, still zero CSS
@include deprecated.class('pr-u-textLeft', $replacement: 'pr-u-textAlignStart', $scope: 'commons/utils');
.pr-u-textLeft { @extend %textLeft; }

For loop-generated names (spacing/border-radius/palette utilities, the whole u- prefix) the registration lives inside the loop using the same interpolation that builds the emitted class, so the recorded name is exact by construction — no regex guessing. This is why the approach was chosen over loud /* @deprecated */ comments: comments can't anchor to @extend-merged selectors or loop output, and de-merging @extend would grow the shipped CSS.

Rule: a deprecation isn't a deprecation until it's registered.

The manifest

A build step (npm run scss:deprecations) compiles a maximal-config entry, reads the registry out through a custom Sass function, and writes packages/scss/css-api/deprecations.json (committed, deterministic, sorted). Schema:

{ "version": 1, "package": "@lucca-front/scss",
  "entries": [ { "kind": "class", "name": "pr-u-textLeft", "replacement": "pr-u-textAlignStart", "note": null, "since": null, "scope": "commons/utils" } ] }

684 entries: 477 utility classes, 140 CSS variables, 49 component selectors, 18 Sass APIs. The manifest is committed (so Storybook and typecheck work from a clean checkout) and shipped in the published package; CI runs npm run scss:deprecations -- --check to fail on drift.

Storybook page

Documentation / Integration / Deprecations — a searchable, kind-filterable table of every deprecated element and its replacement, built programmatically from the committed JSON so it updates automatically. The PR's staging build posts a live preview link.

Size audit — provably neutral

Registry calls emit no CSS. npm run scss:audit compiles the full bundle and every module before/after and compares sha256:

Output	Before	After	Δ
bundle lucca-front.min.css	1,242,368 B	1,242,368 B	0
bundle (maximal config, u- prefix on)	1,248,519 B	1,248,519 B	0

125/125 comparable outputs are byte-identical (the full bundle + commons + 123 component modules; one pre-existing component that doesn't compile standalone is excluded). Full per-module table and the before/after deprecation inventory: scss-size-audit.md.

Commits

1. tech(scss): add deprecation registry module and extraction tooling
2. tech(scss): register commons deprecations through the registry
3. tech(scss): register component deprecations through the registry
4. tech(scss): commit generated deprecations manifest with CI drift check
5. feat(stories): add deprecations explorer to integration documentation
6. tech(scss): satisfy stylelint formatting and harden the audit tool
7. docs(scss): document the deprecation registry and audit workflow

Notes & known limitations

• Selector deprecations key on (kind, name) without scope, so a bare class shared across components (e.g. .mod-text in both button and buttonGroup) is recorded once, under one component. Compound selectors (.box.mod-grey) are unambiguous. Acceptable given the shared class name; can be refined later if needed.
• A few --commons-* custom properties under the legacy block (container/navSide sizing) were left unregistered because they lack a clear replacement and appear semi-active internally — deliberately under-claiming rather than mis-claiming deprecation.
• Usage-site @warn (warning consumers who include a deprecated Sass mixin) is intentionally deferred — it adds build-log noise for little value and can be a follow-up.
• No CI size gate: size-neutrality is a property of this refactor, not a package invariant (future PRs legitimately change sizes). The audit tool is committed for one-off use.

Follow-ups (branch feat.vscode.intellisense)

• Have css-api/generate.js consume deprecations.json and delete the regex seed css-api/deprecations.js.
• Enable the extension's deprecation diagnostics by default now that the data is trustworthy.
• Feed the same JSON into a stylelint rule and ng update codemods.

---

[github-actions]

🚀 Storybook preview deployed: https://pub-dc6d99acd6874e2aaff6219dd8a13ae2.r2.dev/PR-5132/index.html