ai-developer-skill-os 9.1.2 → 9.3.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/.agents/AGENTS.md +139 -42
- package/.agents/DEV_PROFILE.md +95 -0
- package/.agents/registry/capability-graph.yml +171 -334
- package/.agents/registry/graph.json +37 -19
- package/.agents/registry/index.yaml +59 -13
- package/.agents/registry/skills-index.yml +204 -447
- package/.agents/rules/coding.md +23 -0
- package/.agents/rules/global.md +44 -30
- package/.agents/skills/_template/SKILL.md +2 -377
- package/.agents/skills/qk-access-policy/SKILL.md +98 -473
- package/.agents/skills/qk-agent-observability/SKILL.md +3 -439
- package/.agents/skills/qk-ai-builder/SKILL.md +132 -565
- package/.agents/skills/qk-api-consumer/SKILL.md +256 -0
- package/.agents/skills/qk-api-consumer/capability.yaml +21 -0
- package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +29 -0
- package/.agents/skills/qk-api-lifecycle/SKILL.md +133 -456
- package/.agents/skills/qk-bug-resolution/SKILL.md +128 -561
- package/.agents/skills/qk-code-review/SKILL.md +142 -420
- package/.agents/skills/qk-context-loader/SKILL.md +99 -471
- package/.agents/skills/qk-data-engineer/SKILL.md +119 -340
- package/.agents/skills/qk-data-lifecycle/SKILL.md +89 -488
- package/.agents/skills/qk-db-optimizer/SKILL.md +102 -488
- package/.agents/skills/qk-design-system-engineering/SKILL.md +76 -461
- package/.agents/skills/qk-devops-platform/SKILL.md +77 -463
- package/.agents/skills/qk-docs/SKILL.md +88 -494
- package/.agents/skills/qk-engineering-standard/SKILL.md +4 -588
- package/.agents/skills/qk-fe-api-integration/SKILL.md +343 -343
- package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +29 -29
- package/.agents/skills/qk-feature-delivery/SKILL.md +137 -445
- package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-frontend-architecture/SKILL.md +5 -479
- package/.agents/skills/qk-help/evals/scorecard.yaml +13 -13
- package/.agents/skills/qk-orchestrator/SKILL.md +63 -502
- package/.agents/skills/qk-orchestrator/references/routing-table.md +10 -14
- package/.agents/skills/qk-product-specification/SKILL.md +70 -479
- package/.agents/skills/qk-production-release/SKILL.md +80 -537
- package/.agents/skills/qk-project-audit/SKILL.md +174 -0
- package/.agents/skills/qk-project-bootstrap/SKILL.md +243 -471
- package/.agents/skills/qk-project-health/SKILL.md +97 -496
- package/.agents/skills/qk-project-memory/SKILL.md +76 -21
- package/.agents/skills/qk-refactor/SKILL.md +167 -384
- package/.agents/skills/qk-security-audit/SKILL.md +141 -463
- package/.agents/skills/qk-security-audit/capability.yaml +1 -2
- package/.agents/skills/qk-system-evolution/SKILL.md +343 -343
- package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +26 -26
- package/.agents/skills/qk-test-engineering/SKILL.md +119 -509
- package/.agents/skills/qk-ui-audit/SKILL.md +73 -537
- package/.agents/skills/qk-ui-builder/SKILL.md +521 -482
- package/.agents/skills/qk-ui-system-builder/SKILL.md +68 -514
- package/.agents/skills/qk-upgrade/SKILL.md +301 -0
- package/.agents/skills/qk-upgrade/capability.yaml +24 -0
- package/.agents/skills/qk-upgrade/evals/scorecard.yaml +26 -0
- package/.agents/skills/qk-validation-gate/SKILL.md +4 -603
- package/.agents/skills/qk-web-quality-gate/SKILL.md +85 -463
- package/.agents/workflows/bug-resolution.yml +6 -6
- package/.agents/workflows/context-discovery.yml +94 -0
- package/.agents/workflows/feature-delivery.yml +8 -4
- package/.agents/workflows/refactor.yml +6 -3
- package/.agents/workflows/shared/quality-gate.yml +94 -0
- package/.agents/workflows/skin-governance.yml +115 -0
- package/README.md +152 -67
- package/package.json +2 -2
- package/tooling/build-registry.js +30 -8
|
@@ -1,482 +1,521 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
1
|
+
---
|
|
2
|
+
# ── Identity ───────────────────────────────────────────────
|
|
3
|
+
name: qk-ui-builder
|
|
4
|
+
version: 9.2.0
|
|
5
|
+
status: stable
|
|
6
|
+
description: "Xây dựng, sửa, audit, và hoàn thiện UI component từ Figma/ảnh/mô tả layout — responsive, chuẩn token, đầy đủ hover/active/loading states. Dùng skill này khi user nhắc đến: build ui, làm giao diện, css, layout, component, figma, design ui, tạo trang, code giao diện — kể cả khi chỉ gửi ảnh thiết kế hoặc nói 'làm cho tôi cái navbar/card này'."
|
|
7
|
+
platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
|
|
8
|
+
|
|
9
|
+
# ── V9: Classification ─────────────────────────────────────
|
|
10
|
+
type: capability
|
|
11
|
+
|
|
12
|
+
intent:
|
|
13
|
+
- ui-development
|
|
14
|
+
- frontend-design
|
|
15
|
+
|
|
16
|
+
complexity:
|
|
17
|
+
level: high
|
|
18
|
+
criteria:
|
|
19
|
+
files_affected: "1-10"
|
|
20
|
+
has_behavior_change: true
|
|
21
|
+
has_external_dependency: true
|
|
22
|
+
has_breaking_change: false
|
|
23
|
+
|
|
24
|
+
triggers:
|
|
25
|
+
- "build ui"
|
|
26
|
+
- "làm giao diện"
|
|
27
|
+
- "css"
|
|
28
|
+
- "layout"
|
|
29
|
+
- "component"
|
|
30
|
+
- "figma"
|
|
31
|
+
- "design ui"
|
|
32
|
+
- "tạo trang"
|
|
33
|
+
- "code giao diện"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# ── V8: References ─────────────────────────────────────────
|
|
37
|
+
workflow: feature-delivery
|
|
38
|
+
|
|
39
|
+
rules:
|
|
40
|
+
- global
|
|
41
|
+
- coding
|
|
42
|
+
|
|
43
|
+
tools:
|
|
44
|
+
- filesystem
|
|
45
|
+
- terminal
|
|
46
|
+
|
|
47
|
+
related_skills:
|
|
48
|
+
- qk-ui-system-builder
|
|
49
|
+
|
|
50
|
+
knowledge_scope:
|
|
51
|
+
owns:
|
|
52
|
+
- ui-components
|
|
53
|
+
- styling execution
|
|
54
|
+
- component implementation
|
|
55
|
+
does_not_own:
|
|
56
|
+
- choose product visual direction
|
|
57
|
+
- define brand identity
|
|
58
|
+
- create design system rules
|
|
59
|
+
conflicts_with: []
|
|
60
|
+
references:
|
|
61
|
+
- design-system
|
|
62
|
+
|
|
63
|
+
knowledge_dependencies:
|
|
64
|
+
- design-intelligence
|
|
65
|
+
- component-patterns
|
|
66
|
+
|
|
67
|
+
# ── V8: Verification ───────────────────────────────────────
|
|
68
|
+
verification:
|
|
69
|
+
required: true
|
|
70
|
+
strategy: feature
|
|
71
|
+
|
|
72
|
+
selection:
|
|
73
|
+
priority: medium
|
|
74
|
+
confidence_threshold: 0.80
|
|
75
|
+
|
|
76
|
+
examples: []
|
|
77
|
+
learnings: []
|
|
78
|
+
|
|
79
|
+
# ── V7 Runtime ─────────────────────────────────────────────
|
|
80
|
+
execution_mode: deterministic
|
|
81
|
+
cost: high
|
|
82
|
+
latency: slow
|
|
83
|
+
risk: low
|
|
84
|
+
side_effects: edit_files
|
|
85
|
+
produces: [code, report]
|
|
86
|
+
consumes: [design-md, design-asset, source-code, api-schema]
|
|
87
|
+
|
|
88
|
+
token_budget:
|
|
89
|
+
max_files_read: 5
|
|
90
|
+
max_lines_per_read: 150
|
|
91
|
+
max_shell_commands: 0
|
|
92
|
+
stop_early: true
|
|
93
|
+
|
|
94
|
+
exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
# qk-ui-builder — UI Builder & Auditor
|
|
98
|
+
|
|
99
|
+
> **Language rule:** Code, identifiers, file names English. Explanations, summaries Vietnamese.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Verbs
|
|
104
|
+
|
|
105
|
+
| Verb | Trigger | Behavior |
|
|
106
|
+
|------|---------|----------|
|
|
107
|
+
| *(default)* | `./qk-ui-builder` | Build or edit UI from design reference |
|
|
108
|
+
| `--audit` | `./qk-ui-builder --audit` | Score UI against anti-slop checklist, no edits |
|
|
109
|
+
| `--redesign` | `./qk-ui-builder --redesign` | Rebuild structure, keep copy/IA/brand |
|
|
110
|
+
| `--study` | `./qk-ui-builder --study <screenshot\|URL>` | Extract design DNA `design.md` |
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Preconditions
|
|
115
|
+
- [ ] `DESIGN.md` exists with color tokens, spacing scale, typography
|
|
116
|
+
- [ ] For default/edit: design reference or target component specified
|
|
117
|
+
- [ ] For `--audit`: target UI file(s) specified
|
|
118
|
+
- [ ] For `--redesign`: target page + brand/copy context provided
|
|
119
|
+
- [ ] For `--study`: screenshot file or public URL provided
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
On missing precondition:
|
|
123
|
+
EXIT: BLOCKED
|
|
124
|
+
Message: "[Missing item]. See Escalation Rules."
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Scope
|
|
130
|
+
|
|
131
|
+
### Default verb
|
|
132
|
+
- ✅ Build new UI from Figma/ảnh/design reference
|
|
133
|
+
- ✅ Sửa text, thêm nội dung, map API key vào component
|
|
134
|
+
- ✅ Fix UI bug: padding, màu, hiển thị, responsive
|
|
135
|
+
- ✅ Generate strict UI từ DESIGN.md tokens
|
|
136
|
+
|
|
137
|
+
### `--audit`
|
|
138
|
+
- ✅ Score UI against anti-slop checklist (58 gates)
|
|
139
|
+
- ✅ Detect generic AI aesthetics, hardcoded values
|
|
140
|
+
- ✅ Verify ARIA, contrast, responsive states
|
|
141
|
+
- ⚠️ Note: This uses the 58-gate binary slop test (in-build self-check), which is distinct from the point-based scoring in the standalone `qk-ui-audit` skill.
|
|
142
|
+
|
|
143
|
+
### `--redesign`
|
|
144
|
+
- ✅ Thay đổi cấu trúc page, giữ nội dung/IA/brand
|
|
145
|
+
- ✅ Pick new macrostructure + theme fingerprint
|
|
146
|
+
|
|
147
|
+
### `--study`
|
|
148
|
+
- ✅ Extract design DNA từ ảnh/Figma/URL
|
|
149
|
+
- ✅ Emit portable `design.md` for handoff
|
|
150
|
+
|
|
151
|
+
## Non-Goals
|
|
152
|
+
- ❌ Invent design tokens not in DESIGN.md
|
|
153
|
+
- ❌ Use hardcoded hex colors, px sizes not from token system
|
|
154
|
+
- ❌ Copy generic Tailwind/Bootstrap templates
|
|
155
|
+
- ❌ Skip loading/error/empty states
|
|
156
|
+
- ❌ Clone paid templates or violate design copyright
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Priority Order
|
|
161
|
+
|
|
162
|
+
| Priority | Task | Skip Threshold |
|
|
163
|
+
|----------|------|----------------|
|
|
164
|
+
| P1 | HTML structure + semantic markup | Never |
|
|
165
|
+
| P2 | DESIGN.md token application (colors, spacing, typography) | Never |
|
|
166
|
+
| P3 | Interactive states (hover, focus, active) | Budget < 30% |
|
|
167
|
+
| P4 | Responsive breakpoints (mobile) | Budget < 50% |
|
|
168
|
+
| P5 | Loading / error / empty states | Budget < 60% |
|
|
169
|
+
| P6 | Animation / micro-interactions | Budget < 70% |
|
|
170
|
+
| P7 | ARIA roles + keyboard navigation | Budget < 80% |
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Workflow
|
|
175
|
+
|
|
176
|
+
### Phase 1 — Route by Verb
|
|
177
|
+
|
|
178
|
+
**Decision:**
|
|
179
|
+
```
|
|
180
|
+
IF --audit
|
|
181
|
+
Load slop-test gates go to Audit phase
|
|
182
|
+
|
|
183
|
+
ELSE IF --redesign
|
|
184
|
+
Load macrostructure index pick new fingerprint go to Build phase
|
|
185
|
+
|
|
186
|
+
ELSE IF --study
|
|
187
|
+
Load study protocol extract DNA emit design.md EXIT: SUCCESS
|
|
188
|
+
|
|
189
|
+
ELSE (default: build/edit)
|
|
190
|
+
go to Build phase
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
### Phase 2 — Load Design Context (default/edit/redesign only)
|
|
196
|
+
|
|
197
|
+
**Load Discipline (MANDATORY):**
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
EAGER (load every build):
|
|
201
|
+
- typography.md
|
|
202
|
+
- color.md
|
|
203
|
+
- layout-and-space.md
|
|
204
|
+
- copy.md
|
|
205
|
+
- anti-patterns.md
|
|
206
|
+
|
|
207
|
+
INDEX-THEN-PICK (load index, choose ONE):
|
|
208
|
+
- macrostructures.md pick ONE load only that file
|
|
209
|
+
|
|
210
|
+
CONDITIONAL (load only if needed):
|
|
211
|
+
- themes/[name].md only if project has locked theme
|
|
212
|
+
- motion.md only if animation requested
|
|
213
|
+
- interaction-and-states.md only if complex interactions
|
|
214
|
+
- responsive.md only if mobile breakpoints needed
|
|
215
|
+
- component-cookbook.md only if building known archetype
|
|
216
|
+
|
|
217
|
+
LOAD-AT-END (post-emit only):
|
|
218
|
+
- slop-test.md run AFTER build completes
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
**Steps:**
|
|
222
|
+
1. Read `DESIGN.md` extract tokens: colors (HSL), spacing, fonts, radius, shadows
|
|
223
|
+
2. Load eager references (typography, color, layout, copy, anti-patterns)
|
|
224
|
+
3. Check `.agents/memory/ui-diversification.json` for last theme/macrostructure used
|
|
225
|
+
4. If redesign: read `references/macrostructures.md` index pick ONE different from last load only that file
|
|
226
|
+
5. If project has locked theme: load `references/themes/[name].md`
|
|
227
|
+
|
|
228
|
+
**Diversification rule:** consecutive builds must use different theme + macrostructure from `ui-diversification.json`.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
### Phase 3 — Build or Edit
|
|
233
|
+
|
|
234
|
+
**Steps:**
|
|
235
|
+
1. For new UI: create component from design reference using DESIGN.md tokens
|
|
236
|
+
2. For edit: modify existing component per user request (text, API mapping, layout)
|
|
237
|
+
3. Apply theme + macrostructure fingerprint
|
|
238
|
+
4. Handle all 3 UI states: Loading, Success, Error
|
|
239
|
+
|
|
240
|
+
**API mapping rule:**
|
|
241
|
+
- Bind API response to component props via generated TypeScript interfaces
|
|
242
|
+
- NEVER hardcode API URLs in component
|
|
243
|
+
- Use existing API client pattern from project
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
### Phase 4 — Self-Audit (Anti-Slop Check)
|
|
248
|
+
|
|
249
|
+
**Checklist (must pass ALL):**
|
|
250
|
+
- [ ] No hardcoded colors — only DESIGN.md tokens
|
|
251
|
+
- [ ] No font-size in px without token — use rem/token
|
|
252
|
+
- [ ] No `margin: auto` soup — use proper grid/flex
|
|
253
|
+
- [ ] All interactive elements have hover + focus state
|
|
254
|
+
- [ ] Mobile viewport works (no horizontal overflow)
|
|
255
|
+
- [ ] No `!important` overrides (except resets)
|
|
256
|
+
- [ ] No inline styles except dynamic values
|
|
257
|
+
- [ ] Loading state implemented (skeleton or spinner)
|
|
258
|
+
- [ ] Error state implemented (clear message)
|
|
259
|
+
- [ ] Empty state implemented (helpful illustration/text)
|
|
260
|
+
|
|
261
|
+
**Decision:**
|
|
262
|
+
```
|
|
263
|
+
IF all checks pass
|
|
264
|
+
EXIT: SUCCESS
|
|
265
|
+
|
|
266
|
+
ELSE IF 1–2 minor fails
|
|
267
|
+
Fix immediately, EXIT: SUCCESS
|
|
268
|
+
|
|
269
|
+
ELSE IF > 2 fails OR hardcoded colors found
|
|
270
|
+
Fix all, re-audit, EXIT: PARTIAL if still one gap
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
### Phase 5 — Slop Test (post-emit)
|
|
276
|
+
|
|
277
|
+
Load `references/slop-test.md` and verify all 58 gates pass.
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
IF all 58 gates pass
|
|
281
|
+
EXIT: SUCCESS
|
|
282
|
+
|
|
283
|
+
ELSE IF critical gate fails (hardcoded purple gradient, banned font)
|
|
284
|
+
EXIT: FAILED — rebuild required
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## Confidence Model
|
|
290
|
+
|
|
291
|
+
| Level | Condition | Action |
|
|
292
|
+
|-------|-----------|--------|
|
|
293
|
+
| HIGH | DESIGN.md complete, design reference clear, API schema provided | Build directly |
|
|
294
|
+
| MEDIUM | Some tokens missing or design reference ambiguous | Note gaps, proceed |
|
|
295
|
+
| LOW | DESIGN.md missing or design reference too vague | EXIT: BLOCKED |
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Severity
|
|
300
|
+
|
|
301
|
+
| Level | Definition | Example |
|
|
302
|
+
|-------|-----------|---------|
|
|
303
|
+
| CRITICAL | Hardcoded API URL in component, banned font used | `axios.get("http://localhost")` in JSX |
|
|
304
|
+
| HIGH | Missing error/loading state, hardcoded color not in DESIGN.md | No 500 handler |
|
|
305
|
+
| MEDIUM | Missing hover state, spacing off by 1 unit | Button without focus ring |
|
|
306
|
+
| LOW | Comment missing, minor naming inconsistency | `temp` variable name |
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Evidence Format
|
|
311
|
+
|
|
312
|
+
```
|
|
313
|
+
[SEVERITY] path/to/Component.tsx:LINE
|
|
314
|
+
Category: [TOKEN|SEMANTIC|INTERACTION|RESPONSIVE|STATE|ARIA|SLOP]
|
|
315
|
+
Reason: [specific violation]
|
|
316
|
+
Confidence: HIGH
|
|
317
|
+
Fix: [one-line actionable suggestion]
|
|
318
|
+
Points: -N pts (for audit mode)
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Retry Policy
|
|
324
|
+
|
|
325
|
+
```
|
|
326
|
+
Build/Edit fails
|
|
327
|
+
└─ Check failure type
|
|
328
|
+
├─ Token missing infer from DESIGN.md, note assumption
|
|
329
|
+
└─ Design reference unclear EXIT: BLOCKED, ask user
|
|
330
|
+
|
|
331
|
+
Slop test fails
|
|
332
|
+
└─ Critical gate (hardcoded color, banned font)
|
|
333
|
+
└─ EXIT: FAILED — do not ship, rebuild required
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Escalation Rules
|
|
339
|
+
|
|
340
|
+
```
|
|
341
|
+
BLOCKED: DESIGN.md missing or design reference unclear
|
|
342
|
+
Missing:
|
|
343
|
+
- DESIGN.md with color/spacing/typography tokens
|
|
344
|
+
- Design reference (Figma/ảnh/wireframe)
|
|
345
|
+
- For --study: screenshot or public URL
|
|
346
|
+
Questions:
|
|
347
|
+
1. Bạn có DESIGN.md chưa? (chạy qk-project-bootstrap nếu chưa)
|
|
348
|
+
2. Design reference là gì? (Figma link / ảnh / mô tả)
|
|
349
|
+
3. Cho phép tạo DESIGN.md mới không?
|
|
350
|
+
Recommended Assumptions (if proceeding):
|
|
351
|
+
- Use industry-standard: 8px spacing, Inter font, neutral gray palette
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## Handoff Contract
|
|
357
|
+
|
|
358
|
+
### Consumes
|
|
359
|
+
```json
|
|
360
|
+
{
|
|
361
|
+
"from": "user or qk-orchestrator",
|
|
362
|
+
"required_fields": ["verb", "design_md_path"],
|
|
363
|
+
"optional_fields": ["design_reference", "target_component", "api_schema", "framework"]
|
|
364
|
+
}
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### Produces
|
|
368
|
+
```json
|
|
369
|
+
{
|
|
370
|
+
"to": "user or qk-ui-audit (if --audit)",
|
|
371
|
+
"output_fields": ["component_files", "tokens_used", "states_implemented", "slop_test_result", "exit_code"]
|
|
372
|
+
}
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## Output Format
|
|
378
|
+
|
|
379
|
+
### Default (build/edit)
|
|
380
|
+
```
|
|
381
|
+
🎨 UI Builder
|
|
382
|
+
─────────────────────────────────────────────────
|
|
383
|
+
Component: [ComponentName]
|
|
384
|
+
Theme: [theme name from references/themes/]
|
|
385
|
+
Macrostructure: [macrostructure name]
|
|
386
|
+
|
|
387
|
+
States implemented:
|
|
388
|
+
✅ Loading / ✅ Success / ✅ Error
|
|
389
|
+
✅ Hover / ✅ Focus / ✅ Active / ✅ Disabled
|
|
390
|
+
|
|
391
|
+
Tokens used:
|
|
392
|
+
- --color-primary-500, --space-4, --font-size-base
|
|
393
|
+
|
|
394
|
+
API Mapping:
|
|
395
|
+
✅ [endpoint prop] mapped
|
|
396
|
+
|
|
397
|
+
Exit Code: [SUCCESS | PARTIAL | BLOCKED | FAILED]
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
### `--audit`
|
|
401
|
+
```
|
|
402
|
+
🎨 UI Audit Report
|
|
403
|
+
─────────────────────────────────────────────────
|
|
404
|
+
Component: [path/to/component]
|
|
405
|
+
Theme: [N/A — read-only audit]
|
|
406
|
+
|
|
407
|
+
Scores:
|
|
408
|
+
P1 Accessibility: [X/15]
|
|
409
|
+
P2 Layout: [X/15]
|
|
410
|
+
P3 Typography: [X/15]
|
|
411
|
+
P4 Interactions: [X/15]
|
|
412
|
+
P5 Anti-Slop: [X/15]
|
|
413
|
+
P6 Performance: [X/10]
|
|
414
|
+
─────────────────
|
|
415
|
+
Total: [X/85] [PASS ≥ 90% | FAIL < 90%]
|
|
416
|
+
|
|
417
|
+
Violations (top priority first):
|
|
418
|
+
[SEVERITY] file:LINE — reason — Fix: suggestion (-Xpts)
|
|
419
|
+
|
|
420
|
+
Verdict: [PASS | FAIL — requires redesign]
|
|
421
|
+
Exit Code: [SUCCESS | PARTIAL | FAILED]
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
### `--redesign`
|
|
425
|
+
```
|
|
426
|
+
🎨 UI Redesign
|
|
427
|
+
─────────────────────────────────────────────────
|
|
428
|
+
Component: [ComponentName]
|
|
429
|
+
Old macrostructure: [old name]
|
|
430
|
+
New macrostructure: [new name]
|
|
431
|
+
Old theme: [old theme]
|
|
432
|
+
New theme: [new theme]
|
|
433
|
+
|
|
434
|
+
Kept:
|
|
435
|
+
- Copy/IA structure
|
|
436
|
+
- Brand colors
|
|
437
|
+
- Primary user flow
|
|
438
|
+
|
|
439
|
+
Changed:
|
|
440
|
+
- Layout fingerprint
|
|
441
|
+
- Section ordering
|
|
442
|
+
- Visual hierarchy
|
|
443
|
+
|
|
444
|
+
Exit Code: [SUCCESS | PARTIAL | BLOCKED | FAILED]
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### `--study`
|
|
448
|
+
```
|
|
449
|
+
🎨 Design Study
|
|
450
|
+
─────────────────────────────────────────────────
|
|
451
|
+
Source: [screenshot path | URL]
|
|
452
|
+
DNA extracted:
|
|
453
|
+
- Macrostructure: [name]
|
|
454
|
+
- Theme axes: [paper band / display style / accent hue]
|
|
455
|
+
- Type pairing: [font1 + font2]
|
|
456
|
+
- Color anchor: [primary / secondary / accent]
|
|
457
|
+
|
|
458
|
+
Output: design.md written to [path]
|
|
459
|
+
Next: ./qk-ui-builder --redesign with extracted DNA
|
|
460
|
+
|
|
461
|
+
Exit Code: [SUCCESS | BLOCKED]
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
---
|
|
465
|
+
|
|
466
|
+
## Exit Codes
|
|
467
|
+
|
|
468
|
+
| Code | Meaning | When |
|
|
469
|
+
|------|---------|------|
|
|
470
|
+
| SUCCESS | Build/edit/audit/study completed successfully | All checks passed |
|
|
471
|
+
| PARTIAL | Built with minor gaps or incomplete audit | Budget exhausted or 1-2 fixes pending |
|
|
472
|
+
| BLOCKED | Missing DESIGN.md, design reference, or screenshot | Cannot proceed |
|
|
473
|
+
| FAILED | Slop test critical failure or architectural conflict | Rebuild required |
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
## References
|
|
478
|
+
|
|
479
|
+
- `references/themes/` — Theme catalog (20 themes)
|
|
480
|
+
- `references/macrostructures/` — 21 page shapes
|
|
481
|
+
- `references/slop-test.md` — 58 anti-slop gates
|
|
482
|
+
- `references/anti-patterns.md` — Named tells to avoid
|
|
483
|
+
|
|
484
|
+
---
|
|
485
|
+
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
---
|
|
490
|
+
|
|
491
|
+
## Prompt Template — Cách viết yêu cầu để AI build UI đúng ngay
|
|
492
|
+
|
|
493
|
+
```
|
|
494
|
+
Làm gì: [build / edit / audit / redesign]
|
|
495
|
+
Component: [Tên component hoặc trang cần làm]
|
|
496
|
+
Framework: [React / Vue / Next.js / ...]
|
|
497
|
+
CSS: [Tailwind / SCSS / CSS Modules / ...]
|
|
498
|
+
Tham chiếu: [Link Figma / đính kèm ảnh / mô tả layout]
|
|
499
|
+
Done khi: [Trông như thế nào / hoạt động ra sao]
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
**Ví dụ đủ thông tin:**
|
|
503
|
+
```
|
|
504
|
+
Làm gì: build
|
|
505
|
+
Component: ProductCard — hiển thị ảnh, tên, giá, nút Add to Cart
|
|
506
|
+
Framework: React + TypeScript
|
|
507
|
+
CSS: Tailwind CSS
|
|
508
|
+
Tham chiếu: [đính kèm ảnh Figma]
|
|
509
|
+
Done khi: Responsive, có hover state, loading skeleton khi chưa có data
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
**Ví dụ dùng command với args:**
|
|
513
|
+
```
|
|
514
|
+
./qk-ui-builder --fw=react --css=tailwind
|
|
515
|
+
Làm ProductCard theo ảnh đính kèm
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
**Ví dụ tối giản:**
|
|
519
|
+
```
|
|
520
|
+
Làm navbar responsive cho app Next.js, logo bên trái, menu bên phải
|
|
521
|
+
```
|