Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .ai/skills/igniteui-doc-topics/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,32 @@ cheat-sheet's "two classic confusions" section explains the reasoning.
7. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and
metadata (D-checks). Fix, then deliver the `.mdx`.

### Category/index topics use a separate structure

Do not apply the component-topic blueprint to a category or index page. A category overview is a
reference/navigation map, not a composite component page. Its structure is:

1. `#` title followed by a one-line definition.
2. `## Key Features` immediately after the title and definition. Open with a short sentence, then present
the category's capabilities in a compact table with `Feature`, `Description`, and `Benefits`
columns when the content is naturally scannable. Use `## Types` or `## Members` as a top-level
navigation section when the category maps component types. Make `Types` the parent navigation
section and make each
concrete type, such as `{Platform} Data Grid`, `{Platform} List`, or `{Platform} Tree Grid`, a
separate navigable `###` subsection beneath it. Include a verified `<Sample>` for every type
entry, together with a concise definition and verified link. Additional
feature groups can follow as subsections inside `Key Features`.
3. `## Next Steps`.
4. `## API References`.
5. `## Additional Resources`.

Do not add component-only `When to Use`, `When Not to Use`, `Live Demo`, `Getting
Started`, `Usage`, `Properties`, `Accessibility`, or `Troubleshooting` sections
to the category introduction. Put selection guidance in the category definition or the relevant
type/member entry, and put each demo inside the entry it demonstrates. Supporting content such as
browser support, support options, licensing, and FAQ belongs after the navigation sections as
subsections of the page's main structure, not as additional top-level category sections.

## Audit workflow

1. **Classify** the topic and identify its doc set (Angular vs xplat) and type.
Expand Down
11 changes: 11 additions & 0 deletions .ai/skills/igniteui-doc-topics/references/audit-rubric.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,17 @@ concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fi

## Checks

### Category/index exception
Classify the topic before applying the checks below. A category/index page is evaluated against the
category blueprint in `house-style.md`, not the component-topic checklist. Do not report missing
component sections such as `Live Demo`, `Getting Started`, `Usage`, or `Accessibility`
when the page follows `Key Features` (with a short intro and a `Feature` / `Description` /
`Benefits` table) → top-level `Types/Members` section with each concrete type as its own
navigable `###` child subsection and a verified sample → `Next Steps` → `API References`
→ `Additional Resources`. Report component-topic sections in the category introduction as
information-architecture drift instead. Browser support, support options, licensing, and FAQ may be
subsections after the navigation sections and should not be required as top-level sections.

### A. Structure & order
- A1 (Error) A required section or subsection is missing (`## Live Demo`, Anatomy, Getting Started
with `### Prerequisites and Version Compatibility`, Usage, Properties, Accessibility,
Expand Down
15 changes: 13 additions & 2 deletions .ai/skills/igniteui-doc-topics/references/house-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,8 +293,19 @@ Title + intro → **Overview** → **Before You Start** → **Next Steps** → *
accordion for FAQ content when a compact question-and-answer block is useful.

**5b. Category / index overview** (Diátaxis: *reference/navigation* — a map) — e.g. "Charts overview":
Title + intro → **Key Features** → **Types** (identical micro-structure per entry: one-line def + link + small
`<Sample>`) → **Next Steps** → **API References / Additional Resources**.
The page uses **Key Features** immediately after the title and definition (open with a short intro and a compact `Feature` / `Description` /
`Benefits` table) → top-level **Types / Members** section when the category maps component
types. Each concrete type/member, such as `{Platform} Data Grid`, `{Platform} List`, or
`{Platform} Tree Grid`, is its own navigable `###` child subsection with a concise definition,
verified link, and a verified `<Sample>` for every entry) → additional feature
subsections as needed → **Next Steps** → **API References** → **Additional Resources**.

The category introduction must not use the component-topic sequence `When to Use`,
`When Not to Use`, `Live Demo`, `Getting Started`, `Usage`, `Properties`,
`Accessibility`, or `Troubleshooting`. Selection guidance belongs in the category definition or in
the relevant type/member entry, and a demo belongs inside the entry it demonstrates. Supporting
content such as browser support, support options, licensing, and FAQ follows the navigation sections
as subsections of the page's main structure; do not make each one a new top-level category section.

Guardrails: cap each section at ~3 short paragraphs (else add sub-sections); isolate marketing copy in
a single "Why {ProductName}" section — never thread it through instructional content.
Expand Down
Loading
Loading