Troubleshooting the Living Syllabus

This guide serves as the technical reference for "Maintainers" using the Canvas Component Generator. It details the constraints of the Canvas Learning Management System (LMS) "Walled Garden" environment and provides specific fixes for common rendering issues.

For more context on the project philosophy or to contribute to the source code, visit the Project Hub or the GitHub Repository.

1. The Canvas Sanitizer Constraints

Canvas employs an aggressive HTML sanitizer (based on canvas_sanitize) that strips out code considered insecure or unstable. You cannot paste a standard website's code into a Canvas Page and expect it to function.

1. The Allowed List (Safe to Use)

These tags and attributes consistently survive the sanitization process.

The Blocked List (Will Be Stripped)

Attempting to use these will result in the code being deleted or the tags stripped, leaving unstyled text behind.

• JavaScript: <script> tags are instantly removed. No interactive quizzes or calculators.
• External CSS: <link rel="stylesheet"> is blocked. You cannot import Google Fonts or Bootstrap.
• Style Blocks: <style>...</style> headers are generally stripped. Fix: All CSS must be inlined (<div style="...">).
• SVG Code: Raw <svg> blocks are often corrupted. Fix: Use .svg files as <img> sources.
• Iframes: Generally blocked unless the domain is whitelisted by your university admin (e.g., YouTube is usually safe; personal blogs are not).

2. Common Display Issues & Fixes

Issue: "My Columns Don't Stack on Mobile"

Symptoms: Content side-by-side looks great on desktop but gets squished and unreadable on phones.
Cause: Canvas often strips @media queries, meaning standard responsive CSS (like Bootstrap's col-md-6) fails.
The Fix: Use the "Fluid Hybrid" (Flex-Wrap) method.

• Solution: Apply display: flex; flex-wrap: wrap; to the container and min-width: 300px; flex: 1; to the columns. This forces the browser to wrap columns automatically when the screen is too narrow, without needing media queries.

Issue: "White Boxes with Invisible Text in Dark Mode"

Symptoms: Your content looks perfect in Light Mode, but in Dark Mode, you see blinding white boxes, or your text disappears (black text on dark grey background).
Cause:

1. Hard-coding background-color: #ffffff.
2. Hard-coding color: #000000.
   The Fix: Use RGBA Transparency and Undefined Colors.

• Backgrounds: Never use solid white. Use background-color: rgba(0,0,0, 0.04). In Light Mode, it looks light grey. In Dark Mode, it allows the dark theme to show through.
• Text: Never set a text color to black. Leave it undefined so the browser automatically toggles it to White in Dark Mode.

Issue: "My Styles Disappeared After Pasting"

Symptoms: You pasted your HTML, but it looks like plain Times New Roman text. All margins, colors, and grids are gone.
Cause: You likely pasted code with CSS classes (e.g., class="p-4 bg-blue-500") but did not include the CSS definitions, or the <style> block was stripped.
The Fix: Run the Generator Script.

• Solution: You must use the generate.js script (or juice) to "compile" your classes into inline styles (style="padding: 1rem; background: blue;") before pasting. Canvas ignores classes it doesn't recognize but respects inline styles.

3. The Environment Test (Verification)

Before deploying a complex component, create a blank Page in Canvas, switch to the HTML Editor, and paste this test block. It validates if your specific university instance supports the necessary features.

<details style="background: rgba(0,0,0,0.05); padding: 10px; border-radius: 5px; margin-bottom: 1rem;">
  <summary style="cursor: pointer; font-weight: bold;">Click to expand this secret section</summary>
  <p>✅ PASS: If you can see this, native interactions (<details>) work.</p>
</details>

<div style="display: flex; gap: 20px; flex-wrap: wrap;">
  <div style="flex: 1; min-width: 200px; background: rgba(49, 130, 206, 0.15); padding: 20px; border: 1px solid #3182ce;">
    ✅ PASS: Flexbox Column A
  </div>
  <div style="flex: 1; min-width: 200px; background: rgba(56, 161, 105, 0.15); padding: 20px; border: 1px solid #38a169;">
    ✅ PASS: Flexbox Column B
  </div>
</div>

• If the columns sit side-by-side: You can use modern layouts.
• If the columns stack vertically on desktop: Your Canvas instance strips display: flex. You must fall back to basic block layouts.

4. Quick Reference: Safe Values

Use these values to ensure your components look professional and remain accessible in all modes.