nk_jtb 0.21.0 → 0.22.0

package/.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# Copilot Instructions for JTB (Just the Basics)
+
+## Project Overview
+- **JTB** is a Sass-based utility framework focused on composable classes, minimal components, and predictable naming. It avoids runtime JavaScript and prioritizes build-time CSS generation.
+- The architecture centers on SCSS mixins for class generation, using configuration maps and builder/maker mixins.
+
+- This framework uses tailwind-like class, but is not tailwind.
+- Read the conventions in `docs/conventions.md` for naming patterns and class structures.
+
+## Key Files & Structure
+- `src/` — Main SCSS source. Organized by `base/`, `components/`, `forms/`, `functions/`, `maps_and_variables/`, `mixins/`, `utilities/`.
+- `build.scss` — Entry point for building the full framework.
+- `docs/` — Documentation, conventions, and architecture explanations.
+- `examples/` — Examples are provided in the documents not the examples/ folder.
+- `package.json` — Build/test/lint scripts and dependencies.
+
+## Before Responding
+- Always consider existing patterns in the codebase
+- Reference docs/ when explaining architecture
+- Don't give generic CSS advice—this is a framework with specific conventions
+
+For more details, see:
+- `docs/core-architecture.md`
+- `docs/conventions.md`
+- `docs/responsive-design.md`
+- `README.md`
+
+## Class Generation Patterns
+- **Builders**: Use configuration maps to generate sets of utility classes. Example:
+  ```scss
+  @include build-classes((margin: (prefix: 'm-', values: (1,2,3), unit: 'rem')));
+  // Generates: .m-1, .m-2, .m-3
+  ```
+- **Makers**: For single, precise classes. Example:
+  ```scss
+  @include make-single-property-class('display', 'hidden', 'none', $breakpoints: (md, lg), $states: (hover));
+  // Generates: .hidden, .md:hidden, .lg:hidden, .hover:hidden:hover
+  ```
+- **Responsive Prefixes**: `md:`, `on-md:`, `to-md:` control when styles apply. See `docs/responsive-design.md` for details.
+
+## Naming Conventions
+- Utility classes: `{breakpoint}:{property}-{variant/value}`
+  - Examples: `mxy`, `gap-lg`, `md:mxy-3`, `on-lg:hidden`
+- Properties use short prefixes: `m` (margin), `p` (padding), `bg` (background), `txt` (text)
+- Variants: Semantic keywords (`sm`, `lg`) or direct values (`1.5`, `0`)
+
+## Developer Workflows
+- **Build**: `npm run build` (uses Vite)
+- **Dev**: `npm run dev` (hot reload, watches SCSS)
+- **Watch**: `npm run watch` (watches build.scss)
+- **Lint**: `npm run lint` or `npm run lint:base` (uses stylelint)
+- **Playground**: `npm run play` (watches play.scss, opens files)
+- **Debug**: `npm run debug` (Vite debug mode)
+
+## Customization & Configuration
+- Override variables in `maps_and_variables/` before importing modules.
+- Import only needed modules for smaller builds.
+- Vite config for SCSS: see `docs/installation.md` for `additionalData` usage.
+
+## Integration Points
+- Minimal JS: Only for interactive components (see `public/docs/components/` and dependencies in `package.json`).
+- External: Uses Alpine.js for some components, Highlight.js and Marked for docs/examples.
+
+## Project-Specific Patterns
+- **No runtime CSS-in-JS.** All class generation is build-time via SCSS.
+- **Responsive system**: Three prefix types for breakpoints (`md:`, `on-md:`, `to-md:`).
+- **Spacing scale**: See `README.md` for px/rem mapping.
+- **Class name prediction**: See `docs/conventions.md` for structure and examples.
+
+---
+

package/.stylelintrc.json

@@ -1,17 +1,17 @@
-{
-    "extends": "stylelint-config-standard-scss",
-    "plugins": [
-        "stylelint-order"
-    ],
-    "ignoreFiles": [
-        "dist/**/*",
-        "**/*.min.css"
-    ],
-    "rules": {
-        "scss/comment-no-empty": null,
-        "order/properties-alphabetical-order": true,
-        "scss/dollar-variable-colon-space-after": "always",
-        "scss/dollar-variable-empty-line-before": null,
-        "hue-degree-notation": null
-    }
+{
+    "extends": "stylelint-config-standard-scss",
+    "plugins": [
+        "stylelint-order"
+    ],
+    "ignoreFiles": [
+        "dist/**/*",
+        "**/*.min.css"
+    ],
+    "rules": {
+        "scss/comment-no-empty": null,
+        "order/properties-alphabetical-order": true,
+        "scss/dollar-variable-colon-space-after": "always",
+        "scss/dollar-variable-empty-line-before": null,
+        "hue-degree-notation": null
+    }
 }

package/dev.html

@@ -12,208 +12,7 @@
 </head>
 
 <body class="container py-5 bg-gray-200">
-    <div class="x">some text</div>
-    <section id="horizontal-menu-examples">
-        <h2>Horizontal Menu Examples</h2>
-        <p>All parents are identical except for the alpine.js triggers.</p>
-        <div class="menu-title">Utility Example</div>
-        <nav id="utility-example" class="bx pxy-1 bdr bdr-blue">
-            <ul class="flex gap-05 txt-sm">
-                <li>
-                    <a href="#" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <svg class="wh-1.25 bdr bdr-blue bg-stripes-blue"></svg>
-                        Item
-                    </a>
-                </li>
-                <li>
-                    <a href="#" class="bg-gray-200 flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700">
-                        <svg class="wh-1.25 bdr bdr-blue bg-stripes-blue"></svg>
-                        Active
-                    </a>
-                </li>
-                <!-- Click to toggle -->
-                <li class="relative" x-data="{ open: false }">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-blue bg-stripes-blue"></svg>
-                            Parent (Click)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse x-cloak class="absolute mt-05 flex w-10 z-100">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-                <!-- Click with click.away -->
-                <li class="relative" x-data="{ open: false }" x-on:click.away="open = false">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-blue bg-stripes-blue"></svg>
-                            Parent (Click Away)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse class="absolute mt-05 flex w-10 z-100" style="display: none;">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-                <!-- Hover to show -->
-                <li class="relative" x-data="{ open: false }" x-on:mouseenter="open = true" x-on:mouseleave="open = false">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-blue bg-stripes-blue"></svg>
-                            Parent (Hover)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse x-cloak class="absolute mt-05 flex w-10 z-100">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-            </ul>
-        </nav>
-        <div class="menu-title">Menu Class Example</div>
-        <nav id="menu-class-example" class="menu bx pxy-1 bdr bdr-green">
-            <ul class="flex gap-05 txt-sm">
-                <li>
-                    <a href="#" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <svg class="wh-1.25 bdr bdr-green bg-stripes-green"></svg>
-                        Item
-                    </a>
-                </li>
-                <li>
-                    <a href="#" class="bg-gray-200 flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700">
-                        <svg class="wh-1.25 bdr bdr-green bg-stripes-green"></svg>
-                        Active
-                    </a>
-                </li>
-                <!-- Click to toggle -->
-                <li class="relative" x-data="{ open: false }">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-green bg-stripes-green"></svg>
-                            Parent (Click)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse x-cloak class="absolute mt-05 flex w-10 z-100">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-                <!-- Click with click.away -->
-                <li class="relative" x-data="{ open: false }" x-on:click.away="open = false">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-green bg-stripes-green"></svg>
-                            Parent (Click Away)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse class="absolute mt-05 flex w-10 z-100" style="display: none;">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-                <!-- Hover to show -->
-                <li class="relative" x-data="{ open: false }" x-on:mouseenter="open = true" x-on:mouseleave="open = false">
-                    <button x-on:click="open = ! open" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-700 hover:bg-gray-100">
-                        <span class="flex items-center gap-075">
-                            <svg class="wh-1.25 bdr bdr-green bg-stripes-green"></svg>
-                            Parent (Hover)
-                        </span>
-                        <svg class="wh-1" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
-                            <path x-show="open" d="m6 15 6-6 6 6" />
-                            <path x-show="!open" d="m6 9 6 6 6-6" />
-                        </svg>
-                    </button>
-                    <div x-show="open" x-collapse x-cloak class="absolute mt-05 flex w-10 z-100">
-                        <ul class="bx pxy-0 w-full flex-col gap-0">
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                            <li>
-                                <a href="#" class="flex items-center gap-075 px-075 py-05 txt-gray-700 hover:bg-gray-100">
-                                    Child Item
-                                </a>
-                            </li>
-                        </ul>
-                    </div>
-                </li>
-            </ul>
-        </nav>
 
-    </section>
     <script type="module" src="/main.js"></script>
 </body>
 

package/docs/animation.md

@@ -0,0 +1,131 @@
+# Animation Utilities
+
+<h2>Loading States</h2>
+<div class="grid md:cols-2 lg:cols-3 gap">
+    <!-- Simple Spinner -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Simple Spinner</h3>
+        <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-blue-600"></div>
+        <p class="txt-sm txt-gray-600">Sending message...</p>
+    </div>
+    <!-- Ring Spinner (Thicker) -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Ring Spinner</h3>
+        <div class="animate-spin rounded-full wh-4 bdr-8 bdr-gray-200 bdr-t-indigo-600"></div>
+        <p class="txt-sm txt-gray-600">Processing...</p>
+    </div>
+    <!-- Dual Ring -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Dual Ring</h3>
+        <div class="relative">
+            <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-purple-600"></div>
+            <div class="absolute top-05 left-05 animate-spin rounded-full wh-3 bdr-4 bdr-gray-100 bdr-t-purple-400" style="animation-direction: reverse;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Loading...</p>
+    </div>
+    <!-- Bouncing Dots -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Bouncing Dots</h3>
+        <div class="flex space-x-05">
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0s;"></div>
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.1s;"></div>
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.2s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Submitting...</p>
+    </div>
+    <!-- Pulsing Circle -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Pulse</h3>
+        <div class="wh-4 bg-teal-500 rounded-full animate-pulse"></div>
+        <p class="txt-sm txt-gray-600">Please wait...</p>
+    </div>
+    <!-- Pulse Rings -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Pulse Rings</h3>
+        <div class="relative">
+            <div class="wh-4 bg-emerald-500 rounded-full"></div>
+            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring"></div>
+            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring" style="animation-delay: 0.5s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Processing...</p>
+    </div>
+    <!-- SVG Spinner -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">SVG Spinner</h3>
+        <svg class="animate-spin wh-4 txt-orange-600" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-30" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+            <path class="opacity-80" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+        </svg>
+        <p class="txt-sm txt-gray-600">Uploading...</p>
+    </div>
+    <!-- Progress Bar -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Progress Bar</h3>
+        <div class="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
+            <div class="h-full bg-blue-600 rounded-full animate-pulse" style="width: 70%;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">70% Complete</p>
+    </div>
+    <!-- Sequential Dots -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Sequential Dots</h3>
+        <div class="flex space-x-05 items-center h-2">
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0s;"></div>
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.3s;"></div>
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.6s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Loading...</p>
+    </div>
+</div>
+
+## Loading Animations
+
+<div class="loader-container bx dark">
+    <div class="spinner"></div>
+    <div class="loading-text">Loading<span class="dots"></span></div>
+</div>
+
+<div class="loader-container bx dark">
+    <div class="loading-text">Loading<span class="dots"></span></div>
+</div>
+
+
+## SVG Spinners
+
+<div class="bx  flex va-c">
+    <svg class="wh-2 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-400" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-100" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+    <svg class="wh-3 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-red-300" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-blue-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+    <svg class="wh-4 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-yellow-300" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-green-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+</div>
+
+
+## Border Animations
+
+### Spinner
+
+```html +code +preview +collapse
+<div class="dark flex-centered gap bx">
+    <div class="spinner sm"></div>
+    <div class="spinner"></div>
+    <div class="spinner lg"></div>
+</div>
+```
+
+**Thick Spinners:**
+
+```html +code +preview +collapse
+<div class="dark flex-centered gap bx">
+    <div class="spinner sm thick"></div>
+    <div class="spinner thick "></div>
+    <div class="spinner lg thick"></div>
+</div>
+```

package/docs/api/architecture-naming.md

@@ -0,0 +1,79 @@
+# Mixin Architecture & Naming Conventions
+
+
+
+## Architecture Levels
+
+## The 4 Layers
+
+**Layer 1: Base**
+Foundation classes without breakpoints or states. Lowest priority in cascade.
+
+**Layer 2: Responsive**
+Media query variants that override base at different breakpoints (md:, lg:, etc).
+
+**Layer 3: State**
+Interaction state variants (hover:, focus:, active:) that override responsive.
+
+**Layer 4: Responsive + State**
+Combined breakpoint and state variants (md:hover:, lg:focus:, etc). Highest priority.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Based on the pattern, here's my recommendation:
+
+## Naming Convention: **class** vs **variant**
+
+- **`make-base-class()`** — Generates THE class (foundation, layer 1 only)
+- **`make-responsive-variant()`** — Generates variants OF that class (layer 2)
+- **`make-state-variant()`** — Generates variants OF that class (layer 3)
+- **`make-responsive-state-variant()`** — Generates variants OF that class (layer 4)
+
+And for position-based:
+- **`make-responsive-position-variant()`** — Responsive variants (layer 2)
+- **`make-state-position-variant()`** — State variants (layer 3)
+- **`make-responsive-state-position-variant()`** — Both (layer 4)
+
+
+
+## Data Flow
+
+```
+User Config (property map)
+        ↓
+build-classes-new (normalize config)
+        ↓
+build-base-layer (loop through values)
+        ↓
+make-base-class (generate CSS for one class)
+        ↓
+Final CSS Output
+```
+
+
+
+
+## Layer Order (Cascade Priority)
+
+1. **Base Layer** → Lowest priority, establishes defaults
+2. **Responsive Layer** → Overrides base at screen sizes
+3. **State Layer** → Interactive states (hover, focus)
+4. **Responsive+State Layer** → Highest priority, combined variants
+
+
+
+
+
+
+

package/docs/api/build-classes.md

@@ -0,0 +1,108 @@
+# build-classes()
+
+## Signature
+
+```scss +code
+@mixin build-classes(
+    $properties-map,
+    $responsive: false,
+    $with-state: false,
+    $debug: false
+)
+```
+
+## Parameters
+
+| Parameter         | Type    | Default | Description                                                                        |
+| ----------------- | ------- | ------- | ---------------------------------------------------------------------------------- |
+| `$properties-map` | Map     | —       | CSS property config with `prefix`, `values`, `unit`, `positions`, `omit-axis-keys` |
+| `$responsive`     | Boolean | `false` | Generate responsive variants (`md:`, `lg:`, etc.)                                  |
+| `$with-state`     | Boolean | `false` | Generate state variants (`:hover`, `:focus`, `:active`)                            |
+| `$debug`          | Boolean | `false` | Output debug info during compilation                                               |
+
+### `$properties-map` Configuration
+
+```scss +code
+$border-properties-map: (
+    border-width: (
+        prefix: 'bdr-',              // Class prefix (optional)
+        values: $border-width-map,   // Values to generate (required)
+        positions: $logical-position-map,  // For directional properties (t, b, l, r)
+        omit-axis-keys: (xy),        // Exclude x/y combinations
+        unit: 'px'                   // CSS unit
+    ),
+    border-color: (
+        prefix: 'bdr-',
+        values: $colors-map
+    )
+);
+
+@include build-classes($border-properties-map);
+```
+
+## Examples
+
+### Basic Usage
+
+```scss +code
+@include build-classes((
+    margin: (
+        prefix: 'm-',
+        values: (1, 2, 3, 4),
+        unit: 'rem'
+    )
+));
+// Output: .m-1, .m-2, .m-3, .m-4
+```
+
+### With Positions
+
+```scss +code
+@include build-classes((
+    margin: (
+        prefix: 'm-',
+        values: (1, 2, 3),
+        positions: (t: margin-top, b: margin-bottom, l: margin-left, r: margin-right),
+        unit: 'rem'
+    )
+));
+// Output: .m-1, .mt-1, .mb-1, .ml-1, .mr-1
+```
+
+### With Responsive Variants
+
+```scss +code
+@include build-classes((
+    display: (prefix: 'd-', values: (flex, grid, block, hidden))
+), $responsive: true);
+// Output: .d-flex, .md:d-flex, .lg:d-flex, etc.
+```
+
+### With State Variants
+
+```scss +code
+@include build-classes((
+    opacity: (prefix: 'op-', values: (0.5, 0.75, 1))
+), $with-state: true);
+// Output: .op-0.5, .op-0.5:hover, .op-0.5:focus, etc.
+```
+
+### Omitting Axis Combinations
+
+```scss +code
+@include build-classes((
+    border-width: (
+        prefix: 'bdr-',
+        values: (1, 2, 3),
+        positions: $logical-position-map,
+        omit-axis-keys: (xy),  // Exclude x/y combinations
+        unit: 'px'
+    )
+));
+```
+
+## Output Structure
+
+Pattern: `{breakpoint}:{property}-{value}{state}`
+
+Examples: `m-1`, `md:m-1`, `m-1:hover`, `md:m-1:hover`