igniteui-webcomponents 7.4.0 → 7.4.1

package/skills/igniteui-wc-figma-to-app/references/validation-patterns.md

@@ -2,21 +2,15 @@
 
 > **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
 >
-> Use this file in Phase 5 for the measurement-driven validation loop. Read it in full
-> before calling any Playwright tool.
+> Use this file in Phase 5 for the measurement-driven validation loop. Read it in full before calling any Playwright tool.
 
 ---
 
 ## Core Philosophy
 
-**Measure, don't eyeball.** The goal is not visual regression (did this change since last
-week?) but design fidelity (does this match the Figma spec?). Screenshots give you the
-gestalt; `playwright_browser_evaluate` gives you the numbers; numbers drive corrections.
+**Measure, don't eyeball.** The goal is not visual regression (did this change since last week?) but design fidelity (does this match the Figma spec?). Screenshots give you the gestalt; `playwright_browser_evaluate` gives you the numbers; numbers drive corrections.
 
-**The Web Components twist:** almost everything you want to measure lives inside a shadow
-root. `document.querySelector('igc-card .title')` returns `null` — not because the element
-is missing, but because the selector cannot cross the boundary. Every snippet below is
-shadow-aware. Use them instead of writing ad-hoc selectors.
+**The Web Components twist:** almost everything you want to measure lives inside a shadow root. `document.querySelector('igc-card .title')` returns `null` — not because the element is missing, but because the selector cannot cross the boundary. Every snippet below is shadow-aware and inlines the helpers it uses. Use them instead of writing ad-hoc selectors. A view built as a Lit component is itself a shadow root, so reach its content with a `host >>> selector` path (e.g. `app-dashboard >>> .kpi-card`).
 
 ---
 
@@ -30,16 +24,16 @@ shadow-aware. Use them instead of writing ad-hoc selectors.
 5.  playwright_browser_evaluate        → registration + theme audit (fail fast)
 6.  playwright_browser_take_screenshot → capture the full viewport
 7.  [Visual comparison]                → against the Phase 1c reference, section by section
-8.  playwright_browser_evaluate        → measure EVERY section in the Phase 1g Surfaces table
+8.  playwright_browser_evaluate        → measure EVERY section in the Phase 1g Table B (Layout Surfaces)
 9.  [Surfaces audit]                   → assert background, radius, padding, border
 10. [Action controls audit]            → count and name every control, shadow roots included
 11. [Input variant audit]              → check `outlined` against the Phase 1d variant
 12. [Classify mismatches]              → severity table
 13. [Apply fixes]                      → edit source files
 14. playwright_browser_navigate        → reload after fixes
-15. Repeat 6–14 until no Critical/Major issues remain
-16. Do NOT advance to the next artboard until all checks pass on this one
-17. playwright_browser_snapshot        → final accessibility check
+15. Repeat 6–14 until the exit condition below is met (only Cosmetic and Accepted items left)
+16. Do NOT advance to the next artboard until then
+17. playwright_browser_snapshot        → accessibility check for this view (once per artboard)
 ```
 
 ---
@@ -48,8 +42,7 @@ shadow-aware. Use them instead of writing ad-hoc selectors.
 
 ### 1. Viewport reset after resize
 
-After `playwright_browser_resize`, the browser may navigate itself to `about:blank`, and
-subsequent screenshots and measurements come back empty.
+After `playwright_browser_resize`, the browser may navigate itself to `about:blank`, and subsequent screenshots and measurements come back empty.
 
 ```
 playwright_browser_resize({ width: 1440, height: 900 })
@@ -71,19 +64,17 @@ playwright_browser_evaluate({ function: "() => document.title" })
 
 ### 3. Measuring before the components have upgraded
 
-Custom elements upgrade asynchronously, and Lit renders on a microtask. Measuring too early
-returns pre-upgrade box metrics (often `height: 0`). Wait for definition and render:
+Custom elements upgrade asynchronously, and Lit renders on a microtask. Measuring too early returns pre-upgrade box metrics (often `height: 0`). Wait for the registered elements to render. The snippet only waits on tags that are already defined, with a 3-second cap, so an unregistered tag cannot hang it; it is returned in `undefinedTags` instead:
 
 ```
 playwright_browser_evaluate({
-  function: "async () => { const tags = [...new Set([...document.querySelectorAll('*')].map(e => e.tagName.toLowerCase()).filter(t => t.startsWith('igc-')))]; await Promise.all(tags.map(t => customElements.whenDefined(t))); const els = [...document.querySelectorAll('*')].filter(e => e.tagName.startsWith('IGC-')); await Promise.all(els.map(e => e.updateComplete).filter(Boolean)); await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))); return { upgraded: tags.length }; }"
+  function: "async () => { const deepQueryAll = (sel, root = document) => { const out = []; const walk = (node) => { out.push(...node.querySelectorAll(sel)); node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(root); return out; }; const els = deepQueryAll('*').filter(e => e.tagName.startsWith('IGC-')); const tags = [...new Set(els.map(e => e.tagName.toLowerCase()))]; const undefinedTags = tags.filter(t => !customElements.get(t)); const timeout = new Promise(r => setTimeout(r, 3000)); await Promise.race([Promise.all(els.filter(e => customElements.get(e.tagName.toLowerCase())).map(e => e.updateComplete).filter(Boolean)), timeout]); await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))); return { upgraded: tags.length - undefinedTags.length, undefinedTags }; }"
 })
 ```
 
 ### 4. An unregistered element fails silently
 
-A missing `defineComponents(...)` produces **no console error** — the tag renders as an
-empty inline box. Run the registration audit before blaming CSS.
+A missing `defineComponents(...)` produces **no console error** — the tag renders as an empty inline box. Run the registration audit before blaming CSS.
 
 ### 5. Dev server must be running
 
@@ -92,18 +83,16 @@ playwright_browser_navigate({ url: "http://localhost:5173" })
 playwright_browser_console_messages()
 ```
 
-`ERR_CONNECTION_REFUSED` or a blank page means the Vite dev server is not running — ask the
-user to run `npm start`. Note the port: Vite defaults to **5173**.
+`ERR_CONNECTION_REFUSED` or a blank page means the Vite dev server is not running — ask the user to run `npm start`. Note the port: Vite defaults to **5173**.
 
 ---
 
 ## The Deep-Query Helper
 
-Every measurement snippet below assumes this helper. It walks shadow roots, so a selector
-like `igc-card >>> [part="header"]` resolves.
+Every measurement snippet below assumes this helper. It walks shadow roots, so a selector like `igc-card >>> [part="header"]` resolves.
 
 ```javascript
-// Paste as the first statements of any evaluate() function.
+// Every snippet below already inlines the helpers it uses. Paste these into new snippets.
 const deepQuery = (path, root = document) =>
   path.split('>>>').map(s => s.trim()).reduce(
     (node, sel) => node && (node.shadowRoot || node).querySelector(sel),
@@ -122,10 +111,7 @@ const deepQueryAll = (sel, root = document) => {
 };
 ```
 
-Prefer measuring the **host element** (`igc-card`) for box metrics — width, height,
-position, margin — and pierce only for internals that the design calls out (header height,
-row padding). When you must pierce, target documented `::part(...)` names from `get_doc`,
-never internal class names.
+Prefer measuring the **host element** (`igc-card`) for box metrics — width, height, position, margin — and pierce only for internals that the design calls out (header height, row padding). When you must pierce, target documented `::part(...)` names from `get_doc`, never internal class names.
 
 ---
 
@@ -137,13 +123,11 @@ All snippets use the `function` parameter.
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const tags = [...new Set(deepQueryAll('*').map(e => e.tagName.toLowerCase()).filter(t => t.startsWith('igc-')))]; const undefinedTags = tags.filter(t => !customElements.get(t)); const s = getComputedStyle(document.documentElement); return { tags, undefinedTags, theme: s.getPropertyValue('--ig-theme').trim(), variant: s.getPropertyValue('--ig-theme-variant').trim(), primary500: s.getPropertyValue('--ig-primary-500').trim(), surface500: s.getPropertyValue('--ig-surface-500').trim(), fontFamily: s.getPropertyValue('--ig-font-family').trim() }; }"
+  function: "() => { const deepQueryAll = (sel, root = document) => { const out = []; const walk = (node) => { out.push(...node.querySelectorAll(sel)); node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(root); return out; }; const tags = [...new Set(deepQueryAll('*').map(e => e.tagName.toLowerCase()).filter(t => t.startsWith('igc-')))]; const undefinedTags = tags.filter(t => !customElements.get(t)); const s = getComputedStyle(document.documentElement); return { tags, undefinedTags, theme: s.getPropertyValue('--ig-theme').trim(), variant: s.getPropertyValue('--ig-theme-variant').trim(), primary500: s.getPropertyValue('--ig-primary-500').trim(), surface500: s.getPropertyValue('--ig-surface-500').trim(), fontFamily: s.getPropertyValue('--ig-font-family').trim() }; }"
 })
 ```
 
-Assert: `undefinedTags` is empty; `theme` and `variant` match the design system and variant
-resolved in Phase 3. An empty `theme` means no theme CSS is loaded — components silently
-fall back to `bootstrap` / `light`.
+Assert: `undefinedTags` is empty; `theme` and `variant` match the design system and variant resolved in Phase 3. An empty `theme` means no theme CSS is loaded — components silently fall back to `bootstrap` / `light`.
 
 ### Measure a single element (shadow-aware)
 
@@ -153,14 +137,13 @@ playwright_browser_evaluate({
 })
 ```
 
-> A host element with `display: inline` (the Lit default) reports a misleading box. If width
-> or height look wrong, check for a missing `:host { display: block }` before chasing padding.
+> A host element with `display: inline` (the Lit default) reports a misleading box. If width or height look wrong, check for a missing `:host { display: block }` before chasing padding.
 
 ### Surfaces audit (mandatory — every page, every Phase 1g surface)
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const sections = { /* fill from the Phase 1g Surfaces table */ sectionA: '.section-a', sectionB: '.section-b' }; const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const out = {}; for (const [key, sel] of Object.entries(sections)) { const el = deepQuery(sel); if (!el) { out[key] = 'NOT FOUND'; continue; } const s = getComputedStyle(el); const r = el.getBoundingClientRect(); out[key] = { bg: s.backgroundColor, radius: s.borderRadius, padding: s.padding, border: s.border, shadow: s.boxShadow, w: Math.round(r.width), h: Math.round(r.height) }; } return out; }"
+  function: "() => { const sections = { /* fill from the Phase 1g Table B */ sectionA: '.section-a', sectionB: '.section-b' }; const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const out = {}; for (const [key, sel] of Object.entries(sections)) { const el = deepQuery(sel); if (!el) { out[key] = 'NOT FOUND'; continue; } const s = getComputedStyle(el); const r = el.getBoundingClientRect(); out[key] = { bg: s.backgroundColor, radius: s.borderRadius, padding: s.padding, border: s.border, shadow: s.boxShadow, w: Math.round(r.width), h: Math.round(r.height) }; } return out; }"
 })
 ```
 
@@ -179,41 +162,33 @@ playwright_browser_evaluate({
 })
 ```
 
-Compare against the Phase 1d inventory. Any control not in the design context output is
-fabricated and must be removed. `(unlabeled)` entries are also an accessibility failure —
-icon-only buttons need `aria-label`.
+Compare against the Phase 1d inventory. Any control not in the design context output is fabricated and must be removed. `(unlabeled)` entries are also an accessibility failure — icon-only buttons need `aria-label`.
 
 ### Input variant audit (every page with form controls)
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const tags = ['igc-input','igc-textarea','igc-mask-input','igc-date-time-input','igc-file-input','igc-select','igc-combo','igc-date-picker','igc-date-range-picker']; const out = {}; tags.forEach(t => { const els = deepQueryAll(t); if (els.length) out[t] = { count: els.length, outlined: els.filter(e => e.hasAttribute('outlined')).length }; }); return out; }"
+  function: "() => { const deepQueryAll = (sel, root = document) => { const out = []; const walk = (node) => { out.push(...node.querySelectorAll(sel)); node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(root); return out; }; const tags = ['igc-input','igc-textarea','igc-mask-input','igc-date-time-input','igc-file-input','igc-select','igc-combo','igc-date-picker','igc-date-range-picker']; const out = {}; tags.forEach(t => { const els = deepQueryAll(t); if (els.length) out[t] = { count: els.length, outlined: els.filter(e => e.hasAttribute('outlined')).length }; }); return out; }"
 })
 ```
 
-Compare against the variant detected in Phase 1d. If the design uses border-style inputs
-everywhere, every control should report `outlined === count`.
+Compare against the variant detected in Phase 1d. If the design uses border-style inputs everywhere, every control should report `outlined === count`.
 
 ### Property-binding audit (collection-bound charts, grids, combos)
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const defs = [ ['igc-category-chart', ['dataSource', 'data']], ['igc-data-chart', ['dataSource', 'data']], ['igc-pie-chart', ['dataSource', 'data']], ['igc-doughnut-chart', ['dataSource', 'data']], ['igc-financial-chart', ['dataSource', 'data']], ['igc-sparkline', ['dataSource', 'data']], ['igc-treemap', ['dataSource', 'data']], ['igc-funnel-chart', ['dataSource', 'data']], ['igc-grid', ['data']], ['igc-grid-lite', ['data']], ['igc-combo', ['data']] ]; const out = {}; defs.forEach(([tag, dataProps]) => { deepQueryAll(tag).forEach((el, i) => { const dataProp = dataProps.find(prop => Array.isArray(el[prop])); const brushProps = ['brushes', 'outlines'].filter(prop => Array.isArray(el[prop])); out[tag + '#' + i] = { dataLength: dataProp ? el[dataProp].length : null, brushCollections: brushProps.length ? Object.fromEntries(brushProps.map(prop => [prop, el[prop]])) : null, height: Math.round(el.getBoundingClientRect().height) }; }); }); return out; }"
+  function: "() => { const deepQueryAll = (sel, root = document) => { const out = []; const walk = (node) => { out.push(...node.querySelectorAll(sel)); node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(root); return out; }; const defs = [ ['igc-category-chart', 'dataSource', ['brushes', 'outlines']], ['igc-data-chart', 'dataSource', ['brushes', 'outlines']], ['igc-pie-chart', 'dataSource', ['brushes', 'outlines']], ['igc-financial-chart', 'dataSource', ['brushes', 'outlines']], ['igc-funnel-chart', 'dataSource', ['brushes', 'outlines']], ['igc-sparkline', 'dataSource', ['brush']], ['igc-treemap', 'dataSource', ['fillBrushes']], ['igc-grid', 'data', []], ['igc-grid-lite', 'data', []], ['igc-combo', 'data', []] ]; const out = {}; const assigned = (el, props) => props.filter(p => el[p] != null && el[p] !== ''); defs.forEach(([tag, dataProp, brushProps]) => { deepQueryAll(tag).forEach((el, i) => { const data = el[dataProp]; out[tag + '#' + i] = { dataLength: Array.isArray(data) ? data.length : null, brushes: brushProps.length ? assigned(el, brushProps) : 'n/a', height: Math.round(el.getBoundingClientRect().height) }; }); }); deepQueryAll('igc-doughnut-chart').forEach((el, i) => { const series = [...el.querySelectorAll('igc-ring-series')]; out['igc-doughnut-chart#' + i] = { series: series.map(s => ({ dataLength: Array.isArray(s.dataSource) ? s.dataSource.length : null, brushes: assigned(s, ['brushes', 'outlines']) })), height: Math.round(el.getBoundingClientRect().height) }; }); return out; }"
 })
 ```
 
-`dataLength: null` means the collection was set as an attribute (or not at all) instead of
-as a property. `brushCollections: null` on a chart means none of its documented
-`brushes` / `outlines` arrays were assigned, so it is still using the default palette instead
-of the Figma series colors. `height: 0` means the element or its grid track has no height.
-Use this audit for the collection-bound host tags in the selected plan; gauges and maps need
-their own host-specific validation once you know which properties the chosen component binds.
+`dataLength: null` means the collection was set as an attribute (or not at all) instead of as a property. An empty `brushes` list on a chart means no series colors were assigned, so it is still using the default palette instead of the Figma series colors. The brush members differ per chart: `brushes` / `outlines` on most charts, `brush` on `igc-sparkline`, `fillBrushes` on `igc-treemap`, and `brushes` / `outlines` on each `igc-ring-series` child of `igc-doughnut-chart` (not on the host). `height: 0` means the element or its grid track has no height. Use this audit for the collection-bound host tags in the selected plan; gauges and maps need their own host-specific validation once you know which properties the chosen component binds.
 
 ### Measure the gap between two elements
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const a = document.querySelector('<SELECTOR_A>'); const b = document.querySelector('<SELECTOR_B>'); if (!a || !b) return { error: 'one or both elements not found' }; const ra = a.getBoundingClientRect(); const rb = b.getBoundingClientRect(); return { gapBetween: Math.round(rb.top - ra.bottom), aHeight: Math.round(ra.height), bTop: Math.round(rb.top) }; }"
+  function: "() => { const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const a = deepQuery('<SELECTOR_A>'); const b = deepQuery('<SELECTOR_B>'); if (!a || !b) return { error: 'one or both elements not found' }; const ra = a.getBoundingClientRect(); const rb = b.getBoundingClientRect(); return { gapBetween: Math.round(rb.top - ra.bottom), aHeight: Math.round(ra.height), bTop: Math.round(rb.top) }; }"
 })
 ```
 
@@ -221,7 +196,7 @@ playwright_browser_evaluate({
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const sels = ['h1','h2','h3','p','.subtitle','.caption']; const out = {}; sels.forEach(sel => { const el = document.querySelector(sel); if (el) { const s = getComputedStyle(el); out[sel] = { fontSize: s.fontSize, fontWeight: s.fontWeight, lineHeight: s.lineHeight, fontFamily: s.fontFamily }; } }); return out; }"
+  function: "() => { const deepQueryAll = (sel, root = document) => { const out = []; const walk = (node) => { out.push(...node.querySelectorAll(sel)); node.querySelectorAll('*').forEach(el => el.shadowRoot && walk(el.shadowRoot)); }; walk(root); return out; }; const sels = ['h1','h2','h3','p','.subtitle','.caption']; const out = {}; sels.forEach(sel => { const el = deepQueryAll(sel)[0]; if (el) { const s = getComputedStyle(el); out[sel] = { fontSize: s.fontSize, fontWeight: s.fontWeight, lineHeight: s.lineHeight, fontFamily: s.fontFamily }; } }); return out; }"
 })
 ```
 
@@ -229,7 +204,7 @@ playwright_browser_evaluate({
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const el = document.querySelector('<LAYOUT_CONTAINER>'); if (!el) return { error: 'layout container not found' }; const s = getComputedStyle(el); return { display: s.display, gridTemplateColumns: s.gridTemplateColumns, gridTemplateRows: s.gridTemplateRows, gap: s.gap, width: Math.round(el.getBoundingClientRect().width) }; }"
+  function: "() => { const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const el = deepQuery('<LAYOUT_CONTAINER>'); if (!el) return { error: 'layout container not found' }; const s = getComputedStyle(el); return { display: s.display, gridTemplateColumns: s.gridTemplateColumns, gridTemplateRows: s.gridTemplateRows, gap: s.gap, width: Math.round(el.getBoundingClientRect().width) }; }"
 })
 ```
 
@@ -237,12 +212,11 @@ playwright_browser_evaluate({
 
 ```
 playwright_browser_evaluate({
-  function: "() => { const host = document.querySelector('<igc-tag>'); if (!host || !host.shadowRoot) return { error: 'host or shadow root not found' }; return [...host.shadowRoot.querySelectorAll('[part]')].map(el => ({ part: el.getAttribute('part'), bg: getComputedStyle(el).backgroundColor, color: getComputedStyle(el).color })); }"
+  function: "() => { const deepQuery = (path, root = document) => path.split('>>>').map(s => s.trim()).reduce((n, sel) => n && (n.shadowRoot || n).querySelector(sel), root); const host = deepQuery('<igc-tag>'); if (!host || !host.shadowRoot) return { error: 'host or shadow root not found' }; return [...host.shadowRoot.querySelectorAll('[part]')].map(el => ({ part: el.getAttribute('part'), bg: getComputedStyle(el).backgroundColor, color: getComputedStyle(el).color })); }"
 })
 ```
 
-Use the reported `part` names — they are the supported styling surface when a design token
-does not exist for a detail the design requires.
+Use the reported `part` names — they are the supported styling surface when a design token does not exist for a detail the design requires.
 
 ---
 
@@ -250,17 +224,25 @@ does not exist for a detail the design requires.
 
 | Severity     | Category                   | Decision rule                                               | Action                      |
 | ------------ | -------------------------- | ----------------------------------------------------------- | --------------------------- |
-| **Critical** | Missing element            | Present in Figma, absent from DOM                           | Auto-fix                    |
-| **Critical** | Unregistered component     | Tag present but `customElements.get()` is undefined         | Auto-fix (add registration) |
-| **Critical** | Broken layout              | Overlapping elements, content outside bounds, zero-height   | Auto-fix                    |
-| **Critical** | Wrong design system active | `--ig-theme` does not match the Phase 3 resolution          | Auto-fix (theme import)     |
-| **Major**    | Wrong component            | Figma shows a combo, code has a select                      | Auto-fix                    |
-| **Major**    | Wrong variant              | `variant="flat"` when the design shows contained            | Auto-fix                    |
-| **Major**    | Collection not bound       | `data` / `dataSource` / `brushes` set as an attribute       | Auto-fix                    |
-| **Minor**    | Spacing off by > 4px       | `gap: 24px` measured, Figma shows `16px`                    | Auto-fix if a single property |
-| **Minor**    | Font size wrong by > 2px   | `16px` measured, Figma shows `14px`                         | Auto-fix                    |
-| **Cosmetic** | Color shade                | `rgb(50,50,50)` vs `#333333` (perceptually identical)       | Report only                 |
-| **Cosmetic** | Spacing off by ≤ 4px       | Rounding or sub-pixel difference                            | Report only                 |
+| **Critical** | Missing element            | Present in Figma, absent from DOM                           | Fix                         |
+| **Critical** | Unregistered component     | Tag present but `customElements.get()` is undefined         | Fix (add registration)      |
+| **Critical** | Broken layout              | Overlapping elements, content outside bounds, zero-height   | Fix                         |
+| **Critical** | Wrong design system active | `--ig-theme` does not match the Phase 3 resolution          | Fix (theme import)          |
+| **Major**    | Wrong component            | Figma shows a combo, code has a select                      | Fix                         |
+| **Major**    | Wrong variant              | `variant="flat"` when the design shows contained            | Fix                         |
+| **Major**    | Collection not bound       | `data` / `dataSource` set as an attribute, or no series brushes assigned | Fix                         |
+| **Major**    | Token-fixable mismatch     | Color, radius, border, shadow, or text casing differs, or a control height differs by more than 4px, and a component token, palette seed, `--ig-size` step, or `--ig-<style>-<property>` override can close it | Fix |
+| **Minor**    | Spacing off by > 4px       | `gap: 24px` measured, Figma shows `16px`                    | Fix                         |
+| **Minor**    | Font size wrong by > 2px   | `16px` measured, Figma shows `14px`                         | Fix                         |
+| **Cosmetic** | Color rounding             | The same color after conversion: `rgb(51, 51, 51)` vs `#333333`. Any visibly different shade (`#333` vs `#2d2d2d`, a 500-vs-600 seed) is **Major** | Report only |
+| **Cosmetic** | Size off by ≤ 4px          | Spacing or control height within 4px, or font size within 2px, from rounding or sub-pixel layout | Report only |
+| **Accepted** | Approved anatomy delta     | Matches a delta-ledger entry the user approved (e.g. an M3 segmented button's check icon, a sheet rendered as a dialog) | Report only. Do not "fix" it; it does not count toward the 3-retry rule |
+
+**Exit condition for an artboard:** no Critical, Major, or Minor issues remain. Only Cosmetic and Accepted items may be left, and both go into the final report.
+
+> **Accepted needs the user's approval.** A delta is Accepted only after the user approves its ledger entry. Most entries come from Phase 2d. When Phase 5 finds a difference that tokens, documented `::part(...)` selectors, or slotted content cannot close, add it to the ledger and ask the user. Once they approve it, it is Accepted from then on. Until then, classify it normally, and never downgrade it silently.
+>
+> **Third-party kits (Path B):** color, radius, border, casing, and height mismatches are almost always fixable with component tokens or the `--ig-<style>-<property>` typography overrides. They are Major, never Accepted. Only *structural* differences (a label position the baseline cannot move, an adornment the component does not render, a behavior pattern with no equivalent) qualify for the ledger.
 
 ### Mismatch report format
 
@@ -269,20 +251,19 @@ ISSUE:    <concise description of the mismatch>
 LOCATION: <component/section in the view>
 FIGMA:    <value from the design context>
 RENDERED: <value measured by Playwright>
-SEVERITY: <Critical | Major | Minor | Cosmetic>
+SEVERITY: <Critical | Major | Minor | Cosmetic | Accepted>
 FIX:      <specific, one-line code change>
 ```
 
 Example:
 
 ```
-ISSUE:    Card surface is transparent
-LOCATION: igc-card in the "Budget Categories" section
-FIGMA:    background = #222222 (Surfaces table row 1)
+ISSUE:    Section surface is transparent
+LOCATION: .budget-categories wrapper (Phase 1g Table B row "Budget Categories")
+FIGMA:    background = #222222
 RENDERED: backgroundColor = rgba(0, 0, 0, 0)
-SEVERITY: Critical
-FIX:      create_component_theme("card", tokens: { background: "var(--ig-surface-100)" })
-          and apply the generated block — do not set background on a wrapper div.
+SEVERITY: Major
+FIX:      .budget-categories { background: var(--ig-surface-100); }  /* the Table B values */
 
 ISSUE:    Chart series colors are the default palette
 LOCATION: igc-category-chart in the "Spending" panel
@@ -300,11 +281,11 @@ FIX:      chart.brushes = ['#9DE772', '#6DB1FF'] assigned as a property after va
 | Section              | What to check                                                                                                            |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | Top navigation       | Height, background, slotted `start`/`end` content alignment, action icon positions                                       |
-| Sidebar / nav drawer | Width (`--menu-full-width`), `position="relative"` vs modal, item spacing, icon + label alignment, selected state          |
+| Sidebar / nav drawer | Width (`--ig-nav-drawer-size`), `position="relative"` vs modal, item spacing, icon + label alignment, selected state          |
 | Page header          | Typography size and weight, breadcrumb spacing, action button prominence                                                  |
 | Data grid            | Column widths (at least one fluid), header background, row height, cell padding, grid theme CSS actually loaded           |
 | Cards / panels       | **Background** (must not be `rgba(0,0,0,0)` when Figma shows a surface), border, radius, shadow, padding                   |
-| Surface containers   | Every entry in the Phase 1g Surfaces table; children enclosed within the card's bounding rect                             |
+| Surface containers   | Every entry in the Phase 1g Table B; children enclosed within the card's bounding rect                             |
 | Form fields          | `outlined` presence matching the Phase 1d variant; label placement; helper text slot                                      |
 | Action controls      | Count and names vs the Phase 1d inventory; `aria-label` on icon-only buttons                                              |
 | Buttons              | `variant` (flat/outlined/contained/fab), color, typography, padding                                                       |
@@ -358,6 +339,22 @@ igc-calendar {
 
 Choose the multiplier by visual judgment — never by mapping a Figma pixel value.
 
+### Typography correction
+
+Fix the type style, not an internal class. Every type style is a set of `--ig-<style>-<property>` variables on `:root` that the components read (see `design-token-bridge.md § B4`):
+
+```css
+/* Example: the page heading renders at 28px, the design shows 24px. Native <h1> elements
+   get the h1 type style inside an element with the `ig-typography` class. */
+:root {
+  --ig-h1-font-size: 1.5rem; /* 24px */
+}
+```
+
+If the text belongs to a component, find which type style it uses in the component's doc, or use its typography-related design tokens from `theming_get_component_design_tokens`. Or style content you slot into it.
+
+Inside a Lit view's shadow root, document CSS such as `.ig-typography h1` does not reach native headings. Apply the variables in the view's `static styles` yourself, for example `h1 { font-size: var(--ig-h1-font-size); font-weight: var(--ig-h1-font-weight); line-height: var(--ig-h1-line-height); }`.
+
 ### Color correction
 
 ```css
@@ -366,11 +363,8 @@ background: var(--ig-primary-500);
 color: var(--ig-primary-500-contrast);
 ```
 
-Use `get_color({ color: "primary", variant: "500", contrast: true })` when unsure of the
-exact variable name.
+Use `get_color({ color: "primary", variant: "500", contrast: true })` when unsure of the exact variable name.
 
 ### Missing element
 
-If an element is in Figma but absent from the DOM, check in this order: registration
-(`customElements.get`) → import path → the slot name it should occupy → then go back to
-Phase 2 and re-read the component doc. A wrong slot name renders nothing and reports nothing.
+If an element is in Figma but absent from the DOM, check in this order: registration (`customElements.get`) → import path → the slot name it should occupy → then go back to Phase 2 and re-read the component doc. A wrong slot name renders nothing and reports nothing.

package/skills/igniteui-wc-generate-from-image-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
+license: MIT
 name: igniteui-wc-generate-from-image-design
-description: Implement application views from design images using Ignite UI Web Components. Uses MCP servers (igniteui-cli, igniteui-theming) to discover components, generate themes, and follow best practices. Triggers when the user provides a design image (screenshot, mockup, wireframe) and wants it built as a working view with Ignite UI Web Components. Also triggers when the user asks to "implement this design", "build this UI", "convert this mockup", or "create a page from this image" in an Ignite UI Web Components project.
+description: "Implement application views from design images (screenshots, mockups, wireframes) using Ignite UI Web Components, with the igniteui-cli and igniteui-theming MCP servers for component discovery, theme generation, and best practices. WHEN TO USE: the user provides a design image and wants it built as a working view, or asks to 'implement this design', 'build this UI', 'convert this mockup', or 'create a page from this image' in an Ignite UI Web Components project. WHEN NOT TO USE: the design source is a Figma file or URL (use figma-to-app), no image is provided and the user only needs component suggestions (use choose-components), the task is only theming or restyling existing views (use customize-component-theme), or the task is package installation/framework setup (use integrate-with-framework)."
 user-invocable: true
 ---
 

package/skills/igniteui-wc-generate-from-image-design/references/gotchas.md

@@ -98,11 +98,11 @@ Use the Web Components slot anatomy:
 ```
 
 ### Nav drawer width
-Width is controlled by two CSS custom properties exposed on the host — they are **not** design tokens and won't appear in `get_component_design_tokens`. Override them directly:
+Width comes from the `navdrawer` design tokens `size` and `size--mini`, exposed as `--ig-nav-drawer-size` (default 15rem) and `--ig-nav-drawer-size--mini` (default depends on the design system). Set them with `create_component_theme("navdrawer", …)`, or directly:
 ```css
 igc-nav-drawer {
-  --menu-full-width: 280px;  /* default: 240px */
-  --menu-mini-width: 56px;   /* no default — collapses to content width if unset */
+  --ig-nav-drawer-size: 280px;
+  --ig-nav-drawer-size--mini: 56px;
 }
 ```
 

package/skills/igniteui-wc-grids/SKILL.md

@@ -0,0 +1,133 @@
+---
+license: MIT
+name: igniteui-wc-grids
+description: "Set up a data grid with Ignite UI Web Components, including grid selection, single-design-system theming, Shadow DOM theme injection, component registration, fluid layout, and sorting/filtering. WHEN TO USE: adding a grid to a Web Components app, or fixing an unstyled, mis-sized, or broken grid inside a custom element or Shadow DOM, or needing correct package, theme, layout, or sorting/filter setup. WHEN NOT TO USE: general component selection (use choose-components), Grid Lite to premium migration (use migrate-grid-lite-to-premium), framework wiring (use integrate-with-framework), app-wide theming (use customize-component-theme), bundle optimization (use optimize-bundle-size), or non-tabular components such as charts, lists, or tree views."
+user-invocable: true
+---
+
+# Using the Ignite UI for Web Components grids
+
+## Required Workflow
+
+1. **Pick the grid type/package** using the table below; ask if ambiguous.
+2. **Use only the verified import paths in this file** (`igniteui-webcomponents-grids`, `grids/combined.js`, `themes/<variant>/<design>.css`). For anything else (toolbar, export, pivot/tree/hierarchical APIs, properties/events), look it up with `list_components({ framework: "webcomponents", ... })` / `get_doc({ framework: "webcomponents", name: "<doc-name>" })` / `search_api({ platform: "webcomponents", query: "<keyword>" })` / `get_api_reference({ platform: "webcomponents", component: "<ClassName>" })` instead of guessing.
+
+## Choosing the Grid
+
+| Need | Component | Package |
+|---|---|---|
+| Read-only table, sorting/filtering only | `<igc-grid-lite>` | `igniteui-grid-lite` (MIT) |
+| Editing, selection, paging, grouping, summaries, export, toolbar | `<igc-grid>` | `igniteui-webcomponents-grids` (trial) / `@infragistics/igniteui-webcomponents-grids` (licensed; replace the package name in all imports below) |
+| Parent-child, single schema (`managerId`/nested `children`) | `<igc-tree-grid>` | `igniteui-webcomponents-grids` (trial) / `@infragistics/igniteui-webcomponents-grids` (licensed) |
+| Parent-child, different schema per level | `<igc-hierarchical-grid>` | `igniteui-webcomponents-grids` (trial) / `@infragistics/igniteui-webcomponents-grids` (licensed) |
+| Cross-tab / OLAP analysis | `<igc-pivot-grid>` | `igniteui-webcomponents-grids` (trial) / `@infragistics/igniteui-webcomponents-grids` (licensed) |
+
+Never mix `igc-grid-lite` with a premium grid type for the same table — pick one. For upgrading Grid Lite to `igc-grid`, use the migration skill above.
+
+For Grid Lite, import the `igniteui-grid-lite` package and its elements directly. Load only the base Ignite UI theme; do not import the premium grid package or grid theme:
+
+```typescript
+import { IgcGridLite, IgcGridLiteColumn } from 'igniteui-grid-lite';
+import 'igniteui-webcomponents/themes/light/material.css';
+```
+
+## Theming Setup
+
+- **Pick exactly one design system** (`material` | `bootstrap` | `fluent` | `indigo`) **and one variant** (`light` | `dark`) for the whole app. Never load two design systems together, and never load both a light and a dark file at once — toggle between the matching light/dark pair of the *same* design system instead.
+- **For premium grids only** (`igc-grid`, `igc-tree-grid`, `igc-hierarchical-grid`, `igc-pivot-grid`), load both the base theme and the grid theme, same design system + variant — the grid package ships its own theme file for its internal structure (headers, cells, sort/filter icons, resize handles):
+
+  ```typescript
+  import 'igniteui-webcomponents/themes/light/material.css';
+  import 'igniteui-webcomponents-grids/grids/themes/light/material.css';
+  ```
+
+  Path pattern for both packages: `themes/<light|dark>/<material|bootstrap|fluent|indigo>.css` (grid package: `igniteui-webcomponents-grids/grids/themes/...`).
+
+- These are document-level imports — they style the light DOM only. If the grid renders inside a Shadow root, see **Shadow DOM** below; a bare import never crosses into a shadow root.
+
+## Registering Components
+
+For premium grids, register only the selected grid type:
+
+```typescript
+import { IgcGridComponent } from 'igniteui-webcomponents-grids';
+IgcGridComponent.register();
+
+// Base package — register only what you use, not defineAllComponents()
+import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents';
+defineComponents(IgcButtonComponent);
+```
+
+Use the corresponding `Igc*GridComponent.register()` method for tree, hierarchical, or pivot grids. Use `igniteui-webcomponents-grids/grids/combined.js` only when the application intentionally uses all premium grid types.
+
+Built-in grid glyphs (sort direction, filter, expand/collapse) come from the library's internal SVG icon collection and render automatically once the grid module above is registered — no icon font and no manual `registerIcon`/`registerIconFromText` call is needed for them. Only register icons for custom glyphs the app adds itself.
+
+## Shadow DOM
+
+The most common cause of a "broken grid" (e.g. a checkbox expanding to 1000px+ wide) is a Lit component rendering `<igc-grid>` in its own shadow tree without the grid theme reaching that tree. Import the theme as an inline string and inject it as a `<style>` tag in `render()`:
+
+```typescript
+import { html, LitElement } from 'lit';
+import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';
+
+class MyGridPanel extends LitElement {
+  private readonly data: Array<{ name: string }> = [
+    { name: 'Ada Lovelace' },
+  ];
+
+  render() {
+    return html`
+      <style>${gridTheme}</style>
+      <igc-grid .data=${this.data} allow-filtering="true" height="100%">
+        <igc-column field="name" sortable="true" filterable="true"></igc-column>
+      </igc-grid>
+    `;
+  }
+}
+```
+
+The ?inline suffix is Vite-specific. In other bundlers, use their equivalent method for raw-string CSS imports. If the grid looks broken, fix the missing theme injection — do not mask the symptom with fallback CSS overrides.
+
+## Fluid Layout
+
+Let the grid fill its container instead of hardcoding pixel heights:
+
+```css
+.app-shell { display: flex; flex-direction: column; block-size: 100vh; }
+.app-header { flex: 0 0 auto; }                 /* fixed-height header */
+.app-content { display: flex; flex-direction: column; flex: 1 1 auto; min-height: 0; }  /* min-height: 0 lets this row shrink instead of overflow */
+igc-grid { flex: 1 1 auto; min-height: 0; block-size: 100%; }
+```
+
+- The grid still needs a resolvable height for row virtualization — get it from the fluid layout (`100%` of a sized ancestor), not a guessed fixed pixel value on the grid itself.
+- Omit column `width` unless a column needs a fixed size — columns are fluid by default; leave at least one column without `width` to absorb remaining space.
+
+## Sorting & Filtering
+
+```html
+<igc-grid allow-filtering="true" height="100%">
+  <igc-column field="name" sortable="true" filterable="true"></igc-column>
+</igc-grid>
+```
+
+`allow-filtering="true"` on the grid is required for the filtering UI to appear — a column's `filterable="true"` alone has no visible effect. Boolean-looking attributes take quoted string values (`sortable="true"`, not bare `sortable`). For events, remote sort/filter, or programmatic APIs, see the migration skill above (same API whether or not the app is migrating from Grid Lite).
+
+## Verify with a Clean Run
+
+- [ ] No console errors/warnings (missing element definitions, CSS import errors)
+- [ ] Grid fully styled per the chosen design system — no unstyled/browser-default look
+- [ ] Sort/filter icons render as glyphs, not empty boxes or ligature text
+- [ ] Filtering UI is visible; sorting and filtering both work interactively
+- [ ] Grid keeps filling its container on resize — no trailing empty space, no clipped rows
+- [ ] No leftover commented-out theme blocks from an earlier attempt
+
+## Key Rules
+
+1. One design system, one variant, everywhere — never mix design systems or light/dark files.
+2. Always load both the base theme and the grid theme for that same design system + variant.
+3. Inject the grid theme into every Shadow root that renders `<igc-grid>`/`<igc-tree-grid>`/`<igc-hierarchical-grid>`/`<igc-pivot-grid>`.
+4. Register only the selected grid type and components actually used — no `defineAllComponents()`, no "just in case" bundles.
+5. Never guess deep import paths or APIs beyond what's verified here — look them up.
+6. Fluid layout by default: `min-height: 0` + `flex`/`grid` sizing; fixed pixel heights only when explicitly required.
+7. `allow-filtering="true"` on the grid + `sortable`/`filterable` per column to enable sorting/filtering UI.
+8. Fix root causes (missing theme/registration) instead of papering over symptoms with fallback CSS.

package/skills/igniteui-wc-integrate-with-framework/SKILL.md

@@ -1,6 +1,7 @@
 ---
+license: MIT
 name: igniteui-wc-integrate-with-framework
-description: Integrate Ignite UI Web Components packages into React, Angular, Vue, or vanilla JS applications with framework-specific configurations
+description: "Install and integrate Ignite UI Web Components packages into React, Angular, Vue 3, LitElement, or vanilla JS/HTML apps, detecting the framework and applying framework-specific setup (package choice, component registration, theme imports, schemas/config, events and property binding). WHEN TO USE: the user wants to add Ignite UI Web Components or igniteui-react to a project, set up a new app with them, fix registration/'unknown element' errors, or needs framework-specific wiring for templates, events, or forms. WHEN NOT TO USE: picking which components to use (use choose-components), customizing themes or styles (use customize-component-theme), trimming bundle size or import granularity (use optimize-bundle-size), building a view from a design (use generate-from-image-design or figma-to-app), or projects using Ignite UI for Angular/Blazor native packages instead of Web Components."
 user-invocable: true
 ---
 

package/skills/igniteui-wc-migrate-grid-lite-to-premium/SKILL.md

@@ -1,6 +1,7 @@
 ---
+license: MIT
 name: igniteui-wc-migrate-grid-lite-to-premium
-description: Step-by-step migration guide from igniteui-grid-lite (IgcGridLite) to the premium igniteui-webcomponents-grids (IgcGridComponent), covering every import, class name, HTML tag, property, event, template, sorting, filtering, and theming API change.
+description: "Step-by-step migration from igniteui-grid-lite (IgcGridLite, <igc-grid-lite>) to the premium igniteui-webcomponents-grids data grid (IgcGridComponent, <igc-grid>), covering imports, class names, HTML tags, properties, events, templates, sorting, filtering, remote data, and theming API changes. WHEN TO USE: the user wants to upgrade from Grid Lite to the premium grid, or needs enterprise features Grid Lite lacks (editing, selection, paging, grouping, summaries, Excel export, state persistence). WHEN NOT TO USE: starting a new grid from scratch (use choose-components), migrating between other grids (Tree Grid, Hierarchical Grid, Pivot Grid) or across major versions of the same package, the project uses igniteui-angular or Blazor grids, or the user only needs theming (use customize-component-theme)."
 user-invocable: true
 ---
 

package/skills/igniteui-wc-optimize-bundle-size/SKILL.md

@@ -1,6 +1,7 @@
 ---
+license: MIT
 name: igniteui-wc-optimize-bundle-size
-description: Optimize application bundle size by importing only necessary components and using tree-shaking effectively
+description: "Reduce application bundle size with Ignite UI Web Components by registering only needed components via named imports from the package root with defineComponents instead of defineAllComponents, lazy-loading heavy components, and verifying tree-shaking with bundle analysis. WHEN TO USE: the user reports a large bundle or slow load, asks how to import components individually, wants to lazy-load grids, charts, or dock manager, or needs to audit Ignite UI imports in Vite/webpack/Rollup builds. WHEN NOT TO USE: initial package installation or framework wiring (use integrate-with-framework), choosing components (use choose-components), theming (use customize-component-theme), or general performance issues unrelated to bundle size such as runtime rendering or data virtualization."
 user-invocable: true
 ---