docs: add frontmatter audit skill and refine topic guidelines

.ai/skills/igniteui-doc-topics/SKILL.md

@@ -92,31 +92,43 @@ cheat-sheet's "two classic confusions" section explains the reasoning.
    for React/WC/Blazor using `{Platform}`/`{ProductName}` tokens and `<PlatformBlock for="…">`. Load
    the relevant details from `house-style.md`.
 3. **Follow the verification workflow** in `house-style.md` before writing technical content.
-   Existing snippets and old prose are clues, not authority.
+   Existing snippets and old prose are clues, not authority. For component topics, also inspect the
+   matching Indigo.Design component documentation under
+   `https://www.infragistics.com/products/indigo-design/help/components/` and use its component
+   structure as input for Usage subsection suggestions.
 4. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`,
    `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component
    has close siblings (this lets **Usage**'s final **Do/Don't** subsection name the specific
    sibling instead of speaking generically).
 5. **Lay out the canonical sections** in order for that topic type, required ones always present.
    Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections.
 6. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put
-   reference in tables. In **Usage**, start with a basic declaration and then add property-focused
-   sub-sections so every public input is shown with a minimal snippet; group only tightly coupled
-   properties that form one behavior. End **Usage** with `### Do/Don't`, using inline **When to use:**
-   and **When not to use:** labels rather than nested headings. Embed exactly one top `<Sample>`, then
-   Usage samples only for distinct tasks (soft max 5/page). Phrase Do/Don't and Troubleshooting as
-   the reader's real questions.
+   reference in tables. In **Usage**, add property-focused sub-sections so every public input is
+   shown with a minimal snippet; group only tightly coupled properties that form one behavior. Keep
+   existing useful subsections, then compare against Indigo.Design's component sections by meaning,
+   not by exact heading name, to suggest or add any missing runtime-relevant Usage subsections.
+   End **Usage** with `### Do/Don't`, using inline **When to use:**
+   and **When not to use:** labels rather than nested headings, plus the matching guidance image
+   from the Indigo.Design documentation or a `{/* TODO */}` marker when the asset is not available.
+   Add a required `## Live Demo` section
+   with exactly one top `<Sample>`, then Usage samples only for distinct tasks (soft max 5/page).
+   Phrase Do/Don't and Troubleshooting as the reader's real questions.
 7. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and
    metadata (D-checks). Fix, then deliver the `.mdx`.
 
 ## Audit workflow
 
 1. **Classify** the topic and identify its doc set (Angular vs xplat) and type.
 2. **Follow the verification workflow** in `house-style.md` before judging technical content.
-   Old snippets/prose are never the source of truth by themselves.
+   Old snippets/prose are never the source of truth by themselves. For component topics, inspect the
+   matching Indigo.Design component documentation and compare its structure to the topic's Usage
+   subsections by semantic content, not heading text, before making Usage-coverage suggestions.
 3. **Run every check** in `references/audit-rubric.md` — structure/order (A), naming (B), Diátaxis
    mode integrity (C), metadata/AI-readiness and correctness (D), samples/links (E), formatting and
    snippet currency (F). For mode integrity, run the compass on each section and flag drift.
+   For detailed frontmatter-only audits or normalization, use the companion
+   `igniteui-topic-frontmatter` skill; for full topic audits, apply only the basic metadata checks
+   here unless the user asks for frontmatter suggestions.
 4. **Report** in the rubric's exact format: Verdict → Summary → Findings (each with Where / Issue /
    Principle / Fix) → Quick wins. Order findings Error → Warning → Suggestion.
 5. Keep every **Fix** concrete and applyable (the corrected heading, the sentence to move, the table

.ai/skills/igniteui-doc-topics/references/audit-rubric.md

@@ -13,18 +13,21 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi
 ## Checks
 
 ### A. Structure & order
-- A1 (Error) A required section is missing (Live Demo, Anatomy, Getting Started, Usage,
+- A1 (Error) A required section is missing (`## Live Demo`, Anatomy, Getting Started, Usage,
   Properties, Accessibility, API References, Additional Resources on a component
   topic).
 - A2 (Warning) Sections are present but out of the canonical order.
 - A3 (Warning) A conditional section sits in the wrong slot.
 - A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**,
   including a top-level `## Do/Don't`.
-- A5 (Error) **Live Demo** is missing near the top of the topic or appears after **Anatomy**.
-- A6 (Suggestion) >10 live samples on one page (soft cap) — consider splitting. Up to 10 is fine;
+- A5 (Error) `## Live Demo` is missing near the top of the topic, appears after **Anatomy**, or the
+  top preview `<Sample>` is left as a bare block instead of living inside the `## Live Demo` section.
+- A6 (Suggestion) >5 live samples on one page (soft cap) — consider splitting. Up to 5 is fine;
   only flag when a page clearly sprawls past that.
-- A7 (Warning) **Usage** does not end with `### Do/Don't`, or **When to use:** / **When not to use:**
-  are written as nested headings instead of inline labels inside that subsection.
+- A7 (Warning) **Usage** does not end with `### Do/Don't`, **Do/Don't** is missing the
+  Indigo.Design guidance image or a `{/* TODO */}` marker for the not-yet-available asset, or
+  **When to use:** / **When not to use:** are written as nested headings instead of inline labels
+  inside that subsection.
 - A8 (Warning) **Anatomy** is incomplete: missing its opening screenshot/GIF (or a `{/* TODO */}`
   marker for a not-yet-available asset), or missing the verified DOM tree / skeleton.
 - A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections —
@@ -56,12 +59,17 @@ Run the compass on each section; flag content that has drifted out of the sectio
 - C6 (Warning) **Styling content inside Usage** (CSS-var overrides, `color`/background
   snippets) — move to the **Styling** section; Styling should also open with a `<Sample>` of the result.
 - C7 (Warning) **Usage doesn't cover every public input** with a property-focused sub-section and
-  minimal snippet, omits `### Basic Declaration`, or documents each option in isolation instead of
+  minimal snippet, or documents each option in isolation instead of
   grouping tightly coupled properties and stating the behavioral relationship once (e.g. the
   content-type priority).
 - C8 (Warning) **Usage**'s **Do/Don't** drifts into another mode — install/code steps (belongs in Getting
   Started/Usage), an exhaustive option table (belongs in Properties), or conformance claims (belongs
   in Accessibility) instead of do/don't guidance.
+- C9 (Suggestion) **Usage subsection opportunities from Indigo.Design** — the matching
+  Indigo.Design component topic has a section whose meaning maps to a real Ignite UI API, slot,
+  state, layout pattern, or verified sample, but the topic does not cover it. Compare by semantic
+  content rather than heading text, and do not flag Figma-only structure that belongs in Anatomy or
+  Styling instead of Usage.
 
 ### D. Metadata & AI-readiness
 - D1 (Warning) `relatedComponents` is set but **Usage**'s **Do/Don't** guidance doesn't name the

.ai/skills/igniteui-doc-topics/references/house-style.md

@@ -26,7 +26,7 @@ Topics are **Astro `.mdx`**. Frontmatter is YAML. Observed + target fields:
 
 ```yaml
 ---
-title: "Angular Star Rating Component – Ignite UI for Angular - MIT license"   # SEO title
+title: "Star Rating | Ignite UI for Angular"   # SEO title: {Component} | Ignite UI for {Framework}
 description: "…"           # <=~160 chars, shaped as an answer ("X is a … that …")
 keywords: "…"              # comma-separated
 license: MIT
@@ -39,6 +39,9 @@ relatedComponents: [Toast, Banner]   # TARGET field — drives the Usage Do/Don'
 
 - **`llms.description`** already exists in both sets and is high-value — write it as a crisp,
   self-contained answer sentence. It is *not* optional filler.
+- **`title`** uses the SEO pattern `{Component} | Ignite UI for {Framework}`. Avoid duplicating the
+  framework in the component phrase when the product phrase already names it (`Avatar | Ignite UI for
+  React`, not `React Avatar | Ignite UI for React`).
 - **`relatedComponents`** is the revision-2 trigger and is **not yet in the repo**. When authoring to
   target, set it. When auditing, treat a missing-but-warranted value as a finding, and a set value
   with no **Usage** → **Do/Don't** guidance as a hard error.
@@ -47,9 +50,10 @@ relatedComponents: [Toast, Banner]   # TARGET field — drives the Usage Do/Don'
 
 ```mdx
 import Sample from 'igniteui-astro-components/components/mdx/Sample.astro';
+import { Image } from 'astro:assets';  // when embedding repo-owned images
 import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro';
 import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro';
-import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro';  # xplat only
+import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro';  // xplat only
 ```
 
 ## Per-framework mechanics
@@ -135,10 +139,10 @@ under **Usage**, never a new top-level section.
 | # | Section (`##`) | Required? | Diátaxis mode | Contents |
 |---|---|---|---|---|
 | 1 | *Title + one-line definition* (`#` + lead ¶) | required | orient / reference | H1 is **`‹Component› Component`** — **no** framework prefix, **no** "Overview" suffix (the framework lives in the SEO `title`). Follow with one plain sentence: what it is, what problem it solves. Mirror `llms.description`. |
-| 2 | *Live Demo* | required | demonstration (action) | `<Sample>` of the simplest useful state near the top of the page, before **Anatomy**. |
+| 2 | **Live Demo** | required | demonstration (action) | A `## Live Demo` section containing exactly one `<Sample>` of the simplest useful state, before **Anatomy**. Keep this section sample-only unless a one-sentence setup is truly needed. |
 | 3 | **Anatomy** | required for component topics | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image, but still include the section and verified skeleton. |
 | 4 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. |
-| 5 | **Usage** | required | how-to + explanation | Start with `### Basic Declaration`, showing the smallest valid component markup for each platform. Then add property-focused sub-sections that showcase every public input with a minimal snippet and, when a verified demo exists and adds visual value, a `<Sample>`. Give standalone properties their own sub-section (`Shape`, not `Avatar Shape`); group only tightly coupled properties that form one behavior (for example, content-source priority such as `src`, `alt`, `initials`, and default slot content). The final Usage subsection must be `### Do/Don't`; it uses inline **When to use:** and **When not to use:** labels, not nested headings. Styling content belongs in **Styling**, not here. |
+| 5 | **Usage** | required | how-to + explanation | Add property-focused sub-sections that showcase every public input with a minimal snippet and, when a verified demo exists and adds visual value, a `<Sample>`. Give standalone properties their own sub-section (`Shape`, not `Avatar Shape`); group only tightly coupled properties that form one behavior (for example, content-source priority such as `src`, `alt`, `initials`, and default slot content). The final Usage subsection must be `### Do/Don't`; it uses inline **When to use:** and **When not to use:** labels, not nested headings, and includes the matching guidance image from the Indigo.Design documentation or a `{/* TODO */}` marker when the asset is not available. Styling content belongs in **Styling**, not here. |
 | 6 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) |
 | 7 | **Methods** | conditional | reference | Table of callable actions. |
 | 8 | **Events** | conditional | reference | Table of emitted events. |
@@ -150,10 +154,13 @@ under **Usage**, never a new top-level section.
 | 14 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. |
 
 **When Not to Use trigger:** every component topic ends **Usage** with `### Do/Don't`. This subsection
-must include inline **When to use:** and **When not to use:** labels, not nested headings. When
-`relatedComponents` is non-empty, **When not to use:** must name the specific better-fit sibling(s)
-by name and link them; when it's empty (standalone primitives like Badge/Divider), **When not to
-use:** states the boundary without inventing a sibling.
+must include the matching guidance image from the Indigo.Design documentation before the guidance
+text. Use a repo-owned image import with `<Image>`; if the visual asset does not exist yet, leave a
+`{/* TODO */}` marker rather than a broken image. The subsection must also include inline **When to
+use:** and **When not to use:** labels, not nested headings. When `relatedComponents` is non-empty,
+**When not to use:** must name the specific better-fit sibling(s) by name and link them; when it's
+empty (standalone primitives like Badge/Divider), **When not to use:** states the boundary without
+inventing a sibling.
 
 **Reference-table contract:** Properties / Methods / Events tables are **generated from the same typed
 API source** as the full reference — not hand-typed. Inline tables = the core knobs for fast scanning;
@@ -162,17 +169,33 @@ hand-write or invent rows:** emit the fixed column headers (`name · type · def
 single build-injection note, and leave the row values to the generator. Inventing a plausible property
 or event name is exactly the failure this contract exists to prevent.
 
-**Usage coverage contract:** begin with `### Basic Declaration`, then use property-focused
-sub-sections to demonstrate every public input. Prefer one sub-section per standalone property; group
+**Usage coverage contract:** use property-focused sub-sections to demonstrate every public input.
+Prefer one sub-section per standalone property; group
 properties only when they are inseparable in real use or define a shared precedence/behavior. Each
 sub-section should include a minimal, copyable snippet for every platform it affects. Add a
 `<Sample>` only when the demo path is verified and the visual result teaches something the snippet
 alone does not.
 
-**Live-sample contract:** exactly one top preview; add Usage samples only for distinct,
+**Indigo.Design Usage suggestions:** for every component topic, inspect the matching Indigo.Design
+component documentation under `https://www.infragistics.com/products/indigo-design/help/components/`
+before finalizing or auditing the **Usage** structure. Extract the Indigo.Design component outline
+(typically the H2/H3 sections after the demo) and map it to Ignite UI by **meaning**, not by exact
+heading text. A section named `Image` may become `Media`; `Card Layout` may become `Layout`;
+`Item Content Template` may become `Content`; and a Figma-only `Areas` section may belong in
+**Anatomy** instead of **Usage**. Keep useful existing Usage subsections, then suggest or add missing
+subsections only when the Indigo.Design section corresponds to a real Ignite UI API, slot, state,
+layout pattern, or verified sample. Do not copy Figma-only implementation details into runtime docs;
+translate them into the closest verified Ignite UI behavior, or leave them as suggestion-level notes.
+If the Indigo.Design topic or asset cannot be reached, state that limitation and continue from the
+verified Ignite UI API/source.
+
+**Live Demo contract:** every component topic has a `## Live Demo` section immediately after the
+intro and before **Anatomy**. It contains exactly one top preview `<Sample>` of the simplest useful
+state so the page table of contents exposes the demo as a navigable section. Do not leave the top
+sample as a bare block between the intro and Anatomy. Add Usage samples only for distinct,
 user-facing tasks or property-focused behaviors (selection, editing, sorting, validation,
-templating, styling, shape, content, sizing). Soft max **10 samples/page**; up to 10 is fine, and
-only clear sprawl past that warrants splitting into focused topics.
+templating, styling, shape, content, sizing). Soft max **5 samples/page**; up to 5 is fine, and only
+clear sprawl past that warrants splitting into focused topics.
 
 ### `<Sample>` configuration — pick the props deliberately
 
@@ -199,7 +222,7 @@ Choose the display config from **what the sample is showing**, not by habit:
 | `lob` / `dv` / `crm` | default base | The demo lives in the LOB, Data-Viz, or CRM demos app rather than the default — **verify before setting**. |
 
 Defaults are right for most Usage samples: `<Sample src="…" height={…} alt="…" />`. Reach for the extra props
-only when the component type calls for it — the top preview and standard task demos keep the code tabs (no
+only when the component type calls for it — the `## Live Demo` preview and standard task demos keep the code tabs (no
 `iframeOnly`); the **Styling** section still opens with a styled-result `<Sample>`, using `iframeOnly` only
 when its styling isn't shown as copyable code.