mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-04-29 00:59:07 -05:00
docs: Document completed callout styling consolidation
Added comprehensive REFACTORING COMPLETED section documenting: - Changes to dark-mode.scss (159 lines → 13 lines) - Changes to style.scss (52 refs → 8 refs) - Verification that foldbox.css already had all needed styles - New Extension-First architecture diagram - Testing results (HTML/EPUB builds, output verification) - Metrics (~190 lines removed, 2 files modified) - Benefits achieved (no duplication, single source of truth) - Issues resolved (colab dark mode, maintenance burden) Status: Ready for review and merge to dev
This commit is contained in:
Vijay Janapa Reddi
@@ -279,4 +279,211 @@ details.callout-colab > summary {
|
||||
- **Keep git history clean**: Small, focused commits
|
||||
- **Document decisions**: Update this file as we go
|
||||
|
||||
---
|
||||
|
||||
## ✅ REFACTORING COMPLETED
|
||||
|
||||
**Commit**: `56c30395f` (2025-11-09)
|
||||
**Branch**: `refactor/consolidate-callout-styles`
|
||||
|
||||
### Changes Implemented
|
||||
|
||||
#### 1. `quarto/assets/styles/dark-mode.scss`
|
||||
**Before**: 159 lines of duplicate callout dark mode rules
|
||||
**After**: 13-line comment block explaining foldbox.css handles it
|
||||
|
||||
**Removed**:
|
||||
- All `details.callout-*` color/background definitions (quiz, definition, example, colab, chapter-connection, resources, code)
|
||||
- All summary header text colors (`color: #f0f0f0 !important`)
|
||||
- All content body backgrounds (`background-color: #212529 !important`)
|
||||
- All arrow styling (`details > summary::after`)
|
||||
- All code element colors (`details.callout-* code`)
|
||||
- All link colors for callouts (`details.callout-* a { color: lighten($crimson, 10%) }`)
|
||||
|
||||
**Added**:
|
||||
```scss
|
||||
// ============================================================================
|
||||
// CALLOUT/FOLDBOX DARK MODE STYLING
|
||||
// ============================================================================
|
||||
// NOTE: All foldbox/callout dark mode styling is now handled by:
|
||||
// quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css
|
||||
//
|
||||
// The extension contains a @media (prefers-color-scheme: dark) section that
|
||||
// handles all dark mode styling for custom callouts...
|
||||
```
|
||||
|
||||
#### 2. `quarto/assets/styles/style.scss`
|
||||
**Before**: 52 references with redundant alignment rules
|
||||
**After**: 8 references with minimal Quarto overrides
|
||||
|
||||
**Removed**:
|
||||
- `details.callout-definition > div` left-align rules (44 lines)
|
||||
- `details.callout-* ul/ol` list styling rules
|
||||
- `details.callout-* li` list item alignment
|
||||
- `details.callout-* > summary` header alignment
|
||||
- `details.callout-* > summary strong` text alignment
|
||||
|
||||
**Kept**:
|
||||
```scss
|
||||
/* Exclude all custom foldbox callouts from general callout styling */
|
||||
.callout.callout-quiz-question,
|
||||
.callout.callout-quiz-answer,
|
||||
.callout.callout-definition,
|
||||
.callout.callout-example,
|
||||
.callout.callout-colab {
|
||||
margin: 0 !important;
|
||||
border: none !important;
|
||||
box-shadow: none !important;
|
||||
background: transparent !important;
|
||||
text-align: left !important;
|
||||
}
|
||||
|
||||
/* Ensure content inside foldbox callouts is left-aligned */
|
||||
.callout.callout-* div {
|
||||
text-align: left !important;
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. `quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css`
|
||||
**No changes required** ✅
|
||||
|
||||
Already contained complete styling:
|
||||
- Light mode (lines 1-220): colors, borders, backgrounds, icon positioning
|
||||
- Dark mode (lines 223-398): `@media (prefers-color-scheme: dark)` with all overrides
|
||||
- All callout types: definition, example, quiz-question, quiz-answer, colab, chapter-connection, chapter-forward, chapter-recall, resource-slides, resource-videos, resource-exercises, code
|
||||
|
||||
**Verified dark mode includes**:
|
||||
```css
|
||||
@media (prefers-color-scheme: dark) {
|
||||
details.callout-colab {
|
||||
--text-color: #e6e6e6;
|
||||
--background-color: rgba(255, 107, 53, 0.12);
|
||||
--title-background-color: rgba(255, 107, 53, 0.12);
|
||||
border-color: #FF6B35;
|
||||
}
|
||||
|
||||
details.callout-colab summary,
|
||||
details.callout-colab summary strong,
|
||||
details.callout-colab > summary {
|
||||
color: #f0f0f0 !important;
|
||||
}
|
||||
|
||||
details.callout-colab code {
|
||||
color: #e6e6e6 !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### New Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ foldbox.css (Extension - Single Source of Truth) │
|
||||
│ ✅ Light mode: colors, layouts, icons │
|
||||
│ ✅ Dark mode: @media query with all overrides │
|
||||
│ ✅ ALL callout types fully styled │
|
||||
│ ✅ Self-contained and portable │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ includes
|
||||
│
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ style.scss (Minimal Quarto Overrides - 8 refs) │
|
||||
│ ✅ Exclude custom callouts from Quarto defaults │
|
||||
│ ✅ Remove box-shadow/borders from wrapper divs │
|
||||
│ ✅ One simple left-align rule for content │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ dark-mode.scss (No Callout Rules - 13 lines) │
|
||||
│ ✅ Comment explaining foldbox.css handles everything │
|
||||
│ ✅ Only non-callout dark mode rules remain │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ epub.css (EPUB Fallback - Unchanged) │
|
||||
│ ✅ Fallback styles when extension doesn't run │
|
||||
│ ✅ Plain div rendering without <details> │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Testing Results
|
||||
|
||||
#### Build Verification
|
||||
```bash
|
||||
./binder html intro # ✅ Success - no errors
|
||||
./binder epub intro # ✅ Success - no errors
|
||||
```
|
||||
|
||||
#### Output Verification
|
||||
```bash
|
||||
# Confirmed callout icons render correctly
|
||||
grep "callout-definition" quarto/_build/html/.../introduction.html
|
||||
# Output: <details class="callout-definition fbx-default closebutton" open="">
|
||||
|
||||
# Confirmed dark mode styles present in built CSS
|
||||
grep "callout-colab" quarto/_build/html/site_libs/quarto-contrib/foldbox/foldbox.css
|
||||
# Found at lines: 166 (light), 354 (dark), 361-379 (dark rules)
|
||||
|
||||
# Confirmed CSS is properly linked
|
||||
grep "foldbox.css" quarto/_build/html/.../introduction.html
|
||||
# Output: <link href=".../foldbox/foldbox.css" rel="stylesheet">
|
||||
```
|
||||
|
||||
#### Visual Verification
|
||||
✅ All callout icons present (definition, quiz-question, quiz-answer, example)
|
||||
✅ Callout styling matches previous renders
|
||||
✅ No visual regressions detected
|
||||
✅ Pre-commit hooks passed (no whitespace, YAML, or formatting issues)
|
||||
|
||||
### Metrics
|
||||
|
||||
**Lines Removed**: ~190 lines of duplicate/redundant CSS
|
||||
- `dark-mode.scss`: 159 lines → 13 lines (comment)
|
||||
- `style.scss`: 52 references → 8 references
|
||||
|
||||
**Files Modified**: 2
|
||||
- `quarto/assets/styles/dark-mode.scss`
|
||||
- `quarto/assets/styles/style.scss`
|
||||
|
||||
**Files Unchanged**: 2
|
||||
- `quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css` (already correct)
|
||||
- `quarto/assets/styles/epub.css` (fallback still needed)
|
||||
|
||||
### Benefits Achieved
|
||||
|
||||
1. ✅ **No Duplication**: Dark mode rules exist only in foldbox.css `@media` query
|
||||
2. ✅ **Consistency**: All callouts (including colab) styled identically via extension
|
||||
3. ✅ **Maintainability**: Single file (`foldbox.css`) to update for callout appearance changes
|
||||
4. ✅ **Self-Contained**: Extension handles its own light/dark modes independently
|
||||
5. ✅ **Clear Separation**: Host styles (`style.scss`) only exclude from Quarto defaults, don't define appearance
|
||||
6. ✅ **Tested**: HTML and EPUB builds verified working with correct rendering
|
||||
7. ✅ **Portable**: Extension can be reused in other Quarto projects without modifications
|
||||
|
||||
### Potential Issues Resolved
|
||||
|
||||
- ❌ **BEFORE**: `callout-colab` missing from `dark-mode.scss` (inconsistent dark mode support)
|
||||
- ✅ **AFTER**: All callouts get consistent dark mode via extension's `@media` query
|
||||
|
||||
- ❌ **BEFORE**: Duplication between `foldbox.css` and `dark-mode.scss` (maintenance burden)
|
||||
- ✅ **AFTER**: Single source of truth in extension
|
||||
|
||||
- ❌ **BEFORE**: 52 references in `style.scss` with scattered logic across multiple rules
|
||||
- ✅ **AFTER**: 8 references with clear, minimal purpose
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. ✅ **Refactoring complete** - all tests passing
|
||||
2. ⏳ **Merge to dev** - once user approves
|
||||
3. ⏳ **Update documentation** - document Extension-First architecture in project docs
|
||||
4. ⏳ **Monitor production** - watch for any dark mode issues in deployed book
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The consolidation successfully eliminated ~190 lines of duplicate CSS while maintaining exact visual fidelity. The custom-numbered-blocks extension is now self-contained and handles all callout styling (light and dark modes) independently. Host stylesheets (`style.scss`, `dark-mode.scss`) now have clear, minimal roles: exclude custom callouts from Quarto's default styling, nothing more.
|
||||
|
||||
**Status**: ✅ **Ready for Review and Merge**
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user