From de56755d604d8d1956c8e978df8d31965c910f42 Mon Sep 17 00:00:00 2001
From: Nicolas Merget <104347736+nmerget@users.noreply.github.com>
Date: Wed, 8 Jan 2025 08:27:55 +0100
Subject: [PATCH] docs: add performance documentation with purgecss and csso
 (#3648)

---
 packages/foundations/docs/Performance.md      | 67 +++++++++++++++++++
 showcases/patternhub/data/routes.tsx          |  3 +-
 .../pages/foundations/performance/index.mdx   |  7 ++
 showcases/patternhub/styles/highlight.scss    |  2 +-
 4 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 packages/foundations/docs/Performance.md
 create mode 100644 showcases/patternhub/pages/foundations/performance/index.mdx

diff --git a/packages/foundations/docs/Performance.md b/packages/foundations/docs/Performance.md
new file mode 100644
index 00000000000..97807d52eba
--- /dev/null
+++ b/packages/foundations/docs/Performance.md
@@ -0,0 +1,67 @@
+# Performance
+
+If you need to improve the performance of your application, you can use the following tips:
+
+## Minify with PurgeCSS and CSSO
+
+When you use the full bundled `.css` file we provide, you could easily reduce the file size by removing unused CSS classes. This can be done with [PurgeCSS](https://purgecss.com/) and [CSSO](https://github.com/css/csso).
+
+Install both with:
+
+```shell
+npm i purgecss csso --save-dev
+```
+
+Next you should create a file, e.g. `purgecss.js` in your project root with the following content:
+
+```javascript
+import { writeFileSync } from "node:fs";
+
+import { PurgeCSS } from "purgecss";
+import { minify } from "csso";
+
+const distFolder = "dist"; // TODO: Change me if you need another folder
+
+new PurgeCSS()
+	.purge({
+		content: [`${distFolder}/**/*.html`, `${distFolder}/**/*.js`],
+		css: [`${distFolder}/**/*.css`],
+		defaultExtractor: (content) => content.match(/[\w-/:]+(?<!:)/g) || [],
+		variables: true,
+		rejectedCss: true,
+		safelist: {
+			variables: [
+				/* TODO: Keep only the densities you need */
+				/-functional-/,
+				/-regular-/,
+				/-expressive-/,
+				/* Keep density & all color properties/variables */
+				/-default$/,
+				/-hovered$/,
+				/-pressed$/
+			],
+			/* Some components require a safelist */
+			greedy: [
+				/db-tabs/ // TODO: Add more components if necessary
+			]
+		}
+	})
+	.then((purgeCSSResult) => {
+		for (const result of purgeCSSResult) {
+			writeFileSync(result.file, minify(result.css).css);
+
+			/* Optional: for debugging */
+			// writeFileSync(`rejected.css`, result.rejectedCss || "");
+		}
+	});
+```
+
+You can run this script with `node purgecss.js` and it will minify your CSS files. You can also add this script to your `package.json` to run after your regular build process:
+
+```json
+{
+	"scripts": {
+		"postbuild": "node purgecss.js"
+	}
+}
+```
diff --git a/showcases/patternhub/data/routes.tsx b/showcases/patternhub/data/routes.tsx
index 99bb4a25951..c44c55594a1 100644
--- a/showcases/patternhub/data/routes.tsx
+++ b/showcases/patternhub/data/routes.tsx
@@ -233,7 +233,8 @@ export const ROUTES: NavigationItem[] = [
 				label: 'Testing Overview Table',
 				path: '/foundations/test-table'
 			},
-			{ label: 'IDE Support', path: '/foundations/ide' }
+			{ label: 'IDE Support', path: '/foundations/ide' },
+			{ label: 'Performance', path: '/foundations/performance' }
 		]
 	},
 	{
diff --git a/showcases/patternhub/pages/foundations/performance/index.mdx b/showcases/patternhub/pages/foundations/performance/index.mdx
new file mode 100644
index 00000000000..baa52a6b46e
--- /dev/null
+++ b/showcases/patternhub/pages/foundations/performance/index.mdx
@@ -0,0 +1,7 @@
+import DefaultPage from "../../../components/default-page";
+
+import Readme from "../../../../../packages/foundations/docs/Performance.md";
+
+<Readme />
+
+export default ({ children }) => <DefaultPage>{children}</DefaultPage>;
diff --git a/showcases/patternhub/styles/highlight.scss b/showcases/patternhub/styles/highlight.scss
index 70c131cd20c..be1ef281b71 100644
--- a/showcases/patternhub/styles/highlight.scss
+++ b/showcases/patternhub/styles/highlight.scss
@@ -73,7 +73,7 @@ pre:has(.hljs):not(:has(.language-shell)) {
 }
 .hljs-subst {
 	/* prettylights-syntax-storage-modifier-import */
-	color: colors.$db-neutral-bg-basic-level-1-default;
+	color: colors.$db-warning-on-bg-basic-emphasis-90-default;
 }
 .hljs-section {
 	/* prettylights-syntax-markup-heading */