gh-christianlouis-docuelevate/.github/instructions/frontend.instructions.md

applyTo

applyTo
frontend/**/*

Frontend Instructions

These instructions apply to all files in the frontend/ directory (templates, CSS, JavaScript, images).

Templates (Jinja2)

Location and Structure

• All templates in frontend/templates/
• Use template inheritance with base.html
• Keep templates organized by feature

Template Patterns

{% extends "base.html" %}

{% block title %}Document Upload - DocuElevate{% endblock %}

{% block content %}
<div class="container mx-auto px-4 py-8">
    <h1 class="text-2xl font-bold mb-4">{{ page_title }}</h1>
    
    {% if error_message %}
    <div class="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded mb-4">
        {{ error_message }}
    </div>
    {% endif %}
    
    <form method="post" enctype="multipart/form-data">
        <!-- Form content -->
    </form>
</div>
{% endblock %}

Tailwind CSS Usage

• Use Tailwind utility classes (already configured)
• Follow responsive design: md:, lg: breakpoints
• Use existing color scheme from the project
• Common patterns:
  • Containers: container mx-auto px-4
  • Buttons: bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded
  • Cards: bg-white shadow-md rounded-lg p-6
  • Forms: w-full px-3 py-2 border rounded

Static Files

• CSS files in frontend/static/css/
• JavaScript in frontend/static/js/
• Images in frontend/static/images/
• Reference with {{ url_for('static', path='css/style.css') }}

JavaScript

• Keep JavaScript minimal - prefer server-side rendering
• Use vanilla JavaScript or minimal dependencies
• Place scripts at the end of the body
• Use defer or async for external scripts

<script src="{{ url_for('static', path='js/upload.js') }}" defer></script>

Forms

• Use CSRF protection when needed
• Include proper validation
• Show clear error messages
• Use proper method (GET/POST) and enctype for file uploads

<form method="post" enctype="multipart/form-data">
    <div class="mb-4">
        <label class="block text-gray-700 text-sm font-bold mb-2" for="file">
            Document File
        </label>
        <input 
            type="file" 
            id="file" 
            name="file"
            class="w-full px-3 py-2 border rounded"
            required
        />
    </div>
    <button type="submit" class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
        Upload
    </button>
</form>

Accessibility

• Use semantic HTML elements (nav, main, article, section)
• Include alt text for images
• Use proper heading hierarchy (h1 → h2 → h3)
• Add ARIA labels when needed
• Ensure keyboard navigation works

Error Handling

• Display user-friendly error messages
• Use flash messages for feedback
• Show loading states for async operations

{% with messages = get_flashed_messages(with_categories=true) %}
    {% if messages %}
        {% for category, message in messages %}
        <div class="bg-{{ category }}-100 border border-{{ category }}-400 text-{{ category }}-700 px-4 py-3 rounded mb-4">
            {{ message }}
        </div>
        {% endfor %}
    {% endif %}
{% endwith %}

URL Generation

• Always use url_for() for URLs, never hardcode
• Examples:
  • Routes: {{ url_for('upload_document') }}
  • Static: {{ url_for('static', path='css/style.css') }}
  • API: {{ url_for('api_document', document_id=doc.id) }}

Template Variables

• Check if variables exist before using them
• Use filters for formatting

{% if document %}
    <p>Uploaded: {{ document.created_at|datetime }}</p>
    <p>Size: {{ document.file_size|filesizeformat }}</p>
{% else %}
    <p>No document found</p>
{% endif %}

Common Components

• Follow existing patterns for headers, footers, navigation
• Reuse template blocks and includes
• Keep components modular

{% include 'components/navigation.html' %}
{% include 'components/document_card.html' with document=doc %}

UI/UX Guidelines

• Maintain consistent spacing using Tailwind's scale (4, 8, 16, etc.)
• Use the existing color palette from the design
• Ensure mobile responsiveness
• Show loading indicators for long operations
• Provide feedback for user actions (success/error messages)
• Keep the interface clean and minimal

Performance

• Optimize images (compress, use appropriate formats)
• Minimize JavaScript bundle size
• Use lazy loading for images when appropriate
• Cache static assets