Updating production from staging

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

@@ -0,0 +1,142 @@
+---
+name: igniteui-doc-topics
+description: >-
+  Author or audit Ignite UI documentation topics — component pages, how-to guides, conceptual
+  overviews, and category indexes — for both the Angular doc set and the cross-platform (React /
+  Web Components / Blazor) doc set. Applies the Diátaxis framework mapped onto Ignite UI's house
+  templates: canonical section order, fixed heading names, frontmatter (including `llms.description`
+  and the `relatedComponents` trigger), `.mdx` sample embeds, and per-framework token/PlatformBlock
+  mechanics. Use this whenever someone asks to write, draft, create, review, audit, fix, or
+  standardize a documentation topic, tutorial, guide, reference page, or concept overview for Ignite
+  UI — even if they just say "write docs for the X component" or "review this topic" without naming
+  Diátaxis or the templates. Also use it when deciding what *kind* of documentation a page should be,
+  or when a topic mixes tutorial / how-to / reference / explanation content that should be separated.
+---
+
+# Ignite UI doc topics
+
+Write and audit Ignite UI documentation topics so every page has the same predictable shape — easy
+for developers to read and for AI assistants to answer from. The engine is **Diátaxis** (four
+documentation modes) applied through **Ignite UI's house templates**.
+
+## Two modes of operation
+
+- **Create** — draft a new topic (component, concept/guide, or category/index) to the standard.
+- **Audit** — review an existing topic against the standard and return an issues-and-fixes report.
+
+Detect which from the request ("write/draft/create" → Create; "review/audit/check/fix/standardize" →
+Audit). If a topic file or content is supplied, default to Audit unless they ask for a rewrite.
+
+## Reference files — load what the task needs
+
+- `references/diataxis-cheatsheet.md` — the four modes + the compass. Load when classifying a topic
+  or diagnosing mode-bleed.
+- `references/house-style.md` — sections, order, naming, frontmatter, sample/token mechanics, both
+  doc sets. Load for **every** create or audit.
+- `references/audit-rubric.md` — the checkable rules + report format. Load for **every** audit.
+
+Read `house-style.md` before writing or judging any topic — it carries the mechanical details
+(frontmatter fields, `<Sample>`/`<PlatformBlock>` syntax, Angular-vs-xplat differences) that aren't
+in this file.
+
+## Step 0 — Classify with the compass (always first)
+
+Before writing or auditing, decide what *kind* of documentation the page is, using the compass from
+the cheat-sheet:
+
+> **action or cognition?**  ×  **acquisition (study) or application (work)?**
+> → tutorial · how-to · reference · explanation
+
+- A **component page** is a *composite* (see below).
+- A **concept / guide overview** is **explanation**.
+- A **category / index overview** is **reference/navigation** (a map).
+- A standalone **"How to …" article** is a **how-to guide** — keep it single-mode.
+
+If a request is ambiguous ("document X"), state which topic type you're producing and why, in one
+line, before proceeding.
+
+## The composite-topic principle (the heart of this skill)
+
+Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics
+deliberately don't** — one page carries a live demo, a how-to (Getting Started/Usage),
+decision guidance in Usage's final Do/Don't subsection, and reference tables
+(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule
+that makes it work:
+
+> **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a
+> second mode wants in, move it to the section that owns it and cross-link.
+
+Section → mode map (full contents in `house-style.md`):
+
+| Section | Mode | Stays out of |
+|---|---|---|
+| Live Demo | demonstration (action) | prose/explanation |
+| Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps |
+| Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists |
+| Usage → Do/Don't | **explanation** | install steps, code, API detail |
+| Properties / Methods / Events | **reference** | instructions, opinion |
+| Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays |
+| Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims |
+| Troubleshooting | how-to (cause → fix) | background theory |
+| API References / Dependencies / Additional Resources | reference / navigation | new teaching |
+
+Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to Do/Don't or a concept
+topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table
+descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The
+cheat-sheet's "two classic confusions" section explains the reasoning.
+
+## Create workflow
+
+1. **Classify** (Step 0). Name the topic type.
+2. **Pick the doc set & framework.** Angular set = its own file, plain prose. xplat set = one file
+   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.
+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.
+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.
+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.
+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
+   to add). If the topic is already clean, say so and note what it does well — don't invent problems.
+
+## Grounding notes
+
+- The live `vnext` repo is **pre-standardization**: expect drifted headings (`## Angular Rating
+  Example`, `## Configuration`) and a missing `relatedComponents` field. Author to the **target**
+  standard; audit against it while recognizing current reality.
+- **Invent no verifiable identifier (zero-risk rule).** Never emit a guessed tag, class, package,
+  property, method, event, CSS part, or theming variable — a plausible-but-wrong name a reader copies is
+  worse than a visible gap. Use an identifier only when verified (typed API source, an existing topic,
+  or the user); otherwise write `‹VERIFY: …›`. For Properties/Methods/Events, emit the fixed column
+  headers plus a build-injection note and leave the rows to the generator. React/Blazor wrapper symbols
+  resolve to the `igc` core — prefer verified `igc` usage and mark unconfirmed wrapper names `‹VERIFY:…›`.
+  (Full detail in `house-style.md` → "Never fabricate API identifiers".)
+- Prefer paraphrase and the standard section names over copying any existing topic's prose verbatim.
+- **Write in one voice and verify every claim** (see house-style → *Voice & tone* and *Verify every
+  claim against the component*): instruct in the imperative/second person, and check every factual
+  statement — defaults, behavior, version support, DOM — against the MCP/API-doc source, the official
+  platform API docs, typed source when needed, or official framework docs before writing it or
+  recommending it as an edit. Don't "correct" prose into a plausible claim you haven't verified.