@skyroc/scripts 2.5.1 → 2.5.3

package/templates/admin-root/.agents/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    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 Pro Max 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 (html-tailwind, react, nextjs)")
+    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")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/templates/admin-root/.agents/skills/uniwind/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: uniwind
+description: >
+  Uniwind — Tailwind CSS v4 styling for React Native. Use when adding, building,
+  or debugging components in a React Native project that uses Uniwind classNames.
+  Covers setup, Metro config, global.css, theming, className props, accent-* color
+  props, platform/data/state/responsive variants, CSS variables, custom utilities,
+  withUniwind for third-party components, cn/tailwind-merge, tailwind-variants,
+  safe area utilities, LayoutDirection, gradients, fonts, React Navigation,
+  UI kits, diagnostics, troubleshooting, and Uniwind Pro features. Does not
+  cover NativeWind migration.
+---
+
+# Uniwind
+
+> Uniwind 1.7.0+ / Uniwind Pro 1.2.1+ / Tailwind CSS v4 / React Native 0.81+ / Expo SDK 54+
+
+If user has lower version, recommend updating to 1.7.0+ (free) / 1.2.1+ (Pro) for best experience.
+
+`LayoutDirection` is available from Uniwind 1.8.0+.
+
+Uniwind brings Tailwind CSS v4 to React Native. All core React Native components support the `className` prop out of the box. Styles are compiled at build time — no runtime overhead.
+
+## Critical Rules
+
+1. **Tailwind v4 only** — Use `@import 'tailwindcss'` not `@tailwind base`. Tailwind v3 is not supported.
+2. **Never construct classNames dynamically** — Tailwind scans at build time. `bg-${color}-500` will NOT work. Use complete string literals, mapping objects, or ternaries.
+3. **Never use `cssInterop` or `remapProps`** — Those are NativeWind APIs. Uniwind does not override global components.
+4. **No `tailwind.config.js`** — All config goes in `global.css` via `@theme` and `@layer theme`.
+5. **No ThemeProvider required** — Use `Uniwind.setTheme()` directly.
+6. **`withUniwindConfig` must be the outermost** Metro config wrapper.
+7. **NEVER wrap `react-native` or `react-native-reanimated` components with `withUniwind`** — `View`, `Text`, `Pressable`, `Image`, `TextInput`, `ScrollView`, `FlatList`, `Switch`, `Modal`, `Animated.View`, `Animated.Text`, etc. already have full `className` support built in. Wrapping them with `withUniwind` will break behavior. Only use `withUniwind` for **third-party** components (e.g., `expo-image`, `expo-blur`, `moti`).
+8. **Font families: single font only** — React Native doesn't support fallbacks. Use `--font-sans: 'Roboto-Regular'` not `'Roboto', sans-serif`.
+9. **All theme variants must define the same set of CSS variables** — If `light` defines `--color-primary`, then `dark` and every custom theme must too. Mismatched variables cause runtime errors.
+10. **`accent-` prefix is REQUIRED for non-style color props** — This is crucial. Props like `color` (Button, ActivityIndicator), `tintColor` (Image), `thumbColor` (Switch), `placeholderTextColor` (TextInput) are NOT part of the `style` object. You MUST use the corresponding `{propName}ClassName` prop with `accent-` prefixed classes. Example: `<ActivityIndicator colorClassName="accent-blue-500" />` NOT `<ActivityIndicator className="text-blue-500" />`. Regular Tailwind color classes (like `text-blue-500`) only work on `className` (which maps to `style`). For non-style color props, always use `accent-`.
+11. **rem default is 16px** — NativeWind used 14px. Set `polyfills: { rem: 14 }` in metro config if migrating.
+12. **`cssEntryFile` must be a relative path string** — Use `'./global.css'` not `path.resolve(__dirname, 'global.css')`.
+13. **Deduplicate with `cn()` when mixing custom CSS classes and Tailwind** — Uniwind does NOT auto-deduplicate. If a custom CSS class (`.card { padding: 16px }`) and a Tailwind utility (`p-6`) set the same property, both apply with unpredictable results. Always wrap with `cn('card', 'p-6')` when there's overlap.
+14. **Important utilities are supported** — Tailwind important modifier works in classNames with `!` at the end: `bg-red-500!`, `active:bg-red-500!`, `ios:pt-12!`. Leading `!bg-red-500` syntax is deprecated. Important utilities override non-important utilities for the same style property, but inline `style` still overrides className.
+
+## Reference Routing
+
+Read only relevant bundled reference files under `references/` after identifying the user's task:
+
+- Setup/config install issues: `references/setup.md`
+- React Native component className props, accent color props, or component examples: `references/component-bindings.md`
+- Third-party components, `withUniwind`, dynamic class names, `tailwind-variants`, `cn`, or important utilities: `references/styling-patterns.md`
+- Themes, CSS variables, `ScopedTheme`, `LayoutDirection`, color spaces, or runtime variable APIs: `references/theming.md`
+- Platform, data, state, responsive, or safe-area utilities: `references/variants-and-selectors.md`
+- CSS functions, custom CSS, `@utility`, `@theme`, fonts, or gradients: `references/css-and-utilities.md`
+- React Navigation, UI kits, support matrix, or unsupported classes: `references/integrations.md`
+- Uniwind Pro installation, animations, diagnostics, group variants, default styles, native insets, or theme transitions: `references/pro.md`
+- Broken styles, setup diagnostics, errors, cache issues, FAQ answers, MCP, or related skills: `references/troubleshooting.md`
+
+## Workflow
+
+1. Identify whether user needs setup, styling, theming, variants, integrations, Pro, or troubleshooting help.
+2. Read the matching reference file before giving detailed guidance or editing code.
+3. Apply the Critical Rules above even if the selected reference omits them.
+4. Do not guess Uniwind APIs. If unsure, verify against official docs: https://docs.uniwind.dev/llms-full.txt
+
+## Related Skills
+
+NativeWind migration is intentionally separate. Use the `migrate-nativewind-to-uniwind` skill when the user wants to migrate from NativeWind.

package/templates/admin-root/.agents/skills/uniwind/references/component-bindings.md

@@ -0,0 +1,338 @@
+## Component Bindings
+
+All core React Native components support `className` out of the box. Some have additional className props for sub-styles (like `contentContainerClassName`) and non-style color props (requiring `accent-` prefix).
+
+### Complete Reference
+
+**Legend**: Props marked with ⚡ require the `accent-` prefix. Props in parentheses are platform-specific.
+
+#### View
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+#### Text
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `selectionColorClassName` | `selectionColor` | ⚡ `accent-` |
+
+#### Pressable
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+Supports `active:`, `disabled:`, `focus:` state selectors.
+
+#### Image
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `tintColorClassName` | `tintColor` | ⚡ `accent-` |
+
+#### TextInput
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `cursorColorClassName` | `cursorColor` | ⚡ `accent-` |
+| `selectionColorClassName` | `selectionColor` | ⚡ `accent-` |
+| `placeholderTextColorClassName` | `placeholderTextColor` | ⚡ `accent-` |
+| `selectionHandleColorClassName` | `selectionHandleColor` | ⚡ `accent-` |
+| `underlineColorAndroidClassName` | `underlineColorAndroid` (Android) | ⚡ `accent-` |
+
+Supports `focus:`, `active:`, `disabled:` state selectors.
+
+#### ScrollView
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `contentContainerClassName` | `contentContainerStyle` | — |
+| `endFillColorClassName` | `endFillColor` | ⚡ `accent-` |
+
+#### FlatList
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `contentContainerClassName` | `contentContainerStyle` | — |
+| `columnWrapperClassName` | `columnWrapperStyle` | — |
+| `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — |
+| `ListFooterComponentClassName` | `ListFooterComponentStyle` | — |
+| `endFillColorClassName` | `endFillColor` | ⚡ `accent-` |
+
+#### SectionList
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `contentContainerClassName` | `contentContainerStyle` | — |
+| `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — |
+| `ListFooterComponentClassName` | `ListFooterComponentStyle` | — |
+| `endFillColorClassName` | `endFillColor` | ⚡ `accent-` |
+
+#### VirtualizedList
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `contentContainerClassName` | `contentContainerStyle` | — |
+| `ListHeaderComponentClassName` | `ListHeaderComponentStyle` | — |
+| `ListFooterComponentClassName` | `ListFooterComponentStyle` | — |
+| `endFillColorClassName` | `endFillColor` | ⚡ `accent-` |
+
+#### Switch
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `thumbColorClassName` | `thumbColor` | ⚡ `accent-` |
+| `trackColorOnClassName` | `trackColor.true` (on) | ⚡ `accent-` |
+| `trackColorOffClassName` | `trackColor.false` (off) | ⚡ `accent-` |
+| `ios_backgroundColorClassName` | `ios_backgroundColor` (iOS) | ⚡ `accent-` |
+
+Note: Switch does NOT support `className` (`className?: never` in types). Use only the color-specific className props above. Supports `disabled:` state selector.
+
+#### ActivityIndicator
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `colorClassName` | `color` | ⚡ `accent-` |
+
+#### Button
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `colorClassName` | `color` | ⚡ `accent-` |
+
+Note: Button does not support `className` (no `style` prop on RN Button).
+
+#### Modal
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `backdropColorClassName` | `backdropColor` | ⚡ `accent-` |
+
+#### RefreshControl
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `colorsClassName` | `colors` (Android) | ⚡ `accent-` |
+| `tintColorClassName` | `tintColor` (iOS) | ⚡ `accent-` |
+| `titleColorClassName` | `titleColor` (iOS) | ⚡ `accent-` |
+| `progressBackgroundColorClassName` | `progressBackgroundColor` (Android) | ⚡ `accent-` |
+
+#### ImageBackground
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `imageClassName` | `imageStyle` | — |
+| `tintColorClassName` | `tintColor` | ⚡ `accent-` |
+
+#### SafeAreaView
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+#### KeyboardAvoidingView
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `contentContainerClassName` | `contentContainerStyle` | — |
+
+#### InputAccessoryView
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `backgroundColorClassName` | `backgroundColor` | ⚡ `accent-` |
+
+#### TouchableHighlight
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+| `underlayColorClassName` | `underlayColor` | ⚡ `accent-` |
+
+Supports `active:`, `disabled:` state selectors.
+
+#### TouchableOpacity
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+Supports `active:`, `disabled:` state selectors.
+
+#### TouchableNativeFeedback
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+Supports `active:`, `disabled:` state selectors.
+
+#### TouchableWithoutFeedback
+
+| Prop | Maps to | Prefix |
+|------|---------|--------|
+| `className` | `style` | — |
+
+Supports `active:`, `disabled:` state selectors.
+
+### Usage Examples
+
+```tsx
+import { View, Text, Pressable, TextInput, ScrollView, FlatList, Switch, Image, ActivityIndicator, Modal, RefreshControl, Button } from 'react-native';
+
+// View — basic layout
+<View className="flex-1 bg-background p-4">
+  <Text className="text-foreground text-lg font-bold">Title</Text>
+</View>
+
+// Pressable — with press/focus states
+<Pressable className="bg-primary px-6 py-3 rounded-lg active:opacity-80 active:bg-primary/90 focus:ring-2">
+  <Text className="text-white text-center font-semibold">Press Me</Text>
+</Pressable>
+
+// TextInput — with focus state and accent- color props
+<TextInput
+  className="border border-border rounded-lg px-4 py-2 text-base text-foreground focus:border-primary"
+  placeholderTextColorClassName="accent-muted"
+  selectionColorClassName="accent-primary"
+  cursorColorClassName="accent-primary"
+  selectionHandleColorClassName="accent-primary"
+  underlineColorAndroidClassName="accent-transparent"
+  placeholder="Enter text..."
+/>
+
+// ScrollView — with content container
+<ScrollView className="flex-1" contentContainerClassName="p-4 gap-4">
+  {/* content */}
+</ScrollView>
+
+// FlatList — with all sub-style props
+<FlatList
+  className="flex-1"
+  contentContainerClassName="p-4 gap-3"
+  columnWrapperClassName="gap-3"
+  ListHeaderComponentClassName="pb-4"
+  ListFooterComponentClassName="pt-4"
+  endFillColorClassName="accent-gray-100"
+  numColumns={2}
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+/>
+
+// Switch — no className support, use color-specific props only
+<Switch
+  thumbColorClassName="accent-white"
+  trackColorOnClassName="accent-primary"
+  trackColorOffClassName="accent-gray-300 dark:accent-gray-700"
+  ios_backgroundColorClassName="accent-gray-200"
+/>
+
+// Image — tint color
+<Image className="w-6 h-6" tintColorClassName="accent-primary" source={icon} />
+
+// ActivityIndicator
+<ActivityIndicator className="m-4" colorClassName="accent-primary" size="large" />
+
+// Button — only colorClassName (no className)
+<Button colorClassName="accent-primary" title="Submit" onPress={handleSubmit} />
+
+// Modal — backdrop color
+<Modal className="flex-1" backdropColorClassName="accent-black/50">
+  {/* content */}
+</Modal>
+
+// RefreshControl — platform-specific color props
+<RefreshControl
+  className="p-4"
+  tintColorClassName="accent-primary"
+  titleColorClassName="accent-gray-500"
+  colorsClassName="accent-primary"
+  progressBackgroundColorClassName="accent-white dark:accent-gray-800"
+/>
+
+// ImageBackground — separate image styling
+<ImageBackground
+  className="flex-1 justify-center items-center"
+  imageClassName="opacity-50"
+  tintColorClassName="accent-blue-500"
+  source={bgImage}
+>
+  <Text className="text-white text-2xl font-bold">Overlay</Text>
+</ImageBackground>
+
+// KeyboardAvoidingView
+<KeyboardAvoidingView
+  behavior="padding"
+  className="flex-1 bg-white"
+  contentContainerClassName="p-4 justify-end"
+>
+  <TextInput className="border border-gray-300 rounded-lg p-3" placeholder="Type..." />
+</KeyboardAvoidingView>
+
+// InputAccessoryView
+<InputAccessoryView
+  className="p-4 border-t border-gray-300"
+  backgroundColorClassName="accent-white dark:accent-gray-800"
+>
+  <Button title="Done" onPress={dismissKeyboard} />
+</InputAccessoryView>
+
+// TouchableHighlight — underlay color
+<TouchableHighlight
+  className="bg-blue-500 px-6 py-3 rounded-lg"
+  underlayColorClassName="accent-blue-600 dark:accent-blue-700"
+  onPress={handlePress}
+>
+  <Text className="text-white font-semibold">Press Me</Text>
+</TouchableHighlight>
+```
+
+## The accent- Prefix Pattern
+
+React Native components have props like `color`, `tintColor`, `thumbColor` that are NOT part of the `style` object. To set these via Tailwind classes, use the `accent-` prefix with the corresponding `{propName}ClassName` prop:
+
+```tsx
+// color prop → colorClassName with accent- prefix
+<ActivityIndicator colorClassName="accent-blue-500 dark:accent-blue-400" />
+<Button colorClassName="accent-primary" title="Submit" />
+
+// tintColor prop → tintColorClassName
+<Image className="w-6 h-6" tintColorClassName="accent-red-500" source={icon} />
+
+// thumbColor → thumbColorClassName
+<Switch thumbColorClassName="accent-white" trackColorOnClassName="accent-primary" />
+
+// placeholderTextColor → placeholderTextColorClassName
+<TextInput placeholderTextColorClassName="accent-gray-400 dark:accent-gray-600" />
+```
+
+**CRITICAL Rule**: `className` maps to the `style` prop — it handles layout, typography, backgrounds, borders, etc. But React Native has many color props that live OUTSIDE of `style` (like `color`, `tintColor`, `thumbColor`, `placeholderTextColor`). These require a separate `{propName}ClassName` prop with the `accent-` prefix. Without `accent-`, the class resolves to a style object — but these props expect a plain color string.
+
+```tsx
+// WRONG — className sets style, but ActivityIndicator's color is NOT a style prop
+<ActivityIndicator className="text-blue-500" />  // color will NOT be set
+
+// CORRECT — use the dedicated colorClassName prop with accent- prefix
+<ActivityIndicator colorClassName="accent-blue-500" />  // color IS set to #3b82f6
+
+// WRONG — tintColor is not a style prop on Image
+<Image className="tint-blue-500" source={icon} />  // won't work
+
+// CORRECT
+<Image tintColorClassName="accent-blue-500" source={icon} />
+```