@ankhorage/rules-design 0.3.0 → 0.3.2
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 +12 -0
- package/README.md +1 -1
- package/dist/features/color/colorObservationValues.d.ts +7 -0
- package/dist/features/color/colorObservationValues.js +9 -0
- package/dist/features/color/createColorPolicyRules.d.ts +6 -0
- package/dist/features/color/createColorPolicyRules.js +138 -0
- package/dist/features/color/createColorRuleSet.d.ts +6 -0
- package/dist/features/color/createColorRuleSet.js +175 -0
- package/dist/features/color/evaluateColorPolicyObservation.d.ts +6 -0
- package/dist/features/color/evaluateColorPolicyObservation.js +148 -0
- package/dist/features/color/isColorRulePolicy.d.ts +3 -0
- package/dist/features/color/isColorRulePolicy.js +84 -0
- package/dist/features/contrast/createContrastRules.d.ts +8 -0
- package/dist/features/contrast/createContrastRules.js +225 -0
- package/dist/features/contrast/hasValidContrastMeasurement.d.ts +3 -0
- package/dist/features/contrast/hasValidContrastMeasurement.js +66 -0
- package/dist/types/color.d.ts +25 -0
- package/dist/types/color.js +0 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 66a4de6: Implement Color and Tokens rules with rendered-area 60-30-10 evaluation.
|
|
8
|
+
|
|
9
|
+
## 0.3.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- d715c7a: Fix Contrast rule evaluation to apply canonical standards to observed facts.
|
|
14
|
+
|
|
3
15
|
## 0.3.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
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,7 @@
|
|
|
1
|
+
import type { JsonValue } from '@ankhorage/rules';
|
|
2
|
+
/*** Provides shared primitive checks for normalized Color observation fields. */
|
|
3
|
+
export declare const colorObservationValues: {
|
|
4
|
+
sequence: (left: readonly string[], right: readonly string[]) => boolean;
|
|
5
|
+
strings: (value: JsonValue | undefined) => readonly string[] | undefined;
|
|
6
|
+
text: (value: unknown) => value is string;
|
|
7
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { isDeepStrictEqual } from 'node:util';
|
|
2
|
+
/*** Provides shared primitive checks for normalized Color observation fields. */
|
|
3
|
+
export const colorObservationValues = {
|
|
4
|
+
sequence: (left, right) => isDeepStrictEqual(left, right),
|
|
5
|
+
strings: (value) => Array.isArray(value) && value.length > 0 && value.every(colorObservationValues.text)
|
|
6
|
+
? value
|
|
7
|
+
: undefined,
|
|
8
|
+
text: (value) => typeof value === 'string' && value.trim() !== '',
|
|
9
|
+
};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Rule } from '@ankhorage/rules';
|
|
2
|
+
import type { ColorRulePolicy } from '../../types/color';
|
|
3
|
+
import type { DesignContext } from '../../types/designRuleProvider';
|
|
4
|
+
export type { ColorRulePolicy } from '../../types/color';
|
|
5
|
+
/*** Creates the twelve frozen Color and Tokens policy rules from normalized raw observations. */
|
|
6
|
+
export declare function createColorPolicyRules(policy: ColorRulePolicy): readonly Rule<DesignContext>[];
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { colorObservationValues } from './colorObservationValues';
|
|
3
|
+
import { evaluateColorPolicyObservation } from './evaluateColorPolicyObservation';
|
|
4
|
+
import { isColorRulePolicy } from './isColorRulePolicy';
|
|
5
|
+
const policyRuleIds = [
|
|
6
|
+
'design.color.syntax-valid',
|
|
7
|
+
'design.color.token-exists',
|
|
8
|
+
'design.color.token-allowed',
|
|
9
|
+
'design.color.semantic-role',
|
|
10
|
+
'design.color.literal-drift',
|
|
11
|
+
'design.color.ramp-consistency',
|
|
12
|
+
'design.color.alpha-composition',
|
|
13
|
+
'design.color.surface-role',
|
|
14
|
+
'design.color.hover-state',
|
|
15
|
+
'design.color.active-state',
|
|
16
|
+
'design.color.disabled-state',
|
|
17
|
+
'design.color.theme-coverage',
|
|
18
|
+
];
|
|
19
|
+
const { text } = colorObservationValues;
|
|
20
|
+
/*** Creates the twelve frozen Color and Tokens policy rules from normalized raw observations. */
|
|
21
|
+
export function createColorPolicyRules(policy) {
|
|
22
|
+
validateColorRulePolicy(policy);
|
|
23
|
+
return policyRuleIds.map((ruleId) => createColorPolicyRule(ruleId, policy));
|
|
24
|
+
}
|
|
25
|
+
/*** Rejects malformed trusted policy before Color rules can produce ambiguous verdicts. */
|
|
26
|
+
function validateColorRulePolicy(policy) {
|
|
27
|
+
if (!isColorRulePolicy(policy))
|
|
28
|
+
throw new Error('Color rule policy must define complete acceptance and coverage configuration.');
|
|
29
|
+
}
|
|
30
|
+
/*** Constructs one fact-driven atomic rule without trusting adapter verdict fields. */
|
|
31
|
+
function createColorPolicyRule(ruleId, policy) {
|
|
32
|
+
return {
|
|
33
|
+
defaultSeverity: 'warning',
|
|
34
|
+
dependencies: [],
|
|
35
|
+
evaluate: (input) => evaluateColorPolicyRule(ruleId, policy, input),
|
|
36
|
+
identity: { id: ruleId, version: '1.0.0' },
|
|
37
|
+
requiredCapabilities: ['design.color-policy-facts'],
|
|
38
|
+
summary: colorPolicySummary(ruleId),
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/*** Assesses each normalized raw observation with the rule-specific trusted policy. */
|
|
42
|
+
function evaluateColorPolicyRule(ruleId, policy, input) {
|
|
43
|
+
const facts = (input.context.facts ?? []).filter((fact) => fact.kind === ruleId && sameScope(fact, input));
|
|
44
|
+
const observations = facts.map((fact) => ({ fact, observation: parseObservation(fact) }));
|
|
45
|
+
if (facts.length === 0 || observations.some(({ observation }) => observation === undefined))
|
|
46
|
+
return incomplete(ruleId, input);
|
|
47
|
+
const assessments = observations.flatMap(({ fact, observation }) => observation === undefined
|
|
48
|
+
? []
|
|
49
|
+
: [
|
|
50
|
+
{
|
|
51
|
+
fact,
|
|
52
|
+
observation,
|
|
53
|
+
verdict: evaluateColorPolicyObservation(ruleId, observation.value, policy),
|
|
54
|
+
},
|
|
55
|
+
]);
|
|
56
|
+
if (assessments.some(({ verdict }) => verdict === 'INCOMPLETE'))
|
|
57
|
+
return incomplete(ruleId, input);
|
|
58
|
+
const findings = assessments.flatMap(({ fact, observation, verdict }) => verdict === 'FAIL' ? [finding(ruleId, fact, observation)] : []);
|
|
59
|
+
return { findings, status: findings.length === 0 ? 'PASS' : 'FAIL' };
|
|
60
|
+
}
|
|
61
|
+
/*** Accepts facts only from the complete active Rules scope. */
|
|
62
|
+
function sameScope(fact, input) {
|
|
63
|
+
return fact.scope.id === input.scope.id && fact.scope.kind === input.scope.kind;
|
|
64
|
+
}
|
|
65
|
+
/*** Parses available raw evidence while ignoring adapter-supplied verdict fields. */
|
|
66
|
+
function parseObservation(fact) {
|
|
67
|
+
if (fact.status !== 'available' || !isRecord(fact.value) || !isSubject(fact.value.subject))
|
|
68
|
+
return undefined;
|
|
69
|
+
const { subject, ...value } = fact.value;
|
|
70
|
+
return Object.values(value).every(isJsonValue) ? { subject, value } : undefined;
|
|
71
|
+
}
|
|
72
|
+
/*** Narrows a serializable raw observation field to the Rules JSON vocabulary. */
|
|
73
|
+
function isJsonValue(value) {
|
|
74
|
+
return (value === null ||
|
|
75
|
+
typeof value === 'boolean' ||
|
|
76
|
+
typeof value === 'number' ||
|
|
77
|
+
typeof value === 'string' ||
|
|
78
|
+
(Array.isArray(value) && value.every(isJsonValue)) ||
|
|
79
|
+
(isRecord(value) && Object.values(value).every(isJsonValue)));
|
|
80
|
+
}
|
|
81
|
+
/*** Narrows the observation provenance required for an evidence-backed finding. */
|
|
82
|
+
function isSubject(value) {
|
|
83
|
+
return isRecord(value) && text(value.id) && text(value.kind);
|
|
84
|
+
}
|
|
85
|
+
/*** Reports unavailable or malformed evidence without creating a false pass. */
|
|
86
|
+
function incomplete(ruleId, input) {
|
|
87
|
+
return {
|
|
88
|
+
findings: [
|
|
89
|
+
{
|
|
90
|
+
evidence: { scopeId: input.scope.id },
|
|
91
|
+
message: `${colorPolicySummary(ruleId)} No available normalized raw observation was supplied for this exact scope.`,
|
|
92
|
+
ruleId,
|
|
93
|
+
severity: 'info',
|
|
94
|
+
subjects: [{ id: input.scope.id, kind: input.scope.kind }],
|
|
95
|
+
},
|
|
96
|
+
],
|
|
97
|
+
status: 'INCOMPLETE',
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
/*** Creates an evidence-backed finding from a trusted policy contradiction. */
|
|
101
|
+
function finding(ruleId, fact, observation) {
|
|
102
|
+
return {
|
|
103
|
+
evidence: { factId: fact.id, observation: observation.value },
|
|
104
|
+
message: `${colorPolicySummary(ruleId)} Observed raw values contradict the configured policy.`,
|
|
105
|
+
ruleId,
|
|
106
|
+
severity: 'warning',
|
|
107
|
+
subjects: [observation.subject],
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/*** Supplies the frozen catalog summary for one Color and Tokens rule. */
|
|
111
|
+
function colorPolicySummary(ruleId) {
|
|
112
|
+
switch (ruleId) {
|
|
113
|
+
case 'design.color.active-state':
|
|
114
|
+
return 'Active color variation follows policy.';
|
|
115
|
+
case 'design.color.alpha-composition':
|
|
116
|
+
return 'Transparency is evaluated against the actual backdrop.';
|
|
117
|
+
case 'design.color.disabled-state':
|
|
118
|
+
return 'Disabled colors communicate disabled state.';
|
|
119
|
+
case 'design.color.hover-state':
|
|
120
|
+
return 'Hover color variation follows policy.';
|
|
121
|
+
case 'design.color.literal-drift':
|
|
122
|
+
return 'Unnecessary literal values do not drift from tokens.';
|
|
123
|
+
case 'design.color.ramp-consistency':
|
|
124
|
+
return 'Defined color ramps remain consistent.';
|
|
125
|
+
case 'design.color.semantic-role':
|
|
126
|
+
return 'Foreground, background, and border roles are semantically correct.';
|
|
127
|
+
case 'design.color.surface-role':
|
|
128
|
+
return 'Surface colors consistently express their role.';
|
|
129
|
+
case 'design.color.syntax-valid':
|
|
130
|
+
return 'Colors are syntactically valid.';
|
|
131
|
+
case 'design.color.theme-coverage':
|
|
132
|
+
return 'Light and dark theme tokens are available.';
|
|
133
|
+
case 'design.color.token-allowed':
|
|
134
|
+
return 'Only permitted palette tokens are used.';
|
|
135
|
+
case 'design.color.token-exists':
|
|
136
|
+
return 'Referenced color tokens exist.';
|
|
137
|
+
}
|
|
138
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { RuleSet } from '@ankhorage/rules';
|
|
2
|
+
import type { DesignContext } from '../../types/designRuleProvider';
|
|
3
|
+
import { type ColorRulePolicy } from './createColorPolicyRules';
|
|
4
|
+
export type { ColorRulePolicy } from './createColorPolicyRules';
|
|
5
|
+
/*** Creates the isolated Color and Tokens contribution without central registration. */
|
|
6
|
+
export declare function createColorRuleSet(policy: ColorRulePolicy): RuleSet<DesignContext>;
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { createColorPolicyRules } from './createColorPolicyRules';
|
|
3
|
+
/*** Creates the isolated Color and Tokens contribution without central registration. */
|
|
4
|
+
export function createColorRuleSet(policy) {
|
|
5
|
+
return {
|
|
6
|
+
id: 'ankhorage.rules-design.color',
|
|
7
|
+
rules: [...createColorPolicyRules(policy), createUsageRule(policy)],
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
/*** Evaluates rendered color areas against provider-owned targets and tolerances. */
|
|
11
|
+
function createUsageRule(policy) {
|
|
12
|
+
return {
|
|
13
|
+
defaultSeverity: 'warning',
|
|
14
|
+
dependencies: [],
|
|
15
|
+
evaluate: (input) => evaluateUsage(input, policy),
|
|
16
|
+
identity: { id: 'design.color.usage-distribution', version: '1.0.0' },
|
|
17
|
+
requiredCapabilities: ['rendered.area-analysis'],
|
|
18
|
+
summary: 'Compare separately measured rendered color-role areas with the configured distribution.',
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
/*** Keeps exact rule scope, breakpoint, theme, and coverage measurements isolated. */
|
|
22
|
+
function evaluateUsage(input, policy) {
|
|
23
|
+
const facts = (input.context.facts ?? []).filter((fact) => fact.kind === 'design.color.usage-distribution' && exactScope(fact, input));
|
|
24
|
+
const observations = facts.map(parseObservation);
|
|
25
|
+
if (facts.length === 0 || observations.some((value) => value === undefined))
|
|
26
|
+
return incomplete(input, 'No complete normalized rendered-area fact was supplied.');
|
|
27
|
+
const complete = observations.filter(isObservation);
|
|
28
|
+
const missing = missingCoverage(complete, policy);
|
|
29
|
+
if (missing.length > 0)
|
|
30
|
+
return incomplete(input, `Required rendered-area scope measurements are missing: ${missing.join(', ')}.`);
|
|
31
|
+
const page = complete.filter((observation) => observation.scope === 'page');
|
|
32
|
+
const failures = page.flatMap((observation) => deviations(observation, policy).map((value) => finding(value, 'warning')));
|
|
33
|
+
const diagnostics = complete
|
|
34
|
+
.filter((observation) => observation.scope !== 'page')
|
|
35
|
+
.flatMap((observation) => deviations(observation, policy).map((value) => finding(value, 'info')));
|
|
36
|
+
return {
|
|
37
|
+
findings: [...failures, ...diagnostics],
|
|
38
|
+
status: failures.length === 0 ? 'PASS' : 'FAIL',
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/*** Requires configured coverage for every breakpoint and theme without merging local samples. */
|
|
42
|
+
function missingCoverage(observations, policy) {
|
|
43
|
+
return policy.requiredBreakpointIds.flatMap((breakpointId) => policy.requiredThemeIds.flatMap((themeId) => policy.requiredScopes.flatMap((scope) => hasRequiredCoverage(observations, breakpointId, themeId, scope)
|
|
44
|
+
? []
|
|
45
|
+
: [`${breakpointId}:${themeId}:${scope}`])));
|
|
46
|
+
}
|
|
47
|
+
/*** Requires one page assessment and at least one advisory local sample for configured coverage. */
|
|
48
|
+
function hasRequiredCoverage(observations, breakpointId, themeId, scope) {
|
|
49
|
+
const matching = observations.filter((observation) => observation.breakpointId === breakpointId &&
|
|
50
|
+
observation.themeId === themeId &&
|
|
51
|
+
observation.scope === scope);
|
|
52
|
+
return scope === 'page' ? matching.length === 1 : matching.length > 0;
|
|
53
|
+
}
|
|
54
|
+
/*** Narrows a parsed observation after incomplete evidence has been rejected. */
|
|
55
|
+
function isObservation(observation) {
|
|
56
|
+
return observation !== undefined;
|
|
57
|
+
}
|
|
58
|
+
/*** Validates one available pixel observation including exact total and unknown coverage. */
|
|
59
|
+
function parseObservation(fact) {
|
|
60
|
+
if (fact.status !== 'available' || !isRecord(fact.value))
|
|
61
|
+
return undefined;
|
|
62
|
+
const { value } = fact;
|
|
63
|
+
const roles = value.rolePixels;
|
|
64
|
+
if (!isRecord(roles))
|
|
65
|
+
return undefined;
|
|
66
|
+
const identity = parseIdentity(value);
|
|
67
|
+
const pixels = parsePixels(value, roles);
|
|
68
|
+
if (!identity || !pixels)
|
|
69
|
+
return undefined;
|
|
70
|
+
const total = pixels.base + pixels.secondary + pixels.accent + pixels.unknown;
|
|
71
|
+
return total === pixels.measuredPixels &&
|
|
72
|
+
pixels.measuredPixels > 0 &&
|
|
73
|
+
pixels.unknown === pixels.unknownPixels &&
|
|
74
|
+
pixels.unknownPixels === 0
|
|
75
|
+
? {
|
|
76
|
+
...identity,
|
|
77
|
+
rolePixels: pixels,
|
|
78
|
+
measuredPixels: pixels.measuredPixels,
|
|
79
|
+
unknownPixels: pixels.unknownPixels,
|
|
80
|
+
}
|
|
81
|
+
: undefined;
|
|
82
|
+
}
|
|
83
|
+
/*** Parses the immutable breakpoint, theme, and coverage identity. */
|
|
84
|
+
function parseIdentity(value) {
|
|
85
|
+
return text(value.breakpointId) &&
|
|
86
|
+
text(value.themeId) &&
|
|
87
|
+
text(value.scopeId) &&
|
|
88
|
+
isCoverageScope(value.scope)
|
|
89
|
+
? {
|
|
90
|
+
breakpointId: value.breakpointId,
|
|
91
|
+
scope: value.scope,
|
|
92
|
+
scopeId: value.scopeId,
|
|
93
|
+
themeId: value.themeId,
|
|
94
|
+
}
|
|
95
|
+
: undefined;
|
|
96
|
+
}
|
|
97
|
+
/*** Parses exclusive integer pixel counters without accepting partial coverage. */
|
|
98
|
+
function parsePixels(value, roles) {
|
|
99
|
+
const { measuredPixels, unknownPixels } = value;
|
|
100
|
+
const { accent, base, secondary, unknown } = roles;
|
|
101
|
+
return pixel(measuredPixels) &&
|
|
102
|
+
pixel(unknownPixels) &&
|
|
103
|
+
pixel(accent) &&
|
|
104
|
+
pixel(base) &&
|
|
105
|
+
pixel(secondary) &&
|
|
106
|
+
pixel(unknown)
|
|
107
|
+
? { accent, base, measuredPixels, secondary, unknown, unknownPixels }
|
|
108
|
+
: undefined;
|
|
109
|
+
}
|
|
110
|
+
/*** Produces deviations only when the provider-owned tolerance is exceeded. */
|
|
111
|
+
function deviations(observation, policy) {
|
|
112
|
+
return [
|
|
113
|
+
deviation('base', observation.rolePixels.base, observation, policy.roleTargets.base, policy.roleTolerances.base),
|
|
114
|
+
deviation('secondary', observation.rolePixels.secondary, observation, policy.roleTargets.secondary, policy.roleTolerances.secondary),
|
|
115
|
+
deviation('accent', observation.rolePixels.accent, observation, policy.roleTargets.accent, policy.roleTolerances.accent),
|
|
116
|
+
].flatMap((value) => (value === undefined ? [] : [value]));
|
|
117
|
+
}
|
|
118
|
+
/*** Produces one deviation when a measured role exceeds its configured tolerance. */
|
|
119
|
+
function deviation(role, pixels, observation, target, tolerance) {
|
|
120
|
+
const observed = pixels / observation.measuredPixels;
|
|
121
|
+
return Math.abs(observed - target) > tolerance
|
|
122
|
+
? { observation, observed, role, target, tolerance }
|
|
123
|
+
: undefined;
|
|
124
|
+
}
|
|
125
|
+
/*** Creates a full-evidence finding while retaining advisory viewport and scroll results. */
|
|
126
|
+
function finding(value, severity) {
|
|
127
|
+
return {
|
|
128
|
+
evidence: {
|
|
129
|
+
breakpointId: value.observation.breakpointId,
|
|
130
|
+
observed: value.observed,
|
|
131
|
+
role: value.role,
|
|
132
|
+
scope: value.observation.scope,
|
|
133
|
+
scopeId: value.observation.scopeId,
|
|
134
|
+
target: value.target,
|
|
135
|
+
themeId: value.observation.themeId,
|
|
136
|
+
tolerance: value.tolerance,
|
|
137
|
+
unknownPixels: value.observation.unknownPixels,
|
|
138
|
+
},
|
|
139
|
+
message: `${value.role} occupies ${value.observed} of ${value.observation.scope}, outside its configured tolerance.`,
|
|
140
|
+
ruleId: 'design.color.usage-distribution',
|
|
141
|
+
severity,
|
|
142
|
+
subjects: [{ id: value.observation.scopeId, kind: 'rendered-color-scope' }],
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
/*** Reports missing evidence without allowing a partial page to pass. */
|
|
146
|
+
function incomplete(input, message) {
|
|
147
|
+
return {
|
|
148
|
+
findings: [
|
|
149
|
+
{
|
|
150
|
+
evidence: { scopeId: input.scope.id },
|
|
151
|
+
message,
|
|
152
|
+
ruleId: 'design.color.usage-distribution',
|
|
153
|
+
severity: 'info',
|
|
154
|
+
subjects: [{ id: input.scope.id, kind: input.scope.kind }],
|
|
155
|
+
},
|
|
156
|
+
],
|
|
157
|
+
status: 'INCOMPLETE',
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
/*** Compares the complete active Rules scope rather than only its identifier. */
|
|
161
|
+
function exactScope(fact, input) {
|
|
162
|
+
return fact.scope.id === input.scope.id && fact.scope.kind === input.scope.kind;
|
|
163
|
+
}
|
|
164
|
+
/*** Narrows a non-empty identifier. */
|
|
165
|
+
function text(value) {
|
|
166
|
+
return typeof value === 'string' && value.trim() !== '';
|
|
167
|
+
}
|
|
168
|
+
/*** Narrows a non-negative integer pixel count. */
|
|
169
|
+
function pixel(value) {
|
|
170
|
+
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
|
|
171
|
+
}
|
|
172
|
+
/*** Narrows coverage scope vocabulary. */
|
|
173
|
+
function isCoverageScope(value) {
|
|
174
|
+
return value === 'page' || value === 'scroll-sample' || value === 'viewport';
|
|
175
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { JsonValue } from '@ankhorage/rules';
|
|
2
|
+
import type { ColorPolicyRuleId, ColorRulePolicy } from '../../types/color';
|
|
3
|
+
type Verdict = 'FAIL' | 'INCOMPLETE' | 'PASS';
|
|
4
|
+
/*** Evaluates one normalized raw observation using its frozen Color rule policy. */
|
|
5
|
+
export declare function evaluateColorPolicyObservation(ruleId: ColorPolicyRuleId, value: Readonly<Record<string, JsonValue>>, policy: ColorRulePolicy): Verdict;
|
|
6
|
+
export {};
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import { colorObservationValues } from './colorObservationValues';
|
|
2
|
+
/*** Evaluates one normalized raw observation using its frozen Color rule policy. */
|
|
3
|
+
export function evaluateColorPolicyObservation(ruleId, value, policy) {
|
|
4
|
+
switch (ruleId) {
|
|
5
|
+
case 'design.color.syntax-valid':
|
|
6
|
+
return syntaxValid(value, policy);
|
|
7
|
+
case 'design.color.token-exists':
|
|
8
|
+
return tokenExists(value, policy);
|
|
9
|
+
case 'design.color.token-allowed':
|
|
10
|
+
return tokenAllowed(value, policy);
|
|
11
|
+
case 'design.color.semantic-role':
|
|
12
|
+
return semanticRole(value, policy);
|
|
13
|
+
case 'design.color.literal-drift':
|
|
14
|
+
return literalDrift(value, policy);
|
|
15
|
+
case 'design.color.ramp-consistency':
|
|
16
|
+
return rampConsistency(value, policy);
|
|
17
|
+
case 'design.color.alpha-composition':
|
|
18
|
+
return alphaComposition(value, policy);
|
|
19
|
+
case 'design.color.surface-role':
|
|
20
|
+
return surfaceRole(value, policy);
|
|
21
|
+
case 'design.color.hover-state':
|
|
22
|
+
return state(value, policy, 'hover');
|
|
23
|
+
case 'design.color.active-state':
|
|
24
|
+
return state(value, policy, 'active');
|
|
25
|
+
case 'design.color.disabled-state':
|
|
26
|
+
return state(value, policy, 'disabled');
|
|
27
|
+
case 'design.color.theme-coverage':
|
|
28
|
+
return themeCoverage(value, policy);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/*** Confirms syntax policy and the corresponding literal form. */
|
|
32
|
+
function syntaxValid(value, policy) {
|
|
33
|
+
const { color, syntax } = value;
|
|
34
|
+
if (!colorObservationValues.text(color) || !colorObservationValues.text(syntax))
|
|
35
|
+
return 'INCOMPLETE';
|
|
36
|
+
return policy.allowedColorSyntaxes.includes(syntax) && validColorSyntax(color, syntax)
|
|
37
|
+
? 'PASS'
|
|
38
|
+
: 'FAIL';
|
|
39
|
+
}
|
|
40
|
+
/*** Validates the supported syntax representation without deriving a policy verdict. */
|
|
41
|
+
function validColorSyntax(color, syntax) {
|
|
42
|
+
if (syntax === 'hex')
|
|
43
|
+
return /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/iu.test(color);
|
|
44
|
+
if (syntax === 'token')
|
|
45
|
+
return /^[-\w./]+$/u.test(color);
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
/*** Requires a referenced token to be present in the trusted inventory. */
|
|
49
|
+
function tokenExists(value, policy) {
|
|
50
|
+
return colorObservationValues.text(value.token)
|
|
51
|
+
? policy.knownTokens.includes(value.token)
|
|
52
|
+
? 'PASS'
|
|
53
|
+
: 'FAIL'
|
|
54
|
+
: 'INCOMPLETE';
|
|
55
|
+
}
|
|
56
|
+
/*** Requires a referenced token to be permitted for use. */
|
|
57
|
+
function tokenAllowed(value, policy) {
|
|
58
|
+
return colorObservationValues.text(value.token)
|
|
59
|
+
? policy.allowedTokens.includes(value.token)
|
|
60
|
+
? 'PASS'
|
|
61
|
+
: 'FAIL'
|
|
62
|
+
: 'INCOMPLETE';
|
|
63
|
+
}
|
|
64
|
+
/*** Checks that a semantic role uses one of its trusted tokens. */
|
|
65
|
+
function semanticRole(value, policy) {
|
|
66
|
+
const { role, token } = value;
|
|
67
|
+
if (!colorObservationValues.text(role) || !colorObservationValues.text(token))
|
|
68
|
+
return 'INCOMPLETE';
|
|
69
|
+
return configuredTokens(policy.semanticRoleTokens, role)?.includes(token) ? 'PASS' : 'FAIL';
|
|
70
|
+
}
|
|
71
|
+
/*** Rejects a canonical literal when it identifies a different token. */
|
|
72
|
+
function literalDrift(value, policy) {
|
|
73
|
+
const { literal, token } = value;
|
|
74
|
+
if (!colorObservationValues.text(literal) || !colorObservationValues.text(token))
|
|
75
|
+
return 'INCOMPLETE';
|
|
76
|
+
const canonicalToken = configuredValue(policy.canonicalLiterals, literal);
|
|
77
|
+
return canonicalToken === undefined || canonicalToken === token ? 'PASS' : 'FAIL';
|
|
78
|
+
}
|
|
79
|
+
/*** Verifies the complete ordered token sequence for a named color ramp. */
|
|
80
|
+
function rampConsistency(value, policy) {
|
|
81
|
+
const { ramp } = value;
|
|
82
|
+
const tokens = colorObservationValues.strings(value.tokens);
|
|
83
|
+
if (!colorObservationValues.text(ramp) || tokens === undefined)
|
|
84
|
+
return 'INCOMPLETE';
|
|
85
|
+
const expectedTokens = configuredTokens(policy.rampTokens, ramp);
|
|
86
|
+
return expectedTokens !== undefined && colorObservationValues.sequence(tokens, expectedTokens)
|
|
87
|
+
? 'PASS'
|
|
88
|
+
: 'FAIL';
|
|
89
|
+
}
|
|
90
|
+
/*** Verifies a foreground and backdrop against their trusted composited result. */
|
|
91
|
+
function alphaComposition(value, policy) {
|
|
92
|
+
const { backdrop, composite, foreground } = value;
|
|
93
|
+
if (!colorObservationValues.text(foreground) ||
|
|
94
|
+
!colorObservationValues.text(backdrop) ||
|
|
95
|
+
!colorObservationValues.text(composite))
|
|
96
|
+
return 'INCOMPLETE';
|
|
97
|
+
const composites = configuredTokens(policy.alphaCompositions, foreground);
|
|
98
|
+
return configuredValue(composites, backdrop) === composite ? 'PASS' : 'FAIL';
|
|
99
|
+
}
|
|
100
|
+
/*** Checks the configured token inventory for a rendered surface role. */
|
|
101
|
+
function surfaceRole(value, policy) {
|
|
102
|
+
const { surface, token } = value;
|
|
103
|
+
if (!colorObservationValues.text(surface) || !colorObservationValues.text(token))
|
|
104
|
+
return 'INCOMPLETE';
|
|
105
|
+
return configuredTokens(policy.surfaceRoleTokens, surface)?.includes(token) ? 'PASS' : 'FAIL';
|
|
106
|
+
}
|
|
107
|
+
/*** Checks the configured transition token for one interactive state. */
|
|
108
|
+
function state(value, policy, stateName) {
|
|
109
|
+
const { baseToken, stateToken } = value;
|
|
110
|
+
if (!colorObservationValues.text(baseToken) || !colorObservationValues.text(stateToken))
|
|
111
|
+
return 'INCOMPLETE';
|
|
112
|
+
return configuredValue(statePolicy(policy, stateName), baseToken) === stateToken
|
|
113
|
+
? 'PASS'
|
|
114
|
+
: 'FAIL';
|
|
115
|
+
}
|
|
116
|
+
/*** Selects a fixed interactive state map without dynamic policy object access. */
|
|
117
|
+
function statePolicy(policy, stateName) {
|
|
118
|
+
switch (stateName) {
|
|
119
|
+
case 'active':
|
|
120
|
+
return policy.stateTokens.active;
|
|
121
|
+
case 'disabled':
|
|
122
|
+
return policy.stateTokens.disabled;
|
|
123
|
+
case 'hover':
|
|
124
|
+
return policy.stateTokens.hover;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/*** Requires a token to supply every required theme in its policy inventory. */
|
|
128
|
+
function themeCoverage(value, policy) {
|
|
129
|
+
const { token } = value;
|
|
130
|
+
const themes = colorObservationValues.strings(value.themes);
|
|
131
|
+
if (!colorObservationValues.text(token) || themes === undefined)
|
|
132
|
+
return 'INCOMPLETE';
|
|
133
|
+
const configuredThemes = configuredTokens(policy.themeTokens, token);
|
|
134
|
+
return configuredThemes !== undefined &&
|
|
135
|
+
policy.requiredThemeIds.every((theme) => themes.includes(theme) && configuredThemes.includes(theme))
|
|
136
|
+
? 'PASS'
|
|
137
|
+
: 'FAIL';
|
|
138
|
+
}
|
|
139
|
+
/*** Retrieves a configured string value without dynamic object indexing. */
|
|
140
|
+
function configuredValue(values, key) {
|
|
141
|
+
return values === undefined
|
|
142
|
+
? undefined
|
|
143
|
+
: Object.entries(values).find(([entry]) => entry === key)?.[1];
|
|
144
|
+
}
|
|
145
|
+
/*** Retrieves a configured string list without dynamic object indexing. */
|
|
146
|
+
function configuredTokens(values, key) {
|
|
147
|
+
return Object.entries(values).find(([entry]) => entry === key)?.[1];
|
|
148
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
/*** Verifies trusted Color factory policy before assessment closures are created. */
|
|
3
|
+
export function isColorRulePolicy(value) {
|
|
4
|
+
return (isRecord(value) &&
|
|
5
|
+
value.version === 1 &&
|
|
6
|
+
corePolicy(value) &&
|
|
7
|
+
colorSyntaxes(value.allowedColorSyntaxes) &&
|
|
8
|
+
identifiers(value.knownTokens) &&
|
|
9
|
+
identifiers(value.allowedTokens) &&
|
|
10
|
+
identifiers(value.requiredBreakpointIds) &&
|
|
11
|
+
identifiers(value.requiredThemeIds) &&
|
|
12
|
+
coverageScopes(value.requiredScopes) &&
|
|
13
|
+
roleMap(value.roleTargets, true) &&
|
|
14
|
+
roleMap(value.roleTolerances, false));
|
|
15
|
+
}
|
|
16
|
+
/*** Validates the semantic policy maps independently from the coverage policy. */
|
|
17
|
+
function corePolicy(value) {
|
|
18
|
+
return (stringMap(value.canonicalLiterals) &&
|
|
19
|
+
tokenLists(value.rampTokens) &&
|
|
20
|
+
nestedTokenMap(value.alphaCompositions) &&
|
|
21
|
+
tokenLists(value.semanticRoleTokens) &&
|
|
22
|
+
tokenLists(value.surfaceRoleTokens) &&
|
|
23
|
+
stateTokenMaps(value.stateTokens) &&
|
|
24
|
+
tokenLists(value.themeTokens));
|
|
25
|
+
}
|
|
26
|
+
/*** Requires non-empty unique policy identifiers. */
|
|
27
|
+
function identifiers(value) {
|
|
28
|
+
return (Array.isArray(value) &&
|
|
29
|
+
value.length > 0 &&
|
|
30
|
+
new Set(value).size === value.length &&
|
|
31
|
+
value.every(text));
|
|
32
|
+
}
|
|
33
|
+
/*** Requires configured Color syntax formats to use the supported closed vocabulary. */
|
|
34
|
+
function colorSyntaxes(value) {
|
|
35
|
+
return identifiers(value) && value.every((syntax) => syntax === 'hex' || syntax === 'token');
|
|
36
|
+
}
|
|
37
|
+
/*** Narrows a complete map of raw literal values to canonical token names. */
|
|
38
|
+
function stringMap(value) {
|
|
39
|
+
return isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(text);
|
|
40
|
+
}
|
|
41
|
+
/*** Narrows a semantic role map whose entries are non-empty trusted token inventories. */
|
|
42
|
+
function tokenLists(value) {
|
|
43
|
+
return (isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(identifiers));
|
|
44
|
+
}
|
|
45
|
+
/*** Narrows a foreground and backdrop matrix to its trusted composited token. */
|
|
46
|
+
function nestedTokenMap(value) {
|
|
47
|
+
return isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(stringMap);
|
|
48
|
+
}
|
|
49
|
+
/*** Narrows the three explicit interactive state policies. */
|
|
50
|
+
function stateTokenMaps(value) {
|
|
51
|
+
return (isRecord(value) &&
|
|
52
|
+
stringMap(value.active) &&
|
|
53
|
+
stringMap(value.disabled) &&
|
|
54
|
+
stringMap(value.hover));
|
|
55
|
+
}
|
|
56
|
+
/*** Requires page evidence while allowing any enabled local diagnostic scopes. */
|
|
57
|
+
function coverageScopes(value) {
|
|
58
|
+
return (Array.isArray(value) &&
|
|
59
|
+
value.includes('page') &&
|
|
60
|
+
new Set(value).size === value.length &&
|
|
61
|
+
value.every((scope) => scope === 'page' || scope === 'scroll-sample' || scope === 'viewport'));
|
|
62
|
+
}
|
|
63
|
+
/*** Checks normalized target or tolerance role maps. */
|
|
64
|
+
function roleMap(value, target) {
|
|
65
|
+
if (!isRecord(value))
|
|
66
|
+
return false;
|
|
67
|
+
const { accent, base, secondary } = value;
|
|
68
|
+
return (proportion(accent) &&
|
|
69
|
+
proportion(base) &&
|
|
70
|
+
proportion(secondary) &&
|
|
71
|
+
(!target ||
|
|
72
|
+
(typeof base === 'number' &&
|
|
73
|
+
typeof secondary === 'number' &&
|
|
74
|
+
typeof accent === 'number' &&
|
|
75
|
+
Math.abs(base + secondary + accent - 1) < Number.EPSILON)));
|
|
76
|
+
}
|
|
77
|
+
/*** Narrows a finite role proportion within the supported inclusive range. */
|
|
78
|
+
function proportion(value) {
|
|
79
|
+
return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
|
|
80
|
+
}
|
|
81
|
+
/*** Narrows a non-empty identifier. */
|
|
82
|
+
function text(value) {
|
|
83
|
+
return typeof value === 'string' && value.trim() !== '';
|
|
84
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { FactEnvelope } from '@ankhorage/contracts/rules';
|
|
2
|
+
import type { Rule } from '@ankhorage/rules';
|
|
3
|
+
interface Context {
|
|
4
|
+
readonly facts: readonly FactEnvelope[];
|
|
5
|
+
}
|
|
6
|
+
/*** Creates the independent Contrast and Visual Hierarchy rule contribution without central registration. */
|
|
7
|
+
export declare function createContrastRules(): readonly Rule<Context>[];
|
|
8
|
+
export {};
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { hasValidContrastMeasurement } from './hasValidContrastMeasurement';
|
|
3
|
+
const definitions = [
|
|
4
|
+
{
|
|
5
|
+
id: 'design.contrast.text-ratio',
|
|
6
|
+
requiredCapabilities: ['dom.computed-style', 'dom.text-content'],
|
|
7
|
+
severity: 'error',
|
|
8
|
+
summary: 'Require observed effective text contrast to meet the selected WCAG standard.',
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
id: 'design.contrast.nontext-ratio',
|
|
12
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
13
|
+
severity: 'error',
|
|
14
|
+
summary: 'Require observed non-text contrast to meet WCAG AA.',
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
id: 'design.contrast.focus-visible',
|
|
18
|
+
requiredCapabilities: ['dom.computed-style', 'browser.interaction-state'],
|
|
19
|
+
severity: 'error',
|
|
20
|
+
summary: 'Require a visible focus indicator with sufficient contrast.',
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
id: 'design.contrast.surface-separation',
|
|
24
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
25
|
+
severity: 'error',
|
|
26
|
+
summary: 'Require adjacent effective surfaces to remain distinguishable.',
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
id: 'design.contrast.state-distinction',
|
|
30
|
+
requiredCapabilities: ['dom.computed-style', 'browser.interaction-state'],
|
|
31
|
+
severity: 'error',
|
|
32
|
+
summary: 'Require observed interactive states to remain distinct.',
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
id: 'design.contrast.link-distinction',
|
|
36
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
37
|
+
severity: 'error',
|
|
38
|
+
summary: 'Require links to have a non-color cue or sufficient distinction.',
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
id: 'design.contrast.text-background-resolved',
|
|
42
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
43
|
+
severity: 'error',
|
|
44
|
+
summary: 'Require an observed effective text background.',
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
id: 'design.contrast.cta-prominence',
|
|
48
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
49
|
+
severity: 'warning',
|
|
50
|
+
summary: 'Require a primary CTA to exceed competing visual prominence.',
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
id: 'design.contrast.visual-hierarchy',
|
|
54
|
+
requiredCapabilities: ['dom.computed-style'],
|
|
55
|
+
severity: 'warning',
|
|
56
|
+
summary: 'Require observed visual emphasis to descend through a hierarchy.',
|
|
57
|
+
},
|
|
58
|
+
];
|
|
59
|
+
/*** Creates the independent Contrast and Visual Hierarchy rule contribution without central registration. */
|
|
60
|
+
export function createContrastRules() {
|
|
61
|
+
return definitions.map(createRule);
|
|
62
|
+
}
|
|
63
|
+
/*** Creates one frozen rule whose policy is controlled by validated options or canonical standards. */
|
|
64
|
+
function createRule(definition) {
|
|
65
|
+
return {
|
|
66
|
+
defaultSeverity: definition.severity,
|
|
67
|
+
dependencies: [],
|
|
68
|
+
identity: { id: definition.id, version: '1.0.0' },
|
|
69
|
+
requiredCapabilities: definition.requiredCapabilities,
|
|
70
|
+
summary: definition.summary,
|
|
71
|
+
validateOptions: (options) => validateOptions(definition.id, options),
|
|
72
|
+
evaluate: ({ context, options, scope }) => evaluate(definition, context.facts, options, scope),
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
/*** Evaluates exact-scope observations, rejecting absent, malformed, and self-judging evidence. */
|
|
76
|
+
function evaluate(definition, facts, options, scope) {
|
|
77
|
+
const standard = standardFor(definition.id, options);
|
|
78
|
+
const scoped = facts.filter((fact) => matchesRuleScope(fact, definition.id, scope));
|
|
79
|
+
if (scoped.length === 0)
|
|
80
|
+
return incomplete(definition.id, scope);
|
|
81
|
+
const observations = scoped.flatMap((fact) => toContrastObservation(fact, definition.id));
|
|
82
|
+
if (observations.length !== scoped.length)
|
|
83
|
+
return incomplete(definition.id, scope);
|
|
84
|
+
const failures = observations.filter((observation) => !passes(definition.id, observation.value, standard));
|
|
85
|
+
return failures.length === 0
|
|
86
|
+
? { findings: [], status: 'PASS' }
|
|
87
|
+
: {
|
|
88
|
+
findings: failures.map((observation) => failure(definition, standard, observation)),
|
|
89
|
+
status: 'FAIL',
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
/*** Selects only facts whose producer-declared kind identifies this exact frozen rule and scope. */
|
|
93
|
+
function matchesRuleScope(fact, id, scope) {
|
|
94
|
+
return fact.kind === id && fact.scope.id === scope.id && fact.scope.kind === scope.kind;
|
|
95
|
+
}
|
|
96
|
+
/*** Validates a closed versioned standard choice rather than arbitrary numeric acceptance criteria. */
|
|
97
|
+
function validateOptions(id, options) {
|
|
98
|
+
return options === undefined ||
|
|
99
|
+
(isRecord(options) &&
|
|
100
|
+
options.version === 1 &&
|
|
101
|
+
typeof options.standard === 'string' &&
|
|
102
|
+
supportsStandard(id, options.standard) &&
|
|
103
|
+
Object.keys(options).every((key) => key === 'version' || key === 'standard'))
|
|
104
|
+
? []
|
|
105
|
+
: [
|
|
106
|
+
{
|
|
107
|
+
code: 'invalid-contrast-options',
|
|
108
|
+
message: 'Options must contain version 1 and a standard.',
|
|
109
|
+
},
|
|
110
|
+
];
|
|
111
|
+
}
|
|
112
|
+
/*** Confines each frozen rule to the standards its policy can evaluate. */
|
|
113
|
+
function supportsStandard(id, standard) {
|
|
114
|
+
if (id === 'design.contrast.text-ratio')
|
|
115
|
+
return ['wcag-aa-large', 'wcag-aa-normal', 'wcag-aaa-large', 'wcag-aaa-normal'].includes(standard);
|
|
116
|
+
if (id === 'design.contrast.cta-prominence' || id === 'design.contrast.visual-hierarchy')
|
|
117
|
+
return ['heuristic-clear', 'heuristic-strong'].includes(standard);
|
|
118
|
+
if (id === 'design.contrast.text-background-resolved')
|
|
119
|
+
return standard === 'heuristic-clear';
|
|
120
|
+
return standard === 'wcag-aa-nontext';
|
|
121
|
+
}
|
|
122
|
+
/*** Resolves a canonical or validated standard owned by the rule rather than its fact envelope. */
|
|
123
|
+
function standardFor(id, options) {
|
|
124
|
+
const selected = isRecord(options) && typeof options.standard === 'string' ? options.standard : undefined;
|
|
125
|
+
if (id === 'design.contrast.text-ratio') {
|
|
126
|
+
return ['wcag-aa-large', 'wcag-aa-normal', 'wcag-aaa-large', 'wcag-aaa-normal'].includes(selected ?? '')
|
|
127
|
+
? (selected ?? 'wcag-aa-normal')
|
|
128
|
+
: 'wcag-aa-normal';
|
|
129
|
+
}
|
|
130
|
+
return id === 'design.contrast.cta-prominence' || id === 'design.contrast.visual-hierarchy'
|
|
131
|
+
? selected === 'heuristic-strong'
|
|
132
|
+
? selected
|
|
133
|
+
: 'heuristic-clear'
|
|
134
|
+
: id === 'design.contrast.text-background-resolved'
|
|
135
|
+
? 'heuristic-clear'
|
|
136
|
+
: 'wcag-aa-nontext';
|
|
137
|
+
}
|
|
138
|
+
/*** Converts one available contrast fact into a fully validated rule observation. */
|
|
139
|
+
function toContrastObservation(fact, id) {
|
|
140
|
+
if (fact.status !== 'available' || !valid(fact.value, id))
|
|
141
|
+
return [];
|
|
142
|
+
return [{ subject: fact.value.subject, value: fact.value }];
|
|
143
|
+
}
|
|
144
|
+
/*** Validates rule-specific observations and forbids evidence-provided comparisons or thresholds. */
|
|
145
|
+
function valid(value, id) {
|
|
146
|
+
return isBaseObservation(value, id) && hasValidContrastMeasurement(id, value);
|
|
147
|
+
}
|
|
148
|
+
/*** Verifies the evidence fields shared by every Contrast observation. */
|
|
149
|
+
function isBaseObservation(value, id) {
|
|
150
|
+
return (isRecord(value) &&
|
|
151
|
+
value.ruleId === id &&
|
|
152
|
+
isRuleSubject(value.subject) &&
|
|
153
|
+
!['comparison', 'expected', 'minimum', 'operator', 'threshold'].some((key) => key in value));
|
|
154
|
+
}
|
|
155
|
+
/*** Applies the rule-owned semantic standard to one complete observation. */
|
|
156
|
+
function passes(id, value, standard) {
|
|
157
|
+
if (id === 'design.contrast.text-background-resolved')
|
|
158
|
+
return true;
|
|
159
|
+
if (id === 'design.contrast.cta-prominence')
|
|
160
|
+
return (Number(value.primaryProminence) - Number(value.competingProminence) >=
|
|
161
|
+
(standard === 'heuristic-strong' ? 0.2 : 0.1));
|
|
162
|
+
if (id === 'design.contrast.visual-hierarchy') {
|
|
163
|
+
const { emphasis } = value;
|
|
164
|
+
if (!isJsonValueArray(emphasis) || emphasis.length < 2)
|
|
165
|
+
return false;
|
|
166
|
+
return emphasis.slice(1).every((entry, index) => {
|
|
167
|
+
const previous = emphasis.at(index);
|
|
168
|
+
return (isScore(entry) &&
|
|
169
|
+
isScore(previous) &&
|
|
170
|
+
previous.score - entry.score >= (standard === 'heuristic-strong' ? 0.2 : 0.1));
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
if (id === 'design.contrast.link-distinction')
|
|
174
|
+
return value.nonColorCueVisible === true || Number(value.distinguishingContrastRatio) >= 3;
|
|
175
|
+
if (id === 'design.contrast.focus-visible')
|
|
176
|
+
return value.focusIndicatorVisible === true && Number(value.contrastRatio) >= 3;
|
|
177
|
+
return (Number(value.contrastRatio) >=
|
|
178
|
+
(standard === 'wcag-aaa-normal'
|
|
179
|
+
? 7
|
|
180
|
+
: standard === 'wcag-aa-large' || standard === 'wcag-aa-nontext'
|
|
181
|
+
? 3
|
|
182
|
+
: 4.5));
|
|
183
|
+
}
|
|
184
|
+
/*** Produces an incomplete result when evidence cannot prove this exact-scope rule. */
|
|
185
|
+
function incomplete(id, scope) {
|
|
186
|
+
return {
|
|
187
|
+
findings: [
|
|
188
|
+
{
|
|
189
|
+
evidence: { scopeId: scope.id, scopeKind: scope.kind },
|
|
190
|
+
message: `Rule "${id}" is incomplete for scope "${scope.kind}:${scope.id}".`,
|
|
191
|
+
ruleId: id,
|
|
192
|
+
severity: 'info',
|
|
193
|
+
subjects: [{ id: scope.id, kind: scope.kind }],
|
|
194
|
+
},
|
|
195
|
+
],
|
|
196
|
+
status: 'INCOMPLETE',
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
/*** Retains observed evidence and the applied canonical standard for a failed rule. */
|
|
200
|
+
function failure(definition, standard, observation) {
|
|
201
|
+
return {
|
|
202
|
+
evidence: { observation: observation.value, standard },
|
|
203
|
+
message: `Observed ${definition.id} evidence does not meet the ${standard} standard.`,
|
|
204
|
+
ruleId: definition.id,
|
|
205
|
+
severity: definition.severity,
|
|
206
|
+
subjects: [observation.subject],
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
/*** Narrows a serializable subject to the Rules finding contract. */
|
|
210
|
+
function isRuleSubject(value) {
|
|
211
|
+
return (isRecord(value) &&
|
|
212
|
+
typeof value.id === 'string' &&
|
|
213
|
+
value.id.length > 0 &&
|
|
214
|
+
typeof value.kind === 'string' &&
|
|
215
|
+
value.kind.length > 0 &&
|
|
216
|
+
(value.path === undefined || (typeof value.path === 'string' && value.path.length > 0)));
|
|
217
|
+
}
|
|
218
|
+
/*** Narrows a JSON value to an immutable sequence of JSON values. */
|
|
219
|
+
function isJsonValueArray(value) {
|
|
220
|
+
return Array.isArray(value);
|
|
221
|
+
}
|
|
222
|
+
/*** Narrows a hierarchy entry to a finite observed emphasis score. */
|
|
223
|
+
function isScore(value) {
|
|
224
|
+
return isRecord(value) && typeof value.score === 'number' && Number.isFinite(value.score);
|
|
225
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
/*** Verifies the complete observation shape required by one frozen Contrast rule. */
|
|
3
|
+
export function hasValidContrastMeasurement(id, value) {
|
|
4
|
+
const validator = measurementValidators.get(id);
|
|
5
|
+
return validator?.(value) === true;
|
|
6
|
+
}
|
|
7
|
+
const measurementValidators = new Map([
|
|
8
|
+
[
|
|
9
|
+
'design.contrast.cta-prominence',
|
|
10
|
+
(value) => number(value.primaryProminence) && number(value.competingProminence),
|
|
11
|
+
],
|
|
12
|
+
[
|
|
13
|
+
'design.contrast.focus-visible',
|
|
14
|
+
(value) => number(value.contrastRatio) &&
|
|
15
|
+
typeof value.focusIndicatorVisible === 'boolean' &&
|
|
16
|
+
text(value.effectiveBackground),
|
|
17
|
+
],
|
|
18
|
+
[
|
|
19
|
+
'design.contrast.link-distinction',
|
|
20
|
+
(value) => number(value.distinguishingContrastRatio) && typeof value.nonColorCueVisible === 'boolean',
|
|
21
|
+
],
|
|
22
|
+
['design.contrast.nontext-ratio', hasColorRatio],
|
|
23
|
+
[
|
|
24
|
+
'design.contrast.state-distinction',
|
|
25
|
+
(value) => number(value.contrastRatio) &&
|
|
26
|
+
text(value.state) &&
|
|
27
|
+
text(value.comparedState) &&
|
|
28
|
+
value.state !== value.comparedState,
|
|
29
|
+
],
|
|
30
|
+
[
|
|
31
|
+
'design.contrast.surface-separation',
|
|
32
|
+
(value) => number(value.contrastRatio) &&
|
|
33
|
+
text(value.firstEffectiveBackground) &&
|
|
34
|
+
text(value.secondEffectiveBackground),
|
|
35
|
+
],
|
|
36
|
+
[
|
|
37
|
+
'design.contrast.text-background-resolved',
|
|
38
|
+
(value) => text(value.effectiveBackground) &&
|
|
39
|
+
Number.isInteger(value.backgroundLayerCount) &&
|
|
40
|
+
Number(value.backgroundLayerCount) > 0,
|
|
41
|
+
],
|
|
42
|
+
['design.contrast.text-ratio', hasColorRatio],
|
|
43
|
+
['design.contrast.visual-hierarchy', (value) => isEmphasis(value.emphasis)],
|
|
44
|
+
]);
|
|
45
|
+
/*** Validates a complete foreground-to-effective-background contrast measurement. */
|
|
46
|
+
function hasColorRatio(value) {
|
|
47
|
+
return number(value.contrastRatio) && text(value.effectiveBackground) && text(value.foreground);
|
|
48
|
+
}
|
|
49
|
+
/*** Narrows ordered hierarchy entries to finite observed emphasis scores. */
|
|
50
|
+
function isEmphasis(value) {
|
|
51
|
+
return (isJsonValueArray(value) &&
|
|
52
|
+
value.length > 1 &&
|
|
53
|
+
value.every((entry) => isRecord(entry) && number(entry.score)));
|
|
54
|
+
}
|
|
55
|
+
/*** Narrows a JSON value to an immutable sequence of JSON values. */
|
|
56
|
+
function isJsonValueArray(value) {
|
|
57
|
+
return Array.isArray(value);
|
|
58
|
+
}
|
|
59
|
+
/*** Checks finite non-negative numeric observations. */
|
|
60
|
+
function number(value) {
|
|
61
|
+
return typeof value === 'number' && Number.isFinite(value) && value >= 0;
|
|
62
|
+
}
|
|
63
|
+
/*** Checks non-empty textual observations. */
|
|
64
|
+
function text(value) {
|
|
65
|
+
return typeof value === 'string' && value.length > 0;
|
|
66
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/*** Identifies one frozen atomic Color policy rule. */
|
|
2
|
+
export type ColorPolicyRuleId = 'design.color.syntax-valid' | 'design.color.token-exists' | 'design.color.token-allowed' | 'design.color.semantic-role' | 'design.color.literal-drift' | 'design.color.ramp-consistency' | 'design.color.alpha-composition' | 'design.color.surface-role' | 'design.color.hover-state' | 'design.color.active-state' | 'design.color.disabled-state' | 'design.color.theme-coverage';
|
|
3
|
+
type ColorState = 'active' | 'disabled' | 'hover';
|
|
4
|
+
type ColorRole = 'accent' | 'base' | 'secondary';
|
|
5
|
+
type RoleValues = Readonly<Record<ColorRole, number>>;
|
|
6
|
+
/*** Configures trusted semantic acceptance and coverage policy for frozen Color rules. */
|
|
7
|
+
export interface ColorRulePolicy {
|
|
8
|
+
readonly alphaCompositions: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
9
|
+
readonly allowedColorSyntaxes: readonly string[];
|
|
10
|
+
readonly allowedTokens: readonly string[];
|
|
11
|
+
readonly canonicalLiterals: Readonly<Record<string, string>>;
|
|
12
|
+
readonly knownTokens: readonly string[];
|
|
13
|
+
readonly rampTokens: Readonly<Record<string, readonly string[]>>;
|
|
14
|
+
readonly requiredBreakpointIds: readonly string[];
|
|
15
|
+
readonly requiredScopes: readonly ('page' | 'scroll-sample' | 'viewport')[];
|
|
16
|
+
readonly requiredThemeIds: readonly string[];
|
|
17
|
+
readonly roleTargets: RoleValues;
|
|
18
|
+
readonly roleTolerances: RoleValues;
|
|
19
|
+
readonly semanticRoleTokens: Readonly<Record<string, readonly string[]>>;
|
|
20
|
+
readonly stateTokens: Readonly<Record<ColorState, Readonly<Record<string, string>>>>;
|
|
21
|
+
readonly surfaceRoleTokens: Readonly<Record<string, readonly string[]>>;
|
|
22
|
+
readonly themeTokens: Readonly<Record<string, readonly string[]>>;
|
|
23
|
+
readonly version: number;
|
|
24
|
+
}
|
|
25
|
+
export {};
|
|
File without changes
|