@supersoniks/concorde 5.0.3 → 5.0.5

package/docs/crawl/core/components/ui/tooltip/tooltip.html

@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Tooltip — Concorde</title>
-  <meta name="description" content="By default, tooltip is centered next to its content">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component">
+  <meta name="description" content="Tooltip shows a short label on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default placement is top (center-aligned). A">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component, label, placement, top, disabled, bottom, left, right, -start">
   <meta name="concorde-doc-id" content="core/components/ui/tooltip/tooltip">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html">
 </head>
@@ -15,63 +15,124 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Tooltip</strong>. By default, tooltip is centered next to its content <span>Doc ID: <code>core/components/ui/tooltip/tooltip</code>. Keywords: Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html">https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Tooltip</strong>. Tooltip shows a short label on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default placement is top (center-aligned). A <span>Doc ID: <code>core/components/ui/tooltip/tooltip</code>. Keywords: Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component, label, placement, top, disabled, bottom, left, right, -start. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html">https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html</a>.</span></p>
       <h1 id="tooltip">Tooltip</h1>
-<pre><code>&lt;sonic-tooltip label=&quot;Tada : Text appears&quot;&gt;hover me&lt;/sonic-tooltip&gt;
+<p>Tooltip shows a short <strong><code>label</code></strong> on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default <strong><code>placement</code></strong> is <strong><code>top</code></strong> (center-aligned). An empty <strong><code>label</code></strong> hides the bubble the same way as <strong><code>disabled</code></strong>.</p>
+<h2 id="basic-example">Basic example</h2>
+<pre><code>&lt;sonic-tooltip label=&quot;Additional context on hover&quot;&gt;
+      &lt;sonic-button variant=&quot;outline&quot;&gt;Hover me&lt;/sonic-button&gt;
+    &lt;/sonic-tooltip&gt;
 </code></pre>
 <h2 id="placement">Placement</h2>
-<p>By default, tooltip is centered next to its content</p>
-<pre><code>&lt;sonic-tooltip placement=&quot;top&quot; label=&quot;Top text&quot;&gt;
-      &lt;sonic-button&gt;Top&lt;/sonic-button&gt;
-    &lt;/sonic-tooltip&gt;
-    &lt;sonic-tooltip placement=&quot;bottom&quot; label=&quot;Bottom text&quot;&gt;
-      &lt;sonic-button&gt;Bottom&lt;/sonic-button&gt;
-    &lt;/sonic-tooltip&gt;
-     &lt;sonic-tooltip placement=&quot;right&quot; label=&quot;Right text&quot;&gt;
-      &lt;sonic-button&gt;Right&lt;/sonic-button&gt;
-    &lt;/sonic-tooltip&gt;
-    &lt;sonic-tooltip placement=&quot;left&quot; label=&quot;Left text&quot;&gt;
-      &lt;sonic-button&gt;Left&lt;/sonic-button&gt;
-    &lt;/sonic-tooltip&gt;
+<p>Use <strong><code>top</code></strong> · <strong><code>bottom</code></strong> · <strong><code>left</code></strong> · <strong><code>right</code></strong> for the main axis. Add <strong><code>-start</code></strong> or <strong><code>-end</code></strong> to align the bubble along the anchor edge.</p>
+<pre><code>&lt;div class=&quot;flex flex-wrap gap-2&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;top&quot; label=&quot;Top&quot;&gt;
+        &lt;sonic-button&gt;Top&lt;/sonic-button&gt;
+      &lt;/sonic-tooltip&gt;
+      &lt;sonic-tooltip placement=&quot;bottom&quot; label=&quot;Bottom&quot;&gt;
+        &lt;sonic-button&gt;Bottom&lt;/sonic-button&gt;
+      &lt;/sonic-tooltip&gt;
+      &lt;sonic-tooltip placement=&quot;right&quot; label=&quot;Right&quot;&gt;
+        &lt;sonic-button&gt;Right&lt;/sonic-button&gt;
+      &lt;/sonic-tooltip&gt;
+      &lt;sonic-tooltip placement=&quot;left&quot; label=&quot;Left&quot;&gt;
+        &lt;sonic-button&gt;Left&lt;/sonic-button&gt;
+      &lt;/sonic-tooltip&gt;
+    &lt;/div&gt;
 </code></pre>
-<h2 id="more-placement">More placement</h2>
+<h3 id="aligned-placements">Aligned placements</h3>
 <pre><code>&lt;div class=&quot;flex gap-3 flex-wrap&quot;&gt;
-      &lt;sonic-tooltip placement=&quot;top-start&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;top-start&quot; label=&quot;Top start&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Top start&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;top-end&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;top-end&quot; label=&quot;Top end&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Top end&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;bottom-start&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;bottom-start&quot; label=&quot;Bottom start&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Bottom start&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;bottom-end&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;bottom-end&quot; label=&quot;Bottom end&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Bottom end&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;right-start&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;right-start&quot; label=&quot;Right start&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Right start&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;right-end&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;right-end&quot; label=&quot;Right end&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Right end&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;left-start&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;left-start&quot; label=&quot;Left start&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Left start&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
-      &lt;sonic-tooltip placement=&quot;left-end&quot; label=&quot;My tooltip&quot;&gt;
+      &lt;sonic-tooltip placement=&quot;left-end&quot; label=&quot;Left end&quot;&gt;
         &lt;sonic-button class=&quot;size-40 bg-neutral-200 rounded-lg&quot;&gt;Left end&lt;/sonic-button&gt;
       &lt;/sonic-tooltip&gt;
     &lt;/div&gt;
 </code></pre>
+<h2 id="label-formatting">Label formatting</h2>
+<p><strong><code>label</code></strong> supports line breaks (<code>\n</code> in markup or multiline text). Lines are trimmed; <strong><code>&amp;nbsp;</code></strong> is normalized to spaces. <strong><code>white-space: pre-line</code></strong> preserves breaks in the bubble (max width <strong>18rem</strong>).</p>
+<pre><code>&lt;sonic-tooltip label=&quot;First line&amp;#10;Second line&quot;&gt;
+      &lt;sonic-button variant=&quot;outline&quot;&gt;Multiline label&lt;/sonic-button&gt;
+    &lt;/sonic-tooltip&gt;
+</code></pre>
 <h2 id="focusable">Focusable</h2>
-<pre><code>&lt;sonic-tooltip focusable label=&quot;The Concorde made its first transatlantic crossing on September 26, 1973&quot;&gt;
-      &lt;sonic-icon library=&quot;iconoir&quot; name=&quot;chat-bubble-question&quot;&gt;&lt;/sonic-icon&gt; Focus or hover non interactive element 
+<p>On non-interactive triggers, set <strong><code>focusable</code></strong> so the host gets <strong><code>tabindex=&quot;0&quot;</code></strong> and the tooltip opens on keyboard focus as well as hover.</p>
+<pre><code>&lt;sonic-tooltip
+      focusable
+      label=&quot;The Concorde made its first transatlantic crossing on September 26, 1973&quot;
+    &gt;
+      &lt;sonic-icon library=&quot;iconoir&quot; name=&quot;chat-bubble-question&quot;&gt;&lt;/sonic-icon&gt;
+      Focus or hover this text
     &lt;/sonic-tooltip&gt;
 </code></pre>
 <h2 id="disabled">Disabled</h2>
-<pre><code>&lt;sonic-tooltip disabled label=&quot;Disabled text&quot;&gt;
+<pre><code>&lt;sonic-tooltip disabled label=&quot;Not shown&quot;&gt;
       &lt;sonic-button&gt;Tooltip disabled&lt;/sonic-button&gt;
     &lt;/sonic-tooltip&gt;
 </code></pre>
+<h2 id="accessibility">Accessibility</h2>
+<p>The bubble uses <strong><code>popover=&quot;hint&quot;</code></strong> (non-modal, no pointer capture). Prefer <strong><code>focusable</code></strong> when the slotted content is not already focusable. When the Popover API is unavailable, the host falls back to the native <strong><code>title</code></strong> attribute with a single-line label. Opacity transitions respect <strong><code>prefers-reduced-motion</code></strong>.</p>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>label</code></td>
+<td>string</td>
+<td>Tooltip copy; whitespace-only values suppress the bubble</td>
+</tr>
+<tr>
+<td><code>placement</code></td>
+<td><code>top</code> (default) · <code>bottom</code> · <code>left</code> · <code>right</code> · <code>top-start</code> · <code>top-end</code> · <code>bottom-start</code> · <code>bottom-end</code> · <code>left-start</code> · <code>left-end</code> · <code>right-start</code> · <code>right-end</code></td>
+<td>Position relative to the trigger; repositions while open</td>
+</tr>
+<tr>
+<td><code>disabled</code></td>
+<td>boolean</td>
+<td>Suppress show/hide; sets <strong><code>tabindex=&quot;-1&quot;</code></strong> on the host</td>
+</tr>
+<tr>
+<td><code>focusable</code></td>
+<td>boolean</td>
+<td>Add <strong><code>tabindex=&quot;0&quot;</code></strong> on the host for keyboard access</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Slot</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(default)</em></td>
+<td>Trigger content (hover target)</td>
+</tr>
+</tbody></table>
 
     </article>
   </main>

package/docs/crawl/docs/_decorators/ancestor-attribute.html

@@ -66,10 +66,11 @@ export class DemoAncestorAttribute extends LitElement {
 <li>By default (<code>dynamic: false</code>), the value is read once at connect time and is not updated afterward</li>
 <li>With <code>{ dynamic: true }</code>, the property stays in sync when:<ul>
 <li>an ancestor <strong>changes</strong> the attribute value</li>
-<li>a <strong>closer</strong> ancestor <strong>gains</strong> the attribute (that value wins)</li>
-<li>the <strong>nearest</strong> ancestor <strong>loses</strong> the attribute (falls back to the next one up, or <code>null</code>)</li>
+<li>a <strong>closer</strong> ancestor <strong>gains</strong> / <strong>loses</strong> the attribute (fallback / <code>null</code>)</li>
+<li>the component is <strong>reparented</strong> (no extra opt-in) — parent <code>childList</code> only reacts if <em>this</em> node moves</li>
 </ul>
 </li>
+<li>Observers are <strong>shared</strong> (one per ancestor attribute / one per parent) so large lists of <code>sonic-icon</code> stay cheap on Firefox.</li>
 <li>When <code>dynamic</code> is enabled, updates also propagate to <code>@subscribe</code> / <code>@bind</code> paths that depend on the decorated property (e.g. <code>${dataProvider}</code>)</li>
 </ul>
 <h3 id="dynamic-mode">Dynamic mode</h3>

package/docs/crawl/docs/_getting-started/start.html

@@ -18,7 +18,7 @@
       <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Introduction</strong>. Based on lit.dev, Concorde is a collection of web components for shared apps and websites. <span>Doc ID: <code>docs/_getting-started/start</code>. Keywords: Concorde, supersoniks, docs/_getting-started/start, start, Introduction, guide, get, set, formDataProvider, @ancestorAttribute, @bind, serviceURL, yarn ai:sync, AGENTS.md. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/start.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/start.html</a>.</span></p>
       <h1 id="introduction">Introduction</h1>
 <h2 id="what-is-concorde">What is Concorde?</h2>
-<p>Based on <strong><a href="https://lit.dev">lit.dev</a></strong>, Concorde is a collection of web components for shared apps and websites.<br>Build UIs without tying components to a specific host stack, while keeping visual consistency through a small set of CSS variables.</p>
+<p>Based on <strong><a href="https://lit.dev">lit.dev</a></strong>, Concorde is a collection of web components for shared apps and websites.<br>Build UIs without tying components to a specific host stack, while keeping visual consistency through the smallest set of CSS variables needed to define a theme.</p>
 <h2 id="why-and-use-case">Why and use case</h2>
 <p>In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.<br>One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.</p>
 <h3 id="stack">Stack</h3>

package/docs/crawl/docs/_getting-started/theming.html

@@ -3,9 +3,9 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Adding styles — Concorde</title>
-  <meta name="description" content="No style crosses the shadow root of a component, except for inheritable properties (which have the &quot;inherit&quot; property possible) and CSS variables.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/_getting-started/theming, theming, Adding styles, guide, , size, {reflect: true}, :host(), :host([type='primary']){...}, inline, block, display, contents">
+  <title>Customization — Concorde</title>
+  <meta name="description" content="Concorde components ship with default styles (fallback values in each component and in &lt;sonic-theme&gt;).">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_getting-started/theming, theming, Customization, guide, , :root, theme=&quot;custom&quot;, --sc-*, theme=&quot;light&quot;, &quot;dark&quot;, &quot;auto&quot;, auto, prefers-color-scheme">
   <meta name="concorde-doc-id" content="docs/_getting-started/theming">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html">
 </head>
@@ -15,69 +15,317 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Adding styles</strong>. No style crosses the shadow root of a component, except for inheritable properties (which have the &quot;inherit&quot; property possible) and CSS variables. <span>Doc ID: <code>docs/_getting-started/theming</code>. Keywords: Concorde, supersoniks, docs/_getting-started/theming, theming, Adding styles, guide, , size, {reflect: true}, :host(), :host([type='primary']){...}, inline, block, display, contents. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html</a>.</span></p>
-      <h1 id="adding-styles">Adding styles</h1>
-<h2 id="normal-behavior">Normal Behavior</h2>
-<p>No style crosses the shadow root of a component, except for inheritable properties (which have the &quot;inherit&quot; property possible) and CSS variables.
-Properties integrated via a &quot;<a href="https://developer.mozilla.org/en/docs/Web/HTML/Element/slot">slot</a>&quot; remain stylizable in a conventional way.</p>
-<ul>
-<li><strong>During creation / from the inside:</strong><ul>
-<li>We edit the <a href="https://lit.dev/docs/components/styles/">static &quot;styles&quot; property of the lit component</a>, which can also reference shared and dynamic styles.
-These styles are scoped and do not impact the outside.</li>
-<li>We use CSS variables as the value of properties intended to be customized from the outside.
-For each variable, we define a default value to have a simple but consistent base style.</li>
-<li>We only rewrite inheritable properties with hard values if they are truly specific to the component.</li>
-<li>The <code>&lt;style&gt;</code> tag as a direct child can be used as a last resort, especially if there is a need for particularly dynamic customization. Performance is reduced.</li>
-</ul>
-</li>
-<li><strong>During use / from the outside:</strong>
-We define values for <strong>inheritable CSS properties</strong> (e.g., font-_, color...) using tools like Tailwind.
-We modify the value of <strong>CSS variables</strong> used by the component.</li>
-</ul>
-<h2 id="choosing-style-presets-via-reactive-properties">Choosing Style Presets via Reactive Properties:</h2>
-<p>The declaration of reactive properties is useful for selecting a particular configuration that mostly affects a set of properties.</p>
-<p>For example, a <code>size</code> property (xs, sm, md, xl) will affect margins, font, line heights to align them with the corresponding CSS vars, which can be customized using the methods mentioned earlier if necessary.</p>
-<p>It is recommended to use the <code>{reflect: true}</code> property for reactive properties that have an associated style on the <code>:host()</code>. For example: <code>:host([type=&#39;primary&#39;]){...}</code></p>
-<p>☢️ <strong>Caution:</strong> Passing class names via reactive properties / HTML attributes of the component should be avoided as it can quickly lead to difficult-to-manage situations.</p>
-<h4 id="css-display-property">CSS &quot;display&quot; Property</h4>
-<p>By default, the display property is <code>inline</code>.
-Therefore, be careful to define it according to the needs, as one might mistakenly expect it to be <code>block</code> as with a regular <code>&lt;div&gt;</code>.</p>
-<p>☢️ <strong>Caution:</strong> Defining the <code>display</code> property as <code>contents</code> may seem attractive at first, but:</p>
-<ul>
-<li>It almost always leads to the creation of wrappers to style the content (instead of using <code>:host</code>).</li>
-<li>It is no longer possible to directly add classes to the component or style it from the outside.
-Ultimately, the amount of code to write increases significantly.</li>
-</ul>
-<h2 id="tailwind-functional-classes">TAILWIND Functional Classes</h2>
-<p><a href="https://tailwindcss.com/">tailwind</a> has been integrated into Concorde and is available in scoped components (with Shadow DOM).
-To use it, you need to import the following:</p>
-<pre><code class="language-javascript">import { tailwind } from &quot;@supersoniks/concorde/la-billetterie/ui/theme/theme&quot;;
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Customization</strong>. Concorde components ship with default styles (fallback values in each component and in &lt;sonic-theme&gt;). <span>Doc ID: <code>docs/_getting-started/theming</code>. Keywords: Concorde, supersoniks, docs/_getting-started/theming, theming, Customization, guide, , :root, theme=&quot;custom&quot;, --sc-*, theme=&quot;light&quot;, &quot;dark&quot;, &quot;auto&quot;, auto, prefers-color-scheme. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html</a>.</span></p>
+      <h1 id="customization">Customization</h1>
+<h2 id="theme-first-customization">Theme-first customization</h2>
+<p>Concorde components ship with <strong>default styles</strong> (fallback values in each component and in <code>&lt;sonic-theme&gt;</code>).<br>You do not need to define any CSS variables to get a usable UI.</p>
+<p>To align the kit with your brand, override <strong>only the essential theme tokens</strong> on <code>&lt;sonic-theme&gt;</code>, on <code>:root</code>, or in a project stylesheet.<br>Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—<strong>do not copy long lists of derived variables</strong> unless you have a specific need.</p>
+<pre><code class="language-html">&lt;sonic-theme color font class=&quot;block bg-base min-h-screen&quot;&gt;
+  &lt;!-- your app --&gt;
+&lt;/sonic-theme&gt;
 </code></pre>
-<p>Then include the <code>tailwind</code> style in the static <code>styles</code> property of the component:</p>
-<pre><code class="language-javascript">static styles = [tailwind];
+<pre><code class="language-javascript">import &quot;@supersoniks/concorde/theme&quot;;
 </code></pre>
-<p>Finally, use it in the HTML within the render function:</p>
-<pre><code class="language-html">&lt;p class=&quot;m-2&quot;&gt;A paragraph with margin&lt;/p&gt;
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(omit)</em> | <code>theme=&quot;custom&quot;</code></td>
+<td>Default: core tokens + your <code>--sc-*</code>; no built-in light/dark palette</td>
+</tr>
+<tr>
+<td><code>theme=&quot;light&quot;</code> | <code>&quot;dark&quot;</code> | <code>&quot;auto&quot;</code></td>
+<td>Opt-in presets; <code>auto</code> follows <code>prefers-color-scheme</code></td>
+</tr>
+<tr>
+<td><code>class=&quot;bg-base block&quot;</code> (Tailwind)</td>
+<td>Page/surface background (<code>--sc-base</code>)</td>
+</tr>
+<tr>
+<td><code>color</code></td>
+<td>Text color (<code>--sc-base-content</code>)</td>
+</tr>
+<tr>
+<td><code>font</code></td>
+<td>Base font family/weight (<code>--sc-font-family-base</code>, etc.)</td>
+</tr>
+</tbody></table>
+<p>Popovers, modals, and toasts mount under the nearest <code>&lt;sonic-theme&gt;</code>.</p>
+<h2 id="customization-example">Customization example</h2>
+<p>Example (full brand override on <code>&lt;sonic-theme&gt;</code> or <code>:root</code>). Set every essential token below; derived radii and shadows still come from the theme engine—only <code>--sc-rounded</code> is listed here.</p>
+<pre><code class="language-css">sonic-theme {
+  /* Semantic fills */
+  --sc-primary: #353429;
+  --sc-secondary: #f43f5e;
+  --sc-info: #7c3aed;
+  --sc-danger: #d71839;
+  --sc-warning: #f97316;
+  --sc-success: #10b981;
+  --sc-contrast: #111;
+
+  /* Text/icons on semantic fills */
+  --sc-primary-content: #fff;
+  --sc-secondary-content: #fff;
+  --sc-info-content: #fff;
+  --sc-danger-content: #fff;
+  --sc-warning-content: #fff;
+  --sc-success-content: #fff;
+  --sc-contrast-content: #fff;
+
+  /* Neutral fills */
+  --sc-base: #fff;
+  --sc-base-50: #f6f6f5;
+  --sc-base-100: #ededec;
+  --sc-base-200: #d7d7d4;
+  --sc-base-300: #c8c7c4;
+  --sc-base-400: #a8a7a2;
+  --sc-base-500: #94938c;
+  --sc-base-600: #76756c;
+  --sc-base-700: #59584e;
+  --sc-base-800: #47463b;
+  --sc-base-900: #353429;
+
+  /* Text/icons on neutral surfaces */
+  --sc-base-content: var(--sc-base-900);
+
+  /* Typography */
+  --sc-font-family-base: &quot;Oswald&quot;, system-ui, -apple-system, &quot;Segoe UI&quot;, Roboto,
+    &quot;Helvetica Neue&quot;, Arial, sans-serif;
+  --sc-headings-font-family: &quot;alternate-gothic-compressed&quot;, system-ui, sans-serif;
+  --sc-headings-line-height: 1.1;
+  --sc-headings-font-weight: bold;
+  --sc-headings-text-transform: none;
+
+  /* Shape (primitive only) */
+  --sc-rounded: 0;
+
+  /* Forms */
+  --sc-border-width: 0.2rem;
+  --sc-form-height: 2em;
+  --sc-input-bg: var(--sc-base);
+  --sc-input-color: var(--sc-base-content);
+  --sc-input-border-color: var(--sc-input-color);
+  --sc-input-active-bg: var(--sc-primary);
+  --sc-input-active-color: var(--sc-primary-content);
+  --sc-input-active-border-color: var(--sc-primary);
+}
+</code></pre>
+<p><sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button></p>
+<p><strong>Without these overrides</strong>, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set <code>theme=&quot;light&quot;</code>, <code>theme=&quot;dark&quot;</code>, or <code>theme=&quot;auto&quot;</code>.</p>
+<p><strong>What we intentionally avoid:</strong> large public <code>--sc-alert-*</code> / <code>--sc-badge-*</code> APIs or <code>::part()</code> styling hooks on most components. Prefer attributes (<code>type</code>, <code>status</code>, <code>size</code>, …) and the theme tokens above.</p>
+<h2 id="only-essential-css-variables-public-theme-api">Only essential CSS variables (public theme API)</h2>
+<p>These are the <strong>smallest set</strong> we recommend customizing. Everything else should stay internal to the theme or to components (<code>--sc_*</code> private variables, attributes like <code>type</code>, <code>size</code>, <code>variant</code>).</p>
+<h3 id="surfaces-and-foreground">Surfaces and foreground</h3>
+<p>Tokens <strong>without</strong> a <code>-content</code> suffix are <strong>fill / background</strong> colors.<br>Tokens <strong>with</strong> <code>-content</code> are <strong>text and icons</strong> on top of the matching fill (solid buttons, badges, alerts, etc.).</p>
+<h4 id="neutral-fills">Neutral fills</h4>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-base</code></td>
+<td>Main surface / page background</td>
+</tr>
+<tr>
+<td><code>--sc-base-50</code> … <code>--sc-base-900</code></td>
+<td>Neutral scale (borders, subtle backgrounds, muted UI)</td>
+</tr>
+</tbody></table>
+<h4 id="neutral-foreground">Neutral foreground</h4>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-base-content</code></td>
+<td>Default body text and icons on neutral surfaces</td>
+</tr>
+</tbody></table>
+<h4 id="semantic-fills">Semantic fills</h4>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-primary</code></td>
+<td>Primary actions, links, emphasis</td>
+</tr>
+<tr>
+<td><code>--sc-secondary</code></td>
+<td>Secondary brand accent (when used)</td>
+</tr>
+<tr>
+<td><code>--sc-info</code>, <code>--sc-success</code>, <code>--sc-warning</code>, <code>--sc-danger</code></td>
+<td>Status and feedback</td>
+</tr>
+<tr>
+<td><code>--sc-contrast</code></td>
+<td>High-contrast fills (e.g. on media)</td>
+</tr>
+</tbody></table>
+<h4 id="semantic-foreground">Semantic foreground</h4>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-primary-content</code>, <code>--sc-secondary-content</code>, …</td>
+<td>Text/icons on the matching semantic <strong>fill</strong> (<code>--sc-primary</code>, etc.)</td>
+</tr>
+</tbody></table>
+<h3 id="shape">Shape</h3>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-rounded</code></td>
+<td><strong>Single primitive</strong> corner radius; the theme computes <code>--sc-rounded-sm</code>, <code>--sc-btn-rounded</code>, <code>--sc-input-rounded</code>, etc.</td>
+</tr>
+</tbody></table>
+<h3 id="typography">Typography</h3>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-font-family-base</code></td>
+<td>Body UI text</td>
+</tr>
+<tr>
+<td><code>--sc-font-weight-base</code>, <code>--sc-font-style-base</code></td>
+<td>Optional</td>
+</tr>
+<tr>
+<td><code>--sc-headings-font-family</code>, <code>--sc-headings-line-height</code>, <code>--sc-headings-font-weight</code>, <code>--sc-headings-text-transform</code></td>
+<td>Headings (modal titles, etc.)</td>
+</tr>
+</tbody></table>
+<h3 id="forms-only-if-you-customize-inputs-globally">Forms (only if you customize inputs globally)</h3>
+<p>Interactive controls expose a few extra <strong>theme-level</strong> tokens; prefer these over styling individual inputs from outside.</p>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sc-border-width</code></td>
+<td>Default border thickness</td>
+</tr>
+<tr>
+<td><code>--sc-form-height</code></td>
+<td>Control height</td>
+</tr>
+<tr>
+<td><code>--sc-input-bg</code>, <code>--sc-input-color</code>, <code>--sc-input-border-color</code></td>
+<td>Default field chrome</td>
+</tr>
+<tr>
+<td><code>--sc-input-active-bg</code>, <code>--sc-input-active-color</code>, <code>--sc-input-active-border-color</code></td>
+<td>Focus/active state</td>
+</tr>
+</tbody></table>
+<hr>
+<h2 id="tailwind-in-new-components-">Tailwind in new components ?</h2>
+<p>Set <code>tailwind.config.js</code> to match concorde style token in your custom component.</p>
+<pre><code class="language-js">...
+theme: {
+  borderRadius: {
+    DEFAULT: &quot;var(--sc-rounded)&quot;,
+    none: &quot;0&quot;,
+    sm: &quot;var(--sc-rounded-sm)&quot;,
+    md: &quot;var(--sc-rounded-md)&quot;,
+    lg: &quot;var(--sc-rounded-lg)&quot;,
+    xl: &quot;var(--sc-rounded-xl)&quot;,
+    full: &quot;9999px&quot;,
+  },
+  boxShadow: {
+    DEFAULT: &quot;var(--sc-shadow)&quot;,
+    none: &quot;none&quot;,
+    sm: &quot;var(--sc-shadow-sm)&quot;,
+    md: &quot;var(--sc-shadow-md)&quot;,
+    lg: &quot;var(--sc-shadow-lg)&quot;,
+    xl: &quot;var(--sc-shadow-xl)&quot;,
+  },
+  colors: {
+    transparent: &quot;transparent&quot;,
+    current: &quot;currentColor&quot;,
+    content: &quot;var(--sc-base-content)&quot;,
+    base: &quot;var(--sc-base)&quot;,
+    neutral: {
+      0: &quot;var(--sc-base)&quot;,
+      50: &quot;var(--sc-base-50)&quot;,
+      100: &quot;var(--sc-base-100)&quot;,
+      200: &quot;var(--sc-base-200)&quot;,
+      300: &quot;var(--sc-base-300)&quot;,
+      400: &quot;var(--sc-base-400)&quot;,
+      500: &quot;var(--sc-base-500)&quot;,
+      600: &quot;var(--sc-base-600)&quot;,
+      700: &quot;var(--sc-base-700)&quot;,
+      800: &quot;var(--sc-base-800)&quot;,
+      900: &quot;var(--sc-base-900)&quot;,
+      content: &quot;var(--sc-base)&quot;,
+    },
+    primary: {
+      DEFAULT: &quot;var(--sc-primary)&quot;,
+      content: &quot;var(--sc-primary-content)&quot;,
+    },
+    success: {
+      DEFAULT: &quot;var(--sc-success)&quot;,
+      content: &quot;var(--sc-success-content)&quot;,
+    },
+    danger: {
+      DEFAULT: &quot;var(--sc-danger)&quot;,
+      content: &quot;var(--sc-danger-content)&quot;,
+    },
+    warning: {
+      DEFAULT: &quot;var(--sc-warning)&quot;,
+      content: &quot;var(--sc-warning-content)&quot;,
+    },
+    info: {
+      DEFAULT: &quot;var(--sc-info)&quot;,
+      content: &quot;var(--sc-info-content)&quot;,
+    },
+    contrast: {
+      DEFAULT: &quot;var(--sc-contrast)&quot;,
+      content: &quot;var(--sc-contrast-content)&quot;,
+    },
+  },
+  extend: {
+    borderWidth: {
+      DEFAULT: &quot;var(--sc-border-width)&quot;,
+    },
+    fontFamily: {
+      headings: [&quot;var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))&quot;],
+      body: [&quot;var(--sc-font-family-base)&quot;],
+      monospace: [&quot;var(--sc-font-family-monospace, monospace)&quot;],
+    }
+  }
 </code></pre>
-<p>The colors from Concorde&#39;s theme are referenced in Tailwind&#39;s theme.</p>
-<h2 id="operation-without-shadow-dom">Operation without Shadow DOM</h2>
-<h3 id="usefulness">Usefulness</h3>
-<p>This operation is particularly useful when it comes to <strong>adding behavior to a simple existing element</strong>.
-It may also become necessary to establish <strong>compatibility with a traditional JS library</strong>.</p>
-<p>For example, with a text input:</p>
-<ul>
-<li>Trigger automatic data or filter update when typing text.</li>
-<li>Automatic formatting.</li>
-<li>Constraints that cannot be handled by native methods.</li>
-</ul>
-<h3 id="consequences">Consequences</h3>
-<p>If there is no shadow DOM (see the <strong>noShadowDom</strong> property of <strong>Subscriber</strong>):</p>
-<ul>
-<li>Styling using the static &quot;styles&quot; property of the lit component will not be applied.</li>
-<li>The element and its content can be styled in a traditional manner.</li>
-</ul>
-<p>For example, the components <code>queue</code>, <code>list</code>, and <code>fetch</code> do not have a shadow DOM.</p>
-<p>ℹ️ <strong>Note:</strong> Specifically in this case, it may be useful to set the <code>display</code> property to <code>contents</code>.</p>
 
     </article>
   </main>