@fishawack/lab-env 4.45.0-beta.1 → 4.45.0-beta.3

package/_Ai/sass-@.md

@@ -0,0 +1,350 @@
+---
+applyTo: "**/*.scss"
+---
+
+# SCSS/SASS Development Instructions for GitHub Copilot
+
+## Project Overview
+
+This project follows a structured SCSS/SASS architecture built on top of `@fishawack/lab-ui`, a proprietary utility-first CSS framework similar to Tailwind CSS. The architecture enforces separation of concerns where styles are kept entirely outside of component files (Vue, React, etc.). All styling is managed through a structured SASS directory system that promotes reusability, maintainability, and fast compilation times.
+
+The build system uses Dart SASS with custom bundling that automatically combines files and implements PurgeCSS for production optimization. The architecture prioritizes component-based styling with a clear separation between vendor libraries, project-specific components, and variable overrides.
+
+## Folder Structure
+
+```
+resources/sass/
+├── _variables.scss          # Project-specific variable overrides
+├── _defaults.scss           # Lab-UI component setting overrides
+├── general.scss             # Project component imports (fast-reloading)
+├── vendor.scss              # Third-party library imports (cached)
+└── components/              # Project-specific component styles
+    ├── _component-name.scss # Individual component files
+    ├── _utilities.scss      # Project-specific utility extensions
+    └── ...                  # Additional components as needed
+```
+
+> resources/sass is specific to laravel projects, in wordpress, static sites and other frameworks the sass folder is usually in \_Build/sass but it may vary
+
+### File Organization Rules
+
+- **`_variables.scss`**: Hard-coded project variables that override lab-ui defaults
+- **`_defaults.scss`**: Component-specific setting overrides for lab-ui components
+- **`general.scss`**: Imports all project-defined components (recompiles frequently)
+- **`vendor.scss`**: Imports external libraries and lab-ui base (cached for performance)
+- **`components/`**: Individual component files using underscore prefix naming convention
+
+## Libraries and Frameworks
+
+### Primary Framework: @fishawack/lab-ui
+
+- **Version**: Latest
+- **Documentation**: https://lab-ui.fishawack.solutions/
+- **Purpose**: Provides grid system, utility classes, and base components
+- **Import Pattern**: `@import "@fishawack/lab-ui/_[component].scss";`
+
+### Key Lab-UI Components Available:
+
+- `_variables.scss` - Base color palette and spacing variables
+- `_defaults.scss` - Component default settings
+- `_typography.scss` - Text styling and font configuration
+- `_grid.scss` - Flexbox-based 12-column grid system
+- `_button.scss` - Button component base
+- `_form.scss` - Form component base
+- `_utilities.scss` - Utility classes (Tailwind-like system)
+- `_flex.scss` - Flexbox utilities
+- `_card.scss` - Card layout component
+- `_icon.scss` - Icon sizing and styling
+- `_modal.scss` - Modal dialog component
+- `_alert.scss` - Alert/notification component
+- Additional components available as needed (breadcrumb, pagination, progress, etc.)
+
+### Utility System
+
+Lab-UI provides a comprehensive utility class system similar to Tailwind CSS with some differences:
+
+#### Responsive Breakpoints:
+
+- `mobile:` - 767px and below
+- `tablet:` - 1023px and below
+- `desktop:` - 1299px and below
+
+#### Spacing Scale:
+
+- `-0`: 0
+- `-0.5`: $spacing \* 0.5 (8px)
+- ``: $spacing (16px)
+- `-1.5`: $spacing \* 1.5 (24px)
+- `-2`: $spacing \* 2 (32px)
+- `-3`: $spacing \* 3 (48px)
+- `-4`: $spacing \* 4 (64px)
+
+#### Color Classes:
+
+- Background: `bg-0` through `bg-6` (uses $color0-$color6)
+- Text: `color-1` through `color-6` (uses $color1-$color6)
+- Border: `border-color-1` through `border-color-6`
+
+#### Grid System:
+
+- Default max-width: 1400px
+- 12-column factor system
+- Classes: `grid__1/12` through `grid__12/12`
+- Responsive: `mobile:grid__12/12`, `tablet:grid__6/12`
+- Gutters: `grid--gutters`, `grid--gutters-x`, `grid--gutters-y`
+- Gutter sizes: `-0`, `-0.5`, ``, `-1.5`, `-2`, `-3`, `-4`
+
+#### Flexbox Utilities:
+
+- `flex`, `inline-flex`
+- `justify-start`, `justify-center`, `justify-between`, `justify-around`, `justify-evenly`
+- `items-start`, `items-center`, `items-end`, `items-baseline`, `items-stretch`
+- `flex-row`, `flex-column`, `flex-wrap`, `flex-no-wrap`
+- `flex-grow-1` through `flex-grow-12`
+- `order-1` through `order-12`
+
+#### Display & Visibility:
+
+- `block`, `inline-block`, `inline`, `hidden`
+- `visible`, `invisible`
+- Responsive: `mobile:hidden`, `tablet:block`
+
+#### Typography:
+
+- `text-left`, `text-center`, `text-right`
+- `font-100` through `font-900`
+- `italic`, `not-italic`
+- `uppercase`, `lowercase`, `capitalize`, `normal-case`
+- `underline`, `line-through`, `no-underline`
+
+Full documentation: https://lab-ui.fishawack.solutions/#Utilities
+
+### Build System
+
+- **Compiler**: Dart SASS
+- **PurgeCSS**: Enabled for production builds only
+- **File Watching**: `general.scss` recompiles faster than `vendor.scss`
+- **Output**: Combined CSS file with automatic optimization
+
+## Coding Standards
+
+### File Naming Conventions
+
+- Component files: `_component-name.scss` (underscore prefix, kebab-case)
+- Partials: Always use underscore prefix for imported files
+- Main files: `general.scss`, `vendor.scss` (no underscore, not imported elsewhere)
+
+### Import Structure
+
+```scss
+// 1. Always import variables first
+@import "_variables.scss";
+
+// 2. Import defaults second (for lab-ui overrides)
+@import "_defaults.scss";
+
+// 3. Import specific lab-ui components in vendor.scss
+@import "@fishawack/lab-ui/_typography.scss";
+@import "@fishawack/lab-ui/_grid.scss";
+@import "@fishawack/lab-ui/_button.scss";
+
+// 4. Import project components in general.scss
+@import "./components/_utilities.scss";
+@import "./components/_button.scss";
+```
+
+### Variable System
+
+#### Lab-UI Default Colors (Base Framework):
+
+```scss
+$color0: white; // White
+$color1: #22f0cc; // Light Blue
+$color2: #19b398; // Darker Light Blue
+$color3: #ff9d2e; // Orange
+$color4: #333333; // Dark Gray
+$color5: #f2f2f2; // Light Gray
+$color6: #e6e6e6; // Medium Gray
+
+$colorGood: #dff0d8; // Green
+$colorInfo: #d9edf7; // Blue
+$colorWarn: #fcf8e3; // Yellow
+$colorBad: #f2dede; // Red
+```
+
+#### Project Color Override Pattern:
+
+```scss
+// Override lab-ui defaults in _variables.scss
+$color1: #your-primary; // Primary brand color
+$color2: #your-secondary; // Secondary brand color
+$color3: #your-accent; // Accent color
+// ... continue as needed
+
+// Define additional project colors beyond lab-ui defaults
+$color7: #custom-color;
+$color8: #another-color;
+// ... as many as needed
+
+// Create semantic aliases for better readability
+$colorPrimary: $color1;
+$colorSuccess: $color9; // If using additional colors
+$colorWarning: $color10;
+$colorError: $color11;
+
+// Component-specific overrides in _defaults.scss
+$fontColor: $color4;
+$fontFamily: "Your-Font-Family";
+$formBorder: $color6;
+$formBorder--active: $color1;
+```
+
+### Component Architecture
+
+- Use BEM methodology: `.component__element--modifier`
+- Keep components small and focused on single responsibility
+- Leverage lab-ui utilities instead of custom CSS when possible
+- Override lab-ui components through variable redefinition, not direct CSS
+
+### PurgeCSS Considerations
+
+```scss
+/* purgecss start ignore */
+// Styles that are added via JavaScript
+.dynamic-class {
+    // This will be preserved in production
+}
+/* purgecss end ignore */
+```
+
+**Important**: PurgeCSS only runs on production builds, not development. Always test production builds when using JavaScript-generated classes.
+
+## UI Guidelines
+
+### Design System Integration
+
+- **Primary Colors**: Use the defined `$color1-$color6` variables consistently
+- **Typography**: Rely on lab-ui typography classes and custom font family
+- **Spacing**: Use lab-ui spacing scale (`$spacing` based increments)
+- **Grid System**: Utilize lab-ui's flexbox grid for layouts
+- **Responsive Design**: Mobile-first approach with lab-ui breakpoints
+
+### Component Development Patterns
+
+#### Custom Button Extensions (Example):
+
+```scss
+.button {
+    // Extend lab-ui button component
+    color: $fontColor;
+    border: 2px solid $color1;
+
+    &:hover,
+    &:focus,
+    &:active {
+        background-color: $color1;
+        color: $color0;
+    }
+
+    // Custom button variants
+    &--secondary {
+        border-color: $color2;
+        color: $color2;
+
+        &:hover {
+            background-color: $color2;
+        }
+    }
+}
+```
+
+#### Form Component Extensions (Example):
+
+```scss
+.form__group {
+    // Extend lab-ui form patterns
+
+    &--active input {
+        box-shadow: inset 0 0 0px 2px $formBorder--active;
+    }
+
+    &--error {
+        color: $colorBad;
+
+        input {
+            box-shadow: inset 0 0 0px 2px $colorBad;
+            color: $colorBad;
+        }
+    }
+
+    &--disabled input {
+        opacity: 0.5;
+        pointer-events: none;
+    }
+}
+```
+
+#### Custom Utility Extensions (Example):
+
+```scss
+// Background pattern utilities
+.bg-pattern-1 {
+    background-image: url("path/to/pattern.svg");
+    background-position: center;
+    background-repeat: no-repeat;
+    background-size: cover;
+}
+
+// Gradient utilities
+.bg-gradient-primary {
+    background: linear-gradient(135deg, $color1 0%, $color2 100%);
+}
+
+// Custom spacing utilities beyond lab-ui defaults
+.spacing-custom {
+    margin: $spacing * 2.5; // Custom spacing multiplier
+}
+```
+
+### Performance Optimization
+
+- **File Separation**: Keep project styles in `general.scss` for fast recompilation
+- **Vendor Caching**: Import stable external libraries in `vendor.scss`
+- **Utility-First**: Prefer lab-ui utilities over custom CSS when possible
+- **Component Scope**: Keep component files focused and lightweight
+
+### Component Framework Integration
+
+- **No Scoped Styles**: Never use `<style scoped>` in component files
+- **No Inline Styles**: Avoid `<style>` blocks in component files entirely
+- **Class-Based**: Use CSS classes exclusively for styling
+- **Global Scope**: All styles are global and managed through the SASS architecture
+- **Component Naming**: Use BEM methodology for component-specific styles that extend beyond utility classes
+
+### Browser Support & Fallbacks
+
+- Lab-ui includes legacy fallbacks for older browsers
+- **Grid fallback**: Uses inline-block as fallback (requires no whitespace between grid containers)
+- **Flexbox**: Progressive enhancement with fallbacks
+- **CSS Calc**: Enhanced where supported with fallbacks
+- **Modernizr integration**: Feature detection for `flexbox`, `csscalc`, `cssanimations`
+- Grid containers must have no whitespace between them for inline-block fallback to work properly
+
+### Development Workflow
+
+1. **Define Brand Variables**: Set project colors and overrides in `_variables.scss` first
+2. **Configure Component Defaults**: Override lab-ui component settings in `_defaults.scss` if needed
+3. **Create Component Styles**: Build component-specific styles in `components/` directory
+4. **Import in General**: Add new components to `general.scss` for fast recompilation
+5. **Test Development Build**: Verify styles work correctly (PurgeCSS disabled)
+6. **Validate Production Build**: Test with production build (PurgeCSS enabled)
+7. **Check for Purged Classes**: Ensure JavaScript-generated classes haven't been removed
+
+### Project Customization Guidelines
+
+- Always start with lab-ui utilities before creating custom CSS
+- Override lab-ui variables rather than writing new component CSS when possible
+- Create semantic color aliases for better maintainability
+- Use BEM methodology for project-specific components
+- Keep component files focused and lightweight
+- Leverage the vendor/general split for optimal build performance