# Development

This section outlines the development workflow for the Gears CSS Library, including how to build the CSS, the project structure, and future development plans.

## Build Process

The Gears CSS Library uses a PostCSS-based build pipeline to process and optimize the CSS. The build process involves:

1.  **Token and Utility Generation**: The `build/generator.js` script reads `css.config.json` and generates `src/settings/tokens.base.css`, `src/settings/tokens.theme.[name].css`, and `src/utilities/utilities.generated.css`.
2.  **PostCSS Processing**: The generated and authored CSS files are then processed by PostCSS, which handles:
    *   `postcss-import`: Resolves `@import` rules.
    *   `postcss-nesting`: Enables CSS nesting syntax.
    *   `autoprefixer`: Adds vendor prefixes to CSS rules.
    *   `cssnano`: Minifies the CSS for production (only in `production` environment).

### Build Command

To generate the CSS files (`dist/gears.css` and `dist/gears.min.css`):

```bash
npm run build
```

This command executes the `bin/gears-cli.js` script, which orchestrates the generation and PostCSS processing.

### Watch Command (Not yet implemented)

```bash
npm run watch
```

This command is intended to watch for changes in your `src` directory or `css.config.json` and automatically rebuild the CSS. It is currently a placeholder and will be implemented in future updates.

## Project Layout

Understanding the project structure is key to contributing to or extending Gears:

```
/gears
  /src
    /settings
      reset.css
      tokens.base.css         <-- generated from config (base tokens)
      tokens.theme.[name].css <-- generated theme overrides
    /tools
      functions.css           <-- helper classes (mixins via comments)
    /generic
      generic.css
    /elements
      elements.css
    /objects
      layout.css
    /components
      /* BEM component modules */
      button.css
      card.css
    /utilities
      utilities.generated.css <-- generated from config
    index.css                 <-- imports layer files in ITCSS order
  /bin
    gears-cli.js              <-- CLI entry (node)
  /build
    generator.js              <-- main generator script used by CLI
  /dist
    gears.css
    gears.min.css
  /docs
    index.md                  <-- Main documentation entry
    ...
  package.json
  postcss.config.cjs
  css.config.json            <-- user-editable config (tokens + utilities + themes)
  README.md                  <-- Project overview
  LICENSE
  .gitignore
```

## Future Improvements (Roadmap)

-   **Responsive Utility Generation**: Implement support for generating responsive utility classes based on configurable breakpoints in `css.config.json`.
-   **Purge Unused Utilities**: Develop a CLI tool or integrate a PostCSS plugin to analyze usage and remove unused utility classes from the final CSS output, further optimizing file size.
-   **Plugin System**: Explore the possibility of a plugin system to allow third-party developers to extend Gears CSS with custom generators for utilities or components.
-   **CSS-in-JS Adapters**: Create adapters or bindings for popular JavaScript frameworks (e.g., React, Vue) to facilitate CSS-in-JS workflows.
-   **Comprehensive Testing**: Expand unit and integration tests for the generator, CLI, and generated CSS output.
-   **Watch Mode Implementation**: Complete the `npm run watch` functionality for automatic rebuilding during development.