SCSS VARIABLES & UNITS - MIGRATION GUIDE
Date: 2024-12-18

SUMMARY
    RSX theme SCSS has been standardized to use centralized variables from
    variables.scss and px units exclusively (never rem). This ensures consistent
    styling across all components and makes the codebase self-documenting.

    All hardcoded "magic numbers" (colors, spacing, font sizes, etc.) have been
    refactored to use named variables. The rem unit has been completely removed
    from application SCSS in favor of px for predictable, consistent sizing.

    A new rsx/theme/CLAUDE.md file documents these requirements for AI agents
    and developers writing new SCSS.

DESIGN PRINCIPLES

    1. Variables First
       Every value that appears more than once, or represents a design decision,
       should be a named variable. Reading SCSS should reveal intent through
       variable names like $spacing-lg, $text-muted, $border-radius-md.

    2. px Only, Never rem
       All measurements use px units. This provides:
       - Predictable sizing (no font-size inheritance issues)
       - Easier debugging (values match computed styles exactly)
       - Consistent component sizing regardless of context

    3. Self-Documenting Code
       Variable names should immediately convey meaning without comments.
       $spacing-lg is clearly larger than $spacing-sm. $text-muted is
       clearly de-emphasized text.

AFFECTED FILES

    Framework files (already updated):
        rsx/theme/variables.scss (expanded with new variables and mixins)
        rsx/theme/CLAUDE.md (new file - coding guidelines)
        rsx/theme/layout.scss
        rsx/theme/components/navigation/sidebar/sidebar_nav.scss
        rsx/lib/modal/rsx_modal.scss
        rsx/theme/components/datagrid/datagrid_abstract.scss
        rsx/theme/components/forms/pin_verification_form.scss
        rsx/theme/components/feedback/errors/generic_error_page_component.scss
        rsx/theme/components/feedback/errors/php_exception_error_page_component.scss
        rsx/theme/components/business/textbox_click_to_copy/textbox_click_to_copy.scss
        rsx/theme/components/inputs/select/select_input.scss
        rsx/theme/components/page/breadcrumb_nav.scss
        rsx/app/frontend/frontend_spa_layout.scss
        rsx/app/frontend/settings/settings_layout.scss
        rsx/app/login/login_layout.scss
        rsx/app/dev/dev_layout.scss
        rsx/app/root/root_layout.scss
        rsx/app/backend/backend_index.scss

    Application files requiring migration:
        Any *.scss file using rem units
        Any *.scss file with hardcoded colors, spacing, or font sizes

CHANGES REQUIRED

    1. Review and Adopt variables.scss
       -------------------------------------------------------------------------
       The following variable categories are now defined. Use these instead of
       hardcoded values:

       SPACING (px only):
           $spacing-xs: 4px;
           $spacing-sm: 8px;
           $spacing-md: 16px;
           $spacing-lg: 24px;
           $spacing-xl: 32px;
           $spacing-2xl: 48px;
           $spacing-3xl: 64px;

           Fine-grained spacing:
           $spacing-1: 4px;
           $spacing-2: 8px;
           $spacing-3: 12px;
           $spacing-4: 16px;
           $spacing-5: 20px;
           $spacing-6: 24px;

       FONT SIZES (px only):
           $font-size-xs: 12px;
           $font-size-sm: 14px;
           $font-size-base: 16px;
           $font-size-lg: 18px;
           $font-size-xl: 20px;
           $font-size-2xl: 24px;
           $font-size-3xl: 30px;

       FONT WEIGHTS:
           $font-weight-light: 300;
           $font-weight-normal: 400;
           $font-weight-medium: 500;
           $font-weight-semibold: 600;
           $font-weight-bold: 700;

       COLORS - Bootstrap-aligned grays:
           $gray-100: #f8f9fa;
           $gray-200: #e9ecef;
           $gray-300: #dee2e6;
           $gray-400: #ced4da;
           $gray-500: #adb5bd;
           $gray-600: #6c757d;
           $gray-700: #495057;
           $gray-800: #343a40;
           $gray-900: #212529;

       SEMANTIC COLORS:
           $text-color: $gray-700;
           $text-muted: $gray-600;
           $border-color: $gray-300;
           $background-light: $gray-100;

       THEME COLORS:
           $primary-color: #0d6efd;
           $secondary-color: #6c757d;
           $success-color: #198754;
           $info-color: #0dcaf0;
           $warning-color: #ffc107;
           $danger-color: #dc3545;

       ERROR/ALERT COLORS:
           $error-bg: #fff3f3;
           $error-border: #f5c6cb;
           $error-text: #721c24;
           $warning-text: #856404;

       BORDER RADIUS:
           $border-radius-sm: 4px;
           $border-radius-md: 6px;
           $border-radius-lg: 8px;
           $border-radius-xl: 12px;
           $border-radius-2xl: 16px;
           $border-radius-pill: 9999px;

       Z-INDEX:
           $z-index-dropdown: 1000;
           $z-index-sticky: 1020;
           $z-index-fixed: 1030;
           $z-index-modal-backdrop: 1040;
           $z-index-modal: 1050;
           $z-index-modal-content: 1100;
           $z-index-flash: 1200;
           $z-index-system: 9000;

       TRANSITIONS:
           $transition-duration-fast: 0.15s;
           $transition-duration-base: 0.2s;
           $transition-duration-slow: 0.3s;
           $transition-fast: all $transition-duration-fast ease;
           $transition-base: all $transition-duration-base ease;

       NAVIGATION:
           $nav-link-padding: 12px 16px;
           $nav-link-border-radius: $border-radius-md;
           $nav-icon-size: 18px;
           $nav-icon-width: $spacing-lg;

       ICONS:
           $icon-size-xs: 12px;
           $icon-size-sm: 16px;
           $icon-size-md: 20px;
           $icon-size-lg: 24px;
           $icon-size-xl: 32px;

       CONTENT WIDTHS:
           $content-max-width: 1600px;
           $content-max-width-wide: 1800px;

       MODAL:
           $modal-min-width: 400px;
           $modal-min-width-mobile: 280px;
           $modal-min-height: 260px;

       DATAGRID:
           $datagrid-cell-padding-y: 12px;
           $datagrid-cell-padding-x: 12px;
           $datagrid-header-bg: $gray-100;

    2. Use the primary-hover-bg Mixin
       -------------------------------------------------------------------------
       A mixin is provided for consistent primary color hover backgrounds:

       @mixin primary-hover-bg($alpha: 0.1) {
           background: rgba($primary-color, $alpha);
       }

       Usage:
           &:hover {
               @include primary-hover-bg(0.1);
               color: $primary-color;
           }

    3. Convert rem to px
       -------------------------------------------------------------------------
       Replace all rem values with px equivalents:

           0.25rem  →  4px   (use $spacing-xs or $spacing-1)
           0.375rem →  6px   (use $border-radius-md)
           0.5rem   →  8px   (use $spacing-sm or $spacing-2)
           0.75rem  →  12px  (use $spacing-3 or $font-size-xs)
           0.875rem →  14px  (use $font-size-sm)
           1rem     →  16px  (use $spacing-md or $font-size-base)
           1.25rem  →  20px  (use $font-size-xl or $spacing-5)
           1.5rem   →  24px  (use $spacing-lg or $font-size-2xl)
           2rem     →  32px  (use $spacing-xl)
           2.5rem   →  40px
           3rem     →  48px  (use $spacing-2xl)

       Example migration:

       Before:
           .My_Component {
               padding: 1rem 1.5rem;
               font-size: 0.875rem;
               margin-bottom: 0.5rem;
               border-radius: 0.375rem;
           }

       After:
           .My_Component {
               padding: $spacing-md $spacing-lg;
               font-size: $font-size-sm;
               margin-bottom: $spacing-sm;
               border-radius: $border-radius-md;
           }

    4. Replace Hardcoded Colors
       -------------------------------------------------------------------------
       Replace hex colors with variables:

       Before:
           color: #495057;
           background: #f8f9fa;
           border-color: #dee2e6;

       After:
           color: $text-color;        // or $gray-700
           background: $background-light;  // or $gray-100
           border-color: $border-color;    // or $gray-300

       For primary/theme colors:
           #0d6efd  →  $primary-color
           #6c757d  →  $secondary-color or $text-muted
           #198754  →  $success-color
           #dc3545  →  $danger-color
           #ffc107  →  $warning-color
           #0dcaf0  →  $info-color

    5. Replace Hardcoded Font Weights
       -------------------------------------------------------------------------
       Before:
           font-weight: 400;
           font-weight: 500;
           font-weight: 600;
           font-weight: bold;

       After:
           font-weight: $font-weight-normal;
           font-weight: $font-weight-medium;
           font-weight: $font-weight-semibold;
           font-weight: $font-weight-bold;

    6. Add New Variables When Needed
       -------------------------------------------------------------------------
       If no existing variable fits your use case, add a new one to variables.scss
       with a descriptive name following the established patterns.

       Good variable names:
           $sidebar-width: 250px;
           $header-height: 57px;
           $card-padding: $spacing-lg;
           $button-min-width: 120px;

       Bad variable names:
           $size1: 250px;      // Meaningless
           $big-padding: 24px; // Vague
           $x: 57px;           // Cryptic

CONFIGURATION

    No additional configuration required.

    The rsx/theme/CLAUDE.md file documents these guidelines for AI agents and
    serves as a quick reference for developers.

VERIFICATION

    1. Search for remaining rem values:
       grep -r "rem" rsx/app rsx/theme/components rsx/lib --include="*.scss" | grep -v vendor | grep -v archive | grep -v research

    2. Search for hardcoded colors that should be variables:
       grep -rE "#[0-9a-fA-F]{3,6}" rsx/app rsx/theme/components --include="*.scss" | grep -v vendor

    3. Compile bundles and verify no SCSS errors:
       php artisan rsx:bundle:compile Frontend_Bundle

    4. Visually inspect key pages to ensure styling is unchanged:
       - Login page
       - Dashboard
       - Settings page
       - Any page with modals or datagrids

DOCUMENTATION

    Created: rsx/theme/CLAUDE.md
    Guidelines for AI agents and developers:
    - Always check variables.scss before writing new rules
    - Use existing variables for spacing, colors, typography
    - Add new variables when needed with descriptive names
    - Never use rem, always use px
    - Theme SCSS should be self-documenting through variable names

REFERENCE

    rsx/theme/variables.scss   - All variable definitions
    rsx/theme/CLAUDE.md        - SCSS coding guidelines
    php artisan rsx:man scss   - SCSS organization conventions