novahiz 0.1.0

package/bundled-skills/apple-hig-expert/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: apple-hig-expert
+description: "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')."
+license: MIT
+metadata:
+  version: 1.1.0
+  author: Alireza Rezvani
+  category: design
+  updated: 2026-06-11
+---
+
+# Apple HIG Expert
+
+Design and audit apps against the Apple Human Interface Guidelines (HIG, [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines)), including the **Liquid Glass** design language. HIG content evolves with each OS release — when a claim matters, verify against the live HIG pages cited in `references/`.
+
+## Before Starting
+
+If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. Then gather:
+
+1. **Platform target**: iOS, macOS, watchOS, or visionOS?
+2. **Current state**: new design or auditing an existing mockup/code?
+3. **App category**: utility, productivity, game, social, etc.
+
+## Modes
+
+- **Mode 1 — Design from scratch**: pick the platform navigation paradigm and layout primitives first (see `references/platform-specifics.md`), then apply typography and semantic color (`references/visual-design.md`).
+- **Mode 2 — HIG audit**: fill in `templates/hig-audit-template.md`, run `scripts/hig_checker.py` on every measurable element, and deliver a scored report (see Worked example below).
+
+## The Compliance Tool
+
+`scripts/hig_checker.py` (stdlib-only) has three subcommands:
+
+```bash
+# 1. Contrast ratio (WCAG formula; pass >= 4.5:1 for normal text)
+python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF"
+# -> Contrast Ratio: 3.26 [FAILED]
+
+# 2. Tap-target size (pass >= 44x44 pt per HIG)
+python3 scripts/hig_checker.py target 32 32
+# -> Tap Target: 32x32 [FAILED]
+
+# 3. Batch audit from JSON -> scorecard (starts at 100, -10 per violation)
+python3 scripts/hig_checker.py batch audit.json
+```
+
+Batch input shape:
+
+```json
+{
+  "checks": [
+    {"type": "contrast", "name": "caption-on-card", "fg": "#8E8E93", "bg": "#FFFFFF"},
+    {"type": "target", "name": "close-button", "w": 32, "h": 32}
+  ]
+}
+```
+
+**Scorecard rubric:** the batch score starts at 100 and subtracts 10 per failed check; violations are listed by element name. 90-100 = ship, 70-80 = fix before release, below 70 = systematic rework. Checks the tool cannot measure (VoiceOver labels, Dynamic Type behavior, Reduce Transparency) are assessed manually via the audit template and tagged with confidence.
+
+## Worked example: iOS settings-screen audit
+
+**Input:** mockup with body text `#1C1C1E` and captions `#8E8E93` on white cards, a 32x32 pt close button, and a 343x50 pt primary CTA.
+
+**Run:**
+
+```bash
+python3 scripts/hig_checker.py batch audit.json
+```
+
+**Output (real):**
+
+```json
+{
+  "score": 80,
+  "violations": [
+    "Contrast 3.26 fails for caption-on-card",
+    "Target 32x32 small for close-button"
+  ]
+}
+```
+
+**Findings → fixes (bottom line first):**
+
+> **HIG score 80/100 — two fixes before release.**
+> 1. Captions fail contrast (3.26 < 4.5). Use `.secondaryLabel` (semantic color) instead of hardcoded `#8E8E93`, or darken to ≥ `#6E6E73` on white. 🟢 verified by tool.
+> 2. Close button is 32x32 pt (< 44x44 minimum). Keep the glyph small but expand the hit region to 44x44 with padding/`contentShape`. 🟢 verified by tool.
+> 3. Manual check: the card uses an ultra-thin material over a photo background — re-test caption contrast against the *busiest* underlying region and with Reduce Transparency on. 🟡 needs device test.
+
+## Core Design Principles
+
+1. **Liquid Glass** — translucent material hierarchy (announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, visionOS 26). In SwiftUI, apply it via the `glassEffect` view modifier; keep hierarchy between content and controls. See `references/visual-design.md`.
+2. **Accessibility first** — VoiceOver labels on every element, 44x44 pt minimum targets, 4.5:1 contrast for normal text (3:1 large text), Dynamic Type support. See `references/accessibility.md`.
+3. **Platform ergonomics** — tab bars/thumb reach on iOS, sidebars + menu bar + shortcuts on macOS, ornaments + gaze states on visionOS, glanceable vertical layouts on watchOS. See `references/platform-specifics.md`.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked: low contrast over translucent layers; interactive elements under 44 pt; icon buttons with no accessibility label; density overload (no breathing room between glass layers).
+
+## Communication
+
+- **Bottom line first** — compliance status before details.
+- **What + Why + How** — "Expand the hit region (What) because 32 pt targets fail the HIG minimum (Why); pad to 44x44 via contentShape (How)."
+- **Confidence tagging** — 🟢 tool-verified / 🟡 needs device test / 🔴 assumed.
+
+## Related Skills
+
+- **ui-design-system**: token-based component systems (not platform HIG rules).
+- **ux-researcher-designer**: persona/research validation (not visual styling).
+- **landing-page-generator**: web marketing pages, not native apps.

package/bundled-skills/apple-hig-expert/references/accessibility.md

@@ -0,0 +1,55 @@
+# Accessibility Compliance Guide
+
+Accessibility isn't a feature; it's a foundational standard. Apple's design philosophy requires apps to be fully usable by everyone, regardless of their physical or cognitive abilities.
+
+## The 4 Pillars of Accessibility
+
+### 1. Perceivable
+Information and UI components must be presentable to users in ways they can perceive.
+- **VoiceOver**: Provide meaningful accessibility labels and hints. Avoid "Button 1". Use "Submit Order" with hint "Double tap to place your order."
+- **Visuals**: Don't rely on color alone to convey meaning (e.g., use icons + color for errors).
+
+### 2. Operable
+User interface components and navigation must be operable.
+- **Tap Targets**: 44x44 points minimum.
+- **Motor Control**: Support Switch Control and AssistiveTouch.
+
+### 3. Understandable
+Information and the operation of the user interface must be understandable.
+- **Predictability**: Use standard Apple UI patterns (Tab Bars, Sidebars) so users already know how they work.
+
+### 4. Robust
+Content must be robust enough to be interpreted by a wide variety of user agents, including assistive technologies.
+
+## Technical Requirements (2026)
+
+### Dynamic Type
+Apps must respond to system-wide font size changes.
+- **Scaling Layouts**: Use Auto Layout or SwiftUI `VStack`/`HStack` that wrap content when fonts get large.
+- **No Clipped Text**: Text should never be truncated unnecessarily.
+
+### Contrast Ratios
+- **Normal Text**: 4.5:1 minimum against its background.
+- **Large Text**: 3:1 minimum.
+- **Liquid Glass Exception**: Be extremely careful with translucency (vibrancy). If a background is too busy, reduce transparency for accessibility.
+
+### Haptics & Audio
+- Provide haptic feedback for primary actions (success, failure, selection change).
+- Ensure all audio content has captions or visual equivalents.
+
+## Checklist for Designers
+
+- [ ] Does the app work in Grayscale mode?
+- [ ] Are all buttons at least 44pt tall?
+- [ ] Is every icon labeled for VoiceOver?
+- [ ] Does the layout remain usable at the largest Dynamic Type size?
+- [ ] Have you tested with "Reduce Transparency" enabled in system settings?
+
+
+## Sources
+
+- Apple HIG — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility
+- Apple HIG — Buttons (44x44 pt minimum hit region): https://developer.apple.com/design/human-interface-guidelines/buttons
+- Apple HIG — Typography (Dynamic Type text styles): https://developer.apple.com/design/human-interface-guidelines/typography
+- Apple Accessibility for developers: https://developer.apple.com/accessibility/
+- WCAG 2.x contrast minimums (4.5:1 / 3:1), which the HIG color guidance mirrors: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html

package/bundled-skills/apple-hig-expert/references/platform-specifics.md

@@ -0,0 +1,48 @@
+# Platform Specific Guidelines
+
+While Apple aims for a unified aesthetic (Liquid Glass), each platform has unique ergonomics and hardware constraints.
+
+## iOS (iPhone)
+Designed for one-handed operation and touch-first input.
+- **Bottom Navigation**: Primary controls should be reachable by the thumb at the bottom (Tab Bars, Toolbars).
+- **Safe Area**: Avoid placing UI near the Dynamic Island or the home indicator.
+- **Dynamic Island**: Use Live Activities and the Dynamic Island for high-value background status (e.g., timers, delivery status).
+
+## macOS (Desktop)
+Designed for precision cursor input and multitasking.
+- **Sidebars**: Use for primary navigation.
+- **Menu Bar**: Always provide standard File, Edit, and View menus.
+- **Windowing**: Support multi-window environments and Split View.
+- **Keyboard Shortcuts**: Every primary action must have a `Cmd` + [Key] equivalent.
+
+## visionOS (Spatial Computing)
+Designed for eyes (gaze) and hands (gestures).
+- **Windows**: Have a physical presence in space. They cast shadows and reflect light.
+- **Ornaments**: Floating controls that attach to the edge of a window.
+- **Gaze-Contingent Feedback**: Elements should react (subtle hover state) when the user looks at them.
+- **Z-Axis**: Use depth to prioritize content. Closer items are more important.
+
+## watchOS (Wrist)
+Designed for "Glances" — 2 to 5 second interactions.
+- **Vertical Layout**: Scroll everything vertically using the Digital Crown.
+- **Complications**: Design for the watch face to provide high-value data at a glance.
+- **Full-Bleed Images**: Use the entire screen to reduce the perception of bezels.
+
+## Platform Differences Table
+
+| Feature | iOS | macOS | visionOS |
+|---------|-----|-------|----------|
+| **Navigation** | Tab Bar / Nav Bar | Sidebar / Menu Bar | Ornaments / Sidebars |
+| **Input** | Touch / Voice | Mouse / Trackpad / Keys | Eyes (Gaze) / Hands |
+| **Typical Dist.** | 6 - 12 inches | 18 - 30 inches | Infinite (Arm's length) |
+| **Aesthetic** | High density | High precision | Spatially grounded |
+
+
+## Sources
+
+- Apple HIG — Designing for iOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-ios
+- Apple HIG — Designing for macOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-macos
+- Apple HIG — Designing for visionOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos
+- Apple HIG — Designing for watchOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos
+- Apple HIG — Ornaments (visionOS): https://developer.apple.com/design/human-interface-guidelines/ornaments
+- Apple HIG — Live Activities / Dynamic Island: https://developer.apple.com/design/human-interface-guidelines/live-activities

package/bundled-skills/apple-hig-expert/references/visual-design.md

@@ -0,0 +1,69 @@
+# Visual Design Guide (Liquid Glass 2026)
+
+This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** design language — announced at WWDC25 (June 9, 2025) and shipped in September 2025 with iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, and visionOS 26. In SwiftUI it is applied with the `glassEffect` view modifier.
+
+## Core Aesthetic: Liquid Glass
+
+Liquid Glass evolves the "Glassmorphism" trend into a more dynamic and physically grounded style.
+
+### 1. Materials and Translucency
+Materials provide background blurs and vibrancy.
+- **Ultra-Thin**: Use for secondary elements like tab bars or small floating buttons.
+- **Thin**: Use for standard menu and sidebar backgrounds.
+- **Thick**: Use for static high-level containers like macOS window backgrounds.
+
+### 2. Vibrancy
+Vibrancy isn't just transparency; it’s a filter that pulls primary colors from the background to make text more readable.
+- **Vibrant Primary**: For headlines and body text.
+- **Vibrant Secondary**: For captions and secondary info.
+
+## Color Palette
+
+### Semantic Colors
+Always use Apple's semantic color system (`systemBlue`, `systemRed`) rather than hardcoded hex values to support:
+- Light / Dark Mode.
+- High Contrast Mode.
+- Dynamic color adjustments in 2026 systems.
+
+### 2. Gradients
+Liquid Glass uses subtle, non-distracting gradients to imply surface curvature.
+
+## Typography: San Francisco
+
+Apple uses the **San Francisco (SF)** family across all platforms.
+
+| Variant | Platform | Usage |
+|---------|----------|-------|
+| **SF Pro** | iOS, macOS | System standard for performance and legibility. |
+| **SF Compact** | watchOS | Optimized for small screens (the Camera app uses SF Compact Rounded as of iOS 26). |
+| **SF Mono** | Dev tools | Monospaced variant for code. |
+| **New York** | All | Serif companion family for editorial contexts. |
+
+Only the families on [developer.apple.com/fonts](https://developer.apple.com/fonts/) (SF Pro, SF Compact, SF Mono, SF Arabic/Hebrew and other language extensions, New York) are available to developers. "SF Camera" was an internal face used in Apple's Camera app, never a public download — do not specify it in design systems.
+
+### Dynamic Type
+You MUST support Dynamic Type.
+- Use system text styles (e.g., `Title 1`, `Body`, `Caption 1`).
+- Design for scale; UI should remain usable when font size is at 300%.
+
+## Spacing and Grid
+
+### The 8pt Rule
+All spacing should be increments of 8 (8pt, 16pt, 24pt, 32pt).
+- **Margins**: Typically 16pt or 24pt for standard layouts.
+- **Tap Targets**: 44pt minimum vertical height.
+
+### Margin Logic
+- **iOS**: Match the Dynamic Island or Safe Area insets.
+- **watchOS**: Maximize the bezel-less display by using rounded corner layouts.
+
+
+## Sources
+
+- Apple HIG — Materials: https://developer.apple.com/design/human-interface-guidelines/materials
+- Apple HIG — Typography: https://developer.apple.com/design/human-interface-guidelines/typography
+- Apple HIG — Color: https://developer.apple.com/design/human-interface-guidelines/color
+- Apple HIG — Layout: https://developer.apple.com/design/human-interface-guidelines/layout
+- Apple Fonts (official SF/New York downloads): https://developer.apple.com/fonts/
+- "Meet Liquid Glass" (WWDC25 session 219): https://developer.apple.com/videos/play/wwdc2025/219/
+- Apple Newsroom, June 9 2025 — new software design announcement: https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/

package/bundled-skills/apple-hig-expert/scripts/hig_checker.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Apple HIG Compliance Checker
+Quantitative checks for tap targets, contrast, and typography.
+"""
+
+import sys
+import argparse
+import json
+import math
+
+def calculate_luminance(hex_color):
+    """Calculates relative luminance for a given hex color."""
+    hex_color = hex_color.lstrip('#')
+    if len(hex_color) != 6:
+        return 0
+    
+    r, g, b = [int(hex_color[i:i+2], 16) / 255.0 for i in (0, 2, 4)]
+    
+    def adjust(c):
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+    
+    return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b)
+
+def check_contrast(fg, bg):
+    """Checks contrast ratio between foreground and background."""
+    l1 = calculate_luminance(fg)
+    l2 = calculate_luminance(bg)
+    
+    if l1 < l2:
+        l1, l2 = l2, l1
+        
+    ratio = (l1 + 0.05) / (l2 + 0.05)
+    return round(ratio, 2)
+
+def main():
+    parser = argparse.ArgumentParser(description="Apple HIG Compliance Checker")
+    subparsers = parser.add_subparsers(dest="command", help="Compliance command")
+    
+    # Contrast command
+    contrast_parser = subparsers.add_parser("contrast", help="Check contrast ratio")
+    contrast_parser.add_argument("fg", help="Foreground Hex (e.g. #FFFFFF)")
+    contrast_parser.add_argument("bg", help="Background Hex (e.g. #000000)")
+    
+    # Target command
+    target_parser = subparsers.add_parser("target", help="Check tap target size")
+    target_parser.add_argument("width", type=int, help="Width in points")
+    target_parser.add_argument("height", type=int, help="Height in points")
+    
+    # Batch command
+    batch_parser = subparsers.add_parser("batch", help="Batch check from JSON")
+    batch_parser.add_argument("file", help="Path to JSON file")
+    
+    args = parser.parse_args()
+    
+    results = {"score": 100, "violations": []}
+    
+    if args.command == "contrast":
+        ratio = check_contrast(args.fg, args.bg)
+        status = "PASSED" if ratio >= 4.5 else "FAILED"
+        print(f"Contrast Ratio: {ratio} [{status}]")
+        if status == "FAILED":
+            print("Recommendation: Increase contrast to at least 4.5:1 for accessibility.")
+            
+    elif args.command == "target":
+        if args.width < 44 or args.height < 44:
+            print(f"Tap Target: {args.width}x{args.height} [FAILED]")
+            print("Recommendation: Minimum tap target size is 44x44 points per Apple HIG.")
+        else:
+            print(f"Tap Target: {args.width}x{args.height} [PASSED]")
+            
+    elif args.command == "batch":
+        try:
+            with open(args.file, 'r') as f:
+                data = json.load(f)
+                # Sample batch processing
+                for item in data.get("checks", []):
+                    if item['type'] == 'contrast':
+                        r = check_contrast(item['fg'], item['bg'])
+                        if r < 4.5:
+                            results["violations"].append(f"Contrast {r} fails for {item.get('name', 'element')}")
+                            results["score"] -= 10
+                    elif item['type'] == 'target':
+                        if item['w'] < 44 or item['h'] < 44:
+                            results["violations"].append(f"Target {item['w']}x{item['h']} small for {item.get('name', 'element')}")
+                            results["score"] -= 10
+                            
+            print(json.dumps(results, indent=2))
+        except Exception as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+            
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

package/bundled-skills/apple-hig-expert/templates/hig-audit-template.md

@@ -0,0 +1,83 @@
+# Apple HIG Audit Scorecard
+
+**App Name:** [Name]
+**Platform:** [iOS / macOS / visionOS / watchOS]
+**Auditor:** [Name]
+**Date:** YYYY-MM-DD
+
+---
+
+## 1. Visual Design & Aesthetic (0-20 pts)
+Score: /20
+
+- [ ] **Liquid Glass Compliance**: Does it use translucency and layers effectively?
+- [ ] **Typography**: Is San Francisco used? Are text styles semantic?
+- [ ] **Color**: Are semantic colors used (Light/Dark mode support)?
+- [ ] **Spacing**: Is the 8pt grid followed?
+
+**Notes:**
+
+---
+
+## 2. Navigation & Layout (0-20 pts)
+Score: /20
+
+- [ ] **Platform Native**: Does it use native paradigms (Tab Bar, Sidebar, etc.)?
+- [ ] **Reachability**: (iOS only) Are primary actions at the bottom?
+- [ ] **Safe Areas**: Are items clear of Dynamic Island / Home Indicator?
+- [ ] **Information Density**: Is there enough white space (Deference)?
+
+**Notes:**
+
+---
+
+## 3. Accessibility (0-30 pts)
+Score: /30
+
+- [ ] **VoiceOver**: All elements have labels and hints?
+- [ ] **Tap Targets**: All buttons min 44x44pt?
+- [ ] **Dynamic Type**: Does the layout scale without clipping?
+- [ ] **Contrast**: Min 4.5:1 ratio for text?
+
+**Notes:**
+
+---
+
+## 4. Interaction & Motion (0-20 pts)
+Score: /20
+
+- [ ] **Feel**: Are animations fluid and spring-based?
+- [ ] **Feedback**: Are haptics used appropriately for actions?
+- [ ] **Predictability**: Do standard gestures (swipe, pinch) work as expected?
+
+**Notes:**
+
+---
+
+## 5. Platform Features (0-10 pts)
+Score: /10
+
+- [ ] **Native Integration**: Does it use Dynamic Island, Live Activities, or Complications?
+- [ ] **Shortcuts**: (macOS) Comprehensive keyboard shortcuts?
+
+**Notes:**
+
+---
+
+## Final Score: /100
+
+### 🟢 85-100: App Store Ready
+Highly compliant. Ready for official review or featuring.
+
+### 🟡 70-84: Needs Polish
+Functional and native, but missing critical design finesse or accessibility details.
+
+### 🔴 <70: High Risk
+Significant violations. Likely to be rejected by App Store review or provide poor UX.
+
+---
+
+## Primary Recommendations:
+1. [Recommendation 1]
+2. [Recommendation 2]
+3. [Recommendation 3]

package/bundled-skills/build-graph/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: build-graph
+description: Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.
+argument-hint: "[full]"
+---
+
+# Build Graph
+
+Build or incrementally update the persistent code knowledge graph for this repository.
+
+## Steps
+
+1. **Check graph status** by calling the `list_graph_stats_tool` MCP tool.
+   - If the graph has never been built (last_updated is null), proceed with a full build.
+   - If the graph exists, proceed with an incremental update.
+
+2. **Build the graph** by calling the `build_or_update_graph_tool` MCP tool:
+   - For first-time setup: `build_or_update_graph_tool(full_rebuild=True)`
+   - For updates: `build_or_update_graph_tool()` (incremental by default)
+
+3. **Verify** by calling `list_graph_stats_tool` again and report the results:
+   - Number of files parsed
+   - Number of nodes and edges created
+   - Languages detected
+   - Any errors encountered
+
+## When to Use
+
+- First time setting up the graph for a repository
+- After major refactoring or branch switches
+- If the graph seems stale or out of sync
+- The graph auto-updates via hooks on edit/commit, so manual builds are rarely needed
+
+## Notes
+
+- The graph is stored as a SQLite database (`.code-review-graph/graph.db`) in the repo root
+- Binary files, generated files, and patterns in `.code-review-graphignore` are skipped
+- Supported languages: Python, TypeScript/JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++