feat: enhance keyframes handling to preserve animations referenced via CSS variables

#478

Author: Ffloriel

docs/configuration.md

@@ -206,6 +206,20 @@ await new PurgeCSS().purge({
 
 If you are using a CSS animation library such as animate.css, you can remove unused keyframes by setting the `keyframes` option to `true`.
 
+PurgeCSS detects used keyframes by scanning `animation` and `animation-name` property values, as well as CSS custom property (variable) values. This means keyframes referenced via CSS variables will be correctly preserved:
+
+```css
+.component {
+  animation: var(--component-animation);
+}
+.component--animated {
+  --component-animation: fadeIn 0.4s;
+}
+@keyframes fadeIn {
+  /* This keyframe will be preserved because "fadeIn" appears in --component-animation */
+}
+```
+
 ```js
 await new PurgeCSS().purge({
   content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],

packages/purgecss/__tests__/keyframes.test.ts

@@ -121,3 +121,47 @@ describe("keep webkit keyframe decimals", () => {
     expect(purgedCSS.includes("99.9%")).toBe(true);
   });
 });
+
+describe("keep keyframes referenced via CSS variables", () => {
+  let purgedCSS: string;
+  beforeAll(async () => {
+    const resultsPurge = await new PurgeCSS().purge({
+      content: [
+        {
+          raw: '<div class="component component--animated"></div>',
+          extension: "html",
+        },
+      ],
+      css: [
+        {
+          raw: `
+            .component {
+              animation: var(--component-animation);
+            }
+            .component--animated {
+              --component-animation: fadeIn 0.4s;
+            }
+            @keyframes fadeIn {
+              from { opacity: 0; }
+              to { opacity: 1; }
+            }
+            @keyframes unused {
+              from { opacity: 1; }
+              to { opacity: 0; }
+            }
+          `,
+        },
+      ],
+      keyframes: true,
+    });
+    purgedCSS = resultsPurge[0].css;
+  });
+
+  it("keeps `@keyframes fadeIn` referenced via CSS variable", () => {
+    expect(purgedCSS.includes("@keyframes fadeIn")).toBe(true);
+  });
+
+  it("removes `@keyframes unused`", () => {
+    expect(purgedCSS.includes("@keyframes unused")).toBe(false);
+  });
+});

packages/purgecss/src/index.ts

@@ -404,6 +404,13 @@ class PurgeCSS {
         }
         return;
       }
+      // Also check CSS custom properties for animation names
+      // e.g., --my-animation: fadeIn 0.4s;
+      if (prop.startsWith("--")) {
+        for (const word of value.split(/[\s,]+/)) {
+          this.usedAnimations.add(word);
+        }
+      }
     }
 
     // collect font faces data