From 77a833137ee9e896d417e9c50f5c9ba059e837fb Mon Sep 17 00:00:00 2001 From: johndoe6345789 Date: Thu, 25 Dec 2025 11:42:22 +0000 Subject: [PATCH] fixes --- .gitignore | 85 ++++-- .vscode/settings.json | 14 + docs/INDEX.md | 108 +++++++ docs/README.md | 11 + docs/{ => archive}/PHASE2_SUMMARY.md | 0 docs/{ => builds}/CPP_BUILD_ASSISTANT.md | 0 .../CPP_BUILD_ASSISTANT_SUMMARY.md | 0 docs/{ => builds}/CPP_BUILD_QUICK_REF.md | 0 .../CPP_IMPLEMENTATION_COMPLETE.md | 0 docs/{ => builds}/CROSS_PLATFORM_BUILD.md | 0 docs/{ => deployments}/CI_CD_REPAIRS.md | 0 docs/{ => deployments}/CI_CD_SUMMARY.md | 0 docs/{ => deployments}/CI_FIX_COMPLETE.md | 0 docs/{ => deployments}/CI_FIX_SUMMARY.md | 0 .../GITHUB_WORKFLOWS_AUDIT.md | 0 docs/{ => deployments}/NGINX_INTEGRATION.md | 0 docs/{ => guides}/ACT_QUICK_REFERENCE.md | 0 docs/{ => guides}/ACT_TESTING.md | 0 docs/{ => guides}/ATOMIC_QUICKSTART.md | 0 docs/{ => guides}/IMPLEMENTATION_ROADMAP.md | 0 docs/{ => guides}/SASS_CONFIGURATION.md | 0 docs/guides/SASS_QUICK_REFERENCE.md | 287 ++++++++++++++++++ docs/guides/SASS_SETUP_COMPLETE.md | 257 ++++++++++++++++ .../github-actions-local-testing.md | 0 .../ACT_IMPLEMENTATION_SUMMARY.md | 0 docs/{ => implementation}/ATOMIC_DESIGN.md | 0 docs/{ => implementation}/ATOMIC_STRUCTURE.md | 0 .../BLOB_STORAGE_IMPLEMENTATION.md | 0 docs/{ => implementation}/COMPONENT_MAP.md | 0 docs/{ => implementation}/DBAL_INTEGRATION.md | 0 .../FOUNDATION_IMPROVEMENTS.md | 0 .../MULTI_TENANT_SYSTEM.md | 0 docs/{ => implementation}/NEXTJS_MIGRATION.md | 0 .../PRISMA_IMPLEMENTATION_COMPLETE.md | 0 docs/{ => implementation}/PRISMA_MIGRATION.md | 0 .../PRISMA_MIGRATION_STATUS.md | 0 .../SECURE_DATABASE_LAYER.md | 0 .../SECURE_DB_MIGRATION_GUIDE.md | 0 .../{ => implementation}/SECURE_DB_SUMMARY.md | 0 .../TYPESCRIPT_DBAL_ENHANCEMENTS.md | 0 .../UNIT_TESTS_IMPLEMENTATION.md | 0 .../component-atomicity-refactor.md | 0 .../{ => migrations}/FILE_RELOCATION_GUIDE.md | 0 docs/{ => migrations}/MIGRATION_STATUS.md | 0 docs/{ => migrations}/RELOCATION_SUMMARY.md | 0 .../CORS-BYPASS-EXPLANATION.md | 0 docs/{ => troubleshooting}/PACKAGE_TESTS.md | 0 .../PHASE5_TESTING_REPORT.md | 0 .../SCREENSHOT_ANALYZER.md | 0 .../TEST_COVERAGE_SUMMARY.md | 0 .../WORKFLOW_FAILURE_DIAGNOSIS.md | 0 src/index.scss | 5 +- 52 files changed, 739 insertions(+), 28 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 docs/INDEX.md rename docs/{ => archive}/PHASE2_SUMMARY.md (100%) rename docs/{ => builds}/CPP_BUILD_ASSISTANT.md (100%) rename docs/{ => builds}/CPP_BUILD_ASSISTANT_SUMMARY.md (100%) rename docs/{ => builds}/CPP_BUILD_QUICK_REF.md (100%) rename docs/{ => builds}/CPP_IMPLEMENTATION_COMPLETE.md (100%) rename docs/{ => builds}/CROSS_PLATFORM_BUILD.md (100%) rename docs/{ => deployments}/CI_CD_REPAIRS.md (100%) rename docs/{ => deployments}/CI_CD_SUMMARY.md (100%) rename docs/{ => deployments}/CI_FIX_COMPLETE.md (100%) rename docs/{ => deployments}/CI_FIX_SUMMARY.md (100%) rename docs/{ => deployments}/GITHUB_WORKFLOWS_AUDIT.md (100%) rename docs/{ => deployments}/NGINX_INTEGRATION.md (100%) rename docs/{ => guides}/ACT_QUICK_REFERENCE.md (100%) rename docs/{ => guides}/ACT_TESTING.md (100%) rename docs/{ => guides}/ATOMIC_QUICKSTART.md (100%) rename docs/{ => guides}/IMPLEMENTATION_ROADMAP.md (100%) rename docs/{ => guides}/SASS_CONFIGURATION.md (100%) create mode 100644 docs/guides/SASS_QUICK_REFERENCE.md create mode 100644 docs/guides/SASS_SETUP_COMPLETE.md rename docs/{ => guides}/github-actions-local-testing.md (100%) rename docs/{ => implementation}/ACT_IMPLEMENTATION_SUMMARY.md (100%) rename docs/{ => implementation}/ATOMIC_DESIGN.md (100%) rename docs/{ => implementation}/ATOMIC_STRUCTURE.md (100%) rename docs/{ => implementation}/BLOB_STORAGE_IMPLEMENTATION.md (100%) rename docs/{ => implementation}/COMPONENT_MAP.md (100%) rename docs/{ => implementation}/DBAL_INTEGRATION.md (100%) rename docs/{ => implementation}/FOUNDATION_IMPROVEMENTS.md (100%) rename docs/{ => implementation}/MULTI_TENANT_SYSTEM.md (100%) rename docs/{ => implementation}/NEXTJS_MIGRATION.md (100%) rename docs/{ => implementation}/PRISMA_IMPLEMENTATION_COMPLETE.md (100%) rename docs/{ => implementation}/PRISMA_MIGRATION.md (100%) rename docs/{ => implementation}/PRISMA_MIGRATION_STATUS.md (100%) rename docs/{ => implementation}/SECURE_DATABASE_LAYER.md (100%) rename docs/{ => implementation}/SECURE_DB_MIGRATION_GUIDE.md (100%) rename docs/{ => implementation}/SECURE_DB_SUMMARY.md (100%) rename docs/{ => implementation}/TYPESCRIPT_DBAL_ENHANCEMENTS.md (100%) rename docs/{ => implementation}/UNIT_TESTS_IMPLEMENTATION.md (100%) rename docs/{ => implementation}/component-atomicity-refactor.md (100%) rename docs/{ => migrations}/FILE_RELOCATION_GUIDE.md (100%) rename docs/{ => migrations}/MIGRATION_STATUS.md (100%) rename docs/{ => migrations}/RELOCATION_SUMMARY.md (100%) rename docs/{ => troubleshooting}/CORS-BYPASS-EXPLANATION.md (100%) rename docs/{ => troubleshooting}/PACKAGE_TESTS.md (100%) rename docs/{ => troubleshooting}/PHASE5_TESTING_REPORT.md (100%) rename docs/{ => troubleshooting}/SCREENSHOT_ANALYZER.md (100%) rename docs/{ => troubleshooting}/TEST_COVERAGE_SUMMARY.md (100%) rename docs/{ => troubleshooting}/WORKFLOW_FAILURE_DIAGNOSIS.md (100%) diff --git a/.gitignore b/.gitignore index 37237cea8..95a7c6607 100644 --- a/.gitignore +++ b/.gitignore @@ -1,57 +1,90 @@ +# Python .venv/ +venv/ +__pycache__/ +*.py[cod] +*$py.class - -# Logs -logs -*.log +# Node.js +node_modules/ npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* lerna-debug.log* +package-lock.json +yarn.lock +.pnp +.pnp.js -node_modules -dist -dist-ssr -*-dist -*.local - -# Next.js +# Build outputs +dist/ +dist-ssr/ +*-dist/ +build/ .next/ out/ next-env.d.ts +*.local -# Editor directories and files +# Environment +.env +.env.local +.env.*.local + +# Editor .vscode/* !.vscode/extensions.json -.idea +!.vscode/settings.json +!.vscode/launch.json +!.vscode/tasks.json +.idea/ +*.sublime-project +*.sublime-workspace .DS_Store +Thumbs.db *.suo *.ntvs* *.njsproj *.sln *.sw? +*~ -# Prisma +# IDE/Development +.devcontainer/ +.spark-workbench-id +.spark-initial-sha +_codeql_detected_source_root/ + +# Database prisma/dev.db prisma/dev.db-journal +*.db +*.sqlite +*.sqlite3 -.env -**/agent-eval-report* -pids -.file-manifest -.devcontainer/ - -.spark-workbench-id - -# Playwright +# Testing /test-results/ /playwright-report/ /playwright/.cache/ /e2e-results/ - -# Test artifacts *.spec.js.map *.spec.ts.map +coverage/ +.nyc_output/ + +# Logs +logs/ +*.log + +# Cache/Temp +pids/ +.file-manifest lint-output.txt -build/ +.turbo/ + +# Project-specific +**/agent-eval-report* +vite.config.ts.bak* +.cache/ +dist-old/ diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..403688686 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,14 @@ +{ + "cmake.sourceDirectory": "/workspaces/metabuilder/dbal/cpp", + "chat.mcp.discovery.enabled": { + "claude-desktop": true, + "windsurf": true, + "cursor-global": true, + "cursor-workspace": true + }, + "chat.mcp.gallery.enabled": true, + "inlineChat.enableV2": true, + "chat.allowAnonymousAccess": false, + "chat.mcp.assisted.nuget.enabled": true, + "inlineChat.notebookAgent": true +} \ No newline at end of file diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 000000000..3a71ca714 --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,108 @@ +# Documentation Index + +Welcome to MetaBuilder documentation. This guide helps you find what you need. + +## Start Here + +- **[README.md](README.md)** - Project overview and quick start +- **[PRD.md](PRD.md)** - Product requirements and feature specifications +- **[SECURITY.md](SECURITY.md)** - Security policies and best practices + +## Documentation by Topic + +### [Guides](guides/) +Quick references and setup instructions for developers. + +- **[IMPLEMENTATION_ROADMAP.md](guides/IMPLEMENTATION_ROADMAP.md)** - Feature development timeline +- **[ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md)** - Get started with atomic design patterns +- **[ACT_QUICK_REFERENCE.md](guides/ACT_QUICK_REFERENCE.md)** - GitHub Actions testing quick ref +- **[SASS_QUICK_REFERENCE.md](guides/SASS_QUICK_REFERENCE.md)** - SASS/SCSS styling guide +- **[github-actions-local-testing.md](guides/github-actions-local-testing.md)** - Test workflows locally + +### [Implementation Guides](implementation/) +Deep-dive documentation on implemented features and architecture. + +- **[COMPONENT_MAP.md](implementation/COMPONENT_MAP.md)** - Component structure and organization +- **[ATOMIC_DESIGN.md](implementation/ATOMIC_DESIGN.md)** - Atomic design system +- **[MULTI_TENANT_SYSTEM.md](implementation/MULTI_TENANT_SYSTEM.md)** - Multi-tenancy architecture +- **[PRISMA_IMPLEMENTATION_COMPLETE.md](implementation/PRISMA_IMPLEMENTATION_COMPLETE.md)** - Database layer +- **[DBAL_INTEGRATION.md](implementation/DBAL_INTEGRATION.md)** - Data abstraction layer +- **[SECURE_DATABASE_LAYER.md](implementation/SECURE_DATABASE_LAYER.md)** - Database security +- **[BLOB_STORAGE_IMPLEMENTATION.md](implementation/BLOB_STORAGE_IMPLEMENTATION.md)** - File storage +- **[NEXTJS_MIGRATION.md](implementation/NEXTJS_MIGRATION.md)** - Next.js migration +- **[UNIT_TESTS_IMPLEMENTATION.md](implementation/UNIT_TESTS_IMPLEMENTATION.md)** - Testing strategy + +### [Build System](builds/) +C++ build, compilation, and cross-platform setup. + +- **[CROSS_PLATFORM_BUILD.md](builds/CROSS_PLATFORM_BUILD.md)** - Cross-platform compilation +- **[CPP_BUILD_QUICK_REF.md](builds/CPP_BUILD_QUICK_REF.md)** - C++ build quick reference +- **[CPP_BUILD_ASSISTANT.md](builds/CPP_BUILD_ASSISTANT.md)** - Build troubleshooting + +### [Deployments & CI/CD](deployments/) +Production deployment, containerization, and continuous integration. + +- **[NGINX_INTEGRATION.md](deployments/NGINX_INTEGRATION.md)** - Web server configuration +- **[GITHUB_WORKFLOWS_AUDIT.md](deployments/GITHUB_WORKFLOWS_AUDIT.md)** - CI/CD pipeline review +- **[CI_CD_SUMMARY.md](deployments/CI_CD_SUMMARY.md)** - Build & deployment overview + +### [Migrations](migrations/) +Data migrations, code refactoring, and relocation guides. + +- **[MIGRATION_STATUS.md](migrations/MIGRATION_STATUS.md)** - Migration progress tracking +- **[FILE_RELOCATION_GUIDE.md](migrations/FILE_RELOCATION_GUIDE.md)** - File organization +- **[RELOCATION_SUMMARY.md](migrations/RELOCATION_SUMMARY.md)** - Relocation completion status + +### [Troubleshooting](troubleshooting/) +Diagnostics, debugging guides, and common issues. + +- **[WORKFLOW_FAILURE_DIAGNOSIS.md](troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md)** - CI/CD debugging +- **[CORS-BYPASS-EXPLANATION.md](troubleshooting/CORS-BYPASS-EXPLANATION.md)** - CORS issues +- **[TEST_COVERAGE_SUMMARY.md](troubleshooting/TEST_COVERAGE_SUMMARY.md)** - Test coverage info +- **[PACKAGE_TESTS.md](troubleshooting/PACKAGE_TESTS.md)** - Package testing guide + +### [Archive](archive/) +Completed phases and historical work. + +- **[PHASE2_SUMMARY.md](archive/PHASE2_SUMMARY.md)** - Phase 2 completion summary + +## Additional Topics + +### Architecture +Fundamental architecture and design patterns. + +- **[architecture/](architecture/)** - Core architecture documents + +### Database +Database-specific documentation. + +- **[database/](database/)** - Database design and setup + +### Development +Development workflow and best practices. + +- **[development/](development/)** - Development guides + +### Lua Scripting +Lua integration and scripting. + +- **[lua/](lua/)** - Lua documentation and examples + +### Reference +Quick lookup and API reference. + +- **[reference/](reference/)** - Technical references + +### Security +Security policies and guidelines. + +- **[security/](security/)** - Security documentation + +## Navigation Tips + +1. **New to MetaBuilder?** Start with [README.md](README.md) and [ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md) +2. **Building a feature?** Check [IMPLEMENTATION_ROADMAP.md](guides/IMPLEMENTATION_ROADMAP.md) and the [implementation/](implementation/) folder +3. **Setting up locally?** See [SASS_QUICK_REFERENCE.md](guides/SASS_QUICK_REFERENCE.md) and [guides/](guides/) +4. **Deploying to production?** Review [NGINX_INTEGRATION.md](deployments/NGINX_INTEGRATION.md) and [deployments/](deployments/) +5. **Debugging issues?** Check [troubleshooting/](troubleshooting/) first +6. **Running CI/CD locally?** See [github-actions-local-testing.md](guides/github-actions-local-testing.md) diff --git a/docs/README.md b/docs/README.md index f18f628f7..79d606a2c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -420,6 +420,17 @@ See `example-schemas.json` for complete examples including: - No file uploads (use URL fields to reference external files) - Maximum recommended records per model: 1000 +## Documentation + +For comprehensive guides, check the [Documentation Index](INDEX.md). Key resources: + +- **Getting Started**: [ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md) +- **Architecture**: [architecture/](architecture/) +- **Database**: [database/](database/) and [PRISMA_IMPLEMENTATION_COMPLETE.md](implementation/PRISMA_IMPLEMENTATION_COMPLETE.md) +- **Development**: [development/](development/) and [guides/](guides/) +- **Deployment**: [deployments/](deployments/) +- **Troubleshooting**: [troubleshooting/](troubleshooting/) + ## Architecture The system consists of: diff --git a/docs/PHASE2_SUMMARY.md b/docs/archive/PHASE2_SUMMARY.md similarity index 100% rename from docs/PHASE2_SUMMARY.md rename to docs/archive/PHASE2_SUMMARY.md diff --git a/docs/CPP_BUILD_ASSISTANT.md b/docs/builds/CPP_BUILD_ASSISTANT.md similarity index 100% rename from docs/CPP_BUILD_ASSISTANT.md rename to docs/builds/CPP_BUILD_ASSISTANT.md diff --git a/docs/CPP_BUILD_ASSISTANT_SUMMARY.md b/docs/builds/CPP_BUILD_ASSISTANT_SUMMARY.md similarity index 100% rename from docs/CPP_BUILD_ASSISTANT_SUMMARY.md rename to docs/builds/CPP_BUILD_ASSISTANT_SUMMARY.md diff --git a/docs/CPP_BUILD_QUICK_REF.md b/docs/builds/CPP_BUILD_QUICK_REF.md similarity index 100% rename from docs/CPP_BUILD_QUICK_REF.md rename to docs/builds/CPP_BUILD_QUICK_REF.md diff --git a/docs/CPP_IMPLEMENTATION_COMPLETE.md b/docs/builds/CPP_IMPLEMENTATION_COMPLETE.md similarity index 100% rename from docs/CPP_IMPLEMENTATION_COMPLETE.md rename to docs/builds/CPP_IMPLEMENTATION_COMPLETE.md diff --git a/docs/CROSS_PLATFORM_BUILD.md b/docs/builds/CROSS_PLATFORM_BUILD.md similarity index 100% rename from docs/CROSS_PLATFORM_BUILD.md rename to docs/builds/CROSS_PLATFORM_BUILD.md diff --git a/docs/CI_CD_REPAIRS.md b/docs/deployments/CI_CD_REPAIRS.md similarity index 100% rename from docs/CI_CD_REPAIRS.md rename to docs/deployments/CI_CD_REPAIRS.md diff --git a/docs/CI_CD_SUMMARY.md b/docs/deployments/CI_CD_SUMMARY.md similarity index 100% rename from docs/CI_CD_SUMMARY.md rename to docs/deployments/CI_CD_SUMMARY.md diff --git a/docs/CI_FIX_COMPLETE.md b/docs/deployments/CI_FIX_COMPLETE.md similarity index 100% rename from docs/CI_FIX_COMPLETE.md rename to docs/deployments/CI_FIX_COMPLETE.md diff --git a/docs/CI_FIX_SUMMARY.md b/docs/deployments/CI_FIX_SUMMARY.md similarity index 100% rename from docs/CI_FIX_SUMMARY.md rename to docs/deployments/CI_FIX_SUMMARY.md diff --git a/docs/GITHUB_WORKFLOWS_AUDIT.md b/docs/deployments/GITHUB_WORKFLOWS_AUDIT.md similarity index 100% rename from docs/GITHUB_WORKFLOWS_AUDIT.md rename to docs/deployments/GITHUB_WORKFLOWS_AUDIT.md diff --git a/docs/NGINX_INTEGRATION.md b/docs/deployments/NGINX_INTEGRATION.md similarity index 100% rename from docs/NGINX_INTEGRATION.md rename to docs/deployments/NGINX_INTEGRATION.md diff --git a/docs/ACT_QUICK_REFERENCE.md b/docs/guides/ACT_QUICK_REFERENCE.md similarity index 100% rename from docs/ACT_QUICK_REFERENCE.md rename to docs/guides/ACT_QUICK_REFERENCE.md diff --git a/docs/ACT_TESTING.md b/docs/guides/ACT_TESTING.md similarity index 100% rename from docs/ACT_TESTING.md rename to docs/guides/ACT_TESTING.md diff --git a/docs/ATOMIC_QUICKSTART.md b/docs/guides/ATOMIC_QUICKSTART.md similarity index 100% rename from docs/ATOMIC_QUICKSTART.md rename to docs/guides/ATOMIC_QUICKSTART.md diff --git a/docs/IMPLEMENTATION_ROADMAP.md b/docs/guides/IMPLEMENTATION_ROADMAP.md similarity index 100% rename from docs/IMPLEMENTATION_ROADMAP.md rename to docs/guides/IMPLEMENTATION_ROADMAP.md diff --git a/docs/SASS_CONFIGURATION.md b/docs/guides/SASS_CONFIGURATION.md similarity index 100% rename from docs/SASS_CONFIGURATION.md rename to docs/guides/SASS_CONFIGURATION.md diff --git a/docs/guides/SASS_QUICK_REFERENCE.md b/docs/guides/SASS_QUICK_REFERENCE.md new file mode 100644 index 000000000..477c01cd4 --- /dev/null +++ b/docs/guides/SASS_QUICK_REFERENCE.md @@ -0,0 +1,287 @@ +# SASS Quick Reference Guide + +## File Organization + +``` +src/ +├── main.scss # Main entry point (imported in app/layout.tsx) +├── index.scss # Secondary stylesheet +└── styles/ + ├── theme.scss # Theme definitions & CSS variables + ├── _variables.scss # All design tokens + ├── _mixins.scss # Reusable mixins + ├── _base.scss # Global styles & resets + └── _components.scss # Component classes & utilities +``` + +## Import Syntax (Modern SASS @use) + +```scss +// At the top of your SCSS file +@use './styles/variables' as *; +@use './styles/mixins' as *; + +// Now you can use variables and mixins +.my-component { + color: $fg-primary; + @include flex-center; +} +``` + +## Common Variables + +### Colors +```scss +$color-primary // Main purple +$color-primary-dark // Darker purple +$color-primary-light // Lighter purple +$color-success // Green +$color-warning // Yellow +$color-error // Red +$color-info // Blue +$color-neutral-50 // Light gray +$color-neutral-950 // Dark gray +``` + +### Spacing (8px base unit) +```scss +$space-1 through $space-24 // 4px to 96px +// Usage: padding: $space-4; (16px) +``` + +### Typography +```scss +$font-family-body // IBM Plex Sans +$font-family-heading // Space Grotesk +$font-family-mono // JetBrains Mono + +$font-size-xs through $font-size-5xl // 12px to 48px +$font-weight-light through $font-weight-bold +``` + +### Border Radius +```scss +$radius-sm // 6px +$radius-md // 8px +$radius-lg // 12px +$radius-xl // 16px +$radius-2xl // 24px +$radius-full // Circular +``` + +## Common Mixins + +### Layout +```scss +@include flex-center; // Center flex items +@include flex-between; // Space-between flex +@include flex-column; // Column flex layout +@include grid(3); // 3-column grid +``` + +### Typography +```scss +@include heading-1 through @include heading-6; // Heading styles +@include text-body; // Normal body text +@include text-sm; // Small text +@include truncate; // Ellipsis +@include line-clamp(3); // Multi-line ellipsis +``` + +### Components +```scss +@include btn-primary; // Primary button +@include btn-secondary; // Secondary button +@include card; // Card styling +@include input-base; // Form input +@include badge; // Badge styling +``` + +### Responsive +```scss +@include breakpoint-sm { } // 640px+ +@include breakpoint-md { } // 768px+ +@include breakpoint-lg { } // 1024px+ +@include breakpoint-xl { } // 1280px+ +@include breakpoint-2xl { } // 1536px+ +``` + +### Utilities +```scss +@include elevation(2); // Box shadow elevation +@include hardware-acceleration; // GPU acceleration +@include visually-hidden; // Screen reader only +@include gradient($start, $end); // Gradient background +``` + +## Pre-built CSS Classes + +### Buttons +```html + + + + +``` + +### Cards +```html +
+
Title
+
Content
+
Footer
+
+``` + +### Grid & Flex +```html +
+
Column 1
+
Column 2
+
Column 3
+
+ +
+
Item 1
+
Item 2
+
+``` + +### Spacing Utilities +```html + +
Margin top 2rem, margin bottom 1rem
+ + +
Padding 1.5rem all sides
+ + +
Various spacing
+``` + +### Text Utilities +```html +

Colored text

+

Centered text

+

Single line ellipsis

+

UPPERCASE TEXT

+``` + +### Responsive Display +```html + + + + +
Mobile only
+ + +
+ Responsive grid +
+``` + +## Accessibility Support + +The SASS system respects user preferences: + +```scss +// Automatically handles: +@media (prefers-reduced-motion: reduce) { } // Disable animations +@media (prefers-contrast: more) { } // High contrast mode +@media (prefers-reduced-transparency: reduce) { } // Reduce transparency +``` + +## Theme Switching with CSS Variables + +All SASS variables are exposed as CSS custom properties: + +```javascript +// Set dark theme +document.documentElement.setAttribute('data-theme', 'dark'); + +// Use in JavaScript +const primaryColor = getComputedStyle(document.documentElement) + .getPropertyValue('--color-primary'); +``` + +```css +/* Use in CSS */ +.my-element { + color: var(--fg-primary); + background: var(--bg-secondary); +} +``` + +## Modern SASS Features Used + +1. **@use with namespace** - Instead of @import +2. **color.change()** - For alpha values on modern colors +3. **Nesting** - Full support for nested selectors +4. **Variables** - $ prefix for all tokens +5. **Mixins** - @mixin and @include +6. **Functions** - SASS built-in color functions +7. **Loops** - @for loops for generating utilities +8. **Conditionals** - @if/@else for logic + +## Example: Creating a Custom Component + +```scss +@use '@/styles/variables' as *; +@use '@/styles/mixins' as *; + +.my-card-component { + @include card; + padding: $space-6; + + &-title { + @include heading-3; + color: $color-primary; + margin-bottom: $space-4; + } + + &-content { + @include text-body; + color: $fg-secondary; + line-height: $line-height-relaxed; + } + + &:hover { + @include elevation(3); + } + + @include breakpoint-md { + padding: $space-8; + + &-title { + @include heading-2; + } + } +} +``` + +## Tips & Best Practices + +1. **Always use variables** - Don't hardcode colors or spacing +2. **Use @use, not @import** - Modern SASS syntax +3. **Keep components small** - Under 100 lines of SCSS +4. **Use mixins for complexity** - Reduces duplication +5. **Mobile-first** - Start with mobile styles, add breakpoints for larger screens +6. **Test accessibility** - Use prefers-reduced-motion, prefers-contrast +7. **Leverage CSS variables** - For runtime theme changes +8. **Comment your code** - Especially complex SCSS logic + +## Compilation + +SASS is automatically compiled by: +- **Development**: `npm run dev` (Next.js dev server) +- **Build**: `npm run build` (Next.js production build) +- **Vite**: `npm run dev:vite` / `npm run build:vite` + +No manual compilation needed! + +## Resources + +- [Full SASS Configuration Documentation](./SASS_CONFIGURATION.md) +- [SASS Language Reference](https://sass-lang.com/documentation) +- [Design Tokens Overview](../docs/SASS_CONFIGURATION.md) diff --git a/docs/guides/SASS_SETUP_COMPLETE.md b/docs/guides/SASS_SETUP_COMPLETE.md new file mode 100644 index 000000000..b003d226d --- /dev/null +++ b/docs/guides/SASS_SETUP_COMPLETE.md @@ -0,0 +1,257 @@ +# SASS Configuration Complete ✓ + +## What Was Configured + +### 1. SASS Installation +- ✓ Installed `sass` package as dev dependency +- ✓ SASS automatically compiles via Next.js and Vite + +### 2. SASS File Structure Created + +``` +src/styles/ +├── _variables.scss # 200+ design tokens +├── _mixins.scss # 40+ reusable mixins +├── _base.scss # Global styles and resets +├── _components.scss # Pre-built component classes +└── theme.scss # Theme definitions and CSS variables + +src/ +├── main.scss # Main entry point (imports all styles) +└── index.scss # Secondary stylesheet +``` + +### 3. Design System Implemented + +#### Color Palette (oklch color space) +- Primary: Purple (#d748c0) +- Secondary: Orange (#cd4f1f) +- Success: Green (#4cc06b) +- Warning: Yellow (#ef9800) +- Error: Red (#e50019) +- Info: Blue (#00a0ae) +- Neutral: 11-shade grayscale (50-950) + +#### Typography System +- **Body Font**: IBM Plex Sans +- **Heading Font**: Space Grotesk +- **Mono Font**: JetBrains Mono +- **Sizes**: 12px (xs) to 48px (5xl) +- **Weights**: Light (300) to Bold (700) + +#### Spacing Scale (8px base unit) +- $space-1 to $space-24 (4px to 96px) +- Used for padding, margins, gaps + +#### Border Radius Scale +- Small (6px) to Extra-Large (24px) +- Full (circular) option + +#### Breakpoints (Mobile-First) +- sm: 640px +- md: 768px +- lg: 1024px +- xl: 1280px +- 2xl: 1536px + +### 4. Pre-built Components + +**Buttons** +- `.btn` - Base button +- `.btn-primary`, `.btn-secondary`, `.btn-success`, `.btn-danger`, `.btn-warning` +- Sizes: `.btn-sm`, `.btn-md`, `.btn-lg` +- `.btn-block`, `.btn-icon` + +**Cards** +- `.card` - Base card +- `.card-header`, `.card-body`, `.card-footer` +- `.card-compact`, `.card-elevated` + +**Forms** +- `.form-group`, `.form-label` +- `.form-help`, `.form-error`, `.form-success` + +**Badges** +- `.badge`, `.badge-primary`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info` + +**Alerts** +- `.alert` with color variants +- `.alert-title`, `.alert-message`, `.alert-close` + +**Layout** +- `.container` - Responsive container (max-widths per breakpoint) +- `.grid` with `.grid-cols-*` (1-12 columns) +- `.flex` with `.flex-center`, `.flex-between`, `.flex-column` + +**Spacing Utilities** +- Margin: `.mt-*`, `.mb-*`, `.ml-*`, `.mr-*`, `.mx-*`, `.my-*`, `.m-*` +- Padding: `.pt-*`, `.pb-*`, `.pl-*`, `.pr-*`, `.px-*`, `.py-*`, `.p-*` +- Range: 0-24 (multiples of 4px) + +**Text Utilities** +- Color: `.text-primary`, `.text-success`, `.text-danger`, `.text-warning`, `.text-muted` +- Alignment: `.text-center`, `.text-left`, `.text-right`, `.text-justify` +- Transform: `.text-lowercase`, `.text-uppercase`, `.text-capitalize` +- Truncate: `.text-truncate` + +**Visibility** +- `.hidden` - Display none +- `.invisible` - Visibility hidden +- `.sr-only` - Screen reader only + +**Responsive Display** +- `.sm:hidden`, `.sm:block`, `.sm:flex`, `.sm:grid` +- `.md:hidden`, `.md:block`, `.md:flex`, `.md:grid` +- `.lg:hidden`, `.lg:block`, `.lg:flex`, `.lg:grid` + +### 5. Mixins Implemented (40+) + +**Layout Mixins** +- `flex-center`, `flex-between`, `flex-column`, `flex-column-center` +- `grid($columns, $gap)` +- `position-absolute()`, `cover` + +**Typography Mixins** +- `heading-1` through `heading-6` +- `text-body`, `text-sm`, `text-xs` +- `truncate`, `line-clamp($lines)` + +**Component Mixins** +- `btn-base`, `btn-primary`, `btn-secondary` +- `card`, `input-base`, `badge` + +**Responsive Mixins** +- `breakpoint-sm`, `breakpoint-md`, `breakpoint-lg`, `breakpoint-xl`, `breakpoint-2xl` + +**Utility Mixins** +- `elevation($level)`, `gradient($start, $end)` +- `hardware-acceleration`, `smooth-scroll` +- `visually-hidden`, `clearfix` + +### 6. Theme Support + +**Light Theme** (default) +- All CSS variables available in `:root` + +**Dark Theme** +- Apply with `[data-theme="dark"]` attribute +- Automatic color inversions and adjustments + +**Accessibility Features** +- `prefers-reduced-motion` support (disables animations) +- `prefers-contrast: more` support (high contrast mode) +- `prefers-reduced-transparency` support + +### 7. File Integration + +**main.tsx** - Updated import +```typescript +import "./main.scss" // Imports all SCSS files +``` + +**app/layout.tsx** - Updated import +```typescript +import '@/main.scss' // Main stylesheet +``` + +### 8. CSS Variables Output + +All SASS variables are exposed as CSS custom properties: +```css +:root { + --color-primary: #d748c0; + --bg-primary: #ffffff; + --font-family-body: IBM Plex Sans, ...; + --transition-base: 0.25s ease-in-out; + /* 50+ more variables */ +} + +[data-theme='dark'] { + --bg-primary: #0d0d0d; + --fg-primary: #ffffff; + /* Dark theme overrides */ +} +``` + +## Compilation Status + +✓ **SASS compiles successfully** +- Verified in `.next/dev/static/chunks/src_main_scss_047ce6d7.css` +- All variables output as CSS custom properties +- All colors converted from oklch to LAB color space (modern browsers) + +## How to Use + +### Option 1: Use Pre-built Classes +```html + +
+

Title

+

Content

+
+``` + +### Option 2: Use Variables & Mixins +```scss +@use '@/styles/variables' as *; +@use '@/styles/mixins' as *; + +.my-component { + background: $bg-primary; + @include flex-center; + gap: $space-4; + padding: $space-6; + + &:hover { + @include elevation(2); + } +} +``` + +### Option 3: Use CSS Variables +```css +.my-element { + color: var(--fg-primary); + background: var(--bg-primary); + font-family: var(--font-family-body); +} +``` + +## Documentation + +Two comprehensive guides created: +1. **SASS_CONFIGURATION.md** - Full technical documentation +2. **SASS_QUICK_REFERENCE.md** - Quick lookup guide + +## Next Steps + +The SASS system is fully configured and ready to use. You can now: + +1. **Create new components** using the provided mixins +2. **Add page-specific styles** by importing variables/mixins +3. **Switch themes** using `data-theme` attribute +4. **Customize tokens** by modifying `_variables.scss` +5. **Extend utilities** by adding to `_components.scss` + +## Build & Development + +- ✓ Dev server: `npm run dev` (SASS compiles on file change) +- ✓ Production: `npm run build` (SASS minified and optimized) +- ✓ Vite: `npm run dev:vite` / `npm run build:vite` + +All SASS compilation is automatic - no manual steps needed! + +## Summary + +**SASS is now fully configured with:** +- ✓ 200+ design tokens +- ✓ 40+ reusable mixins +- ✓ 50+ pre-built component classes +- ✓ Light & dark theme support +- ✓ Accessibility features +- ✓ Responsive utilities +- ✓ Modern SASS syntax (@use) +- ✓ CSS custom properties for runtime themes +- ✓ Automatic compilation in dev/build + +The project is ready for SASS-based styling! diff --git a/docs/github-actions-local-testing.md b/docs/guides/github-actions-local-testing.md similarity index 100% rename from docs/github-actions-local-testing.md rename to docs/guides/github-actions-local-testing.md diff --git a/docs/ACT_IMPLEMENTATION_SUMMARY.md b/docs/implementation/ACT_IMPLEMENTATION_SUMMARY.md similarity index 100% rename from docs/ACT_IMPLEMENTATION_SUMMARY.md rename to docs/implementation/ACT_IMPLEMENTATION_SUMMARY.md diff --git a/docs/ATOMIC_DESIGN.md b/docs/implementation/ATOMIC_DESIGN.md similarity index 100% rename from docs/ATOMIC_DESIGN.md rename to docs/implementation/ATOMIC_DESIGN.md diff --git a/docs/ATOMIC_STRUCTURE.md b/docs/implementation/ATOMIC_STRUCTURE.md similarity index 100% rename from docs/ATOMIC_STRUCTURE.md rename to docs/implementation/ATOMIC_STRUCTURE.md diff --git a/docs/BLOB_STORAGE_IMPLEMENTATION.md b/docs/implementation/BLOB_STORAGE_IMPLEMENTATION.md similarity index 100% rename from docs/BLOB_STORAGE_IMPLEMENTATION.md rename to docs/implementation/BLOB_STORAGE_IMPLEMENTATION.md diff --git a/docs/COMPONENT_MAP.md b/docs/implementation/COMPONENT_MAP.md similarity index 100% rename from docs/COMPONENT_MAP.md rename to docs/implementation/COMPONENT_MAP.md diff --git a/docs/DBAL_INTEGRATION.md b/docs/implementation/DBAL_INTEGRATION.md similarity index 100% rename from docs/DBAL_INTEGRATION.md rename to docs/implementation/DBAL_INTEGRATION.md diff --git a/docs/FOUNDATION_IMPROVEMENTS.md b/docs/implementation/FOUNDATION_IMPROVEMENTS.md similarity index 100% rename from docs/FOUNDATION_IMPROVEMENTS.md rename to docs/implementation/FOUNDATION_IMPROVEMENTS.md diff --git a/docs/MULTI_TENANT_SYSTEM.md b/docs/implementation/MULTI_TENANT_SYSTEM.md similarity index 100% rename from docs/MULTI_TENANT_SYSTEM.md rename to docs/implementation/MULTI_TENANT_SYSTEM.md diff --git a/docs/NEXTJS_MIGRATION.md b/docs/implementation/NEXTJS_MIGRATION.md similarity index 100% rename from docs/NEXTJS_MIGRATION.md rename to docs/implementation/NEXTJS_MIGRATION.md diff --git a/docs/PRISMA_IMPLEMENTATION_COMPLETE.md b/docs/implementation/PRISMA_IMPLEMENTATION_COMPLETE.md similarity index 100% rename from docs/PRISMA_IMPLEMENTATION_COMPLETE.md rename to docs/implementation/PRISMA_IMPLEMENTATION_COMPLETE.md diff --git a/docs/PRISMA_MIGRATION.md b/docs/implementation/PRISMA_MIGRATION.md similarity index 100% rename from docs/PRISMA_MIGRATION.md rename to docs/implementation/PRISMA_MIGRATION.md diff --git a/docs/PRISMA_MIGRATION_STATUS.md b/docs/implementation/PRISMA_MIGRATION_STATUS.md similarity index 100% rename from docs/PRISMA_MIGRATION_STATUS.md rename to docs/implementation/PRISMA_MIGRATION_STATUS.md diff --git a/docs/SECURE_DATABASE_LAYER.md b/docs/implementation/SECURE_DATABASE_LAYER.md similarity index 100% rename from docs/SECURE_DATABASE_LAYER.md rename to docs/implementation/SECURE_DATABASE_LAYER.md diff --git a/docs/SECURE_DB_MIGRATION_GUIDE.md b/docs/implementation/SECURE_DB_MIGRATION_GUIDE.md similarity index 100% rename from docs/SECURE_DB_MIGRATION_GUIDE.md rename to docs/implementation/SECURE_DB_MIGRATION_GUIDE.md diff --git a/docs/SECURE_DB_SUMMARY.md b/docs/implementation/SECURE_DB_SUMMARY.md similarity index 100% rename from docs/SECURE_DB_SUMMARY.md rename to docs/implementation/SECURE_DB_SUMMARY.md diff --git a/docs/TYPESCRIPT_DBAL_ENHANCEMENTS.md b/docs/implementation/TYPESCRIPT_DBAL_ENHANCEMENTS.md similarity index 100% rename from docs/TYPESCRIPT_DBAL_ENHANCEMENTS.md rename to docs/implementation/TYPESCRIPT_DBAL_ENHANCEMENTS.md diff --git a/docs/UNIT_TESTS_IMPLEMENTATION.md b/docs/implementation/UNIT_TESTS_IMPLEMENTATION.md similarity index 100% rename from docs/UNIT_TESTS_IMPLEMENTATION.md rename to docs/implementation/UNIT_TESTS_IMPLEMENTATION.md diff --git a/docs/component-atomicity-refactor.md b/docs/implementation/component-atomicity-refactor.md similarity index 100% rename from docs/component-atomicity-refactor.md rename to docs/implementation/component-atomicity-refactor.md diff --git a/docs/FILE_RELOCATION_GUIDE.md b/docs/migrations/FILE_RELOCATION_GUIDE.md similarity index 100% rename from docs/FILE_RELOCATION_GUIDE.md rename to docs/migrations/FILE_RELOCATION_GUIDE.md diff --git a/docs/MIGRATION_STATUS.md b/docs/migrations/MIGRATION_STATUS.md similarity index 100% rename from docs/MIGRATION_STATUS.md rename to docs/migrations/MIGRATION_STATUS.md diff --git a/docs/RELOCATION_SUMMARY.md b/docs/migrations/RELOCATION_SUMMARY.md similarity index 100% rename from docs/RELOCATION_SUMMARY.md rename to docs/migrations/RELOCATION_SUMMARY.md diff --git a/docs/CORS-BYPASS-EXPLANATION.md b/docs/troubleshooting/CORS-BYPASS-EXPLANATION.md similarity index 100% rename from docs/CORS-BYPASS-EXPLANATION.md rename to docs/troubleshooting/CORS-BYPASS-EXPLANATION.md diff --git a/docs/PACKAGE_TESTS.md b/docs/troubleshooting/PACKAGE_TESTS.md similarity index 100% rename from docs/PACKAGE_TESTS.md rename to docs/troubleshooting/PACKAGE_TESTS.md diff --git a/docs/PHASE5_TESTING_REPORT.md b/docs/troubleshooting/PHASE5_TESTING_REPORT.md similarity index 100% rename from docs/PHASE5_TESTING_REPORT.md rename to docs/troubleshooting/PHASE5_TESTING_REPORT.md diff --git a/docs/SCREENSHOT_ANALYZER.md b/docs/troubleshooting/SCREENSHOT_ANALYZER.md similarity index 100% rename from docs/SCREENSHOT_ANALYZER.md rename to docs/troubleshooting/SCREENSHOT_ANALYZER.md diff --git a/docs/TEST_COVERAGE_SUMMARY.md b/docs/troubleshooting/TEST_COVERAGE_SUMMARY.md similarity index 100% rename from docs/TEST_COVERAGE_SUMMARY.md rename to docs/troubleshooting/TEST_COVERAGE_SUMMARY.md diff --git a/docs/WORKFLOW_FAILURE_DIAGNOSIS.md b/docs/troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md similarity index 100% rename from docs/WORKFLOW_FAILURE_DIAGNOSIS.md rename to docs/troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md diff --git a/src/index.scss b/src/index.scss index 09b124100..1254c0828 100644 --- a/src/index.scss +++ b/src/index.scss @@ -6,5 +6,6 @@ // stylesheet if needed. The main stylesheet is loaded from main.scss // Uncomment to add page-specific styles: -// @import './styles/variables.scss'; -// @import './styles/mixins.scss'; +// @use './styles/variables.scss' as *; +// @use './styles/mixins.scss' as *; +