mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 09:26:52 +01:00
Sync knowledge articles with review agent instructions
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde
parent
f562fba837
commit
5bcdc55df9
62 changed files with 768 additions and 58 deletions
|
|
@ -0,0 +1,14 @@
|
|||
page 50731 "UI Caption Bad"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
field(CustomerName; Rec."Customer Name")
|
||||
{
|
||||
InstructionalText = 'Enter the customer name.';
|
||||
ShowCaption = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
page 50730 "UI Caption Good"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
group(Description)
|
||||
{
|
||||
Caption = 'Description';
|
||||
field(DescriptionField; Rec.Description)
|
||||
{
|
||||
MultiLine = true;
|
||||
ShowCaption = false;
|
||||
}
|
||||
}
|
||||
field(CustomerName; Rec."Customer Name")
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
26
microsoft/knowledge/ui/keep-captions-on-editable-fields.md
Normal file
26
microsoft/knowledge/ui/keep-captions-on-editable-fields.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: ui
|
||||
keywords: [showcaption, editable, accessibility, screen-reader, label]
|
||||
technologies: [al]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Keep captions on editable fields
|
||||
|
||||
## Description
|
||||
|
||||
`ShowCaption = false` on an editable page field removes the visible and accessible label that identifies the input. `InstructionalText` is not a replacement: it behaves like placeholder text, disappears after entry, and is not reliably announced as the field label. The default `ShowCaption = true` is the safe form-field pattern.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Leave captions visible on editable fields. `ShowCaption = false` is acceptable for non-editable content fields, for fields inside a valid data-table grid pattern, and for the first visible field in a parent group with a visible non-empty caption; in that last pattern, the group caption becomes the accessible label.
|
||||
|
||||
See sample: `keep-captions-on-editable-fields.good.al`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Hiding the caption on an editable field because the page layout looks cleaner, or because `InstructionalText` appears to describe the input. Screen reader users lose the field label, and sighted users lose the persistent visual cue.
|
||||
|
||||
See sample: `keep-captions-on-editable-fields.bad.al`.
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: ui
|
||||
keywords: [control-addin, javascript, accessibility, wcag, keyboard, aria]
|
||||
technologies: [al, javascript]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Manually review UI-rendering control add-in changes for accessibility
|
||||
|
||||
## Description
|
||||
|
||||
JavaScript control add-ins bypass much of the Business Central client's built-in accessibility support. Once the add-in renders its own HTML, JavaScript, or CSS, the extension owns WCAG 2.1 AA concerns such as accessible names, semantic HTML, keyboard navigation, color contrast, focus management, and 200% zoom/reflow. Automated review cannot exhaustively verify those behaviours.
|
||||
|
||||
## Best Practice
|
||||
|
||||
When a control add-in change touches DOM creation, templates, CSS, interaction handlers, ARIA attributes, dynamic visibility, or focus flow, include a manual accessibility review finding even if no specific defect is obvious. Do not require manual accessibility review for pure data processing or API changes that do not render UI.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Treating a control add-in diff as clean because no AL page properties changed. A new `div`-based button without an accessible name, a keyboard trap, or a color-only status indicator lives in JavaScript and still affects Business Central users.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
page 50735 "UI Style Bad"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
field(Score; Score)
|
||||
{
|
||||
Caption = 'Score';
|
||||
Style = Favorable;
|
||||
StyleExpr = IsGood;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
var
|
||||
Score: Integer;
|
||||
IsGood: Boolean;
|
||||
}
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
page 50734 "UI Style Good"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
field(ValidationStatus; ValidationStatus)
|
||||
{
|
||||
Caption = 'Validation status';
|
||||
Style = Unfavorable;
|
||||
StyleExpr = HasValidationErrors;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
var
|
||||
ValidationStatus: Text;
|
||||
HasValidationErrors: Boolean;
|
||||
}
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: ui
|
||||
keywords: [style, styleexpr, favorable, unfavorable, ambiguous, accessibility]
|
||||
technologies: [al]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Provide text meaning for semantic styles
|
||||
|
||||
## Description
|
||||
|
||||
Most Business Central page styles are cosmetic, but `Favorable`, `Unfavorable`, and `Ambiguous` communicate meaning through color. Color-only meaning is not accessible. A user who cannot perceive the style must still be able to determine whether the value is positive, negative, or uncertain from the caption, value, or nearby text.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Use semantic styles only when the meaning is independently available: a caption such as "Error", a value such as "Failed", a signed number whose sign carries the meaning, or an adjacent status field. Cosmetic styles such as `Strong`, `Attention`, and `Subordinate` do not need this extra check. Cue tiles inside `cuegroup` are exempt because the client supplies accessible semantic labels.
|
||||
|
||||
See sample: `provide-text-meaning-for-semantic-styles.good.al`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Applying `Style = Favorable`, `Unfavorable`, or `Ambiguous` to a value whose text is neutral, such as "42" or "Open", without any caption or adjacent field explaining what the color means.
|
||||
|
||||
See sample: `provide-text-meaning-for-semantic-styles.bad.al`.
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
page 50733 "UI Grid Bad"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
grid(BalanceGrid)
|
||||
{
|
||||
GridLayout = Columns;
|
||||
field(CustomerName; Rec."Customer Name")
|
||||
{
|
||||
ShowCaption = false;
|
||||
}
|
||||
group(BalanceColumn)
|
||||
{
|
||||
field(Balance; Rec.Balance)
|
||||
{
|
||||
ShowCaption = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
page 50732 "UI Grid Good"
|
||||
{
|
||||
layout
|
||||
{
|
||||
area(Content)
|
||||
{
|
||||
grid(BalanceGrid)
|
||||
{
|
||||
GridLayout = Columns;
|
||||
group(CustomerColumn)
|
||||
{
|
||||
ShowCaption = false;
|
||||
field(CustomerName; Rec."Customer Name")
|
||||
{
|
||||
ShowCaption = false;
|
||||
}
|
||||
}
|
||||
group(BalanceColumn)
|
||||
{
|
||||
ShowCaption = false;
|
||||
field(Balance; Rec.Balance)
|
||||
{
|
||||
ShowCaption = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
bc-version: [all]
|
||||
domain: ui
|
||||
keywords: [grid, fixed, showcaption, accessibility, table-semantics]
|
||||
technologies: [al]
|
||||
countries: [w1]
|
||||
application-area: [all]
|
||||
---
|
||||
|
||||
# Use the grid data-table pattern consistently
|
||||
|
||||
## Description
|
||||
|
||||
Business Central `grid` and `fixed` layouts render either as data tables or layout tables based on a structural heuristic. A data table requires all direct children to be groups, every group child to be a field, and all fields to have `ShowCaption = false`. If the structure fails that heuristic, the client renders a layout table; hidden captions on editable fields then remove the only accessible labels.
|
||||
|
||||
## Best Practice
|
||||
|
||||
Use one pattern consistently. For a data-table grid, make every direct child a group and every field `ShowCaption = false`. For a layout grid, keep captions visible on editable or tabular fields and hide captions only on standalone non-editable content where the missing label is not a form-field problem.
|
||||
|
||||
See sample: `use-grid-data-table-pattern-consistently.good.al`.
|
||||
|
||||
## Anti Pattern
|
||||
|
||||
Mixing the patterns: one loose field, nested group, or visible field caption prevents data-table rendering, while other editable fields still hide captions. The result looks like a table visually but has layout-table semantics and missing labels for assistive technology.
|
||||
|
||||
See sample: `use-grid-data-table-pattern-consistently.bad.al`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue