https://github.com/franbarinstance/bootstrapdyn
Modular & Dynamic Bootstrap 5
https://github.com/franbarinstance/bootstrapdyn
Last synced: about 1 month ago
JSON representation
Modular & Dynamic Bootstrap 5
- Host: GitHub
- URL: https://github.com/franbarinstance/bootstrapdyn
- Owner: FranBarInstance
- Created: 2026-05-09T20:25:07.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-09T22:45:36.000Z (about 1 month ago)
- Last Synced: 2026-05-10T00:28:34.969Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 441 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# BootstrapDyn – Modular & Dynamic Bootstrap 5
BootstrapDyn is a build-time utility that transforms compiled Bootstrap 5.3 CSS into a modular CSS variable architecture.
Its goal is not to be a visual theme editor or a collection of ready-made themes. BootstrapDyn generates the CSS modules that make those tools possible: default theme modules, fixed component CSS, optional contrast behavior, and a bundler-friendly load order. Users and external applications can then create their own dynamic Bootstrap themes by replacing module files instead of editing Bootstrap component rules.
The core idea is simple: **make Bootstrap themeable by substitution, not by overriding**.
## What BootstrapDyn Produces
BootstrapDyn takes `bootstrap/dist/css/bootstrap.css` and generates:
1. `dist/default-*.css` modules for themeable concerns such as color, typography, spacing, borders, shadows, forms, layout, sizing, motion, layers, and grid.
2. `dist/bootstrap-dyn.css`, the fixed Bootstrap-compatible component layer that consumes those variables.
3. `dist/contrast-dyn.css`, an optional behavior module for dynamic contrast.
4. `dist/bootstrap-dyn-bundle.css` and `dist/bootstrap-dyn-bundle.min.css`, optional single-file bundles for production usage.
Theme authors replace one or more `default-*.css` files with complete custom modules that follow the same contract. Bootstrap HTML, component classes, and JavaScript behavior remain unchanged.
## What BootstrapDyn Is Not
BootstrapDyn is not a runtime JavaScript theme engine, a UI for editing themes, or a Sass-level Bootstrap fork. It is the CSS compatibility layer that lets those tools exist.
For example, a theme editor can use BootstrapDyn as its foundation: expose the generated module variables in a UI, let users edit values, export complete replacement modules, and keep `bootstrap-dyn.css` untouched. One example of that kind of editor is [bootstrap-dynamic-themes](https://github.com/FranBarInstance/bootstrap-dynamic-themes).
Users do not need an editor to create themes. They can download this project, copy the generated `dist/default-*.css` modules, rename them with a theme prefix, and edit the variable values directly. AI coding agents can also use the included [`theme-creation`](.agents/skills/theme-creation/SKILL.md) skill to create or update a complete theme module set.
Example prompt:
```text
Use the theme-creation skill to create a BootstrapDyn theme named "midnight" in path/to/theme. Make it dark, high contrast, with cooler primary colors and slightly larger border radii.
```
## Visual Parity and Compatibility
A core principle of this project is **strict visual fidelity**. The files generated in `dist/` are designed to produce the exact same visual result as the original Bootstrap CSS when using the default variables. This ensures that:
1. Your project starts with the 100% standard Bootstrap "look and feel".
2. **Zero HTML changes**: You don't need to modify your templates, component structures, or Bootstrap classes. Compatibility is maintained purely at the CSS layer.
3. All Bootstrap components behave and render identically.
4. You only deviate from the original design when you explicitly choose to replace default modules with theme modules.
### Single-file bundle
For production deployments that prefer a single HTTP request, use the build script to run the extractor pipeline and bundler in one step:
```bash
npm run build
```
This runs `extractor/main.js` followed by `scripts/bundle.mjs`, producing the 14 individual files plus `dist/bootstrap-dyn-bundle.css` and `dist/bootstrap-dyn-bundle.min.css`. Load the minified bundle instead of the 14 individual files:
```html
```
The bundle contains all modules in the canonical load order defined in [`.specify/theme-spec.md`](.specify/theme-spec.md). The bundler discovers files by canonical suffix (`*-color.css`, `*-typography.css`, etc.), so it works with any theme directory, not just `dist/`. See [`examples/demo/bundle.html`](examples/demo/bundle.html) for a complete demo page.
## How `contrast-dyn.css` works (optional)
A common challenge in Bootstrap 5+ is handling accessibility and contrast dynamically without bloating the HTML with `data-bs-theme` attributes.
### The standard (static) approach
In standard Bootstrap, developers must explicitly define the contrast mode for each container. If you have a dark background, you add `data-bs-theme="dark"` to make the child elements (text, links, buttons) visible.
```html
```
**The limitation:** This approach is hardcoded into your HTML. If you change your theme to a light version at runtime, the `data-bs-theme="dark"` attribute will remain, making the text unreadable (white text on a light background).
### The BootstrapDyn (dynamic) approach
BootstrapDyn handles contrast at the CSS variable level. Each color theme defines its own contrast variables (`--bs-primary-contrast`, `--bs-secondary-contrast`, etc.) inside `default-color.css` (or your custom color theme). `contrast-dyn.css` only consumes those variables — it does not define them.
This means if you create a custom color theme, you must provide the matching `*-contrast` variables alongside your palette so that `contrast-dyn.css` can resolve the correct text colors.
```html
```
The `text-reset` class is recommended when you want child links to inherit the computed contrast color rather than Bootstrap's default link color.
**Zero HTML changes:** Switch from a dark professional theme to a light pastel style, and your menus, cards, and links automatically adapt their colors instantly. The contrast rules handle both `bg-*` background utilities and `btn-outline-*` hover/active states.
### Do you need it?
Most dynamic themes should load `contrast-dyn.css`.
With this module enabled, a background utility such as `bg-primary` also applies the matching contrast variable. For text contrast, these two examples are visually equivalent:
```html
Text is white because of data-bs-theme.
Text automatically uses --bs-primary-contrast.
```
Only omit `contrast-dyn.css` if you want strict Bootstrap default behavior, where background utilities do not automatically set text contrast and you manage `data-bs-theme`, text utilities, or custom classes manually.
For more details on how it changes Bootstrap's behavior, see [Contrast Dynamic Documentation](docs/modules/contrast-dyn.md).
## Theme customization
Copy any `default-*.css` file to a theme file (e.g. copy `dist/default-color.css` to `theme/custom-color.css`) and edit the values you want to change. Then load the theme file **instead of** the matching default file.
This allows fully modular theming: you can swap fonts without touching colors, or change the color palette without affecting typography.
## Versioning Policy
BootstrapDyn follows a **synchronized versioning** scheme with Bootstrap for its first two digits:
- **Major & Minor**: Synchronized with Bootstrap (e.g., `5.3.x` is for Bootstrap `v5.3`).
- **Patch**: Represents the revision of the BootstrapDyn extraction tool and modules.
| BootstrapDyn Version | Target Bootstrap | Status |
|----------------------|------------------|--------|
| **5.3.0** | **5.3.8** | Current |
This ensures that you always know which Bootstrap family is supported by a specific version of BootstrapDyn.
## Contributing
If you want to modify the pipeline, add new modules, or upgrade the Bootstrap source, see [`extractor/README.md`](extractor/README.md) for developer documentation.
---
## Acknowledgments
This project is based on and uses [Bootstrap](https://github.com/twbs/bootstrap). BootstrapDyn extends Bootstrap's modular CSS architecture to provide dynamic theming capabilities while maintaining full compatibility with the original framework.
*Designed for Bootstrap 5.3.8 – Modular and extensible theme system.*