# Configuration The `css.config.json` file is the central hub for customizing your Gears CSS Library. It allows you to define your design tokens, utility classes, and theme presets, providing a powerful way to align the library with your project's design system. ## `css.config.json` Structure Here's an example of the `css.config.json` structure: ```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" } } } } ``` ## Sections Explained ### `name` and `version` These fields are for informational purposes, typically reflecting the name and version of your Gears setup. ### `tokens` The `tokens` section defines your design system's foundational values. These are automatically generated as CSS custom properties (e.g., `--g-colors-primary`, `--g-space-1`) under the `:root` selector in `src/settings/tokens.base.css`. These custom properties serve as the single source of truth for your design values. - **`colors`**: Define your project's color palette. Each key-value pair creates a CSS custom property like `--g-colors-primary: #0b76ff;`. - **`space`**: Define consistent spacing units. These are crucial for maintaining vertical rhythm and consistent layouts. Example: `--g-space-1: 0.25rem;`. - **`radius`**: Define border-radius values for consistent rounded corners. Example: `--g-radius-md: 8px;`. - **`font`**: Define font families and other typographic settings. Example: `--g-font-base: "Inter, ...";`. ### `themes` The `themes` section allows you to define different visual themes for your application (e.g., `light`, `dark`, `high-contrast`). Each theme is an object where keys are theme names. Inside each theme, you can override any of the base tokens defined in the `tokens` section. These overrides are generated as CSS custom properties under a `[data-theme=""]` selector in `src/settings/tokens.theme.[name].css`. This mechanism enables dynamic theme switching by simply changing the `data-theme` attribute on your `` element. For more details, see [Theming](theming.md). ### `utilities` The `utilities` section is used to define atomic utility classes that provide single-purpose styles. These classes are generated into `src/utilities/utilities.generated.css`. Each utility entry specifies: - **`prefix`**: A short, unique prefix for the utility class (e.g., `g-m` for margin, `g-p` for padding). This helps prevent naming clashes with other CSS and clearly identifies Gears utilities. - **`props`**: An array of CSS properties this utility applies (e.g., `["margin"]`, `["padding", "margin"]`). - **`values`**: This can be either an array or an object: - **Array of values**: If an array, each value will generate a utility class. 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)`). Otherwise, the literal value is used. Example: `"values": ["0","1","2","3","4","8"]` for margin would generate `.g-m-0 { margin: var(--g-space-0); }`, `.g-m-1 { margin: var(--g-space-1); }`, etc. - **Object map of values**: If an object, it maps a short code to a resolved CSS value. This is useful for properties with non-numeric values or when you want more control over the class name. Example: `"values": { "b": "block", "ib":"inline-block", "f":"flex", "g":"grid" }` for display would generate `.g-d-b { display: block; }`, `.g-d-ib { display: inline-block; }`, etc. ## Extending Tokens / Adding Themes To add new tokens, modify existing ones, or define additional themes, simply update the `css.config.json` file. The Gears CSS build process will automatically detect these changes and regenerate the necessary CSS files on the next build (`npm run build`). This allows for seamless integration of your design system's evolution.