appiq-solution 1.4.8 → 1.5.0

package/bmad-core/data/shadcn-ui-integration.md

@@ -1,388 +0,0 @@
-# shadcn/ui Integration Guide
-
-## 📋 Overview
-
-This guide provides comprehensive integration instructions for shadcn/ui components with MCP @21st-dev/magic tool integration for enhanced React development workflows.
-
-## 🎯 shadcn/ui Framework Support
-
-### What is shadcn/ui?
-
-shadcn/ui is a collection of reusable components built using Radix UI and Tailwind CSS. It's designed to be:
-- **Copy & Paste**: Components you can copy and paste into your apps
-- **Customizable**: Fully customizable and extensible
-- **Accessible**: Built on Radix UI primitives for accessibility
-- **Modern**: Uses the latest React patterns and TypeScript
-
-### Key Features
-
-- **Headless Components**: Built on Radix UI primitives
-- **Tailwind CSS**: Styled with Tailwind CSS utility classes
-- **TypeScript**: Full TypeScript support with proper type definitions
-- **Dark Mode**: Built-in dark mode support
-- **Theming**: Comprehensive theming system
-- **Responsive**: Mobile-first responsive design
-
-## 🛠️ MCP @21st-dev/magic Integration
-
-### MCP Tool Capabilities
-
-The @21st-dev/magic MCP tool provides:
-- **Component Generation**: Generate shadcn/ui components with proper setup
-- **Theme Management**: Manage and customize themes programmatically
-- **Component Customization**: Modify existing components with variations
-- **Template Creation**: Create component templates for reuse
-- **Code Analysis**: Analyze component usage and optimization opportunities
-
-### Setup Instructions
-
-1. **Install MCP Tool**
-```bash
-npm install -g @21st-dev/magic
-```
-
-2. **Configure MCP in Project**
-```json
-// .mcp-config.json
-{
-  "tools": {
-    "@21st-dev/magic": {
-      "enabled": true,
-      "config": {
-        "framework": "react",
-        "ui-library": "shadcn/ui",
-        "styling": "tailwind",
-        "typescript": true
-      }
-    }
-  }
-}
-```
-
-3. **Initialize shadcn/ui**
-```bash
-npx shadcn-ui@latest init
-```
-
-## 🎨 Component Architecture
-
-### Component Structure
-
-```
-src/
-├── components/
-│   ├── ui/                 # shadcn/ui components
-│   │   ├── button.tsx
-│   │   ├── card.tsx
-│   │   ├── dialog.tsx
-│   │   └── ...
-│   ├── custom/            # Custom components
-│   │   ├── data-table.tsx
-│   │   ├── form-builder.tsx
-│   │   └── ...
-│   └── layout/            # Layout components
-│       ├── header.tsx
-│       ├── sidebar.tsx
-│       └── footer.tsx
-├── lib/
-│   ├── utils.ts           # Utility functions (cn, etc.)
-│   └── validations.ts     # Form validation schemas
-└── styles/
-    └── globals.css        # Global styles and CSS variables
-```
-
-### Component Categories
-
-#### Core UI Components
-- **Button**: Various button styles and sizes
-- **Input**: Form input components with validation
-- **Card**: Content containers with headers and footers
-- **Dialog**: Modal dialogs and sheets
-- **Dropdown**: Dropdown menus and select components
-- **Navigation**: Navigation menus and breadcrumbs
-
-#### Data Display
-- **Table**: Data tables with sorting and filtering
-- **Badge**: Status indicators and labels
-- **Avatar**: User profile images and initials
-- **Skeleton**: Loading state placeholders
-- **Progress**: Progress bars and indicators
-
-#### Form Components
-- **Form**: Form wrapper with validation
-- **Label**: Form field labels
-- **Checkbox**: Checkbox inputs
-- **Radio**: Radio button groups
-- **Switch**: Toggle switches
-- **Textarea**: Multi-line text inputs
-
-#### Layout Components
-- **Sheet**: Slide-out panels and drawers
-- **Tabs**: Tabbed content organization
-- **Accordion**: Collapsible content sections
-- **Separator**: Visual content dividers
-- **Scroll Area**: Custom scrollable areas
-
-## 🎯 Development Patterns
-
-### Component Creation with MCP
-
-```typescript
-// Using MCP @21st-dev/magic to generate components
-import { magic } from '@21st-dev/magic';
-
-// Generate a new shadcn/ui component
-const component = await magic.generate({
-  type: 'component',
-  name: 'UserProfile',
-  baseComponent: 'card',
-  props: {
-    user: 'User',
-    showActions: 'boolean',
-    onEdit: '() => void'
-  },
-  styling: {
-    theme: 'default',
-    variant: 'outline'
-  }
-});
-```
-
-### Theme Customization
-
-```css
-/* globals.css - CSS Variables for theming */
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
-    --card: 0 0% 100%;
-    --card-foreground: 222.2 84% 4.9%;
-    --popover: 0 0% 100%;
-    --popover-foreground: 222.2 84% 4.9%;
-    --primary: 221.2 83.2% 53.3%;
-    --primary-foreground: 210 40% 98%;
-    --secondary: 210 40% 96%;
-    --secondary-foreground: 222.2 84% 4.9%;
-    --muted: 210 40% 96%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --accent: 210 40% 96%;
-    --accent-foreground: 222.2 84% 4.9%;
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 210 40% 98%;
-    --border: 214.3 31.8% 91.4%;
-    --input: 214.3 31.8% 91.4%;
-    --ring: 221.2 83.2% 53.3%;
-    --radius: 0.5rem;
-  }
-
-  .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
-    /* ... dark mode variables */
-  }
-}
-```
-
-### Utility Functions
-
-```typescript
-// lib/utils.ts
-import { type ClassValue, clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
-
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
-}
-
-// Form validation with Zod
-import { z } from "zod";
-
-export const userSchema = z.object({
-  name: z.string().min(2, "Name must be at least 2 characters"),
-  email: z.string().email("Invalid email address"),
-  age: z.number().min(18, "Must be at least 18 years old"),
-});
-
-export type User = z.infer<typeof userSchema>;
-```
-
-## 🚀 Integration with BMAD Workflow
-
-### Agent Integration
-
-#### Frontend Developer Agent Enhancement
-```yaml
-# Enhanced commands for shadcn/ui support
-commands:
-  - create-shadcn-component: Generate shadcn/ui component with MCP magic
-  - customize-theme: Customize theme variables and dark mode
-  - optimize-components: Analyze and optimize component usage
-  - generate-form: Create form components with validation
-  - create-data-table: Generate data table with sorting and filtering
-```
-
-#### MCP Tool Integration
-```typescript
-// Integration with MCP tools in development workflow
-interface MCPShadcnIntegration {
-  generateComponent(spec: ComponentSpec): Promise<ComponentCode>;
-  customizeTheme(theme: ThemeConfig): Promise<CSSVariables>;
-  analyzeUsage(project: ProjectStructure): Promise<UsageReport>;
-  optimizeBundle(components: ComponentList): Promise<OptimizationSuggestions>;
-}
-```
-
-### Workflow Integration
-
-1. **Component Planning**: Use MCP to analyze requirements and suggest components
-2. **Generation**: Generate base components with proper TypeScript types
-3. **Customization**: Apply project-specific styling and behavior
-4. **Integration**: Integrate with existing state management and data flow
-5. **Testing**: Generate tests for components with proper mocking
-6. **Optimization**: Analyze bundle size and optimize imports
-
-## 📋 Best Practices
-
-### Component Development
-- **Composition over Inheritance**: Build complex components from simple ones
-- **Prop Drilling Avoidance**: Use React Context for deep prop passing
-- **TypeScript First**: Always define proper TypeScript interfaces
-- **Accessibility**: Ensure all components meet WCAG guidelines
-- **Performance**: Use React.memo and useMemo for expensive operations
-
-### Styling Guidelines
-- **Utility First**: Use Tailwind utility classes primarily
-- **CSS Variables**: Use CSS custom properties for theming
-- **Responsive Design**: Mobile-first responsive approach
-- **Dark Mode**: Support both light and dark themes
-- **Consistent Spacing**: Use consistent spacing scale
-
-### State Management Integration
-```typescript
-// Integration with state management
-interface ComponentWithState {
-  // Zustand integration
-  useStore: <T>(selector: (state: State) => T) => T;
-  
-  // React Query integration
-  useQuery: <T>(key: string, fetcher: () => Promise<T>) => QueryResult<T>;
-  
-  // Form state management
-  useForm: <T>(schema: ZodSchema<T>) => FormMethods<T>;
-}
-```
-
-## 🔧 Development Commands
-
-### Component Generation
-```bash
-# Generate new component with MCP
-npx @21st-dev/magic generate component UserCard --base=card --props="user:User,onEdit:()=>void"
-
-# Add shadcn/ui component
-npx shadcn-ui@latest add button card dialog
-
-# Customize existing component
-npx @21st-dev/magic customize button --variant=ghost --size=lg
-```
-
-### Theme Management
-```bash
-# Generate theme variations
-npx @21st-dev/magic theme create --name=corporate --primary="#1a365d"
-
-# Export theme variables
-npx @21st-dev/magic theme export --format=css --output=theme.css
-```
-
-### Code Analysis
-```bash
-# Analyze component usage
-npx @21st-dev/magic analyze components --report=usage
-
-# Bundle optimization
-npx @21st-dev/magic optimize --target=bundle-size --threshold=100kb
-```
-
-## 🧪 Testing Strategy
-
-### Component Testing
-```typescript
-// Component test with shadcn/ui
-import { render, screen, fireEvent } from '@testing-library/react';
-import { Button } from '@/components/ui/button';
-
-describe('Button Component', () => {
-  it('renders with correct variant', () => {
-    render(<Button variant="destructive">Delete</Button>);
-    
-    const button = screen.getByRole('button', { name: /delete/i });
-    expect(button).toHaveClass('bg-destructive');
-  });
-
-  it('handles click events', () => {
-    const handleClick = jest.fn();
-    render(<Button onClick={handleClick}>Click me</Button>);
-    
-    fireEvent.click(screen.getByRole('button'));
-    expect(handleClick).toHaveBeenCalledTimes(1);
-  });
-});
-```
-
-### Visual Testing
-```typescript
-// Storybook integration for visual testing
-import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from '@/components/ui/button';
-
-const meta: Meta<typeof Button> = {
-  title: 'UI/Button',
-  component: Button,
-  parameters: {
-    layout: 'centered',
-  },
-  tags: ['autodocs'],
-};
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Primary: Story = {
-  args: {
-    variant: 'default',
-    children: 'Button',
-  },
-};
-```
-
-## 🔒 Security Considerations
-
-### Input Validation
-- **Sanitization**: Sanitize all user inputs before rendering
-- **XSS Prevention**: Use proper escaping for dynamic content
-- **CSRF Protection**: Implement CSRF tokens for forms
-- **Content Security Policy**: Configure CSP headers properly
-
-### Component Security
-- **Prop Validation**: Validate all component props
-- **Safe Rendering**: Avoid dangerouslySetInnerHTML
-- **Access Control**: Implement proper role-based access
-- **Audit Dependencies**: Regular security audits of dependencies
-
-## 📊 Performance Optimization
-
-### Bundle Optimization
-- **Tree Shaking**: Import only used components
-- **Code Splitting**: Split components into separate bundles
-- **Lazy Loading**: Lazy load heavy components
-- **Bundle Analysis**: Regular bundle size analysis
-
-### Runtime Performance
-- **Memoization**: Use React.memo for expensive components
-- **Virtual Scrolling**: For large lists and tables
-- **Image Optimization**: Optimize images and use proper formats
-- **Caching**: Implement proper caching strategies
-
-This integration guide ensures shadcn/ui is properly integrated into the BMAD framework with full MCP tool support for enhanced development workflows.

package/bmad-core/tasks/create-flutter-story.md

@@ -1,197 +0,0 @@
-# Create Flutter Story Task
-
-## Overview
-This task creates a detailed Flutter development story following Clean Architecture principles with feature-based organization. The story will include all three layers (data/domain/presentation) and comprehensive testing requirements.
-
-## Prerequisites
-- Flutter PRD document available
-- Flutter architecture document (if applicable)
-- Feature requirements clearly defined
-- UI/UX specifications available
-
-## Task Execution
-
-### Step 1: Gather Requirements
-**Action:** Collect and analyze story requirements
-**Process:**
-1. Read Flutter PRD or feature requirements
-2. Review UI/UX specifications if available
-3. Understand user needs and business value
-4. Identify technical constraints and dependencies
-5. Determine story scope and complexity
-
-**Deliverable:** Clear understanding of feature requirements
-
-### Step 2: Define User Story
-**Action:** Create user story following standard format
-**Process:**
-1. Identify the user persona and role
-2. Define the specific functionality/goal
-3. Articulate the business value/benefit
-4. Add mobile-specific context and usage scenarios
-5. Consider offline/online behavior requirements
-
-**Template:**
-```
-As a [type of user]
-I want [goal/functionality]
-So that [benefit/value]
-
-Mobile Context:
-- Device usage scenario
-- User interaction patterns
-- Performance expectations
-```
-
-### Step 3: Create Acceptance Criteria
-**Action:** Define comprehensive, testable acceptance criteria
-**Process:**
-1. **Functional Criteria:** Define what the feature must do
-2. **UI/UX Criteria:** Material Design 3, responsive design, accessibility
-3. **Technical Criteria:** Clean Architecture, state management, error handling
-4. **Performance Criteria:** Loading times, animations, memory usage
-
-**Quality Check:** Each criterion must be:
-- Specific and measurable
-- Testable with clear pass/fail conditions
-- Aligned with user value and business goals
-
-### Step 4: Break Down Flutter Implementation Tasks
-**Action:** Organize tasks by Flutter Clean Architecture layers
-**Process:**
-
-#### A. Presentation Layer Tasks
-1. **UI Implementation:**
-   - Create feature pages/screens with Material 3 design
-   - Implement custom widgets and components  
-   - Set up responsive layouts for phone/tablet
-   - Add animations and micro-interactions
-   - Implement accessibility features
-
-2. **State Management (Cubit):**
-   - Create Cubit class with business logic coordination
-   - Define State classes with Equatable
-   - Implement state transitions and error handling
-   - Connect UI to Cubit with BlocBuilder/BlocListener
-
-3. **Navigation & Routing:**
-   - Define routes and navigation paths
-   - Implement deep linking (if required)
-   - Add navigation transitions
-
-#### B. Domain Layer Tasks
-1. **Business Entities:**
-   - Create entity classes with Equatable
-   - Define entity relationships and properties
-   - Add entity validation rules
-
-2. **Use Cases:**
-   - Implement use case classes with @injectable
-   - Add business logic and validation
-   - Define Either<Failure, Success> return types
-
-3. **Repository Interfaces:**
-   - Define repository abstract classes
-   - Specify method signatures and return types
-
-#### C. Data Layer Tasks
-1. **Data Models:**
-   - Create model classes with @freezed annotation
-   - Add JSON serialization
-   - Implement model to entity conversion methods
-
-2. **Repository Implementations:**
-   - Implement concrete repository classes
-   - Add error handling and data transformation
-
-3. **Data Sources:**
-   - Create remote data source for API calls
-   - Implement local data source for caching
-   - Add offline-first functionality (if required)
-
-#### D. Cross-Cutting Tasks
-1. **Localization & Theming:**
-   - Add all text content to ARB files
-   - Implement RTL support
-   - Verify dark/light theme compatibility
-
-2. **Testing:**
-   - Unit tests for domain layer
-   - Unit tests for data layer
-   - Widget tests for UI components
-   - Cubit/state management tests
-   - Integration tests for user flows
-
-### Step 5: Add Technical Implementation Details
-**Action:** Provide technical guidance for developers
-**Process:**
-1. List required Flutter dependencies
-2. Define file structure following feature-based architecture
-3. Specify key implementation patterns
-4. Include performance considerations
-5. Add security requirements (if applicable)
-
-### Step 6: Define Testing Requirements
-**Action:** Create comprehensive testing strategy
-**Process:**
-1. **Unit Tests:** Domain and data layer testing with mocks
-2. **Widget Tests:** UI component testing in isolation
-3. **Cubit Tests:** State management testing with bloc_test
-4. **Integration Tests:** End-to-end user flow testing
-5. **Accessibility Tests:** Screen reader and semantic testing
-
-**Coverage Target:** Minimum 80% code coverage, 100% for business logic
-
-### Step 7: Add Development Notes
-**Action:** Include additional guidance and considerations
-**Process:**
-1. Performance optimization tips
-2. Accessibility implementation guidelines
-3. Localization best practices
-4. Code quality standards
-5. Common pitfalls and solutions
-
-### Step 8: Create Definition of Done
-**Action:** Define clear completion criteria
-**Process:**
-1. **Implementation Complete:** All tasks and layers implemented
-2. **Code Quality:** Follows Flutter best practices and standards
-3. **Testing Complete:** All tests written and passing
-4. **Performance Verified:** Meets performance benchmarks
-5. **Documentation:** Code documented and file list updated
-6. **Review Process:** Code review, design review, QA testing completed
-
-## Template Usage
-**Template:** Use `flutter-story-tmpl.yaml` for consistent story structure
-
-## Quality Validation
-Before marking story as complete, verify:
-- [ ] Story follows standard user story format
-- [ ] Acceptance criteria are specific and testable
-- [ ] Tasks cover all Flutter architecture layers
-- [ ] Technical details provide clear implementation guidance  
-- [ ] Testing requirements are comprehensive
-- [ ] Performance and accessibility requirements included
-- [ ] Localization requirements specified
-- [ ] Definition of done is complete and measurable
-
-## Handoff Process
-1. Review story with Product Owner for business value alignment
-2. Review with Tech Lead for technical feasibility
-3. Estimate story points with development team
-4. Ensure all dependencies are identified and available
-5. Confirm story is ready for development sprint
-
-## Success Criteria
-- Story provides complete implementation guidance for developers
-- All acceptance criteria are testable and measurable
-- Technical approach follows Flutter Clean Architecture principles
-- Story scope is appropriate for single sprint completion
-- Dependencies and integration points are clearly identified
-
-## Notes
-- Keep stories focused on single feature or user flow
-- Ensure story can be completed within one sprint (usually 1-2 weeks)
-- Consider breaking large features into multiple stories
-- Always include mobile-specific considerations (performance, battery, offline)
-- Maintain consistency with existing codebase patterns and standards