docs-style-lint

name: docs-style-lint description: Reviews and lints Avalonia documentation pages against house style rules, content boundaries, anti-marketing standards, accessibility, and SEO. Use when reviewing, editing, or writing documentation to ensure consistency with established patterns. Checks structure, voice, terminology, formatting, linking, tone, Diataxis compliance, image accessibility, meta descriptions, and jargon simplification.

Avalonia Docs Style Lint

Review documentation pages against Avalonia's house style rules derived from corpus analysis of professional .NET framework documentation, adapted for Avalonia's Docusaurus-based site.

Diataxis as invisible discipline

Diataxis is an editorial QA layer, not a navigation structure. The visible site structure follows product domains and user journeys (Getting Started, Controls, Styling, Layout, Binding, MVVM). Each page declares a doc-type in frontmatter, and that type constrains what content is allowed and forbidden. This prevents the "duplication swamp" where every page re-explains everything. If doc-type is present, use it. If absent, infer the type and flag BOUND-005.

Diataxis defines exactly four canonical types (tutorial, how-to, reference, explanation) derived from two dimensions: action/cognition and acquisition/application. The Avalonia docs also use four project-specific types (overview, troubleshooting, release-notes, migration) that are specializations of the canonical four, not additional Diataxis categories.

Technical accuracy (non-negotiable)

This skill must NEVER fabricate, invent, or guess technical details. Every API name, property, method, event, enum value, parameter, and behavioral claim in documentation must be verified against the actual Avalonia API reference before it can appear in output. When in doubt, look it up; never assume.

Three hard rules:

1. ACCU-001 (blocker): Never fabricate technical details. All API names, property names, method signatures, event names, enum values, and behavioral claims must be verified. Do not invent, guess, or hallucinate any technical detail. If you cannot verify a technical claim, flag it as unverified rather than asserting it.

2. ACCU-002 (blocker): Never modify existing code snippets unless the user has expressly asked for code changes. When linting or reviewing documentation, flag prose issues but leave all code blocks (``` fenced blocks and ` inline code) exactly as they are. Code changes require explicit user authorization.

3. ACCU-003 (blocker): Validate all API mentions against the Avalonia API reference. Use the lookup_avalonia_api tool from the Avalonia Docs MCP server to confirm that every class, property, method, event, or enum value referenced in the documentation actually exists. Any API reference that cannot be validated must be flagged in the lint report as ACCU-003: Unverified API reference. See Avalonia Build MCP for MCP tool documentation.

When to use

• Reviewing a documentation page before publishing
• Writing new documentation content
• Editing or improving existing pages
• Auditing a section for style consistency

Inputs

• $ARGUMENTS: Path to the file(s) to lint, or "all" to scan changed files

Workflow

Step 1: Identify page type

Read the target file and classify it as one of the page archetypes defined in page-templates.yaml:

If the page has a doc-type frontmatter field, use that value. If doc-type is absent, infer the type from the signals above and flag BOUND-005.

Diataxis compass (use when surface signals are ambiguous):

1. Does this content inform action (doing) or cognition (thinking)?
2. Does it serve acquisition (study/learning) or application (work/goals)?

Step 2: Run structural checks

Apply rules from house-rules.yaml that match the page type scope.

Blocker-level checks (must pass):

1. STR-001: Exactly one H1 heading (Docusaurus renders frontmatter title as H1, so an explicit # heading in the body is not required; count the frontmatter title as the H1)
2. STR-003: Tutorials have ## Prerequisites before first procedure
3. MIC-003: All fenced code blocks specify a language tag
4. LINK-001: No generic link labels (click here, here, this link)
5. QUAL-001: Tutorials include an outcome verification section
6. MIC-006: No em dashes or en dashes anywhere in the text
7. ACCU-001: No fabricated technical details (all API names, properties, methods, events, and behavioral claims must be real)
8. ACCU-002: No modifications to existing code snippets unless expressly requested by the user
9. ACCU-003: All API references validated against the Avalonia API reference via lookup_avalonia_api MCP tool

Major-level checks (should pass; justify exceptions):

10. STR-002: Headings use sentence case (>= 80% for new/edited pages)
11. STR-005: Page ends with ## See also or ## Related content or similar navigation handoff
12. VOI-001: Task pages use direct you/your address
13. VOI-002: Minimal we/our/us usage (< 1 per 1,000 words). Exception: tutorials use we to establish the instructor-learner bond (per Diataxis). VOI-002 does not apply to tutorials.
14. MIC-001: UI labels and menu paths in bold
15. MIC-002: Code identifiers and API literals in backticks
16. MIC-004: Admonitions use approved Docusaurus types only: :::note, :::tip, :::info, :::caution, :::danger
17. TERM-002: Use control not widget for UI components

Minor-level checks (style drift warnings):

18. VOI-003: Intensifiers (simply, obviously, just) are rare (< 1 per 1,000 words)
19. MIC-005: Keyboard shortcuts use <kbd> tags with platform-native symbols (e.g., <kbd>⌘</kbd> <kbd>S</kbd> not plain text "Cmd+S")
20. STR-009: Intro before first H2 is <= 150 words
21. ACC-001: All images have non-empty alt text (![description](path), not ![](path))
22. SEO-001: Frontmatter description present, 50-160 characters, no marketing buzzwords
23. SEO-002: Frontmatter title is <= 60 characters
24. QUAL-003: On task pages (tutorial, how-to, troubleshooting, migration), average sentence length <= 25 words; flag individual sentences over 40 words
25. QUAL-004: ARI (Automated Readability Index) score <= 14 across all prose. Calculate using 4.71 × (characters ÷ words) + 0.5 × (words ÷ sentences) - 21.43. Strip all fenced code blocks, inline code spans, frontmatter, and admonition markers before counting, measure prose only. Report score to one decimal place with the grade-level label (8 or below = high-school, 9-12 = standard adult, 13-14 = college, above 14 = graduate). Scores above 14 are a warning to simplify sentence structure and word choice.

Step 3: Run anti-marketing checks

Apply tone rules from house-rules.yaml. Documentation must never read like marketing copy.

Blocker-level:

1. TONE-001: Scan for banned marketing buzzwords (powerful, seamless, elegant, best-in-class, world-class, cutting-edge, game-changing, leverage, unlock, empower, delightful, blazing fast, robust, state-of-the-art, next-generation, revolutionary, groundbreaking, innovative). Context-dependent terms (leverage, unlock, robust, innovative) are flagged as candidates for reviewer judgment. See terminology-map.yaml for replacements.
2. TONE-002: Flag unsupported superlatives (the fastest, the most, the best, the only, unmatched, unparalleled). Pass only if measurable evidence appears in the same sentence or paragraph.

Major-level:

3. TONE-003: Flag promotional framing. Pages should describe what a feature does, not why the reader should be excited about it.
4. TONE-004: Flag vague future promises. Any future-tense claim must include a version number, issue link, or timeline.

Step 4: Run terminology checks

Cross-reference against terminology-map.yaml:

• Verify canonical terms are used (not forbidden synonyms)
• Check first-use acronym expansion (TERM-001)
• Verify must vs should usage matches intent (TERM-003)
• Check for forbidden marketing terms and suggest replacements
• TERM-004: On introductory pages (tutorials, overviews), verify that Avalonia-specific jargon (visual tree, logical tree, data template, control theme, style selector, binding expression, value converter, content presenter, items presenter, template part, pseudo-class) is explained inline or linked on first use. See framework_jargon in terminology-map.yaml for definitions and link targets.

Step 5: Validate API references (ACCU-003)

Extract all Avalonia API mentions from the page: class names, property names, method names, event names, enum values, and any other identifiers presented as part of the Avalonia API surface.

For each API mention:

1. Call lookup_avalonia_api (from the Avalonia Docs MCP server) with the API identifier (e.g., TextBlock, Window.Show, StyledProperty, Control.PointerPressed).
2. If the tool confirms the API exists, mark it as verified.
3. If the tool returns no match or an error, flag it as ACCU-003: Unverified API reference at blocker severity.

Important constraints:

• Do NOT skip this step. Every API reference in documentation must be validated.
• Do NOT assume an API exists because the name sounds plausible. LLMs frequently generate plausible-but-incorrect API names.
• If the page contains code snippets, validate API identifiers used in the code but do NOT modify the code (ACCU-002).
• Group related lookups where possible (e.g., look up a class once, then check its members) to minimize tool calls.
• When a page references many APIs, prioritize validating: (a) APIs central to the page's purpose, (b) APIs that appear only once (higher risk of error), (c) recently added or changed APIs.

MCP tool reference: The lookup_avalonia_api tool is part of the Avalonia Docs MCP server. It accepts queries for classes, properties, methods, and events using dot notation (e.g., TextBlock, Window.Show). See Build MCP documentation.

Step 6: Run content boundary checks

Apply content boundary rules using the page's declared (or inferred) doc-type and the forbidden_content and content_boundaries fields in page-templates.yaml.

1. BOUND-001: Verify the page serves a single Diataxis responsibility. Flag if content substantially overlaps another doc-type.
2. BOUND-002: Check the page does not contain content listed in its template's forbidden_content. Forbidden content should be linked to the appropriate page type, not duplicated.
3. BOUND-003: If the page lists more than 3 properties or API members of a single type inline, flag it and recommend linking to the reference page instead.
4. BOUND-004: For explanation pages, flag any numbered procedural sequence longer than 3 steps. Recommend linking to a how-to or tutorial instead.
5. BOUND-005: Verify frontmatter includes a doc-type field with a valid value (tutorial, how-to, explanation, overview, reference, troubleshooting, release-notes, migration).

Step 7: Run template compliance

Compare page structure against the expected archetype from page-templates.yaml:

• Check required sections are present and in order
• Flag missing optional sections that would improve the page
• Verify ordering rules (e.g., prerequisites before procedure)

Step 8: Check banned phrases

Flag any use of:

Step 9: Run inclusive language checks

Apply inclusive language rules from house-rules.yaml.

Major-level:

1. INC-001: Scan for gendered pronouns used generically (he/she/him/her/his/hers referring to an unspecified person or the reader) and gendered nouns (guys as a group address, mankind, manmade, man-hours). Suggest they/them/their, everyone, humankind, human-made, person-hours. Flag singular pronoun uses as candidates — distinguish generic use from a named individual (manual review).
2. INC-002: Scan for legacy technical terms with exclusionary connotations: blacklist/whitelist → blocklist/allowlist; master/slave in role contexts → primary/replica; sanity check → verify or check; dummy as placeholder data → placeholder/sample/stub. Context-sensitive uses (e.g. master in a git command literal, established API names like MasterDetail) require human review before flagging.

Step 10: Generate report

Output a structured lint report:

## Style Lint Report: [filename]

**Page type**: [detected type]
**doc-type frontmatter**: [present/absent]
**Score**: [PASS / FAIL with score]

### Blockers (must fix)
- [rule-id]: [description of issue] (line X)

### Major issues (should fix)
- [rule-id]: [description] (line X)

### Minor issues (consider fixing)
- [rule-id]: [description] (line X)

### Technical accuracy
- ACCU-001 (no fabricated details): [pass / N findings]
- ACCU-002 (code snippets preserved): [pass / N unauthorized modifications]
- ACCU-003 (API validation): [N APIs checked, N verified, N unverified]
  - Verified: [list of confirmed API references]
  - Unverified: [list of API references that could not be confirmed — BLOCKER]

### Anti-marketing compliance
- [TONE rule findings or "Clean"]

### Content boundary compliance
- [BOUND rule findings or "Clean"]
- Declared doc-type: [type]
- Forbidden content detected: [none / list]
- Single responsibility: [pass / concern]

### Inclusive language
- INC-001 (gender-neutral language): [pass / N findings]
- INC-002 (inclusive terminology): [pass / N findings]

### Readability
- QUAL-004 (ARI score): [X.X — grade label (pass / warning: above 14)]

### Accessibility & SEO
- ACC-001 (image alt text): [pass / N findings]
- SEO-001 (meta description): [pass / missing / too short / too long / contains buzzwords]
- SEO-002 (title length): [pass / X characters (over 60)]

### Template compliance
- Required sections: [present/missing list]
- Section order: [correct/issues]

### Suggested fixes
For each flagged issue, provide a structured fix suggestion:

- **[rule-id]** (line X):
  - Original: `[exact text from the page]`
  - Suggested: `[corrected text]`
  - Explanation: [why the change is needed]

### Summary
[1-2 sentence overall assessment with priority fixes]

Severity definitions

• Blocker: Must fix before publishing. Page cannot ship with these issues.
• Major: Should fix; document exceptions if skipped. These affect consistency and readability.
• Minor: Style drift warning. Fix opportunistically.

Avalonia-specific conventions

These override or extend the base rules for Avalonia's Docusaurus site:

Frontmatter

Avalonia docs use simple frontmatter with doc-type and description fields:

---
id: page-id
title: Page Title
description: A concise summary for search engines and social cards (50-160 characters).
doc-type: how-to
---

Admonitions

Use Docusaurus syntax, not Microsoft > [!NOTE] syntax:

:::note
Content here.
:::

:::tip
Content here.
:::

:::info
Content here.
:::

:::caution
Content here.
:::

:::danger
Content here.
:::

Code blocks

• XAML uses xml language tag (Avalonia AXAML is XML-based)
• C# uses csharp language tag
• F# uses fsharp language tag
• Always include a language tag on fenced code blocks

Terminology

• Use "Avalonia" not "Avalonia UI" in body text (except for trademark/legal contexts)
• Use "AXAML" when referring to Avalonia's XAML file extension specifically
• Use "XAML" when referring to the markup language itself
• Use control for UI components (never widget)
• Use StyledProperty / DirectProperty / AttachedProperty for Avalonia property types
• Use AvaloniaProperty as the base property type
• Use "view model" (two words) not "viewmodel"

Cross-linking

• Use relative paths: [Data binding](../data-binding/introduction-to-data-binding.md)
• No xref links (those are Microsoft docs specific)
• Verify link targets exist in the repository

Italics for defined terms

On first use of a new term, italicize it:

A *styled property* is a property backed by Avalonia's property system.