ai-developer-skill-os 9.3.1 → 10.2.0

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

@@ -1,115 +0,0 @@
-# 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

@@ -1,111 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-# 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

@@ -1,51 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-# 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)

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

@@ -1,44 +0,0 @@
-# 05 — Workbench
-
-**Fingerprint:** sidebar + main content, tool-first, dense information, keyboard-centric.
-
-## Structure
-
-```
-+---------+------------------+
-| Sidebar |   Main Content   |
-| Nav     |                  |
-| Tools   |   Editor/Canvas  |
-| Status  |                  |
-+---------+------------------+
-```
-
-## Rules
-
-- Sidebar width: 260px fixed on desktop, collapsible on mobile
-- Main content: fluid, max-width 1200px
-- Toolbar: sticky top of main content
-- Status bar: sticky bottom of main content
-
-## Typography
-
-- Heading: mono (Lumen) or geometric-sans (Cobalt)
-- Body: body font, 14px base
-- Code: mono, 13px
-
-## Spacing
-
-- Sidebar padding: `--space-4`
-- Main padding: `--space-6`
-- Toolbar height: 48px
-
-## Anti-Patterns
-
-- ❌ Centered hero in workbench
-- ❌ Large decorative images
-- ❌ Excessive whitespace
-
-## Theme Affinity
-
-- ✅ Lumen, Cobalt
-- ❌ Carnival (too playful)

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

@@ -1,50 +0,0 @@
-# 06 — Conversational FAQ
-
-**Fingerprint:** chat-like Q&A, message bubbles, support docs, expandable answers.
-
-## Structure
-
-```
-+---------------------------+
-|   Search / Ask box        |
-+------+--------------------+
-|  Q   |                    |
-|  [bubble]  A (expand)     |
-|       |   ----            |
-|  Q    |  A                |
-|  [bubble]                 |
-+------+--------------------+
-|   Contact / escalate      |
-+---------------------------+
-```
-
-## Rules
-
-- Questions: left-aligned or avatar-led bubbles
-- Answers: expandable accordion or inline below question
-- Search: filters questions live as user types
-- Support escalation: visible link when answer insufficient
-- Grouped by topic/category when many questions
-
-## Typography
-
-- Heading: display for section title
-- Question: medium weight, 15px
-- Answer: body font, 14px, muted
-
-## Spacing
-
-- Bubble padding: `--space-4` (16px)
-- Bubble gap: `--space-3` (12px)
-- Search margin-bottom: `--space-6` (24px)
-
-## Anti-Patterns
-
-- ❌ Walls of ungrouped questions
-- ❌ Answers that don't match the question
-- ❌ No search on large FAQ sets
-
-## Theme Affinity
-
-- ✅ Hum, Lumen
-- ⚠️ Carnival (keep bubble decoration minimal)

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

@@ -1,51 +0,0 @@
-# 07 — Manifesto
-
-**Fingerprint:** brand statement, large editorial type, about pages, bold declarative copy.
-
-## Structure
-
-```
-+---------------------------+
-|                           |
-|   BIG STATEMENT           |
-|   (one sentence, huge)    |
-|                           |
-+------+--------------------+
-|  Lead |  Supporting       |
-|  para |  paragraphs,      |
-|       |  values list      |
-+---------------------------+
-|   Sign-off / signature    |
-+---------------------------+
-```
-
-## Rules
-
-- Opening statement: single declarative sentence, largest type scale
-- Body: 1 lead paragraph + supporting points
-- Values: short bullet or numbered list, not a table
-- Generous negative space around the statement
-- One signature/sign-off at the end
-
-## Typography
-
-- Heading: editorial display or serif, very large
-- Lead: body font, 20px, slightly muted
-- Values: medium weight list items
-
-## Spacing
-
-- Statement padding: `--space-12` (48px)
-- Lead margin: `--space-8` (32px)
-- Values gap: `--space-4` (16px)
-
-## Anti-Patterns
-
-- ❌ Multiple equal-weight statements
-- ❌ Cluttered hero with images
-- ❌ Corporate buzzword soup without a point
-
-## Theme Affinity
-
-- ✅ Hum, Carnival
-- ⚠️ Lumen (can feel too technical)

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

@@ -1,50 +0,0 @@
-# 08 — Photographic
-
-**Fingerprint:** image-heavy, full-bleed photos, portfolios, travel, minimal chrome.
-
-## Structure
-
-```
-+---------------------------+
-|   Minimal Nav (overlay)   |
-+---------------------------+
-|                           |
-|   [ FULL-BLEED IMAGE ]    |
-|                           |
-+------+------+-------------+
-| img  | img  |  img        |
-+------+------+-------------+
-|   Caption / story text    |
-+---------------------------+
-```
-
-## Rules
-
-- Images: full-bleed or near-full-bleed, high resolution
-- Nav: transparent overlay, becomes solid on scroll
-- Captions: small, muted, placed under or beside image
-- Limit text; let images carry the narrative
-- Lazy-load below-fold images
-
-## Typography
-
-- Heading: display or editorial, often white over image
-- Caption: 13px muted, body font
-- Body: minimal, max-width 60ch
-
-## Spacing
-
-- Image gap: `--space-2` (8px) or 0 for bleed
-- Caption margin-top: `--space-3` (12px)
-- Section gap: `--space-10` (40px)
-
-## Anti-Patterns
-
-- ❌ Heavy UI chrome over photos
-- ❌ Low-res stretched images
-- ❌ Text that competes with imagery
-
-## Theme Affinity
-
-- ✅ Carnival, Hum
-- ❌ Cobalt (too utilitarian)

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

@@ -1,50 +0,0 @@
-# 09 — Quote-Led
-
-**Fingerprint:** testimonial-first, large pull quotes, editorial, social proof.
-
-## Structure
-
-```
-+---------------------------+
-|                           |
-|   "BIG PULL QUOTE"        |
-|   — attribution           |
-|                           |
-+------+--------------------+
-|  small |  supporting      |
-|  quote |  context / logo  |
-+------+--------------------+
-|   CTA / next quote        |
-+---------------------------+
-```
-
-## Rules
-
-- Lead quote: largest type, occupies hero space
-- Attribution: name, role, company, muted
-- Secondary quotes: smaller, in a row or grid
-- One dominant quote per screen, no crowding
-- Optional logo lockup beside attribution
-
-## Typography
-
-- Quote: editorial serif or display, italic optional
-- Attribution: 14px medium, muted
-- Body: body font, minimal
-
-## Spacing
-
-- Quote padding: `--space-10` (40px)
-- Attribution margin-top: `--space-4` (16px)
-- Quote gap: `--space-6` (24px)
-
-## Anti-Patterns
-
-- ❌ Multiple equal quotes fighting for attention
-- ❌ Fake-looking testimonials without attribution
-- ❌ Quote text too small to read
-
-## Theme Affinity
-
-- ✅ Hum, Carnival
-- ⚠️ Lumen (needs warmer tone)