quality_recticel/py_app/CSS_MODULAR_GUIDE.md

CSS Modular Structure Guide

Overview

This guide explains how to migrate from a monolithic CSS file to a modular CSS structure for better maintainability and organization.

New CSS Structure

app/static/css/
├── base.css          # Global styles, header, buttons, theme
├── login.css         # Login page specific styles
├── dashboard.css     # Dashboard and module cards
├── warehouse.css     # Warehouse module styles
├── etichete.css      # Labels/etiquette module styles (to be created)
├── quality.css       # Quality module styles (to be created)
└── scan.css          # Scan module styles (to be created)

Implementation Strategy

Phase 1: Setup Modular Structure ✅

• Created css/ directory
• Created base.css with global styles
• Created login.css for login page
• Created warehouse.css for warehouse module
• Updated base.html to include modular CSS
• Updated login.html to use new structure

Phase 2: Migration Plan (Next Steps)

1. Extract module-specific styles from style.css:

   • Etiquette/Labels module → etichete.css
   • Quality module → quality.css
   • Scan module → scan.css

2. Update templates to use modular CSS:

   {% block head %}
   <link rel="stylesheet" href="{{ url_for('static', filename='css/module-name.css') }}">
   {% endblock %}
   

3. Clean up original style.css:

   • Remove extracted styles
   • Keep only legacy/common styles temporarily
   • Eventually eliminate when all modules migrated

Template Usage Pattern

Standard Template Structure:

{% extends "base.html" %}
{% block title %}Page Title{% endblock %}

{% block head %}
<!-- Include module-specific CSS -->
<link rel="stylesheet" href="{{ url_for('static', filename='css/module-name.css') }}">
<!-- Page-specific overrides -->
<style>
/* Only use this for page-specific customizations */
</style>
{% endblock %}

{% block content %}
<!-- Page content -->
{% endblock %}

CSS Loading Order

1. base.css - Global styles, header, buttons, theme
2. style.css - Legacy styles (temporary, for backward compatibility)
3. Module-specific CSS (e.g., warehouse.css)
4. Inline <style> blocks for page-specific overrides

Benefits of This Structure

1. Maintainability

• Easy to find and edit module-specific styles
• Reduced conflicts between different modules
• Clear separation of concerns

2. Performance

• Only load CSS needed for specific pages
• Smaller file sizes per page
• Better caching (module CSS rarely changes)

3. Team Development

• Different developers can work on different modules
• Less merge conflicts in CSS files
• Clear ownership of styles

4. Scalability

• Easy to add new modules
• Simple to deprecate old styles
• Clear migration path

Migration Checklist

For Each Template:

• Identify module/page type
• Extract relevant styles to module CSS file
• Update template to include module CSS
• Test styling works correctly
• Remove old styles from style.css

Current Status:

• Login page - Fully migrated
• Warehouse module - Partially migrated (create_locations.html updated)
• Dashboard - CSS created, templates need updating
• Etiquette module - Needs CSS extraction
• Quality module - Needs CSS extraction
• Scan module - Needs CSS extraction

Example: Migrating a Template

Before:

{% block head %}
<style>
.my-module-specific-class {
    /* styles here */
}
</style>
{% endblock %}

After:

1. Move styles to css/module-name.css
2. Update template:

{% block head %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/module-name.css') }}">
{% endblock %}

Best Practices

1. Use semantic naming: warehouse.css, login.css, not page1.css
2. Keep base.css minimal: Only truly global styles
3. Avoid deep nesting: Keep CSS selectors simple
4. Use consistent naming: Follow existing patterns
5. Document changes: Update this guide when adding new modules

Next Steps

1. Extract etiquette module styles to etichete.css
2. Update all etiquette templates to use new CSS
3. Extract quality module styles to quality.css
4. Extract scan module styles to scan.css
5. Gradually remove migrated styles from style.css
6. Eventually remove style.css dependency from base.html