>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588785. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Acquia Source's Mercury Drupal theme uses non-layered CSS that silently overrides every Tailwind responsive breakpoint utility (<code>md:</code>, <code>lg:</code>) in Canvas components. Components look correct in Storybook but are broken on the live site.</p> <p>This is a systemic cascade issue: every responsive Tailwind utility in every Canvas component deployed on a Mercury-themed Acquia Source site may be silently ignored. An agent building a two-column grid using <code>md:grid-cols-2</code> will upload the component, verify it in Storybook (where it works), and conclude it is correct &mdash; but on the live site it renders as a single column. The agent then spends iterations debugging "wrong grid count" or "wrong heading size" without realising the classes are present but overridden at the cascade level. In recorded sessions this pattern recurred from Q2 through Q4, totalling multiple debugging cycles per session. Heading font sizes, minimum heights, and border utilities were all separately hit as isolated bugs before the systemic root cause was identified.</p> <p>How it manifests: <code>md:grid-cols-2</code> has no effect &mdash; element stays single column on desktop. <code>md:min-h-[500px]</code> has no effect &mdash; element uses default height. <code>md:text-[3rem]</code> has no effect &mdash; heading stays at mobile size. All work correctly in Storybook but fail on the live Mercury-themed site.</p> <p>Root cause: Acquia Source uses the Mercury Drupal theme which ships a base CSS stylesheet using non-layered CSS rules. Canvas components output Tailwind utilities wrapped in CSS <code>@layer</code> declarations. Per the CSS cascade specification, non-layered CSS always wins over layered CSS regardless of selector specificity. Mercury's base rules for <code>h2</code>, <code>h3</code>, grid defaults, and min-heights beat any Tailwind utility in a Canvas component. The bug is invisible in Storybook because Storybook runs without the Mercury stylesheet.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Build a Canvas component using a Tailwind responsive utility (e.g., <code>md:grid-cols-2</code> or <code>md:min-h-[500px]</code>).</li> <li>Verify in Storybook at the <code>md:</code> breakpoint &mdash; it renders correctly.</li> <li>Upload via <code>canvas:upload</code>.</li> <li>View on the live Acquia Source site (Mercury theme) at the same viewport width.</li> <li>Observe: the responsive utility has no visible effect.</li> <li>Inspect computed styles in DevTools: the Tailwind class is present in the class list, but a Mercury rule of equal-or-lower specificity wins because it is non-layered.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Document the gotcha in <code>.claude/agents/component-builder.md</code>, the <code>component-authoring</code> skill, and <code>docs/migration/gotchas.md</code>. No platform code change is proposed &mdash; this is a Mercury cascade reality that the agent must work around with <code>!important</code> mirrors.</p> <p><strong>Step 1 &mdash; Add a "MERCURY THEME AWARENESS" block to <code>.claude/agents/component-builder.md</code></strong> immediately after the existing Canvas hard rules. Include: the cascade explanation (non-layered beats layered), the list of classes most likely affected (<code>md:*</code>, <code>lg:*</code>, heading font sizes, border utilities), the 3-step post-upload audit (test each category, add <code>!important</code> mirror if failing), and a concrete <code>global.css</code> <code>@media</code> template block.</p> <p><strong>Step 2 &mdash; Add the workaround CSS template verbatim:</strong></p> <pre>@media (min-width: 768px) { .md\:min-h-\[500px\] { min-height: 500px !important; } .md\:grid-cols-2 { grid-template-columns: repeat(2, 1fr) !important; } }</pre><p>Note the escaped backslashes &mdash; these are required for Tailwind JIT class names in standard CSS.</p> <p><strong>Step 3 &mdash; Add a one-line entry to <code>docs/migration/gotchas.md</code></strong> so it survives compaction: "Mercury theme (Acquia Source) overrides Tailwind <code>md:</code> utilities silently. Fix: <code>!important</code> mirrors in <code>global.css</code> @media blocks. See component-builder.md &sect; Mercury Theme Awareness."</p> <p><strong>Step 4 &mdash; Mirror the warning</strong> in the <code>component-authoring</code> skill SKILL.md under "Acquia Source deployment considerations".</p> <p>Verbatim recommended block (from skill recommendations): "Acquia Source uses the Mercury Drupal theme. Mercury's CSS is non-layered and beats Canvas's layered Tailwind output in the CSS cascade. AFTER first upload and visual check: 1. Test all responsive utilities (<code>md:</code>, <code>lg:</code>) &mdash; if they don't apply, add <code>!important</code> mirrors to global.css 2. Test all heading font sizes &mdash; Mercury resets these; add explicit <code>!important</code> rules 3. Test all border utilities &mdash; Mercury may override."</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the Mercury Theme Awareness block to <code>.claude/agents/component-builder.md</code>.</li> <li>Add the same warning to <code>.claude/skills/component-authoring/SKILL.md</code> (or equivalent &mdash; confirm canonical filename).</li> <li>Add the gotchas.md entry.</li> <li>Verify on a Mercury-themed Acquia Source site: a component using <code>md:grid-cols-2</code> renders as two columns at <code>md:</code> breakpoint after applying the <code>!important</code> mirror.</li> <li><code>grep -n "Mercury" .claude/agents/component-builder.md</code> returns at least one hit.</li> <li><code>grep -n "important" .claude/agents/component-builder.md</code> returns the <code>@media</code> template block.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None directly. Indirectly: components that ship correct <code>!important</code> mirrors will render correctly on Mercury-themed sites.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None. New documentation only &mdash; agent file rule block and gotchas.md entry.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-5-Drupal-Canvas-Gotchas/01-P1-5-mercury-theme-overrides-tailwind-md.md</code> (id: P1-5)</li> <li>Gotcha catalog: <code>RESEARCH-2026-04-28/07-cross-cutting/acquia-cms-gotchas.md</code> &sect; G11 (full verbatim entry, workaround CSS example)</li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P1-5</li> <li>Q2 discovery: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q2-records-2884-to-5768/issues-found.md</code> ISSUE-3, ISSUE-7</li> <li>Q3 recurrence: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q3-records-5768-to-8651/issues-found.md</code> Issue #13</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> &sect; component-builder.md / Mercury Theme Override Pattern</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is <code>component-authoring</code> a separate skill file from <code>component-builder.md</code>? Confirm which file the implementer should target &mdash; the agent prompt file takes priority over the skill SKILL.md for per-turn instruction.</li> <li>Does the current <code>global.css</code> in the jamie-demo project already have any Mercury overrides? If so, the gotcha entry should reference the existing file as a template.</li> </ul>