ai-developer-skill-os 7.0.2 → 7.5.1

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

@@ -0,0 +1,44 @@
+# 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/skills/qk-ui-builder/references/macrostructures/06-conversational-faq.md

@@ -0,0 +1,50 @@
+# 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/skills/qk-ui-builder/references/macrostructures/07-manifesto.md

@@ -0,0 +1,51 @@
+# 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/skills/qk-ui-builder/references/macrostructures/08-photographic.md

@@ -0,0 +1,50 @@
+# 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/skills/qk-ui-builder/references/macrostructures/09-quote-led.md

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

package/skills/qk-ui-builder/references/macrostructures/11-catalogue.md

@@ -0,0 +1,49 @@
+# 11 — Catalogue
+
+**Fingerprint:** product listings, e-commerce grid, filterable cards, scannable.
+
+## Structure
+
+```
++---------------------------+
+|   Search + Filters        |
++------+--------------------+
+| Facet|  [card][card]      |
+| Nav  |  [card][card]      |
+|      |  [card][card]      |
+|      |                    |
++------+--------------------+
+|   Pagination / Load more  |
++---------------------------+
+```
+
+## Rules
+
+- Grid: 3–4 columns desktop, 2 tablet, 1 mobile
+- Card: image, title, price, rating, quick-add
+- Facets: sticky filter sidebar, collapsible on mobile
+- Pagination: numbered or infinite scroll, state preserved
+- Sorting: visible control (price, popularity)
+
+## Typography
+
+- Heading: display for page title
+- Price: tabular-nums, medium weight
+- Title: 14px body, truncated to 2 lines
+
+## Spacing
+
+- Grid gap: `--space-4` (16px)
+- Card padding: `--space-3` (12px)
+- Filter width: 240px
+
+## Anti-Patterns
+
+- ❌ Cards with inconsistent heights breaking grid
+- ❌ Hidden or unclear pricing
+- ❌ Filters that require page reload
+
+## Theme Affinity
+
+- ✅ Carnival, Cobalt
+- ❌ Hum (needs more product pop)

package/skills/qk-ui-builder/references/macrostructures/12-letter.md

@@ -0,0 +1,49 @@
+# 12 — Letter
+
+**Fingerprint:** personal, newsletters, 1-on-1 communication, single readable column.
+
+## Structure
+
+```
++---------------------------+
+|   Salutation (Dear ...)   |
++---------------------------+
+|   Body paragraphs         |
+|   (personal, signed)      |
+|                           |
+|   Signature               |
++---------------------------+
+|   PS / footnotes          |
++---------------------------+
+```
+
+## Rules
+
+- Single column, intimate width (max 60ch)
+- Tone: first-person, conversational
+- Salutation and signature frame the content
+- Optional PS line for emphasis
+- Minimal decoration; focus on the words
+
+## Typography
+
+- Heading: display or editorial for subject
+- Body: body font, 17px, comfortable line-height
+- Signature: italic or handwritten-style if theme allows
+
+## Spacing
+
+- Body padding: `--space-8` (32px)
+- Paragraph gap: `--space-4` (16px)
+- Signature margin-top: `--space-6` (24px)
+
+## Anti-Patterns
+
+- ❌ Corporate marketing tone
+- ❌ Multi-column newsletter chaos
+- ❌ Missing personal sign-off
+
+## Theme Affinity
+
+- ✅ Hum, Lumen
+- ⚠️ Carnival (tone may clash)

package/skills/qk-ui-builder/references/macrostructures/13-index-first.md

@@ -0,0 +1,49 @@
+# 13 — Index-First
+
+**Fingerprint:** wiki-style, knowledge base, docs hub, alphabetical/topic index upfront.
+
+## Structure
+
+```
++---------------------------+
+|   Search + A-Z / Topics   |
++------+--------------------+
+| Index|  Entry content     |
+| list |  (when selected)   |
+| A B  |                    |
+| C D  |  headings, links   |
++------+--------------------+
+|   Breadcrumb             |
++---------------------------+
+```
+
+## Rules
+
+- Index: alphabetical or categorical list, always visible
+- Search: primary entry point, live filter
+- Entries: cross-linked, consistent heading structure
+- Breadcrumb: shows location in hierarchy
+- Last-updated timestamp per entry
+
+## Typography
+
+- Heading: display for hub title
+- Index items: 14px, hover underline
+- Entry body: body font, 16px
+
+## Spacing
+
+- Index width: 220px
+- Entry padding: `--space-6` (24px)
+- Item gap: `--space-2` (8px)
+
+## Anti-Patterns
+
+- ❌ Deep nesting with no index
+- ❌ Orphan pages without back-links
+- ❌ Stale "last updated" dates
+
+## Theme Affinity
+
+- ✅ Lumen, Cobalt
+- ❌ Carnival (too playful for reference)

package/skills/qk-ui-builder/references/macrostructures/14-narrative-workflow.md

@@ -0,0 +1,48 @@
+# 14 — Narrative Workflow
+
+**Fingerprint:** vertical scroll, step-by-step progression, progress indicator, one primary action per screen.
+
+## Structure
+
+```
++---------------------+
+|     Progress Bar    |
++---------------------+
+|                     |
+|   Step Content      |
+|   (text + media)    |
+|   [Primary Action]  |
++---------------------+
+|   Skip / Back       |
++---------------------+
+```
+
+## Rules
+
+- Max 1 primary action per step
+- Progress bar always visible
+- Steps must have clear entry/exit criteria
+- Support keyboard navigation (Enter = next, Backspace = back)
+
+## Typography
+
+- Heading: display style, 1 per step
+- Body: body font, max-width 65ch
+- Helper text: muted color, 14px
+
+## Spacing
+
+- Step padding: `--space-8` (32px)
+- Action margin-top: `--space-6` (24px)
+- Progress bar height: 4px
+
+## Anti-Patterns
+
+- ❌ Multiple CTAs per step
+- ❌ Progress bar that doesn't reflect actual state
+- ❌ Steps that require going back to change data
+
+## Theme Affinity
+
+- ✅ Hum, Cobalt
+- ⚠️ Carnival (can work but needs restraint)

package/skills/qk-ui-builder/references/macrostructures/15-split-studio.md

@@ -0,0 +1,48 @@
+# 15 — Split Studio
+
+**Fingerprint:** before/after, comparison layouts, side-by-side, A/B showcase.
+
+## Structure
+
+```
++---------------------------+
+|   Title + toggle (vs)     |
++-------------+-------------+
+|   BEFORE    |   AFTER     |
+|   (media)   |   (media)   |
+|   caption   |   caption   |
++-------------+-------------+
+|   Diff / notes row        |
++---------------------------+
+```
+
+## Rules
+
+- Two equal panes, clear "vs" divider or toggle
+- Sync scroll when comparing scrollable content
+- Optional slider for wipe comparison
+- Captions: label each side unambiguously
+- Notes: explain the difference below
+
+## Typography
+
+- Heading: display for comparison title
+- Pane labels: uppercase, 13px muted
+- Notes: body font, 15px
+
+## Spacing
+
+- Pane gap: `--space-2` (8px) or divider line
+- Pane padding: `--space-4` (16px)
+- Notes margin-top: `--space-6` (24px)
+
+## Anti-Patterns
+
+- ❌ Asymmetric panes implying bias
+- ❌ No labels on before/after
+- ❌ Wipe slider that lags input
+
+## Theme Affinity
+
+- ✅ Cobalt, Lumen
+- ⚠️ Carnival (keep divider clean)

package/skills/qk-ui-builder/references/macrostructures/16-feature-stack.md

@@ -0,0 +1,51 @@
+# 16 — Feature Stack
+
+**Fingerprint:** stacked feature highlights, SaaS product pages, alternating sections.
+
+## Structure
+
+```
++---------------------------+
+|   Hero (value prop)       |
++------+--------------------+
+| img  |  Feature 1         |
+|      |  (title + desc)    |
++------+--------------------+
+|  Feature 2  | img         |
++------+--------------------+
+|   ... repeated N times    |
++---------------------------+
+|   Final CTA               |
++---------------------------+
+```
+
+## Rules
+
+- Alternating image/text rows, consistent rhythm
+- Each feature: one headline, 1–2 sentence desc, optional icon
+- Max 5–6 features before fatigue
+- Sticky or scroll-reveal for emphasis
+- Final CTA after the stack
+
+## Typography
+
+- Heading: display for hero and feature titles
+- Desc: body font, 16px, max-width 50ch
+- Icon labels: 13px muted
+
+## Spacing
+
+- Row padding: `--space-10` (40px)
+- Row gap: `--space-8` (32px)
+- Media min-height: 320px
+
+## Anti-Patterns
+
+- ❌ More than 6 stacked features
+- ❌ Inconsistent alternation direction
+- ❌ Features without a clear benefit
+
+## Theme Affinity
+
+- ✅ Cobalt, Hum
+- ⚠️ Carnival (restraint needed)

package/skills/qk-ui-builder/references/macrostructures/17-type-specimen.md

@@ -0,0 +1,48 @@
+# 17 — Type Specimen
+
+**Fingerprint:** typography showcase, design system docs, font scales on display.
+
+## Structure
+
+```
++---------------------------+
+|   Typeface name + meta    |
++------+--------------------+
+| Spec |  Glyph / alphabet  |
+| nav  |  Aa Bb Cc ...       |
+|      |  Weight row         |
++------+--------------------+
+|   Scale / line-height     |
++---------------------------+
+```
+
+## Rules
+
+- Show full character set and key glyphs
+- Display each weight (light → black) with label
+- Type scale: list sizes with px/rem and usage
+- Sample text: pangram + real paragraph
+- Nav: jump to typeface sections
+
+## Typography
+
+- Specimen: the typeface itself, all sizes
+- Labels: mono, 12px muted for metadata
+- Sample: body font fallback noted
+
+## Spacing
+
+- Specimen padding: `--space-8` (32px)
+- Weight row gap: `--space-4` (16px)
+- Nav width: 200px
+
+## Anti-Patterns
+
+- ❌ Showing only one weight
+- ❌ No scale reference
+- ❌ Illegible specimen background
+
+## Theme Affinity
+
+- ✅ Lumen, Cobalt
+- ❌ Hum (too quiet for showcase)

package/skills/qk-ui-builder/references/macrostructures/18-portfolio-grid.md

@@ -0,0 +1,48 @@
+# 18 — Portfolio Grid
+
+**Fingerprint:** creative portfolio, masonry grid, varied tile sizes, visual-first.
+
+## Structure
+
+```
++---------------------------+
+|   Name + filter (tags)    |
++---------------------------+
+| [big][sm][sm]             |
+| [sm  ][med  ]             |
+| [med ][sm][big]           |
++---------------------------+
+|   Hover = reveal meta     |
++---------------------------+
+```
+
+## Rules
+
+- Masonry or bento-style varied tile sizes
+- Hover/focus: reveal title, category, year
+- Filter: by tag/category, animates layout
+- Click: opens project detail
+- No fixed equal rows; embrace asymmetry
+
+## Typography
+
+- Heading: display for name/title
+- Tile meta: 13px muted, revealed on hover
+- Tags: 12px uppercase labels
+
+## Spacing
+
+- Grid gap: `--space-3` (12px)
+- Tile min-height: 200px
+- Filter margin-bottom: `--space-6` (24px)
+
+## Anti-Patterns
+
+- ❌ Rigid equal grid hiding creativity
+- ❌ No hover state on tiles
+- ❌ Missing project metadata
+
+## Theme Affinity
+
+- ✅ Carnival, Hum
+- ❌ Cobalt (too rigid)

package/skills/qk-ui-builder/references/macrostructures/19-map-diagram.md

@@ -0,0 +1,50 @@
+# 19 — Map / Diagram
+
+**Fingerprint:** architecture diagrams, org charts, flows, node-and-edge layouts.
+
+## Structure
+
+```
++---------------------------+
+|   Legend + zoom controls  |
++---------------------------+
+|                           |
+|   [ node ] -- [ node ]    |
+|        \     /            |
+|        [ node ]           |
+|                           |
++---------------------------+
+|   Side panel (node info)  |
++---------------------------+
+```
+
+## Rules
+
+- Nodes: clear shapes with labels, consistent styling
+- Edges: directional arrows, avoid crossing when possible
+- Legend: explains node/edge types
+- Zoom/pan: required for complex diagrams
+- Side panel: details on node select
+
+## Typography
+
+- Heading: display for diagram title
+- Node label: 13px medium, legible on node bg
+- Legend: 12px muted
+
+## Spacing
+
+- Node padding: `--space-3` (12px)
+- Edge spacing: auto-layout with min gap
+- Panel width: 280px
+
+## Anti-Patterns
+
+- ❌ Overlapping nodes/edges
+- ❌ Unlabeled connections
+- ❌ No zoom on large diagrams
+
+## Theme Affinity
+
+- ✅ Lumen, Cobalt
+- ❌ Carnival (distracts from structure)