# Gears CSS Library
## Table of Contents
- [Introduction](#introduction)
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [HTML Example](#html-example)
- [Theming](#theming)
- [Configuration (`css.config.json`)](#configuration-cssconfigjson)
- [Tokens](#tokens)
- [Themes](#themes)
- [Utilities](#utilities)
- [Extending Tokens / Adding Themes](#extending-tokens--adding-themes)
- [Development](#development)
- [Build](#build)
- [Watch (Not yet implemented)](#watch-not-yet-implemented)
- [Project Layout](#project-layout)
- [Naming Conventions](#naming-conventions)
- [Accessibility & Best Practices](#accessibility--best-practices)
- [License](#license)
## Introduction
Gears is an atomic, utility-first CSS library designed for modern web development. It follows a robust architecture combining ITCSS layering, BEM naming for components, and a utility-first approach for rapid and consistent styling. With config-driven tokens and comprehensive theme support, Gears provides a flexible and maintainable solution for your project's styling needs.
## Features
- **ITCSS Architecture**: Organized into distinct layers (settings, tools, generic, elements, objects, components, utilities) for improved maintainability, scalability, and specificity management.
- **BEM Naming**: Clear and consistent Block-Element-Modifier naming conventions for components, enhancing readability and collaboration.
- **Utility-First**: A comprehensive set of atomic utility classes for applying single-purpose styles quickly and efficiently.
- **Config-Driven**: Easily customize design tokens (colors, spacing, typography), utility classes, and theme presets through a simple `css.config.json` file.
- **Theme Support**: Built-in light/dark/custom theme capabilities implemented with CSS custom properties, allowing for dynamic theme switching.
- **PostCSS Powered**: Leverages PostCSS for modern CSS features like nesting, custom properties, and autoprefixing, while maintaining a vanilla CSS feel.
- **NPM Ready**: Designed as an npm package for easy integration into JavaScript projects.
## Quick Start
### Installation
To get started, install Gears CSS via npm:
```bash
npm install gears
```
### Usage
#### Import in JavaScript (e.g., in your main JS file or a bundler entry point)
```javascript
import 'gears-css/dist/gears.css';
// Or for the minified version:
// import 'gears-css/dist/gears.min.css';
```
#### Link in HTML (e.g., via CDN or if serving directly)
```html
```
### HTML Example
Combine BEM-named components with utility classes for flexible styling:
```html
Card Title
This is the card body content.
This text uses the primary color.
This is a flex container with primary background.
```
## Theming
Gears provides robust theme support using CSS custom properties. You can switch themes dynamically by setting the `data-theme` attribute on the `` element.
```javascript
// Set the 'dark' theme
document.documentElement.setAttribute('data-theme','dark');
// Remove the theme (reverts to the default/light theme defined in css.config.json)
document.documentElement.removeAttribute('data-theme');
```
## Configuration (`css.config.json`)
The `css.config.json` file is the heart of Gears' customization. It allows you to define your design tokens, utility classes, and theme presets.
```json
{
"name": "gears",
"version": "0.1.0",
"tokens": {
"colors": {
"primary": "#0b76ff",
"accent": "#ff7ab6",
"text": "#111111",
"bg": "#ffffff"
},
"space": {
"0": "0",
"1": "0.25rem",
"2": "0.5rem",
"3": "0.75rem",
"4": "1rem",
"8": "2rem"
},
"radius": {
"sm": "4px",
"md": "8px",
"lg": "12px"
},
"font": {
"base": "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial"
}
},
"themes": {
"light": {
"colors": {
"bg": "#ffffff",
"text": "#111111",
"primary": "#0b76ff"
}
},
"dark": {
"colors": {
"bg": "#0b0b0b",
"text": "#f2f2f2",
"primary": "#66a6ff"
}
}
},
"utilities": {
"margin": {
"prefix": "g-m",
"props": ["margin"],
"values": ["0","1","2","3","4","8"]
},
"padding": {
"prefix": "g-p",
"props": ["padding"],
"values": ["0","1","2","3","4","8"]
},
"text": {
"prefix": "g-text",
"props": ["color"],
"values": ["primary","accent","text"]
},
"display": {
"prefix": "g-d",
"props": ["display"],
"values": { "b": "block", "ib":"inline-block", "f":"flex", "g":"grid" }
}
}
}
```
### Tokens
The `tokens` section defines your design system's foundational values. These are generated as CSS custom properties (e.g., `--g-colors-primary`, `--g-space-1`) under the `:root` selector.
- **`colors`**: Define your color palette.
- **`space`**: Define consistent spacing units.
- **`radius`**: Define border-radius values.
- **`font`**: Define font families and other typographic settings.
### Themes
The `themes` section allows you to define different visual themes for your application. Each theme is an object where keys are theme names (e.g., `light`, `dark`). Inside each theme, you can override any of the base tokens. These overrides are generated as CSS custom properties under a `[data-theme=""]` selector.
### Utilities
The `utilities` section is used to define atomic utility classes. Each utility entry specifies:
- **`prefix`**: A short prefix for the utility class (e.g., `g-m` for margin).
- **`props`**: An array of CSS properties this utility applies (e.g., `["margin"]`).
- **`values`**: An array or object mapping values to be used. If a value matches a token key (e.g., `"1"` for `space.1`), it will automatically reference the corresponding CSS custom property (e.g., `var(--g-space-1)`). If an object, it maps a short code to a resolved CSS value (e.g., `"f": "flex"`).
### Extending Tokens / Adding Themes
To add new tokens or define additional themes, simply modify the `css.config.json` file. The build process will automatically pick up these changes and regenerate the necessary CSS files.
## Development
### Build
To generate the CSS files (`dist/gears.css` and `dist/gears.min.css`):
```bash
npm run build
```
This command runs the `build/generator.js` script to create token and utility CSS, then processes all CSS files through PostCSS for nesting, custom properties, autoprefixing, and minification.
### Watch (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.
## Project Layout
```
/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
package.json
postcss.config.cjs
css.config.json <-- user-editable config (tokens + utilities + themes)
README.md <-- This file
LICENSE
.gitignore
```
## Naming Conventions
- **Components**: Follow BEM (Block-Element-Modifier) naming conventions (e.g., `.card`, `.card__header`, `.card--compact`).
- **Utilities**: Are atomic, short, and predictable, using the `g-` prefix to prevent clashes (e.g., `g-m-4`, `g-text-primary`, `g-d-f`).
## Accessibility & Best Practices
Gears encourages the use of semantic HTML and thoughtful application of utility classes to enhance accessibility. Components should include focus styles (e.g., `outline` and `focus-visible`). Consider adding an `.sr-only` utility for screen reader-only content.
## License
This project is licensed under the [MIT License](LICENSE).