@nqlib/nqui 0.3.2 → 0.4.0

package/docs/internal-notes/BUILD_VERIFICATION.md

@@ -0,0 +1,174 @@
+# Build Verification Report
+
+This document provides a comprehensive comparison between source CSS files and the built `dist/styles.css` to ensure no content is missing or broken during the build process.
+
+## Verification Script
+
+Run the verification script after building:
+
+```bash
+npm run verify:build
+```
+
+Or manually:
+
+```bash
+node scripts/verify-build.js
+```
+
+## Verification Checks
+
+The verification script performs the following checks:
+
+### 1. @source inline() Directives
+- ✅ Verifies all 15 `@source inline()` directives are preserved
+- ✅ Checks that all categories are present (Layout, Spacing, Typography, etc.)
+- ✅ Ensures no directives are missing or duplicated
+
+### 2. :root CSS Variables
+- ✅ Extracts all CSS variables from `src/index.css`, `src/styles/colors.css`, and `src/styles/elevation.css`
+- ✅ Verifies all variables are present in the built CSS
+- ✅ Checks for missing or extra variables
+
+### 3. .dark CSS Variables
+- ✅ Extracts all dark mode CSS variables from source files
+- ✅ Verifies all dark mode variables are preserved
+- ✅ Ensures proper merging of variables from multiple sources
+
+### 4. Custom CSS Classes
+- ✅ Checks for custom `.nqui-*` classes (e.g., `.nqui-button-gradient`, `.nqui-debug-panel`)
+- ✅ Verifies all custom classes are present in the built CSS
+
+### 5. Utility Classes in @source inline()
+- ✅ Extracts all utility class names from `@source inline()` directives
+- ✅ Verifies all 137+ utility classes are preserved
+- ✅ Ensures no utility classes are missing
+
+### 6. Critical Patterns
+- ✅ Checks for presence of `@source inline()` directives
+- ✅ Verifies `:root` and `.dark` blocks exist
+- ✅ Validates specific elevation variables (--z-base, --z-content, etc.)
+- ✅ Validates specific color variables (--primary-500, --background, etc.)
+
+### 7. Unwanted Patterns
+- ✅ Ensures `@import` directives are removed
+- ✅ Ensures `@custom-variant` directives are removed
+- ✅ Ensures framework-specific `@source` directives are removed
+
+## Expected Results
+
+### File Sizes
+- **Source index.css**: ~20 KB
+- **Built styles.css**: ~35 KB (includes merged colors.css and elevation.css)
+- **Colors.css**: ~6 KB
+- **Elevation.css**: ~10 KB
+
+### Content Counts
+- **@source inline() directives**: 15 (17 occurrences including comments)
+- **:root blocks**: 1 (merged from all sources)
+- **.dark blocks**: 1 (merged from all sources)
+- **CSS variables**: ~240 total
+- **Custom classes**: 4 (.nqui-button-gradient, .nqui-button-shadow, .nqui-debug-panel, .nqui-shiki-container)
+- **@keyframes**: 6
+- **@layer base**: 1
+
+### Structure Verification
+- ✅ `@source inline()` directives present
+- ✅ `@theme inline` present
+- ✅ `:root` block present
+- ✅ `.dark` block present
+- ✅ Elevation variables present (11 variables)
+- ✅ Color variables present (all primary, background, foreground, etc.)
+- ✅ Custom classes present
+- ✅ No `@import` directives
+- ✅ No `@custom-variant` directives
+
+## Build Process
+
+The build process (`scripts/build-styles.js`) performs the following steps:
+
+1. **Extract @source inline() directives** - Preserves all `@source inline()` directives before processing
+2. **Remove framework-specific directives** - Removes `@import`, `@custom-variant`, and non-inline `@source` directives
+3. **Extract CSS variables** - Extracts `:root` and `.dark` blocks from:
+   - `src/index.css`
+   - `src/styles/colors.css`
+   - `src/styles/elevation.css`
+4. **Merge variables** - Merges variables from all sources in the correct order:
+   - Elevation variables first
+   - Color system variables second
+   - Additional variables from index.css last
+5. **Preserve custom classes** - Keeps all custom CSS classes (`.nqui-*`)
+6. **Preserve @theme inline** - Keeps the `@theme inline` block
+7. **Preserve @keyframes** - Keeps all animation keyframes
+8. **Add header** - Adds documentation header
+9. **Prepend @source inline()** - Adds extracted `@source inline()` directives at the top
+
+## Common Issues
+
+### Missing @source inline() Directives
+**Symptom**: Verification fails with "Missing @source inline() directives"
+
+**Cause**: The build script's regex might not be matching multiline directives correctly.
+
+**Fix**: Ensure the regex uses `[\s\S]*?` for multiline matching:
+```javascript
+const sourceInlineRegex = /\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\([\s\S]*?\)\s*;/g;
+```
+
+### Missing CSS Variables
+**Symptom**: Verification fails with "Missing X variables"
+
+**Cause**: The extraction regex might not be handling nested braces correctly.
+
+**Fix**: Ensure the regex uses a pattern that handles nested braces:
+```javascript
+const regex = /:root\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s;
+```
+
+### Duplicate @source inline() Directives
+**Symptom**: Verification shows more directives than expected
+
+**Cause**: The removal regex might not be matching correctly, causing directives to be added twice.
+
+**Fix**: Ensure the removal regex matches the extraction regex exactly.
+
+## Integration with CI/CD
+
+Add verification to your build pipeline:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Build library
+  run: npm run build:lib
+
+- name: Verify build integrity
+  run: npm run verify:build
+```
+
+## Manual Verification
+
+To manually verify specific aspects:
+
+```bash
+# Check @source inline() directives
+grep -c "@source inline" dist/styles.css
+
+# Check CSS variables
+grep -c "--.*:" dist/styles.css
+
+# Check custom classes
+grep -c "\.nqui-" dist/styles.css
+
+# Check for unwanted patterns
+grep "@import" dist/styles.css  # Should return nothing
+grep "@custom-variant" dist/styles.css  # Should return nothing
+```
+
+## Related Files
+
+- `scripts/build-styles.js` - Build script that generates `dist/styles.css`
+- `scripts/verify-build.js` - Verification script
+- `src/index.css` - Main source CSS file
+- `src/styles/colors.css` - Color system variables
+- `src/styles/elevation.css` - Z-index elevation variables
+- `dist/styles.css` - Built CSS file (generated)