Base Layout and Modular Front-End Style Architecture

[DiogoKaster]

1. Context

The existing styling is not modular, leading to inconsistencies in visual identity across projects and user implementations.

To address this, we will introduce a base layout and a modular CSS architecture.
This structure will include:

• An index.css file responsible for orchestrating imports and serving as the entry point for all styles.
• A base.css file containing global rules and foundational styles for all components.
• A theme.css file defining design tokens such as colors, typography, and spacing.

Each project will be able to create its own theme folder, containing component-specific CSS files that override or extend the base styles, while maintaining the same architecture.

2. Goal

The goal is to standardize the layout and styling of components while keeping flexibility for customization.

• Provide a shared structure for all components and layouts.
• Allow projects to override or extend styles without touching the base files.
• Make the front-end easier to maintain, consistent, and scalable.
• Support customization through modular and isolated CSS files.

3. Scope

This issue focuses on creating the base layout and CSS architecture, which includes:

• Creating a index.css, theme.css and base.css file containing global rules and imports.
• Defining a core structure for base components and utilities.
• Enabling per-theme style customization through a mirrored folder structure.
• Ensuring consistent naming and organization of files across all layers.

4. Proposed Folder Structure

resources/
└── css/
    ├── base.css
    ├── theme.css
    ├── index.css
    │── components/
    │       ├── card.css
    │       └── input.css
    └── themes/
        └── theme1/
            ├── index.css  
            ├── base.css
            ├── theme.css
            └── components/
                └── card.css

base.css will define foundational layout rules such as spacing, typography, border-radius, and font families.
theme.css will define design tokens such as colors, backgrounds, and borders.
index.css will act as the main entry point, importing both base.css, theme.css, and all component styles from the components/ directory.
Components under resources/css/components/ (e.g., card.css, input.css) will provide reusable structural styles applied globally across the system.

What is expected

• Base layout renders correctly using the default theme
• When a specific theme overrides variables, those changes must affect the UI.
• Components that aren’t overridden in specific themes must fall back to the base style.