Create a shared UI component library within Drupal AI for AI core and AI contrib modules
>>> [!note] Migrated issue
<!-- Drupal.org comment -->
<!-- Migrated from issue #3567389. -->
Reported by: [afoster](https://www.drupal.org/user/594458)
>>>
<p>[Tracker]<br>
<strong>Update Summary: </strong>Specs proposed - Needs Review<br>
<strong>Short Description: </strong>Create shared UI component library (tooltips, icons, typography) for AI modules<br>
<strong>Check-in Date: </strong>01/13/2026<br>
<em>Metadata is used by the <a href="https://www.drupalstarforge.ai/" title="AI Tracker">AI Tracker.</a> Docs and additional fields <a href="https://www.drupalstarforge.ai/ai-dashboard/docs" title="AI Issue Tracker Documentation">here</a>.</em><br>
[/Tracker]</p>
<h2 id="tl-dr">TL;DR</h2>
<p><strong>We need a shared UI component library in the Drupal AI module</strong> because Gin/Claro don't provide essential UI elements (smart tooltips, external link icons, typography utilities) and multiple AI submodules are solving the same problems independently, leading to inconsistent implementations and duplicated effort.</p>
<p><strong>Proposed approach:</strong></p>
<ul>
<li>Use <code>ai-</code> CSS prefix with Drupal 11 core CSS variables</li>
<li>Tooltips: <strong>Decision needed</strong> — use Tooltip contrib, reference core's internal Floating UI, or bundle Floating UI directly</li>
<li>Source icons from Drupal CMS Design System, then Phosphor</li>
</ul>
<hr>
<h2 id="problem-motivation">Problem/Motivation</h2>
<p>As development progresses on the Drupal AI module, AI Dashboard, and related submodules, we are repeatedly encountering gaps in the existing Gin admin theme that force individual solutions for common UI needs. This leads to:</p>
<ul>
<li><strong>Inconsistent implementations</strong> across AI modules (e.g., AI Dashboard, AI settings page, Flowdrop UI)</li>
<li><strong>Duplicated effort</strong> as each submodule solves the same problems independently</li>
<li><strong>Potential theme conflicts</strong> when custom CSS classes collide with admin theme styles</li>
<li><strong>Maintenance burden</strong> as fixes need to be applied in multiple places</li>
</ul>
<p>During the UX working group meeting on 2025-01-12, we identified several common UI elements that are needed across multiple AI modules but are not adequately provided by the Gin theme:</p>
<h3 id="missing-ui-elements-identified">Missing UI Elements Identified</h3>
<ol>
<li>
<p><strong>Tooltips</strong> - Smart tooltips that handle positioning, wrapping, and don't disappear off-screen. Gin's existing tooltip (used in collapsed navigation) is limited to short single-word labels.</p>
</li>
<li>
<p><strong>External link (and other) icons</strong> - Consistent iconography for links to external resources (provider documentation, model info pages, etc.)</p>
</li>
<li>
<p><strong>Typography utilities</strong> - Small/extra-small text classes that don't rely on hijacking unrelated classes like <code>form-item__description</code></p>
</li>
<li>
<p><strong>Consistent iconography</strong> - A defined icon library source (Drupal CMS Design System, Phosphor) for AI-specific indicators (supported/unsupported capabilities, provider status, etc.)</p>
</li>
<li>
<p><strong>Table styling</strong> - Consistent column widths that don't shift when content changes dynamically via Ajax</p>
</li>
</ol>
<h2 id="proposed-resolution">Proposed Resolution</h2>
<p>Create a centralized UI component library within the Drupal AI module that:</p>
<ol>
<li><strong>Uses an <code>ai-</code> CSS prefix</strong> for all custom classes to prevent conflicts with Gin, Claro, or other admin themes</li>
<li><strong>Leverages Drupal 11 core CSS variables</strong> (e.g., <code>--font-size-xs</code>, <code>--font-size-s</code>, <code>--color-text-light</code>) within AI-prefixed classes for theme consistency</li>
<li><strong>Includes tooltip functionality</strong> — approach TBD (see decision table below)</li>
<li><strong>Defines icon source hierarchy</strong>: Drupal CMS Design System icons first, Phosphor icons second</li>
<li><strong>Provides shared CSS and JavaScript</strong> that AI submodules can depend on</li>
</ol>
<h3 id="tooltip-approach-decision-needed">Tooltip Approach — Decision Needed</h3>
<p>⚠️ <strong>Note:</strong> Tippy.js was archived November 2024 and should not be used.</p>
<p>Floating UI (the successor to Popper.js) is in Drupal Core but is currently marked as an <strong>internal library</strong>, meaning it's not officially supported for contrib use and could change without notice.</p>
<p><strong>Options to discuss:</strong></p>
<table>
<thead>
<tr>
<th>Option</th>
<th>Approach</th>
<th>Pros</th>
<th>Cons</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>A</strong></td>
<td>Use <a href="https://www.drupal.org/project/tooltip">Tooltip contrib module</a></td>
<td>Community-maintained; abstracts positioning library</td>
<td>Adds contrib dependency; maturity needs evaluation</td>
</tr>
<tr>
<td><strong>B</strong></td>
<td>Reference core's internal Floating UI library directly</td>
<td>No additional dependencies; already in core</td>
<td>Internal API - could break; not officially supported</td>
</tr>
<tr>
<td><strong>C</strong></td>
<td>Bundle Floating UI directly (like Webform does with Popper.js)</td>
<td>Full control; stable</td>
<td>Maintenance burden; duplicates code in core</td>
</tr>
</tbody>
</table>
<p><strong>Recommendation:</strong> Discuss with AI module maintainers. Option A (Tooltip contrib) is safest. If the AI initiative has influence, we could also advocate for Floating UI to become a public core library (<a href="https://www.drupal.org/project/drupal/issues/3197758">#3197758</a>).</p>
<h3 id="css-architecture">CSS Architecture</h3>
<p>The AI module should use <strong>Drupal 11 core CSS variables</strong> (defined in <code>core/themes/claro/css/base/variables.pcss.css</code>) rather than Gin-specific variables. This ensures compatibility across admin themes (Claro, Gin, etc.).</p>
<p><strong>Key Drupal 11 Core CSS Variables:</strong></p>
<table>
<thead>
<tr>
<th>Category</th>
<th>Variable</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Typography</strong></td>
<td><code>--font-size-base</code></td>
<td>1rem (~16px)</td>
</tr>
<tr>
<td></td>
<td><code>--font-size-s</code></td>
<td>0.889rem (~14px)</td>
</tr>
<tr>
<td></td>
<td><code>--font-size-xs</code></td>
<td>0.79rem (~13px)</td>
</tr>
<tr>
<td></td>
<td><code>--font-size-xxs</code></td>
<td>0.702rem (~11px)</td>
</tr>
<tr>
<td></td>
<td><code>--font-size-description</code></td>
<td>var(--font-size-xs)</td>
</tr>
<tr>
<td></td>
<td><code>--font-size-label</code></td>
<td>var(--font-size-s)</td>
</tr>
<tr>
<td><strong>Colors</strong></td>
<td><code>--color-text</code></td>
<td>var(--color-gray)</td>
</tr>
<tr>
<td></td>
<td><code>--color-text-light</code></td>
<td>var(--color-gray-500)</td>
</tr>
<tr>
<td></td>
<td><code>--color-link</code></td>
<td>var(--color-absolutezero)</td>
</tr>
<tr>
<td></td>
<td><code>--input-fg-color--description</code></td>
<td>var(--color-gray-800)</td>
</tr>
<tr>
<td><strong>Spacing</strong></td>
<td><code>--space-xs</code></td>
<td>0.5rem (8px)</td>
</tr>
<tr>
<td></td>
<td><code>--space-s</code></td>
<td>0.75rem (12px)</td>
</tr>
<tr>
<td></td>
<td><code>--space-m</code></td>
<td>1rem (16px)</td>
</tr>
<tr>
<td></td>
<td><code>--space-l</code></td>
<td>1.5rem (24px)</td>
</tr>
</tbody>
</table>
<pre>
<pre><pre>.ai-tooltip-content {<br> padding: var(--space-xs) var(--space-s);<br> font-size: var(--font-size-xs); /* ~13px */<br>}</pre></pre></pre><p><strong>Reference:</strong> <a href="https://api.drupal.org/api/drupal/core!themes!claro!css!base!variables.pcss.css/11.x">https://api.drupal.org/api/drupal/core!themes!claro!css!base!variables.pcss.css/11.x</a></p>
<h3 id="file-organization">File Organization</h3>
<pre><pre>ai/<br>├── assets/<br>│ ├── css/<br>│ │ └── ai-<span class="hljs-keyword">global</span>.css <span class="hljs-comment"># Shared AI UI styles</span><br>│ └── js/<br>│ └── ai-<span class="hljs-keyword">global</span>.js <span class="hljs-comment"># Shared AI UI behaviors (tooltip integration, etc.)</span></pre></pre><h2 id="remaining-decisions-needed">Remaining Decisions Needed</h2>
<ul>
<li>[ ] <strong>Tooltip library approach</strong> — Choose between Options A, B, or C above</li>
<li>[ ] Finalize icon library selection (Drupal CMS Design System vs. Phosphor)</li>
<li>[ ] Determine if this should live in AI core module or a separate <code>ai_ui</code> submodule</li>
<li>[ ] Review licensing for any external libraries</li>
</ul>
<h2 id="meeting-context">Meeting Context</h2>
<p>This issue was identified during the Drupal AI UX working group call on 2025-01-12. Participants included Aidan Foster, Bruno, Emma Horrell, Jamie Abrahams, and Sahil Sharma.</p>
<p>Key discussion points:</p>
<ul>
<li>Bruno confirmed AI Dashboard had to add external icons independently</li>
<li>Aidan demonstrated the AI settings page redesign which needs tooltips</li>
<li>Emma noted tooltips are an "interim solution to terminology" - providing explanatory context for AI concepts</li>
<li>Bruno suggested tooltips are useful "overall...everywhere" not just for AI</li>
<li>Jamie mentioned prior discussions at Pune about a "stripped-down design system" for admin elements, but it isn't available yet.</li>
</ul>
<h3 id="resources-referenced">Resources Referenced</h3>
<ul>
<li><strong>Drupal CMS Design System (Figma):</strong> <a href="https://www.figma.com/design/IQNqQnxkUiFjp5GSp9E3nV/Design-System---Drupal-CMS?node-id=2349-2606">https://www.figma.com/design/IQNqQnxkUiFjp5GSp9E3nV/Design-System---Drupal-CMS?node-id=2349-2606</a></li>
<li><strong>Floating UI:</strong> <a href="https://floating-ui.com/">https://floating-ui.com/</a></li>
<li><strong>Core issue Floating UI Tool tips:</strong> <a href="https://www.drupal.org/project/drupal/issues/3197758">https://www.drupal.org/project/drupal/issues/3197758</a></li>
<li><strong>Tooltip contrib module:</strong> <a href="https://www.drupal.org/project/tooltip">https://www.drupal.org/project/tooltip</a></li>
<li><strong>Phosphor Icons:</strong> <a href="https://phosphoricons.com/">https://phosphoricons.com/</a></li>
<li><del><strong>Tippy.js:</strong> <a href="https://atomiks.github.io/tippyjs/">https://atomiks.github.io/tippyjs/</a></del> <em>(Archived November 2024 - do not use)</em></li>
</ul>
issue