@hydrogen-css/hydrogen
v2.1.0
Published
An open-source, inline CSS framework powered by data-attributes. GPL-3.0 Licensed.
Downloads
1,605
Maintainers
Readme
Hydrogen is an open-source design and CSS utility framework powered by data-attributes.
By parsing the contents of custom data-h2-
attributes, Hydrogen allows you to style elements completely from your markup. It comes equipped with a comprehensive library of tools and configurations for easy, seamless development. At runtime, it processes your markup and builds a CSS file that contains only the code you've used, preventing duplication and bloat.
🛠️ Basic usage
Installation
- navigate to your project
- run
npm install @hydrogen-css/hydrogen
to install Hydrogen - run
npx h2-init
to create a configuration file and set up your input/output directories - modify your
hydrogen.config.json
file to match your theme - add
data-h2
to your<html>
element or parent wrapper - run
npx h2-build
when you're ready to build your CSS or integrate the module into your build tool
Syntax
Hydrogen uses a custom data-attribute
syntax:
data-h2-property="query:modifiers(options)"
An example of a Hydrogen attribute in use looks something like this:
data-h2-color="base(primary) base:hover(accent)"
This repository also contains a handy hydrogen.snippets.json
file that offers snippet automation for VS Code, enabling auto completion and tab stops so that you don't have to memorize options for every property.
🏗️ Configuration
Hydrogen is configured using a hydrogen.config.json
file located at the root of your project. The npx h2-init
script is designed to create this file for you and prompts for some required information to get things working.
Within this configuration file, you can modify many of Hydrogen's options to include values that suit your project's needs and theme, including custom media queries, colors, typography, and shadows.
You can learn more about configuring Hydrogen in the documentation.
🤖 Features
Utilities
Hydrogen supports almost all CSS properties and includes a handful of custom properties that provide support for common tasks such as containers or color overlays. Standard CSS properties accept their relevant CSS syntax as options.
data-h2-display="base(grid)"
data-h2-border-top="base(1px solid black)"
Properties that are unique to Hydrogen use a comma separated syntax to accept specific options:
data-h2-container="base(center, large)"
data-h2-flex-grid="base(flex-start, x2)"
Queries and modifiers
The biggest advantage to Hydrogen's data-attribute
syntax is that it enables the use of inline media queries, selectors, states, targeting of nested elements, and dark mode. By chaining modifiers onto your query, you can target complex combinations of elements, manage styles based on the presence of classes or ids, bulk style an element's children, and more.
Learn more about modifiers in the documentation.
Speed and compression
Hydrogen uses custom scripting to scan your code for data-h2-
attributes and then builds a CSS stylesheet that contains only Hydrogen's core and the attributes you've used. No bloat. No duplication. This means that the library in production is concise while allowing it to provide a robust set of features and support complex customization.
It also runs Lightning CSS on itself to provide a complete, production ready file.
Development and contribution
Fork the repository and pull it down
Navigate to the code repository and run
npm run setup
To add a feature or propose a change, ensure you're doing the following:
- Update the relevant files in the
lib
directory - Update or create matching Jest test files for your changes
- If relevant, add a visual test in the
test
directory'smarkup
- Update the documentation in the
docs
directory
- Update the relevant files in the
Submit a pull request with details on your changes
Hydrogen takes two approaches to development testing:
- Jest is used for function level unit tests and can be run using
npm run jest
- The
test
directory contains a working Hydrogen project for visual testing and real-world compiling tests and can be run usingnpm run test
- Jest is used for function level unit tests and can be run using
The folder structure in the lib
directory tries to reflect the relationships between functions, including whether a function is a synchronous build step or a reusable parsing function. You can read up on specifics about how Hydrogen works on a technical level in the CONTRIBUTING.md
file.