feat: add D2 theme support and update documentation with architecture diagrams

- Introduced 'astro-d2' package and integrated D2 theme overrides for light and dark modes
- Updated documentation to include detailed D2 architecture and task lifecycle diagrams
- Modified package.json to include 'astro-d2' dependency
- Enhanced Astro configuration with new theme settings and diagrams for better clarity

Author: jumski

.github/actions/setup-d2/action.yml

@@ -0,0 +1,23 @@
+name: 'Setup D2'
+description: 'Install D2 diagramming tool with retry logic'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install D2
+      shell: bash
+      run: |
+        for i in 1 2 3 4 5; do
+          echo "Attempt $i to install D2..."
+          if curl -fsSL https://d2lang.com/install.sh | sh -s --; then
+            echo "D2 installed successfully"
+            break
+          else
+            if [ $i -eq 5 ]; then
+              echo "Failed to install D2 after 5 attempts"
+              exit 1
+            fi
+            echo "Install failed, retrying in 5 seconds..."
+            sleep 5
+          fi
+        done

.github/workflows/ci.yml

@@ -83,6 +83,8 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           atlas-cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
 
+      - uses: ./.github/actions/setup-d2
+
       - name: Set Nx base for affected commands
         run: |
           echo "NX_BASE=origin/main" >> $GITHUB_ENV
@@ -306,6 +308,8 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           atlas-cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
 
+      - uses: ./.github/actions/setup-d2
+
       - name: Check if website is affected
         id: check-affected
         run: |

pkgs/website/.gitignore

@@ -19,4 +19,7 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# generated files
 public/edge-worker/
+public/d2/

pkgs/website/astro.config.mjs

@@ -8,6 +8,7 @@ import robotsTxt from 'astro-robots-txt';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import starlightContextualMenu from 'starlight-contextual-menu';
 import starlightImageZoom from 'starlight-image-zoom';
+import d2 from 'astro-d2';
 import { fileURLToPath } from 'url';
 import path from 'path';
 
@@ -70,6 +71,7 @@ export default defineConfig({
   redirects,
 
   integrations: [
+    d2(),
     react({
       include: ['**/components/**/*.tsx'],
       exclude: ['**/pages/**/*'],
@@ -433,6 +435,7 @@ export default defineConfig({
               '/author',
               '/demos',
               '/demo-colors',
+              '/d2-guide',
               '/news',
               '/news/**',
               '/edge-worker',

pkgs/website/package.json

@@ -22,6 +22,7 @@
     "@types/react-dom": "^19.1.7",
     "@vercel/analytics": "^1.5.0",
     "astro": "^5.7.14",
+    "astro-d2": "^0.8.0",
     "astro-robots-txt": "^1.0.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",

pkgs/website/src/assets/pgflow-theme.d2

@@ -0,0 +1,103 @@
+vars: {
+  d2-config: {
+    theme-id: 0
+    dark-theme-overrides: {
+      # Canvas background
+      N7: "#121a19"
+
+      # Neutrals - desaturated grays for default nodes
+      N1: "#e8eced"
+      N2: "#c5cacc"
+      N3: "#95a0a3"
+      N4: "#4a5759"
+      N5: "#2d3739"
+      N6: "#1a2324"
+
+      # Borders - neutral grays
+      B1: "#3a4547"
+      B2: "#4a5759"
+      B3: "#5a6769"
+      B4: "#1a2324"
+      B5: "#2d3739"
+      B6: "#4a5759"
+
+      # Semantic colors - intentional states
+      AA2: "#a87c45"
+      AA4: "#a33636"
+      AA5: "#4d3d2b"
+      AB4: "#247056"
+      AB5: "#34578f"
+    }
+  }
+}
+
+# Semantic color classes for workflow states
+classes: {
+  # Generic semantic classes (for general use)
+  neutral: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  info: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  warning: {
+    style.fill: "#a87c45"
+    style.stroke: "#d9a66e"
+  }
+  error: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+  success: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+
+  # Run state classes (started, completed, failed)
+  run_started: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  run_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  run_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+
+  # Step state classes (created, started, completed, failed)
+  step_created: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  step_started: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  step_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  step_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+
+  # Task state classes (queued, completed, failed)
+  task_queued: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  task_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  task_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+}