@ankhorage/rules-design 0.0.0-stage → 0.2.0
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 +15 -0
- package/LICENSE +21 -0
- package/README.md +38 -2
- package/dist/features/catalog/designRuleCatalog.d.ts +3 -0
- package/dist/features/catalog/designRuleCatalog.js +211 -0
- package/dist/features/catalog/designRuleComposites.d.ts +3 -0
- package/dist/features/catalog/designRuleComposites.js +47 -0
- package/dist/features/catalog/designRuleProfiles.d.ts +3 -0
- package/dist/features/catalog/designRuleProfiles.js +29 -0
- package/dist/features/catalog/designRuleProviderManifest.d.ts +3 -0
- package/dist/features/catalog/designRuleProviderManifest.js +7 -0
- package/dist/features/catalog/designRuleSemantics.d.ts +9 -0
- package/dist/features/catalog/designRuleSemantics.js +120 -0
- package/dist/features/catalog/filterDesignRuleCatalog.d.ts +3 -0
- package/dist/features/catalog/filterDesignRuleCatalog.js +11 -0
- package/dist/features/catalog/fixtures/designRuleCatalogManifest.d.ts +3 -0
- package/dist/features/catalog/fixtures/designRuleCatalogManifest.js +8 -0
- package/dist/features/provider/designRuleProvider.d.ts +3 -0
- package/dist/features/provider/designRuleProvider.js +9 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +5 -0
- package/dist/types/designRuleCatalog.d.ts +45 -0
- package/dist/types/designRuleCatalog.js +0 -0
- package/dist/types/designRuleProvider.d.ts +16 -0
- package/dist/types/designRuleProvider.js +0 -0
- package/package.json +61 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 41ed755: Expose the reusable Design RuleSet provider through the generic Rules engine.
|
|
8
|
+
|
|
9
|
+
## 0.1.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 676d01f: Publish the frozen design-rule catalog and provider manifest.
|
|
14
|
+
|
|
15
|
+
All notable changes to this package will be documented in this file by the managed release workflow.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ankhorage
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,39 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- markdownlint-disable MD013 MD033 -->
|
|
2
|
+
<!-- This file is generated by Paradox. Do not edit manually. -->
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
# @ankhorage/rules-design
|
|
5
|
+
|
|
6
|
+
        
|
|
7
|
+
|
|
8
|
+
Declarative catalog for reusable design rules.
|
|
9
|
+
|
|
10
|
+
## Usage
|
|
11
|
+
|
|
12
|
+
### CLI
|
|
13
|
+
|
|
14
|
+
Ankhorage packages expose their command-line interface through `ankh`. Use `ankh --help` to discover available package commands, or run a package command with `--help` for package-specific usage.
|
|
15
|
+
|
|
16
|
+
```zsh
|
|
17
|
+
# Install the Ankhorage CLI
|
|
18
|
+
bun add --global @ankhorage/ankh
|
|
19
|
+
|
|
20
|
+
# Show usage information for rules-design
|
|
21
|
+
ankh rules-design --help
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Evaluate Design Evidence
|
|
25
|
+
|
|
26
|
+
Register the Design provider with the generic Rules evaluator.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { createRuleRegistry, evaluateRules } from '@ankhorage/rules';
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Generated documentation
|
|
33
|
+
|
|
34
|
+
- [Interactive documentation app](././paradox/index.html)
|
|
35
|
+
- [Public API reference](././paradox/exports.md)
|
|
36
|
+
- [Component registry](././paradox/components.md)
|
|
37
|
+
- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
|
|
38
|
+
- [Module relationships](././paradox/diagrams/module-relationships.mmd)
|
|
39
|
+
- [Export graph](././paradox/diagrams/export-graph.mmd)
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
import { designRuleComposites } from './designRuleComposites';
|
|
2
|
+
import { designRuleSemantics } from './designRuleSemantics';
|
|
3
|
+
/*** Declares the Wave 0 catalog without registering executable rules. */
|
|
4
|
+
const atomicDesignRuleCatalog = [
|
|
5
|
+
group('Color & Tokens', ['color'], ['color'], [
|
|
6
|
+
['design.color.syntax-valid', 'Colors are syntactically valid.'],
|
|
7
|
+
['design.color.token-exists', 'Referenced color tokens exist.'],
|
|
8
|
+
['design.color.token-allowed', 'Only permitted palette tokens are used.'],
|
|
9
|
+
[
|
|
10
|
+
'design.color.semantic-role',
|
|
11
|
+
'Foreground, background, and border roles are semantically correct.',
|
|
12
|
+
],
|
|
13
|
+
['design.color.literal-drift', 'Unnecessary literal values do not drift from tokens.'],
|
|
14
|
+
['design.color.ramp-consistency', 'Defined color ramps remain consistent.'],
|
|
15
|
+
['design.color.alpha-composition', 'Transparency is evaluated against the actual backdrop.'],
|
|
16
|
+
['design.color.surface-role', 'Surface colors consistently express their role.'],
|
|
17
|
+
['design.color.hover-state', 'Hover color variation follows policy.'],
|
|
18
|
+
['design.color.active-state', 'Active color variation follows policy.'],
|
|
19
|
+
['design.color.disabled-state', 'Disabled colors communicate disabled state.'],
|
|
20
|
+
['design.color.theme-coverage', 'Light and dark theme tokens are available.'],
|
|
21
|
+
[
|
|
22
|
+
'design.color.usage-distribution',
|
|
23
|
+
'Configured base, complementary, and accent shares are evidenced from visible areas.',
|
|
24
|
+
'heuristic',
|
|
25
|
+
],
|
|
26
|
+
]),
|
|
27
|
+
group('Contrast & Visual Hierarchy', ['text', 'page'], ['color', 'accessibility'], [
|
|
28
|
+
['design.contrast.text-ratio', 'Effective text contrast meets the selected standard.'],
|
|
29
|
+
[
|
|
30
|
+
'design.contrast.nontext-ratio',
|
|
31
|
+
'Relevant non-text UI and graphics have sufficient contrast.',
|
|
32
|
+
],
|
|
33
|
+
['design.contrast.focus-visible', 'Focus indicators are visible.'],
|
|
34
|
+
['design.contrast.surface-separation', 'Relevant surfaces remain distinguishable.'],
|
|
35
|
+
['design.contrast.state-distinction', 'Interactive states are visibly distinct.'],
|
|
36
|
+
['design.contrast.link-distinction', 'Links are sufficiently distinguishable.'],
|
|
37
|
+
['design.contrast.text-background-resolved', 'The effective text background is resolved.'],
|
|
38
|
+
[
|
|
39
|
+
'design.contrast.cta-prominence',
|
|
40
|
+
'Primary calls to action are visually prominent.',
|
|
41
|
+
'heuristic',
|
|
42
|
+
],
|
|
43
|
+
[
|
|
44
|
+
'design.contrast.visual-hierarchy',
|
|
45
|
+
'Visual emphasis forms an understandable hierarchy.',
|
|
46
|
+
'heuristic',
|
|
47
|
+
],
|
|
48
|
+
]),
|
|
49
|
+
group('Typography & Heading', ['text', 'heading'], ['typography', 'heading'], [
|
|
50
|
+
['design.typography.font-family', 'Font families are permitted.'],
|
|
51
|
+
['design.typography.scale', 'Typography follows a consistent scale.'],
|
|
52
|
+
['design.typography.weight', 'Typography weights are defined.'],
|
|
53
|
+
['design.typography.line-height', 'Line heights are consistent.'],
|
|
54
|
+
['design.typography.letter-spacing', 'Letter spacing is consistent.'],
|
|
55
|
+
['design.typography.paragraph-measure', 'Paragraph line length is useful.', 'heuristic'],
|
|
56
|
+
['design.typography.body-minimum', 'Body text meets the configured minimum.'],
|
|
57
|
+
['design.typography.responsive-scale', 'Typography scales consistently across breakpoints.'],
|
|
58
|
+
['design.heading.h1-presence', 'Each page has an expected H1.'],
|
|
59
|
+
['design.heading.h1-count', 'H1 count obeys its configured constraint.'],
|
|
60
|
+
['design.heading.level-order', 'Heading levels form a logical hierarchy.'],
|
|
61
|
+
[
|
|
62
|
+
'design.heading.semantic-style',
|
|
63
|
+
'HTML heading level and visual role are correctly separated.',
|
|
64
|
+
],
|
|
65
|
+
['design.heading.spacing-before', 'Heading spacing before is contextually consistent.'],
|
|
66
|
+
['design.heading.spacing-after', 'Heading spacing after is contextually consistent.'],
|
|
67
|
+
['design.heading.text-clipping', 'Headings are not clipped.'],
|
|
68
|
+
]),
|
|
69
|
+
group('Spacing & Proximity', ['card', 'form', 'heading'], ['spacing', 'alignment'], [
|
|
70
|
+
['design.spacing.token-allowed', 'Spacing uses permitted tokens.'],
|
|
71
|
+
['design.spacing.vertical-rhythm', 'Vertical rhythm is consistent.'],
|
|
72
|
+
['design.spacing.section-gap', 'Section gaps follow the system.'],
|
|
73
|
+
['design.spacing.container-padding', 'Containers have appropriate padding.'],
|
|
74
|
+
['design.proximity.related-grouping', 'Related elements are near each other.', 'heuristic'],
|
|
75
|
+
[
|
|
76
|
+
'design.proximity.unrelated-separation',
|
|
77
|
+
'Unrelated groups are visually separated.',
|
|
78
|
+
'heuristic',
|
|
79
|
+
],
|
|
80
|
+
['design.proximity.label-control', 'Labels and controls are spatially connected.'],
|
|
81
|
+
['design.proximity.heading-content', 'Headings group with their following content.'],
|
|
82
|
+
['design.proximity.card-internals', 'Card internals are consistently grouped.'],
|
|
83
|
+
['design.spacing.double-application', 'Cumulative duplicate spacing is detected.'],
|
|
84
|
+
['design.spacing.unexpected-collapse', 'Unexpected margin collapsing and gaps are detected.'],
|
|
85
|
+
]),
|
|
86
|
+
group('Alignment & Layout', ['page', 'component'], ['alignment', 'responsive'], [
|
|
87
|
+
['design.alignment.shared-edges', 'Shared visual edges align.'],
|
|
88
|
+
['design.alignment.grid-tracks', 'Elements follow grid tracks.'],
|
|
89
|
+
['design.alignment.baselines', 'Typical baselines align.'],
|
|
90
|
+
['design.alignment.text', 'Text alignment is intentional and consistent.'],
|
|
91
|
+
['design.alignment.flex-items', 'Flex alignment follows its defined pattern.'],
|
|
92
|
+
['design.alignment.component-axes', 'Equivalent components share axes.'],
|
|
93
|
+
['design.layout.container-width', 'Container widths obey configured bounds.'],
|
|
94
|
+
['design.layout.grid-gap', 'Grid gaps follow the system.'],
|
|
95
|
+
['design.layout.horizontal-overflow', 'Unexpected horizontal overflow is absent.'],
|
|
96
|
+
['design.layout.vertical-clipping', 'Unexpected vertical clipping is absent.'],
|
|
97
|
+
['design.layout.unintended-overlap', 'Unexpected overlap is absent.'],
|
|
98
|
+
[
|
|
99
|
+
'design.layout.unnecessary-wrapper',
|
|
100
|
+
'Avoidable structural wrappers are identified.',
|
|
101
|
+
'heuristic',
|
|
102
|
+
],
|
|
103
|
+
['design.layout.visual-balance', 'Visual weight is balanced.', 'heuristic'],
|
|
104
|
+
]),
|
|
105
|
+
group('Repetition & Components', ['button', 'card', 'form'], ['typography', 'alignment'], [
|
|
106
|
+
['design.repetition.button-variants', 'Button variants are consistent.'],
|
|
107
|
+
['design.repetition.card-variants', 'Card variants and templates are consistent.'],
|
|
108
|
+
['design.repetition.heading-variants', 'Heading roles are consistent.'],
|
|
109
|
+
['design.repetition.form-control-style', 'Form controls are consistently styled.'],
|
|
110
|
+
['design.repetition.link-treatment', 'Link treatment is consistent.'],
|
|
111
|
+
['design.repetition.navigation-treatment', 'Navigation treatment is consistent.'],
|
|
112
|
+
['design.repetition.icons', 'Icon size and style are consistent.'],
|
|
113
|
+
['design.repetition.border-radius', 'Border radii follow tokens and variants.'],
|
|
114
|
+
['design.repetition.border-weight', 'Border weights are consistent.'],
|
|
115
|
+
['design.repetition.elevation', 'Shadows and elevation are consistent.'],
|
|
116
|
+
['design.repetition.motion', 'Motion patterns are consistent.'],
|
|
117
|
+
['design.repetition.local-overrides', 'Unwanted local overrides are identified.'],
|
|
118
|
+
['design.repetition.template-drift', 'Instances do not drift from their template.'],
|
|
119
|
+
]),
|
|
120
|
+
group('Responsive', ['page', 'text', 'image'], ['responsive'], [
|
|
121
|
+
['design.responsive.breakpoint-coverage', 'Required viewport ranges were examined.'],
|
|
122
|
+
['design.responsive.reflow', 'Layouts reflow meaningfully.'],
|
|
123
|
+
['design.responsive.horizontal-overflow', 'Critical widths do not overflow horizontally.'],
|
|
124
|
+
['design.responsive.text-wrap', 'Text wraps meaningfully.'],
|
|
125
|
+
['design.responsive.touch-target', 'Controls meet configured touch target size.'],
|
|
126
|
+
['design.responsive.order', 'Important reading order is preserved.'],
|
|
127
|
+
['design.responsive.image-crop', 'Important image content is not lost by crop.', 'heuristic'],
|
|
128
|
+
['design.responsive.fixed-dimensions', 'Problematic fixed dimensions are identified.'],
|
|
129
|
+
['design.responsive.zoom-reflow', 'Layouts reflow under zoom.'],
|
|
130
|
+
['design.responsive.orientation', 'Layouts are robust across orientation.'],
|
|
131
|
+
]),
|
|
132
|
+
group('Accessibility & Semantics', ['button', 'form', 'image', 'page'], ['accessibility'], [
|
|
133
|
+
['design.a11y.accessible-name', 'Interactive controls have accessible names.'],
|
|
134
|
+
['design.a11y.form-label', 'Form fields have correct labels.'],
|
|
135
|
+
['design.a11y.error-association', 'Errors are semantically associated.'],
|
|
136
|
+
['design.a11y.keyboard-reachability', 'Interactive elements are keyboard reachable.'],
|
|
137
|
+
['design.a11y.focus-order', 'Focus order is meaningful.'],
|
|
138
|
+
['design.a11y.color-only', 'Information is not conveyed by color alone.'],
|
|
139
|
+
['design.a11y.reduced-motion', 'Reduced-motion settings are respected.'],
|
|
140
|
+
['design.a11y.landmarks', 'Landmarks are meaningful.'],
|
|
141
|
+
['design.a11y.main-landmark', 'Main content is identified.'],
|
|
142
|
+
['design.a11y.list-semantics', 'Lists have correct semantics.'],
|
|
143
|
+
['design.a11y.button-link-semantics', 'Buttons and links have correct semantics.'],
|
|
144
|
+
['design.a11y.status-feedback', 'Status changes are announced.'],
|
|
145
|
+
[
|
|
146
|
+
'design.a11y.text-alternatives',
|
|
147
|
+
'Text alternatives are meaningful and decorative media is identified.',
|
|
148
|
+
],
|
|
149
|
+
]),
|
|
150
|
+
group('Images & Media', ['image', 'media'], ['media'], [
|
|
151
|
+
['design.media.aspect-ratio', 'Aspect ratios are consistent.'],
|
|
152
|
+
['design.media.intrinsic-size', 'Intrinsic image dimensions are known.'],
|
|
153
|
+
['design.media.resolution-fit', 'Resolution suits rendered size.'],
|
|
154
|
+
['design.media.object-fit', 'Object fitting follows configuration.'],
|
|
155
|
+
[
|
|
156
|
+
'design.media.focal-point',
|
|
157
|
+
'Important subjects are not unintentionally cropped.',
|
|
158
|
+
'heuristic',
|
|
159
|
+
],
|
|
160
|
+
['design.media.responsive-sources', 'Appropriate responsive sources exist.'],
|
|
161
|
+
['design.media.overlay-legibility', 'Text on imagery remains legible.'],
|
|
162
|
+
['design.media.icon-sizing', 'Icons scale consistently.'],
|
|
163
|
+
[
|
|
164
|
+
'design.media.decorative-vs-content',
|
|
165
|
+
'Decorative and content images are classified correctly.',
|
|
166
|
+
],
|
|
167
|
+
]),
|
|
168
|
+
].flat();
|
|
169
|
+
/*** Exposes the complete planned atomic and composite design rule catalog. */
|
|
170
|
+
export const designRuleCatalog = [
|
|
171
|
+
...atomicDesignRuleCatalog,
|
|
172
|
+
...designRuleComposites(atomicDesignRuleCatalog),
|
|
173
|
+
];
|
|
174
|
+
/*** Creates complete catalog records from one semantically cohesive rule group. */
|
|
175
|
+
function group(groupName, subjects, topics, rules) {
|
|
176
|
+
return rules.map(([id, description, assessmentKind = 'objective']) => {
|
|
177
|
+
const semantics = designRuleSemantics(id, description);
|
|
178
|
+
return {
|
|
179
|
+
assessmentKind,
|
|
180
|
+
dependencies: [],
|
|
181
|
+
description,
|
|
182
|
+
evidenceSchemaVersion: '1',
|
|
183
|
+
expectedEvidence: semantics.evidence,
|
|
184
|
+
facets: {
|
|
185
|
+
principles: principlesFor(id),
|
|
186
|
+
scopes: semantics.scopes,
|
|
187
|
+
subjects,
|
|
188
|
+
topics,
|
|
189
|
+
},
|
|
190
|
+
group: groupName,
|
|
191
|
+
id,
|
|
192
|
+
name: id.slice('design.'.length),
|
|
193
|
+
requiredCapabilities: semantics.requiredCapabilities,
|
|
194
|
+
semanticsVersion: '1',
|
|
195
|
+
severity: assessmentKind === 'objective' ? 'required' : 'advisory',
|
|
196
|
+
status: 'planned',
|
|
197
|
+
};
|
|
198
|
+
});
|
|
199
|
+
}
|
|
200
|
+
/*** Maps catalog IDs to controlled C.R.A.P. facet principles. */
|
|
201
|
+
function principlesFor(id) {
|
|
202
|
+
if (id.includes('contrast') || id.includes('color'))
|
|
203
|
+
return ['contrast'];
|
|
204
|
+
if (id.includes('repetition'))
|
|
205
|
+
return ['repetition'];
|
|
206
|
+
if (id.includes('alignment') || id.includes('layout'))
|
|
207
|
+
return ['alignment'];
|
|
208
|
+
if (id.includes('spacing') || id.includes('proximity'))
|
|
209
|
+
return ['proximity'];
|
|
210
|
+
return [];
|
|
211
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { DesignRuleCatalogEntry } from '../../types/designRuleCatalog';
|
|
2
|
+
/*** Creates the five planned C.R.A.P. composite nodes from their atomic child rules. */
|
|
3
|
+
export declare function designRuleComposites(atomicEntries: readonly DesignRuleCatalogEntry[]): readonly DesignRuleCatalogEntry[];
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/*** Creates the five planned C.R.A.P. composite nodes from their atomic child rules. */
|
|
2
|
+
export function designRuleComposites(atomicEntries) {
|
|
3
|
+
const children = (prefixes) => atomicEntries
|
|
4
|
+
.filter((entry) => prefixes.some((prefix) => entry.id.startsWith(prefix)))
|
|
5
|
+
.map((entry) => entry.id);
|
|
6
|
+
return [
|
|
7
|
+
composite('design.crap.contrast', 'C.R.A.P. contrast composition.', children(['design.color.', 'design.contrast.'])),
|
|
8
|
+
composite('design.crap.repetition', 'C.R.A.P. repetition composition.', children(['design.repetition.', 'design.typography.'])),
|
|
9
|
+
composite('design.crap.alignment', 'C.R.A.P. alignment composition.', children(['design.alignment.', 'design.layout.', 'design.responsive.'])),
|
|
10
|
+
composite('design.crap.proximity', 'C.R.A.P. proximity composition.', children(['design.spacing.', 'design.proximity.'])),
|
|
11
|
+
composite('design.crap', 'C.R.A.P. composition from exactly four composite results.', [
|
|
12
|
+
'design.crap.contrast',
|
|
13
|
+
'design.crap.repetition',
|
|
14
|
+
'design.crap.alignment',
|
|
15
|
+
'design.crap.proximity',
|
|
16
|
+
]),
|
|
17
|
+
];
|
|
18
|
+
}
|
|
19
|
+
/*** Creates the evidence contract for a planned advisory composite. */
|
|
20
|
+
function composite(id, description, dependencies) {
|
|
21
|
+
return {
|
|
22
|
+
assessmentKind: 'heuristic',
|
|
23
|
+
dependencies,
|
|
24
|
+
description,
|
|
25
|
+
evidenceSchemaVersion: '1',
|
|
26
|
+
expectedEvidence: {
|
|
27
|
+
assertion: 'Every referenced child rule result is available for composition.',
|
|
28
|
+
observations: ['child rule identifier', 'child result status', 'child evidence reference'],
|
|
29
|
+
source: 'rule-result-set',
|
|
30
|
+
},
|
|
31
|
+
facets: {
|
|
32
|
+
principles: id === 'design.crap'
|
|
33
|
+
? ['contrast', 'repetition', 'alignment', 'proximity']
|
|
34
|
+
: [id.split('.').at(-1) ?? ''],
|
|
35
|
+
scopes: ['project'],
|
|
36
|
+
subjects: ['page'],
|
|
37
|
+
topics: ['design-quality'],
|
|
38
|
+
},
|
|
39
|
+
group: 'C.R.A.P.',
|
|
40
|
+
id,
|
|
41
|
+
name: id.slice('design.'.length),
|
|
42
|
+
requiredCapabilities: ['rule.result-set'],
|
|
43
|
+
semanticsVersion: '1',
|
|
44
|
+
severity: 'advisory',
|
|
45
|
+
status: 'planned',
|
|
46
|
+
};
|
|
47
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { designRuleCatalog } from './designRuleCatalog';
|
|
2
|
+
const objectiveRuleIds = designRuleCatalog
|
|
3
|
+
.filter((entry) => entry.assessmentKind === 'objective' && !entry.id.startsWith('design.crap'))
|
|
4
|
+
.map((entry) => entry.id);
|
|
5
|
+
/*** Declares selectable profiles without adding another executable or composite rule. */
|
|
6
|
+
export const designRuleProfiles = [
|
|
7
|
+
{
|
|
8
|
+
description: 'Objective baseline design checks.',
|
|
9
|
+
id: 'design.quality.base',
|
|
10
|
+
rootRuleIds: objectiveRuleIds,
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
description: 'Advisory accessibility-oriented checks.',
|
|
14
|
+
id: 'design.wcag.advisory',
|
|
15
|
+
rootRuleIds: designRuleCatalog
|
|
16
|
+
.filter((entry) => entry.id.startsWith('design.contrast.') || entry.id.startsWith('design.a11y.'))
|
|
17
|
+
.map((entry) => entry.id),
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
description: 'C.R.A.P. composition profile.',
|
|
21
|
+
id: 'design.crap',
|
|
22
|
+
rootRuleIds: ['design.crap'],
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
description: 'Advisory 60-30-10 visible color-area distribution profile.',
|
|
26
|
+
id: 'design.60-30-10',
|
|
27
|
+
rootRuleIds: ['design.color.usage-distribution'],
|
|
28
|
+
},
|
|
29
|
+
];
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/*** Declares the released MIT provider surface without exposing unclassified planned rules. */
|
|
2
|
+
export const designRuleProviderManifest = {
|
|
3
|
+
packageName: '@ankhorage/rules-design',
|
|
4
|
+
providerId: 'ankhorage.rules-design',
|
|
5
|
+
publishedRuleIds: [],
|
|
6
|
+
schemaVersion: '1',
|
|
7
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { DesignRuleEvidence, DesignRuleScope } from '../../types/designRuleCatalog';
|
|
2
|
+
interface RuleSemantics {
|
|
3
|
+
readonly evidence: DesignRuleEvidence;
|
|
4
|
+
readonly requiredCapabilities: readonly string[];
|
|
5
|
+
readonly scopes: readonly DesignRuleScope[];
|
|
6
|
+
}
|
|
7
|
+
/*** Resolves each planned rule into the evidence contract a provider must satisfy. */
|
|
8
|
+
export declare function designRuleSemantics(id: string, assertion: string): RuleSemantics;
|
|
9
|
+
export {};
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
const evidenceDefinitions = [
|
|
2
|
+
{
|
|
3
|
+
capabilities: ['source.style-tokens'],
|
|
4
|
+
observations: ['declared token name', 'token value', 'reference location'],
|
|
5
|
+
source: 'declared-design-tokens',
|
|
6
|
+
terms: ['token', 'ramp', 'literal-drift'],
|
|
7
|
+
},
|
|
8
|
+
{
|
|
9
|
+
capabilities: ['rendered.area-analysis'],
|
|
10
|
+
observations: ['viewport image', 'classified visible areas', 'area ratio'],
|
|
11
|
+
source: 'rendered-area-analysis',
|
|
12
|
+
terms: ['usage-distribution', 'visual-balance'],
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
capabilities: ['viewport.layout', 'viewport.matrix'],
|
|
16
|
+
observations: ['viewport dimensions', 'element bounds', 'scroll dimensions'],
|
|
17
|
+
source: 'viewport-layout-snapshots',
|
|
18
|
+
terms: ['responsive', 'zoom', 'orientation', 'reflow', 'text-wrap', 'horizontal-overflow'],
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
capabilities: ['dom.accessibility-tree'],
|
|
22
|
+
observations: ['semantic role', 'accessible name', 'document order'],
|
|
23
|
+
source: 'accessibility-tree',
|
|
24
|
+
terms: [
|
|
25
|
+
'heading',
|
|
26
|
+
'landmark',
|
|
27
|
+
'semantics',
|
|
28
|
+
'accessible-name',
|
|
29
|
+
'form-label',
|
|
30
|
+
'error-association',
|
|
31
|
+
'focus-order',
|
|
32
|
+
'keyboard',
|
|
33
|
+
'status-feedback',
|
|
34
|
+
'text-alternatives',
|
|
35
|
+
'color-only',
|
|
36
|
+
],
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
capabilities: ['media.metadata'],
|
|
40
|
+
observations: ['intrinsic media metadata', 'rendered bounds', 'resolved object-fit'],
|
|
41
|
+
source: 'media-and-render-metadata',
|
|
42
|
+
terms: ['image', 'media', 'icon'],
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
capabilities: ['ui.component-tree'],
|
|
46
|
+
observations: ['component identity', 'variant properties', 'instance style values'],
|
|
47
|
+
source: 'component-instance-tree',
|
|
48
|
+
terms: ['repetition', 'template-drift', 'local-overrides'],
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
capabilities: ['dom.layout'],
|
|
52
|
+
observations: ['element bounds', 'computed spacing', 'alignment axis'],
|
|
53
|
+
source: 'resolved-layout-geometry',
|
|
54
|
+
terms: ['spacing', 'proximity', 'alignment', 'layout'],
|
|
55
|
+
},
|
|
56
|
+
];
|
|
57
|
+
const scopeDefinitions = [
|
|
58
|
+
[
|
|
59
|
+
[
|
|
60
|
+
'token-exists',
|
|
61
|
+
'token-allowed',
|
|
62
|
+
'ramp-consistency',
|
|
63
|
+
'theme-coverage',
|
|
64
|
+
'template-drift',
|
|
65
|
+
'local-overrides',
|
|
66
|
+
],
|
|
67
|
+
'project',
|
|
68
|
+
],
|
|
69
|
+
[
|
|
70
|
+
[
|
|
71
|
+
'usage-distribution',
|
|
72
|
+
'visual-hierarchy',
|
|
73
|
+
'visual-balance',
|
|
74
|
+
'breakpoint-coverage',
|
|
75
|
+
'reflow',
|
|
76
|
+
'zoom',
|
|
77
|
+
'orientation',
|
|
78
|
+
'heading.h1',
|
|
79
|
+
'heading.level-order',
|
|
80
|
+
'landmark',
|
|
81
|
+
'focus-order',
|
|
82
|
+
'reading-order',
|
|
83
|
+
'status-feedback',
|
|
84
|
+
],
|
|
85
|
+
'page',
|
|
86
|
+
],
|
|
87
|
+
[['spacing', 'proximity', 'alignment', 'layout', 'repetition'], 'component'],
|
|
88
|
+
];
|
|
89
|
+
/*** Resolves each planned rule into the evidence contract a provider must satisfy. */
|
|
90
|
+
export function designRuleSemantics(id, assertion) {
|
|
91
|
+
const definition = evidenceDefinitions.find((candidate) => includesAny(id, candidate.terms));
|
|
92
|
+
const evidence = definition ?? defaultEvidenceDefinition;
|
|
93
|
+
const scope = scopeDefinitions.find(([terms]) => includesAny(id, terms))?.[1] ?? 'element';
|
|
94
|
+
return {
|
|
95
|
+
evidence: { assertion, observations: evidence.observations, source: evidence.source },
|
|
96
|
+
requiredCapabilities: additionalCapabilities(id, evidence.capabilities),
|
|
97
|
+
scopes: [scope],
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
const defaultEvidenceDefinition = {
|
|
101
|
+
capabilities: ['dom.computed-style'],
|
|
102
|
+
observations: ['computed style property', 'resolved foreground', 'resolved background'],
|
|
103
|
+
source: 'resolved-rendered-style',
|
|
104
|
+
terms: [],
|
|
105
|
+
};
|
|
106
|
+
/*** Adds only the capabilities required by interaction, text, or motion semantics. */
|
|
107
|
+
function additionalCapabilities(id, capabilities) {
|
|
108
|
+
return [
|
|
109
|
+
...capabilities,
|
|
110
|
+
...(id.includes('ratio') ? ['dom.text-content'] : []),
|
|
111
|
+
...(includesAny(id, ['hover', 'active', 'disabled', 'focus-visible'])
|
|
112
|
+
? ['browser.interaction-state']
|
|
113
|
+
: []),
|
|
114
|
+
...(id.includes('reduced-motion') ? ['browser.media-preference'] : []),
|
|
115
|
+
];
|
|
116
|
+
}
|
|
117
|
+
/*** Returns whether a rule identifier contains one of a definition's semantic terms. */
|
|
118
|
+
function includesAny(value, terms) {
|
|
119
|
+
return terms.some((term) => value.includes(term));
|
|
120
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { DesignRuleCatalogEntry, DesignRuleCatalogFilter } from '../../types/designRuleCatalog';
|
|
2
|
+
/*** Selects planned catalog entries matching every supplied controlled facet. */
|
|
3
|
+
export declare function filterDesignRuleCatalog(entries: readonly DesignRuleCatalogEntry[], filter: DesignRuleCatalogFilter): readonly DesignRuleCatalogEntry[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/*** Selects planned catalog entries matching every supplied controlled facet. */
|
|
2
|
+
export function filterDesignRuleCatalog(entries, filter) {
|
|
3
|
+
return entries.filter((entry) => matches(entry.facets.topics, filter.topics) &&
|
|
4
|
+
matches(entry.facets.subjects, filter.subjects) &&
|
|
5
|
+
matches(entry.facets.scopes, filter.scopes) &&
|
|
6
|
+
matches(entry.facets.principles, filter.principles));
|
|
7
|
+
}
|
|
8
|
+
/*** Returns whether an entry facet contains every requested value. */
|
|
9
|
+
function matches(values, requested) {
|
|
10
|
+
return requested === undefined || requested.every((value) => values.includes(value));
|
|
11
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { designRuleCatalog } from '../designRuleCatalog';
|
|
2
|
+
import { designRuleProfiles } from '../designRuleProfiles';
|
|
3
|
+
/*** Provides the internal Wave 0 planning manifest without claiming a provider implementation. */
|
|
4
|
+
export const designRulePlanningManifest = {
|
|
5
|
+
profiles: designRuleProfiles,
|
|
6
|
+
rules: designRuleCatalog,
|
|
7
|
+
schemaVersion: '1',
|
|
8
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/*** Exposes the reusable Design provider through the generic Rules RuleSet contract. */
|
|
2
|
+
export const designRuleProvider = {
|
|
3
|
+
id: 'ankhorage.rules-design',
|
|
4
|
+
packageName: '@ankhorage/rules-design',
|
|
5
|
+
ruleSet: {
|
|
6
|
+
id: 'ankhorage.rules-design',
|
|
7
|
+
rules: [],
|
|
8
|
+
},
|
|
9
|
+
};
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { designRuleCatalog } from './features/catalog/designRuleCatalog';
|
|
2
|
+
export { designRuleProfiles } from './features/catalog/designRuleProfiles';
|
|
3
|
+
export { designRuleProviderManifest } from './features/catalog/designRuleProviderManifest';
|
|
4
|
+
export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
|
|
5
|
+
export { designRuleProvider } from './features/provider/designRuleProvider';
|
|
6
|
+
export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
|
|
7
|
+
export type { DesignContext, DesignEvidence, DesignRuleProvider } from './types/designRuleProvider';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { designRuleCatalog } from './features/catalog/designRuleCatalog';
|
|
2
|
+
export { designRuleProfiles } from './features/catalog/designRuleProfiles';
|
|
3
|
+
export { designRuleProviderManifest } from './features/catalog/designRuleProviderManifest';
|
|
4
|
+
export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
|
|
5
|
+
export { designRuleProvider } from './features/provider/designRuleProvider';
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
export type DesignAssessmentKind = 'heuristic' | 'objective';
|
|
2
|
+
export type DesignRuleStatus = 'planned';
|
|
3
|
+
export type DesignRuleScope = 'component' | 'element' | 'page' | 'project' | 'site';
|
|
4
|
+
export interface DesignRuleEvidence {
|
|
5
|
+
readonly assertion: string;
|
|
6
|
+
readonly observations: readonly string[];
|
|
7
|
+
readonly source: string;
|
|
8
|
+
}
|
|
9
|
+
export interface DesignRuleCatalogEntry {
|
|
10
|
+
readonly assessmentKind: DesignAssessmentKind;
|
|
11
|
+
readonly dependencies: readonly string[];
|
|
12
|
+
readonly description: string;
|
|
13
|
+
readonly evidenceSchemaVersion: '1';
|
|
14
|
+
readonly expectedEvidence: DesignRuleEvidence;
|
|
15
|
+
readonly facets: {
|
|
16
|
+
readonly principles: readonly string[];
|
|
17
|
+
readonly scopes: readonly DesignRuleScope[];
|
|
18
|
+
readonly subjects: readonly string[];
|
|
19
|
+
readonly topics: readonly string[];
|
|
20
|
+
};
|
|
21
|
+
readonly group: string;
|
|
22
|
+
readonly id: string;
|
|
23
|
+
readonly name: string;
|
|
24
|
+
readonly requiredCapabilities: readonly string[];
|
|
25
|
+
readonly semanticsVersion: '1';
|
|
26
|
+
readonly severity: 'advisory' | 'required';
|
|
27
|
+
readonly status: DesignRuleStatus;
|
|
28
|
+
}
|
|
29
|
+
export type DesignRuleCatalogFilter = Partial<Pick<DesignRuleCatalogEntry['facets'], 'principles' | 'scopes' | 'subjects' | 'topics'>>;
|
|
30
|
+
export interface DesignRuleProfile {
|
|
31
|
+
readonly description: string;
|
|
32
|
+
readonly id: string;
|
|
33
|
+
readonly rootRuleIds: readonly string[];
|
|
34
|
+
}
|
|
35
|
+
export interface DesignRulePlanningManifest {
|
|
36
|
+
readonly profiles: readonly DesignRuleProfile[];
|
|
37
|
+
readonly rules: readonly DesignRuleCatalogEntry[];
|
|
38
|
+
readonly schemaVersion: '1';
|
|
39
|
+
}
|
|
40
|
+
export interface DesignRuleProviderManifest {
|
|
41
|
+
readonly packageName: '@ankhorage/rules-design';
|
|
42
|
+
readonly providerId: 'ankhorage.rules-design';
|
|
43
|
+
readonly publishedRuleIds: readonly string[];
|
|
44
|
+
readonly schemaVersion: '1';
|
|
45
|
+
}
|
|
File without changes
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { RuleSet } from '@ankhorage/rules';
|
|
2
|
+
/*** One provider-neutral design observation supplied by a Design context. */
|
|
3
|
+
export interface DesignEvidence {
|
|
4
|
+
readonly id: string;
|
|
5
|
+
readonly kind: string;
|
|
6
|
+
}
|
|
7
|
+
/*** The minimal context shared by Design rules without prescribing its source. */
|
|
8
|
+
export interface DesignContext {
|
|
9
|
+
readonly evidence: readonly DesignEvidence[];
|
|
10
|
+
}
|
|
11
|
+
/*** The public identity and generic Rules contribution for the Design provider. */
|
|
12
|
+
export interface DesignRuleProvider {
|
|
13
|
+
readonly id: 'ankhorage.rules-design';
|
|
14
|
+
readonly packageName: '@ankhorage/rules-design';
|
|
15
|
+
readonly ruleSet: RuleSet<DesignContext>;
|
|
16
|
+
}
|
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,63 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/rules-design",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Declarative catalog for reusable design rules.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"homepage": "https://github.com/ankhorage/rules-design#readme",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/ankhorage/rules-design/issues"
|
|
9
|
+
},
|
|
10
|
+
"keywords": [
|
|
11
|
+
"ankhorage",
|
|
12
|
+
"design",
|
|
13
|
+
"rules"
|
|
14
|
+
],
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
18
|
+
"type": "module",
|
|
19
|
+
"sideEffects": false,
|
|
20
|
+
"files": [
|
|
21
|
+
"dist",
|
|
22
|
+
"CHANGELOG.md",
|
|
23
|
+
"LICENSE"
|
|
24
|
+
],
|
|
25
|
+
"main": "./dist/index.js",
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"exports": {
|
|
28
|
+
".": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"import": "./dist/index.js"
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"repository": {
|
|
34
|
+
"type": "git",
|
|
35
|
+
"url": "git+https://github.com/ankhorage/rules-design.git"
|
|
36
|
+
},
|
|
37
|
+
"packageManager": "bun@1.4.2",
|
|
38
|
+
"scripts": {
|
|
39
|
+
"build": "rm -rf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && bun x tsc -p tsconfig.build.json",
|
|
40
|
+
"check-types": "bun x tsc --noEmit -p tsconfig.json",
|
|
41
|
+
"typecheck": "bun run check-types",
|
|
42
|
+
"test": "bun test",
|
|
43
|
+
"lint": "ankhorage-eslint . --max-warnings=0",
|
|
44
|
+
"knip:check": "ankhorage-knip",
|
|
45
|
+
"format": "ankhorage-prettier --write .",
|
|
46
|
+
"format:check": "ankhorage-prettier --check .",
|
|
47
|
+
"lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
|
|
48
|
+
"changeset": "ankhorage-changeset",
|
|
49
|
+
"changeset:status": "ankhorage-changeset status --since=origin/main",
|
|
50
|
+
"version-packages": "ankhorage-changeset version",
|
|
51
|
+
"docs": "paradox"
|
|
52
|
+
},
|
|
53
|
+
"devDependencies": {
|
|
54
|
+
"@types/bun": "^1.4.2",
|
|
55
|
+
"@types/node": "^26.6.6",
|
|
56
|
+
"typescript": "~6.0.3",
|
|
57
|
+
"@ankhorage/devtools": "^2.3.47",
|
|
58
|
+
"@ankhorage/paradox": "^0.3.6"
|
|
59
|
+
},
|
|
60
|
+
"dependencies": {
|
|
61
|
+
"@ankhorage/rules": "^0.3.0"
|
|
62
|
+
}
|
|
63
|
+
}
|