7781aab39f
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
485 lines
16 KiB
Plaintext
Executable File
485 lines
16 KiB
Plaintext
Executable File
RESPONSIVE BREAKPOINT SYSTEM - MIGRATION GUIDE
|
|
Date: 2024-12-18
|
|
|
|
SUMMARY
|
|
RSX now uses a custom two-tier responsive breakpoint system that replaces
|
|
Bootstrap's default breakpoints (xs/sm/md/lg/xl/xxl) with semantic device
|
|
names. This provides clearer intent (mobile vs desktop) and finer control
|
|
(phone/tablet/desktop-sm/desktop-md/desktop-lg). All existing media queries
|
|
using hardcoded pixel values or Bootstrap breakpoint variables should be
|
|
migrated to use the new SCSS mixins.
|
|
|
|
Bootstrap's default responsive utility classes (.col-md-*, .d-lg-*, etc.)
|
|
no longer work. Applications must use the new breakpoint names.
|
|
|
|
BREAKPOINT DEFINITIONS
|
|
|
|
Tier 1 - Semantic (Mobile vs Desktop):
|
|
mobile 0 - 1023px Phone + tablet combined
|
|
desktop 1024px+ All desktop sizes
|
|
|
|
Tier 2 - Granular Device Classes:
|
|
phone 0 - 799px Phones, small handhelds
|
|
tablet 800 - 1023px Tablets portrait, large phones landscape
|
|
desktop-sm 1024 - 1699px Laptops, small monitors
|
|
desktop-md 1700 - 2199px Standard monitors (1080p-1440p)
|
|
desktop-lg 2200px+ Large/ultra-wide monitors, 4K
|
|
|
|
The 1024px mobile/desktop boundary was chosen because tablets in landscape
|
|
(iPad Pro at 1366px) should receive desktop layouts.
|
|
|
|
VARIABLE CONVENTION
|
|
|
|
IMPORTANT: Only 4 breakpoint variables are defined. Each variable represents
|
|
where that breakpoint STARTS. Max values are calculated inline in mixins as
|
|
($next-breakpoint - 0.02px).
|
|
|
|
DO NOT create -min/-max suffix variables like $bp-desktop-sm-max. This is
|
|
the old convention and is incorrect.
|
|
|
|
Correct:
|
|
$bp-tablet: 800px;
|
|
$bp-desktop: 1024px;
|
|
$bp-desktop-md: 1700px;
|
|
$bp-desktop-lg: 2200px;
|
|
|
|
Wrong (old convention - do not use):
|
|
$bp-phone-max: 799px;
|
|
$bp-tablet-min: 800px;
|
|
$bp-tablet-max: 1023px;
|
|
$bp-desktop-sm-min: 1024px;
|
|
$bp-desktop-sm-max: 1699px;
|
|
... etc
|
|
|
|
AFFECTED FILES
|
|
|
|
Framework files (already updated):
|
|
rsx/theme/vendor/bootstrap5/scss/_variables.scss
|
|
rsx/theme/variables.scss
|
|
rsx/theme/responsive.scss (new file)
|
|
All bundle definition files (*_bundle.php)
|
|
|
|
Application files requiring migration:
|
|
Any *.scss file with @media queries using pixel values
|
|
Any template using Bootstrap responsive classes (.col-md-*, .d-lg-*, etc.)
|
|
|
|
CHANGES REQUIRED
|
|
|
|
1. Bootstrap Assertion Disabled
|
|
-------------------------------------------------------------------------
|
|
In rsx/theme/vendor/bootstrap5/scss/_variables.scss, the ascending
|
|
assertion for $grid-breakpoints has been commented out to allow
|
|
semantic aliases (mobile/phone share 0, desktop/desktop-sm share 1024px):
|
|
|
|
Line 494-495:
|
|
// RSX: Disabled to allow semantic breakpoint aliases
|
|
// @include _assert-ascending($grid-breakpoints, "$grid-breakpoints");
|
|
|
|
If you have a custom Bootstrap checkout, apply this change.
|
|
|
|
2. Create responsive.scss
|
|
-------------------------------------------------------------------------
|
|
Create rsx/theme/responsive.scss with mixins and utility classes.
|
|
|
|
Full file contents:
|
|
|
|
// ==========================================================================
|
|
// RSX RESPONSIVE SYSTEM
|
|
// ==========================================================================
|
|
//
|
|
// Two-tier responsive breakpoint system for consistent mobile/desktop handling.
|
|
//
|
|
// TIER 1 - Semantic (Mobile vs Desktop):
|
|
// Mobile: 0 - 1023px (phone + tablet combined)
|
|
// Desktop: 1024px+ (all desktop sizes)
|
|
//
|
|
// TIER 2 - Granular Device Classes:
|
|
// phone: 0 - 799px Phones, small handhelds
|
|
// tablet: 800 - 1023px Tablets portrait, large phones landscape
|
|
// desktop-sm: 1024 - 1699px Laptops, small monitors
|
|
// desktop-md: 1700 - 2199px Standard monitors (1080p-1440p)
|
|
// desktop-lg: 2200px+ Large/ultra-wide monitors, 4K
|
|
//
|
|
// BREAKPOINTS: 800, 1024, 1700, 2200
|
|
// No -min/-max variables; calculate max as ($next-breakpoint - 0.02px)
|
|
//
|
|
// USAGE:
|
|
// SCSS Mixins:
|
|
// @include mobile { ... } // 0 - 1023px
|
|
// @include desktop { ... } // 1024px+
|
|
// @include phone { ... } // 0 - 799px
|
|
// @include tablet { ... } // 800 - 1023px
|
|
// @include desktop-sm { ... } // 1024 - 1699px
|
|
// @include desktop-md { ... } // 1700 - 2199px
|
|
// @include desktop-lg { ... } // 2200px+
|
|
//
|
|
// Bootstrap Utility Classes (auto-generated from $grid-breakpoints):
|
|
// .col-mobile-6, .col-desktop-4, .col-tablet-12
|
|
// .d-mobile-none, .d-desktop-block, .d-phone-flex
|
|
// .p-mobile-2, .p-desktop-4, .m-tablet-3
|
|
// ... and all other Bootstrap responsive utilities
|
|
//
|
|
// Custom Utility Classes:
|
|
// .mobile-only, .desktop-only
|
|
// .phone-only, .tablet-only
|
|
// .hide-mobile, .hide-desktop, .hide-phone, .hide-tablet
|
|
//
|
|
// ==========================================================================
|
|
|
|
// ==========================================================================
|
|
// TIER 1 MIXINS: Mobile vs Desktop
|
|
// ==========================================================================
|
|
|
|
@mixin mobile {
|
|
@media (max-width: #{$bp-desktop - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop {
|
|
@media (min-width: $bp-desktop) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// TIER 2 MIXINS: Device-specific ("only" ranges)
|
|
// ==========================================================================
|
|
|
|
@mixin phone {
|
|
@media (max-width: #{$bp-tablet - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin tablet {
|
|
@media (min-width: $bp-tablet) and (max-width: #{$bp-desktop - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-sm {
|
|
@media (min-width: $bp-desktop) and (max-width: #{$bp-desktop-md - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-md {
|
|
@media (min-width: $bp-desktop-md) and (max-width: #{$bp-desktop-lg - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-lg {
|
|
@media (min-width: $bp-desktop-lg) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// TIER 2 MIXINS: "and up" ranges
|
|
// ==========================================================================
|
|
|
|
@mixin tablet-up {
|
|
@media (min-width: $bp-tablet) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin tablet-down {
|
|
@media (max-width: #{$bp-desktop - 0.02px}) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-sm-up {
|
|
@media (min-width: $bp-desktop) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-md-up {
|
|
@media (min-width: $bp-desktop-md) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-lg-up {
|
|
@media (min-width: $bp-desktop-lg) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// UTILITY CLASSES
|
|
// ==========================================================================
|
|
|
|
// Tier 1: Mobile/Desktop visibility
|
|
.mobile-only {
|
|
@include desktop {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.desktop-only {
|
|
@include mobile {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.hide-mobile {
|
|
@include mobile {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.hide-desktop {
|
|
@include desktop {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
// Tier 2: Device-specific visibility
|
|
.phone-only {
|
|
@include tablet-up {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.tablet-only {
|
|
@include phone {
|
|
display: none !important;
|
|
}
|
|
@include desktop {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.hide-phone {
|
|
@include phone {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
.hide-tablet {
|
|
@include tablet {
|
|
display: none !important;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// CSS CUSTOM PROPERTIES (for JavaScript access)
|
|
// ==========================================================================
|
|
// Usage:
|
|
// const bp = parseInt(getComputedStyle(document.documentElement).getPropertyValue('--bp-desktop'));
|
|
// const isDesktop = window.innerWidth >= bp;
|
|
|
|
:root {
|
|
--bp-tablet: #{$bp-tablet}; // 800px
|
|
--bp-desktop: #{$bp-desktop}; // 1024px
|
|
--bp-desktop-md: #{$bp-desktop-md}; // 1700px
|
|
--bp-desktop-lg: #{$bp-desktop-lg}; // 2200px
|
|
}
|
|
|
|
3. Update variables.scss
|
|
-------------------------------------------------------------------------
|
|
Add breakpoint variables and Bootstrap $grid-breakpoints override.
|
|
|
|
Add to rsx/theme/variables.scss (replace any existing breakpoint vars):
|
|
|
|
// ==========================================================================
|
|
// RESPONSIVE BREAKPOINTS
|
|
// ==========================================================================
|
|
// Two-tier system: Tier 1 (Mobile vs Desktop) and Tier 2 (Granular devices)
|
|
// See rsx/theme/responsive.scss for mixins and utilities
|
|
|
|
// Breakpoints define where each tier STARTS
|
|
// No -min/-max suffixes; calculate max inline as ($next-breakpoint - 0.02px)
|
|
//
|
|
// phone: 0px (implicit, viewport < $bp-tablet)
|
|
// tablet: 800px (viewport >= 800 and < $bp-desktop)
|
|
// desktop-sm: 1024px (viewport >= 1024 and < $bp-desktop-md)
|
|
// desktop-md: 1700px (viewport >= 1700 and < $bp-desktop-lg)
|
|
// desktop-lg: 2200px (viewport >= 2200)
|
|
|
|
$bp-tablet: 800px;
|
|
$bp-desktop: 1024px;
|
|
$bp-desktop-md: 1700px;
|
|
$bp-desktop-lg: 2200px;
|
|
|
|
// Bootstrap grid breakpoints override
|
|
// Allows: .col-mobile-6, .col-phone-12, .col-tablet-8, .col-desktop-4, etc.
|
|
// Note: mobile/phone share 0, desktop/desktop-sm share 1024px (assertion disabled)
|
|
$grid-breakpoints: (
|
|
xs: 0,
|
|
mobile: 0,
|
|
phone: 0,
|
|
tablet: 800px,
|
|
desktop: 1024px,
|
|
desktop-sm: 1024px,
|
|
desktop-md: 1700px,
|
|
desktop-lg: 2200px
|
|
);
|
|
|
|
Remove any old breakpoint variables like:
|
|
$breakpoint-sm, $breakpoint-md, $breakpoint-lg, $breakpoint-xl, $breakpoint-2xl
|
|
$bp-phone-max, $bp-tablet-min, $bp-tablet-max, $bp-desktop-sm-min, etc.
|
|
|
|
4. Update Bundle Definitions
|
|
-------------------------------------------------------------------------
|
|
Add responsive.scss to every bundle after variables.scss but before Bootstrap.
|
|
|
|
Before:
|
|
'include' => [
|
|
'rsx/theme/variables.scss',
|
|
'Bootstrap5_Src_Bundle',
|
|
...
|
|
]
|
|
|
|
After:
|
|
'include' => [
|
|
'rsx/theme/variables.scss',
|
|
'rsx/theme/responsive.scss', // ADD THIS LINE
|
|
'Bootstrap5_Src_Bundle',
|
|
...
|
|
]
|
|
|
|
Apply to all bundle files:
|
|
- rsx/app/frontend/frontend_bundle.php
|
|
- rsx/app/login/login_bundle.php
|
|
- rsx/app/root/root_bundle.php
|
|
- rsx/app/dev/dev_bundle.php
|
|
- rsx/app/backend/backend_bundle.php
|
|
- Any other *_bundle.php files
|
|
|
|
5. Migrate SCSS Media Queries
|
|
-------------------------------------------------------------------------
|
|
Replace hardcoded media queries with mixins.
|
|
|
|
Common patterns:
|
|
|
|
Before: @media (max-width: 767px) { ... }
|
|
After: @include phone { ... }
|
|
|
|
Before: @media (max-width: 768px) { ... }
|
|
After: @include mobile { ... }
|
|
|
|
Before: @media (max-width: 991.98px) { ... }
|
|
After: @include mobile { ... }
|
|
|
|
Before: @media (max-width: 1199px) { ... }
|
|
After: @include mobile { ... }
|
|
|
|
Before: @media (min-width: 768px) { ... }
|
|
After: @include tablet-up { ... }
|
|
|
|
Before: @media (min-width: 992px) { ... }
|
|
After: @include desktop { ... }
|
|
|
|
Before: @media (min-width: 1200px) { ... }
|
|
After: @include desktop { ... }
|
|
|
|
Example file migration:
|
|
|
|
Before:
|
|
.My_Component {
|
|
padding: 1rem;
|
|
|
|
@media (max-width: 991.98px) {
|
|
padding: 0.5rem;
|
|
}
|
|
}
|
|
|
|
After:
|
|
.My_Component {
|
|
padding: 1rem;
|
|
|
|
@include mobile {
|
|
padding: 0.5rem;
|
|
}
|
|
}
|
|
|
|
Remove any local breakpoint variables like:
|
|
$mobile-breakpoint: 991.98px;
|
|
|
|
6. Migrate Bootstrap Utility Classes in Templates
|
|
-------------------------------------------------------------------------
|
|
Replace Bootstrap's default breakpoint names with RSX names.
|
|
|
|
Grid columns:
|
|
Before: class="col-12 col-md-6 col-lg-4"
|
|
After: class="col-mobile-12 col-tablet-6 col-desktop-4"
|
|
|
|
Before: class="col-sm-6 col-xl-3"
|
|
After: class="col-phone-6 col-desktop-md-3"
|
|
|
|
Display utilities:
|
|
Before: class="d-none d-md-block"
|
|
After: class="d-none d-tablet-block" or class="d-mobile-none d-tablet-block"
|
|
|
|
Before: class="d-lg-none"
|
|
After: class="d-desktop-none"
|
|
|
|
Spacing:
|
|
Before: class="p-2 p-md-4"
|
|
After: class="p-2 p-tablet-4" or class="p-mobile-2 p-desktop-4"
|
|
|
|
Common mappings:
|
|
Bootstrap RSX equivalent
|
|
--------- --------------
|
|
xs (use base class, no suffix)
|
|
sm phone or mobile
|
|
md tablet or mobile
|
|
lg desktop
|
|
xl desktop or desktop-md
|
|
xxl desktop-lg
|
|
|
|
CONFIGURATION
|
|
|
|
No additional configuration required beyond the file changes above.
|
|
|
|
Optional: If you need JavaScript access to breakpoints:
|
|
|
|
const styles = getComputedStyle(document.documentElement);
|
|
const desktopMin = parseInt(styles.getPropertyValue('--bp-desktop'));
|
|
const isMobile = window.innerWidth < desktopMin;
|
|
|
|
VERIFICATION
|
|
|
|
1. Compile bundles and verify no SCSS errors:
|
|
php artisan rsx:bundle:compile Frontend_Bundle
|
|
|
|
2. Check that responsive utility classes work:
|
|
- Add class="mobile-only" to an element, verify hidden on desktop
|
|
- Add class="col-mobile-12 col-desktop-6" to a div, verify layout changes
|
|
|
|
3. Search for orphaned Bootstrap classes:
|
|
grep -r "col-sm-\|col-md-\|col-lg-\|col-xl-\|d-sm-\|d-md-\|d-lg-\|d-xl-" rsx/
|
|
|
|
4. Search for hardcoded media queries that should be migrated:
|
|
grep -r "@media.*max-width.*px\|@media.*min-width.*px" rsx/app rsx/theme/components
|
|
|
|
DOCUMENTATION
|
|
|
|
Man page created: rsx/resource/man/responsive.txt
|
|
View with: php artisan rsx:man responsive
|
|
|
|
CLAUDE.md and docs.dist/CLAUDE.dist.md updated with:
|
|
- Responsive Breakpoints section under SCSS Component-First Architecture
|
|
- Tier 1 and Tier 2 definitions
|
|
- Mixin and class name reference
|
|
- Warning about Bootstrap default classes not working
|
|
|
|
PROJECT MAN PAGES
|
|
|
|
The rsx:man command now also searches rsx/resource/man/ for project-specific
|
|
documentation. Project man pages override framework man pages of the same name.
|
|
|
|
Created: rsx/resource/man/CLAUDE.md (guidelines for project man pages)
|
|
|
|
REFERENCE
|
|
|
|
php artisan rsx:man responsive - Full responsive system documentation
|
|
php artisan rsx:man scss - SCSS organization conventions
|
|
php artisan rsx:man man - Man page system documentation
|