fix: update order of steps in tokens-check workflow (#7)

* feat(theme): complete design tokens documentation and add tokens-check script

* docs: update project plan for task 1.5

* fix: update order of steps in tokens-check workflow

* fix: update install dependencies command to not use frozen-lockfile

Author: christoph2806

.github/workflows/tokens-check.yml

@@ -0,0 +1,38 @@
+name: Design Tokens Check
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'packages/ui-kit/src/theme/**'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'packages/ui-kit/src/theme/**'
+
+jobs:
+  tokens-check:
+    name: Check Design Tokens Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Run tokens-check script
+        working-directory: packages/ui-kit
+        run: pnpm tokens-check 

docs/project_plan.md

@@ -33,8 +33,8 @@ A pragmatic breakdown into **four one‑week sprints** plus a preparatory **Spri
 | 1.2b | Install and configure Storybook addon‑docs.                                                           | Documentation tab shows component documentation.                         | ✓      |
 | 1.2c | Configure and verify Storybook addon‑a11y.                                                            | axe‑a11y addon shows zero violations.                                    | ✓      |
 | 1.3  | Add global theme bridging (`theme.css` ↔ DaisyUI).                                                   | Cypress visual diff (light/dark) matches golden images.                  | ✓      |
-| 1.4  | Create first **AuthShell** layout with logo slot.                                                     | Rendered via Storybook; Playwright snapshot approved.                    | PR     |
-| 1.5  | Document design tokens (`DESIGN_TOKENS.md`).                                                          | File exists; CI step `tokens-check` verifies presence of each CSS var.   |        |
+| 1.4  | Create first **AuthShell** layout with logo slot.                                                     | Rendered via Storybook; Playwright snapshot approved.                    | ✓      |
+| 1.5  | Document design tokens (`DESIGN_TOKENS.md`).                                                          | File exists; CI step `tokens-check` verifies presence of each CSS var.   | PR     |
 
 ---
 

packages/ui-kit/package.json

@@ -30,7 +30,8 @@
     "theme-screenshots": "cypress run --spec \"cypress/e2e/theme.cy.ts\"",
     "playwright:install": "playwright install",
     "playwright:test": "playwright test",
-    "playwright:update-snapshots": "playwright test --update-snapshots"
+    "playwright:update-snapshots": "playwright test --update-snapshots",
+    "tokens-check": "node scripts/tokens-check.js"
   },
   "dependencies": {
     "@radix-ui/react-slot": "^1.0.2",

packages/ui-kit/scripts/tokens-check.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Design tokens consistency checker
+ * 
+ * This script ensures that all CSS variables defined in theme.css
+ * are properly documented in DESIGN_TOKENS.md
+ */
+
+/* global console, process */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get current file and directory paths
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// File paths
+const themeCssPath = path.join(__dirname, '../src/theme/theme.css');
+const tokensMdPath = path.join(__dirname, '../src/theme/DESIGN_TOKENS.md');
+
+// Read the files
+const themeCss = fs.readFileSync(themeCssPath, 'utf8');
+const tokensMd = fs.readFileSync(tokensMdPath, 'utf8');
+
+// Extract CSS variables from theme.css
+function extractCssVariables(css) {
+    const regex = /--[\w-]+(?=:)/g;
+    const matches = css.match(regex);
+
+    // Remove duplicates (variables can appear in both :root and .dark)
+    return [...new Set(matches)];
+}
+
+// Check if variables are documented in DESIGN_TOKENS.md
+function checkVariablesDocumented(variables, doc) {
+    const undocumented = [];
+
+    for (const variable of variables) {
+        const variableRegex = new RegExp(`\`${variable}\``, 'g');
+        if (!variableRegex.test(doc)) {
+            undocumented.push(variable);
+        }
+    }
+
+    return undocumented;
+}
+
+// Main function
+function main() {
+    console.log('🔍 Checking design tokens documentation...');
+
+    const cssVariables = extractCssVariables(themeCss);
+    console.log(`Found ${cssVariables.length} CSS variables in theme.css`);
+
+    const undocumentedVariables = checkVariablesDocumented(cssVariables, tokensMd);
+
+    if (undocumentedVariables.length === 0) {
+        console.log('✅ All CSS variables are properly documented in DESIGN_TOKENS.md');
+        process.exit(0);
+    } else {
+        console.error('❌ The following CSS variables are not documented in DESIGN_TOKENS.md:');
+        undocumentedVariables.forEach(v => console.error(`   - ${v}`));
+        console.error(`\nPlease add documentation for these ${undocumentedVariables.length} variables to maintain the design system consistency.`);
+        process.exit(1);
+    }
+}
+
+main(); 

packages/ui-kit/src/theme/DESIGN_TOKENS.md

@@ -57,12 +57,16 @@ This document provides an overview of the design tokens used in the UI-Kit. Thes
 
 ### Shadows
 
-| Token         | Description    |
-| ------------- | -------------- |
-| `--shadow-sm` | Small shadow   |
-| `--shadow`    | Default shadow |
-| `--shadow-md` | Medium shadow  |
-| `--shadow-lg` | Large shadow   |
+| Token               | Value                | Description                         |
+| ------------------- | -------------------- | ----------------------------------- |
+| `--shadow-color`    | `220 3% 15%` (light) | Color used for shadow calculations  |
+|                     | `220 40% 2%` (dark)  | Darker in dark mode                 |
+| `--shadow-strength` | `1%` (light)         | Opacity strength for shadow effects |
+|                     | `4%` (dark)          | Stronger in dark mode               |
+| `--shadow-sm`       | Calculated value     | Small shadow                        |
+| `--shadow`          | Calculated value     | Default shadow                      |
+| `--shadow-md`       | Calculated value     | Medium shadow                       |
+| `--shadow-lg`       | Calculated value     | Large shadow                        |
 
 ## Theme Switching