@ankhorage/rules-design 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +1 -1
- package/dist/features/accessibility/createAccessibilityRules.d.ts +8 -0
- package/dist/features/accessibility/createAccessibilityRules.js +110 -0
- package/dist/features/accessibility/evaluateAccessibilityObservation.d.ts +8 -0
- package/dist/features/accessibility/evaluateAccessibilityObservation.js +156 -0
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# @ankhorage/rules-design
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
8
|
Declarative catalog for reusable design rules.
|
|
9
9
|
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { FactEnvelope } from '@ankhorage/contracts/rules';
|
|
2
|
+
import type { Rule } from '@ankhorage/rules';
|
|
3
|
+
/*** Creates the independently owned Accessibility and Semantics rule family. */
|
|
4
|
+
export declare function createAccessibilityRules(): readonly Rule<DesignAccessibilityContext>[];
|
|
5
|
+
interface DesignAccessibilityContext {
|
|
6
|
+
readonly facts: readonly FactEnvelope[];
|
|
7
|
+
}
|
|
8
|
+
export {};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { evaluateAccessibilityObservation } from './evaluateAccessibilityObservation';
|
|
2
|
+
/*** Creates the independently owned Accessibility and Semantics rule family. */
|
|
3
|
+
export function createAccessibilityRules() {
|
|
4
|
+
return accessibilityRuleDefinitions.map(createAccessibilityRule);
|
|
5
|
+
}
|
|
6
|
+
const accessibilityRuleDefinitions = [
|
|
7
|
+
definition('design.a11y.accessible-name', ['dom.accessibility-tree'], 'Interactive controls have accessible names.'),
|
|
8
|
+
definition('design.a11y.form-label', ['dom.accessibility-tree'], 'Form fields have correct labels.'),
|
|
9
|
+
definition('design.a11y.error-association', ['dom.accessibility-tree'], 'Validation errors are semantically associated with their fields.'),
|
|
10
|
+
definition('design.a11y.keyboard-reachability', ['browser.keyboard-navigation'], 'Interactive elements are keyboard reachable.'),
|
|
11
|
+
definition('design.a11y.focus-order', ['dom.accessibility-tree'], 'Focus order is meaningful.'),
|
|
12
|
+
definition('design.a11y.color-only', ['dom.computed-style', 'dom.accessibility-tree'], 'Information is not conveyed by color alone.'),
|
|
13
|
+
definition('design.a11y.reduced-motion', ['browser.media-preference', 'browser.motion'], 'Reduced-motion settings are respected.'),
|
|
14
|
+
definition('design.a11y.landmarks', ['dom.accessibility-tree'], 'Landmarks are meaningful.'),
|
|
15
|
+
definition('design.a11y.main-landmark', ['dom.accessibility-tree'], 'Main content is identified.'),
|
|
16
|
+
definition('design.a11y.list-semantics', ['dom.accessibility-tree'], 'Lists have correct semantics.'),
|
|
17
|
+
definition('design.a11y.button-link-semantics', ['dom.accessibility-tree'], 'Buttons and links have correct semantics.'),
|
|
18
|
+
definition('design.a11y.status-feedback', ['dom.accessibility-tree'], 'Status changes are announced.'),
|
|
19
|
+
definition('design.a11y.text-alternatives', ['dom.accessibility-tree'], 'Text alternatives are meaningful and decorative media is identified.'),
|
|
20
|
+
];
|
|
21
|
+
/*** Defines one frozen rule identity with the observations that can support its verdict. */
|
|
22
|
+
function definition(id, requiredCapabilities, summary) {
|
|
23
|
+
return { id, requiredCapabilities, summary };
|
|
24
|
+
}
|
|
25
|
+
/*** Adapts one declared accessibility invariant to the generic Rules contract. */
|
|
26
|
+
function createAccessibilityRule(definition) {
|
|
27
|
+
return {
|
|
28
|
+
defaultSeverity: 'error',
|
|
29
|
+
dependencies: [],
|
|
30
|
+
evaluate: ({ context, scope }) => evaluateAccessibilityFact(context.facts, definition, scope.id, scope.kind),
|
|
31
|
+
identity: { id: definition.id, version: '1.0.0' },
|
|
32
|
+
requiredCapabilities: definition.requiredCapabilities,
|
|
33
|
+
summary: definition.summary,
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/*** Resolves one scoped fact into an explicit PASS, FAIL, or INCOMPLETE rule outcome. */
|
|
37
|
+
function evaluateAccessibilityFact(facts, definition, scopeId, scopeKind) {
|
|
38
|
+
const matchingFacts = facts.filter((fact) => fact.kind === definition.id && fact.scope.id === scopeId && fact.scope.kind === scopeKind);
|
|
39
|
+
const availableFacts = matchingFacts.filter((fact) => fact.status === 'available');
|
|
40
|
+
const values = availableFacts.map((fact) => parseAccessibilityFactValue(fact.value));
|
|
41
|
+
if (matchingFacts.length === 0 ||
|
|
42
|
+
availableFacts.length !== matchingFacts.length ||
|
|
43
|
+
values.some((value) => value === null))
|
|
44
|
+
return incomplete();
|
|
45
|
+
const observations = values.flatMap((value) => value?.observations ?? []);
|
|
46
|
+
if (observations.length === 0)
|
|
47
|
+
return incomplete();
|
|
48
|
+
const evaluations = observations.map((observation) => ({
|
|
49
|
+
observation,
|
|
50
|
+
verdict: evaluateAccessibilityObservation(definition.id, observation),
|
|
51
|
+
}));
|
|
52
|
+
if (evaluations.some(({ verdict }) => verdict === 'INCOMPLETE'))
|
|
53
|
+
return incomplete();
|
|
54
|
+
const failures = evaluations
|
|
55
|
+
.filter(({ verdict }) => verdict === 'FAIL')
|
|
56
|
+
.map(({ observation }) => observation);
|
|
57
|
+
return failures.length === 0 ? { findings: [], status: 'PASS' } : fail(definition, failures);
|
|
58
|
+
}
|
|
59
|
+
/*** Returns the canonical closed outcome when facts cannot defend a verdict. */
|
|
60
|
+
function incomplete() {
|
|
61
|
+
return { findings: [], status: 'INCOMPLETE' };
|
|
62
|
+
}
|
|
63
|
+
/*** Builds findings only from observations that explicitly contradict a rule invariant. */
|
|
64
|
+
function fail(definition, observations) {
|
|
65
|
+
return {
|
|
66
|
+
findings: observations.map((observation) => ({
|
|
67
|
+
evidence: { detail: observation.detail, observationId: observation.id },
|
|
68
|
+
message: `${definition.summary} ${observation.detail}`,
|
|
69
|
+
ruleId: definition.id,
|
|
70
|
+
severity: 'error',
|
|
71
|
+
subjects: [observation.subject],
|
|
72
|
+
})),
|
|
73
|
+
status: 'FAIL',
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
/*** Narrows a portable serializable fact value to complete normalized observations. */
|
|
77
|
+
function parseAccessibilityFactValue(value) {
|
|
78
|
+
if (!isRecord(value) || !Array.isArray(value.observations))
|
|
79
|
+
return null;
|
|
80
|
+
const observations = value.observations.map(parseAccessibilityObservation);
|
|
81
|
+
return observations.every((observation) => observation !== null) ? { observations } : null;
|
|
82
|
+
}
|
|
83
|
+
/*** Narrows one serializable observation without accepting incomplete subject evidence. */
|
|
84
|
+
function parseAccessibilityObservation(value) {
|
|
85
|
+
if (!isRecord(value) ||
|
|
86
|
+
typeof value.detail !== 'string' ||
|
|
87
|
+
typeof value.id !== 'string' ||
|
|
88
|
+
typeof value.kind !== 'string' ||
|
|
89
|
+
!isRecord(value.properties) ||
|
|
90
|
+
!isRuleSubject(value.subject))
|
|
91
|
+
return null;
|
|
92
|
+
return {
|
|
93
|
+
detail: value.detail,
|
|
94
|
+
id: value.id,
|
|
95
|
+
kind: value.kind,
|
|
96
|
+
properties: value.properties,
|
|
97
|
+
subject: value.subject,
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
/*** Checks the portable subject shape retained in the generic Rules result contract. */
|
|
101
|
+
function isRuleSubject(value) {
|
|
102
|
+
return (isRecord(value) &&
|
|
103
|
+
typeof value.id === 'string' &&
|
|
104
|
+
typeof value.kind === 'string' &&
|
|
105
|
+
(value.path === undefined || typeof value.path === 'string'));
|
|
106
|
+
}
|
|
107
|
+
/*** Narrows unknown serializable values before reading their named factual fields. */
|
|
108
|
+
function isRecord(value) {
|
|
109
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
110
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
type ObservationVerdict = 'FAIL' | 'INCOMPLETE' | 'PASS';
|
|
2
|
+
interface AccessibilityObservation {
|
|
3
|
+
readonly kind: string;
|
|
4
|
+
readonly properties: Readonly<Record<string, unknown>>;
|
|
5
|
+
}
|
|
6
|
+
/*** Evaluates one normalized observation against its frozen Accessibility rule meaning. */
|
|
7
|
+
export declare function evaluateAccessibilityObservation(ruleId: string, observation: AccessibilityObservation): ObservationVerdict;
|
|
8
|
+
export {};
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
const ruleEvaluators = [
|
|
2
|
+
[
|
|
3
|
+
'design.a11y.accessible-name',
|
|
4
|
+
(o) => booleanVerdict(o, 'control', o.properties.hasAccessibleName),
|
|
5
|
+
],
|
|
6
|
+
[
|
|
7
|
+
'design.a11y.form-label',
|
|
8
|
+
(o) => booleanVerdict(o, 'form-field', o.properties.hasProgrammaticLabel),
|
|
9
|
+
],
|
|
10
|
+
[
|
|
11
|
+
'design.a11y.error-association',
|
|
12
|
+
(o) => stringVerdict(o, 'validation-error', o.properties.associatedFieldId),
|
|
13
|
+
],
|
|
14
|
+
[
|
|
15
|
+
'design.a11y.keyboard-reachability',
|
|
16
|
+
(o) => booleanVerdict(o, 'interactive-element', o.properties.keyboardReachable),
|
|
17
|
+
],
|
|
18
|
+
['design.a11y.focus-order', focusOrderVerdict],
|
|
19
|
+
[
|
|
20
|
+
'design.a11y.color-only',
|
|
21
|
+
(o) => booleanVerdict(o, 'information-cue', o.properties.hasNonColorIndicator),
|
|
22
|
+
],
|
|
23
|
+
['design.a11y.reduced-motion', reducedMotionVerdict],
|
|
24
|
+
['design.a11y.landmarks', landmarkVerdict],
|
|
25
|
+
['design.a11y.main-landmark', mainLandmarkVerdict],
|
|
26
|
+
['design.a11y.list-semantics', listSemanticsVerdict],
|
|
27
|
+
['design.a11y.button-link-semantics', buttonLinkVerdict],
|
|
28
|
+
['design.a11y.status-feedback', statusFeedbackVerdict],
|
|
29
|
+
['design.a11y.text-alternatives', textAlternativesVerdict],
|
|
30
|
+
];
|
|
31
|
+
/*** Evaluates one normalized observation against its frozen Accessibility rule meaning. */
|
|
32
|
+
export function evaluateAccessibilityObservation(ruleId, observation) {
|
|
33
|
+
return ruleEvaluators.find(([id]) => id === ruleId)?.[1](observation) ?? 'INCOMPLETE';
|
|
34
|
+
}
|
|
35
|
+
/*** Evaluates one boolean semantic property when it belongs to the expected observation kind. */
|
|
36
|
+
function booleanVerdict(o, kind, value) {
|
|
37
|
+
return o.kind !== kind || typeof value !== 'boolean' ? 'INCOMPLETE' : value ? 'PASS' : 'FAIL';
|
|
38
|
+
}
|
|
39
|
+
/*** Evaluates a non-empty string semantic property when it belongs to the expected observation kind. */
|
|
40
|
+
function stringVerdict(o, kind, value) {
|
|
41
|
+
return o.kind !== kind || typeof value !== 'string'
|
|
42
|
+
? 'INCOMPLETE'
|
|
43
|
+
: value.trim() === ''
|
|
44
|
+
? 'FAIL'
|
|
45
|
+
: 'PASS';
|
|
46
|
+
}
|
|
47
|
+
/*** Compares normalized focus traversal with the normalized document order it must preserve. */
|
|
48
|
+
function focusOrderVerdict(o) {
|
|
49
|
+
const { documentOrder, focusOrder } = o.properties;
|
|
50
|
+
return o.kind !== 'focus-sequence' ||
|
|
51
|
+
!isNormalizedElementOrder(documentOrder) ||
|
|
52
|
+
!isNormalizedElementOrder(focusOrder)
|
|
53
|
+
? 'INCOMPLETE'
|
|
54
|
+
: documentOrder.length === focusOrder.length &&
|
|
55
|
+
documentOrder.every((elementId, index) => elementId === focusOrder.at(index))
|
|
56
|
+
? 'PASS'
|
|
57
|
+
: 'FAIL';
|
|
58
|
+
}
|
|
59
|
+
/*** Evaluates measured motion while the reduced-motion preference is active. */
|
|
60
|
+
function reducedMotionVerdict(o) {
|
|
61
|
+
const { motionObserved, prefersReducedMotion } = o.properties;
|
|
62
|
+
return o.kind !== 'motion-response' ||
|
|
63
|
+
prefersReducedMotion !== true ||
|
|
64
|
+
typeof motionObserved !== 'boolean'
|
|
65
|
+
? 'INCOMPLETE'
|
|
66
|
+
: motionObserved
|
|
67
|
+
? 'FAIL'
|
|
68
|
+
: 'PASS';
|
|
69
|
+
}
|
|
70
|
+
/*** Evaluates whether a measured landmark has a valid semantic role and name. */
|
|
71
|
+
function landmarkVerdict(o) {
|
|
72
|
+
const { hasAccessibleName, role } = o.properties;
|
|
73
|
+
return o.kind !== 'landmark' || typeof role !== 'string' || typeof hasAccessibleName !== 'boolean'
|
|
74
|
+
? 'INCOMPLETE'
|
|
75
|
+
: [
|
|
76
|
+
'banner',
|
|
77
|
+
'complementary',
|
|
78
|
+
'contentinfo',
|
|
79
|
+
'form',
|
|
80
|
+
'main',
|
|
81
|
+
'navigation',
|
|
82
|
+
'region',
|
|
83
|
+
'search',
|
|
84
|
+
].includes(role) &&
|
|
85
|
+
(role !== 'region' || hasAccessibleName)
|
|
86
|
+
? 'PASS'
|
|
87
|
+
: 'FAIL';
|
|
88
|
+
}
|
|
89
|
+
/*** Evaluates whether the measured page landmark summary identifies exactly one main region. */
|
|
90
|
+
function mainLandmarkVerdict(o) {
|
|
91
|
+
const { mainCount } = o.properties;
|
|
92
|
+
return o.kind !== 'landmark-summary' || !isMainLandmarkCount(mainCount)
|
|
93
|
+
? 'INCOMPLETE'
|
|
94
|
+
: mainCount === 1
|
|
95
|
+
? 'PASS'
|
|
96
|
+
: 'FAIL';
|
|
97
|
+
}
|
|
98
|
+
/*** Validates the normalized page-level main landmark count before evaluating its invariant. */
|
|
99
|
+
function isMainLandmarkCount(value) {
|
|
100
|
+
return (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value >= 0);
|
|
101
|
+
}
|
|
102
|
+
/*** Validates a non-empty unique sequence of normalized element identifiers. */
|
|
103
|
+
function isNormalizedElementOrder(value) {
|
|
104
|
+
return (Array.isArray(value) &&
|
|
105
|
+
value.length > 0 &&
|
|
106
|
+
value.every((elementId) => typeof elementId === 'string' && elementId.trim() !== '') &&
|
|
107
|
+
new Set(value).size === value.length);
|
|
108
|
+
}
|
|
109
|
+
/*** Evaluates whether a measured list exposes list and listitem semantics together. */
|
|
110
|
+
function listSemanticsVerdict(o) {
|
|
111
|
+
const { itemRoles, role } = o.properties;
|
|
112
|
+
return o.kind !== 'list' ||
|
|
113
|
+
!Array.isArray(itemRoles) ||
|
|
114
|
+
itemRoles.some((itemRole) => typeof itemRole !== 'string')
|
|
115
|
+
? 'INCOMPLETE'
|
|
116
|
+
: role === 'list' &&
|
|
117
|
+
itemRoles.length > 0 &&
|
|
118
|
+
itemRoles.every((itemRole) => itemRole === 'listitem')
|
|
119
|
+
? 'PASS'
|
|
120
|
+
: 'FAIL';
|
|
121
|
+
}
|
|
122
|
+
/*** Evaluates whether measured buttons and links expose behavior matching their semantic role. */
|
|
123
|
+
function buttonLinkVerdict(o) {
|
|
124
|
+
const { behavior, role } = o.properties;
|
|
125
|
+
return o.kind !== 'interactive-control' ||
|
|
126
|
+
typeof role !== 'string' ||
|
|
127
|
+
typeof behavior !== 'string'
|
|
128
|
+
? 'INCOMPLETE'
|
|
129
|
+
: (role === 'button' && behavior === 'action') || (role === 'link' && behavior === 'navigation')
|
|
130
|
+
? 'PASS'
|
|
131
|
+
: 'FAIL';
|
|
132
|
+
}
|
|
133
|
+
/*** Evaluates whether a measured dynamic status uses an announcing live-region role. */
|
|
134
|
+
function statusFeedbackVerdict(o) {
|
|
135
|
+
const { isAnnounced, role } = o.properties;
|
|
136
|
+
return o.kind !== 'status-message' || typeof role !== 'string' || typeof isAnnounced !== 'boolean'
|
|
137
|
+
? 'INCOMPLETE'
|
|
138
|
+
: ['alert', 'log', 'status'].includes(role) && isAnnounced
|
|
139
|
+
? 'PASS'
|
|
140
|
+
: 'FAIL';
|
|
141
|
+
}
|
|
142
|
+
/*** Evaluates alternatives for meaningful media and the omission expected for decorative media. */
|
|
143
|
+
function textAlternativesVerdict(o) {
|
|
144
|
+
const { isDecorative, textAlternative } = o.properties;
|
|
145
|
+
return o.kind !== 'media' ||
|
|
146
|
+
typeof isDecorative !== 'boolean' ||
|
|
147
|
+
(textAlternative !== undefined && typeof textAlternative !== 'string')
|
|
148
|
+
? 'INCOMPLETE'
|
|
149
|
+
: isDecorative
|
|
150
|
+
? textAlternative === undefined || textAlternative.trim() === ''
|
|
151
|
+
? 'PASS'
|
|
152
|
+
: 'FAIL'
|
|
153
|
+
: typeof textAlternative === 'string' && textAlternative.trim() !== ''
|
|
154
|
+
? 'PASS'
|
|
155
|
+
: 'FAIL';
|
|
156
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/rules-design",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Declarative catalog for reusable design rules.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/ankhorage/rules-design#readme",
|
|
@@ -58,6 +58,7 @@
|
|
|
58
58
|
"@ankhorage/paradox": "^0.3.6"
|
|
59
59
|
},
|
|
60
60
|
"dependencies": {
|
|
61
|
-
"@ankhorage/
|
|
61
|
+
"@ankhorage/contracts": "^26.4.0",
|
|
62
|
+
"@ankhorage/rules": "^0.4.0"
|
|
62
63
|
}
|
|
63
64
|
}
|