mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

generalize presets into mosaic profiles with runtime overlays

Browse Source
This commit is contained in:
Jason Woltje
2026-02-17 11:46:12 -06:00
parent 4eac2c76e6
commit 33bbf60bad
15 changed files with 1868 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
profiles/workflows/api-development.json Normal file
View File

@@ -0,0 +1,182 @@
{
"name": "API Development Workflow",
"description": "Standardized workflow for REST/GraphQL API endpoint development",
"workflowType": "api-development",
"applicablePatterns": ["REST", "GraphQL", "WebSocket"],
"phases": {
"planning": {
"description": "API design and specification phase",
"activities": [
"Define API contract and OpenAPI specification",
"Design request/response schemas",
"Plan error handling and status codes",
"Consider rate limiting and pagination",
"Document authentication and authorization requirements"
]
},
"implementation": {
"description": "Core API implementation phase",
"activities": [
"Create controller/resolver with proper routing",
"Implement service layer with business logic",
"Add input validation and sanitization",
"Implement proper error handling",
"Add authentication and authorization guards"
]
},
"testing": {
"description": "Comprehensive API testing phase",
"activities": [
"Write unit tests for service layer",
"Create integration tests for endpoints",
"Test error scenarios and edge cases",
"Validate API documentation accuracy",
"Perform security testing"
]
},
"documentation": {
"description": "API documentation and examples",
"activities": [
"Generate/update OpenAPI documentation",
"Create usage examples and tutorials",
"Document rate limits and quotas",
"Add error code documentation",
"Update API versioning information"
]
}
},
"implementationPatterns": {
"controller": {
"structure": "Thin controller with business logic in services",
"validation": "Use DTOs for input validation",
"responses": "Standardized response format",
"errors": "Consistent error handling middleware",
"documentation": "Comprehensive API documentation decorators"
},
"service": {
"business_logic": "Core business logic implementation",
"data_access": "Repository pattern for data operations",
"transactions": "Database transaction management",
"caching": "Implement caching where appropriate",
"external_apis": "Handle external API integrations"
},
"validation": {
"input": "Validate all input parameters and body data",
"sanitization": "Sanitize inputs to prevent injection attacks",
"authorization": "Verify user permissions for operations",
"rate_limiting": "Implement appropriate rate limiting",
"idempotency": "Support idempotent operations where needed"
},
"responses": {
"success": "Consistent success response format",
"errors": "Standardized error response structure",
"pagination": "Implement cursor or offset pagination",
"filtering": "Support query filtering and sorting",
"versioning": "Handle API versioning appropriately"
}
},
"qualityGates": {
"pre_implementation": [
"API specification reviewed and approved",
"Data models and schemas defined",
"Authentication requirements clarified",
"Rate limiting strategy determined",
"Error handling approach documented"
],
"implementation": [
"Code follows established patterns and conventions",
"Input validation implemented for all parameters",
"Proper error handling and logging added",
"Authentication and authorization enforced",
"Business logic separated from controller logic"
],
"testing": [
"Unit tests cover all service methods",
"Integration tests validate API contracts",
"Error scenarios properly tested",
"Performance tests pass acceptance criteria",
"Security tests identify no critical vulnerabilities"
],
"deployment": [
"API documentation is accurate and complete",
"Monitoring and alerting configured",
"Database migrations applied successfully",
"Configuration validated in target environment",
"Rollback procedures documented and tested"
]
},
"testingStrategy": {
"unit_tests": {
"scope": "Individual service methods and business logic",
"mocking": "Mock external dependencies and database",
"coverage": "Minimum 80% code coverage",
"focus": "Business logic and edge cases"
},
"integration_tests": {
"scope": "Full API endpoint testing with real database",
"scenarios": "Happy path and error scenarios",
"data": "Use test fixtures and factories",
"cleanup": "Clean up test data after each test"
},
"contract_tests": {
"scope": "API contract validation",
"tools": "OpenAPI validation and contract testing",
"versioning": "Backward compatibility testing",
"documentation": "Ensure examples work correctly"
},
"performance_tests": {
"scope": "Load and stress testing",
"metrics": "Response time, throughput, resource usage",
"scenarios": "Normal and peak load conditions",
"bottlenecks": "Identify and address performance issues"
},
"security_tests": {
"scope": "Authentication, authorization, and input validation",
"scenarios": "SQL injection, XSS, authentication bypass",
"tools": "Automated security scanning",
"compliance": "Ensure regulatory compliance requirements"
}
},
"codeTemplates": {
"restController": {
"framework": "universal",
"template": "// REST Controller Template\n@Controller('/api/v1/users')\n@ApiTags('users')\nexport class UsersController {\n constructor(private usersService: UsersService) {}\n\n @Get()\n @ApiOperation({ summary: 'Get all users' })\n @ApiResponse({ status: 200, description: 'Users retrieved successfully' })\n async getUsers(@Query() query: GetUsersDto): Promise<ApiResponse<User[]>> {\n const users = await this.usersService.getUsers(query);\n return { data: users, message: 'Users retrieved successfully' };\n }\n\n @Post()\n @ApiOperation({ summary: 'Create new user' })\n @ApiResponse({ status: 201, description: 'User created successfully' })\n async createUser(@Body() createUserDto: CreateUserDto): Promise<ApiResponse<User>> {\n const user = await this.usersService.createUser(createUserDto);\n return { data: user, message: 'User created successfully' };\n }\n}"
},
"serviceLayer": {
"framework": "universal",
"template": "// Service Layer Template\n@Injectable()\nexport class UsersService {\n constructor(private usersRepository: UsersRepository) {}\n\n async getUsers(query: GetUsersDto): Promise<User[]> {\n try {\n const users = await this.usersRepository.findWithFilters(query);\n return users;\n } catch (error) {\n throw new ServiceException('Failed to retrieve users', error);\n }\n }\n\n async createUser(createUserDto: CreateUserDto): Promise<User> {\n try {\n const existingUser = await this.usersRepository.findByEmail(createUserDto.email);\n if (existingUser) {\n throw new ConflictException('User with this email already exists');\n }\n \n const user = await this.usersRepository.create(createUserDto);\n return user;\n } catch (error) {\n throw new ServiceException('Failed to create user', error);\n }\n }\n}"
},
"integrationTest": {
"framework": "universal",
"template": "// Integration Test Template\ndescribe('Users API', () => {\n let app: TestingModule;\n let httpServer: any;\n\n beforeAll(async () => {\n app = await Test.createTestingModule({\n imports: [AppModule],\n }).compile();\n \n httpServer = app.createNestApplication();\n await httpServer.init();\n });\n\n describe('GET /api/v1/users', () => {\n it('should return users list', async () => {\n const response = await request(httpServer)\n .get('/api/v1/users')\n .expect(200);\n\n expect(response.body.data).toBeInstanceOf(Array);\n expect(response.body.message).toBe('Users retrieved successfully');\n });\n\n it('should handle pagination', async () => {\n const response = await request(httpServer)\n .get('/api/v1/users?page=1&limit=10')\n .expect(200);\n\n expect(response.body.data.length).toBeLessThanOrEqual(10);\n });\n });\n\n describe('POST /api/v1/users', () => {\n it('should create new user', async () => {\n const newUser = {\n name: 'John Doe',\n email: 'john@example.com'\n };\n\n const response = await request(httpServer)\n .post('/api/v1/users')\n .send(newUser)\n .expect(201);\n\n expect(response.body.data.name).toBe(newUser.name);\n expect(response.body.data.email).toBe(newUser.email);\n });\n\n it('should validate required fields', async () => {\n const response = await request(httpServer)\n .post('/api/v1/users')\n .send({})\n .expect(400);\n\n expect(response.body.errors).toBeDefined();\n });\n });\n});"
}
},
"bestPractices": [
"Use consistent REST conventions for endpoint naming",
"Implement proper HTTP status codes for different scenarios",
"Add comprehensive input validation and sanitization",
"Use DTOs for request/response data structures",
"Implement proper error handling with meaningful messages",
"Add rate limiting to prevent API abuse",
"Use pagination for endpoints returning large datasets",
"Implement API versioning strategy from the start",
"Add comprehensive logging for debugging and monitoring",
"Use dependency injection for better testability",
"Implement proper authentication and authorization",
"Add API documentation with examples and use cases"
],
"commonPitfalls": [
"Putting business logic directly in controllers",
"Not validating input parameters properly",
"Inconsistent error handling and response formats",
"Missing or outdated API documentation",
"Not implementing proper pagination",
"Ignoring rate limiting and abuse prevention",
"Poor error messages that don't help clients",
"Not versioning APIs properly",
"Missing or inadequate logging",
"Not testing error scenarios thoroughly",
"Exposing sensitive information in error responses",
"Not handling database connection failures gracefully"
]
}

201
profiles/workflows/frontend-component.json Normal file
View File

@@ -0,0 +1,201 @@
{
"name": "Frontend Component Development",
"description": "Standardized workflow for React/Vue component development with accessibility and testing",
"workflowType": "frontend-component",
"applicablePatterns": ["React", "Vue", "Angular", "Web Components"],
"phases": {
"design": {
"description": "Component design and specification phase",
"activities": [
"Define component API and props interface",
"Create component design system documentation",
"Plan responsive behavior and breakpoints",
"Design accessibility features and ARIA labels",
"Consider component composition and reusability"
]
},
"implementation": {
"description": "Core component implementation phase",
"activities": [
"Create component with TypeScript interfaces",
"Implement responsive styling with CSS/Tailwind",
"Add accessibility features (ARIA, keyboard navigation)",
"Implement component state management",
"Add proper error boundaries and loading states"
]
},
"testing": {
"description": "Comprehensive component testing phase",
"activities": [
"Write unit tests for component logic",
"Create integration tests with user interactions",
"Test accessibility with screen readers",
"Validate responsive behavior across devices",
"Test component with different prop combinations"
]
},
"documentation": {
"description": "Component documentation and examples",
"activities": [
"Create Storybook stories for all variants",
"Document component API and usage examples",
"Add accessibility guidelines and best practices",
"Create interactive documentation",
"Document component performance characteristics"
]
}
},
"implementationPatterns": {
"structure": {
"functional": "Use functional components with hooks",
"typescript": "Define proper TypeScript interfaces for props",
"composition": "Design for component composition and reusability",
"separation": "Separate logic, presentation, and styling concerns",
"naming": "Use descriptive and consistent naming conventions"
},
"styling": {
"responsive": "Mobile-first responsive design approach",
"design_tokens": "Use design tokens for consistency",
"css_modules": "Scoped styling to prevent conflicts",
"accessibility": "Ensure sufficient color contrast and focus indicators",
"dark_mode": "Support light and dark theme variations"
},
"accessibility": {
"semantic_html": "Use semantic HTML elements when possible",
"aria_labels": "Add appropriate ARIA labels and descriptions",
"keyboard_nav": "Implement full keyboard navigation support",
"screen_readers": "Ensure screen reader compatibility",
"focus_management": "Proper focus management and indicators"
},
"state_management": {
"local_state": "Use useState for component-local state",
"side_effects": "Use useEffect with proper cleanup",
"performance": "Use useMemo and useCallback for optimization",
"context": "Use React Context for component tree state",
"forms": "Controlled components with proper validation"
},
"error_handling": {
"boundaries": "Implement error boundaries for error containment",
"validation": "Input validation with user-friendly messages",
"loading_states": "Proper loading and skeleton states",
"fallbacks": "Graceful degradation for component failures",
"user_feedback": "Clear feedback for user actions"
}
},
"qualityGates": {
"design": [
"Component API designed with reusability in mind",
"Accessibility requirements identified and documented",
"Responsive behavior planned for all breakpoints",
"Design tokens and styling approach determined",
"Component composition strategy defined"
],
"implementation": [
"TypeScript interfaces defined for all props",
"Component implements planned accessibility features",
"Responsive behavior works across all target devices",
"Component follows established coding patterns",
"Error handling and edge cases addressed"
],
"testing": [
"Unit tests cover all component logic and edge cases",
"Accessibility tests pass with screen reader testing",
"Integration tests validate user interaction flows",
"Visual regression tests prevent styling issues",
"Performance tests meet established benchmarks"
],
"documentation": [
"Storybook stories demonstrate all component variants",
"API documentation is complete and accurate",
"Usage examples and best practices documented",
"Accessibility guidelines provided",
"Performance characteristics documented"
]
},
"testingStrategy": {
"unit_tests": {
"scope": "Component logic, prop handling, and state changes",
"tools": "React Testing Library, Jest",
"coverage": "Minimum 85% code coverage",
"focus": "User interactions and business logic"
},
"accessibility_tests": {
"scope": "ARIA labels, keyboard navigation, screen reader compatibility",
"tools": "axe-core, @testing-library/jest-dom",
"manual": "Manual testing with actual screen readers",
"standards": "WCAG 2.1 AA compliance"
},
"visual_tests": {
"scope": "Component appearance across different states",
"tools": "Chromatic, Percy, or similar visual testing",
"devices": "Test across multiple device sizes",
"themes": "Test light/dark theme variations"
},
"integration_tests": {
"scope": "Component behavior within larger application context",
"user_flows": "End-to-end user interaction scenarios",
"data_flow": "Test with real or realistic data",
"performance": "Component performance under load"
},
"responsive_tests": {
"scope": "Component behavior across different screen sizes",
"breakpoints": "Test all defined responsive breakpoints",
"orientation": "Portrait and landscape orientations",
"devices": "Physical device testing when possible"
}
},
"codeTemplates": {
"reactComponent": {
"framework": "React",
"template": "import React, { useState, useEffect, useCallback } from 'react';\nimport { cn } from '@/lib/utils';\n\ninterface ComponentNameProps {\n /** Primary content for the component */\n children?: React.ReactNode;\n /** Additional CSS class names */\n className?: string;\n /** Component variant */\n variant?: 'primary' | 'secondary' | 'outline';\n /** Component size */\n size?: 'sm' | 'md' | 'lg';\n /** Disabled state */\n disabled?: boolean;\n /** Click handler */\n onClick?: () => void;\n}\n\n/**\n * ComponentName - Brief description of what this component does\n * \n * @example\n * <ComponentName variant=\"primary\" size=\"md\">\n * Content goes here\n * </ComponentName>\n */\nexport const ComponentName: React.FC<ComponentNameProps> = ({\n children,\n className,\n variant = 'primary',\n size = 'md',\n disabled = false,\n onClick,\n ...props\n}) => {\n const [isActive, setIsActive] = useState(false);\n\n const handleClick = useCallback(() => {\n if (!disabled && onClick) {\n onClick();\n }\n }, [disabled, onClick]);\n\n const handleKeyDown = useCallback((event: React.KeyboardEvent) => {\n if (event.key === 'Enter' || event.key === ' ') {\n event.preventDefault();\n handleClick();\n }\n }, [handleClick]);\n\n return (\n <button\n className={cn(\n // Base styles\n 'inline-flex items-center justify-center rounded-md font-medium transition-colors',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',\n \n // Variant styles\n {\n 'bg-primary text-primary-foreground hover:bg-primary/90': variant === 'primary',\n 'bg-secondary text-secondary-foreground hover:bg-secondary/80': variant === 'secondary',\n 'border border-input hover:bg-accent hover:text-accent-foreground': variant === 'outline',\n },\n \n // Size styles\n {\n 'h-8 px-3 text-sm': size === 'sm',\n 'h-10 px-4 py-2': size === 'md',\n 'h-12 px-6 text-lg': size === 'lg',\n },\n \n // State styles\n {\n 'opacity-50 cursor-not-allowed': disabled,\n },\n \n className\n )}\n disabled={disabled}\n onClick={handleClick}\n onKeyDown={handleKeyDown}\n role=\"button\"\n tabIndex={disabled ? -1 : 0}\n aria-disabled={disabled}\n {...props}\n >\n {children}\n </button>\n );\n};\n\nComponentName.displayName = 'ComponentName';"
},
"componentTest": {
"framework": "React Testing Library",
"template": "import { render, screen, fireEvent, waitFor } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { axe, toHaveNoViolations } from 'jest-axe';\nimport { ComponentName } from './ComponentName';\n\n// Extend Jest matchers\nexpect.extend(toHaveNoViolations);\n\ndescribe('ComponentName', () => {\n const user = userEvent.setup();\n\n it('renders with default props', () => {\n render(<ComponentName>Test Content</ComponentName>);\n \n const button = screen.getByRole('button', { name: 'Test Content' });\n expect(button).toBeInTheDocument();\n expect(button).toHaveClass('bg-primary'); // default variant\n });\n\n it('handles click events', async () => {\n const handleClick = jest.fn();\n render(\n <ComponentName onClick={handleClick}>\n Click me\n </ComponentName>\n );\n\n const button = screen.getByRole('button', { name: 'Click me' });\n await user.click(button);\n \n expect(handleClick).toHaveBeenCalledTimes(1);\n });\n\n it('supports keyboard navigation', async () => {\n const handleClick = jest.fn();\n render(\n <ComponentName onClick={handleClick}>\n Press Enter\n </ComponentName>\n );\n\n const button = screen.getByRole('button', { name: 'Press Enter' });\n button.focus();\n \n await user.keyboard('{Enter}');\n expect(handleClick).toHaveBeenCalledTimes(1);\n \n await user.keyboard(' ');\n expect(handleClick).toHaveBeenCalledTimes(2);\n });\n\n it('handles disabled state correctly', async () => {\n const handleClick = jest.fn();\n render(\n <ComponentName disabled onClick={handleClick}>\n Disabled\n </ComponentName>\n );\n\n const button = screen.getByRole('button', { name: 'Disabled' });\n expect(button).toBeDisabled();\n expect(button).toHaveAttribute('aria-disabled', 'true');\n \n await user.click(button);\n expect(handleClick).not.toHaveBeenCalled();\n });\n\n it('applies correct variant styles', () => {\n const { rerender } = render(\n <ComponentName variant=\"secondary\">\n Secondary\n </ComponentName>\n );\n \n let button = screen.getByRole('button');\n expect(button).toHaveClass('bg-secondary');\n \n rerender(\n <ComponentName variant=\"outline\">\n Outline\n </ComponentName>\n );\n \n button = screen.getByRole('button');\n expect(button).toHaveClass('border');\n });\n\n it('has no accessibility violations', async () => {\n const { container } = render(\n <ComponentName>\n Accessible Button\n </ComponentName>\n );\n \n const results = await axe(container);\n expect(results).toHaveNoViolations();\n });\n\n it('supports custom className', () => {\n render(\n <ComponentName className=\"custom-class\">\n Custom\n </ComponentName>\n );\n \n const button = screen.getByRole('button');\n expect(button).toHaveClass('custom-class');\n });\n});"
},
"storybookStory": {
"framework": "Storybook",
"template": "import type { Meta, StoryObj } from '@storybook/react';\nimport { ComponentName } from './ComponentName';\n\nconst meta: Meta<typeof ComponentName> = {\n title: 'Components/ComponentName',\n component: ComponentName,\n parameters: {\n layout: 'centered',\n docs: {\n description: {\n component: 'A versatile button component with multiple variants and sizes.',\n },\n },\n },\n argTypes: {\n variant: {\n control: 'select',\n options: ['primary', 'secondary', 'outline'],\n description: 'The visual variant of the button',\n },\n size: {\n control: 'select', \n options: ['sm', 'md', 'lg'],\n description: 'The size of the button',\n },\n disabled: {\n control: 'boolean',\n description: 'Whether the button is disabled',\n },\n onClick: {\n action: 'clicked',\n description: 'Function called when button is clicked',\n },\n },\n};\n\nexport default meta;\ntype Story = StoryObj<typeof meta>;\n\n// Default story\nexport const Default: Story = {\n args: {\n children: 'Button',\n variant: 'primary',\n size: 'md',\n disabled: false,\n },\n};\n\n// Variants showcase\nexport const Variants: Story = {\n render: () => (\n <div className=\"flex gap-4\">\n <ComponentName variant=\"primary\">Primary</ComponentName>\n <ComponentName variant=\"secondary\">Secondary</ComponentName>\n <ComponentName variant=\"outline\">Outline</ComponentName>\n </div>\n ),\n};\n\n// Sizes showcase\nexport const Sizes: Story = {\n render: () => (\n <div className=\"flex items-center gap-4\">\n <ComponentName size=\"sm\">Small</ComponentName>\n <ComponentName size=\"md\">Medium</ComponentName>\n <ComponentName size=\"lg\">Large</ComponentName>\n </div>\n ),\n};\n\n// Disabled state\nexport const Disabled: Story = {\n args: {\n children: 'Disabled Button',\n disabled: true,\n },\n};\n\n// Interactive example\nexport const Interactive: Story = {\n render: () => {\n const [count, setCount] = React.useState(0);\n return (\n <div className=\"text-center\">\n <p className=\"mb-4\">Count: {count}</p>\n <ComponentName onClick={() => setCount(count + 1)}>\n Increment\n </ComponentName>\n </div>\n );\n },\n};"
}
},
"accessibilityRequirements": [
"Use semantic HTML elements when possible (button, input, etc.)",
"Provide meaningful alt text for images",
"Ensure sufficient color contrast (4.5:1 for normal text)",
"Support keyboard navigation for all interactive elements",
"Use ARIA labels and descriptions where needed",
"Implement proper focus management and indicators",
"Support screen readers with appropriate ARIA attributes",
"Test with actual assistive technologies",
"Provide skip links for navigation",
"Use proper heading hierarchy",
"Ensure form labels are properly associated",
"Implement error states with clear messaging"
],
"performanceOptimizations": [
"Use React.memo for components that receive stable props",
"Implement useMemo for expensive calculations",
"Use useCallback for event handlers passed to child components",
"Optimize images with proper formats and lazy loading",
"Implement virtualization for large lists",
"Use code splitting for large components",
"Minimize bundle size by importing only needed modules",
"Use CSS-in-JS efficiently to avoid style recalculations",
"Implement proper error boundaries to prevent crashes",
"Monitor component re-render frequency and optimize"
],
"bestPractices": [
"Design components for reusability and composition",
"Use TypeScript for better development experience and catch errors",
"Follow accessibility guidelines from the start",
"Write comprehensive tests including accessibility tests",
"Document components with clear examples and usage",
"Use consistent naming conventions across components",
"Implement proper error handling and loading states",
"Consider mobile-first responsive design",
"Use design tokens for consistent styling",
"Optimize for performance without premature optimization",
"Follow the principle of least privilege for component APIs",
"Use proper semantic HTML for better accessibility"
]
}

196
profiles/workflows/testing-automation.json Normal file
View File

File diff suppressed because one or more lines are too long