ai-developer-skill-os 7.5.0 → 8.1.4

package/.agents/skills/qk-ui-builder/references/macrostructures/20-ecosystem-index.md

@@ -0,0 +1,48 @@
+# 20 — Ecosystem Index
+
+**Fingerprint:** integrations, partners, plugins directory, logo grid with search.
+
+## Structure
+
+```
++---------------------------+
+|   Search + category tabs  |
++------+--------------------+
+| Cat  |  [logo][logo]      |
+| nav  |  [logo][logo]      |
+|      |  [logo][logo]      |
++------+--------------------+
+|   Featured / popular      |
++---------------------------+
+```
+
+## Rules
+
+- Logo grid: uniform tile size, grayscale → color on hover
+- Categories: tab or sidebar filter
+- Search: matches name and tags
+- Featured row: highlights top integrations
+- Each tile links to detail/install
+
+## Typography
+
+- Heading: display for directory title
+- Tile name: 13px medium under logo
+- Category: 14px, active state bold
+
+## Spacing
+
+- Grid gap: `--space-4` (16px)
+- Tile padding: `--space-4` (16px)
+- Cat nav width: 200px
+
+## Anti-Patterns
+
+- ❌ Logos at inconsistent sizes
+- ❌ No search on large directories
+- ❌ Missing category organization
+
+## Theme Affinity
+
+- ✅ Cobalt, Lumen
+- ⚠️ Carnival (logos need neutral bg)

package/.agents/skills/qk-ui-builder/references/macrostructures/21-component-playground.md

@@ -0,0 +1,45 @@
+# 21 — Component Playground
+
+**Fingerprint:** tabbed or sidebar navigation, live preview, code snippet, copy button.
+
+## Structure
+
+```
++---------+------------------+
+| Nav     |   Preview        |
+| (tabs)  |   (live render)  |
+|         |                  |
++---------+------------------+
+| Code Snippet          [Copy] |
++-----------------------------+
+```
+
+## Rules
+
+- Nav: vertical tabs or horizontal pills
+- Preview: sandboxed iframe or isolated render
+- Code: syntax highlighted, copy button
+- Tabs: at least 3 examples per component
+
+## Typography
+
+- Heading: display style
+- Code: mono, 13px
+- Body: body font, 14px
+
+## Spacing
+
+- Nav width: 200px
+- Preview padding: `--space-6`
+- Code padding: `--space-4`
+
+## Anti-Patterns
+
+- ❌ Preview that doesn't update on tab switch
+- ❌ Code snippets without syntax highlighting
+- ❌ Missing copy button
+
+## Theme Affinity
+
+- ✅ Lumen, Cobalt
+- ❌ Hum, Carnival (too decorative)

package/.agents/skills/qk-ui-builder/references/macrostructures.md

@@ -0,0 +1,38 @@
+# Macrostructure Index
+
+Load this index first, then load ONLY the chosen macrostructure file.
+
+| ID | Name | Best For |
+|----|------|----------|
+| 01 | Bento Grid | Feature dashboards, app shells |
+| 02 | Long Document | Docs, blogs, legal |
+| 03 | Marquee Hero | Marketing, campaigns |
+| 04 | Stat-Led | Analytics, metrics |
+| 05 | Workbench | Tools, editors, IDEs |
+| 06 | Conversational FAQ | Support, onboarding |
+| 07 | Manifesto | Brand, about, careers |
+| 08 | Photographic | Portfolios, travel |
+| 09 | Quote-Led | Testimonials, editorial |
+| 10 | Specimen | Design systems, pattern libraries |
+| 11 | Catalogue | E-commerce, listings |
+| 12 | Letter | Newsletters, personal |
+| 13 | Index-First | Wikis, knowledge bases |
+| 14 | Narrative Workflow | Onboarding, wizards |
+| 15 | Split Studio | Comparison, before/after |
+| 16 | Feature Stack | Product pages, SaaS |
+| 17 | Type Specimen | Typography showcases |
+| 18 | Portfolio Grid | Creative portfolios |
+| 19 | Map/Diagram | Architecture, org charts |
+| 20 | Ecosystem Index | Integrations, partners |
+| 21 | Component Playground | UI libraries, docs |
+
+## Load Rule
+
+1. Read this index only
+2. Pick ONE macrostructure based on brief
+3. Load ONLY `references/macrostructures/XX-<name>.md`
+4. Never load all 21 files
+
+## Diversification Rule
+
+No two consecutive builds in the same project may share the same macrostructure.

package/.agents/skills/qk-ui-builder/references/motion.md

@@ -0,0 +1,95 @@
+# Motion
+
+Foundational rules for animation. Motion must feel intentional, fast, and accessible — never decorative bounce or layout-shifting transitions.
+
+## Duration Scale
+
+Use only these durations. Do not invent values like 250ms or 420ms.
+
+```
+100ms   micro (hover, toggle, color)
+150ms   quick state change
+200ms   default UI transition
+300ms   panel / menu enter-exit
+500ms   large surface / page-level
+```
+
+```css
+:root {
+  --dur-1: 100ms;
+  --dur-2: 150ms;
+  --dur-3: 200ms;
+  --dur-4: 300ms;
+  --dur-5: 500ms;
+}
+```
+
+## Easing
+
+Match easing to the direction of motion:
+
+| Phase | Easing |
+| --- | --- |
+| Enter (appear) | `ease-out` |
+| Exit (disappear) | `ease-in` |
+| Continuous transition | `ease-in-out` |
+
+```css
+.card { transition: transform var(--dur-3) ease-out, opacity var(--dur-3) ease-out; }
+.menu-close { transition: opacity var(--dur-2) ease-in; }
+.theme-switch { transition: background-color var(--dur-4) ease-in-out; }
+```
+
+## Ban List
+
+- **No bounce / overshoot easing.** Never use `cubic-bezier(0.68, -0.55, 0.265, 1.55)` or any springy curve for UI elements. It reads as unprofessional and slows perceived performance.
+
+```css
+/* BANNED */
+transition: all 300ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
+```
+
+- **No infinite decorative animations** (marquee, pulsing glow) unless the user explicitly asks.
+- **No `transition: all`** — name the specific properties.
+
+## prefers-reduced-motion
+
+Respect the user's OS setting. Under `reduce`, disable transforms/opacity animations and drop durations to **0ms**.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Apply this once globally; do not re-introduce motion for individual elements.
+
+## No Animating Layout Properties
+
+Never animate `width`, `height`, `padding`, `margin`, or `top/left`. These trigger layout/paint reflows and jank. Animate only **transform** and **opacity** (compositor-only).
+
+```css
+/* Good: animate transform/opacity only */
+.modal { opacity: 0; transform: translateY(8px); transition: opacity var(--dur-3) ease-out, transform var(--dur-3) ease-out; }
+.modal.open { opacity: 1; transform: translateY(0); }
+
+/* Bad: animates layout */
+.panel { transition: height 300ms ease; }   /* reflows, janky */
+```
+
+For elements that change size (expand/collapse), use `transform: scaleY()` or animate `grid-template-rows: 0fr → 1fr` instead of height.
+
+## Practical Checklist
+
+- [ ] Durations only from the 5-step scale.
+- [ ] ease-out enter / ease-in exit / ease-in-out transition.
+- [ ] No bounce bezier, no `transition: all`, no infinite decoration.
+- [ ] `prefers-reduced-motion` zeroes all motion.
+- [ ] Only `transform` / `opacity` are animated.

package/.agents/skills/qk-ui-builder/references/responsive.md

@@ -0,0 +1,115 @@
+# Responsive
+
+Foundational rules for building layouts that adapt across screen sizes without breaking, horizontal scroll, or un-tappable controls.
+
+## Breakpoints
+
+Use this standard scale. Build **mobile-first** (base styles = small screens, then enhance upward).
+
+```
+sm   640px
+md   768px
+lg   1024px
+xl   1280px
+```
+
+```css
+/* mobile-first: base = mobile, then min-width queries */
+@media (min-width: 640px) { /* sm */ }
+@media (min-width: 768px) { /* md */ }
+@media (min-width: 1024px) { /* lg */ }
+@media (min-width: 1280px) { /* xl */ }
+```
+
+## Mobile: Stack Vertically
+
+On small screens, lay content out in a **single vertical column**. Never require horizontal scrolling for core content.
+
+```css
+.layout {
+  display: grid;
+  grid-template-columns: 1fr;          /* stacked on mobile */
+  gap: var(--space-6);
+}
+@media (min-width: 768px) {
+  .layout { grid-template-columns: 240px 1fr; }  /* sidebar + content */
+}
+```
+
+```css
+/* Guard against accidental horizontal overflow */
+html, body { overflow-x: hidden; max-width: 100%; }
+img, video, table { max-width: 100%; }
+```
+
+## Touch Targets: Min 44×44px
+
+Every interactive control must be at least **44×44px** to be comfortably tappable. Don't let padding shrink the hit area below this.
+
+```css
+.btn, .nav-link, .icon-button {
+  min-height: 44px;
+  min-width: 44px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--space-2) var(--space-4);
+}
+```
+
+## Fluid Typography with clamp()
+
+Use `clamp()` for headings/hero text so type scales smoothly between breakpoints without abrupt jumps.
+
+```css
+h1 {
+  /* min 32px, preferred 5vw, max 64px */
+  font-size: clamp(2rem, 5vw, 4rem);   /* 32px → 64px */
+}
+h2 {
+  font-size: clamp(1.5rem, 3vw, 2rem); /* 24px → 32px */
+}
+```
+
+Keep body text near `--text-base` (16px) for readability; reserve clamp() for display sizes.
+
+## Image Grids: minmax(0, 1fr)
+
+For responsive image/card grids, use `minmax(0, 1fr)` so items shrink properly and never overflow. Fixed-width columns break on mobile.
+
+```css
+.gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(0, 1fr));
+  gap: var(--space-4);
+}
+@media (min-width: 640px)  { .gallery { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (min-width: 1024px) { .gallery { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
+```
+
+```css
+.gallery img { width: 100%; height: 100%; object-fit: cover; display: block; }
+```
+
+## Desktop Container
+
+Cap desktop content at 1200px and center (see layout-and-space.md). On mobile it becomes 100% width with safe padding.
+
+```css
+.container {
+  width: 100%;
+  max-width: 1200px;
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+@media (min-width: 768px) { .container { padding-inline: var(--space-6); } }
+```
+
+## Practical Checklist
+
+- [ ] Mobile-first with sm/md/lg/xl breakpoints.
+- [ ] Mobile stacks vertically; no horizontal scroll.
+- [ ] All tap targets ≥ 44×44px.
+- [ ] Display type uses `clamp()` for fluid scaling.
+- [ ] Image/card grids use `minmax(0, 1fr)`.
+- [ ] Desktop content capped at 1200px.

package/.agents/skills/qk-ui-builder/references/slop-test.md

@@ -0,0 +1,135 @@
+# Slop Test — 58 Anti-Slop Gates
+
+Run this checklist AFTER every build. Every answer must be **NO**.
+
+## Pre-Emit Self-Critique (Score 1–5 on each axis)
+
+| Axis | Question | Score |
+|------|----------|-------|
+| Philosophy | Does this serve the user, or just show off? | ___ |
+| Hierarchy | Is the visual hierarchy clear within 3 seconds? | ___ |
+| Execution | Is every interaction polished, not just present? | ___ |
+| Specificity | Does this feel made for this brief, not generic? | ___ |
+| Restraint | Could anything be removed without losing meaning? | ___ |
+| Variety | Would a second page feel different, not a color-swap? | ___ |
+
+**Rule:** Any axis < 3 → revise before continuing.
+
+---
+
+## Visual Gates (1–7)
+
+- [ ] **1.** No banned fonts: Inter, Roboto, Arial, system-ui as primary identity font
+- [ ] **2.** No purple-blue gradients (`linear-gradient(135deg, #a855f7, #3b82f6)`)
+- [ ] **3.** No gradient text (`background-clip: text`)
+- [ ] **4.** No 3-equal-column icon cards
+- [ ] **5.** No card-in-card layouts (card inside card inside card)
+- [ ] **6.** No side-stripe cards (left border accent only)
+- [ ] **7.** No centred-everything hero (all content centered with max-width)
+
+## Structural Gates (8–9)
+
+- [ ] **8.** No AI-template reuse (same fingerprint as prior build in project)
+- [ ] **9.** Sections separated by more than whitespace (use dividers, headings, or background changes)
+
+## Microinteraction Gates (10–19)
+
+- [ ] **10.** No `transition-all` on interactive elements
+- [ ] **11.** No `hover:scale-105` without context
+- [ ] **12.** No `cubic-bezier(0.68, -0.55, 0.265, 1.55)` (bounce easing)
+- [ ] **13.** No more than 2 hover effects per element
+- [ ] **14.** No animating layout props (width, height, padding)
+- [ ] **15.** No animated focus ring (focus state must be instant)
+- [ ] **16.** No celebratory toasts/confetti on load
+- [ ] **17.** No equal hover/focus tooltip delay
+- [ ] **18.** No auto-rotating carousel without pause-on-hover
+- [ ] **19.** No placeholder names (John Doe, Jane Smith, etc.)
+
+## Variety Gates (20–21)
+
+- [ ] **20.** Macrostructure stamp present in CSS comment
+- [ ] **21.** Not Specimen fall-through (every brief needs a real macrostructure)
+
+## Implementation Gates (22–27)
+
+- [ ] **22.** No zero-chroma neutrals (`hsl(0, 0%, X%)` as primary)
+- [ ] **23.** Accent color footprint < 5% of viewport
+- [ ] **24.** Spacing follows scale (no off-scale values like 13px, 27px)
+- [ ] **25.** Prose measure between 45–75ch
+- [ ] **26.** All interactive elements have focus, active, disabled states
+- [ ] **27.** Motion has `prefers-reduced-motion` fallback
+
+## Hero Enrichment Gates (28–31)
+
+- [ ] **28.** No autoplay-with-sound video
+- [ ] **29.** No over-busy abstract background (more than 2 visual layers)
+- [ ] **30.** No mixed icon libraries or emoji icons in professional UI
+- [ ] **31.** No Lottie animation when CSS transition would suffice
+
+## Diversification Gates (32–33)
+
+- [ ] **32.** Same archetype not repeated without varied knob (size, color, layout)
+- [ ] **33.** Decorative SVG/figure has `aria-hidden="true"` or meaningful `role`
+
+## Layout-Safety Gates (34–36)
+
+- [ ] **34.** No horizontal scroll (`overflow-x: clip` on html+body)
+- [ ] **35.** No misplaced decorative text effects (text-shadow as decoration)
+- [ ] **36.** Interactive bars centered (not left-aligned with unbalanced whitespace)
+
+## Typography Gates (37–38a)
+
+- [ ] **37.** No more than 3 font families
+- [ ] **38.** No outlier font used in > 2 slots
+- [ ] **38a.** No italic headers (headers use weight, not style)
+
+## Input-State Gates (39)
+
+- [ ] **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
+
+## Contrast Gates (40–41)
+
+- [ ] **40.** WCAG 2.1 AA contrast (4.5:1 for text, 3:1 for large text)
+- [ ] **41.** No ink-on-ink (same color for text and background with only opacity difference)
+
+## Chrome Gates (42–45)
+
+- [ ] **42.** No AI nav fingerprint (centered logo, pill nav, gradient CTA)
+- [ ] **43.** No AI footer fingerprint (3 columns: Product, Company, Legal, social icons row)
+- [ ] **44.** Hero fits viewport (no excessive height)
+- [ ] **45.** Decorative elements have purpose or removed
+
+## Honest Copy Gate (46)
+
+- [ ] **46.** No invented metrics ("10x faster", "100% secure", "trusted by 10,000+")
+
+## Re-Drawn Chrome Gate (47)
+
+- [ ] **47.** No fake browser/phone/code/IDE chrome unless building a mockup tool
+
+## Token Discipline Gate (48)
+
+- [ ] **48.** No mid-render token improvisation (all values from DESIGN.md or theme)
+
+## Responsive Clickable Gate (49)
+
+- [ ] **49.** No two-line clickable text (buttons/links max 1 line)
+
+## Mobile Non-Negotiables (50–57)
+
+- [ ] **50.** Image grids use `minmax(0, 1fr)` not fixed widths
+- [ ] **51.** Long words wrap (`overflow-wrap: break-word`)
+- [ ] **52.** Mobile section-head collapse (h1 reduces size on small screens)
+- [ ] **53.** Radio-tab scroll-jump prevented
+- [ ] **54.** No tag-beside-heading on mobile (stack vertically)
+- [ ] **55.** All-caps line-height collision avoided (`letter-spacing: 0.05em` minimum)
+- [ ] **56.** Sticky header doesn't bleed into content
+- [ ] **57.** Studied DNA not discarded (if `--study` was used, its output must be referenced)
+
+---
+
+## Final Gate
+
+- [ ] **58.** Pre-emit self-critique average ≥ 3.0 on all 6 axes
+
+**Pass condition:** All 58 gates = NO. Any YES → fix before shipping.