# Utilities

Gears embraces a utility-first approach, providing a comprehensive set of atomic classes that allow for rapid styling directly in your HTML. These utilities are generated based on your `css.config.json` and are designed to be highly composable and predictable.

## General Principles

-   **Atomic**: Each utility class typically applies a single CSS property or a small, focused set of properties.
-   **Config-Driven**: All utilities are generated from your defined `tokens` and `utilities` in `css.config.json`, ensuring consistency with your design system.
-   **Predictable Naming**: Utility classes follow a clear and consistent naming convention: `g-<property-prefix>-<value-code>`.
-   **Prefixing**: All utility classes are prefixed with `g-` to prevent naming collisions with other CSS frameworks or custom styles.
-   **Responsive (Future)**: While not yet implemented, the architecture supports future expansion for responsive utility generation using breakpoints.

## Generated Utilities

Below are examples of the utility classes generated from the default `css.config.json`.

### Margin Utilities (`g-m-`)

These utilities control the `margin` property, using values defined in your `space` tokens.

| Class       | CSS Property      | Description                               |
| :---------- | :---------------- | :---------------------------------------- |
| `g-m-0`     | `margin: var(--g-space-0);` | Sets margin to 0.                         |
| `g-m-1`     | `margin: var(--g-space-1);` | Sets margin to 0.25rem.                   |
| `g-m-2`     | `margin: var(--g-space-2);` | Sets margin to 0.5rem.                    |
| `g-m-3`     | `margin: var(--g-space-3);` | Sets margin to 0.75rem.                   |
| `g-m-4`     | `margin: var(--g-space-4);` | Sets margin to 1rem.                      |
| `g-m-8`     | `margin: var(--g-space-8);` | Sets margin to 2rem.                      |

### Padding Utilities (`g-p-`)

These utilities control the `padding` property, using values defined in your `space` tokens.

| Class       | CSS Property        | Description                               |
| :---------- | :------------------ | :---------------------------------------- |
| `g-p-0`     | `padding: var(--g-space-0);` | Sets padding to 0.                        |
| `g-p-1`     | `padding: var(--g-space-1);` | Sets padding to 0.25rem.                  |
| `g-p-2`     | `padding: var(--g-space-2);` | Sets padding to 0.5rem.                   |
| `g-p-3`     | `padding: var(--g-space-3);` | Sets padding to 0.75rem.                  |
| `g-p-4`     | `padding: var(--g-space-4);` | Sets padding to 1rem.                     |
| `g-p-8`     | `padding: var(--g-space-8);` | Sets padding to 2rem.                     |

### Text Color Utilities (`g-text-`)

These utilities control the `color` property, using values defined in your `colors` tokens.

| Class           | CSS Property              | Description                               |
| :-------------- | :------------------------ | :---------------------------------------- |
| `g-text-primary`| `color: var(--g-colors-primary);` | Sets text color to primary color.         |
| `g-text-accent` | `color: var(--g-colors-accent);`  | Sets text color to accent color.          |
| `g-text-text`   | `color: var(--g-colors-text);`    | Sets text color to default text color.    |

### Display Utilities (`g-d-`)

These utilities control the `display` property, using explicit values.

| Class       | CSS Property      | Description                               |
| :---------- | :---------------- | :---------------------------------------- |
| `g-d-b`     | `display: block;` | Sets display to block.                    |
| `g-d-ib`    | `display: inline-block;` | Sets display to inline-block.             |
| `g-d-f`     | `display: flex;`  | Sets display to flex.                     |
| `g-d-g`     | `display: grid;`  | Sets display to grid.                     |

## Customizing and Extending Utilities

You can easily customize existing utilities or add new ones by modifying the `utilities` section in your `css.config.json` file. Refer to the [Configuration](configuration.md) documentation for a detailed explanation of how to define utility entries.