@modyo/mcp 0.1.0

package/docs/widgets/platform/development.md

@@ -0,0 +1,744 @@
+# Widget Development Best Practices for Modyo
+
+## Overview
+
+This guide provides best practices for developing widgets in Modyo, specifically for sites that include Bootstrap 5 by default.
+
+## Bootstrap 5 Integration
+
+### Why Use Bootstrap 5
+
+All Modyo sites created from scratch include Bootstrap 5 by default. This means:
+- ✅ **No need to import Bootstrap** - It's already available
+- ✅ **Consistent grid system** - Use Bootstrap's responsive grid
+- ✅ **Built-in utilities** - Spacing, colors, typography already styled
+- ✅ **Smaller CSS** - Leverage existing styles instead of duplicating
+- ✅ **Faster development** - Pre-built components and utilities
+
+### Custom Theme Configuration
+
+**Important**: This site uses a **customized Bootstrap 5 theme** with extended design tokens:
+
+**Enhanced Color Palette**:
+- **Primary**: Pink/Magenta (`--bs-primary` = `rgb(216, 27, 96)`) - Maps to `--bs-pink-rgb`
+- **Secondary**: Purple (`--bs-secondary` = `rgb(72, 72, 183)`) - Maps to `--bs-purple-rgb`
+- **Extended shades**: Each color has 25-900 variants (e.g., `--bs-primary-100`, `--bs-primary-600`, etc.)
+- **Surface colors**: `--bs-surface-primary`, `--bs-surface-gray`, etc.
+- **Soft backgrounds**: `--bs-primary-soft`, `--bs-secondary-soft`, etc.
+
+**Design Tokens**:
+- **Extended spacing**: `--bs-ref-spacer-0` through `--bs-ref-spacer-30` (0 to 7.5rem)
+- **Rounded borders**: Default `border-radius: 1rem` (pill-shaped buttons)
+- **Custom shadows**: Enhanced shadow system for depth
+- **Typography**: Source Sans 3 font family with responsive font sizing
+
+### Core Principles
+
+1. **Always use Bootstrap utilities first**
+2. **Leverage custom CSS variables** - Use `var(--bs-primary-600)` instead of hard-coded colors
+3. **Add custom styles only when necessary**
+4. **Don't recreate what Bootstrap already provides**
+5. **Keep custom CSS minimal and specific**
+
+## Bootstrap 5 Components to Use
+
+### 1. Grid System
+
+**Always use Bootstrap's grid** for layouts:
+
+```html
+<!-- ✅ GOOD: Use Bootstrap grid -->
+<div class="container">
+  <div class="row g-4">
+    <div class="col-12 col-md-6 col-lg-4">
+      <!-- Card content -->
+    </div>
+  </div>
+</div>
+
+<!-- ❌ BAD: Custom grid with CSS -->
+<div class="custom-container">
+  <div class="custom-row">
+    <div class="custom-col">
+      <!-- Card content -->
+    </div>
+  </div>
+</div>
+```
+
+**Grid Classes:**
+- `container` / `container-fluid` - Main wrapper
+- `row` - Row wrapper
+- `col-{breakpoint}-{size}` - Column sizing
+- `g-{size}` - Gutter spacing between columns
+
+### 2. Spacing Utilities
+
+**Use Bootstrap spacing** instead of custom margins/paddings:
+
+```html
+<!-- ✅ GOOD: Bootstrap spacing -->
+<div class="mb-4">Title</div>
+<div class="py-5 px-3">Content</div>
+<div class="mt-3 mb-5">Footer</div>
+
+<!-- ❌ BAD: Custom spacing -->
+<div style="margin-bottom: 24px">Title</div>
+<div class="custom-padding">Content</div>
+```
+
+**Spacing Scale:**
+- `m-{size}` - Margin (0-5, auto)
+- `p-{size}` - Padding (0-5)
+- `mt-`, `mb-`, `ms-`, `me-` - Margin top, bottom, start, end
+- `pt-`, `pb-`, `ps-`, `pe-` - Padding top, bottom, start, end
+- `mx-`, `my-` - Margin x-axis, y-axis
+- `px-`, `py-` - Padding x-axis, y-axis
+
+### 3. Display & Flexbox
+
+**Use Bootstrap display utilities:**
+
+```html
+<!-- ✅ GOOD: Bootstrap flex -->
+<div class="d-flex justify-content-between align-items-center">
+  <span>Left</span>
+  <span>Right</span>
+</div>
+
+<div class="d-grid gap-3">
+  <button>Button 1</button>
+  <button>Button 2</button>
+</div>
+
+<!-- ❌ BAD: Custom flexbox CSS -->
+<div class="custom-flex-container">
+  <span>Left</span>
+  <span>Right</span>
+</div>
+```
+
+### 4. Typography
+
+**Use Bootstrap typography classes:**
+
+```html
+<!-- ✅ GOOD: Bootstrap typography -->
+<h1 class="display-4 fw-bold">Main Title</h1>
+<p class="lead text-muted">Subtitle text</p>
+<p class="fs-5 lh-base">Body text</p>
+
+<!-- ❌ BAD: Custom typography CSS -->
+<h1 class="custom-title">Main Title</h1>
+<p class="custom-subtitle">Subtitle text</p>
+```
+
+### 5. Buttons
+
+**Use Bootstrap button styles:**
+
+```html
+<!-- ✅ GOOD: Bootstrap buttons -->
+<button class="btn btn-primary btn-lg w-100">Primary Action</button>
+<a href="#" class="btn btn-outline-secondary">Secondary</a>
+
+<!-- ❌ BAD: Fully custom button styles -->
+<button class="custom-button-primary">Primary Action</button>
+```
+
+### 6. Cards
+
+**Use Bootstrap card structure:**
+
+```html
+<!-- ✅ GOOD: Bootstrap card -->
+<div class="card h-100 shadow-sm">
+  <img src="..." class="card-img-top" alt="...">
+  <div class="card-body">
+    <h5 class="card-title">Title</h5>
+    <p class="card-text">Description</p>
+    <a href="#" class="btn btn-primary w-100">Action</a>
+  </div>
+</div>
+
+<!-- ❌ BAD: Fully custom card -->
+<div class="custom-card">
+  <img src="..." class="custom-image">
+  <div class="custom-content">
+    <h3>Title</h3>
+    <p>Description</p>
+  </div>
+</div>
+```
+
+### 7. Colors & Backgrounds
+
+**Use Bootstrap color utilities with extended palette:**
+
+```html
+<!-- ✅ GOOD: Bootstrap theme colors -->
+<div class="bg-primary text-white">Primary (Pink/Magenta)</div>
+<div class="bg-secondary text-white">Secondary (Purple)</div>
+<div class="bg-primary-soft">Primary soft background</div>
+<div class="bg-surface-gray">Surface gray</div>
+
+<!-- ✅ GOOD: Extended color shades -->
+<div class="bg-primary-100 text-primary-700">Light primary bg with dark text</div>
+<div class="bg-secondary-600 text-white">Darker secondary</div>
+
+<!-- ✅ GOOD: Semantic colors -->
+<div class="bg-success text-white">Success (Green)</div>
+<div class="bg-info text-white">Info (Blue)</div>
+<div class="bg-warning text-dark">Warning (Yellow)</div>
+<div class="bg-danger text-white">Danger (Red)</div>
+
+<!-- ❌ BAD: Custom color classes -->
+<div class="custom-pink-bg custom-white-text">Primary background</div>
+```
+
+**Available Color Variants** (for each semantic color):
+- `-25`, `-50`, `-100` through `-900` (lightness scale)
+- `-soft` (very light background)
+- `text-{color}-{shade}` (text colors)
+- `bg-{color}-{shade}` (background colors)
+
+### 8. Shadows & Borders
+
+**Use Bootstrap shadows and borders:**
+
+```html
+<!-- ✅ GOOD: Bootstrap utilities -->
+<div class="shadow-sm rounded-3 border border-light">
+  Card with shadow and border
+</div>
+
+<!-- ❌ BAD: Custom shadow/border CSS -->
+<div class="custom-shadow custom-border">
+  Card with shadow and border
+</div>
+```
+
+## Widget Structure Template
+
+### Standard Widget HTML
+
+```html
+<div class="widget-name-wrapper">
+  <div class="container">
+    <!-- Title Section -->
+    <div class="text-center mb-5">
+      <h2 class="display-5 fw-bold mb-3">Widget Title</h2>
+      <p class="lead text-muted">Optional subtitle</p>
+    </div>
+
+    <!-- Content Grid -->
+    <div class="row g-4">
+      <div class="col-12 col-md-6 col-lg-4">
+        <div class="card h-100 shadow-sm">
+          <img src="..." class="card-img-top" alt="...">
+          <div class="card-body d-flex flex-column">
+            <h5 class="card-title">Item Title</h5>
+            <p class="card-text flex-grow-1">Description</p>
+            <a href="#" class="btn btn-primary mt-auto">Action</a>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Minimal Custom CSS
+
+Only add custom CSS for:
+1. Hover effects and transitions (Bootstrap doesn't include these)
+2. Component-specific positioning or layout
+3. Animation keyframes
+4. Complex pseudo-elements
+
+**Use CSS variables** from the theme instead of hard-coded values:
+
+```css
+/* ✅ GOOD: Use theme CSS variables */
+.widget-name-wrapper {
+  background: var(--bs-surface-gray);
+  padding: var(--bs-ref-spacer-8) var(--bs-ref-spacer-6);
+}
+
+.card {
+  transition: transform 0.3s ease, box-shadow 0.3s ease;
+}
+
+.card:hover {
+  transform: translateY(-8px);
+  box-shadow: var(--bs-box-shadow-lg);
+}
+
+.btn-custom {
+  background: var(--bs-primary-600);
+  color: var(--bs-white);
+  border-radius: var(--bs-border-radius-pill);
+  padding: var(--bs-ref-spacer-3) var(--bs-ref-spacer-6);
+}
+
+.btn-custom:hover {
+  background: var(--bs-primary-700);
+}
+
+/* ✅ GOOD: Use extended spacing scale */
+.section {
+  margin-bottom: var(--bs-ref-spacer-12); /* 3rem */
+}
+
+/* ❌ BAD: Hard-coded values */
+.widget-name-wrapper {
+  background: #f0f0f2; /* Use var(--bs-surface-gray) */
+  padding: 32px 24px; /* Use var(--bs-ref-spacer-8) var(--bs-ref-spacer-6) */
+}
+
+.btn-custom {
+  background: #d81b60; /* Use var(--bs-primary) */
+  border-radius: 50px; /* Use var(--bs-border-radius-pill) */
+}
+
+/* ❌ BAD: Duplicating Bootstrap */
+.card {
+  border-radius: 8px;
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+  padding: 20px;
+  margin-bottom: 20px;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+}
+```
+
+**Key CSS Variables to Use**:
+
+**Colors**:
+- `var(--bs-primary)`, `var(--bs-primary-100)` through `var(--bs-primary-900)`
+- `var(--bs-secondary)`, `var(--bs-secondary-100)` through `var(--bs-secondary-900)`
+- `var(--bs-success)`, `var(--bs-info)`, `var(--bs-warning)`, `var(--bs-danger)`
+- `var(--bs-gray-100)` through `var(--bs-gray-900)`
+- `var(--bs-surface-primary)`, `var(--bs-surface-gray)`
+- `var(--bs-primary-soft)`, `var(--bs-secondary-soft)`
+
+**Spacing** (0.25rem increments):
+- `var(--bs-ref-spacer-0)` = 0
+- `var(--bs-ref-spacer-4)` = 1rem
+- `var(--bs-ref-spacer-8)` = 2rem
+- `var(--bs-ref-spacer-12)` = 3rem
+- `var(--bs-ref-spacer-16)` = 4rem
+- Up to `var(--bs-ref-spacer-30)` = 7.5rem
+
+**Borders**:
+- `var(--bs-border-radius)` = 1rem
+- `var(--bs-border-radius-pill)` = 50rem
+- `var(--bs-border-color)`
+
+**Shadows**:
+- `var(--bs-box-shadow-sm)`
+- `var(--bs-box-shadow)`
+- `var(--bs-box-shadow-lg)`
+
+## Responsive Design with Bootstrap
+
+### Breakpoints
+
+Use Bootstrap's responsive classes:
+
+```html
+<!-- Mobile-first approach -->
+<div class="col-12 col-sm-6 col-md-4 col-lg-3">
+  <!-- 1 column on mobile, 2 on small, 3 on medium, 4 on large -->
+</div>
+
+<!-- Hide/show at different breakpoints -->
+<div class="d-none d-md-block">Visible on medium and up</div>
+<div class="d-block d-md-none">Visible only on small screens</div>
+```
+
+### Spacing Responsive
+
+```html
+<!-- Different spacing per breakpoint -->
+<div class="py-3 py-md-5">
+  <!-- py-3 on mobile, py-5 on medium+ -->
+</div>
+
+<div class="mb-3 mb-lg-5">
+  <!-- mb-3 on mobile, mb-5 on large+ -->
+</div>
+```
+
+## Content Integration
+
+### Content Consumption Strategy
+
+**Best Practice**: Always use **Liquid-first approach** for content consumption:
+
+1. ✅ **Primary Method**: Use Liquid templates for initial content load (server-side rendering)
+2. ✅ **Secondary Method**: Fetch additional content via JavaScript if needed (pagination, infinite scroll)
+
+**Why Liquid-first?**
+- ⚡ **Faster initial render** - Content arrives with HTML, no API wait
+- 🔍 **Better SEO** - Search engines see actual content, not loading states
+- 📱 **Better UX** - Users see content immediately, no spinners
+- 💰 **Lower API costs** - Fewer API calls from client-side
+- 🔒 **More secure** - No API tokens exposed to browser
+
+### Accessing Modyo Content with Liquid
+
+**Basic pattern** for displaying content:
+
+```liquid
+{%- assign entries = spaces['space-uid'].types['type-uid'].entries -%}
+{%- if entries.size > 0 -%}
+  <div class="container">
+    <div class="row g-4">
+      {%- for entry in entries -%}
+        <div class="col-12 col-md-6 col-lg-4">
+          <div class="card h-100 shadow-sm">
+            <div class="card-body">
+              <h5 class="card-title">{{ entry.fields['Title'] }}</h5>
+              <p class="card-text">{{ entry.fields['Description'] }}</p>
+              {%- if entry.fields['URL'] != blank -%}
+                <a href="{{ entry.fields['URL'] }}" class="btn btn-primary w-100">
+                  Read More
+                </a>
+              {%- endif -%}
+            </div>
+          </div>
+        </div>
+      {%- endfor -%}
+    </div>
+  </div>
+{%- else -%}
+  <div class="container">
+    <div class="alert alert-info text-center">
+      No content available
+    </div>
+  </div>
+{%- endif -%}
+```
+
+### Hybrid Approach: Liquid + JavaScript
+
+**When to fetch more content via JavaScript:**
+- Pagination ("Load More" button)
+- Infinite scroll
+- Filtering/search after page load
+- Real-time updates
+
+**Example**: Initial 12 items via Liquid, load more via JavaScript:
+
+```liquid
+<!-- HTML: Render first 12 entries via Liquid -->
+{%- assign initial_entries = spaces['products'].types['product'].entries | sort_by: 'created_at' | limit: 12 -%}
+<div id="products-grid" class="row g-4">
+  {%- for entry in initial_entries -%}
+    <div class="col-12 col-md-6 col-lg-4">
+      <div class="card h-100 shadow-sm">
+        <div class="card-body">
+          <h5 class="card-title">{{ entry.fields['Title'] }}</h5>
+          <p class="card-text">{{ entry.fields['Description'] }}</p>
+        </div>
+      </div>
+    </div>
+  {%- endfor -%}
+</div>
+
+<!-- Load More button -->
+{%- if initial_entries.size >= 12 -%}
+  <div class="text-center mt-4">
+    <button id="load-more-btn" class="btn btn-primary">
+      Load More Products
+    </button>
+  </div>
+{%- endif -%}
+```
+
+```javascript
+// JavaScript: Fetch more entries on button click
+let page = 2; // Liquid loaded page 1
+const loadMoreBtn = document.getElementById('load-more-btn');
+
+loadMoreBtn.addEventListener('click', async () => {
+  const response = await fetch(
+    `/api/content/spaces/products/types/product/entries?per_page=12&page=${page}`
+  );
+  const data = await response.json();
+
+  // Append new entries to grid
+  const grid = document.getElementById('products-grid');
+  data.entries.forEach(entry => {
+    const col = document.createElement('div');
+    col.className = 'col-12 col-md-6 col-lg-4';
+    col.innerHTML = `
+      <div class="card h-100 shadow-sm">
+        <div class="card-body">
+          <h5 class="card-title">${entry.fields.Title}</h5>
+          <p class="card-text">${entry.fields.Description}</p>
+        </div>
+      </div>
+    `;
+    grid.appendChild(col);
+  });
+
+  page++;
+
+  // Hide button if no more entries
+  if (data.entries.length < 12) {
+    loadMoreBtn.style.display = 'none';
+  }
+});
+```
+
+### Accessing Site Assets
+
+**Important**: Assets can be uploaded to **two locations**:
+
+1. **Content Space Assets** (`/api/admin/content/spaces/{space_id}/assets`)
+   - Organized by space
+   - Managed in Content module
+   - Accessible via Content Delivery API
+
+2. **Site Assets** (`/api/admin/sites/{site_id}/assets`)
+   - Organized by site
+   - Managed in Channels module
+   - Accessible via site URL
+
+Both asset types are CDN-served and can be referenced in Liquid templates.
+
+**Remember**: Field names must match exactly (see [Liquid Field Access](./LIQUID_FIELD_ACCESS.md))
+
+## Common Patterns
+
+### Hero Section
+
+```html
+<div class="hero-wrapper bg-primary text-white">
+  <div class="container py-5">
+    <div class="row align-items-center">
+      <div class="col-lg-6">
+        <h1 class="display-3 fw-bold mb-4">Hero Title</h1>
+        <p class="lead mb-4">Hero description text</p>
+        <a href="#" class="btn btn-light btn-lg">Get Started</a>
+      </div>
+      <div class="col-lg-6">
+        <img src="..." class="img-fluid rounded" alt="Hero">
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Feature Cards
+
+```html
+<div class="container py-5">
+  <div class="row g-4">
+    <div class="col-md-4">
+      <div class="text-center">
+        <div class="mb-3">
+          <!-- Icon or SVG -->
+        </div>
+        <h5 class="fw-bold">Feature Title</h5>
+        <p class="text-muted">Feature description</p>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Call-to-Action
+
+```html
+<div class="cta-wrapper bg-light py-5">
+  <div class="container">
+    <div class="row justify-content-center">
+      <div class="col-lg-8 text-center">
+        <h2 class="display-5 fw-bold mb-3">Ready to get started?</h2>
+        <p class="lead text-muted mb-4">Join thousands of happy customers</p>
+        <a href="#" class="btn btn-primary btn-lg">Start Now</a>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## Performance Tips
+
+1. **Minimize custom CSS** - Less CSS = faster page load
+2. **Use Bootstrap classes** - Already cached in browser
+3. **Avoid !important** - Breaks Bootstrap cascade
+4. **Use Bootstrap variables** - For consistent theming
+5. **Keep specificity low** - Easier to maintain
+
+## Common Mistakes
+
+### ❌ Don't Do This
+
+```html
+<!-- Don't recreate the grid -->
+<div class="custom-container">
+  <div class="custom-row">
+    <div class="custom-col-4">Content</div>
+  </div>
+</div>
+
+<!-- Don't duplicate spacing -->
+<div style="margin-top: 20px; margin-bottom: 20px;">
+  Content
+</div>
+
+<!-- Don't ignore Bootstrap utilities -->
+<div class="my-custom-centered-flex-container">
+  Content
+</div>
+```
+
+### ✅ Do This Instead
+
+```html
+<!-- Use Bootstrap grid -->
+<div class="container">
+  <div class="row">
+    <div class="col-md-4">Content</div>
+  </div>
+</div>
+
+<!-- Use Bootstrap spacing -->
+<div class="my-4">
+  Content
+</div>
+
+<!-- Use Bootstrap utilities -->
+<div class="d-flex justify-content-center align-items-center">
+  Content
+</div>
+```
+
+## Checklist for Widget Development
+
+Before publishing a widget, verify:
+
+**Bootstrap Usage**:
+- [ ] Uses Bootstrap grid system (`container`, `row`, `col-*`)
+- [ ] Uses Bootstrap spacing utilities (`m-*`, `p-*`, `g-*`)
+- [ ] Uses Bootstrap display utilities (`d-flex`, `d-grid`, etc.)
+- [ ] Uses Bootstrap typography classes (`display-*`, `lead`, `fs-*`)
+- [ ] Uses Bootstrap color utilities (`bg-*`, `text-*`)
+- [ ] Uses extended color shades when needed (`bg-primary-100`, `text-secondary-600`)
+- [ ] No duplicate styles already in Bootstrap
+
+**CSS Variables**:
+- [ ] Uses theme CSS variables instead of hard-coded colors
+- [ ] Uses `var(--bs-primary)`, `var(--bs-primary-600)` etc. for colors
+- [ ] Uses `var(--bs-ref-spacer-*)` for spacing in custom CSS
+- [ ] Uses `var(--bs-border-radius)`, `var(--bs-box-shadow-*)` for effects
+- [ ] Custom CSS is minimal and necessary
+
+**Quality & Testing**:
+- [ ] Responsive at all breakpoints (xs, sm, md, lg, xl)
+- [ ] Field names match Content Type exactly (if using content)
+- [ ] Tested on mobile, tablet, and desktop
+- [ ] No console errors
+- [ ] Hover states work correctly
+- [ ] Follows accessibility best practices
+
+## Reference
+
+### Bootstrap 5 Documentation
+- [Grid System](https://getbootstrap.com/docs/5.3/layout/grid/)
+- [Utilities](https://getbootstrap.com/docs/5.3/utilities/spacing/)
+- [Components](https://getbootstrap.com/docs/5.3/components/alerts/)
+- [Content](https://getbootstrap.com/docs/5.3/content/typography/)
+
+### Modyo Documentation
+- [Liquid Templates](https://docs.modyo.com/en/platform/channels/liquid-markup.html)
+- [Widgets](https://docs.modyo.com/en/platform/channels/widgets.html)
+- [Content Access](./LIQUID_FIELD_ACCESS.md)
+
+---
+
+## CSS Variable Reference
+
+### Complete Color System
+
+**Primary (Pink/Magenta)**:
+```css
+--bs-primary: rgb(216, 27, 96)
+--bs-primary-25 through --bs-primary-900 (lightness scale)
+--bs-primary-soft: rgb(253, 244, 247)
+```
+
+**Secondary (Purple)**:
+```css
+--bs-secondary: rgb(72, 72, 183)
+--bs-secondary-25 through --bs-secondary-900
+--bs-secondary-soft: rgb(246, 246, 251)
+```
+
+**Semantic Colors**:
+- Success (Green): `--bs-success` = `rgb(25, 135, 84)`
+- Info (Blue): `--bs-info` = `rgb(13, 110, 253)`
+- Warning (Yellow): `--bs-warning` = `rgb(255, 193, 7)`
+- Danger (Red): `--bs-danger` = `rgb(220, 53, 69)`
+
+**Gray Scale**:
+```css
+--bs-gray-25: rgb(251, 251, 252)
+--bs-gray-50: rgb(240, 240, 242)
+--bs-gray-100: rgb(225, 225, 230)
+--bs-gray-200 through --bs-gray-900
+```
+
+**Surface & Soft Backgrounds**:
+```css
+--bs-surface-gray: rgb(240, 240, 242)
+--bs-surface-primary: rgb(251, 232, 239)
+--bs-surface-secondary: rgb(237, 237, 248)
+```
+
+### Spacing Scale Reference
+
+```css
+--bs-ref-spacer-0: 0
+--bs-ref-spacer-1: 0.25rem
+--bs-ref-spacer-2: 0.5rem
+--bs-ref-spacer-3: 0.75rem
+--bs-ref-spacer-4: 1rem (16px)
+--bs-ref-spacer-5: 1.25rem
+--bs-ref-spacer-6: 1.5rem
+--bs-ref-spacer-7: 1.75rem
+--bs-ref-spacer-8: 2rem (32px)
+--bs-ref-spacer-12: 3rem (48px)
+--bs-ref-spacer-16: 4rem (64px)
+--bs-ref-spacer-20: 5rem (80px)
+--bs-ref-spacer-24: 6rem (96px)
+--bs-ref-spacer-30: 7.5rem (120px)
+```
+
+### Quick Reference Examples
+
+**Using color shades**:
+```css
+.light-bg { background: var(--bs-primary-100); }
+.medium-bg { background: var(--bs-primary-500); }
+.dark-bg { background: var(--bs-primary-700); }
+```
+
+**Using spacing**:
+```css
+.section { padding: var(--bs-ref-spacer-8); } /* 2rem = 32px */
+.gap { gap: var(--bs-ref-spacer-4); } /* 1rem = 16px */
+```
+
+---
+
+**Document Version**: 2.0.0
+**Last Updated**: 2025-01-10
+**Purpose**: Best practices for widget development with customized Bootstrap 5 theme in Modyo