ai-developer-skill-os 7.0.2 → 7.5.1

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

@@ -0,0 +1,250 @@
+# UI Copy Rules
+
+Microcopy is the small bits of text that guide, inform, and reassure users. Good copy is invisible; bad copy creates friction.
+
+## Button Labels
+
+**Rule:** Verb-first, 1-3 words. Start with the action the user takes.
+
+**Good:**
+- Save changes
+- Delete account
+- Upload file
+- Send message
+- Continue to payment
+
+**Bad:**
+- Submission (noun, not verb)
+- Click here (generic)
+- Yes / No (without context)
+- Submit your information here (too long)
+
+**Guidelines:**
+- Use imperative verbs: Save, Delete, Upload, Send, Continue
+- Avoid articles: "Save" not "Save the changes"
+- Match case to surrounding UI (usually sentence case)
+- For destructive actions, include the object: "Delete file" not just "Delete"
+
+---
+
+## Error Messages
+
+**Rule:** What happened + how to fix. Two sentences max.
+
+**Formula:**
+1. State the problem clearly
+2. Provide a specific solution
+
+**Good:**
+- "Email address is invalid. Please include an @ symbol."
+- "Password must be at least 8 characters. Try adding a number."
+- "Connection lost. Check your internet and try again."
+
+**Bad:**
+- "Error 500" (technical, unhelpful)
+- "Something went wrong" (vague)
+- "Invalid input" (no fix guidance)
+- "Please try again later" (no context)
+
+**Guidelines:**
+- Never blame the user ("You entered...")
+- Use plain language, not technical jargon
+- Include actionable next steps
+- Keep it concise: 1-2 sentences
+
+---
+
+## Placeholder Text
+
+**Rule:** Example, not instruction. Show what good looks like, don't tell users what to do.
+
+**Good:**
+- "you@example.com" (email input)
+- "12/25/2024" (date input)
+- "Project description..." (textarea)
+- "Search by name or email..." (search input)
+
+**Bad:**
+- "Enter your email address" (instruction, redundant with label)
+- "Type here..." (no helpful example)
+- "Required" (states the obvious)
+- "Your full name" (duplicates label)
+
+**Guidelines:**
+- Use actual example values
+- Show format for structured data (dates, phone numbers)
+- Avoid repeating the label text
+- Placeholder disappears on focus, so it must be self-explanatory
+
+---
+
+## CTAs (Call to Action)
+
+**Rule:** Specific, not generic. Tell users exactly what they get.
+
+**Good:**
+- Start free trial
+- Download whitepaper
+- Book a demo
+- Get started
+- Create account
+- Upgrade to Pro
+
+**Bad:**
+- Submit (generic, no value)
+- Click here (no context)
+- Learn more (vague destination)
+- Sign up (missing context: "Sign up for free")
+- Get started (missing context: what are they starting?)
+
+**Guidelines:**
+- Include the value proposition: "Start free trial" not "Submit"
+- Be specific about the outcome: "Download report" not "Continue"
+- Avoid ambiguity: "Create account" not "Join us"
+- Match CTA intensity to action weight (primary vs secondary)
+
+---
+
+## Ban List
+
+These phrases are forbidden in UI copy:
+
+### Absolutely Banned
+- "Lorem ipsum" — placeholder text in production
+- "Click here" — generic link text
+- "Read more" — lazy, no context
+- "Learn more" — vague, no value proposition
+- "Submit" — generic, no action clarity
+- "John Doe" / "Jane Smith" — fake names
+- "Test User" — lazy placeholder data
+- "Coming soon" — broken promise
+- "Under construction" — unprofessional
+- "TBD" — visible planning state
+- "Error 404" — technical error without guidance
+- "Something went wrong" — unhelpful error
+- "Please try again later" — no context or fix
+
+### Contextual Bans
+- "Welcome to our website" — generic, no value
+- "Thank you for your submission" — assumes success before validation
+- "We value your feedback" — insincere, no action
+- "Powered by AI" — unless AI is a selling point
+- "Best in class" — unsubstantiated claim
+- "Seamless" — meaningless buzzword
+- "Synergy" — meaningless buzzword
+- "Leverage" — pretentious verb
+- "Robust" — vague adjective
+- "Cutting-edge" — cliché
+
+---
+
+## Tone Guidelines
+
+**Voice:** Confident, clear, helpful. Not overly casual or corporate.
+
+**Person:** Second person ("you") for user actions. First person plural ("we") for company statements. Avoid third person.
+
+**Length:** Short for actions, longer for explanations. Buttons: 1-3 words. Headlines: 2-8 words. Body: 1-3 sentences.
+
+**Jargon:** Avoid unless audience is technical. If jargon is necessary, define it on first use.
+
+**Humor:** Use sparingly. Only in error states, empty states, or onboarding. Never in critical flows or legal text.
+
+---
+
+## Accessibility Copy
+
+**Alt Text:** Describe the image content, not "image of" or "photo of."
+- Good: "Bar chart showing 40% increase in sales"
+- Bad: "Image" or "Chart"
+
+**ARIA Labels:** Be specific and contextual.
+- Good: `aria-label="Close dialog"`
+- Bad: `aria-label="Button"`
+
+**Link Text:** Descriptive, not generic.
+- Good: "View pricing plans"
+- Bad: "Click here"
+
+**Form Labels:** Clear and concise.
+- Good: "Email address"
+- Bad: "Please enter your email address in the field below"
+
+---
+
+## Validation States
+
+**Success:**
+- "Changes saved"
+- "Account created"
+- "File uploaded"
+
+**Error:**
+- "Invalid email address. Example: you@company.com"
+- "Password must include a number and special character"
+- "Connection failed. Please try again."
+
+**Warning:**
+- "You have unsaved changes. Leave without saving?"
+- "Your session expires in 5 minutes"
+
+**Info:**
+- "New features available. Refresh to see updates."
+- "Your trial ends in 3 days"
+
+---
+
+## Empty States
+
+**No Data:**
+- "No projects yet. Create your first project to get started."
+- "No messages. Start a conversation with your team."
+
+**No Search Results:**
+- "No results for 'query'. Try different keywords or clear filters."
+- "We couldn't find anything matching your search."
+
+**Error States:**
+- "Something went wrong on our end. Refresh the page or contact support if it persists."
+- "Unable to load data. Check your connection and try again."
+
+---
+
+## Confirmation Messages
+
+**Destructive Actions:**
+- "Are you sure you want to delete this project? This cannot be undone."
+- "Deactivate account? You will lose access to all projects."
+
+**Success Actions:**
+- "Account created! Check your email to verify."
+- "File uploaded successfully."
+
+**Conditional Actions:**
+- "You have unsaved changes. Save before leaving?"
+- "Discard draft? Your changes will be lost."
+
+---
+
+## Legal & Compliance
+
+**Privacy:**
+- "We use cookies to improve your experience. [Accept] [Settings]"
+- "By signing up, you agree to our Terms and Privacy Policy."
+
+**Consent:**
+- "Send me emails with product updates and offers." (opt-in)
+- "I agree to the Terms of Service." (required)
+
+**Age:**
+- "You must be 18 or older to create an account."
+
+---
+
+## Measurement
+
+Copy is done when:
+- Users complete tasks without reading the full text
+- Error messages reduce support tickets
+- CTAs have measurable click-through rates
+- No placeholder text remains in production

package/.agents/skills/qk-ui-builder/references/interaction-and-states.md

@@ -0,0 +1,115 @@
+# Interaction & States
+
+Foundational rules for interactive element states. Every interactive control must define a complete, accessible state set — not just default and hover.
+
+## The 8 States
+
+Every interactive component should account for:
+
+1. **default** — resting, ready to interact.
+2. **hover** — pointer is over (pointer devices only).
+3. **focus** — keyboard / programmatic focus.
+4. **active** — being pressed/clicked.
+5. **disabled** — not interactive, clearly shown.
+6. **loading** — work in progress, feedback given.
+7. **error** — invalid input or failed action, with message.
+8. **success** — completed action, confirmed.
+
+```css
+.btn { /* default */ }
+.btn:hover { background: var(--color-accent-hover); }
+.btn:focus-visible { /* focus ring */ }
+.btn:active { transform: translateY(1px); }
+.btn:disabled { /* disabled */ }
+```
+
+## Focus: Visible Ring
+
+Always provide a visible focus indicator. **Never** use `outline: none` without a replacement. Use `:focus-visible` so mouse users aren't spammed but keyboard users are clearly shown.
+
+```css
+.btn:focus { outline: none; }              /* remove default */
+.btn:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+  /* or a ring via box-shadow */
+  box-shadow: 0 0 0 3px oklch(55% 0.16 250 / 0.4);
+}
+```
+
+The focus ring must meet 3:1 contrast against adjacent colors.
+
+## Disabled: Not Opacity-Only
+
+A disabled control must combine **reduced opacity** with **`cursor: not-allowed`** and remain non-interactive. Opacity alone is insufficient and confusing.
+
+```css
+.btn:disabled,
+.btn[aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;   /* or guard in JS */
+}
+```
+
+Also dim/hide associated helper text appropriately, and keep the control in the a11y tree (use `aria-disabled` rather than removing the element).
+
+## Loading: Skeleton or Spinner
+
+While awaiting data or an action, show a **skeleton** or **spinner** — never bare "Loading..." text.
+
+```css
+/* Skeleton shimmer */
+.skeleton {
+  background: linear-gradient(90deg, var(--color-surface) 25%, var(--color-border) 50%, var(--color-surface) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.2s ease-in-out infinite;
+  border-radius: 6px;
+}
+@keyframes shimmer { to { background-position: -200% 0; } }
+```
+
+```html
+<!-- Button loading: keep label, add spinner, disable -->
+<button class="btn" disabled aria-busy="true">
+  <span class="spinner" aria-hidden="true"></span> Saving
+</button>
+```
+
+For data regions, render skeleton placeholders preserving layout to avoid shift (see motion.md: no layout animation).
+
+## Error: Clear Message + Retry
+
+Error states must surface a **human-readable message** and, when recoverable, a **retry / fix action**.
+
+```html
+<div class="field error">
+  <label for="email">Email</label>
+  <input id="email" aria-invalid="true" aria-describedby="email-err" />
+  <p id="email-err" class="error-msg">Enter a valid email like name@example.com.</p>
+</div>
+```
+
+```css
+.field.error input { border-color: var(--color-error); }
+.error-msg { color: var(--color-error); font-size: var(--text-sm); }
+```
+
+Convey error with more than color (icon + text) for accessibility.
+
+## Success
+
+Confirm completed actions with a brief, non-blocking indicator. Keep it subtle and auto-dismiss where appropriate.
+
+```css
+.toast.success { background: var(--color-success); color: oklch(99% 0 0); }
+```
+
+## Practical Checklist
+
+- [ ] All 8 states defined per interactive component.
+- [ ] Focus uses `:focus-visible` ring, no naked `outline: none`.
+- [ ] Disabled = opacity + `cursor: not-allowed` + inert.
+- [ ] Loading uses skeleton/spinner, not text-only.
+- [ ] Error shows message + retry and isn't color-only.
+- [ ] Success confirmation is present and subtle.

package/.agents/skills/qk-ui-builder/references/layout-and-space.md

@@ -0,0 +1,111 @@
+# Layout & Space
+
+Foundational rules for grids, spacing rhythm, and structural layout. The goal is predictable, maintainable layouts built from flow and flex/grid — never magic numbers or absolute offsets.
+
+## 4pt Base Spacing Scale
+
+All spacing derives from a **4px base**. Use only these steps. Do not use arbitrary values like `7px`, `13px`, `23px`.
+
+```
+4px    --space-1   tight (icon gaps, inline)
+8px    --space-2   small (label→control)
+12px   --space-3   control padding, list gaps
+16px   --space-4   default gap between elements
+20px   --space-5   card internal padding
+24px   --space-6   section internal padding
+32px   --space-8   gap between related blocks
+40px   --space-10  large block separation
+48px   --space-12  section separation
+64px   --space-16  major section separation
+```
+
+```css
+:root {
+  --space-1: 0.25rem;  --space-2: 0.5rem;   --space-3: 0.75rem;
+  --space-4: 1rem;     --space-5: 1.25rem;  --space-6: 1.5rem;
+  --space-8: 2rem;     --space-10: 2.5rem;  --space-12: 3rem;
+  --space-16: 4rem;
+}
+```
+
+## Grid & Flexbox (NO Absolute Positioning)
+
+Lay out with **CSS Grid** and **Flexbox**. Do not use `position: absolute` / `position: fixed` for structural layout (overlays, tooltips, and sticky headers are the only exceptions, and they must be scoped).
+
+```css
+/* Page shell */
+.container {
+  width: 100%;
+  max-width: 1200px;
+  margin-inline: auto;
+  padding-inline: var(--space-6);
+}
+
+/* Responsive card grid */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(0, 1fr));
+  gap: var(--space-6);
+}
+```
+
+```css
+/* Inline control row */
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+```
+
+## Minimum Whitespace Between Sections
+
+Maintain **at least 16px** (`--space-4`) of separation between distinct sections; prefer `--space-12`/`--space-16` between major page sections.
+
+```css
+section + section { margin-top: var(--space-12); }
+.card { padding: var(--space-5); }
+.stack > * + * { margin-top: var(--space-4); }  /* vertical rhythm */
+```
+
+## Max Content Width
+
+- **Desktop:** cap content at **1200px**, centered.
+- **Mobile:** content is **100%** width (minus safe padding). Never force desktop widths onto small screens.
+
+```css
+.container { max-width: 1200px; width: 100%; }
+@media (max-width: 640px) {
+  .container { max-width: 100%; padding-inline: var(--space-4); }
+}
+```
+
+## No "Margin: Auto Soup"
+
+Do not scatter `margin: auto` to push elements around. Centralize alignment through flex/grid `justify-content` / `align-items` / `gap`. `margin-inline: auto` is permitted **only** for the top-level `.container` centering.
+
+```css
+/* Bad: fighting the layout with auto margins */
+.sidebar { margin-left: auto; margin-right: 12px; }
+
+/* Good: let the grid place it */
+.layout { display: grid; grid-template-columns: 240px 1fr; gap: var(--space-8); }
+```
+
+## Stack Utility Pattern
+
+Prefer an explicit vertical stack helper over chained margins.
+
+```css
+.stack { display: flex; flex-direction: column; }
+.stack-4 > * + * { margin-top: var(--space-4); }
+.stack-6 > * + * { margin-top: var(--space-6); }
+```
+
+## Practical Checklist
+
+- [ ] All spacing uses the 4pt scale tokens.
+- [ ] Layout via grid/flex; no absolute positioning for structure.
+- [ ] ≥16px between sections; major sections use larger gaps.
+- [ ] Desktop max 1200px, mobile 100%.
+- [ ] No scattered `margin: auto` hacks.

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

@@ -0,0 +1,48 @@
+# 01 — Bento Grid
+
+**Fingerprint:** asymmetric grid, mixed card sizes, icon-led sections, no equal-height rows.
+
+## Structure
+
+```
++-------+-------+
+|       |       |
+|  A    |   B   |
+|       |       |
++---+---+-------+
+|   C   |   D   |
++---+---+-------+
+|        E       |
++-----------------+
+```
+
+## Rules
+
+- Card A: hero metric or primary action (spans 2 cols on desktop)
+- Card B: secondary metric or visual
+- Card C: tertiary content
+- Card D: tertiary content
+- Card E: full-width footer or CTA
+
+## Typography
+
+- Heading: display style from theme
+- Body: body font from theme
+- Metric numbers: tabular-nums, display weight
+
+## Spacing
+
+- Grid gap: `--space-6` (24px)
+- Card padding: `--space-5` (20px)
+- Inner padding: `--space-4` (16px)
+
+## Anti-Patterns
+
+- ❌ 3 equal columns
+- ❌ Card-in-card
+- ❌ All cards same height
+
+## Theme Affinity
+
+- ✅ Cobalt, Carnival, Lumen
+- ⚠️ Hum (needs more whitespace)

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

@@ -0,0 +1,50 @@
+# 02 — Long Document
+
+**Fingerprint:** single-column long scroll, generous line length control, anchored section nav, docs/blogs.
+
+## Structure
+
+```
++---------------------+
+|   Sticky Title Bar  |
++------+--------------+
+|  TOC |   Content    |
+|  Nav |   (headings, |
+|      |    paragraphs|
+|      |    code, img)|
+|      |              |
++------+--------------+
+|   Footer / Pager    |
++---------------------+
+```
+
+## Rules
+
+- Content column: max-width 70ch, centered within reading area
+- TOC: sticky, scrollspy active section highlight
+- Headings: sequential h2/h3 hierarchy, no skipped levels
+- Code blocks: full-width within column, syntax highlighted
+- Support reading progress bar at top
+
+## Typography
+
+- Heading: display or editorial serif from theme
+- Body: body font, 18px base for reading comfort
+- Code: mono, 14px
+
+## Spacing
+
+- Content padding: `--space-8` (32px)
+- Paragraph spacing: `--space-4` (16px)
+- Section gap: `--space-10` (40px)
+
+## Anti-Patterns
+
+- ❌ Multi-column body text
+- ❌ Full-bleed images breaking reading rhythm
+- ❌ Missing table of contents on long pages
+
+## Theme Affinity
+
+- ✅ Hum, Lumen
+- ⚠️ Carnival (needs restraint on decoration)

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

@@ -0,0 +1,51 @@
+# 03 — Marquee Hero
+
+**Fingerprint:** full-width hero, motion/marquee or autoplay carousel, high-contrast headline, marketing.
+
+## Structure
+
+```
++---------------------------+
+|   Nav (transparent)       |
++---------------------------+
+|                           |
+|   BIG HEADLINE            |
+|   subhead + CTA           |
+|                           |
+|  [==== marquee =====]     |
+|  [ scroll / carousel ]    |
++---------------------------+
+|   Trust logos / stats     |
++---------------------------+
+```
+
+## Rules
+
+- Hero: full viewport-ish height (min 70vh) on desktop
+- Marquee: infinite horizontal scroll or autoplay carousel, pausable on hover
+- Headline: one dominant message, max 2 lines
+- CTA: primary action, high contrast against hero bg
+- Respect `prefers-reduced-motion` (disable auto-animation)
+
+## Typography
+
+- Heading: display style, largest scale in system
+- Subhead: body or medium weight, muted
+- Marquee text: mono or uppercase label
+
+## Spacing
+
+- Hero padding: `--space-10` (40px)
+- Marquee height: 64px
+- CTA margin-top: `--space-6` (24px)
+
+## Anti-Patterns
+
+- ❌ Multiple competing CTAs
+- ❌ Autoplay that can't be paused
+- ❌ Hero text low contrast over image
+
+## Theme Affinity
+
+- ✅ Carnival, Cobalt
+- ❌ Hum (too understated for hero theater)

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

@@ -0,0 +1,49 @@
+# 04 — Stat-Led
+
+**Fingerprint:** metrics-first, big numbers above the fold, analytics dashboards, KPI summaries.
+
+## Structure
+
+```
++---------------------------+
+|   Title + Date Range      |
++------+------+------+------+
+|  KPI |  KPI |  KPI |  KPI |
+|  123 |  45% |  8.2 |  99  |
++------+------+------+------+
+|   Primary Chart / Table   |
+|   (trend, breakdown)      |
++---------------------------+
+|   Secondary charts row    |
++---------------------------+
+```
+
+## Rules
+
+- KPI row: 4 cards on desktop, 2 on tablet, 1 on mobile
+- Each KPI: value (display), label (muted), delta (up/down color)
+- Primary chart: spans full width below KPIs
+- Delta: green for positive, red for negative, semantic colors only
+
+## Typography
+
+- Heading: display weight, tabular-nums for values
+- KPI value: largest scale, tabular-nums
+- Labels: 13px muted uppercase
+
+## Spacing
+
+- KPI gap: `--space-4` (16px)
+- Card padding: `--space-5` (20px)
+- Section gap: `--space-6` (24px)
+
+## Anti-Patterns
+
+- ❌ Decorative number animation without context
+- ❌ Mixing units without labels
+- ❌ Charts without axis or legend
+
+## Theme Affinity
+
+- ✅ Cobalt, Lumen
+- ⚠️ Hum (needs stronger number contrast)