heraspec 0.1.0

package/dist/core/templates/skills/scripts/core.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Builder Core - BM25 search engine for UI/UX style guides
+"""
+
+import csv
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+
+# Optional dependencies for vector search
+try:
+    from sentence_transformers import SentenceTransformer
+    import numpy as np
+    from sklearn.metrics.pairwise import cosine_similarity
+    VECTOR_AVAILABLE = True
+except ImportError:
+    VECTOR_AVAILABLE = False
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "style": {
+        "file": "styles.csv",
+        "search_cols": ["Style Category", "Keywords", "Best For", "Type"],
+        "output_cols": ["Style Category", "Type", "Keywords", "Primary Colors", "Effects & Animation", "Best For", "Performance", "Accessibility", "Framework Compatibility", "Complexity"]
+    },
+    "prompt": {
+        "file": "prompts.csv",
+        "search_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords"],
+        "output_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords", "Implementation Checklist"]
+    },
+    "color": {
+        "file": "colors.csv",
+        "search_cols": ["Product Type", "Keywords", "Notes"],
+        "output_cols": ["Product Type", "Keywords", "Primary (Hex)", "Secondary (Hex)", "CTA (Hex)", "Background (Hex)", "Text (Hex)", "Border (Hex)", "Notes"]
+    },
+    "chart": {
+        "file": "charts.csv",
+        "search_cols": ["Data Type", "Keywords", "Best Chart Type", "Accessibility Notes"],
+        "output_cols": ["Data Type", "Keywords", "Best Chart Type", "Secondary Options", "Color Guidance", "Accessibility Notes", "Library Recommendation", "Interactive Level"]
+    },
+    "landing": {
+        "file": "landing.csv",
+        "search_cols": ["Pattern Name", "Keywords", "Conversion Optimization", "Section Order"],
+        "output_cols": ["Pattern Name", "Keywords", "Section Order", "Primary CTA Placement", "Color Strategy", "Conversion Optimization"]
+    },
+    "product": {
+        "file": "products.csv",
+        "search_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Key Considerations"],
+        "output_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Secondary Styles", "Landing Page Pattern", "Dashboard Style (if applicable)", "Color Palette Focus"]
+    },
+    "ux": {
+        "file": "ux-guidelines.csv",
+        "search_cols": ["Category", "Issue", "Description", "Platform"],
+        "output_cols": ["Category", "Issue", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "typography": {
+        "file": "typography.csv",
+        "search_cols": ["Font Pairing Name", "Category", "Mood/Style Keywords", "Best For", "Heading Font", "Body Font"],
+        "output_cols": ["Font Pairing Name", "Category", "Heading Font", "Body Font", "Mood/Style Keywords", "Best For", "Google Fonts URL", "CSS Import", "Tailwind Config", "Notes"]
+    },
+    "pages": {
+        "file": "pages.csv",
+        "search_cols": ["Page Type", "Keywords", "Section Order", "Key Components", "Layout Pattern", "Best For"],
+        "output_cols": ["Page Type", "Keywords", "Section Order", "Key Components", "Layout Pattern", "Color Strategy", "Recommended Effects", "Best For", "Considerations"]
+    }
+}
+
+STACK_CONFIG = {
+    "html-tailwind": {"file": "stacks/html-tailwind.csv"},
+    "react": {"file": "stacks/react.csv"},
+    "nextjs": {"file": "stacks/nextjs.csv"},
+    "vue": {"file": "stacks/vue.csv"},
+    "svelte": {"file": "stacks/svelte.csv"},
+    "swiftui": {"file": "stacks/swiftui.csv"},
+    "react-native": {"file": "stacks/react-native.csv"},
+    "flutter": {"file": "stacks/flutter.csv"}
+}
+
+# Common columns for all stacks
+_STACK_COLS = {
+    "search_cols": ["Category", "Guideline", "Description", "Do", "Don't"],
+    "output_cols": ["Category", "Guideline", "Description", "Do", "Don't", "Code Good", "Code Bad", "Severity", "Docs URL"]
+}
+
+AVAILABLE_STACKS = list(STACK_CONFIG.keys())
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+
+    def tokenize(self, text):
+        """Lowercase, split, remove punctuation, filter short words"""
+        text = re.sub(r'[^\w\s]', ' ', str(text).lower())
+        return [w for w in text.split() if len(w) > 2]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        for doc in self.corpus:
+            seen = set()
+            for word in doc:
+                if word not in seen:
+                    self.doc_freqs[word] += 1
+                    seen.add(word)
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx, doc in enumerate(self.corpus):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = defaultdict(int)
+            for word in doc:
+                term_freqs[word] += 1
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs[token]
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+
+# ============ VECTOR SEARCH IMPLEMENTATION ============
+class VectorSearch:
+    """Vector-based semantic search using sentence transformers"""
+    
+    def __init__(self):
+        if not VECTOR_AVAILABLE:
+            raise ImportError(
+                "Vector search requires sentence-transformers and scikit-learn. "
+                "Install with: pip install sentence-transformers scikit-learn"
+            )
+        # Use lightweight, fast model
+        self.model = SentenceTransformer('all-MiniLM-L6-v2')
+        self.embeddings = None
+        self.documents = None
+    
+    def fit(self, documents):
+        """Encode documents into vectors"""
+        self.documents = documents
+        if len(documents) == 0:
+            self.embeddings = np.array([])
+            return
+        # Encode without progress bar for cleaner output
+        self.embeddings = self.model.encode(documents, show_progress_bar=False, convert_to_numpy=True)
+    
+    def search(self, query, top_k=3):
+        """Search using cosine similarity"""
+        if self.embeddings is None or len(self.embeddings) == 0:
+            return []
+        
+        # Encode query
+        query_embedding = self.model.encode([query], show_progress_bar=False, convert_to_numpy=True)
+        
+        # Calculate cosine similarity
+        similarities = cosine_similarity(query_embedding, self.embeddings)[0]
+        
+        # Get top k indices
+        top_indices = np.argsort(similarities)[::-1][:top_k]
+        
+        # Return (index, score) tuples
+        return [(int(idx), float(similarities[idx])) for idx in top_indices if similarities[idx] > 0]
+
+
+# ============ SEARCH FUNCTIONS ============
+def _load_csv(filepath):
+    """Load CSV and return list of dicts"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return list(csv.DictReader(f))
+
+
+def _search_csv(filepath, search_cols, output_cols, query, max_results, mode='bm25'):
+    """Core search function using BM25, Vector, or Hybrid"""
+    if not filepath.exists():
+        return []
+
+    data = _load_csv(filepath)
+
+    # Build documents from search columns
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+    
+    if len(documents) == 0:
+        return []
+
+    # Choose search mode
+    if mode == 'bm25' or (mode in ['vector', 'hybrid'] and not VECTOR_AVAILABLE):
+        # BM25 search (default or fallback)
+        bm25 = BM25()
+        bm25.fit(documents)
+        ranked = bm25.score(query)
+        
+        # Get top results with score > 0
+        results = []
+        for idx, score in ranked[:max_results]:
+            if score > 0:
+                row = data[idx]
+                results.append({col: row.get(col, "") for col in output_cols if col in row})
+        
+        return results
+    
+    elif mode == 'vector':
+        # Vector search
+        vector_search = VectorSearch()
+        vector_search.fit(documents)
+        ranked = vector_search.search(query, top_k=max_results)
+        
+        results = []
+        for idx, score in ranked:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+        
+        return results
+    
+    elif mode == 'hybrid':
+        # Hybrid search: combine BM25 + Vector
+        # Get more results from each to combine
+        search_count = max_results * 2
+        
+        # BM25 results
+        bm25 = BM25()
+        bm25.fit(documents)
+        bm25_ranked = bm25.score(query)
+        bm25_scores = {idx: score for idx, score in bm25_ranked[:search_count] if score > 0}
+        
+        # Vector results
+        vector_search = VectorSearch()
+        vector_search.fit(documents)
+        vector_ranked = vector_search.search(query, top_k=search_count)
+        vector_scores = {idx: score for idx, score in vector_ranked}
+        
+        # Normalize scores to 0-1 range
+        max_bm25 = max(bm25_scores.values()) if bm25_scores else 1.0
+        max_vector = max(vector_scores.values()) if vector_scores else 1.0
+        
+        # Combine scores (alpha = 0.5 for balanced, can be adjusted)
+        alpha = 0.5
+        combined_scores = {}
+        all_indices = set(bm25_scores.keys()) | set(vector_scores.keys())
+        
+        for idx in all_indices:
+            bm25_norm = (bm25_scores.get(idx, 0) / max_bm25) if max_bm25 > 0 else 0
+            vector_norm = (vector_scores.get(idx, 0) / max_vector) if max_vector > 0 else 0
+            combined_scores[idx] = alpha * bm25_norm + (1 - alpha) * vector_norm
+        
+        # Sort by combined score
+        sorted_indices = sorted(combined_scores.items(), key=lambda x: x[1], reverse=True)
+        
+        # Get top results
+        results = []
+        for idx, score in sorted_indices[:max_results]:
+            if score > 0:
+                row = data[idx]
+                results.append({col: row.get(col, "") for col in output_cols if col in row})
+        
+        return results
+    
+    else:
+        # Unknown mode, fallback to BM25
+        return _search_csv(filepath, search_cols, output_cols, query, max_results, mode='bm25')
+
+
+def detect_domain(query):
+    """Auto-detect the most relevant domain from query"""
+    query_lower = query.lower()
+
+    domain_keywords = {
+        "color": ["color", "palette", "hex", "#", "rgb"],
+        "chart": ["chart", "graph", "visualization", "trend", "bar", "pie", "scatter", "heatmap", "funnel"],
+        "landing": ["landing", "page", "cta", "conversion", "hero", "testimonial", "pricing", "section"],
+        "product": ["saas", "ecommerce", "e-commerce", "fintech", "healthcare", "gaming", "portfolio", "crypto", "dashboard"],
+        "prompt": ["prompt", "css", "implementation", "variable", "checklist", "tailwind"],
+        "style": ["style", "design", "ui", "minimalism", "glassmorphism", "neumorphism", "brutalism", "dark mode", "flat", "aurora"],
+        "ux": ["ux", "usability", "accessibility", "wcag", "touch", "scroll", "animation", "keyboard", "navigation", "mobile"],
+        "typography": ["font", "typography", "heading", "serif", "sans"],
+        "pages": ["page", "home", "homepage", "about", "post", "article", "blog", "category", "pricing", "faq", "contact", "product", "shop", "catalog", "details", "single"]
+    }
+
+    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else "style"
+
+
+def search(query, domain=None, max_results=MAX_RESULTS, mode='bm25'):
+    """
+    Main search function with auto-domain detection
+    
+    Args:
+        query: Search query string
+        domain: Domain to search (auto-detected if None)
+        max_results: Maximum number of results
+        mode: Search mode - 'bm25' (default), 'vector', or 'hybrid'
+    
+    Returns:
+        Dictionary with search results
+    """
+    if domain is None:
+        domain = detect_domain(query)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["style"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    # Validate mode
+    if mode not in ['bm25', 'vector', 'hybrid']:
+        mode = 'bm25'
+    
+    # Fallback to BM25 if vector dependencies not available
+    if mode in ['vector', 'hybrid'] and not VECTOR_AVAILABLE:
+        mode = 'bm25'
+
+    results = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results, mode)
+
+    return {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "mode": mode,
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_stack(query, stack, max_results=MAX_RESULTS, mode='bm25'):
+    """Search stack-specific guidelines"""
+    if stack not in STACK_CONFIG:
+        return {"error": f"Unknown stack: {stack}. Available: {', '.join(AVAILABLE_STACKS)}"}
+
+    filepath = DATA_DIR / STACK_CONFIG[stack]["file"]
+
+    if not filepath.exists():
+        return {"error": f"Stack file not found: {filepath}", "stack": stack}
+
+    # Validate mode and fallback if needed
+    if mode not in ['bm25', 'vector', 'hybrid']:
+        mode = 'bm25'
+    if mode in ['vector', 'hybrid'] and not VECTOR_AVAILABLE:
+        mode = 'bm25'
+
+    results = _search_csv(filepath, _STACK_COLS["search_cols"], _STACK_COLS["output_cols"], query, max_results, mode)
+
+    return {
+        "domain": "stack",
+        "stack": stack,
+        "query": query,
+        "file": STACK_CONFIG[stack]["file"],
+        "mode": mode,
+        "count": len(results),
+        "results": results
+    }

package/dist/core/templates/skills/scripts/search.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Builder Search - BM25, Vector, and Hybrid search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--mode <mode>] [--max-results 3]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, pages
+Stacks: html-tailwind, react, nextjs, vue, svelte, swiftui, react-native, flutter
+Modes: bm25 (default), vector, hybrid
+
+Note: Vector and hybrid modes require: pip install sentence-transformers scikit-learn
+"""
+
+import argparse
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack, VECTOR_AVAILABLE
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    mode_info = f" | **Mode:** {result.get('mode', 'bm25')}"
+    if result.get("stack"):
+        output.append(f"## UI/UX Builder Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}{mode_info}")
+    else:
+        output.append(f"## UI/UX Builder Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}{mode_info}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI/UX Builder Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search")
+    parser.add_argument("--mode", "-m", choices=['bm25', 'vector', 'hybrid'], default='bm25',
+                       help="Search mode: bm25 (default, keyword-based), vector (semantic), hybrid (best of both)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    # Check if vector mode is requested but not available
+    if args.mode in ['vector', 'hybrid'] and not VECTOR_AVAILABLE:
+        print("Warning: Vector/Hybrid mode requires sentence-transformers and scikit-learn.")
+        print("Falling back to BM25 mode. Install with: pip install sentence-transformers scikit-learn")
+        args.mode = 'bm25'
+
+    # Stack search takes priority
+    if args.stack:
+        result = search_stack(args.query, args.stack, args.max_results, args.mode)
+    else:
+        result = search(args.query, args.domain, args.max_results, args.mode)
+
+    if args.json:
+        import json
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_output(result))

package/dist/core/templates/skills/suggestion-skill.md

@@ -0,0 +1,118 @@
+# Skill: Feature Suggestion (Cross-Cutting)
+
+## Purpose
+
+This skill is used to analyze existing project structure and suggest new features that would integrate well with the current codebase. It helps identify opportunities for enhancements and new functionality based on existing patterns and architecture.
+
+## When to Use
+
+- When planning new features for a project
+- When identifying gaps in functionality
+- When analyzing project structure for enhancement opportunities
+- When proposing improvements based on existing patterns
+- When suggesting features that align with project architecture
+
+## Step-by-Step Process
+
+### Step 1: Analyze Project Structure
+- Read and understand `heraspec/project.md`
+- Review existing specs in `heraspec/specs/`
+- Analyze existing changes and their patterns
+- Identify project type and tech stack
+- Map current feature set
+
+### Step 2: Identify Integration Points
+- Find logical places for new features
+- Identify patterns in existing code
+- Determine appropriate project structure locations
+- Consider dependencies and relationships
+- Map feature hierarchy
+
+### Step 3: Generate Suggestions
+- Create feature suggestions based on analysis
+- Ensure suggestions align with project type
+- Consider existing patterns and conventions
+- Propose features that enhance current functionality
+- Suggest improvements and extensions
+
+### Step 4: Organize Suggestions
+- Group suggestions by category/domain
+- Prioritize based on feasibility and value
+- Create suggestion files in appropriate locations
+- Link suggestions to existing features
+- Document integration points
+
+### Step 5: Review and Refine
+- Review suggestions for consistency
+- Ensure suggestions follow project conventions
+- Verify integration points are correct
+- Refine based on project requirements
+- Prepare for implementation planning
+
+## Required Input
+
+- **Project structure**: Understanding of project organization
+- **Existing specs**: Current feature specifications
+- **Project type**: Type of project (plugin, module, app, etc.)
+- **Tech stack**: Technologies used in the project
+- **Domain context**: Business domain and requirements
+
+## Expected Output
+
+- Feature suggestion files
+- Suggestions organized by category
+- Integration points identified
+- Suggestions linked to existing features
+- Documentation of suggested enhancements
+
+## Tone & Rules
+
+### Suggestion Quality
+- Suggest features that add value
+- Align with project type and architecture
+- Consider existing patterns and conventions
+- Propose realistic and feasible features
+- Enhance rather than replace existing functionality
+
+### Integration
+- Identify appropriate locations for features
+- Consider dependencies and relationships
+- Follow existing project structure
+- Maintain consistency with current patterns
+- Document integration approach
+
+### Documentation
+- Clearly describe suggested features
+- Explain integration points
+- Link to related existing features
+- Provide context and rationale
+- Include implementation considerations
+
+### Limitations
+- ❌ DO NOT suggest features that conflict with existing architecture
+- ❌ DO NOT ignore project conventions
+- ❌ DO NOT suggest overly complex features
+- ❌ DO NOT duplicate existing functionality
+- ❌ DO NOT suggest features without considering integration
+
+## Available Templates
+
+- `templates/suggestion-template.md` - Template for feature suggestions
+- `templates/suggestion-category-template.md` - Template for organizing suggestions by category
+
+## Available Scripts
+
+- `scripts/analyze-project-structure.py` - Analyze project structure for suggestion opportunities
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-suggestions/` - Well-structured feature suggestions
+- `bad-suggestions/` - Examples to avoid
+
+## Links to Other Skills
+
+- **documents**: Use to document suggestion rationale
+- **unit-test**: Consider testability when suggesting features
+- **integration-test**: Consider integration testing when suggesting features
+

package/dist/core/templates/skills/templates/accessibility-checklist.md

@@ -0,0 +1,40 @@
+# Accessibility Checklist (WCAG 2.1 AA)
+
+## Perceivable
+
+- [ ] All images have descriptive alt text
+- [ ] Color is not the only means of conveying information
+- [ ] Text contrast ratio meets 4.5:1 for normal text, 3:1 for large text
+- [ ] Content can be resized up to 200% without loss of functionality
+
+## Operable
+
+- [ ] All functionality available via keyboard
+- [ ] No keyboard traps
+- [ ] Focus indicators visible
+- [ ] Sufficient time limits (if any) can be extended
+- [ ] No content that causes seizures (flashing)
+- [ ] Touch targets at least 44x44px
+
+## Understandable
+
+- [ ] Page titles are descriptive
+- [ ] Form inputs have labels
+- [ ] Error messages are clear and helpful
+- [ ] Language of page is declared
+- [ ] Navigation is consistent
+
+## Robust
+
+- [ ] Valid HTML markup
+- [ ] ARIA attributes used correctly (if needed)
+- [ ] Screen reader compatible
+- [ ] Works with assistive technologies
+
+## Additional Best Practices
+
+- [ ] `prefers-reduced-motion` respected
+- [ ] Skip links for keyboard navigation
+- [ ] Logical tab order
+- [ ] Focus management for modals/dialogs
+