ai-developer-skill-os 9.3.0 → 10.1.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.
Files changed (185) hide show
  1. package/.agents/AGENTS.md +60 -40
  2. package/.agents/DEV_PROFILE.md +36 -2
  3. package/.agents/registry/graph.json +95 -342
  4. package/.agents/registry/index.yaml +61 -237
  5. package/.agents/rules/coding.md +30 -12
  6. package/.agents/rules/command-safety.md +19 -8
  7. package/.agents/rules/global.md +234 -28
  8. package/.agents/rules/prompt-compiler.md +170 -0
  9. package/.agents/skills/qk-api-data-discovery/SKILL.md +470 -0
  10. package/.agents/skills/qk-backend-data/SKILL.md +190 -0
  11. package/.agents/skills/qk-bug-resolution/SKILL.md +176 -248
  12. package/.agents/skills/qk-code-cleaner/SKILL.md +250 -0
  13. package/.agents/skills/qk-code-review/SKILL.md +126 -247
  14. package/.agents/skills/qk-devops-release/SKILL.md +145 -0
  15. package/.agents/skills/qk-feature-delivery/SKILL.md +179 -247
  16. package/.agents/skills/qk-orchestrator/SKILL.md +100 -151
  17. package/.agents/skills/qk-product-spec/SKILL.md +113 -0
  18. package/.agents/skills/qk-prompt-compiler/SKILL.md +321 -0
  19. package/.agents/skills/qk-ui-engineer/SKILL.md +137 -0
  20. package/.agents/workflows/feature-delivery.yml +1 -1
  21. package/.agents/workflows/production-release.yml +1 -1
  22. package/.agents/workflows/spec-driven-development.yml +109 -87
  23. package/CHANGELOG.md +54 -0
  24. package/README.md +125 -184
  25. package/bin/install.js +337 -329
  26. package/package.json +2 -2
  27. package/.agents/README.md +0 -90
  28. package/.agents/docs/CHI_TIET_SKILLS.md +0 -126
  29. package/.agents/docs/HUONG_DAN_SU_DUNG.md +0 -120
  30. package/.agents/docs/MIGRATION-CLEANUP-V8.1.3.md +0 -36
  31. package/.agents/docs/MIGRATION-STATUS.md +0 -35
  32. package/.agents/docs/MIGRATION-V8.md +0 -10
  33. package/.agents/docs/ROADMAP-V8.2.md +0 -78
  34. package/.agents/docs/V8-CERTIFICATION.md +0 -27
  35. package/.agents/skills/qk-access-policy/SKILL.md +0 -206
  36. package/.agents/skills/qk-access-policy/capability.yaml +0 -23
  37. package/.agents/skills/qk-access-policy/evals/scorecard.yaml +0 -36
  38. package/.agents/skills/qk-agent-observability/SKILL.md +0 -108
  39. package/.agents/skills/qk-agent-observability/capability.yaml +0 -29
  40. package/.agents/skills/qk-agent-observability/evals/scorecard.yaml +0 -29
  41. package/.agents/skills/qk-agent-observability/references/scorecard.yaml +0 -80
  42. package/.agents/skills/qk-ai-builder/SKILL.md +0 -254
  43. package/.agents/skills/qk-ai-builder/capability.yaml +0 -23
  44. package/.agents/skills/qk-ai-builder/evals/scorecard.yaml +0 -30
  45. package/.agents/skills/qk-api-consumer/SKILL.md +0 -256
  46. package/.agents/skills/qk-api-consumer/capability.yaml +0 -21
  47. package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +0 -29
  48. package/.agents/skills/qk-api-lifecycle/SKILL.md +0 -251
  49. package/.agents/skills/qk-api-lifecycle/capability.yaml +0 -23
  50. package/.agents/skills/qk-api-lifecycle/evals/scorecard.yaml +0 -29
  51. package/.agents/skills/qk-bug-resolution/capability.yaml +0 -25
  52. package/.agents/skills/qk-code-review/capability.yaml +0 -23
  53. package/.agents/skills/qk-context-loader/SKILL.md +0 -198
  54. package/.agents/skills/qk-context-loader/capability.yaml +0 -23
  55. package/.agents/skills/qk-context-loader/evals/scorecard.yaml +0 -28
  56. package/.agents/skills/qk-data-engineer/SKILL.md +0 -253
  57. package/.agents/skills/qk-data-lifecycle/SKILL.md +0 -197
  58. package/.agents/skills/qk-data-lifecycle/capability.yaml +0 -23
  59. package/.agents/skills/qk-data-lifecycle/evals/scorecard.yaml +0 -29
  60. package/.agents/skills/qk-db-optimizer/SKILL.md +0 -210
  61. package/.agents/skills/qk-db-optimizer/capability.yaml +0 -22
  62. package/.agents/skills/qk-db-optimizer/evals/scorecard.yaml +0 -28
  63. package/.agents/skills/qk-design-system-engineering/SKILL.md +0 -193
  64. package/.agents/skills/qk-design-system-engineering/capability.yaml +0 -25
  65. package/.agents/skills/qk-design-system-engineering/evals/scorecard.yaml +0 -27
  66. package/.agents/skills/qk-devops-platform/SKILL.md +0 -198
  67. package/.agents/skills/qk-devops-platform/capability.yaml +0 -29
  68. package/.agents/skills/qk-devops-platform/evals/scorecard.yaml +0 -28
  69. package/.agents/skills/qk-docs/SKILL.md +0 -193
  70. package/.agents/skills/qk-docs/capability.yaml +0 -23
  71. package/.agents/skills/qk-docs/evals/scorecard.yaml +0 -27
  72. package/.agents/skills/qk-engineering-standard/SKILL.md +0 -89
  73. package/.agents/skills/qk-engineering-standard/capability.yaml +0 -23
  74. package/.agents/skills/qk-engineering-standard/evals/scorecard.yaml +0 -28
  75. package/.agents/skills/qk-engineering-standard/references/anti-patterns.md +0 -121
  76. package/.agents/skills/qk-engineering-standard/rules/backend.md +0 -122
  77. package/.agents/skills/qk-engineering-standard/rules/database.md +0 -3
  78. package/.agents/skills/qk-engineering-standard/rules/frontend.md +0 -152
  79. package/.agents/skills/qk-engineering-standard/rules/security.md +0 -3
  80. package/.agents/skills/qk-engineering-standard/rules/testing.md +0 -3
  81. package/.agents/skills/qk-fe-api-integration/SKILL.md +0 -704
  82. package/.agents/skills/qk-fe-api-integration/capability.yaml +0 -21
  83. package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +0 -29
  84. package/.agents/skills/qk-feature-delivery/capability.yaml +0 -24
  85. package/.agents/skills/qk-frontend-architecture/SKILL.md +0 -127
  86. package/.agents/skills/qk-frontend-architecture/capability.yaml +0 -28
  87. package/.agents/skills/qk-frontend-architecture/evals/scorecard.yaml +0 -28
  88. package/.agents/skills/qk-help/SKILL.md +0 -107
  89. package/.agents/skills/qk-help/capability.yaml +0 -20
  90. package/.agents/skills/qk-help/evals/scorecard.yaml +0 -13
  91. package/.agents/skills/qk-orchestrator/capability.yaml +0 -22
  92. package/.agents/skills/qk-product-specification/SKILL.md +0 -187
  93. package/.agents/skills/qk-product-specification/capability.yaml +0 -27
  94. package/.agents/skills/qk-product-specification/evals/scorecard.yaml +0 -27
  95. package/.agents/skills/qk-production-release/SKILL.md +0 -188
  96. package/.agents/skills/qk-production-release/capability.yaml +0 -27
  97. package/.agents/skills/qk-production-release/evals/scorecard.yaml +0 -28
  98. package/.agents/skills/qk-project-audit/SKILL.md +0 -174
  99. package/.agents/skills/qk-project-bootstrap/SKILL.md +0 -372
  100. package/.agents/skills/qk-project-bootstrap/capability.yaml +0 -23
  101. package/.agents/skills/qk-project-bootstrap/evals/scorecard.yaml +0 -28
  102. package/.agents/skills/qk-project-health/SKILL.md +0 -202
  103. package/.agents/skills/qk-project-health/capability.yaml +0 -23
  104. package/.agents/skills/qk-project-health/evals/scorecard.yaml +0 -27
  105. package/.agents/skills/qk-project-memory/SKILL.md +0 -303
  106. package/.agents/skills/qk-project-memory/capability.yaml +0 -23
  107. package/.agents/skills/qk-project-memory/evals/scorecard.yaml +0 -27
  108. package/.agents/skills/qk-refactor/SKILL.md +0 -243
  109. package/.agents/skills/qk-refactor/capability.yaml +0 -26
  110. package/.agents/skills/qk-refactor/evals/scorecard.yaml +0 -27
  111. package/.agents/skills/qk-security-audit/SKILL.md +0 -280
  112. package/.agents/skills/qk-security-audit/capability.yaml +0 -29
  113. package/.agents/skills/qk-security-audit/evals/scorecard.yaml +0 -27
  114. package/.agents/skills/qk-system-evolution/SKILL.md +0 -625
  115. package/.agents/skills/qk-system-evolution/capability.yaml +0 -24
  116. package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +0 -26
  117. package/.agents/skills/qk-test-engineering/SKILL.md +0 -215
  118. package/.agents/skills/qk-test-engineering/capability.yaml +0 -28
  119. package/.agents/skills/qk-test-engineering/evals/scorecard.yaml +0 -26
  120. package/.agents/skills/qk-ui-audit/SKILL.md +0 -175
  121. package/.agents/skills/qk-ui-audit/capability.yaml +0 -23
  122. package/.agents/skills/qk-ui-audit/evals/scorecard.yaml +0 -26
  123. package/.agents/skills/qk-ui-audit/references/anti-slop-checklist.md +0 -136
  124. package/.agents/skills/qk-ui-builder/SKILL.md +0 -521
  125. package/.agents/skills/qk-ui-builder/capability.yaml +0 -29
  126. package/.agents/skills/qk-ui-builder/evals/scorecard.yaml +0 -26
  127. package/.agents/skills/qk-ui-builder/references/anti-patterns.md +0 -295
  128. package/.agents/skills/qk-ui-builder/references/color.md +0 -115
  129. package/.agents/skills/qk-ui-builder/references/component-cookbook.md +0 -458
  130. package/.agents/skills/qk-ui-builder/references/copy.md +0 -250
  131. package/.agents/skills/qk-ui-builder/references/interaction-and-states.md +0 -115
  132. package/.agents/skills/qk-ui-builder/references/layout-and-space.md +0 -111
  133. package/.agents/skills/qk-ui-builder/references/macrostructures/01-bento-grid.md +0 -48
  134. package/.agents/skills/qk-ui-builder/references/macrostructures/02-long-document.md +0 -50
  135. package/.agents/skills/qk-ui-builder/references/macrostructures/03-marquee-hero.md +0 -51
  136. package/.agents/skills/qk-ui-builder/references/macrostructures/04-stat-led.md +0 -49
  137. package/.agents/skills/qk-ui-builder/references/macrostructures/05-workbench.md +0 -44
  138. package/.agents/skills/qk-ui-builder/references/macrostructures/06-conversational-faq.md +0 -50
  139. package/.agents/skills/qk-ui-builder/references/macrostructures/07-manifesto.md +0 -51
  140. package/.agents/skills/qk-ui-builder/references/macrostructures/08-photographic.md +0 -50
  141. package/.agents/skills/qk-ui-builder/references/macrostructures/09-quote-led.md +0 -50
  142. package/.agents/skills/qk-ui-builder/references/macrostructures/11-catalogue.md +0 -49
  143. package/.agents/skills/qk-ui-builder/references/macrostructures/12-letter.md +0 -49
  144. package/.agents/skills/qk-ui-builder/references/macrostructures/13-index-first.md +0 -49
  145. package/.agents/skills/qk-ui-builder/references/macrostructures/14-narrative-workflow.md +0 -48
  146. package/.agents/skills/qk-ui-builder/references/macrostructures/15-split-studio.md +0 -48
  147. package/.agents/skills/qk-ui-builder/references/macrostructures/16-feature-stack.md +0 -51
  148. package/.agents/skills/qk-ui-builder/references/macrostructures/17-type-specimen.md +0 -48
  149. package/.agents/skills/qk-ui-builder/references/macrostructures/18-portfolio-grid.md +0 -48
  150. package/.agents/skills/qk-ui-builder/references/macrostructures/19-map-diagram.md +0 -50
  151. package/.agents/skills/qk-ui-builder/references/macrostructures/20-ecosystem-index.md +0 -48
  152. package/.agents/skills/qk-ui-builder/references/macrostructures/21-component-playground.md +0 -45
  153. package/.agents/skills/qk-ui-builder/references/macrostructures.md +0 -38
  154. package/.agents/skills/qk-ui-builder/references/motion.md +0 -95
  155. package/.agents/skills/qk-ui-builder/references/responsive.md +0 -115
  156. package/.agents/skills/qk-ui-builder/references/slop-test.md +0 -135
  157. package/.agents/skills/qk-ui-builder/references/structure.md +0 -280
  158. package/.agents/skills/qk-ui-builder/references/themes/atmospheric.md +0 -53
  159. package/.agents/skills/qk-ui-builder/references/themes/carnival.md +0 -52
  160. package/.agents/skills/qk-ui-builder/references/themes/cobalt.md +0 -52
  161. package/.agents/skills/qk-ui-builder/references/themes/editorial.md +0 -52
  162. package/.agents/skills/qk-ui-builder/references/themes/garden.md +0 -52
  163. package/.agents/skills/qk-ui-builder/references/themes/hum.md +0 -52
  164. package/.agents/skills/qk-ui-builder/references/themes/lumen.md +0 -52
  165. package/.agents/skills/qk-ui-builder/references/themes/midnight.md +0 -52
  166. package/.agents/skills/qk-ui-builder/references/themes/modern-minimal.md +0 -52
  167. package/.agents/skills/qk-ui-builder/references/themes/playful.md +0 -52
  168. package/.agents/skills/qk-ui-builder/references/themes/specimen.md +0 -52
  169. package/.agents/skills/qk-ui-builder/references/themes/terminal.md +0 -52
  170. package/.agents/skills/qk-ui-builder/references/typography.md +0 -129
  171. package/.agents/skills/qk-ui-system-builder/SKILL.md +0 -183
  172. package/.agents/skills/qk-ui-system-builder/capability.yaml +0 -25
  173. package/.agents/skills/qk-ui-system-builder/evals/scorecard.yaml +0 -26
  174. package/.agents/skills/qk-upgrade/SKILL.md +0 -301
  175. package/.agents/skills/qk-upgrade/capability.yaml +0 -24
  176. package/.agents/skills/qk-upgrade/evals/scorecard.yaml +0 -26
  177. package/.agents/skills/qk-validation-gate/SKILL.md +0 -88
  178. package/.agents/skills/qk-validation-gate/capability.yaml +0 -23
  179. package/.agents/skills/qk-validation-gate/evals/scorecard.yaml +0 -26
  180. package/.agents/skills/qk-web-quality-gate/SKILL.md +0 -197
  181. package/.agents/skills/qk-web-quality-gate/capability.yaml +0 -24
  182. package/.agents/skills/qk-web-quality-gate/evals/scorecard.yaml +0 -26
  183. package/.agents/workflows/research.yml +0 -75
  184. package/.agents/workflows/skill-evolution.yml +0 -97
  185. package/tooling/fix-refactor.js +0 -8
@@ -1,115 +0,0 @@
1
- # Responsive
2
-
3
- Foundational rules for building layouts that adapt across screen sizes without breaking, horizontal scroll, or un-tappable controls.
4
-
5
- ## Breakpoints
6
-
7
- Use this standard scale. Build **mobile-first** (base styles = small screens, then enhance upward).
8
-
9
- ```
10
- sm 640px
11
- md 768px
12
- lg 1024px
13
- xl 1280px
14
- ```
15
-
16
- ```css
17
- /* mobile-first: base = mobile, then min-width queries */
18
- @media (min-width: 640px) { /* sm */ }
19
- @media (min-width: 768px) { /* md */ }
20
- @media (min-width: 1024px) { /* lg */ }
21
- @media (min-width: 1280px) { /* xl */ }
22
- ```
23
-
24
- ## Mobile: Stack Vertically
25
-
26
- On small screens, lay content out in a **single vertical column**. Never require horizontal scrolling for core content.
27
-
28
- ```css
29
- .layout {
30
- display: grid;
31
- grid-template-columns: 1fr; /* stacked on mobile */
32
- gap: var(--space-6);
33
- }
34
- @media (min-width: 768px) {
35
- .layout { grid-template-columns: 240px 1fr; } /* sidebar + content */
36
- }
37
- ```
38
-
39
- ```css
40
- /* Guard against accidental horizontal overflow */
41
- html, body { overflow-x: hidden; max-width: 100%; }
42
- img, video, table { max-width: 100%; }
43
- ```
44
-
45
- ## Touch Targets: Min 44×44px
46
-
47
- Every interactive control must be at least **44×44px** to be comfortably tappable. Don't let padding shrink the hit area below this.
48
-
49
- ```css
50
- .btn, .nav-link, .icon-button {
51
- min-height: 44px;
52
- min-width: 44px;
53
- display: inline-flex;
54
- align-items: center;
55
- justify-content: center;
56
- padding: var(--space-2) var(--space-4);
57
- }
58
- ```
59
-
60
- ## Fluid Typography with clamp()
61
-
62
- Use `clamp()` for headings/hero text so type scales smoothly between breakpoints without abrupt jumps.
63
-
64
- ```css
65
- h1 {
66
- /* min 32px, preferred 5vw, max 64px */
67
- font-size: clamp(2rem, 5vw, 4rem); /* 32px → 64px */
68
- }
69
- h2 {
70
- font-size: clamp(1.5rem, 3vw, 2rem); /* 24px → 32px */
71
- }
72
- ```
73
-
74
- Keep body text near `--text-base` (16px) for readability; reserve clamp() for display sizes.
75
-
76
- ## Image Grids: minmax(0, 1fr)
77
-
78
- For responsive image/card grids, use `minmax(0, 1fr)` so items shrink properly and never overflow. Fixed-width columns break on mobile.
79
-
80
- ```css
81
- .gallery {
82
- display: grid;
83
- grid-template-columns: repeat(auto-fill, minmax(0, 1fr));
84
- gap: var(--space-4);
85
- }
86
- @media (min-width: 640px) { .gallery { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
87
- @media (min-width: 1024px) { .gallery { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
88
- ```
89
-
90
- ```css
91
- .gallery img { width: 100%; height: 100%; object-fit: cover; display: block; }
92
- ```
93
-
94
- ## Desktop Container
95
-
96
- Cap desktop content at 1200px and center (see layout-and-space.md). On mobile it becomes 100% width with safe padding.
97
-
98
- ```css
99
- .container {
100
- width: 100%;
101
- max-width: 1200px;
102
- margin-inline: auto;
103
- padding-inline: var(--space-4);
104
- }
105
- @media (min-width: 768px) { .container { padding-inline: var(--space-6); } }
106
- ```
107
-
108
- ## Practical Checklist
109
-
110
- - [ ] Mobile-first with sm/md/lg/xl breakpoints.
111
- - [ ] Mobile stacks vertically; no horizontal scroll.
112
- - [ ] All tap targets ≥ 44×44px.
113
- - [ ] Display type uses `clamp()` for fluid scaling.
114
- - [ ] Image/card grids use `minmax(0, 1fr)`.
115
- - [ ] Desktop content capped at 1200px.
@@ -1,135 +0,0 @@
1
- # Slop Test — 58 Anti-Slop Gates
2
-
3
- Run this checklist AFTER every build. Every answer must be **NO**.
4
-
5
- ## Pre-Emit Self-Critique (Score 1–5 on each axis)
6
-
7
- | Axis | Question | Score |
8
- |------|----------|-------|
9
- | Philosophy | Does this serve the user, or just show off? | ___ |
10
- | Hierarchy | Is the visual hierarchy clear within 3 seconds? | ___ |
11
- | Execution | Is every interaction polished, not just present? | ___ |
12
- | Specificity | Does this feel made for this brief, not generic? | ___ |
13
- | Restraint | Could anything be removed without losing meaning? | ___ |
14
- | Variety | Would a second page feel different, not a color-swap? | ___ |
15
-
16
- **Rule:** Any axis < 3 → revise before continuing.
17
-
18
- ---
19
-
20
- ## Visual Gates (1–7)
21
-
22
- - [ ] **1.** No banned fonts: Inter, Roboto, Arial, system-ui as primary identity font
23
- - [ ] **2.** No purple-blue gradients (`linear-gradient(135deg, #a855f7, #3b82f6)`)
24
- - [ ] **3.** No gradient text (`background-clip: text`)
25
- - [ ] **4.** No 3-equal-column icon cards
26
- - [ ] **5.** No card-in-card layouts (card inside card inside card)
27
- - [ ] **6.** No side-stripe cards (left border accent only)
28
- - [ ] **7.** No centred-everything hero (all content centered with max-width)
29
-
30
- ## Structural Gates (8–9)
31
-
32
- - [ ] **8.** No AI-template reuse (same fingerprint as prior build in project)
33
- - [ ] **9.** Sections separated by more than whitespace (use dividers, headings, or background changes)
34
-
35
- ## Microinteraction Gates (10–19)
36
-
37
- - [ ] **10.** No `transition-all` on interactive elements
38
- - [ ] **11.** No `hover:scale-105` without context
39
- - [ ] **12.** No `cubic-bezier(0.68, -0.55, 0.265, 1.55)` (bounce easing)
40
- - [ ] **13.** No more than 2 hover effects per element
41
- - [ ] **14.** No animating layout props (width, height, padding)
42
- - [ ] **15.** No animated focus ring (focus state must be instant)
43
- - [ ] **16.** No celebratory toasts/confetti on load
44
- - [ ] **17.** No equal hover/focus tooltip delay
45
- - [ ] **18.** No auto-rotating carousel without pause-on-hover
46
- - [ ] **19.** No placeholder names (John Doe, Jane Smith, etc.)
47
-
48
- ## Variety Gates (20–21)
49
-
50
- - [ ] **20.** Macrostructure stamp present in CSS comment
51
- - [ ] **21.** Not Specimen fall-through (every brief needs a real macrostructure)
52
-
53
- ## Implementation Gates (22–27)
54
-
55
- - [ ] **22.** No zero-chroma neutrals (`hsl(0, 0%, X%)` as primary)
56
- - [ ] **23.** Accent color footprint < 5% of viewport
57
- - [ ] **24.** Spacing follows scale (no off-scale values like 13px, 27px)
58
- - [ ] **25.** Prose measure between 45–75ch
59
- - [ ] **26.** All interactive elements have focus, active, disabled states
60
- - [ ] **27.** Motion has `prefers-reduced-motion` fallback
61
-
62
- ## Hero Enrichment Gates (28–31)
63
-
64
- - [ ] **28.** No autoplay-with-sound video
65
- - [ ] **29.** No over-busy abstract background (more than 2 visual layers)
66
- - [ ] **30.** No mixed icon libraries or emoji icons in professional UI
67
- - [ ] **31.** No Lottie animation when CSS transition would suffice
68
-
69
- ## Diversification Gates (32–33)
70
-
71
- - [ ] **32.** Same archetype not repeated without varied knob (size, color, layout)
72
- - [ ] **33.** Decorative SVG/figure has `aria-hidden="true"` or meaningful `role`
73
-
74
- ## Layout-Safety Gates (34–36)
75
-
76
- - [ ] **34.** No horizontal scroll (`overflow-x: clip` on html+body)
77
- - [ ] **35.** No misplaced decorative text effects (text-shadow as decoration)
78
- - [ ] **36.** Interactive bars centered (not left-aligned with unbalanced whitespace)
79
-
80
- ## Typography Gates (37–38a)
81
-
82
- - [ ] **37.** No more than 3 font families
83
- - [ ] **38.** No outlier font used in > 2 slots
84
- - [ ] **38a.** No italic headers (headers use weight, not style)
85
-
86
- ## Input-State Gates (39)
87
-
88
- - [ ] **39.** No border-width shift on focus, no border-built focus ring, no input/button height mismatch, no collapsed helper text, no opacity-only disabled
89
-
90
- ## Contrast Gates (40–41)
91
-
92
- - [ ] **40.** WCAG 2.1 AA contrast (4.5:1 for text, 3:1 for large text)
93
- - [ ] **41.** No ink-on-ink (same color for text and background with only opacity difference)
94
-
95
- ## Chrome Gates (42–45)
96
-
97
- - [ ] **42.** No AI nav fingerprint (centered logo, pill nav, gradient CTA)
98
- - [ ] **43.** No AI footer fingerprint (3 columns: Product, Company, Legal, social icons row)
99
- - [ ] **44.** Hero fits viewport (no excessive height)
100
- - [ ] **45.** Decorative elements have purpose or removed
101
-
102
- ## Honest Copy Gate (46)
103
-
104
- - [ ] **46.** No invented metrics ("10x faster", "100% secure", "trusted by 10,000+")
105
-
106
- ## Re-Drawn Chrome Gate (47)
107
-
108
- - [ ] **47.** No fake browser/phone/code/IDE chrome unless building a mockup tool
109
-
110
- ## Token Discipline Gate (48)
111
-
112
- - [ ] **48.** No mid-render token improvisation (all values from DESIGN.md or theme)
113
-
114
- ## Responsive Clickable Gate (49)
115
-
116
- - [ ] **49.** No two-line clickable text (buttons/links max 1 line)
117
-
118
- ## Mobile Non-Negotiables (50–57)
119
-
120
- - [ ] **50.** Image grids use `minmax(0, 1fr)` not fixed widths
121
- - [ ] **51.** Long words wrap (`overflow-wrap: break-word`)
122
- - [ ] **52.** Mobile section-head collapse (h1 reduces size on small screens)
123
- - [ ] **53.** Radio-tab scroll-jump prevented
124
- - [ ] **54.** No tag-beside-heading on mobile (stack vertically)
125
- - [ ] **55.** All-caps line-height collision avoided (`letter-spacing: 0.05em` minimum)
126
- - [ ] **56.** Sticky header doesn't bleed into content
127
- - [ ] **57.** Studied DNA not discarded (if `--study` was used, its output must be referenced)
128
-
129
- ---
130
-
131
- ## Final Gate
132
-
133
- - [ ] **58.** Pre-emit self-critique average ≥ 3.0 on all 6 axes
134
-
135
- **Pass condition:** All 58 gates = NO. Any YES → fix before shipping.
@@ -1,280 +0,0 @@
1
- # Structure: 6-Axis Fingerprint
2
-
3
- Use this framework to analyze and design page structure systematically. Each axis represents a distinct structural decision that shapes the user's experience.
4
-
5
- ---
6
-
7
- ## Axis 1: Section-Heading Placement
8
-
9
- Where headings sit within their section determines visual hierarchy and reading flow.
10
-
11
- ### Options:
12
-
13
- **Top-left**
14
- - Headings aligned to the left, flush with or near the top of the section.
15
- - Best for: Content-heavy pages, documentation, dashboards.
16
- - Feels: Structured, professional, scannable.
17
-
18
- **Centered**
19
- - Headings centered horizontally within the section.
20
- - Best for: Landing pages, marketing sections, hero content.
21
- - Feels: Formal, balanced, editorial.
22
-
23
- **Inline with content**
24
- - Headings sit within the content flow, often beside images or at the start of cards.
25
- - Best for: Card grids, list layouts, feature sections.
26
- - Feels: Integrated, compact, modern.
27
-
28
- **Floating/overlapping**
29
- - Headings positioned over images or backgrounds, often large and semi-transparent.
30
- - Best for: Hero sections, editorial layouts, portfolio pages.
31
- - Feels: Bold, immersive, designed.
32
-
33
- **Staggered/offset**
34
- - Headings offset from the content grid, creating visual tension.
35
- - Best for: Creative portfolios, marketing sites, asymmetric layouts.
36
- - Feels: Dynamic, intentional, breaking the grid.
37
-
38
- **Hidden/implied**
39
- - No visible heading; section identity comes from context or content structure.
40
- - Best for: Card grids with self-explanatory items, tabbed interfaces.
41
- - Feels: Minimal, relies on content clarity.
42
-
43
- ---
44
-
45
- ## Axis 2: Body Composition
46
-
47
- How content is arranged spatially across the viewport.
48
-
49
- ### Options:
50
-
51
- **Single column**
52
- - One narrow column, max-width ~650px, centered or left-aligned.
53
- - Best for: Long-form reading, articles, documentation.
54
- - Feels: Focused, readable, traditional.
55
-
56
- **Two-column**
57
- - Main content + sidebar, or split content evenly.
58
- - Best for: Documentation, settings pages, blog layouts.
59
- - Feels: Balanced, information-dense, efficient.
60
-
61
- **Three-column**
62
- - Three equal or near-equal columns.
63
- - Best for: Feature grids, card layouts, dashboard widgets.
64
- - Feels: Symmetric, scannable, systematic.
65
-
66
- **Asymmetric**
67
- - Uneven column widths (e.g., 2/3 + 1/3).
68
- - Best for: Marketing pages, case studies, editorial layouts.
69
- - Feels: Dynamic, hierarchical, designed.
70
-
71
- **Full-bleed**
72
- - Content spans the full viewport width.
73
- - Best for: Hero sections, image galleries, immersive experiences.
74
- - Feels: Expansive, modern, bold.
75
-
76
- **Masonry/Pinterest**
77
- - Varied height cards in a waterfall layout.
78
- - Best for: Image galleries, blogs, portfolio grids.
79
- - Feels: Organic, varied, content-adaptive.
80
-
81
- **Dashboard grid**
82
- - Structured grid with mixed card sizes (bento box style).
83
- - Best for: Analytics dashboards, admin panels, data tools.
84
- - Feels: Organized, data-rich, functional.
85
-
86
- ---
87
-
88
- ## Axis 3: Divider Language
89
-
90
- How sections and content blocks are visually separated.
91
-
92
- ### Options:
93
-
94
- **Whitespace**
95
- - Separation achieved through spacing alone, no lines or borders.
96
- - Best for: Modern, minimal designs; content-heavy pages.
97
- - Feels: Clean, breathable, elegant.
98
-
99
- **Horizontal lines**
100
- - Thin or thick lines between sections or list items.
101
- - Best for: Traditional layouts, documents, settings pages.
102
- - Feels: Structured, formal, clear separation.
103
-
104
- **Color blocks**
105
- - Distinct background colors separating sections.
106
- - Best for: Marketing sites, landing pages, long-scrolling pages.
107
- - Feels: Bold, sectional, visually distinct.
108
-
109
- **Cards/containers**
110
- - Each section or item wrapped in a card with shadow/border.
111
- - Best for: Dashboards, data grids, feature lists.
112
- - Feels: Contained, organized, modular.
113
-
114
- **Gradient dividers**
115
- - Fading gradients or angled transitions between sections.
116
- - Best for: Modern marketing, creative portfolios.
117
- - Feels: Fluid, dynamic, premium.
118
-
119
- **Border-only**
120
- - Subtle borders around sections without fill.
121
- - Best for: Admin interfaces, forms, structured data.
122
- - Feels: Precise, technical, understated.
123
-
124
- **No dividers**
125
- - Content flows continuously without separation.
126
- - Best for: Single-topic pages, storytelling, immersive experiences.
127
- - Feels: Unified, narrative, cohesive.
128
-
129
- ---
130
-
131
- ## Axis 4: Button Voice
132
-
133
- The visual language of interactive elements within the page.
134
-
135
- ### Options:
136
-
137
- **Primary/Secondary/Ghost**
138
- - Clear hierarchy: filled primary, outlined secondary, text-only ghost.
139
- - Best for: Standard applications, SaaS, forms.
140
- - Feels: Clear, conventional, accessible.
141
-
142
- **Primary/Secondary only**
143
- - No ghost buttons; all actions have visible backgrounds or borders.
144
- - Best for: Conservative interfaces, enterprise software.
145
- - Feels: Explicit, safe, traditional.
146
-
147
- **Outline-heavy**
148
- - Most buttons are outline/secondary, primary used sparingly.
149
- - Best for: Design-forward products, luxury brands.
150
- - Feels: Refined, minimal, sophisticated.
151
-
152
- **Icon-first**
153
- - Buttons dominated by icons with optional text labels.
154
- - Best for: Toolbars, dense interfaces, mobile apps.
155
- - Feels: Compact, visual, efficient.
156
-
157
- **Text-only**
158
- - No filled buttons; all actions are text links or underlined text.
159
- - Best for: Content sites, blogs, documentation.
160
- - Feels: Minimal, editorial, understated.
161
-
162
- **Size hierarchy**
163
- - Buttons sized by importance: large for primary, small for secondary.
164
- - Best for: Landing pages, marketing, hero CTAs.
165
- - Feels: Directed, scannable, purposeful.
166
-
167
- **Full-width (mobile)**
168
- - Buttons span full container width on small screens.
169
- - Best for: Mobile-first designs, checkout flows.
170
- - Feels: Touch-friendly, accessible, clear.
171
-
172
- ---
173
-
174
- ## Axis 5: Image Treatment
175
-
176
- How images and visual media are presented within the layout.
177
-
178
- ### Options:
179
-
180
- **Full-bleed**
181
- - Images span the full viewport width, edge to edge.
182
- - Best for: Hero sections, immersive storytelling, marketing.
183
- - Feels: Bold, expansive, modern.
184
-
185
- **Contained/inset**
186
- - Images within a max-width container, aligned with text.
187
- - Best for: Articles, documentation, standard layouts.
188
- - Feels: Contained, readable, traditional.
189
-
190
- **Rounded corners**
191
- - Images with border-radius (usually 8px-16px).
192
- - Best for: Card layouts, avatars, modern SaaS.
193
- - Feels: Friendly, modern, approachable.
194
-
195
- **Drop shadow**
196
- - Images with shadow, appearing to float above background.
197
- - Best for: Card UIs, product displays, photography portfolios.
198
- - Feels: Layered, tactile, dimensional.
199
-
200
- **No treatment**
201
- - Images with sharp corners, no shadow, flush with background.
202
- - Best for: Brutalist design, editorial, minimalist layouts.
203
- - Feels: Raw, direct, intentional.
204
-
205
- **Blur/overlay**
206
- - Images with blur, gradient overlay, or darkened treatment.
207
- - Best for: Hero sections, text-over-image, background media.
208
- - Feels: Atmospheric, focused, layered.
209
-
210
- **Masked/cropped**
211
- - Images clipped to specific shapes (circle, angled edge, blob).
212
- - Best for: Avatars, logos, creative layouts.
213
- - Feels: Styled, distinctive, designed.
214
-
215
- ---
216
-
217
- ## Axis 6: Reveal Pattern
218
-
219
- How content and elements appear as the user interacts or scrolls.
220
-
221
- ### Options:
222
-
223
- **Static**
224
- - All content visible immediately on load. No scroll-based animations.
225
- - Best for: Documentation, admin panels, content-heavy sites.
226
- - Feels: Fast, predictable, functional.
227
-
228
- **Scroll-triggered fade**
229
- - Elements fade in as they enter the viewport.
230
- - Best for: Marketing sites, long-form content, storytelling.
231
- - Feels: Progressive, polished, guided.
232
-
233
- **Scroll-triggered slide**
234
- - Elements slide up or in from the side on scroll.
235
- - Best for: Feature sections, case studies, portfolios.
236
- - Feels: Dynamic, engaging, modern.
237
-
238
- **Hover-reveal**
239
- - Content appears or changes on hover (cards, tooltips, previews).
240
- - Best for: Data tables, image grids, dense UIs.
241
- - Feels: Interactive, efficient, responsive.
242
-
243
- **Click-triggered expand**
244
- - Content expands on click (accordions, modals, dropdowns).
245
- - Best for: FAQs, settings, forms, navigation.
246
- - Feels: Controlled, user-directed, organized.
247
-
248
- **Staggered entrance**
249
- - Multiple elements animate in sequence on load or scroll.
250
- - Best for: Hero sections, onboarding, feature showcases.
251
- - Feels: Choreographed, premium, intentional.
252
-
253
- **Parallax**
254
- - Background moves at different speed than foreground.
255
- - Best for: Hero sections, marketing, creative portfolios.
256
- - Feels: Immersive, depth-filled, modern.
257
-
258
- **Skeleton loading**
259
- - Placeholder shapes shown while content loads.
260
- - Best for: Data-heavy apps, dashboards, mobile experiences.
261
- - Feels: Responsive, professional, prepared.
262
-
263
- ---
264
-
265
- ## Using the Fingerprint
266
-
267
- To analyze a page, score each axis:
268
- 1. Identify which option best describes the current implementation.
269
- 2. Note inconsistencies (e.g., centered headings but left-aligned CTAs).
270
- 3. Identify tells: if every axis uses the AI-default option, the design is likely generated.
271
-
272
- **AI-default tendencies:**
273
- - Section headings: centered or top-left without variation
274
- - Body composition: three-column card grids
275
- - Dividers: cards everywhere
276
- - Button voice: primary/secondary/ghost, no size hierarchy
277
- - Images: rounded corners with shadow
278
- - Reveal: scroll-triggered fade on every element
279
-
280
- **Authentic design** intentionally mixes options across axes to serve content and user needs.
@@ -1,53 +0,0 @@
1
- # Theme: Atmospheric
2
-
3
- **Genre:** atmospheric
4
- **Use case:** music, art, creative
5
-
6
- ## Axes
7
-
8
- | Axis | Value |
9
- |------|-------|
10
- | Paper band | dark (0–30% lightness) |
11
- | Display style | display-heavy |
12
- | Accent hue | chromatic-other (multi-hue) |
13
-
14
- ## Token Overrides
15
-
16
- ```css
17
- :root {
18
- --color-background: hsl(260, 20%, 5%);
19
- --color-surface: hsl(260, 20%, 10%);
20
- --color-text: hsl(260, 10%, 90%);
21
- --color-text-muted: hsl(260, 5%, 55%);
22
- --color-accent: hsl(280, 70%, 60%);
23
- --color-accent-hover: hsl(280, 70%, 52%);
24
- --color-accent-2: hsl(340, 60%, 55%);
25
- --font-display: 'Space Grotesk', 'Helvetica Neue', sans-serif;
26
- --font-body: 'Space Grotesk', 'Helvetica Neue', sans-serif;
27
- --radius-sm: 8px;
28
- --radius-md: 12px;
29
- --shadow-sm: 0 2px 4px hsl(260, 20%, 2%);
30
- --shadow-md: 0 8px 24px hsl(260, 20%, 2%);
31
- }
32
- ```
33
-
34
- ## Macrostructure Affinity
35
-
36
- - ✅ Photographic
37
- - ✅ Manifesto
38
- - ✅ Narrative Workflow
39
- - ❌ Index-First (too list-based)
40
- - ❌ Stat-Led (too data-dense)
41
-
42
- ## Anti-Patterns (Atmospheric-specific)
43
-
44
- - ❌ Rigid grid layouts
45
- - ❌ System UI fonts
46
- - ❌ Bright single-accent highlights
47
- - ❌ Card-in-card structures
48
-
49
- ## Voice
50
-
51
- - Poetic, abstract language: "Resonance", "Frequency", "Harmony"
52
- - Short, impactful phrases
53
- - No bullet points in hero sections
@@ -1,52 +0,0 @@
1
- # Theme: Carnival
2
-
3
- **Genre:** playful
4
- **Use case:** Consumer apps, events, marketing
5
-
6
- ## Axes
7
-
8
- | Axis | Value |
9
- |------|-------|
10
- | Paper band | light (>85% lightness) |
11
- | Display style | display-heavy |
12
- | Accent hue | warm (10–60°) |
13
-
14
- ## Token Overrides
15
-
16
- ```css
17
- :root {
18
- --color-background: hsl(0, 0%, 100%);
19
- --color-surface: hsl(45, 100%, 97%);
20
- --color-text: hsl(20, 20%, 15%);
21
- --color-text-muted: hsl(20, 10%, 45%);
22
- --color-accent: hsl(25, 95%, 55%);
23
- --color-accent-hover: hsl(25, 95%, 48%);
24
- --font-display: 'Poppins', sans-serif;
25
- --font-body: 'Poppins', sans-serif;
26
- --radius-sm: 8px;
27
- --radius-md: 16px;
28
- --shadow-sm: 0 2px 4px hsl(25, 80%, 85%);
29
- --shadow-md: 0 8px 24px hsl(25, 80%, 85%);
30
- }
31
- ```
32
-
33
- ## Macrostructure Affinity
34
-
35
- - ✅ Bento Grid
36
- - ✅ Marquee Hero
37
- - ✅ Feature Stack
38
- - ❌ Long Document (too formal)
39
- - ❌ Type Specimen (too restrained)
40
-
41
- ## Anti-Patterns (Carnival-specific)
42
-
43
- - ❌ Flat backgrounds with no depth
44
- - ❌ Monochrome palettes
45
- - ❌ Minimalist whitespace-only layouts
46
- - ❌ System fonts only
47
-
48
- ## Voice
49
-
50
- - Energetic, benefit-driven
51
- - Emoji sparingly (max 1 per section)
52
- - Questions in CTAs: "Ready to play?"
@@ -1,52 +0,0 @@
1
- # Theme: Cobalt
2
-
3
- **Genre:** modern-minimal
4
- **Use case:** SaaS, developer tools, B2B products
5
-
6
- ## Axes
7
-
8
- | Axis | Value |
9
- |------|-------|
10
- | Paper band | mid (30–85% lightness) |
11
- | Display style | geometric-sans |
12
- | Accent hue | cool (200–300°) |
13
-
14
- ## Token Overrides
15
-
16
- ```css
17
- :root {
18
- --color-background: hsl(220, 20%, 98%);
19
- --color-surface: hsl(220, 20%, 100%);
20
- --color-text: hsl(220, 15%, 10%);
21
- --color-text-muted: hsl(220, 10%, 45%);
22
- --color-accent: hsl(220, 80%, 55%);
23
- --color-accent-hover: hsl(220, 80%, 48%);
24
- --font-display: 'Inter', sans-serif;
25
- --font-body: 'Inter', sans-serif;
26
- --radius-sm: 6px;
27
- --radius-md: 8px;
28
- --shadow-sm: 0 1px 2px hsl(220, 15%, 90%);
29
- --shadow-md: 0 4px 12px hsl(220, 15%, 90%);
30
- }
31
- ```
32
-
33
- ## Macrostructure Affinity
34
-
35
- - ✅ Workbench
36
- - ✅ Stat-Led
37
- - ✅ Index-First
38
- - ❌ Manifesto (too editorial)
39
- - ❌ Riso (too analog)
40
-
41
- ## Anti-Patterns (Cobalt-specific)
42
-
43
- - ❌ Purple gradients (`linear-gradient(135deg, #a855f7, #3b82f6)`)
44
- - ❌ Rounded-full buttons with gradient text
45
- - ❌ 3-column icon cards
46
- - ❌ Hero with centered-everything layout
47
-
48
- ## Voice
49
-
50
- - Short labels, sentence case
51
- - Action verbs first: "Get started", "View docs"
52
- - No exclamation marks in headings