bcquality/microsoft/skills/review/al-ui-review.md

kind	id	version	title	description	inputs	outputs	bc-version	technologies	countries	application-area
action-skill	al-ui-review	1	AL UI and accessibility review	Reviews AL page and control add-in UI files, and AL code that sends or recalls notifications, against UI text, caption, tooltip, notification, and accessibility guidance from BCQuality.	pr-diff file-path folder-path	findings-report	all	al javascript	w1	all

AL UI and accessibility review

Reviews AL page source and control add-in UI files against the ui knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by al-code-review.

UI findings apply to page files — files that declare PageType = ..., including *.Page.al under the standard file-naming convention — to AL code that sends or recalls in-client notifications, and to JavaScript/CSS/HTML files that implement Business Central control add-ins, including their client-service communication. The skill returns not-applicable when the diff contains no page, notification, or control add-in changes.

An orchestrator invokes this skill with a pr-diff, file-path, or folder-path. The skill produces a single JSON document conforming to the DO output contract.

Source

Use READ's Bounded retrieval for review skills workflow with -Domain ui. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback.

Relevance

Apply the frontmatter matching rules defined in READ against the task context:

• bc-version — the target BC version from the PR branch's app.json or the orchestrator-supplied version. If unavailable, the dimension is unknown.
• technologies — [al] or [javascript].
• countries — the countries declared in the consuming app's app.json. If absent, unknown.
• application-area — pass the actual set declared by the changed objects; do not substitute [all].

Discard files that are not applicable. Retain conditionally applicable files only when the orchestrator's configuration permits them; findings derived from those files MUST have confidence no higher than medium and MUST name the unknown dimensions in message.

Worklist

Narrow the relevant files to the subset that applies to the changes under review.

• UI-file filter. UI review applies to files declaring page, pageextension, or pagecustomization; to any AL object whose changed code calls Send() or Recall() on a Notification variable or calls codeunit "Notification Lifecycle Mgt."; and to JavaScript/CSS/HTML that implements a control add-in's rendering or Business Central communication. A non-page AL file admitted only by the notification clause is evaluated only against notification knowledge (notification-recall-needs-known-id), not against caption, tooltip, message-text, or client-expression knowledge. When the diff contains no such files, return outcome: "not-applicable" without evaluating knowledge files.
• A new or changed page's name/suffix, primary-key handling, CardPageID, SubPageLink, AutoSplitKey, or UsageCategory doesn't match the conventions of its own declared PageType — page-design-must-match-bc-page-type-conventions.md. A Card page over a composite-key table that supplements a master record, or a supporting/subpage/dialog page intended only to be reached through another workflow and correctly omitting UsageCategory, is not this anti-pattern on its own; check whether the page is actually mixing conventions or is meant as a searchable entry point before flagging.
• For each relevant knowledge file, compute overlap against changed page declarations and control add-in files, weighted toward Caption, ToolTip, AboutTitle, AboutText, OptionCaption, ShowCaption, InstructionalText, GridLayout, Style, StyleExpr, promoted action definitions, field importance, page background tasks, notification send/recall, open-document actions, DOM creation, ARIA attributes, keyboard/focus handlers, packaged-resource AJAX, and calls from JavaScript into AL.
• Tokens extracted from the diff (Caption, ToolTip, AboutTitle, AboutText, PageType, ShowCaption, InstructionalText, grid, fixed, GridLayout, Style, StyleExpr, Importance, Promoted, Additional, area(Promoted), actionref, PromotedCategory, PromotedOnly, PromotedIsBig, ShowAs, SplitButton, fieldgroups, DropDown, UpdatePropagation, EnqueueBackgroundTask, OnAfterGetCurrRecord, OnAfterGetRecord, OnPageBackgroundTaskCompleted, OnPageBackgroundTaskError, RunPageBackgroundTask, Favorable, Unfavorable, Ambiguous, cuegroup, controladdin, control-add-in, usercontrol, aria-, tabindex, keydown, focus, innerHTML, createElement, packaged-resource, ajax, $.get, $.ajax, XMLHttpRequest, xhrFields, withCredentials, withcredentials, InvokeExtensibilityMethod, invokeextensibilitymethod, skipIfBusy, successCallback, success-callback, errorCallback, setInterval, JSON.stringify, payload, throttling, reduced-functionality, ClientServicesMaxUploadSize, &, Specifies, Message(, Confirm(, Error( in a page context, Disabled, Invalid, Whitelist, Blacklist, trailing punctuation patterns on captions, CardPageID, AutoSplitKey, PageType = Card, PageType = List, PageType = Worksheet, PageType = Document, PageType = RoleCenter, Enabled, Visible, Editable, in [, AccessByPermission, ReadPermission, WritePermission, Notification, NotificationScope, .Send(), .Recall(), CreateGuid, Notification Lifecycle Mgt., SendNotification, SendNotificationWithAdditionalContext, RecallNotificationsForRecord, Page Management, PageRun, Page.Run(, ShowDocument). Match tokens case-insensitively; Base App writes both Page.Run( and PAGE.Run(.

A file enters the candidate worklist when its keywords intersect the extracted tokens or its topic (derived from the index entry's path, title, and description) matches a changed page element. Read an article's full file — its ## Best Practice / ## Anti Pattern bodies — only after it makes the worklist; candidate selection uses the index alone.

Apply these high-signal mappings before fuzzy topic ranking:

• A tableextension adds a field to DropDown while the corresponding lookup-page control remains Visible = false — dropdown-fieldgroup-respects-lookup-page-visibility.
• An editable page part affects a total, FlowField, or FactBox on the parent but does not set UpdatePropagation = Both — updatepropagation-both-refreshes-main-page.
• A page or pageextension Enabled, Visible, Editable, or StyleExpr value contains an in [...] list (compiler: "InListExpression is not valid for client expressions", AL0573 or AL0322), or replaces one with a procedure call — page-client-expression-must-not-use-in-list. Plain =/<> comparisons joined with and/or, and in [...] inside a trigger or procedure body, are valid; do not flag them.
• A RoleCenter page, or a pageextension whose target is a Role Center, gates a part, action, or field by binding Visible or Enabled to a procedure that tests a permission, or declares a procedure (AL0569 "A page of type Role Center cannot have procedures", AL0573) — rolecenter-permission-gating-must-use-accessbypermission. The target page name is not reliable evidence of its type; confirm it is a Role Center from its PageType or the AL0569 diagnostic. Setup- or feature-flag gating inside the part page is not this pattern.
• Code sends and recalls a Notification, and the Notification passed to Recall() cannot carry the sent Id: for example Send() on a local variable when a condition holds and Recall() on a fresh local variable when it clears, with no Id assigned or a new CreateGuid() assigned on each call, while neither the sent instance nor its Id is kept in a global variable, a record, or "Notification Lifecycle Mgt."; or, when notifications for several records must be visible at the same time, they share one fixed Id sent and recalled directly — notification-recall-needs-known-id. Flag only with evidence that the recalled identity differs from, or cannot recover, the sent identity: trace the Recall() variable back to its Id assignment and the sent variable forward to where its instance or Id is kept. Valid, do not flag: a notification that is never recalled; a global or page-level Notification instance sent and later recalled, whether its Id came from CreateGuid() (for example once in OnOpenPage) or from Send(); a generated Id saved after Send() and reassigned before Recall(); per-record Ids the code tracks correctly itself; one sent through "Notification Lifecycle Mgt." (SendNotification, SendNotificationWithAdditionalContext) without an Id; and a fixed Id shared across records for a one-at-a-time warning that is recalled before re-send (directly or through SendNotification, as in Sales Line's blocked-item notification). Recommend "Notification Lifecycle Mgt." for per-record tracking, but do not flag correct direct tracking for not using it.
• A page action opens a record of Sales Header, Purchase Header, their archives, or another table that codeunit "Page Management" routes (directly or after a Get) by switching on its Document Type or a similar type field and calling Page.Run(Page::...) per branch — list-page-document-routing-uses-page-management. Severity minor. Opening one known document type directly, a list with a fixed CardPageID, and a table that "Page Management" does not route (for example Assembly Header) are not this pattern.

Once the candidate worklist is known, resolve layer-precedence conflicts per READ and record suppressions.

When the post-conflict worklist is empty because no applicable UI knowledge exists, or because configuration suppressed every candidate, emit outcome: "no-knowledge". When the worklist is empty because no applicable UI knowledge matched the page changes, emit outcome: "completed" with an empty findings array.

Action

For each worklist entry, evaluate the diff against the file's ## Best Practice and ## Anti Pattern sections. UI text findings are generally minor — they affect localization and polish rather than correctness. Accessibility findings for missing labels, broken grid semantics, semantic color without text meaning, or UI-rendering control add-in changes can be major; use minor for low-risk manual-review reminders and polish issues.

For packaged-resource requests, flag $.get or AJAX/XHR that omits withCredentials only when the URL is identifiable as a resource in the control add-in package; do not generalize the rule to external endpoints. For InvokeExtensibilityMethod, flag repeated or timer-driven calls that can overlap because they do not wait for the success/error callbacks, and unbounded serialized payloads sent in one call. Prefer bounded chunks serialized through completion callbacks. Do not emit generic browser or JavaScript performance advice.

Set confidence to:

• high when the detection is based on an unambiguous pattern match (banned term literal, missing "Specifies" opener on a field tooltip, caption exceeding documented limit).
• medium when detection relies on heuristics (judging whether a caption is a noun phrase or a sentence phrase) or when any frontmatter dimension was unknown.
• low when the finding is an advisory derived only from applicability.

This leaf emits only knowledge-backed UI and accessibility findings. Do NOT emit reference-less agent: findings in this domain: online evaluation shows the UI/accessibility agent-finding channel yields almost no accepted findings and a high volume of dismissed noise, so a UI or accessibility concern that no worklist knowledge file covers is omitted here rather than emitted with references: []. When you spot a material UI or accessibility defect no article covers, the durable fix is to add a knowledge article in BCQuality (per the online-eval self-improvement loop) so this leaf can cite it — not a one-off reference-less finding. Before treating a candidate as uncovered, check the worklist for a knowledge file that matches it; if one exists, emit it as a knowledge-backed finding. See skills/do.md for the full contract.

For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace Count() > 0 with not IsEmpty(); add a missing ToolTip, OptionCaption, or DataClassification; replace a string-concatenated Error with a Label-backed call; change an over-broad permission token; or add an obvious else/guard branch). For mechanical findings, emit findings[].suggested-code with the literal replacement for the source lines indicated by location. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a .good.al companion exists and the diff context matches the .bad.al shape, adapt the .good.al replacement into suggested-code.

Omit suggested-code only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit suggested-code, set findings[].suggested-code-omission-reason to a short explanation. See skills/do.md for the full contract.

Outcome selection:

• completed — the skill evaluated every worklist item.
• no-knowledge — no applicable UI knowledge survived filtering.
• not-applicable — the diff contains no page, pageextension, pagecustomization, notification send/recall, or control add-in implementation files.
• partial — a budget was hit before the worklist was exhausted.
• failed — an unrecoverable error occurred.

Output

Output conforms to the DO output contract. Every finding this skill emits MUST set findings[].domain to "Accessibility". A populated example:

{
  "skill": { "id": "al-ui-review", "version": 1 },
  "outcome": "completed",
  "summary": {
    "counts": { "blocker": 0, "major": 0, "minor": 1, "info": 0 },
    "coverage": { "worklist-size": 1, "items-evaluated": 1 }
  },
  "findings": [
    {
      "id": "microsoft/knowledge/ui/show-caption-on-editable-fields.md",
      "severity": "minor",
      "message": "An editable page field sets ShowCaption = false, removing the visible and accessible label. Leave ShowCaption enabled or use a documented exception pattern.",
      "location": {
        "file": "src/Sales/CustomerCard.Page.al",
        "line": 58
      },
      "references": [
        { "path": "microsoft/knowledge/ui/show-caption-on-editable-fields.md" }
      ],
      "confidence": "high",
      "domain": "Accessibility"
    }
  ],
  "suppressed": []
}