flyee 0.1.0

package/core/workflows/ui-ux-pro-max.md

@@ -0,0 +1,437 @@
+---
+description: Plan and implement UI
+---
+
+---
+description: AI-powered design intelligence with 50+ styles, 95+ color palettes, and automated design system generation
+---
+
+# ui-ux-pro-max
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Workflow
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+> [!CAUTION]
+> **SKILL OBRIGATÓRIA:** Este workflow gera RECOMENDAÇÕES. Para Design System FINAL, seguir skill `ui-ux-discovery` que inclui perguntas granulares ao usuário.
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2.5: User Preference Questions (REQUIRED) ⭐
+
+> [!CAUTION]
+> **BLOQUEADOR:** Antes de finalizar Design System, fazer perguntas granulares ao usuário.
+> Seguir skill `ui-ux-discovery` → PASSO 3: Perguntas Granulares.
+
+**Perguntas por Aspecto:**
+1. 🎨 **CORES** - Manter/Modernizar/Definir manual?
+2. ✏️ **TIPOGRAFIA** - Manter/Modernizar/Definir manual?
+3. 📐 **LAYOUT** - Manter estrutura/Reorganizar/Definir manual?
+4. ✨ **EFEITOS** - Quais incluir? (Glassmorphism, Gradients, Dark mode, etc.)
+5. 🖼️ **LOGO** - Manter/Atualizar/Novo/N/A?
+
+**AGUARDAR** respostas ANTES de gerar Design System final.
+
+### Step 2.6: Store Reference Images (If Provided) ⭐
+
+> **Skill:** `ui-ux-discovery` → PASSO 1.5
+
+Se o usuário fornecer **imagens de referência** (screenshots, mockups, inspirações):
+
+1. **Criar pasta:** `design-system/{projeto}/references/`
+2. **Copiar imagens** para essa pasta
+3. **Documentar** no MASTER.md
+
+```bash
+# Exemplo
+mkdir -p design-system/{projeto}/references/
+cp "{path_imagem}" design-system/{projeto}/references/
+```
+
+> [!CAUTION]
+> **NÃO** deixar imagens de referência apenas no brain/conversation. **SEMPRE** copiar para o projeto.
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+
+To save the design system for hierarchical retrieval across sessions, add `--persist`:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+, `jetpack-compose`
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+---
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected
+
+---
+
+## 🛑 VALIDAÇÃO AUTOMATIZADA (OBRIGATÓRIO)
+
+> [!CAUTION]
+> **BLOQUEADOR:** Antes de marcar UI Styling como completo, você DEVE executar validação.
+> Se QUALQUER violação for encontrada, CORRIJA antes de prosseguir.
+
+### Executar Validação
+
+> **Skill:** `ui-validation`
+
+```bash
+python .agent/skills/ui-validation/scripts/ui_antipattern_check.py .
+```
+
+### Interpretação dos Resultados
+
+| Resultado | Ação |
+|-----------|------|
+| **🔴 ERRORS** | ❌ CORRIGIR antes de prosseguir |
+| **🟡 WARNINGS** | ⚠️ Considerar correção |
+| **✅ PASSED** | ✅ Pode prosseguir |
+
+### Passo 3: Correção Obrigatória
+
+Se violações forem encontradas:
+
+1. **Para emojis**: Importe ícones de `lucide-react` ou `@heroicons/react`
+   ```tsx
+   // ❌ ERRADO
+   <div>🔍</div>
+   
+   // ✅ CORRETO
+   import { MagnifyingGlassIcon } from "@heroicons/react/24/outline";
+   <MagnifyingGlassIcon className="w-6 h-6" />
+   ```
+
+2. **Para cursor-pointer**: Adicione ao className
+   ```tsx
+   // ❌ ERRADO
+   <Link href="/blog">Blog</Link>
+   
+   // ✅ CORRETO
+   <Link href="/blog" className="cursor-pointer hover:text-primary">Blog</Link>
+   ```
+
+### Passo 4: Re-validar
+
+Após correções, execute novamente os comandos. **Só prosseguir quando TODAS as validações passarem.**
+
+---
+
+## 🔗 Workflow Integrations
+
+> [!IMPORTANT]
+> Este workflow é chamado **automaticamente** pelos seguintes workflows:
+
+| Workflow | Fase | Quando Chamado |
+|----------|------|----------------|
+| `/new-project` | Phase 2.5 (Design System) | Após TDD aprovado, antes do Breakdown |
+| `/new-project` | Phase 5.3 (UI Styling) | Durante implementação de componentes UI |
+| `/discovery` | Fase 4 (Design System) | Após TDD, antes de criar tasks |
+| `/legacy-project` | Phase 5.5 (Design System) | Após TDD Reverso aprovado |
+| `/new-task` | Fase 3.7 (UI Styling) | Se feature envolve mudanças de UI |
+| `/create` | Step 4 (Design System) | Antes de Application Building |
+
+### Como é Integrado
+
+**1. Em novos projetos (`/new-project`)**:
+```bash
+# Phase 2.5: Definição inicial do Design System
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "{tipo} {indústria}" --design-system --persist -p "{Projeto}"
+```
+
+**2. Durante implementação (`/new-task`, `/new-project Phase 5.3`)**:
+```bash
+# Verificar guidelines do stack
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "{componente}" --stack {html-tailwind|react|nextjs}
+```
+
+**3. Em projetos legados (`/legacy-project`)**:
+```bash
+# Analisar UI existente e propor melhorias
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "{tipo} {indústria}" --design-system -p "{Projeto}"
+```
+
+### Hierarquia de Design System
+
+```
+design-system/
+├── MASTER.md          ← Source of Truth global (gerado aqui)
+└── pages/
+    ├── dashboard.md   ← Override para dashboard
+    ├── checkout.md    ← Override para checkout
+    └── ...
+```
+
+**Regra de Carregamento:**
+1. Verificar se existe `design-system/pages/{pagina}.md`
+2. Se existe → Usar override
+3. Se não → Usar `design-system/MASTER.md`

package/core/workflows/ux-mobile-optimize.md

@@ -0,0 +1,262 @@
+---
+description: Responsible for proposing mobile-first UX improvements for pages or flows that are already usable
+---
+
+## 1. Purpose (Authority Scope)
+
+Mobile UX Optimization (Governed Proposal Workflow) is responsible for **proposing mobile-first UX improvements** for pages or flows that are already usable, aiming to:
+
+* Reduce cognitive load on mobile
+* Improve action clarity and flow efficiency
+* Enhance perceived usability without redesign
+* Increase effectiveness of existing UI on small screens
+
+### Explicitly NOT allowed:
+
+* Create or modify design tokens
+* Create or modify components
+* Redesign layouts or visual identity
+* Rewrite copy or content
+* Apply changes automatically
+* Bypass Design System or validation gates
+
+---
+
+## 2. Execution Preconditions
+
+```json
+{
+  "ux_mobile": "validated | minor_issues_only",
+  "page": "exists",
+  "page_build": "completed",
+  "design_system": "validated",
+  "authorization": "explicit"
+}
+```
+
+### Rules:
+
+* ❌ Cannot run before `/ux-mobile-validate`
+* ❌ Cannot run if `blocking` issues exist
+* ❌ Cannot run without explicit authorization
+
+---
+
+## 3. Required Inputs
+
+```json
+{
+  "page": "/route",
+  "optimization_goals": [
+    "reduce_cognitive_load",
+    "improve_primary_action",
+    "streamline_interaction"
+  ],
+  "constraints": {
+    "max_proposals": 5,
+    "allowed_scope": "page-build"
+  },
+  "control": {
+    "confidence_level": "low | medium | high",
+    "risk_tolerance": "low | medium",
+    "strict_mode": true
+  }
+}
+```
+
+### Notes:
+
+* `optimization_goals` must be explicitly stated
+* `allowed_scope` is **never** broader than `page-build`
+* `max_proposals` limits AI overreach
+
+---
+
+## 4. Optimization Scope (What can be suggested)
+
+### 4.1 Layout Recomposition (Mobile-Only)
+
+Allowed proposals:
+
+* Reordering existing sections
+* Collapsing content using **existing patterns**
+* Moving secondary content below primary actions
+* Reducing vertical height of sections
+
+❌ No creation of new structures
+❌ No desktop layout changes
+
+---
+
+### 4.2 Action & Flow Optimization
+
+Allowed proposals:
+
+* Re-prioritizing existing CTAs
+* Reducing competing actions
+* Improving visibility of primary action
+* Suggesting sticky behavior **only if already supported**
+
+---
+
+### 4.3 Content Density & Grouping
+
+Allowed proposals:
+
+* Grouping related information
+* Delaying non-essential content
+* Reducing above-the-fold noise
+* Improving scanability
+
+⚠️ Copy is never rewritten
+
+---
+
+### 4.4 Interaction Efficiency
+
+Allowed proposals:
+
+* Reducing interaction steps
+* Avoiding hover-dependent behaviors
+* Improving touch feedback using existing states
+* Minimizing unnecessary gestures
+
+---
+
+## 5. Proposal Model (Structured Output)
+
+Each proposal **must** include:
+
+```json
+{
+  "id": "UXO-001",
+  "goal": "Improve primary CTA clarity on mobile",
+  "current_state": "Primary CTA competes with two secondary actions",
+  "proposal": "Move secondary CTAs below the fold and visually de-emphasize them on mobile",
+  "affected_sections": ["Hero"],
+  "mobile_only": true,
+  "allowed_fix_scope": "page-build",
+  "risk_level": "low | medium",
+  "expected_impact": "medium",
+  "requires_ds_change": false
+}
+```
+
+### Rules:
+
+* `requires_ds_change` must always be `false`
+* `mobile_only` must be `true`
+* If risk is `high` → proposal must be dropped
+
+---
+
+## 6. Output Contract
+
+```json
+{
+  "ux_mobile_optimization": {
+    "status": "completed",
+    "proposal_count": 3,
+    "confidence_level": "medium",
+    "proposals": [ /* proposal objects */ ]
+  }
+}
+```
+
+---
+
+## 7. Next-Step Behavior
+
+### Mandatory rule:
+
+```text
+/ux-mobile-optimize
+→ proposals generated
+→ human approval required
+→ /page-build (extend, scoped)
+```
+
+Example:
+
+```json
+{
+  "next_step": {
+    "action": "/page-build",
+    "mode": "extend",
+    "scope": ["Hero", "Pricing"],
+    "origin": "ux-mobile-optimize"
+  }
+}
+```
+
+❌ Cannot auto-apply changes
+❌ Cannot change scope without approval
+
+---
+
+## 8. Logging & Audit
+
+```json
+{
+  "audit": {
+    "optimized_at": "ISO-8601",
+    "design_system_version": "x.y.z",
+    "ux_mobile_validation_reference": "PASS",
+    "proposal_count": 3,
+    "risk_tolerance": "low"
+  }
+}
+```
+
+---
+
+## 9. Hard Constraints (Non-Negotiable)
+
+* Optimization never creates UI
+* Optimization never alters tokens
+* Optimization never alters visual identity
+* Optimization never bypasses validation
+* Optimization always requires approval
+* Optimization is always mobile-first
+
+---
+
+## 10. Final Project State
+
+```json
+{
+  "ux_mobile": "optimized_pending_apply"
+}
+```
+
+After `/page-build` execution:
+
+```json
+{
+  "ux_mobile": "optimized_applied"
+}
+```
+
+---
+
+## 11. Why This Complements `/ux-mobile-validate`
+
+| Validate           | Optimize            |
+| ------------------ | ------------------- |
+| Detects problems   | Improves experience |
+| Can block flow     | Never blocks        |
+| Enforces usability | Enhances usability  |
+| Reactive           | Proactive           |
+| Mandatory          | Optional            |
+
+Together they create:
+
+> **Mobile UX = Usable by rule, improved by intent**
+
+---
+
+## 12. Canonical Definition
+
+> **`/ux-mobile-optimize` is a governed, proposal-only workflow that improves mobile UX strictly within the boundaries of the existing Design System, components, and page composition — without redesign, mutation, or autonomous execution.**
+
+---