ai-developer-skill-os 7.0.2 → 7.5.1

package/skills/qk-ui-builder/references/structure.md

@@ -0,0 +1,280 @@
+# Structure: 6-Axis Fingerprint
+
+Use this framework to analyze and design page structure systematically. Each axis represents a distinct structural decision that shapes the user's experience.
+
+---
+
+## Axis 1: Section-Heading Placement
+
+Where headings sit within their section determines visual hierarchy and reading flow.
+
+### Options:
+
+**Top-left**
+- Headings aligned to the left, flush with or near the top of the section.
+- Best for: Content-heavy pages, documentation, dashboards.
+- Feels: Structured, professional, scannable.
+
+**Centered**
+- Headings centered horizontally within the section.
+- Best for: Landing pages, marketing sections, hero content.
+- Feels: Formal, balanced, editorial.
+
+**Inline with content**
+- Headings sit within the content flow, often beside images or at the start of cards.
+- Best for: Card grids, list layouts, feature sections.
+- Feels: Integrated, compact, modern.
+
+**Floating/overlapping**
+- Headings positioned over images or backgrounds, often large and semi-transparent.
+- Best for: Hero sections, editorial layouts, portfolio pages.
+- Feels: Bold, immersive, designed.
+
+**Staggered/offset**
+- Headings offset from the content grid, creating visual tension.
+- Best for: Creative portfolios, marketing sites, asymmetric layouts.
+- Feels: Dynamic, intentional, breaking the grid.
+
+**Hidden/implied**
+- No visible heading; section identity comes from context or content structure.
+- Best for: Card grids with self-explanatory items, tabbed interfaces.
+- Feels: Minimal, relies on content clarity.
+
+---
+
+## Axis 2: Body Composition
+
+How content is arranged spatially across the viewport.
+
+### Options:
+
+**Single column**
+- One narrow column, max-width ~650px, centered or left-aligned.
+- Best for: Long-form reading, articles, documentation.
+- Feels: Focused, readable, traditional.
+
+**Two-column**
+- Main content + sidebar, or split content evenly.
+- Best for: Documentation, settings pages, blog layouts.
+- Feels: Balanced, information-dense, efficient.
+
+**Three-column**
+- Three equal or near-equal columns.
+- Best for: Feature grids, card layouts, dashboard widgets.
+- Feels: Symmetric, scannable, systematic.
+
+**Asymmetric**
+- Uneven column widths (e.g., 2/3 + 1/3).
+- Best for: Marketing pages, case studies, editorial layouts.
+- Feels: Dynamic, hierarchical, designed.
+
+**Full-bleed**
+- Content spans the full viewport width.
+- Best for: Hero sections, image galleries, immersive experiences.
+- Feels: Expansive, modern, bold.
+
+**Masonry/Pinterest**
+- Varied height cards in a waterfall layout.
+- Best for: Image galleries, blogs, portfolio grids.
+- Feels: Organic, varied, content-adaptive.
+
+**Dashboard grid**
+- Structured grid with mixed card sizes (bento box style).
+- Best for: Analytics dashboards, admin panels, data tools.
+- Feels: Organized, data-rich, functional.
+
+---
+
+## Axis 3: Divider Language
+
+How sections and content blocks are visually separated.
+
+### Options:
+
+**Whitespace**
+- Separation achieved through spacing alone, no lines or borders.
+- Best for: Modern, minimal designs; content-heavy pages.
+- Feels: Clean, breathable, elegant.
+
+**Horizontal lines**
+- Thin or thick lines between sections or list items.
+- Best for: Traditional layouts, documents, settings pages.
+- Feels: Structured, formal, clear separation.
+
+**Color blocks**
+- Distinct background colors separating sections.
+- Best for: Marketing sites, landing pages, long-scrolling pages.
+- Feels: Bold, sectional, visually distinct.
+
+**Cards/containers**
+- Each section or item wrapped in a card with shadow/border.
+- Best for: Dashboards, data grids, feature lists.
+- Feels: Contained, organized, modular.
+
+**Gradient dividers**
+- Fading gradients or angled transitions between sections.
+- Best for: Modern marketing, creative portfolios.
+- Feels: Fluid, dynamic, premium.
+
+**Border-only**
+- Subtle borders around sections without fill.
+- Best for: Admin interfaces, forms, structured data.
+- Feels: Precise, technical, understated.
+
+**No dividers**
+- Content flows continuously without separation.
+- Best for: Single-topic pages, storytelling, immersive experiences.
+- Feels: Unified, narrative, cohesive.
+
+---
+
+## Axis 4: Button Voice
+
+The visual language of interactive elements within the page.
+
+### Options:
+
+**Primary/Secondary/Ghost**
+- Clear hierarchy: filled primary, outlined secondary, text-only ghost.
+- Best for: Standard applications, SaaS, forms.
+- Feels: Clear, conventional, accessible.
+
+**Primary/Secondary only**
+- No ghost buttons; all actions have visible backgrounds or borders.
+- Best for: Conservative interfaces, enterprise software.
+- Feels: Explicit, safe, traditional.
+
+**Outline-heavy**
+- Most buttons are outline/secondary, primary used sparingly.
+- Best for: Design-forward products, luxury brands.
+- Feels: Refined, minimal, sophisticated.
+
+**Icon-first**
+- Buttons dominated by icons with optional text labels.
+- Best for: Toolbars, dense interfaces, mobile apps.
+- Feels: Compact, visual, efficient.
+
+**Text-only**
+- No filled buttons; all actions are text links or underlined text.
+- Best for: Content sites, blogs, documentation.
+- Feels: Minimal, editorial, understated.
+
+**Size hierarchy**
+- Buttons sized by importance: large for primary, small for secondary.
+- Best for: Landing pages, marketing, hero CTAs.
+- Feels: Directed, scannable, purposeful.
+
+**Full-width (mobile)**
+- Buttons span full container width on small screens.
+- Best for: Mobile-first designs, checkout flows.
+- Feels: Touch-friendly, accessible, clear.
+
+---
+
+## Axis 5: Image Treatment
+
+How images and visual media are presented within the layout.
+
+### Options:
+
+**Full-bleed**
+- Images span the full viewport width, edge to edge.
+- Best for: Hero sections, immersive storytelling, marketing.
+- Feels: Bold, expansive, modern.
+
+**Contained/inset**
+- Images within a max-width container, aligned with text.
+- Best for: Articles, documentation, standard layouts.
+- Feels: Contained, readable, traditional.
+
+**Rounded corners**
+- Images with border-radius (usually 8px-16px).
+- Best for: Card layouts, avatars, modern SaaS.
+- Feels: Friendly, modern, approachable.
+
+**Drop shadow**
+- Images with shadow, appearing to float above background.
+- Best for: Card UIs, product displays, photography portfolios.
+- Feels: Layered, tactile, dimensional.
+
+**No treatment**
+- Images with sharp corners, no shadow, flush with background.
+- Best for: Brutalist design, editorial, minimalist layouts.
+- Feels: Raw, direct, intentional.
+
+**Blur/overlay**
+- Images with blur, gradient overlay, or darkened treatment.
+- Best for: Hero sections, text-over-image, background media.
+- Feels: Atmospheric, focused, layered.
+
+**Masked/cropped**
+- Images clipped to specific shapes (circle, angled edge, blob).
+- Best for: Avatars, logos, creative layouts.
+- Feels: Styled, distinctive, designed.
+
+---
+
+## Axis 6: Reveal Pattern
+
+How content and elements appear as the user interacts or scrolls.
+
+### Options:
+
+**Static**
+- All content visible immediately on load. No scroll-based animations.
+- Best for: Documentation, admin panels, content-heavy sites.
+- Feels: Fast, predictable, functional.
+
+**Scroll-triggered fade**
+- Elements fade in as they enter the viewport.
+- Best for: Marketing sites, long-form content, storytelling.
+- Feels: Progressive, polished, guided.
+
+**Scroll-triggered slide**
+- Elements slide up or in from the side on scroll.
+- Best for: Feature sections, case studies, portfolios.
+- Feels: Dynamic, engaging, modern.
+
+**Hover-reveal**
+- Content appears or changes on hover (cards, tooltips, previews).
+- Best for: Data tables, image grids, dense UIs.
+- Feels: Interactive, efficient, responsive.
+
+**Click-triggered expand**
+- Content expands on click (accordions, modals, dropdowns).
+- Best for: FAQs, settings, forms, navigation.
+- Feels: Controlled, user-directed, organized.
+
+**Staggered entrance**
+- Multiple elements animate in sequence on load or scroll.
+- Best for: Hero sections, onboarding, feature showcases.
+- Feels: Choreographed, premium, intentional.
+
+**Parallax**
+- Background moves at different speed than foreground.
+- Best for: Hero sections, marketing, creative portfolios.
+- Feels: Immersive, depth-filled, modern.
+
+**Skeleton loading**
+- Placeholder shapes shown while content loads.
+- Best for: Data-heavy apps, dashboards, mobile experiences.
+- Feels: Responsive, professional, prepared.
+
+---
+
+## Using the Fingerprint
+
+To analyze a page, score each axis:
+1. Identify which option best describes the current implementation.
+2. Note inconsistencies (e.g., centered headings but left-aligned CTAs).
+3. Identify tells: if every axis uses the AI-default option, the design is likely generated.
+
+**AI-default tendencies:**
+- Section headings: centered or top-left without variation
+- Body composition: three-column card grids
+- Dividers: cards everywhere
+- Button voice: primary/secondary/ghost, no size hierarchy
+- Images: rounded corners with shadow
+- Reveal: scroll-triggered fade on every element
+
+**Authentic design** intentionally mixes options across axes to serve content and user needs.

package/skills/qk-ui-builder/references/themes/atmospheric.md

@@ -0,0 +1,53 @@
+# Theme: Atmospheric
+
+**Genre:** atmospheric  
+**Use case:** music, art, creative
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (0–30% lightness) |
+| Display style | display-heavy |
+| Accent hue | chromatic-other (multi-hue) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(260, 20%, 5%);
+  --color-surface: hsl(260, 20%, 10%);
+  --color-text: hsl(260, 10%, 90%);
+  --color-text-muted: hsl(260, 5%, 55%);
+  --color-accent: hsl(280, 70%, 60%);
+  --color-accent-hover: hsl(280, 70%, 52%);
+  --color-accent-2: hsl(340, 60%, 55%);
+  --font-display: 'Space Grotesk', 'Helvetica Neue', sans-serif;
+  --font-body: 'Space Grotesk', 'Helvetica Neue', sans-serif;
+  --radius-sm: 8px;
+  --radius-md: 12px;
+  --shadow-sm: 0 2px 4px hsl(260, 20%, 2%);
+  --shadow-md: 0 8px 24px hsl(260, 20%, 2%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Photographic
+- ✅ Manifesto
+- ✅ Narrative Workflow
+- ❌ Index-First (too list-based)
+- ❌ Stat-Led (too data-dense)
+
+## Anti-Patterns (Atmospheric-specific)
+
+- ❌ Rigid grid layouts
+- ❌ System UI fonts
+- ❌ Bright single-accent highlights
+- ❌ Card-in-card structures
+
+## Voice
+
+- Poetic, abstract language: "Resonance", "Frequency", "Harmony"
+- Short, impactful phrases
+- No bullet points in hero sections

package/skills/qk-ui-builder/references/themes/carnival.md

@@ -0,0 +1,52 @@
+# Theme: Carnival
+
+**Genre:** playful  
+**Use case:** Consumer apps, events, marketing
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | light (>85% lightness) |
+| Display style | display-heavy |
+| Accent hue | warm (10–60°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(0, 0%, 100%);
+  --color-surface: hsl(45, 100%, 97%);
+  --color-text: hsl(20, 20%, 15%);
+  --color-text-muted: hsl(20, 10%, 45%);
+  --color-accent: hsl(25, 95%, 55%);
+  --color-accent-hover: hsl(25, 95%, 48%);
+  --font-display: 'Poppins', sans-serif;
+  --font-body: 'Poppins', sans-serif;
+  --radius-sm: 8px;
+  --radius-md: 16px;
+  --shadow-sm: 0 2px 4px hsl(25, 80%, 85%);
+  --shadow-md: 0 8px 24px hsl(25, 80%, 85%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Bento Grid
+- ✅ Marquee Hero
+- ✅ Feature Stack
+- ❌ Long Document (too formal)
+- ❌ Type Specimen (too restrained)
+
+## Anti-Patterns (Carnival-specific)
+
+- ❌ Flat backgrounds with no depth
+- ❌ Monochrome palettes
+- ❌ Minimalist whitespace-only layouts
+- ❌ System fonts only
+
+## Voice
+
+- Energetic, benefit-driven
+- Emoji sparingly (max 1 per section)
+- Questions in CTAs: "Ready to play?"

package/skills/qk-ui-builder/references/themes/cobalt.md

@@ -0,0 +1,52 @@
+# Theme: Cobalt
+
+**Genre:** modern-minimal  
+**Use case:** SaaS, developer tools, B2B products
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | mid (30–85% lightness) |
+| Display style | geometric-sans |
+| Accent hue | cool (200–300°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 20%, 98%);
+  --color-surface: hsl(220, 20%, 100%);
+  --color-text: hsl(220, 15%, 10%);
+  --color-text-muted: hsl(220, 10%, 45%);
+  --color-accent: hsl(220, 80%, 55%);
+  --color-accent-hover: hsl(220, 80%, 48%);
+  --font-display: 'Inter', sans-serif;
+  --font-body: 'Inter', sans-serif;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px hsl(220, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(220, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Stat-Led
+- ✅ Index-First
+- ❌ Manifesto (too editorial)
+- ❌ Riso (too analog)
+
+## Anti-Patterns (Cobalt-specific)
+
+- ❌ Purple gradients (`linear-gradient(135deg, #a855f7, #3b82f6)`)
+- ❌ Rounded-full buttons with gradient text
+- ❌ 3-column icon cards
+- ❌ Hero with centered-everything layout
+
+## Voice
+
+- Short labels, sentence case
+- Action verbs first: "Get started", "View docs"
+- No exclamation marks in headings

package/skills/qk-ui-builder/references/themes/editorial.md

@@ -0,0 +1,52 @@
+# Theme: Editorial
+
+**Genre:** editorial  
+**Use case:** magazines, news, blogs
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | light (85–100% lightness) |
+| Display style | roman-serif |
+| Accent hue | warm (20–50°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(40, 15%, 97%);
+  --color-surface: hsl(40, 15%, 100%);
+  --color-text: hsl(40, 15%, 10%);
+  --color-text-muted: hsl(40, 5%, 40%);
+  --color-accent: hsl(30, 60%, 50%);
+  --color-accent-hover: hsl(30, 60%, 42%);
+  --font-display: 'Merriweather', 'Georgia', serif;
+  --font-body: 'Merriweather', 'Georgia', serif;
+  --radius-sm: 4px;
+  --radius-md: 4px;
+  --shadow-sm: 0 1px 2px hsl(40, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(40, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Long Document
+- ✅ Quote-Led
+- ✅ Letter
+- ❌ Bento Grid (too tech)
+- ❌ Workbench (too dashboard)
+
+## Anti-Patterns (Editorial-specific)
+
+- ❌ Card-based layouts
+- ❌ Icon grids
+- ❌ Sans-serif headings
+- ❌ Dashboard-style navigation
+
+## Voice
+
+- Headlines with strong verbs: "Revealed", "Analysis", "Opinion"
+- Byline prominence
+- Timestamps and read-time indicators

package/skills/qk-ui-builder/references/themes/garden.md

@@ -0,0 +1,52 @@
+# Theme: Garden
+
+**Genre:** atmospheric  
+**Use case:** organic, eco, sustainability
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | light (85–100% lightness) |
+| Display style | classical-serif |
+| Accent hue | leaf-green (90–150°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(90, 20%, 97%);
+  --color-surface: hsl(90, 20%, 100%);
+  --color-text: hsl(90, 15%, 12%);
+  --color-text-muted: hsl(90, 10%, 40%);
+  --color-accent: hsl(120, 35%, 40%);
+  --color-accent-hover: hsl(120, 35%, 32%);
+  --font-display: 'Lora', 'Times New Roman', serif;
+  --font-body: 'Lora', 'Times New Roman', serif;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px hsl(90, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(90, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Photographic
+- ✅ Long Document
+- ✅ Quote-Led
+- ❌ Stat-Led (too abstract)
+- ❌ Workbench (too technical)
+
+## Anti-Patterns (Garden-specific)
+
+- ❌ Neon or electric colors
+- ❌ Geometric sans-serif headings
+- ❌ Dark mode only experiences
+- ❌ Sharp industrial corners
+
+## Voice
+
+- Organic metaphors: "Grow", "Rooted", "Bloom"
+- Conversational, warm tone
+- Long-form storytelling

package/skills/qk-ui-builder/references/themes/hum.md

@@ -0,0 +1,52 @@
+# Theme: Hum
+
+**Genre:** atmospheric  
+**Use case:** Wellness, food, lifestyle, crafts
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (<30% lightness) |
+| Display style | classical-serif |
+| Accent hue | warm (10–60°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 15%, 10%);
+  --color-surface: hsl(220, 15%, 14%);
+  --color-text: hsl(220, 10%, 90%);
+  --color-text-muted: hsl(220, 10%, 65%);
+  --color-accent: hsl(35, 60%, 55%);
+  --color-accent-hover: hsl(35, 60%, 60%);
+  --font-display: 'Playfair Display', serif;
+  --font-body: 'Source Serif 4', serif;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px hsl(0, 0%, 0%);
+  --shadow-md: 0 4px 12px hsl(0, 0%, 0%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Narrative Workflow
+- ✅ Photographic
+- ✅ Quote-Led
+- ❌ Component Playground (too technical)
+- ❌ Index-First (too utilitarian)
+
+## Anti-Patterns (Hum-specific)
+
+- ❌ Pure black on pure white
+- ❌ Geometric sans-serif for headings
+- ❌ Bright neon accents
+- ❌ Card-in-card layouts
+
+## Voice
+
+- Warm, inviting, sensory words
+- Present tense, active voice
+- Avoid jargon

package/skills/qk-ui-builder/references/themes/lumen.md

@@ -0,0 +1,52 @@
+# Theme: Lumen
+
+**Genre:** tech  
+**Use case:** AI tools, developer products, dashboards
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (<30% lightness) |
+| Display style | mono |
+| Accent hue | cool (200–300°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 20%, 8%);
+  --color-surface: hsl(220, 20%, 12%);
+  --color-text: hsl(220, 10%, 88%);
+  --color-text-muted: hsl(220, 10%, 55%);
+  --color-accent: hsl(200, 100%, 60%);
+  --color-accent-hover: hsl(200, 100%, 65%);
+  --font-display: 'JetBrains Mono', monospace;
+  --font-body: 'Inter', sans-serif;
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --shadow-sm: 0 1px 2px hsl(0, 0%, 0%);
+  --shadow-md: 0 4px 12px hsl(0, 0%, 0%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Component Playground
+- ✅ Stat-Led
+- ❌ Manifesto (too editorial)
+- ❌ Letter (too personal)
+
+## Anti-Patterns (Lumen-specific)
+
+- ❌ Serif fonts
+- ❌ Warm color accents
+- ❌ Excessive border-radius (> 8px)
+- ❌ Large hero images
+
+## Voice
+
+- Concise, technical but accessible
+- Action-oriented: "Deploy", "Connect", "Query"
+- Code snippets welcome

package/skills/qk-ui-builder/references/themes/midnight.md

@@ -0,0 +1,52 @@
+# Theme: Midnight
+
+**Genre:** atmospheric  
+**Use case:** luxury, premium products
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (0–30% lightness) |
+| Display style | classical-serif |
+| Accent hue | cool (180–260°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 20%, 6%);
+  --color-surface: hsl(220, 20%, 10%);
+  --color-text: hsl(220, 10%, 92%);
+  --color-text-muted: hsl(220, 5%, 55%);
+  --color-accent: hsl(220, 40%, 65%);
+  --color-accent-hover: hsl(220, 40%, 58%);
+  --font-display: 'Cormorant Garamond', 'Times New Roman', serif;
+  --font-body: 'Crimson Text', Georgia, serif;
+  --radius-sm: 2px;
+  --radius-md: 4px;
+  --shadow-sm: 0 1px 2px hsl(220, 20%, 2%);
+  --shadow-md: 0 4px 12px hsl(220, 20%, 2%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Photographic
+- ✅ Quote-Led
+- ✅ Narrative Workflow
+- ❌ Stat-Led (too data-dense)
+- ❌ Component Playground (too utilitarian)
+
+## Anti-Patterns (Midnight-specific)
+
+- ❌ Bright saturated colors
+- ❌ Geometric sans-serif fonts
+- ❌ Card-in-card nesting
+- ❌ Grid-based feature lists
+
+## Voice
+
+- Evocative adjectives: "Timeless", "Curated", "Exceptional"
+- Short declarative sentences
+- No bullet points in hero sections