SCSS Styling System - Implementation Complete ✅

Status: Production Ready
Date: May 1, 2024
Implementation Phase: Styling Foundation & Integration

Overview

Successfully implemented a modular, scalable SCSS styling system for Anki flashcards with:

• 80+ CSS variables for consistent design tokens across all courses
• Reusable base components shared by all courses
• Course-specific styling for Psychology and DevOps (foundation for 50+ courses)
• Compiled CSS automatically injected into APKG files
• Zero breaking changes to existing infrastructure

Architecture

File Structure

scripts/anki/styles/
├── _variables.scss              # Global design tokens (colors, spacing, typography)
├── _base-components.scss        # Reusable CSS classes for all card types
├── courses/
│   ├── psychology.scss          # Psychology-specific color overrides
│   └── devops.scss              # DevOps-specific styling
├── psychology.css               # Compiled output (16 KB)
└── devops.css                   # Compiled output (17 KB)

Design Flow

User Card Data (JSON)
    ↓
metadata['course'] = 'psychology'
    ↓
APKGGenerator creates models
    ↓
_get_css('psychology')
    ↓
Load: scripts/anki/styles/psychology.css
    ↓
Inject CSS into Anki models
    ↓
Generate APKG with styled cards

Component Breakdown

1. Global Variables (_variables.scss)

Color Palette:

• Primary colors: Blue (#0066cc), Red (#d9534f), Green (#1e7e34), Orange (#ff9500)
• State colors: Success, Warning, Danger, Info
• Backgrounds: Light, light-blue, light-green, light-orange, dark
• Text: Dark, Light, Muted, White

Spacing Scale:

• xs (4px) → xxl (32px) for consistent margins and padding

Typography:

• Font families: System (-apple-system), Monospace, Code
• Sizes: xs (12px) → xxl (20px)
• Weights: Light (300) → Bold (700)
• Line heights: Tight (1.3) → Loose (1.7)

Other Tokens:

• Border radius (4px - 12px)
• Shadows (sm, md, lg with opacity)
• Transitions (150ms, 300ms, 500ms)
• Z-index scale (base to modal)
• Breakpoints (responsive design)

2. Base Components (_base-components.scss)

Implements universal card types used by all courses:

Content Components:

• .skill-card - Lists of skills with blue accent
• .comparison-box - Side-by-side comparisons
• .definition-card - Term + definition with gradient
• .highlight-card - Highlighted/quoted content

Status Indicators:

• .success-box - Green background, green border
• .warning-box - Orange background, orange border
• .danger-box - Red background, red border
• .info-box - Blue background, blue border

Code & Technical:

• .code-block - Dark background, syntax highlighting
• .terminal-output - Black background, green text (classic terminal)
• Inline code styling with light background

Utilities:

• Text alignment: .text-center, .text-right, .text-left
• Text styling: .text-bold, .text-italic, .text-small, .text-muted
• Spacing utilities: .mt-1, .mb-2, .p-3, etc.

3. Course-Specific Overrides

Psychology (psychology.scss)

Purpose: Support counselling skills, empathy training, therapeutic concepts

Color Scheme:

• Primary: #0066cc (professional blue for empathy)
• Accent: #1e7e34 (warm green for growth)
• Secondary: #005fa3 (darker blue for hierarchy)

Custom Components:

• .counselling-technique - Structured technique display
• .response-pattern - Counsellor response examples
• .skill-assessment - Skill evaluation framework
• .empathy-emphasis / .sympathy-emphasis - Comparative styling
• .counsellor-note - Advisory formatting

Table Styling:

• Light blue headers with psychology primary color
• Hover state with blue tint

DevOps (devops.scss)

Purpose: Support infrastructure, cloud engineering, deployment workflows

Color Scheme:

• Primary: #d9534f (red for critical/alerts)
• Accent: #5cb85c (green for success)
• Secondary: #0275d8 (blue for commands/info)
• Dark: #2d2d2d (code backgrounds)

Custom Components:

• .command-box - Shell commands with output
• .architecture-component - Infrastructure diagrams
• .deployment-steps - Numbered workflow steps
• .configuration-box - Config key/value pairs
• .devops-alert - Incident/failure alerts

Syntax Highlighting:

• Keywords: Pink (#ff79c6)
• Strings: Yellow (#f1fa8c)
• Numbers: Purple (#bd93f9)
• Comments: Blue-gray (#6272a4)
• Functions: Green (#50fa7b)

Status Styling:

• .status-success - Green
• .status-error - Red
• .status-pending - Orange

Compilation Pipeline

Build Process

 1# Compile all course CSS
 2npm run anki:styles:compile
 3
 4# Compile specific course
 5npm run anki:styles:compile:psychology
 6npm run anki:styles:compile:devops
 7
 8# Watch mode for development
 9npm run anki:styles:watch
10
11# List compiled CSS files
12npm run anki:styles:list

Sass Compiler Details

• Installed: sass@^1.99.0 (npm dev dependency)
• Input: Course-specific SCSS files in scripts/anki/styles/courses/
• Output: Compiled CSS in scripts/anki/styles/ (same directory for easy reference)
• Size: Psychology (16K), DevOps (17K)

Integration with APKG Generator

How CSS Gets Into Your Decks

1. Metadata Detection

   1{
   2  "metadata": {
   3    "course": "psychology"  // This key triggers CSS loading
   4  }
   5}
   

2. CSS Loading

   • APKG generator reads data['metadata']['course']
   • Looks for scripts/anki/styles/{course}.css
   • Falls back to default CSS if file not found
   • Caches CSS for performance

3. Model Creation

   • All three card models receive the loaded CSS
   • CSS embedded in Anki model templates
   • Applied to all cards in the deck

4. Result

   • Psychology decks: ~68 KB (includes psychology CSS)
   • DevOps decks: ~72 KB (includes devops CSS)
   • Default decks: ~56 KB (minimal CSS)

Test Results

✅ Psychology CSS integration verified (68.2 KB APKG)
✅ DevOps CSS integration verified (72.2 KB APKG)
✅ Default CSS fallback verified (56.2 KB APKG)
✅ CSS caching working correctly
✅ All 51 existing tests still passing

Adding New Courses

Step 1: Create Course-Specific SCSS

Create scripts/anki/styles/courses/{coursename}.scss:

 1@import '../variables';
 2@import '../base-components';
 3
 4// Override variables for your course
 5$course-primary: #your-color;
 6$course-accent: #another-color;
 7
 8// Override or enhance component styling
 9.skill-card {
10  background-color: rgba($course-primary, 0.1);
11  border-left-color: $course-primary;
12}

Step 2: Compile CSS

1npx sass scripts/anki/styles/courses/{coursename}.scss \
2  scripts/anki/styles/{coursename}.css

Step 3: Add Course Metadata to JSON

1{
2  "metadata": {
3    "course": "coursename"
4  }
5}

Step 4: Generate APKG

The APKG generator automatically detects the course and injects the CSS!

Design Principles

1. DRY (Don’t Repeat Yourself)

• Common styles in _base-components.scss
• Variables in _variables.scss
• Courses only override what’s different

2. Scalability

• Support up to 50+ courses without conflicts
• Each course is isolated in its own SCSS file
• No naming collisions (CSS class names are generic)

3. Maintainability

• Global variables in one place
• Clear component naming conventions
• Comprehensive comments for each section

4. Performance

• CSS cached after first load
• Pre-compiled to CSS (no runtime compilation)
• Reasonable file sizes (16-17 KB per course)

5. Backward Compatibility

• Default CSS still works (no course metadata required)
• Existing decks unaffected
• Graceful fallback if course CSS not found

File Statistics

Source Files

Compiled Output

Test Coverage

Usage Examples

Example 1: Psychology Card with Styling

JSON:

1{
2  "id": "psy-001",
3  "question": "What are the core counselling skills?",
4  "answer": "<div class='skill-card'><h4>Core Skills</h4><ol class='skill-list'><li class='skill-item'><b>Empathy</b></li><li class='skill-item'><b>Active Listening</b></li></ol></div>",
5  "tags": ["counselling", "skills"],
6  "difficulty": 2,
7  "html_enabled": true
8}

Rendered In Anki:

• Light blue background (#f0f7ff)
• Blue border on left side (#0066cc)
• Skills listed vertically with blue emphasis

Example 2: DevOps Command Card

JSON:

1{
2  "id": "devops-001",
3  "question": "Deploy to production",
4  "answer": "<div class='command-box'><div class='command-label'>Deploy Command:</div><div class='command-text'>kubectl apply -f deployment.yaml</div><div class='command-output'>deployment.apps/my-app created</div></div>",
5  "tags": ["kubernetes", "deployment"],
6  "difficulty": 2,
7  "html_enabled": true
8}

Rendered In Anki:

• Dark background (#2d2d2d)
• Green text for success output
• Monospace font for command legibility

Next Steps & Roadmap

Immediate (Completed ✅)

• Create global variables
• Implement base components
• Create psychology styling
• Create devops styling
• Compile to CSS
• Integrate with APKG generator
• Add npm build scripts
• Create integration test

Short Term (Ready to implement)

• Create additional course stylesheets (ML, QA, etc.)
• Document styling guide for content creators
• Create card template examples for each course
• Add responsive design testing

Medium Term (Enhancement)

• Create dark mode variants
• Add animation/transition support
• Implement accessibility improvements
• Create Anki add-on for theme preview

Long Term (Advanced)

• Build theme customization UI
• Add community theme gallery
• Implement dynamic CSS generation from UI
• Cloud sync for theme preferences

Git History

1[679f599f] test(anki): Add CSS integration test for APKG generation
2[547929e1] feat(anki): Integrate course-specific CSS into APKG generation
3[889cb6ee] build(anki): Compile course-specific SCSS to CSS and add npm scripts
4[cd4ba7fb] style(anki): Create comprehensive SCSS styling system

Verification Checklist

• ✅ SCSS files created and organized
• ✅ CSS compiled successfully
• ✅ npm scripts added for compilation
• ✅ APKG generator modified for CSS integration
• ✅ CSS loading from compiled files working
• ✅ Course detection from metadata working
• ✅ Default CSS fallback working
• ✅ CSS caching implemented
• ✅ All existing tests still passing
• ✅ Integration test created and passing
• ✅ Zero breaking changes
• ✅ Documentation complete

Key Metrics

Documentation Links

• 📖 Styling System Guide
• 🔧 Setup Guide

Questions & Support

For questions about the styling system:

1. Check the documentation files in content/docs/anki/
2. Review examples in tests/anki/test_css_integration.py
3. Check course_styles.json for course registry
4. Inspect compiled CSS files for actual styles

Status: ✅ Production Ready - SCSS system fully implemented and integrated