@atom63/cli 0.1.0-beta.1 → 0.1.0-beta.3
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/README.md +8 -0
- package/generated/agent-index.json +5381 -136
- package/package.json +1 -1
- package/src/agents-md.mjs +26 -5
- package/src/commands.mjs +16 -1
- package/src/core.mjs +163 -4
- package/src/format.mjs +48 -0
- package/src/rules.mjs +25 -6
package/package.json
CHANGED
package/src/agents-md.mjs
CHANGED
|
@@ -16,7 +16,8 @@ const cliQueries = [
|
|
|
16
16
|
'',
|
|
17
17
|
'- `atom63 build <idea>`: a kit for what you are building: the closest page templates and blocks, the components they use, the foundation and the rules. For a phone screen it leads with `AppView layout="phone"` and a snippet to start from.',
|
|
18
18
|
'- `atom63 template <id>` and `atom63 copy <id> <dir>`: read a page or block template, then copy it and the blocks it uses into your project to adapt.',
|
|
19
|
-
'- `atom63 search <words>`: find a component, template, docs page, story example or
|
|
19
|
+
'- `atom63 search <words>`: find a component, template, docs page, story example, token or public API name (a SwiftUI type or the export of a package entry point).',
|
|
20
|
+
'- `atom63 api <name>`: a SwiftUI type (`AtomWidgetCard`) or a JavaScript export (`MediaLightbox`, `KeyIdea`) with its import line and docs, and for an MDX block its purpose, an example and its props; an entry point (`@atom63/ui-react/media`, `Atom63UI`) with everything it exports.',
|
|
20
21
|
'- `atom63 component <slug>`: the import line, contract (axes, defaults, slots, states, web and iOS), related components and examples.',
|
|
21
22
|
'- `atom63 example <slug> [story]`: a known-good usage sample to start from.',
|
|
22
23
|
'- `atom63 token <name or words>`: a token with its values per theme and mode, Figma path and Swift name.',
|
|
@@ -34,6 +35,10 @@ const docsQueries = [
|
|
|
34
35
|
'- Start from a component that exists before writing markup of your own.',
|
|
35
36
|
]
|
|
36
37
|
|
|
38
|
+
/** `a`, `a and b`, `a, b and c`. */
|
|
39
|
+
const list = items =>
|
|
40
|
+
items.length > 1 ? `${items.slice(0, -1).join(', ')} and ${items.at(-1)}` : items.join('')
|
|
41
|
+
|
|
37
42
|
/**
|
|
38
43
|
* `variant: 'cli'` points agents at the `atom63` CLI and MCP server; `'docs'`
|
|
39
44
|
* points them at the published docs, for projects that cannot run the CLI yet.
|
|
@@ -43,11 +48,12 @@ export function agentsSection({ variant = 'cli' } = {}) {
|
|
|
43
48
|
(rule, position) =>
|
|
44
49
|
`${position + 1}. ${rule.rule} ${rule.why}${
|
|
45
50
|
rule.check
|
|
46
|
-
? ` In the design system repo, \`check:craft\` enforces it as ${
|
|
47
|
-
.flat()
|
|
48
|
-
|
|
49
|
-
.join(' and ')}.`
|
|
51
|
+
? ` In the design system repo, \`check:craft\` enforces it as ${list(
|
|
52
|
+
[rule.check].flat().map(check => `\`${check}\``)
|
|
53
|
+
)}.`
|
|
50
54
|
: ''
|
|
55
|
+
}${rule.checkedBy ? ` ${rule.checkedBy}` : ''}${
|
|
56
|
+
rule.unchecked ? ` Not checked mechanically: ${rule.unchecked}` : ''
|
|
51
57
|
}`
|
|
52
58
|
)
|
|
53
59
|
return [
|
|
@@ -61,6 +67,21 @@ export function agentsSection({ variant = 'cli' } = {}) {
|
|
|
61
67
|
].join('\n')
|
|
62
68
|
}
|
|
63
69
|
|
|
70
|
+
/**
|
|
71
|
+
* Rules that do not say how they are enforced: each needs `check` or
|
|
72
|
+
* `checkedBy`, or else `unchecked` with the reason no check can enforce it.
|
|
73
|
+
* @returns {string[]} one message per rule that breaks this
|
|
74
|
+
*/
|
|
75
|
+
export function ruleEnforcementErrors(table = rules) {
|
|
76
|
+
return table.flatMap(rule => {
|
|
77
|
+
const checked = Boolean(rule.check || rule.checkedBy)
|
|
78
|
+
if (checked && rule.unchecked) return [`${rule.id}: names a check and says it is unchecked`]
|
|
79
|
+
if (!checked && !rule.unchecked?.trim())
|
|
80
|
+
return [`${rule.id}: names no check (\`check\`, \`checkedBy\`) and no reason (\`unchecked\`)`]
|
|
81
|
+
return []
|
|
82
|
+
})
|
|
83
|
+
}
|
|
84
|
+
|
|
64
85
|
/** The section wrapped in markers, ready to paste into or sync with an AGENTS.md. */
|
|
65
86
|
export function agentsBlock(options) {
|
|
66
87
|
return `${markers.start}\n\n${agentsSection(options)}\n\n${markers.end}`
|
package/src/commands.mjs
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* input and returns an envelope, or throws an AtomError.
|
|
9
9
|
*/
|
|
10
10
|
import { agentsBlock } from './agents-md.mjs'
|
|
11
|
-
import { component, docsPage, example, rules, search, searchKinds, token } from './core.mjs'
|
|
11
|
+
import { api, component, docsPage, example, rules, search, searchKinds, token } from './core.mjs'
|
|
12
12
|
import { build, copy, template, templateKinds } from './templates.mjs'
|
|
13
13
|
|
|
14
14
|
export const commands = [
|
|
@@ -91,6 +91,20 @@ export const commands = [
|
|
|
91
91
|
returns: ['token.detail', 'token.results'],
|
|
92
92
|
run: (index, { query }) => token(index, query),
|
|
93
93
|
},
|
|
94
|
+
{
|
|
95
|
+
name: 'api',
|
|
96
|
+
summary:
|
|
97
|
+
'A public API name or an entry point: a SwiftUI type with its declaration, doc comment and members, or a JavaScript export with its import line and docs page (for an MDX block, its purpose, an example and its props); an entry point (e.g. @atom63/ui-react/media, @atom63/mdx/blocks, Atom63UI) with everything it exports.',
|
|
98
|
+
args: [
|
|
99
|
+
{
|
|
100
|
+
name: 'name',
|
|
101
|
+
description: 'e.g. AtomWidgetCard, MediaLightbox, KeyIdea or @atom63/ui-react/media.',
|
|
102
|
+
},
|
|
103
|
+
],
|
|
104
|
+
flags: [],
|
|
105
|
+
returns: ['api.detail', 'api.entry'],
|
|
106
|
+
run: (index, { name }) => api(index, name),
|
|
107
|
+
},
|
|
94
108
|
{
|
|
95
109
|
name: 'docs',
|
|
96
110
|
summary: 'A docs page as Markdown.',
|
|
@@ -149,6 +163,7 @@ export const errorCodes = [
|
|
|
149
163
|
'token.not_found',
|
|
150
164
|
'docs.not_found',
|
|
151
165
|
'template.not_found',
|
|
166
|
+
'api.not_found',
|
|
152
167
|
]
|
|
153
168
|
|
|
154
169
|
/** The self-describing manifest an agent reads once to learn the interface. */
|
package/src/core.mjs
CHANGED
|
@@ -123,7 +123,7 @@ function synonymBoost(query, slug) {
|
|
|
123
123
|
let best = 0
|
|
124
124
|
for (const term of words(query)) {
|
|
125
125
|
const rank = (synonyms[term] ?? []).indexOf(slug)
|
|
126
|
-
if (rank !== -1) best = Math.max(best,
|
|
126
|
+
if (rank !== -1) best = Math.max(best, 40 - rank * 8)
|
|
127
127
|
}
|
|
128
128
|
return best
|
|
129
129
|
}
|
|
@@ -169,11 +169,42 @@ function synonymTokens(query) {
|
|
|
169
169
|
|
|
170
170
|
/* ── Commands ────────────────────────────────────────────────────────────── */
|
|
171
171
|
|
|
172
|
-
export const searchKinds = ['component', 'template', 'token', 'doc', 'example']
|
|
172
|
+
export const searchKinds = ['component', 'template', 'token', 'doc', 'example', 'api']
|
|
173
|
+
|
|
174
|
+
const firstSentence = text => /^.*?\.(?=\s|$)/.exec(text)?.[0] ?? text
|
|
175
|
+
|
|
176
|
+
/** The last segment of an entry point: `@atom63/ui-react/media/lightbox` → `lightbox`. */
|
|
177
|
+
const entryTail = module => module.split('/').at(-1)
|
|
173
178
|
|
|
174
179
|
/**
|
|
175
|
-
*
|
|
176
|
-
*
|
|
180
|
+
* Every public API name an agent can look up: the Swift types of Atom63UI and
|
|
181
|
+
* the values each published JavaScript entry point exports.
|
|
182
|
+
*/
|
|
183
|
+
function apiSymbols(index) {
|
|
184
|
+
const covered = new Set(index.components.flatMap(component => component.exports.values))
|
|
185
|
+
return [
|
|
186
|
+
...index.api.ios.types.map(type => ({
|
|
187
|
+
name: type.name,
|
|
188
|
+
summary: firstSentence(type.summary) || `${type.declaration} (${index.api.ios.module})`,
|
|
189
|
+
// Swift types do not compete with the web component of the same name.
|
|
190
|
+
inSearch: true,
|
|
191
|
+
})),
|
|
192
|
+
...index.api.web.flatMap(entry =>
|
|
193
|
+
entry.values.map(name => ({
|
|
194
|
+
name,
|
|
195
|
+
summary: `import { ${name} } from '${entry.module}'`,
|
|
196
|
+
// A catalog component's own exports are found through the component.
|
|
197
|
+
inSearch: !covered.has(name),
|
|
198
|
+
}))
|
|
199
|
+
),
|
|
200
|
+
]
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* One ranked list across components, templates, tokens, docs pages, story
|
|
205
|
+
* examples and public API names (Swift types and entry point exports).
|
|
206
|
+
* An API name joins on a name match only, and below components and docs
|
|
207
|
+
* unless it matches exactly or kind is `api`.
|
|
177
208
|
* Tokens only join when the query looks like one (`--…`), kind is `token`, a
|
|
178
209
|
* topic names them, or a query term names them through a synonym ("gradient"),
|
|
179
210
|
* so a thousand variables cannot bury the components.
|
|
@@ -277,6 +308,51 @@ export function search(index, query, { kind, limit = 10 } = {}) {
|
|
|
277
308
|
}
|
|
278
309
|
}
|
|
279
310
|
|
|
311
|
+
if (wants('api')) {
|
|
312
|
+
const entries = [
|
|
313
|
+
{
|
|
314
|
+
module: index.api.ios.module,
|
|
315
|
+
names: [index.api.ios.module, 'ios', 'swiftui', 'swift'],
|
|
316
|
+
summary: `the SwiftUI package: ${index.api.ios.types.length} public types`,
|
|
317
|
+
},
|
|
318
|
+
...index.api.web.map(entry => ({
|
|
319
|
+
module: entry.module,
|
|
320
|
+
names: [entry.module, entryTail(entry.module)],
|
|
321
|
+
summary: `entry point: ${entry.values.length} exports, docs ${entry.docs}`,
|
|
322
|
+
})),
|
|
323
|
+
]
|
|
324
|
+
for (const entry of entries) {
|
|
325
|
+
const total = score(query, terms, { names: entry.names })
|
|
326
|
+
if (total >= 50) {
|
|
327
|
+
results.push({
|
|
328
|
+
kind: 'api',
|
|
329
|
+
id: entry.module,
|
|
330
|
+
label: entry.module,
|
|
331
|
+
summary: entry.summary,
|
|
332
|
+
score: total * 0.9,
|
|
333
|
+
next: `atom63 api ${entry.module}`,
|
|
334
|
+
})
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
const listed = new Set()
|
|
338
|
+
for (const symbol of apiSymbols(index)) {
|
|
339
|
+
if (!symbol.inSearch || listed.has(symbol.name)) continue
|
|
340
|
+
const value = score(query, terms, { names: [symbol.name] })
|
|
341
|
+
// Outside `--kind api`, a name must start with the query: hundreds of
|
|
342
|
+
// contract constants contain short words such as "ios" or "tab".
|
|
343
|
+
if (value < (kind === 'api' ? 50 : 70)) continue
|
|
344
|
+
listed.add(symbol.name)
|
|
345
|
+
results.push({
|
|
346
|
+
kind: 'api',
|
|
347
|
+
id: symbol.name,
|
|
348
|
+
label: symbol.name,
|
|
349
|
+
summary: symbol.summary,
|
|
350
|
+
score: value >= 100 || kind === 'api' ? value : value * 0.4,
|
|
351
|
+
next: `atom63 api ${symbol.name}`,
|
|
352
|
+
})
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
|
|
280
356
|
const allTokens = kind === 'token' || (!kind && query.trim().startsWith('--'))
|
|
281
357
|
if (wants('token')) {
|
|
282
358
|
for (const token of index.tokens) {
|
|
@@ -480,6 +556,89 @@ export function token(index, query) {
|
|
|
480
556
|
return { type: 'token.results', data }
|
|
481
557
|
}
|
|
482
558
|
|
|
559
|
+
/**
|
|
560
|
+
* A public API name or an entry point. A Swift type comes back with its
|
|
561
|
+
* declaration, doc comment, members and the component it renders; a
|
|
562
|
+
* JavaScript export with the entry points that export it, their import lines
|
|
563
|
+
* and docs pages. An entry point (`@atom63/ui-react/media`, `Atom63UI`) comes
|
|
564
|
+
* back with everything it exports.
|
|
565
|
+
*/
|
|
566
|
+
export function api(index, name) {
|
|
567
|
+
if (!name?.trim()) throw new AtomError('api.not_found', 'Pass an API name or an entry point.')
|
|
568
|
+
const wanted = name.trim()
|
|
569
|
+
const { ios, web } = index.api
|
|
570
|
+
if (wanted === ios.module || /^(ios|swiftui)$/i.test(wanted)) {
|
|
571
|
+
return {
|
|
572
|
+
type: 'api.entry',
|
|
573
|
+
data: {
|
|
574
|
+
module: ios.module,
|
|
575
|
+
platform: 'ios',
|
|
576
|
+
docs: ios.docs,
|
|
577
|
+
import: `import ${ios.module}`,
|
|
578
|
+
symbols: ios.types.map(type => ({
|
|
579
|
+
name: type.name,
|
|
580
|
+
kind: type.kind,
|
|
581
|
+
summary: type.summary,
|
|
582
|
+
})),
|
|
583
|
+
},
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
const entry = web.find(candidate => candidate.module === wanted)
|
|
587
|
+
if (entry) {
|
|
588
|
+
return {
|
|
589
|
+
type: 'api.entry',
|
|
590
|
+
data: {
|
|
591
|
+
module: entry.module,
|
|
592
|
+
platform: 'web',
|
|
593
|
+
docs: entry.docs,
|
|
594
|
+
import: `import { … } from '${entry.module}'`,
|
|
595
|
+
symbols: entry.values.map(value => ({ name: value, kind: 'value', summary: '' })),
|
|
596
|
+
},
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
const same = candidate => candidate.toLowerCase() === wanted.toLowerCase()
|
|
601
|
+
const exact = candidate => candidate === wanted
|
|
602
|
+
const pick = list => (list.some(exact) ? list.filter(exact) : list.filter(same))
|
|
603
|
+
const swiftName = pick(ios.types.map(type => type.name))[0]
|
|
604
|
+
const webName = pick([...new Set(web.flatMap(candidate => candidate.values))])[0]
|
|
605
|
+
if (!swiftName && !webName) {
|
|
606
|
+
throw new AtomError(
|
|
607
|
+
'api.not_found',
|
|
608
|
+
`No public API "${wanted}".`,
|
|
609
|
+
closest(wanted, [ios.module, ...apiSymbols(index).map(symbol => symbol.name)])
|
|
610
|
+
)
|
|
611
|
+
}
|
|
612
|
+
const componentOf = new Map(
|
|
613
|
+
index.components.flatMap(component =>
|
|
614
|
+
component.exports.values.map(value => [value, component.slug])
|
|
615
|
+
)
|
|
616
|
+
)
|
|
617
|
+
const swift = ios.types.find(type => type.name === swiftName)
|
|
618
|
+
return {
|
|
619
|
+
type: 'api.detail',
|
|
620
|
+
data: {
|
|
621
|
+
name: swiftName ?? webName,
|
|
622
|
+
ios: swift ? { ...swift, module: ios.module, docs: ios.docs } : null,
|
|
623
|
+
web: webName
|
|
624
|
+
? web
|
|
625
|
+
.filter(candidate => candidate.values.includes(webName))
|
|
626
|
+
.map(candidate => ({
|
|
627
|
+
module: candidate.module,
|
|
628
|
+
import: `import { ${webName} } from '${candidate.module}'`,
|
|
629
|
+
docs: candidate.docs,
|
|
630
|
+
// What the docs page says about this export: purpose, example and props.
|
|
631
|
+
reference: candidate.sections?.[webName] ?? null,
|
|
632
|
+
// Only ui-react's catalog components; @atom63/mdx has its own `Tabs`.
|
|
633
|
+
component: candidate.module.startsWith('@atom63/ui-react')
|
|
634
|
+
? (componentOf.get(webName) ?? null)
|
|
635
|
+
: null,
|
|
636
|
+
}))
|
|
637
|
+
: [],
|
|
638
|
+
},
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
|
|
483
642
|
/** A docs page's Markdown by slug. */
|
|
484
643
|
export function docsPage(index, slug) {
|
|
485
644
|
const page = index.docs.find(doc => doc.slug === slug)
|
package/src/format.mjs
CHANGED
|
@@ -203,7 +203,55 @@ function buildPlaybook(data) {
|
|
|
203
203
|
].join('\n')
|
|
204
204
|
}
|
|
205
205
|
|
|
206
|
+
function apiDetail({ name, ios, web }) {
|
|
207
|
+
const lines = [`# ${name}`]
|
|
208
|
+
if (ios) {
|
|
209
|
+
lines.push(
|
|
210
|
+
'',
|
|
211
|
+
`SwiftUI (${ios.module}): ${ios.declaration}`,
|
|
212
|
+
`Source: ${ios.source}`,
|
|
213
|
+
...(ios.summary ? ['', ios.summary] : []),
|
|
214
|
+
...(ios.component
|
|
215
|
+
? ['', `Renders the ${ios.component} contract: atom63 component ${ios.component}`]
|
|
216
|
+
: []),
|
|
217
|
+
...(ios.members.length > 0
|
|
218
|
+
? ['', 'Members:', ...ios.members.map(member => ` ${member.declaration}`)]
|
|
219
|
+
: []),
|
|
220
|
+
'',
|
|
221
|
+
`Guide: atom63 docs ${ios.docs}`
|
|
222
|
+
)
|
|
223
|
+
}
|
|
224
|
+
for (const entry of web) {
|
|
225
|
+
lines.push(
|
|
226
|
+
'',
|
|
227
|
+
entry.import,
|
|
228
|
+
entry.component
|
|
229
|
+
? `Component: atom63 component ${entry.component}`
|
|
230
|
+
: `Docs: atom63 docs ${entry.docs}`
|
|
231
|
+
)
|
|
232
|
+
}
|
|
233
|
+
// Entries that re-export a name share its docs section; print it once.
|
|
234
|
+
const reference = web.find(entry => entry.reference)?.reference
|
|
235
|
+
if (reference) lines.push('', reference)
|
|
236
|
+
return lines.join('\n')
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
function apiEntry({ module, import: importLine, docs, symbols }) {
|
|
240
|
+
return [
|
|
241
|
+
`# ${module}`,
|
|
242
|
+
'',
|
|
243
|
+
importLine,
|
|
244
|
+
`Docs: atom63 docs ${docs}`,
|
|
245
|
+
'',
|
|
246
|
+
...symbols.map(symbol => (symbol.summary ? `${symbol.name} — ${symbol.summary}` : symbol.name)),
|
|
247
|
+
'',
|
|
248
|
+
'Read one with: atom63 api <name>',
|
|
249
|
+
].join('\n')
|
|
250
|
+
}
|
|
251
|
+
|
|
206
252
|
const renderers = {
|
|
253
|
+
'api.detail': apiDetail,
|
|
254
|
+
'api.entry': apiEntry,
|
|
207
255
|
'search.results': searchResults,
|
|
208
256
|
'token.results': searchResults,
|
|
209
257
|
'component.detail': componentDetail,
|
package/src/rules.mjs
CHANGED
|
@@ -1,50 +1,66 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The rules an agent follows when it builds UI with Atom63. `atom63 rules`
|
|
3
3
|
* prints them, and the AGENTS.md snippet is generated from the same table.
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* Every rule says how it is enforced, or why it is not:
|
|
5
|
+
* - `check`: the `check:craft` rule (or rules) that enforces it;
|
|
6
|
+
* - `checkedBy`: another check that enforces it, as a sentence;
|
|
7
|
+
* - `unchecked`: why no check can enforce it mechanically.
|
|
8
|
+
* `check:agents-md` fails on a rule with none of them.
|
|
6
9
|
*/
|
|
7
10
|
export const rules = [
|
|
8
11
|
{
|
|
9
12
|
id: 'query-first',
|
|
10
13
|
rule: 'Query the design system before writing UI: start a screen from the closest page template, then search for components, read their contracts, and start from story examples.',
|
|
11
14
|
why: 'The templates, catalog, contracts and examples are the reviewed answers; guessing reinvents them with drift.',
|
|
15
|
+
unchecked: 'it is a way of working, not a property of the code it produces.',
|
|
12
16
|
},
|
|
13
17
|
{
|
|
14
18
|
id: 'compose-before-create',
|
|
15
19
|
rule: 'Compose existing components before writing new ones. Add a component to the system with `pnpm ds:new`, not by copying another.',
|
|
16
20
|
why: 'A new component must be wired into contracts, recipes, docs and tests; the scaffold does that, a copy does not.',
|
|
21
|
+
unchecked:
|
|
22
|
+
'whether a new component was needed is a judgement; the vibe case studies report the share of elements taken from the system as a diagnostic.',
|
|
17
23
|
},
|
|
18
24
|
{
|
|
19
25
|
id: 'contract-values',
|
|
20
26
|
rule: "Pass only the axis values a component's contract lists (sizes, variants, orientations), and rely on its defaults.",
|
|
21
27
|
why: 'Recipes, the SwiftUI renderer and the Figma variables are built for exactly those values.',
|
|
28
|
+
unchecked:
|
|
29
|
+
"each component's TypeScript props accept only the contract's values, so a type check rejects any other literal and no lint is needed.",
|
|
22
30
|
},
|
|
23
31
|
{
|
|
24
32
|
id: 'tokens-only',
|
|
25
|
-
rule: 'Take every color, space, radius, shadow and duration from `--a63-*` tokens, and look a name up with `atom63 token` before using it. No literal colors and no Tailwind palette utilities.',
|
|
33
|
+
rule: 'Take every color, space, radius, shadow and duration from `--a63-*` tokens, and look a name up with `atom63 token` before using it. No literal colors and no Tailwind palette utilities. Paint text with `--a63-text-*` tokens and backgrounds with fill tokens, not the other way round.',
|
|
26
34
|
why: 'Tokens follow the theme, brand, mode and density; literals break all four, and a token name that does not exist resolves to nothing.',
|
|
27
|
-
check: ['raw-color', 'unknown-token'],
|
|
35
|
+
check: ['raw-color', 'unknown-token', 'token-role'],
|
|
28
36
|
},
|
|
29
37
|
{
|
|
30
38
|
id: 'accent-sparingly',
|
|
31
39
|
rule: 'Use the accent for one or two cues per view; the main action may be neutral. Give a view at most one `variant="primary"` Button. Selection is neutral by default; set `tone="accent"` on a selection, Slider or Progress only when it is one of those cues. Where the product draws its main action or its links in its brand colour, keep `variant="primary"` and `variant="link"`: sparing means one or two cues, not none.',
|
|
32
|
-
why: 'An accent on every control points at nothing. Button `default` is a high-emphasis neutral solid; `primary` is for a main action in the brand colour.
|
|
40
|
+
why: 'An accent on every control points at nothing. Button `default` is a high-emphasis neutral solid; `primary` is for a main action in the brand colour. Taking the accent off a product whose main action is brand-coloured loses the cue the product relies on.',
|
|
41
|
+
checkedBy:
|
|
42
|
+
'The vibe measures warn at more than one primary Button per file, and a case study with that warning is invalid.',
|
|
33
43
|
},
|
|
34
44
|
{
|
|
35
45
|
id: 'quiet-secondary-actions',
|
|
36
46
|
rule: 'Draw secondary actions in toolbars, list rows and card headers as `variant="ghost"` Buttons with `tone="muted"`, icon-only at `icon-sm` or `icon-xs` in dense rows. Keep the main action at full contrast.',
|
|
37
47
|
why: 'Muted ghost actions rest in the secondary text colour, with no box, and go to full contrast on hover, focus and press, so a row of actions stays calm and still answers the pointer.',
|
|
48
|
+
checkedBy:
|
|
49
|
+
'The vibe measures warn at a `variant="ghost"` Button with no `tone`; whether an action is secondary stays a judgement.',
|
|
38
50
|
},
|
|
39
51
|
{
|
|
40
52
|
id: 'one-boundary',
|
|
41
53
|
rule: "One boundary per element: border, fill or shadow, not two. Don't nest outlined containers.",
|
|
42
54
|
why: 'Each extra edge is another line to read past. Card `filled` and `elevated` and Button `raised` give a fill or a shadow without the border.',
|
|
55
|
+
unchecked:
|
|
56
|
+
'borders, fills and shadows add up across components and their parents at render time, so the source does not show the stack; it is left to review.',
|
|
43
57
|
},
|
|
44
58
|
{
|
|
45
59
|
id: 'on-media-colors',
|
|
46
60
|
rule: 'Controls drawn over photos or video use the `--a63-on-media-*` and `--a63-media-*` tokens.',
|
|
47
61
|
why: 'Theme colors are meaningless on an unknown picture; these hold contrast on any image.',
|
|
62
|
+
unchecked:
|
|
63
|
+
'whether a control sits over a picture is a layout fact the source does not show; it is left to review.',
|
|
48
64
|
},
|
|
49
65
|
{
|
|
50
66
|
id: 'content-colors',
|
|
@@ -80,10 +96,13 @@ export const rules = [
|
|
|
80
96
|
id: 'as-child-spreads-props',
|
|
81
97
|
rule: 'A component you pass with `asChild` (or as `render`) must spread the props it receives onto the element it renders and forward its ref.',
|
|
82
98
|
why: 'The part merges its class, data attributes and ref into that element; a wrapper that drops them renders unstyled.',
|
|
99
|
+
unchecked:
|
|
100
|
+
'the component passed is your own code, and whether it spreads the props it receives shows only when it renders.',
|
|
83
101
|
},
|
|
84
102
|
{
|
|
85
103
|
id: 'accessible-by-default',
|
|
86
104
|
rule: 'Keep the native semantics components render (buttons, links, labels, dialogs) and give every icon-only control an accessible name.',
|
|
87
|
-
why: '
|
|
105
|
+
why: 'Assistive technology reads the roles, states and names those elements carry.',
|
|
106
|
+
checkedBy: 'Every story runs axe in CI; code that removes semantics fails it.',
|
|
88
107
|
},
|
|
89
108
|
]
|