---
title: "Frontend Specification Template"
version: "1.0"
author: "VC-SYS Framework"
description: "Comprehensive frontend UI/UX specification template for AI-driven development"
agents:
  owner: "ux-expert"
  editors: ["developer", "architect"]
  readonly: ["qa", "product-owner", "scrum-master"]
---

template:
  sections:
    - id: "header"
      title: "Frontend Specification Header"
      required: true
      elicit: false
      content: |
        # Frontend Specification: {{ProjectName}}
        
        **Created:** {{Date}}
        **Version:** {{Version}}
        **Target Platforms:** {{Platforms}}
        **Primary Users:** {{PrimaryUsers}}
        **Design System:** {{DesignSystem}}

    - id: "overview"
      title: "Project Overview and Goals"
      required: true
      elicit: true
      content: |
        ## Project Overview
        
        ### Purpose
        {{ProjectPurpose}}
        
        ### Key User Goals
        1. {{UserGoal1}}
        2. {{UserGoal2}}
        3. {{UserGoal3}}
        
        ### Success Metrics
        - **User Engagement:** {{EngagementMetrics}}
        - **Performance:** {{PerformanceTargets}}
        - **Accessibility:** {{AccessibilityGoals}}
        
        ### Design Principles
        - {{DesignPrinciple1}}
        - {{DesignPrinciple2}}
        - {{DesignPrinciple3}}

    - id: "tech_stack"
      title: "Frontend Technology Stack"
      required: true
      elicit: true
      content: |
        ## Technology Stack
        
        ### Core Framework
        - **Frontend Framework:** {{Framework}} {{Version}}
        - **Language:** {{Language}}
        - **Build Tool:** {{BuildTool}}
        
        ### UI and Styling
        - **CSS Framework:** {{CSSFramework}}
        - **Component Library:** {{ComponentLibrary}}
        - **Icon Library:** {{IconLibrary}}
        - **Font System:** {{FontSystem}}
        
        ### State Management
        - **State Solution:** {{StateManagement}}
        - **Data Fetching:** {{DataFetching}}
        - **Form Handling:** {{FormHandling}}
        
        ### Development Tools
        - **Package Manager:** {{PackageManager}}
        - **Linting:** {{LintingTools}}
        - **Testing:** {{TestingFramework}}
        - **Dev Server:** {{DevServer}}

    - id: "design_system"
      title: "Design System and Visual Identity"
      required: true
      elicit: true
      content: |
        ## Design System
        
        ### Color Palette
        ```css
        /* Primary Colors */
        --primary: {{PrimaryColor}};
        --primary-foreground: {{PrimaryForeground}};
        
        /* Secondary Colors */
        --secondary: {{SecondaryColor}};
        --secondary-foreground: {{SecondaryForeground}};
        
        /* Accent Colors */
        --accent: {{AccentColor}};
        --accent-foreground: {{AccentForeground}};
        
        /* Semantic Colors */
        --success: {{SuccessColor}};
        --warning: {{WarningColor}};
        --destructive: {{DestructiveColor}};
        --info: {{InfoColor}};
        
        /* Neutral Colors */
        --background: {{BackgroundColor}};
        --foreground: {{ForegroundColor}};
        --muted: {{MutedColor}};
        --border: {{BorderColor}};
        ```
        
        ### Typography
        - **Primary Font:** {{PrimaryFont}}
        - **Secondary Font:** {{SecondaryFont}}
        - **Monospace Font:** {{MonospaceFont}}
        
        **Type Scale:**
        - **Heading 1:** {{H1Size}} / {{H1Weight}}
        - **Heading 2:** {{H2Size}} / {{H2Weight}}
        - **Heading 3:** {{H3Size}} / {{H3Weight}}
        - **Body Text:** {{BodySize}} / {{BodyWeight}}
        - **Caption:** {{CaptionSize}} / {{CaptionWeight}}
        
        ### Spacing System
        ```css
        /* Spacing Scale */
        --space-1: {{Space1}};    /* {{Space1Comment}} */
        --space-2: {{Space2}};    /* {{Space2Comment}} */
        --space-3: {{Space3}};    /* {{Space3Comment}} */
        --space-4: {{Space4}};    /* {{Space4Comment}} */
        --space-5: {{Space5}};    /* {{Space5Comment}} */
        --space-6: {{Space6}};    /* {{Space6Comment}} */
        ```
        
        ### Border Radius
        - **Small:** {{RadiusSmall}}
        - **Medium:** {{RadiusMedium}}
        - **Large:** {{RadiusLarge}}
        - **Full:** {{RadiusFull}}
        
        ### Shadows
        ```css
        --shadow-sm: {{ShadowSmall}};
        --shadow-md: {{ShadowMedium}};
        --shadow-lg: {{ShadowLarge}};
        --shadow-xl: {{ShadowExtraLarge}};
        ```

    - id: "component_library"
      title: "Component Library Specifications"
      required: true
      elicit: true
      content: |
        ## Component Library
        
        ### Form Components
        
        #### Input Field
        - **Variants:** default, filled, outlined
        - **States:** default, focused, error, disabled
        - **Sizes:** sm, md, lg
        - **Required Props:** {{InputRequiredProps}}
        - **Optional Props:** {{InputOptionalProps}}
        
        #### Button
        - **Variants:** primary, secondary, outline, ghost, destructive
        - **Sizes:** sm, md, lg
        - **States:** default, hover, active, disabled, loading
        - **Required Props:** {{ButtonRequiredProps}}
        - **Optional Props:** {{ButtonOptionalProps}}
        
        #### Select/Dropdown
        - **Variants:** {{SelectVariants}}
        - **Multi-select:** {{MultiSelectSupport}}
        - **Search:** {{SearchableSupport}}
        
        ### Layout Components
        
        #### Card
        - **Variants:** {{CardVariants}}
        - **Padding Options:** {{CardPadding}}
        - **Shadow Options:** {{CardShadows}}
        
        #### Grid System
        - **Breakpoints:** {{GridBreakpoints}}
        - **Columns:** {{GridColumns}}
        - **Gutter:** {{GridGutter}}
        
        ### Navigation Components
        
        #### Header/Navigation
        - **Layout:** {{HeaderLayout}}
        - **Mobile Behavior:** {{HeaderMobile}}
        - **Authentication States:** {{HeaderAuthStates}}
        
        #### Sidebar
        - **Collapsible:** {{SidebarCollapsible}}
        - **Mobile Behavior:** {{SidebarMobile}}
        - **Navigation Items:** {{SidebarItems}}
        
        ### Feedback Components
        
        #### Toast/Notification
        - **Types:** success, error, warning, info
        - **Position:** {{ToastPosition}}
        - **Duration:** {{ToastDuration}}
        
        #### Modal/Dialog
        - **Sizes:** {{ModalSizes}}
        - **Backdrop Behavior:** {{ModalBackdrop}}
        - **Focus Management:** {{ModalFocus}}

    - id: "responsive_design"
      title: "Responsive Design Guidelines"
      required: true
      elicit: true
      content: |
        ## Responsive Design
        
        ### Breakpoint Strategy
        ```css
        /* Mobile First Approach */
        /* Base styles: Mobile (320px+) */
        
        @media (min-width: 640px) {
          /* Small tablets and large phones */
          /* {{SmallTabletChanges}} */
        }
        
        @media (min-width: 768px) {
          /* Tablets */
          /* {{TabletChanges}} */
        }
        
        @media (min-width: 1024px) {
          /* Laptops */
          /* {{LaptopChanges}} */
        }
        
        @media (min-width: 1280px) {
          /* Desktops */
          /* {{DesktopChanges}} */
        }
        ```
        
        ### Layout Patterns
        
        #### Mobile (320px - 639px)
        - **Navigation:** {{MobileNavPattern}}
        - **Content Layout:** {{MobileContentLayout}}
        - **Typography:** {{MobileTypography}}
        - **Spacing:** {{MobileSpacing}}
        
        #### Tablet (640px - 1023px)
        - **Navigation:** {{TabletNavPattern}}
        - **Content Layout:** {{TabletContentLayout}}
        - **Grid System:** {{TabletGrid}}
        
        #### Desktop (1024px+)
        - **Navigation:** {{DesktopNavPattern}}
        - **Content Layout:** {{DesktopContentLayout}}
        - **Grid System:** {{DesktopGrid}}
        - **Sidebar Usage:** {{DesktopSidebar}}
        
        ### Touch and Interaction Guidelines
        - **Minimum Touch Target:** {{MinTouchTarget}}
        - **Spacing Between Targets:** {{TouchSpacing}}
        - **Hover States:** {{HoverStates}}
        - **Focus Indicators:** {{FocusIndicators}}

    - id: "accessibility"
      title: "Accessibility Requirements"
      required: true
      elicit: true
      content: |
        ## Accessibility Guidelines
        
        ### WCAG 2.1 Compliance Level
        **Target Level:** {{WCAGLevel}} (AA recommended)
        
        ### Color and Contrast
        - **Text Contrast Ratio:** {{TextContrast}} (4.5:1 minimum for AA)
        - **Large Text Contrast:** {{LargeTextContrast}} (3:1 minimum for AA)
        - **Non-text Elements:** {{NonTextContrast}} (3:1 minimum)
        - **Color Independence:** {{ColorIndependence}}
        
        ### Keyboard Navigation
        - **Tab Order:** {{TabOrder}}
        - **Skip Links:** {{SkipLinks}}
        - **Focus Management:** {{FocusManagement}}
        - **Keyboard Shortcuts:** {{KeyboardShortcuts}}
        
        ### Screen Reader Support
        - **Semantic HTML:** {{SemanticHTML}}
        - **ARIA Labels:** {{ARIALabels}}
        - **Headings Structure:** {{HeadingsStructure}}
        - **Alternative Text:** {{AltText}}
        
        ### Form Accessibility
        - **Label Association:** {{LabelAssociation}}
        - **Error Messages:** {{ErrorMessages}}
        - **Required Fields:** {{RequiredFields}}
        - **Instructions:** {{FormInstructions}}
        
        ### Media and Animation
        - **Reduced Motion:** {{ReducedMotion}}
        - **Auto-playing Media:** {{AutoplayingMedia}}
        - **Video Captions:** {{VideoCaptions}}
        - **Audio Descriptions:** {{AudioDescriptions}}

    - id: "performance"
      title: "Performance Requirements"
      required: true
      elicit: true
      content: |
        ## Performance Guidelines
        
        ### Core Web Vitals Targets
        - **Largest Contentful Paint (LCP):** {{LCPTarget}} (2.5s or less)
        - **First Input Delay (FID):** {{FIDTarget}} (100ms or less)
        - **Cumulative Layout Shift (CLS):** {{CLSTarget}} (0.1 or less)
        
        ### Loading Performance
        - **First Contentful Paint:** {{FCPTarget}}
        - **Time to Interactive:** {{TTITarget}}
        - **Speed Index:** {{SpeedIndexTarget}}
        
        ### Bundle Size Targets
        - **Initial Bundle:** {{InitialBundle}} (500KB or less)
        - **Total Bundle:** {{TotalBundle}} (2MB or less)
        - **Critical Path:** {{CriticalPath}}
        
        ### Optimization Strategies
        
        #### Code Splitting
        - **Route-based Splitting:** {{RouteSplitting}}
        - **Component Splitting:** {{ComponentSplitting}}
        - **Library Splitting:** {{LibrarySplitting}}
        
        #### Asset Optimization
        - **Image Optimization:** {{ImageOptimization}}
        - **Font Loading:** {{FontLoading}}
        - **CSS Optimization:** {{CSSOptimization}}
        - **JavaScript Minification:** {{JSMinification}}
        
        #### Caching Strategy
        - **Static Assets:** {{StaticCaching}}
        - **API Responses:** {{APICaching}}
        - **Service Worker:** {{ServiceWorker}}
        
        ### Network Considerations
        - **3G Performance:** {{ThreeGPerformance}}
        - **Offline Functionality:** {{OfflineFunctionality}}
        - **Progressive Enhancement:** {{ProgressiveEnhancement}}

    - id: "user_flows"
      title: "Key User Flows and Interactions"
      required: true
      elicit: true
      content: |
        ## User Flows
        
        ### Primary User Flow: {{PrimaryFlowName}}
        
        #### Flow Steps
        1. **Entry Point:** {{Flow1Entry}}
           - **Page/Component:** {{Flow1Component}}
           - **User Action:** {{Flow1Action}}
           - **Expected Outcome:** {{Flow1Outcome}}
        
        2. **Step 2:** {{Flow1Step2}}
           - **Page/Component:** {{Flow1Step2Component}}
           - **User Action:** {{Flow1Step2Action}}
           - **Expected Outcome:** {{Flow1Step2Outcome}}
        
        3. **Completion:** {{Flow1Completion}}
           - **Success State:** {{Flow1Success}}
           - **Error Handling:** {{Flow1Error}}
           - **Next Steps:** {{Flow1Next}}
        
        ### Secondary User Flow: {{SecondaryFlowName}}
        
        #### Flow Steps
        1. **Entry Point:** {{Flow2Entry}}
        2. **Process:** {{Flow2Process}}
        3. **Completion:** {{Flow2Completion}}
        
        ### Error States and Edge Cases
        
        #### Loading States
        - **Page Loading:** {{PageLoading}}
        - **Component Loading:** {{ComponentLoading}}
        - **Data Loading:** {{DataLoading}}
        
        #### Error States
        - **Network Error:** {{NetworkError}}
        - **Validation Error:** {{ValidationError}}
        - **Authorization Error:** {{AuthorizationError}}
        - **404 Error:** {{NotFoundError}}
        
        #### Empty States
        - **No Data:** {{NoDataState}}
        - **No Results:** {{NoResultsState}}
        - **First Time User:** {{FirstTimeUser}}
        
        ### Micro-interactions
        - **Button Hover:** {{ButtonHover}}
        - **Form Feedback:** {{FormFeedback}}
        - **Navigation Transitions:** {{NavTransitions}}
        - **Loading Animations:** {{LoadingAnimations}}

validation:
  required_fields:
    - ProjectName
    - Framework
    - CSSFramework
    - PrimaryColor
    - WCAGLevel
  optional_fields:
    - DesignSystem
    - ComponentLibrary
  dependencies:
    - generate-ai-frontend-prompt.md
    - create-doc.md