# Architecture

Gears CSS Library is built upon a robust and scalable architecture designed for maintainability and consistency. It combines several well-established methodologies:

- **ITCSS (Inverted Triangle CSS)** for structuring the stylesheet layers.
- **BEM (Block-Element-Modifier)** for naming components.
- **Utility-First** approach for atomic styling.

## ITCSS (Inverted Triangle CSS)

ITCSS is an architectural approach for organizing CSS files in a way that manages specificity and cascade effectively. It arranges CSS rules from generic to specific, from low-specificity to high-specificity, and from far-reaching to localized. This helps prevent specificity wars and makes the stylesheet easier to maintain and scale.

Gears CSS follows the standard ITCSS layers:

1.  **Settings**: Global variables, config, functions. (e.g., `src/settings/tokens.base.css`, `src/settings/tokens.theme.[name].css`)
2.  **Tools**: Mixins, helper functions. (e.g., `src/tools/functions.css`)
3.  **Generic**: Reset/normalize styles, box-sizing. (e.g., `src/generic/generic.css`)
4.  **Elements**: Styling for bare HTML elements (e.g., `h1`, `a`, `button`). (e.g., `src/elements/elements.css`)
5.  **Objects**: Undecorated design patterns, layout primitives (e.g., `container`, `grid`). (e.g., `src/objects/layout.css`)
6.  **Components**: Specific UI components, BEM-named. (e.g., `src/components/button.css`, `src/components/card.css`)
7.  **Utilities**: High-specificity, single-purpose classes, often `!important`. (e.g., `src/utilities/utilities.generated.css`)

The `src/index.css` file imports these layers in the correct ITCSS order, ensuring a predictable cascade.

## BEM (Block-Element-Modifier)

BEM is a methodology that helps you develop a reusable and maintainable front-end codebase. It provides a strict naming convention for CSS classes to ensure clarity and modularity, especially for UI components.

-   **Block**: A standalone entity that is meaningful on its own (e.g., `.button`, `.card`).
-   **Element**: A part of a block that has no standalone meaning and is semantically tied to its block (e.g., `.card__header`, `.card__body`).
-   **Modifier**: A flag on a block or an element. It uses a different appearance or behavior (e.g., `.button--ghost`, `.card--compact`).

Gears CSS encourages the use of BEM for all authored components, making them easy to understand, develop, and maintain.

## Utility-First CSS

While BEM provides structure for components, Gears CSS also embraces a utility-first approach for rapid development and fine-grained control over styling. Utility classes are low-level, single-purpose classes that do one thing well (e.g., `g-m-4` for margin, `g-text-primary` for text color).

-   **Atomic**: Each utility class applies a single CSS property or a small, focused set of properties.
-   **Composable**: Utilities are designed to be composed directly in your HTML, allowing you to build complex designs without writing custom CSS for every variation.
-   **Config-Driven**: Gears CSS' utilities are generated directly from your `css.config.json`, ensuring they align perfectly with your design tokens.
-   **Prefixing**: All Gears CSS utility classes are prefixed with `g-` (e.g., `g-m-2`, `g-p-4`) to prevent naming collisions with other stylesheets.

By combining ITCSS for overall structure, BEM for component encapsulation, and utility-first for granular control, Gears CSS provides a powerful and flexible framework for managing your project's CSS.