gears-css

v0.1.0

Published

3 months ago

An atomic, utility-first CSS library with ITCSS + Atomic + BEM + utility-first architecture with theme support.

0High
0Medium
0Low

pinkuagrawal28

css utility-first atomic itcss bem postcss theming

Gears CSS Library

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:

npm install gears

Usage

Import in JavaScript (e.g., in your main JS file or a bundler entry point)

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)

<link rel="stylesheet" href="path/to/node_modules/gears-css/dist/gears.css">
<!-- Example for CDN (replace with actual CDN link when available) -->
<!-- <link rel="stylesheet" href="https://cdn.example/gears/0.1.0/gears.css"> -->

HTML Example

Combine BEM-named components with utility classes for flexible styling:

<button class="btn g-m-2 g-p-2">Click me</button>

<div class="card g-m-4">
  <div class="card__header">Card Title</div>
  <div class="card__body">This is the card body content.</div>
</div>

<p class="g-text-primary g-m-1">This text uses the primary color.</p>
<div class="g-d-f g-p-4 g-bg-primary">This is a flex container with primary background.</div>

Theming

Gears provides robust theme support using CSS custom properties. You can switch themes dynamically by setting the data-theme attribute on the <html> element.

// 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.

{
  "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="<theme-name>"] 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):

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)

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.