1a5d93140c
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
428 lines
14 KiB
Plaintext
Executable File
428 lines
14 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.
|
|
|
|
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
|
|
// tablet: 800 - 1023px
|
|
// desktop-sm: 1024 - 1699px
|
|
// desktop-md: 1700 - 2199px
|
|
// desktop-lg: 2200px+
|
|
|
|
// ==========================================================================
|
|
// TIER 1 MIXINS: Mobile vs Desktop
|
|
// ==========================================================================
|
|
|
|
@mixin mobile {
|
|
@media (max-width: $bp-mobile-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop {
|
|
@media (min-width: $bp-desktop-min) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// TIER 2 MIXINS: Device-specific
|
|
// ==========================================================================
|
|
|
|
@mixin phone {
|
|
@media (max-width: $bp-phone-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin tablet {
|
|
@media (min-width: $bp-tablet-min) and (max-width: $bp-tablet-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin tablet-up {
|
|
@media (min-width: $bp-tablet-min) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin tablet-down {
|
|
@media (max-width: $bp-tablet-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-sm {
|
|
@media (min-width: $bp-desktop-sm-min) and (max-width: $bp-desktop-sm-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-sm-up {
|
|
@media (min-width: $bp-desktop-sm-min) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-md {
|
|
@media (min-width: $bp-desktop-md-min) and (max-width: $bp-desktop-md-max) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-md-up {
|
|
@media (min-width: $bp-desktop-md-min) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
@mixin desktop-lg {
|
|
@media (min-width: $bp-desktop-lg-min) {
|
|
@content;
|
|
}
|
|
}
|
|
|
|
// ==========================================================================
|
|
// UTILITY CLASSES
|
|
// ==========================================================================
|
|
|
|
.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;
|
|
}
|
|
}
|
|
|
|
.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)
|
|
// ==========================================================================
|
|
|
|
:root {
|
|
--bp-mobile-max: #{$bp-mobile-max};
|
|
--bp-desktop-min: #{$bp-desktop-min};
|
|
--bp-phone-max: #{$bp-phone-max};
|
|
--bp-tablet-min: #{$bp-tablet-min};
|
|
--bp-tablet-max: #{$bp-tablet-max};
|
|
--bp-desktop-sm-min: #{$bp-desktop-sm-min};
|
|
--bp-desktop-sm-max: #{$bp-desktop-sm-max};
|
|
--bp-desktop-md-min: #{$bp-desktop-md-min};
|
|
--bp-desktop-md-max: #{$bp-desktop-md-max};
|
|
--bp-desktop-lg-min: #{$bp-desktop-lg-min};
|
|
}
|
|
|
|
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
|
|
|
|
// Tier 2: Granular device breakpoints
|
|
$bp-phone-max: 799px;
|
|
$bp-tablet-min: 800px;
|
|
$bp-tablet-max: 1023px;
|
|
$bp-desktop-sm-min: 1024px;
|
|
$bp-desktop-sm-max: 1699px;
|
|
$bp-desktop-md-min: 1700px;
|
|
$bp-desktop-md-max: 2199px;
|
|
$bp-desktop-lg-min: 2200px;
|
|
|
|
// Tier 1: Semantic breakpoints (mobile = phone + tablet)
|
|
$bp-mobile-max: 1023px;
|
|
$bp-desktop-min: 1024px;
|
|
|
|
// 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
|
|
|
|
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 = styles.getPropertyValue('--bp-desktop-min');
|
|
const isMobile = window.innerWidth <= parseInt(
|
|
styles.getPropertyValue('--bp-mobile-max')
|
|
);
|
|
|
|
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
|