infaira-canvas 0.1.9

package/templates/ICan-Widget-Styling-Patterns.md

@@ -0,0 +1,890 @@
+# ICan Widget Styling Patterns
+
+> **Read this before you write a single line of widget CSS.**
+> This guide explains the four ways to style an ICan widget, what theme support you get with each, and the gotchas to know about. It complements [`ICan-Widget-Theming-Guide.md`](./ICan-Widget-Theming-Guide.md) (the exhaustive variable reference) — this file is about *decisions and concepts*, not variable lookups.
+
+---
+
+## 1. Purpose & how to use this doc
+
+When you build an ICan widget, you have to choose *how much* of the ICan design system to adopt. There are four reasonable approaches. Each has different theme behavior and different gotchas. This doc walks you through them so you can pick the right one for your widget — and so an AI coding agent helping you can pick correctly without trial and error.
+
+If you're an AI agent, jump to **section 10** first.
+
+---
+
+## 2. TL;DR — decision tree
+
+Ask yourself three questions in order:
+
+1. **Do I want my widget to retint when the user switches theme?**
+   - **Yes** → use `var(--ican-*)` for every color. Go to question 2.
+   - **No** → use whatever colors you want. You're done. Go to **Scenario 3**.
+
+2. **Do I need ICan's prebuilt components (Card, Button, DataTable, StatCard, Modal, etc.)?**
+   - **Yes** → import them from `'ican/components'`. Go to question 3.
+   - **No** → build everything yourself. Go to **Scenario 4**.
+
+3. **Are the prebuilt components enough, or do I want a more custom layout?**
+   - **They're enough** → **Scenario 1**.
+   - **I want custom layout but mixed with ICan components** → **Scenario 2** (but use vars in your wrappers if you want full theme support).
+
+| You want… | Pick |
+|---|---|
+| Standard widget that adapts to all 4 themes with minimum effort | **Scenario 1** |
+| ICan components but with a fixed branded "console" look | **Scenario 2** |
+| Standalone widget with a deliberate retro/specialized look that never changes | **Scenario 3** |
+| Maximum design control AND theme adaptation | **Scenario 4** |
+
+---
+
+## 3. Concepts
+
+### 3.1 What is the DOM?
+
+Imagine a webpage as a **LEGO castle**. Every visible thing — buttons, headings, divs, images — is a LEGO brick. The bricks are snapped together in a tree: a `<div>` brick contains other bricks inside it, those contain more, and so on. The whole castle of snapped-together bricks is the **DOM** (Document Object Model). The browser stares at this castle and paints what it sees.
+
+When JavaScript says `document.querySelector('.my-button')`, it's a hand reaching into the castle to grab one specific brick.
+
+### 3.2 What is Shadow DOM?
+
+A **Shadow DOM** is a *secret inner castle hidden inside one brick*. From the outside it looks like one solid LEGO piece, but with the right key you can open it up and there's a whole little world inside with its own bricks, its own rules, its own paint. The outside castle's paint can't drip in, and the inside castle's paint can't leak out. They're **isolated**.
+
+Why would anyone want that? Because if you build a `<calendar-widget>` and ship it to ten different websites, you don't want each website's CSS messing up your calendar. Shadow DOM gives your component its own private styling bubble.
+
+### 3.3 ICan widgets DO NOT use Shadow DOM today
+
+This is important and easy to get wrong.
+
+The codebase contains a `ShadowContainer.tsx` file that *could* mount widgets in a Shadow DOM — but **nothing imports it**. Production widgets render directly inside the portal's `[data-module="ican"]` wrapper, in the regular DOM:
+
+```
+<div data-module="ican" data-theme="light">    ← portal sets this
+  └── <main class="ican-main">
+        └── <div class="widget-cell">           ← grid tile (portal)
+              └── <YourWidget>                  ← your code, plain React
+                    └── .my-card                 ← your DOM
+```
+
+There is **no isolation boundary**. CSS variables cascade in cleanly (which is what you want), but a small set of element-level rules from `globals.scss` (`button`, `input`, `h1`–`h6`, `a`) also reach your widget's elements. **Section 6** lists them all.
+
+### 3.4 How CSS variables cascade
+
+Picture each LEGO brick as having a **sticky pad** where it can write notes like *"my favorite color is purple"*. When a deeper brick asks "what color am I?" using `var(--my-favorite-color)`, the browser walks **upward** through the brick's parents looking for a sticky note with that label. The first match wins.
+
+The portal puts ICan's sticky notes on `[data-module="ican"]`:
+
+```css
+[data-module="ican"] {
+  --ican-accent: #7c6aff;       /* dark theme default */
+  --ican-card-bg: #141417;
+  /* ...77 more notes... */
+}
+```
+
+Your widget renders *inside* `[data-module="ican"]`. So when your CSS says `color: var(--ican-accent)`, the browser walks up, finds the note on `[data-module="ican"]`, resolves to `#7c6aff`. **Variables are inert lookup tokens** — they don't override anything by themselves, they're only resolved when *your* CSS uses them.
+
+When the user switches theme, the portal sets `data-theme="light"` on the same element. The `[data-module="ican"][data-theme='light']` rule fires with new sticky-note values:
+
+```css
+[data-module="ican"][data-theme='light'] {
+  --ican-accent: #5b4cd9;       /* now this */
+  --ican-card-bg: #ffffff;
+}
+```
+
+Your `var(--ican-accent)` re-resolves. Your widget repaints. **Zero JavaScript on your side.**
+
+### 3.5 Why CSS variables cross Shadow DOM boundaries
+
+Even if ICan ever did adopt Shadow DOM, your widget would still see `--ican-*` correctly — because CSS variables are explicitly designed to **leak into Shadow DOM**. It's the one mechanism that intentionally crosses the isolation boundary, so theme systems can work. *Selector-based rules* (like `button { red }`) cannot cross. Variables can.
+
+So even with hypothetical future Shadow-DOM-based widgets, the four scenarios in this doc behave the same way.
+
+---
+
+## 4. The 4 widget styling scenarios
+
+Each scenario below is a full, runnable example. Drop into `src/index.tsx` + `src/styles.scss` of any `infaira-canvas init` project.
+
+---
+
+### 4.1 Scenario 1 — ICan components + `--ican-*` variables (recommended)
+
+**What it does:** Use ICan's prebuilt components for everything that has one, theme-adapt via `--ican-*` everywhere else.
+
+**Theme behavior:** ✅ All four themes adapt automatically.
+
+**Effort:** Lowest — components handle accessibility, keyboard, state.
+
+**`src/index.tsx`**
+
+```tsx
+import * as React from 'react';
+import { Card, Button, StatCard, Badge, useToast } from 'ican/components';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IProps { icanContext?: IContextProvider }
+
+const SalesWidget: React.FC<IProps> = () => {
+  const toast = useToast();
+  return (
+    <div className="sales-widget">
+      <Card>
+        <header className="sales-widget__head">
+          <h3 className="sales-widget__title">Q2 Sales</h3>
+          <Badge variant="success">Live</Badge>
+        </header>
+
+        <div className="sales-widget__stats">
+          <StatCard label="Revenue" value="$48,200" trend="+18.4%" trendDirection="up" />
+          <StatCard label="Orders"  value="1,284"  trend="+6.2%"  trendDirection="up" />
+          <StatCard label="Returns" value="3.1%"   trend="-0.4%" trendDirection="down" />
+        </div>
+
+        <Button variant="primary" label="View Full Report" onClick={() => toast.success('Report opened')} />
+      </Card>
+    </div>
+  );
+};
+
+registerWidget({ id: 'sales-widget', widget: SalesWidget });
+```
+
+**`src/styles.scss`**
+
+```scss
+.sales-widget {
+  padding: 16px;
+  font-family: var(--ican-font-body);
+  color: var(--ican-primary-text);
+
+  &__head {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 16px;
+  }
+
+  &__title {
+    margin: 0;
+    font-family: var(--ican-font-brand);
+    font-size: 16px;
+    font-weight: 600;
+    color: var(--ican-primary-text);
+  }
+
+  &__stats {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 12px;
+    margin-bottom: 16px;
+  }
+}
+```
+
+**Why it works:** `Card`, `Button`, `StatCard`, `Badge` already use `--ican-*` internally. Your custom rules (`__head`, `__title`) also use `--ican-*`. Every theme switch retints everything. Zero issues.
+
+---
+
+### 4.2 Scenario 2 — ICan components + custom class names (no `var(--ican-*)`)
+
+**What it does:** Use ICan's components, but wrap them in your own classes with hardcoded colors.
+
+**Theme behavior:** ⚠️ Partial — ICan components adapt; your wrapper stays fixed. Looks intentional on dark theme, *visually inconsistent* on light/glass themes.
+
+**`src/index.tsx`**
+
+```tsx
+import * as React from 'react';
+import { Card, Button, DataTable } from 'ican/components';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IProps { icanContext?: IContextProvider }
+
+const InventoryWidget: React.FC<IProps> = () => {
+  const rows = [
+    { sku: 'A-100', stock: 42, status: 'OK' },
+    { sku: 'A-101', stock: 7,  status: 'LOW' },
+    { sku: 'A-102', stock: 0,  status: 'OUT' },
+  ];
+
+  return (
+    <div className="inventory-shell">
+      <div className="inventory-banner">Inventory Overview — branch #4</div>
+      <Card>
+        <DataTable rows={rows} columns={[
+          { key: 'sku',    label: 'SKU' },
+          { key: 'stock',  label: 'Stock' },
+          { key: 'status', label: 'Status' },
+        ]} />
+        <div className="inventory-footer">
+          <Button variant="primary" label="Reorder" onClick={() => {}} />
+        </div>
+      </Card>
+    </div>
+  );
+};
+
+registerWidget({ id: 'inventory-widget', widget: InventoryWidget });
+```
+
+**`src/styles.scss`**
+
+```scss
+/* No var(--ican-*) anywhere — your own values, fixed across themes. */
+.inventory-shell {
+  padding: 16px;
+  font-family: 'Inter', sans-serif;
+  color: #fafafa;
+  background: #0e0e14;       /* always this color, even on light theme */
+  border-radius: 12px;
+}
+
+.inventory-banner {
+  background: linear-gradient(90deg, #4f46e5, #ec4899);
+  color: #fff;
+  padding: 10px 14px;
+  border-radius: 8px;
+  font-weight: 600;
+  margin-bottom: 14px;
+}
+
+.inventory-footer {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 12px;
+}
+```
+
+**Why it works:** ICan components use their own internal `--ican-*` rules; your stylesheet never touches them. The mixing is fine — they live in separate selectors.
+
+**Caveat:** On **light theme** your dark `#0e0e14` shell looks wrong on a white dashboard. On **glass themes** your opaque shell blocks the dashboard's gradient — the entire glass aesthetic breaks (see section 5). Use this scenario when you specifically want a fixed branded look (a "console" panel), not when you want the widget to feel native.
+
+---
+
+### 4.3 Scenario 3 — No ICan components, custom classes, no vars
+
+**What it does:** Pure custom React with bespoke class names. No imports from `'ican/components'`. No `var(--ican-*)`.
+
+**Theme behavior:** ❌ Static — looks identical across all 4 themes. That's a *feature* if you want a deliberately stylized widget (terminal, retro UI, embedded tool).
+
+**`src/index.tsx`**
+
+```tsx
+import * as React from 'react';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IProps { icanContext?: IContextProvider }
+
+const RetroTickerWidget: React.FC<IProps> = () => {
+  const [search, setSearch] = React.useState('');
+  const items = [
+    { sym: 'AAPL', price: 187.42, chg: '+1.24%' },
+    { sym: 'MSFT', price: 412.10, chg: '-0.32%' },
+    { sym: 'NVDA', price: 921.55, chg: '+3.18%' },
+  ].filter((i) => i.sym.includes(search.toUpperCase()));
+
+  return (
+    <div className="retro-ticker">
+      <div className="retro-ticker__crt">
+        <div className="retro-ticker__title">▌ MARKET FEED ▐</div>
+
+        {/* Class on the input → my rules can override the portal */}
+        <input
+          className="retro-ticker__search"
+          placeholder="filter symbol…"
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+        />
+
+        <ul className="retro-ticker__list">
+          {items.map((i) => (
+            <li key={i.sym} className="retro-ticker__row">
+              <span className="retro-ticker__sym">{i.sym}</span>
+              <span className="retro-ticker__price">{i.price.toFixed(2)}</span>
+              <span className={`retro-ticker__chg retro-ticker__chg--${i.chg.startsWith('+') ? 'up' : 'down'}`}>{i.chg}</span>
+            </li>
+          ))}
+        </ul>
+
+        <button className="retro-ticker__refresh" onClick={() => setSearch('')}>REFRESH</button>
+      </div>
+    </div>
+  );
+};
+
+registerWidget({ id: 'retro-ticker', widget: RetroTickerWidget });
+```
+
+**`src/styles.scss`**
+
+```scss
+.retro-ticker {
+  height: 100%;
+  padding: 12px;
+  background: #000;
+  font-family: 'Courier New', monospace;
+}
+
+.retro-ticker__crt {
+  height: 100%;
+  background: #001a00;
+  border: 2px solid #00ff66;
+  border-radius: 6px;
+  padding: 14px;
+  color: #00ff66;
+  text-shadow: 0 0 4px #00ff66;
+  box-shadow: inset 0 0 24px rgba(0, 255, 102, 0.18);
+}
+
+.retro-ticker__title {
+  font-size: 14px;
+  font-weight: 700;
+  letter-spacing: 0.2em;
+  margin-bottom: 12px;
+}
+
+/* IMPORTANT: portal applies !important to all <input> bg/color globally.
+   Your class alone has lower specificity than [data-module="ican"] input
+   PLUS the portal uses !important. You must use !important to win. */
+.retro-ticker__search {
+  display: block;
+  width: 100%;
+  background: #001a00 !important;
+  color: #00ff66 !important;
+  border: 1px solid #00ff66 !important;
+  border-radius: 0 !important;
+  padding: 6px 10px !important;
+  font-family: inherit !important;
+  margin-bottom: 12px;
+  outline: none;
+
+  &::placeholder { color: rgba(0, 255, 102, 0.4); }
+}
+
+.retro-ticker__list { list-style: none; padding: 0; margin: 0 0 12px; }
+
+.retro-ticker__row {
+  display: grid;
+  grid-template-columns: 60px 1fr 80px;
+  gap: 8px;
+  padding: 4px 0;
+  border-bottom: 1px dashed rgba(0, 255, 102, 0.3);
+  font-size: 13px;
+}
+
+.retro-ticker__chg--up   { color: #66ff99; }
+.retro-ticker__chg--down { color: #ff6666; text-shadow: 0 0 4px #ff6666; }
+
+.retro-ticker__refresh {
+  background: transparent;
+  color: #00ff66;
+  border: 1px solid #00ff66;
+  padding: 6px 14px;
+  font-family: inherit;
+  letter-spacing: 0.1em;
+  cursor: pointer;
+
+  &:hover { background: rgba(0, 255, 102, 0.1); }
+}
+```
+
+**Why it works:** Every element has a class. The portal's `globals.scss` has zero rules targeting *your* class names — only generic element types. Class names you invent are inert as far as the portal is concerned.
+
+**Two gotchas:**
+1. **`<input>` needs `!important`** — the portal's `[data-module="ican"] input { background-color: !important; color: !important }` rule beats your class on specificity AND uses `!important`. `!important` on your side wins because of source order.
+2. **`<button>` is fine** — the portal's `button` reset doesn't use `!important`, just specificity. Any class on a `<button>` defeats it.
+
+**Bare elements (no class) — what happens:**
+- `<input />` with no class: gets the portal's `--ican-input-bg` background and `--ican-primary-text` color, no override possible.
+- `<button>...</button>` with no class: gets the portal's reset (transparent, no border, inherits color/font). Will look invisible.
+
+**Always put a class on `<input>` and `<button>`** — even if you never style them. That gives you an escape hatch.
+
+---
+
+### 4.4 Scenario 4 — No ICan components, custom classes, but `var(--ican-*)` (most common power-user pattern)
+
+**What it does:** Build every UI primitive yourself, but pull every color/radius/font from `var(--ican-*)` so the portal's theme switch retints your widget for free.
+
+**Theme behavior:** ✅ All four themes adapt.
+
+**Effort:** Medium-high — you're rebuilding primitives, but theme support is automatic.
+
+**`src/index.tsx`**
+
+```tsx
+import * as React from 'react';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IProps { icanContext?: IContextProvider }
+
+interface IActivity { id: string; user: string; action: string; time: string; status: 'ok' | 'warn' | 'err' }
+
+const ActivityFeedWidget: React.FC<IProps> = () => {
+  const [filter, setFilter] = React.useState('');
+  const all: IActivity[] = [
+    { id: '1', user: 'Alex',   action: 'Deployed v2.4.1',     time: '2m ago',  status: 'ok'   },
+    { id: '2', user: 'Bea',    action: 'Reviewed PR #482',     time: '14m ago', status: 'ok'   },
+    { id: '3', user: 'Cy',     action: 'Build #91 failed',     time: '32m ago', status: 'err'  },
+    { id: '4', user: 'Dee',    action: 'Slow query on orders', time: '1h ago',  status: 'warn' },
+  ];
+  const items = all.filter((a) => a.user.toLowerCase().includes(filter.toLowerCase()));
+
+  return (
+    <div className="feed">
+      <header className="feed__head">
+        <h3 className="feed__title">Activity</h3>
+        <span className="feed__count">{items.length}</span>
+      </header>
+
+      <input
+        className="feed__search"
+        placeholder="Filter by user…"
+        value={filter}
+        onChange={(e) => setFilter(e.target.value)}
+      />
+
+      <ul className="feed__list">
+        {items.map((a) => (
+          <li key={a.id} className={`feed__row feed__row--${a.status}`}>
+            <span className="feed__avatar">{a.user[0]}</span>
+            <div className="feed__body">
+              <div className="feed__line">
+                <span className="feed__user">{a.user}</span>
+                <span className="feed__action">{a.action}</span>
+              </div>
+              <div className="feed__time">{a.time}</div>
+            </div>
+            <span className={`feed__pill feed__pill--${a.status}`}>{a.status.toUpperCase()}</span>
+          </li>
+        ))}
+      </ul>
+
+      <button className="feed__refresh" onClick={() => setFilter('')}>Clear filter</button>
+    </div>
+  );
+};
+
+registerWidget({ id: 'activity-feed', widget: ActivityFeedWidget });
+```
+
+**`src/styles.scss`**
+
+```scss
+.feed {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+  font-family: var(--ican-font-body);
+  color: var(--ican-primary-text);
+  background: var(--ican-card-bg);
+  border: 1px solid var(--ican-border);
+  border-radius: var(--ican-radius-lg);
+  /* Single line that frosts on glass themes, no-op on dark */
+  backdrop-filter: var(--ican-backdrop-filter);
+  -webkit-backdrop-filter: var(--ican-backdrop-filter);
+
+  &__head { display: flex; align-items: center; gap: 8px; margin-bottom: 12px; }
+
+  &__title {
+    margin: 0;
+    font-family: var(--ican-font-brand);
+    font-size: 15px;
+    font-weight: 600;
+    color: var(--ican-primary-text);
+  }
+
+  &__count {
+    font-size: 11px; font-weight: 600;
+    color: var(--ican-accent);
+    background: var(--ican-accent-dim);
+    padding: 2px 8px;
+    border-radius: var(--ican-radius-xl);
+  }
+
+  /* INPUT — !important needed because portal forces input bg/color !important */
+  &__search {
+    margin-bottom: 12px;
+    background: var(--ican-input-bg) !important;
+    color: var(--ican-primary-text) !important;
+    border: 1px solid var(--ican-border) !important;
+    border-radius: var(--ican-radius-sm) !important;
+    padding: 8px 10px !important;
+    font-family: var(--ican-font-body) !important;
+    font-size: 13px;
+    outline: none;
+    transition: border-color var(--ican-transition-fast);
+
+    &:focus { border-color: var(--ican-border-focus) !important; }
+    &::placeholder { color: var(--ican-secondary-text); }
+  }
+
+  &__list { list-style: none; padding: 0; margin: 0; flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; }
+
+  &__row {
+    display: grid;
+    grid-template-columns: 32px 1fr auto;
+    gap: 10px;
+    align-items: center;
+    padding: 10px;
+    background: var(--ican-secondary-bg);
+    border: 1px solid var(--ican-border);
+    border-radius: var(--ican-radius-md);
+    transition: background var(--ican-transition-fast);
+
+    &:hover { background: var(--ican-hover); }
+  }
+
+  &__avatar {
+    width: 32px; height: 32px;
+    display: grid; place-items: center;
+    border-radius: 50%;
+    background: var(--ican-accent-dim);
+    color: var(--ican-accent);
+    font-weight: 700; font-size: 13px;
+  }
+
+  &__body { min-width: 0; }
+  &__line { display: flex; gap: 6px; align-items: baseline; }
+  &__user   { font-weight: 600; color: var(--ican-primary-text); font-size: 13px; }
+  &__action { color: var(--ican-secondary-text); font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  &__time   { color: var(--ican-tertiary-text); font-size: 11px; margin-top: 2px; }
+
+  &__pill {
+    font-size: 10px;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    padding: 3px 8px;
+    border-radius: var(--ican-radius-xl);
+
+    &--ok   { color: var(--ican-success); background: var(--ican-success-dim); }
+    &--warn { color: var(--ican-warning); background: var(--ican-warning-dim); }
+    &--err  { color: var(--ican-error);   background: var(--ican-error-dim);   }
+  }
+
+  &__refresh {
+    margin-top: 12px;
+    align-self: flex-start;
+    background: transparent;
+    color: var(--ican-accent);
+    border: 1px solid var(--ican-border);
+    border-radius: var(--ican-radius-md);
+    padding: 6px 12px;
+    font-family: var(--ican-font-body);
+    font-size: 12px;
+    cursor: pointer;
+    transition: all var(--ican-transition-fast);
+
+    &:hover { background: var(--ican-hover); border-color: var(--ican-border-bright); color: var(--ican-primary-text); }
+  }
+}
+```
+
+**Why it works:**
+- Theme awareness: every color is a `var(--ican-*)` lookup. The portal flips `data-theme`, variables remap, your widget repaints. No JS, no observers.
+- No ICan-component dependency: zero imports from `'ican/components'`.
+- Class names are yours: portal has zero rules targeting them.
+
+**When to pick Scenario 4 over Scenario 1:**
+- You want a layout that ICan's components don't already give you (custom timelines, dashboards-within-dashboards, retro UIs that *should* still respect theme).
+- You're porting an existing standalone React component into a widget and want minimal refactoring — just swap colors to vars.
+- You want consistency with the user's portal but with branding/structure that's distinctly yours.
+
+**Most production widgets mix Scenario 1 and Scenario 4** — components for the chrome, custom + vars for unique parts. Both mechanisms sit on the same `--ican-*` cascade.
+
+---
+
+## 5. Why Scenarios 2 and 3 fail on glass themes
+
+The four themes look like this on the dashboard:
+
+| Theme | Dashboard background | Card visual style |
+|---|---|---|
+| Dark (default) | Near-black `#09090b` | Solid dark surface |
+| Light | Near-white `#f5f5f7` | Solid white surface |
+| Glass Dark | Vivid violet/blue radial gradient on `#08061a` | Frosted glass panel — *gradient must show through* |
+| Glass Light | Pastel sky gradient (lavender/pink/mint) on `#d0e4ff` | Frosted glass panel — *gradient must show through* |
+
+The glass aesthetic is "I see a colorful soup behind, and my card is a foggy pane of glass over it." It needs **three coordinated vars**:
+
+```scss
+.my-card {
+  background: var(--ican-card-bg);           /* translucent on glass themes */
+  border:     1px solid var(--ican-glass-border);
+  backdrop-filter: var(--ican-backdrop-filter);
+  -webkit-backdrop-filter: var(--ican-backdrop-filter);
+}
+```
+
+| Var | Dark | Light | Glass Dark | Glass Light |
+|---|---|---|---|---|
+| `--ican-card-bg` | `#141417` (opaque) | `#ffffff` (opaque) | `rgba(255,255,255,0.08)` (almost see-through) | `rgba(255,255,255,0.48)` (half see-through) |
+| `--ican-backdrop-filter` | `none` | `blur(20px) saturate(180%)` | `blur(24px) saturate(200%) brightness(1.12)` | `blur(22px) saturate(190%) brightness(1.08)` |
+
+If you skip these (Scenarios 2 and 3), your card is **always opaque**. On glass themes that's the entire problem — the portal's gradient never shows through, the frost never happens, the design language breaks. You get an opaque dark blob sitting on a vivid purple page.
+
+**The clever bit:** `var(--ican-backdrop-filter)` is `none` on dark theme, so applying it always is *free of cost* on dark. You don't need a theme check in your CSS — one line works everywhere.
+
+### Hybrid escape hatch — keep custom interior, swap only the outer surface
+
+If you love your Scenario 3 retro look but want it not to break on glass themes:
+
+```scss
+/* Before — Scenario 3 outer shell */
+.retro-ticker { background: #000; }
+.retro-ticker__crt { background: #001a00; border: 2px solid #00ff66; }
+
+/* After — frosts on glass themes, still feels CRT inside */
+.retro-ticker {
+  background: var(--ican-card-bg);
+  backdrop-filter: var(--ican-backdrop-filter);
+  -webkit-backdrop-filter: var(--ican-backdrop-filter);
+  border-radius: var(--ican-radius-lg);
+}
+.retro-ticker__crt {
+  background: rgba(0, 26, 0, 0.85);   /* slight transparency lets the frost show */
+  border: 2px solid #00ff66;
+}
+```
+
+You keep ~90% of your custom palette and only opt into vars on the **outermost surface + the frost**. That's enough to make glass themes work and light theme not look broken, while your interior stays as-stylized as you want.
+
+---
+
+## 6. Portal element-level rules that reach your widget
+
+Because there's no Shadow DOM, a small set of rules from `globals.scss` reach your widget's elements. Knowing them makes overriding deterministic.
+
+| Selector | What the portal applies | How to override |
+|---|---|---|
+| `button` | Resets `border`, `background`, `cursor`; sets `font-family`; inherits `color` and `font-size` | Add a class — your rules win on specificity (no `!important` needed) |
+| `input, select, textarea, option` | Forces `background-color` and `color` via `!important`; sets default border + padding + radius | Use `!important` on `background`, `color`, `border`, `padding` |
+| `h1`–`h6` | Sets `font-family` + tightened margins | Set your own `margin` / `font-family` in your widget CSS |
+| `a` | Sets accent color + hover underline | Override `color` / `text-decoration` in your `.my-widget a {}` rule |
+| `*, *::before, *::after` | `box-sizing: border-box` | Leave it — this is the convention you want |
+
+**The `<input>` rule is the only one that uses `!important`.** Everything else is plain specificity, defeated by adding a class.
+
+**Class-name collisions are not a concern.** The portal targets element types only. Any class name you invent is yours — `.my-fancy-card`, `.revenue-value`, anything.
+
+**The minimum input override snippet** (memorize this):
+
+```scss
+.my-input {
+  background: transparent !important;       /* or var(--ican-input-bg) */
+  color: var(--ican-primary-text) !important;
+  border: 1px solid var(--ican-border) !important;
+  padding: 8px 12px !important;
+}
+```
+
+---
+
+## 7. Decision matrix
+
+| | Scenario 1 | Scenario 2 | Scenario 3 | Scenario 4 |
+|---|---|---|---|---|
+| ICan components | ✅ | ⚠️ partial | ❌ | ❌ |
+| ICan vars in your CSS | ✅ | ❌ | ❌ | ✅ |
+| Custom class names | a few | many | full custom | full custom |
+| Theme adapts (dark) | ✅ | ⚠️ | (static) | ✅ |
+| Theme adapts (light) | ✅ | ❌ wrong | (static, looks displaced) | ✅ |
+| Theme adapts (glass dark) | ✅ | ❌ broken | ❌ broken | ✅ |
+| Theme adapts (glass light) | ✅ | ❌ broken | ❌ broken | ✅ |
+| `<input>` needs `!important` | n/a (use ICan `<Input>`) | n/a (use ICan `<Input>`) | yes | yes |
+| Effort | Lowest | Medium | Highest | Medium-High |
+| Best for | Standard widgets | Branded console widgets | Retro/specialized "island" widgets | Custom layouts that respect theme |
+
+---
+
+## 8. Pre-publish checklist
+
+Before you publish a widget, verify:
+
+- [ ] **No hardcoded hex.** Search your `.scss` for `#`, `rgb(`, `hsl(`. Every match should either be a deliberate fixed-look choice (Scenario 3 territory) OR replaced with `var(--ican-*)`.
+- [ ] **Outer surface uses the glass three.** `.my-widget { background: var(--ican-card-bg); backdrop-filter: var(--ican-backdrop-filter); -webkit-backdrop-filter: var(--ican-backdrop-filter); border: 1px solid var(--ican-border); }` — these three vars are what makes glass themes work.
+- [ ] **Every `<input>` has a class** AND the override rule with `!important` on `background`, `color`, `border`, `padding`.
+- [ ] **Every `<button>` has a class** even if you don't style it (gives you an escape hatch from the portal's reset).
+- [ ] **Tested on all 4 themes.** Switch theme in the portal's Appearance page (or in dev: change the `data-theme` attribute on `<html>`) and visually confirm. Glass-dark and glass-light are the strict tests.
+- [ ] **Chart colors derived in JavaScript** from `icanContext.themeType`, not from CSS variables (SVG can't read CSS vars). See [`ICan-Widget-Theming-Guide.md`](./ICan-Widget-Theming-Guide.md) section "Reading the Current Theme in JavaScript".
+
+---
+
+## 9. Where to find more
+
+- **[`ICan-Widget-Theming-Guide.md`](./ICan-Widget-Theming-Guide.md)** — exhaustive `--ican-*` variable reference, every variable's value across all 4 themes, glass frosting deep dive.
+- **[`ICan-Customizing-Components.md`](./ICan-Customizing-Components.md)** — how to customize ICan's bundled component library.
+- **In-portal `/docs` page** — live component playground with prop tables, live demos, computed CSS variable values for the active theme.
+- **`README.md`** in your scaffolded widget project — bundle.json, build, upload flow.
+
+---
+
+## 10. Class name collisions
+
+### The problem
+
+Because ICan widgets render in the **plain DOM** (no Shadow DOM), every widget's CSS rules land in the same global stylesheet. If Widget A and Widget B both define `.widget-root`, both rules exist simultaneously. The browser applies them by cascade order — whichever bundle loaded **last** wins — and **both** widgets end up with the same styles.
+
+| Widget A `styles.scss` | Widget B `styles.scss` |
+|---|---|
+| `.widget-root { background: #1a1a2e; }` | `.widget-root { background: #ffffff; }` |
+
+On a dashboard showing both, both cells get `background: #ffffff`. Widget A looks broken. Neither developer notices in their own dev environment because they only ever test their widget alone.
+
+### The silent failure
+
+This bug has three properties that make it especially hard to catch:
+
+1. **Invisible in isolation.** Each widget looks correct in `npm run dev` because only one widget's CSS is in the page.
+2. **Load-order dependent.** The broken widget changes depending on which script the browser happens to fetch first — it can look correct on one page load and wrong on the next.
+3. **Scroll-triggered.** The portal lazy-loads widget scripts. A dashboard can look fine until the user scrolls to the second widget, which injects its script and immediately overwrites the first widget's styles.
+
+### When it happens
+
+- Both widgets use the scaffold's default class names (`.widget-root`, `.widget-loading`, `.widget-spinner`, `.widget-error`, `.widget-error-message`)
+- Two developers chose the same descriptive name independently (`.card`, `.title`, `.button`, `.header`)
+- A developer copies code from another widget without renaming classes
+
+### The fix: scope all CSS under a unique outer class
+
+Wrap every rule in your `styles.scss` under your widget ID as the outermost class:
+
+```scss
+/* ✅ correct — all rules scoped under the widget ID */
+.my-sales-widget {
+  padding: 20px;
+  color: var(--ican-primary-text);
+
+  &__title {
+    font-size: 15px;
+    font-family: var(--ican-font-brand);
+  }
+
+  &__spinner {
+    animation: my-sales-widget-spin 0.8s linear infinite;
+  }
+}
+
+@keyframes my-sales-widget-spin {
+  to { transform: rotate(360deg); }
+}
+```
+
+And in your TSX root element:
+
+```tsx
+<div className="my-sales-widget">
+  <h3 className="my-sales-widget__title">...</h3>
+</div>
+```
+
+Now `.my-sales-widget__title` only matches elements inside a `.my-sales-widget` root. Any other widget using `.title` is completely unaffected.
+
+### @keyframes need prefixing too
+
+Animation names are global — two widgets both defining `@keyframes spin` will overwrite each other. Always prefix animation names with your widget ID:
+
+```scss
+/* ❌ global — will be overwritten by any other widget named 'spin' */
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* ✅ unique — scoped to your widget */
+@keyframes my-sales-widget-spin { to { transform: rotate(360deg); } }
+```
+
+### Risk by approach
+
+| What you write | Collision risk |
+|---|---|
+| `.button { }` | **High** — any other widget can have `.button` |
+| `.my-sales-widget__button { }` | **None** — scoped to your widget ID |
+| `@keyframes spin { }` | **High** — last loaded wins |
+| `@keyframes my-sales-widget-spin { }` | **None** — unique name |
+| ICan components only (`<Button>`, `<Card>`) | **None** — ICan's internal class names are portal-managed |
+| `var(--ican-*)` inside your scoped class | **None** — CSS variables are not class names |
+
+### What the scaffold generates
+
+The `infaira-canvas init` scaffold uses the widget ID you provide as the outer SCSS wrapper in the generated `styles.scss`. Keep this pattern — do not flatten it to generic names like `.root` or `.container`.
+
+---
+
+## 11. AI-agent quick context block
+
+> Read this section before generating any widget code.
+
+**Architectural facts:**
+1. Widgets render in **plain DOM** inside `[data-module="ican"]`, NOT in Shadow DOM. (`ShadowContainer.tsx` exists but is unused.)
+2. CSS variables (`--ican-*`) are scoped to `[data-module="ican"]`. They cascade down to your widget. They are **inert lookup tokens** — they don't override anything by themselves.
+3. The portal applies element-level styles to `button`, `input, select, textarea, option`, `h1`–`h6`, `a`, `*` inside `[data-module="ican"]`. Your widget's elements *are* affected.
+4. The `input` rule uses `!important` on `background-color` and `color`. To override: use `!important` on your side.
+5. Every `--ican-*` variable name is identical between the dev harness (`infaira-canvas init` scaffold's `index.html` declares them on `:root`) and production (`globals.scss` declares them on `[data-module="ican"]`). Same name + same hex value = same color in both environments.
+6. Widgets render in a shared global DOM — **all class names across all loaded widgets are in the same namespace.** Scope every SCSS rule under the widget ID as the outermost class to prevent collisions. Prefix `@keyframes` names with the widget ID too.
+
+**When generating widget code:**
+- Default to **Scenario 1** unless the user wants a custom look or non-standard layout.
+- For custom layouts that should still respect theme: **Scenario 4**.
+- For deliberately fixed-look widgets: **Scenario 3** with a one-line note acknowledging glass themes will look displaced.
+- Always put a class on `<input>` and `<button>` elements.
+- For `<input>`, always add the override rule with `!important` on `background`, `color`, `border`, `padding`.
+- Use `var(--ican-card-bg)` + `var(--ican-backdrop-filter)` on the outermost card surface to ensure glass themes work — this is the single highest-leverage pair of variables for theme correctness.
+- **Always** wrap all SCSS under the widget ID as the outermost class. Never use generic names like `.root`, `.container`, `.button`, `.title` at top level.
+
+**Do not:**
+- Don't import from `'ican/components'` if the user explicitly says "no ICan components."
+- Don't hardcode hex values without first checking if the user wants theme adaptation.
+- Don't skip `!important` on input overrides — it will silently fail on the portal.
+- Don't add `data-module="ican"` to a portal you create yourself (e.g., a modal). The portal's wrapper is the only one that should have that attribute. Adding it elsewhere will pull in theme rules (radial gradients, `position: relative`, `::before` overlays) that break your layout.
+- Don't use generic top-level class names — always scope under the widget ID.
+
+**Default widget skeleton (Scenario 1, copy-paste-ready):**
+
+```tsx
+import * as React from 'react';
+import { Card } from 'ican/components';
+import { registerWidget } from './ican';
+import type { IContextProvider } from './ican';
+import './styles.scss';
+
+interface IProps { icanContext?: IContextProvider }
+
+const MyWidget: React.FC<IProps> = ({ icanContext }) => {
+  return (
+    <Card>
+      <div className="my-widget">
+        <h3 className="my-widget__title">Title</h3>
+        {/* widget body */}
+      </div>
+    </Card>
+  );
+};
+
+registerWidget({ id: 'my-widget', widget: MyWidget });
+```
+
+```scss
+.my-widget {
+  font-family: var(--ican-font-body);
+  color: var(--ican-primary-text);
+
+  &__title {
+    margin: 0 0 12px;
+    font-family: var(--ican-font-brand);
+    font-size: 15px;
+    font-weight: 600;
+  }
+}
+```
+
+This is the safest starting point for any widget. Customize from here.