lumina-sass 2.7.1 → 2.8.0

package/README.md

@@ -1,251 +1,140 @@
 # Lumina SASS
-*Last updated: 2026-06-09*
-Lumina Sass provides design tokens and mixins to help you build modern web applications.
 
-## Overview
+[![CI](https://github.com/NexusWeave/ux-lumina-sass/actions/workflows/ci.yml/badge.svg)](https://github.com/NexusWeave/ux-lumina-sass/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/lumina-sass.svg)](https://www.npmjs.com/package/lumina-sass)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Lumina SASS offers a collection of standardized color variables and utility mixins. The library uses clear naming conventions, making it simple to add to any SASS-based project.
+**Lumina SASS** is a comprehensive design token and mixin framework engineered for modern web development. It provides a robust, standardized foundation for color systems, responsive layouts, and reusable components utilizing the **Sass Indented Syntax**.
 
-## Installation
+---
+
+## Technical Specifications
+
+Lumina SASS is architected with modularity and efficiency as core principles. Key features include:
+- **Type Safety:** Leveraging Sass maps and sophisticated validation logic.
+- **Architectural Consistency:** Standardized nomenclature for design tokens.
+- **Enhanced Developer Experience:** An intuitive API featuring streamlined mixins.
+- **Modern Standards Compliance:** Full compatibility with Dart Sass and the `@use` module system.
 
-Install the package as a project-level dependency in your project:
+> **Note:** This library utilizes the **Sass Indented Syntax** (.sass). It remains compatible with SCSS projects via the `@use` directive. Demonstration examples employ the indented syntax to maintain consistency with the source codebase.
+
+## Installation
 
 ```bash
 npm install lumina-sass
 ```
 
-This will add `lumina-sass` to your `package.json` file. Do not install the library globally.
-
 ## Usage
 
-### Importing the Library
-
-You can use the library directly in your Sass files using standard `@use` syntax.
+Lumina SASS employs a modular architecture, permitting the importation of the entire framework or specific modules as required.
 
-#### 1. Import Flexbox Utilities (the only public export)
-
-You can import the flexbox utilities directly:
+### Importing Modules
 
 ```sass
-// In your style.sass or style.scss file:
-@use 'lumina-sass/flexbox' as flex;
-
-// Now all flexbox mixins and classes are available:
-.container {
-  @include flex.flexbox-generator('flex');
-}
-```
-
+// Import flexbox utilities (recommended)
+@use 'lumina-sass/flexbox' as flex
 
-#### 2. Import Specific Modules
+// Import generator mixins
+@use 'lumina-sass/generators' as gen
 
- > The package now exports the `flexbox` sub‑path and other public sub‑paths (`color`, `mix`). Other internal modules (`utils`, `map`, …) remain private.
-
-
-### Module Breakdown
-
-| Module | Description |
-| :--- | :--- |
-| `lumina-sass/flexbox` | Flexbox utilities and CSS classes. |
-| `lumina-sass/color`   | Color variables and palettes. |
-| `lumina-sass/mix`     | General mixins (layout, typography, media). |
+// Import descriptive color variables
+@use 'lumina-sass/colors' as color
 
+// Import general mixins (typography, layout, accessibility)
+@use 'lumina-sass/mixins' as mix
 
-### Utility Classes
+// Import design tokens and maps
+@use 'lumina-sass/map' as map
 
-If you prefer to use CSS classes directly in your HTML (like `.flex-center`), please check our [**Utility Classes Guide**](docs/utils/utility_classes.md).
+// Import general utility functions
+@use 'lumina-sass/func' as func
+```
 
-### Semantic Media Queries
-For common media queries, you can use these simple helper mixins to make your code more readable.
+### Implementation Examples
 
+#### Flexbox Layout
 ```sass
-.my-component
-  // Base styles
-  background: white
-
-  // Applies styles for medium screens and smaller
-  @include on-breakpoint(md)
-    font-size: 0.9rem
-
-  // Applies styles when the user prefers dark mode
-  @include on-dark-mode
-    background: black
+.container
+  @include flex.flexbox-generator('flex-row')
+  @include flex.flex-items-center
 ```
 
-Available helpers:
-- `@include on-breakpoint($name)`
-- `@include on-dark-mode`
-- `@include on-light-mode`
-- `@include on-landscape`
-- `@include on-portrait`
-
-## Features
-### Recent Changes
-
-- **RGB conversion:** All colour variables that previously used `rgba(..., 1)` are now simplified to `rgb(...)`; any hexadecimal literals have been converted to `rgb()`.
-### Standardized Colors
-Uses a consistent `$[brand]-[color]` pattern for easy use and maintenance.
-- **Brand Colors:** Social media platforms, operating systems, and tech brands.
-- **UI States:** Hover and active states.
-
-### Flexbox Utilities
-A complete set of flexbox mixins and maps to help you build layouts quickly.
-
-### Utility Mixins
-- **Responsive Design:** Media query breakpoints.
-- **Responsive Media Queries:** Added `media-queries` mixin usage in demo and `device-media` support for iPhone.
-- **Typography:** Font handling and text styling.
-- **Elements:** Button generation and image styling.
-
----
-
-## Contributing & Internal Docs
-
-To learn how to contribute or understand the release process, please see:
-
-- [**Development Guide**](docs/developer/development.md) - Project structure and setup rules.
-- [**Testing Guide**](docs/developer/testing.md) - How to write and run Sass unit tests.
-- [**Releasing & Publishing**](docs/developer/releasing.md) - Details on the release process.
-
----
-
-# AI Operations Guide for **lumina-sass**
-
-> This document is intended for the Antigravity AI (or any other automated assistant) that contributes to the `lumina-sass` project. It consolidates the repository‑specific conventions, tooling, and policies that enable the AI to work safely, efficiently, and in compliance with the user’s personal rules.
-
----
-
-## 1️⃣ Project Overview
-- **Name:** `lumina-sass`
-- **Purpose:** Provides design tokens, mixins, and flexbox utilities for Sass‑based web projects.
-- **Primary public entry point:** `lumina-sass/flexbox` (the only sub‑path exported in `package.json`).
-- **Main files:**
-  - `src/_index.sass` – default entry (re‑exports flexbox).
-  - `src/flexbox/_index.sass` – collection of flexbox mixins and utility classes.
-  - `README.md` – user‑facing documentation (kept up‑to‑date with export changes).
-
----
-
-## 2️⃣ Development Environment (User‑defined rules)
-- **Node.js version:** Use the latest **Stable LTS** (v24.x) via `fnm`.
-  ```bash
-  fnm use lts   # activates the stable LTS version
-  ```
-- **Package manager:** `npm` (default for this repo).
-- **GPG signing:** All commits must be **GPG‑signed** (`git commit -S`). The AI should stage changes and let the user provide the pass‑phrase; never use `--no-gpg-sign`.
-- **Conventional Commits:** Follow the `type: description.` format, ending with a period. Emphasise *why* a change is made.
-- **Python tools:** When needed, create a virtual environment with `python -m venv .venv` (not required for this repo, but noted for future scripts).
-
----
+#### Automated Generation (Icons & Inputs)
+```sass
+// Systematically generate all icon classes
+@include gen.icon-generator()
 
-## 3️⃣ Repository Layout (important paths)
-```
-lumina-sass/
-├─ src/                     # Sass source files
-│  ├─ _index.sass          # Default entry point (re‑exports flexbox)
-│  ├─ flexbox/             # Public module – only exported sub‑path
-│  │   ├─ _index.sass
-│  │   └─ …
-│  └─ (other internal directories: color/, mix/, utils/, map/)
-├─ dist/                    # Build artefacts (generated by `npm run build`)
-├─ docs/                    # Additional documentation
-│  └─ ai_guide.md          # **This file** – AI reference guide
-├─ README.md                # Consumer‑facing docs – kept in sync with exports
-├─ package.json
-└─ ...
+// Apply base styling to all text inputs
+@include gen.input-generator('text')
 ```
 
----
-
-## 4️⃣ Core Tasks for the AI
-| Task | How the AI should perform it | Important notes |
-|------|-----------------------------|----------------|
-| **Edit files** | Use `replace_file_content` for a single contiguous block or `multi_replace_file_content` for multiple non‑adjacent edits. Never overwrite a whole file with `write_to_file` unless explicitly creating a new artifact. | Preserve existing comments and docstrings. |
-| **Stage changes** | `git add <file>` after editing. |
-| **Commit** | `git commit -S -m "<Conventional Commit>"`. The AI must describe the command before execution and ensure GPG signing is enabled. |
-| **Run builds** | `npm run build` (or `npm run dev` if a dev server is needed). Ensure the LTS Node version is active via `fnm`. |
-| **Verify exports** | Test that `import 'lumina-sass/flexbox'` works and that importing any other sub‑path fails with `Package subpath ... is not defined`. |
-| **Update documentation** | Keep `README.md` and any internal docs in sync with code changes, especially the `exports` field. |
-| **Memory synchronization** | Whenever the AI updates a file that is part of the user’s memory (e.g., global or project‑specific memory files), also copy the changes to `/home/kristoffer/Gdrive/Administration/Gemini-Memory-Backup/`. |
-
----
-
-## 5️⃣ Export Management (Key AI Responsibility)
-- The `package.json` **exports** block defines the public API. The AI must:
-  1. Ensure only the intended sub‑paths are listed (currently `.` and `./flexbox`).
-  2. Update the **module breakdown table** in `README.md` to reflect the exported modules.
-  3. When new public modules are added, remember to:
-     - Add them to `exports`.
-     - Update the README table.
-     - Adjust the documentation guide.
-- Any attempt to expose internal modules (`color`, `mixins`, `utils`, `map`) must be rejected unless the user explicitly asks for it.
-
----
-
-## 6️⃣ Testing & Verification Workflow
-1. **Run Unit Tests**
-   ```bash
-   npm test
-   ```
-2. **Local import test**
-   ```bash
-   node -e "import 'lumina-sass/flexbox'"   # should succeed
-   node -e "import 'lumina-sass/utils'"     # should fail
-   ```
-2. **Build**
-   ```bash
-   npm run build
-   ```
-3. **Run demo** (optional) to ensure compiled CSS works:
-   ```bash
-   npm run serve   # serves the demo folder via http‑server
-   ```
-4. **Commit verification**: After committing, run `git log --show-signature -1` to confirm the GPG signature is present.
+#### Accessibility (WCAG Contrast Verification)
+```sass
+.alert
+  background: color.$brand-lumina-blue
+  color: color.$neutral-white
+  // Triggers a build failure if the contrast ratio falls below 4.5:1
+  @include mix.assert-contrast(color.$neutral-white, color.$brand-lumina-blue)
+```
+> For comprehensive details, please refer to our [**Color Contrast & Accessibility Guide**](docs/colors/contrast.md).
 
----
+#### Pure Functions (Mathematical & Logical Utilities)
+```sass
+.custom-bg
+  // Determine the relative luminance of a brand color
+  $luminance: func.luminance(color.$brand-lumina-blue)
+  opacity: if($luminance > 0.5, 0.8, 1)
+```
 
-## 7️⃣ Contribution Guidelines (for AI and humans)
-- **Pull‑request workflow:**
-  1. Create a feature branch.
-  2. Make the required edits.
-  3. Run the verification steps above.
-  4. Commit with a signed Conventional Commit.
-  5. Push and open a PR.
-- **Documentation:** Every public change must be reflected in `README.md` and, if relevant, in the AI guide.
-- **Linting / Formatting:** Keep the repo formatted according to the existing style (Sass indentation, no trailing spaces).
+#### Semantic Breakpoints
+```sass
+.card
+  width: 100%
+  @include mix.on-breakpoint(md)
+    width: 50%
+```
 
----
+## Public API Reference (Sub-paths)
 
-## 8️⃣ Quick Reference Commands (AI‑friendly)
-| Purpose | Command |
-|---------|---------|
-| Activate LTS Node | `fnm use lts` |
-| Install dependencies | `npm install` |
-| Build the package | `npm run build` |
-| Run tests | `npm test` |
-| Serve demo (optional) | `npm run serve` |
-| Stage a file | `git add <path>` |
-| Signed commit (example) | `git commit -S -m "feat: description of change."` |
-| Verify signature | `git log --show-signature -1` |
-| Test valid import | `node -e "import 'lumina-sass/flexbox'"` |
-| Test invalid import | `node -e "import 'lumina-sass/utils'"` |
+| Path | Description |
+| :--- | :--- |
+| `lumina-sass` | Primary entry point (includes common utilities). |
+| `lumina-sass/flexbox` | Comprehensive flexbox mixins and utility classes. |
+| `lumina-sass/color` | Standardized brand and UI color palettes. |
+| `lumina-sass/mix` | Primary mixins for typography, media queries, and structural elements. |
+| `lumina-sass/map` | Internal configurations and design tokens. |
+| `lumina-sass/contrast` | Automated WCAG contrast ratio verification. |
+| `lumina-sass/func` | Specialized Sass functions for mathematics, logic, and searching. |
 
----
+## Key Features
 
-## 9️⃣ Contact & Further Help
-- For any ambiguity, the AI should ask the user via a clarifying question before proceeding.
-- The AI must always **present a plan before executing** any non‑trivial change (as per user‑global rules).
+- **Standardized Palettes:** Consistent `$brand-color` patterns utilizing `rgb()` for maximum compatibility.
+- **Automated Accessibility:** Integrated WCAG contrast ratio verification.
+- **Specialized Functions:** Dedicated modules for mathematical operations and font stack resolution.
+- **Responsive Utilities:** Intuitive media query helpers (e.g., `on-breakpoint`, `on-dark-mode`).
+- **Flexbox Engine:** A robust suite of mixins for rows, columns, and sophisticated alignment.
 
----
+## Developer Resources
 
-*This guide is version‑controlled along with the rest of the repository, ensuring the AI always has an up‑to‑date reference when working on `lumina-sass`.*
+- [**Documentation Index**](docs/README.md)
+- [**Development Guide**](docs/developer/development.md) – Technical overview and contribution workflows.
+- [**Testing Suite**](docs/developer/testing.md) – Detailed specifications for unit testing and code analysis.
+- [**Sass Testing Quick-Start**](docs/developer/testing.md#unit-testing-with-sass-true) – Direct access to testing methodologies.
+- [**Utility Classes**](docs/utils/utility_classes.md) – A comprehensive inventory of pre-configured CSS classes.
+- [**AI Operations Guide**](docs/ai_guide.md) – Guidance for automated assistant integration.
 
+## Contributing
 
+We welcome contributions to the project. Please consult our [Development Guide](docs/developer/development.md) and ensure that all tests pass successfully prior to submitting a pull request.
 
-## Acknowledgements
+```bash
+# Execute unit testing suite
+npm test
 
-Please see our [Acknowledgements](docs/acknowledgements.md) page for a list of projects, libraries, and people who have inspired or contributed to this work.
+# Execute stylistic analysis
+npm run lint:sass
+```
 
 ## License
 
-MIT
+This project is licensed under the terms of the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "lumina-sass",
-  "version": "2.7.1",
+  "version": "2.8.0",
+  "type": "module",
   "description": "Lumina Sass design tokens, mixins and public sub-modules (flexbox, color, mix).",
   "main": "src/_index.sass",
   "sass": "src/_index.sass",
@@ -13,10 +14,22 @@
       "sass": "./src/flexbox/_index.sass",
       "default": "./src/flexbox/_index.sass"
     },
+    "./generators": {
+      "sass": "./src/mix/_generators.sass",
+      "default": "./src/mix/_generators.sass"
+    },
+    "./mixins": {
+      "sass": "./src/mix/_index.sass",
+      "default": "./src/mix/_index.sass"
+    },
     "./color": {
       "sass": "./src/color/_index.sass",
       "default": "./src/color/_index.sass"
     },
+    "./colors": {
+      "sass": "./src/color/_index.sass",
+      "default": "./src/color/_index.sass"
+    },
     "./mix": {
       "sass": "./src/mix/_index.sass",
       "default": "./src/mix/_index.sass"
@@ -24,6 +37,14 @@
     "./map": {
       "sass": "./src/map/_index.sass",
       "default": "./src/map/_index.sass"
+    },
+    "./contrast": {
+      "sass": "./src/mix/_contrast.sass",
+      "default": "./src/mix/_contrast.sass"
+    },
+    "./func": {
+      "sass": "./src/func/_index.sass",
+      "default": "./src/func/_index.sass"
     }
   },
   "repository": {
@@ -31,13 +52,14 @@
     "url": "https://github.com/NexusWeave/ux-lumina-sass.git"
   },
   "scripts": {
-    "test": "npm run test:sass",
     "serve": "http-server demo",
     "release": "standard-version",
+    "lint:sass": "tsx test/ts/syntax-check.ts",
     "dev": "npm run build && npm run serve",
-    "build:demo": "sass demo/style.sass demo/style.css",
-    "test:sass": "sass src/test/index.spec.sass src/test/index.spec.css",
-    "build": "sass src/_index.sass test/index.css && sass src/color/_index.sass test/color.css && sass src/mix/_index.sass test/mix.css && sass src/flexbox/_index.sass test/flexbox.css && sass src/map/_index.sass test/map.css"
+    "module-test": "tsx test/ts/module-test.ts",
+    "build": "sass demo/style.sass demo/style.css",
+    "test:sass": "sass test/index.spec.sass test/index.spec.css",
+    "test": "npm run test:sass && npm run lint:sass && npm run module-test"
   },
   "files": [
     "src"
@@ -45,9 +67,15 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^25.9.2",
     "http-server": "^14.1.1",
+    "postcss-sass": "^0.5.0",
     "sass": "^1.85.1",
     "sass-true": "^10.1.0",
-    "standard-version": "^9.5.0"
+    "standard-version": "^9.5.0",
+    "stylelint": "^17.13.0",
+    "stylelint-config-standard-scss": "^17.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   }
 }

package/src/_index.sass

@@ -1,7 +1,9 @@
 @forward 'mix'
+@forward 'func'
 @forward 'color'
 @forward 'flexbox'
 
+
 *, *::before, *::after    
     box-sizing: border-box
     writing-mode: horizontal-tb

package/src/color/accents/_index.sass

@@ -1,3 +1,3 @@
 $accent-salmon: rgb(255, 119, 119)
-$accent-slate-blue: rgb(123, 104, 238)
-$accent-lavender: rgb(230, 230, 250)
+$accent-lavender: rgb(230, 230, 250)
+$accent-slate-blue: rgb(123, 104, 238)

package/src/flexbox/_index.sass

@@ -1,5 +1,6 @@
 @use '../mix/index' as mix
 
+@forward '../mix/index'
 @forward 'flexbox-row'
 @forward 'flexbox-column'
 @forward 'flexbox-wrap-row'

package/src/func/_color.sass

@@ -0,0 +1,26 @@
+@use 'sass:math'
+@use 'sass:color'
+
+/// Calculates the relative luminance of a color
+/// @param {Color} $color - The color to calculate luminance for
+/// @return {Number} - The relative luminance (0 to 1)
+@function luminance($color)
+    $red: math.div(color.channel($color, "red", $space: rgb), 255)
+    $green: math.div(color.channel($color, "green", $space: rgb), 255)
+    $blue: math.div(color.channel($color, "blue", $space: rgb), 255)
+
+    $r: if($red <= 0.03928, math.div($red, 12.92), math.pow(math.div($red + 0.055, 1.055), 2.4))
+    $g: if($green <= 0.03928, math.div($green, 12.92), math.pow(math.div($green + 0.055, 1.055), 2.4))
+    $b: if($blue <= 0.03928, math.div($blue, 12.92), math.pow(math.div($blue + 0.055, 1.055), 2.4))
+
+    @return $r * 0.2126 + $g * 0.7152 + $b * 0.0722
+
+/// Calculates the contrast ratio between two colors
+/// @param {Color} $color1 - The first color
+/// @param {Color} $color2 - The second color
+/// @return {Number} - The contrast ratio (1 to 21)
+@function contrast-ratio($color1, $color2)
+    $l1: luminance($color1)
+    $l2: luminance($color2)
+
+    @return math.div(math.max($l1, $l2) + 0.05, math.min($l1, $l2) + 0.05)

package/src/func/_icons.sass

@@ -0,0 +1,8 @@
+@use 'sass:map' as map
+@use '../map/icons' as icon-map
+
+@function find($name)
+  @each $category, $maps in icon-map.$icons
+    @if map.has-key($maps, $name)
+      @return map.get($maps, $name)
+  @return null

package/src/func/_index.sass

@@ -0,0 +1,3 @@
+@forward 'color'
+@forward 'typography'
+@forward 'icons'

package/src/func/_typography.sass

@@ -0,0 +1,40 @@
+@use 'sass:map'
+@use 'sass:list'
+@use '../map/fonts' as fonts
+
+@function get-default-stack($category)
+  @if not map.has-key(fonts.$fonts, $category)
+    @return null
+  $map: map.get(fonts.$fonts, $category)
+  $keys: map.keys($map)
+  $generic: $category
+  @if $category == 'mono'
+    $generic: monospace
+  @return list.append($keys, $generic)
+
+@function is-known-font($font)
+  @if $font == null
+    @return false
+  @if map.has-key(fonts.$fonts, $font)
+    @return true
+  @each $category, $map in fonts.$fonts
+    @if map.has-key($map, $font)
+      @return true
+  @return false
+
+// Helper: return the generic family for a given font name using the fonts map.
+@function font-family-of($font)
+  @if $font == null
+    @return ('Nunito', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif)
+
+  @if map.has-key(fonts.$fonts, $font)
+    @if $font == 'mono'
+      @return monospace
+    @return $font
+
+  @each $category, $map in fonts.$fonts
+    @if map.has-key($map, $font)
+      @return map.get($map, $font)
+
+  // Default fallback stack when font is not found
+  @return ('Nunito', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif)

package/src/map/_flexbox.sass

@@ -10,7 +10,6 @@ $flex-wrap-reversed-row: ('display': flex, 'flex-wrap': wrap, 'flex-direction':
 $flex-wrap-reversed-col: ('display': flex, 'flex-wrap': wrap, 'flex-direction': column-reverse)
 
 
-
 $flexbox:(
     'flex': $flex, 
     'flex-row': $flex-row, 

package/src/map/_icons.sass

@@ -2,7 +2,7 @@
 
 
 $academic: ('school': (icon: "\F671"), 'diploma': (icon: "\F11D"))
-$utility-inputs: ('color': (icon: '\F4B0'), 'hidden': (icon: '\F0E7'))
+$icon-utility-mappings: ('color': (icon: '\F4B0'), 'hidden': (icon: '\F0E7'))
 $boolean-controls: ('radio': (icon: '\F110'), 'checkbox': (icon: '\F272'))
 $video-controls: ('play-video': (icon: '\F4F4'), 'pause-video': (icon: '\F4C4'))
 $documents: ('pdf': (icon: "\F63D"), 'dir': (icon: "\F3D7"), 'default': (icon: "\F369"))
@@ -14,7 +14,7 @@ $communication: ('email': (icon: "\F84B"), 'mail': (icon: "\F32F"), 'github': (i
 
 $icons: (
     'academic': $academic, 'document': $documents, 'misc-icons': $misc-icons,
-    'communication': $communication, 'utility-inputs': $utility-inputs,
+    'communication': $communication, 'utility-inputs': $icon-utility-mappings,
     'input-controls': $input-controls, 'video-controls': $video-controls,
     'boolean-controls': $boolean-controls, 'datetime-pickers': $datetime-pickers,
 )

package/src/map/_index.sass

@@ -1,5 +1,6 @@
+@forward 'fonts'
+@forward 'inputs'
 @forward 'icons'
 @forward 'flexbox'
 @forward 'tag-theme'
-
 @forward 'devices-breakpoints'

package/src/map/_inputs.sass

@@ -1,5 +1,5 @@
 $booleanControls: ( 'radio', 'checkbox' )
-$utility-inputs: ( 'range', 'color', 'hidden' )
+$input-utility-types: ( 'range', 'color', 'hidden' )
 $buttons: ( 'file', 'submit', 'reset', 'button')
 $datetimePickers: ( 'date', 'time', 'week', 'month', 'datetime-local' )
 $inputControls:( 'tel', 'url', 'text', 'email', 'search','number','password' )
@@ -7,7 +7,7 @@ $inputControls:( 'tel', 'url', 'text', 'email', 'search','number','password' )
 $inputs: (
     'buttons': $buttons,
     'inputControls': $inputControls,
-    'utility-inputs': $utility-inputs,
+    'utility-inputs': $input-utility-types,
     'booleanControls': $booleanControls,
     'datetimePickers': $datetimePickers,
     

package/src/mix/_contrast.sass

@@ -0,0 +1,11 @@
+@use '../func/color' as func-color
+
+/// Throws an architectural error if the contrast ratio between two colors fails to meet the specified threshold.
+/// This mixin ensures that color combinations adhere to WCAG accessibility standards during the compilation process.
+/// @param {Color} $foreground - The foreground color to be evaluated.
+/// @param {Color} $background - The background color against which contrast is measured.
+/// @param {Number} $threshold [4.5] - The minimum acceptable contrast ratio (standard WCAG AA compliance is 4.5:1).
+@mixin assert-contrast($foreground, $background, $threshold: 4.5)
+    $ratio: func-color.contrast-ratio($foreground, $background)
+    @if $ratio < $threshold
+        @error "Accessibility Failure: The contrast ratio of #{$ratio} between #{$foreground} and #{$background} does not meet the required threshold of #{$threshold}:1."

package/src/mix/_elements.sass

@@ -31,4 +31,4 @@
 
         color: $color
         cursor: pointer
-        @include typo.text-adjustments()
+        @include typo.text-adjustments($quiet: true)

package/src/mix/_generators.sass

@@ -6,15 +6,10 @@
 @use '../map/icons' as icon-map
 @use '../map/tag-theme' as tag-map
 @use '../map/flexbox' as flexbox-mapping
-
-@function _icon-find($name)
-  @each $category, $maps in icon-map.$icons
-    @if map.has-key($maps, $name)
-      @return map.get($maps, $name)
-  @return null
+@use '../func/icons' as func-icons
 
 @mixin _icon-base($name, $color, $font-family)
-  $props: _icon-find($name)
+  $props: func-icons.find($name)
   @if $props
     .#{$name}
       &::before

package/src/mix/_index.sass

@@ -3,4 +3,5 @@
 @forward 'generators'
 @forward 'buttons'
 @forward 'elements'
-@forward 'misc-styling'
+@forward 'misc-styling'
+@forward 'contrast'

package/src/mix/_typography.sass

@@ -1,9 +1,9 @@
-
 @use 'sass:map'
 @use 'sass:list'
 @use 'sass:meta'
 @use 'sass:string'
 @use '../map/fonts' as fonts
+@use '../func/typography' as func-typo
 
 @mixin text-wrap-safe($inline: 0)
   p, h1, h2, h3, h4, h5, h6, figcaption, a, li
@@ -13,15 +13,15 @@
     overflow-wrap: anywhere
     min-inline-size: $inline
 
-@mixin font( $font:null, $size: 1rem, $family: null, $style: null, $weight: null, $line-height: null, $variant: null)
-  $detected-family: font-family-of($font)
+@mixin font( $font:null, $size: 1rem, $family: null, $style: null, $weight: null, $line-height: null, $variant: null, $quiet: false)
+  $detected-family: func-typo.font-family-of($font)
 
-  @if is-known-font($font)
+  @if func-typo.is-known-font($font)
     $family: $detected-family
   
   @else if $family == null
     $family: $detected-family
-    @if $font != null
+    @if $font != null and $quiet == false
       @warn "Font '#{$font}' not found in configuration map. Defaulting to stack: '#{$font}', #{$family}."
 
   @if meta.type-of($font) == 'list'
@@ -49,59 +49,28 @@
   @if $variant != null
     font-variant: $variant
 
-@function get-default-stack($category)
-  @if not map.has-key(fonts.$fonts, $category)
-    @return null
-  $map: map.get(fonts.$fonts, $category)
-  $keys: map.keys($map)
-  $generic: $category
-  @if $category == 'mono'
-    $generic: monospace
-  @return list.append($keys, $generic)
-
 @mixin sans-serif($font: null, $size: 1rem, $weight: null, $style: null)
   @if $font == null
-    $font: get-default-stack('sans-serif')
+    $font: func-typo.get-default-stack('sans-serif')
   @include font($font, $size, sans-serif, $style, $weight)
 
 @mixin serif($font: null, $size: 1rem, $weight: null, $style: null)
   @if $font == null
-    $font: get-default-stack('serif')
+    $font: func-typo.get-default-stack('serif')
   @include font($font, $size, serif, $style, $weight)
 
 @mixin monospace($font: null, $size: 1rem, $weight: null, $style: null)
   @if $font == null
-    $font: get-default-stack('mono')
+    $font: func-typo.get-default-stack('mono')
   @include font($font, $size, monospace, $style, $weight)
 
-@function is-known-font($font)
-  @if $font == null
-    @return false
-  @if map.has-key(fonts.$fonts, $font)
-    @return true
-  @each $category, $map in fonts.$fonts
-    @if map.has-key($map, $font)
-      @return true
-  @return false
-
-// Helper: return the generic family for a given font name using the fonts map.
-@function font-family-of($font)
-  @if $font == null
-    @return ('Nunito', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif)
-
-  @if map.has-key(fonts.$fonts, $font)
-    @if $font == 'mono'
-      @return monospace
-    @return $font
-
-  @each $category, $map in fonts.$fonts
-    @if map.has-key($map, $font)
-      @return map.get($map, $font)
-
-  // Default fallback stack when font is not found
-  @return ('Nunito', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif)
+@mixin line-clamp($lines: 3)
+  display: -webkit-box
+  -webkit-line-clamp: $lines
+  -webkit-box-orient: vertical
+  overflow: hidden
 
-@mixin text-adjustments($alignment: null, $decoration: null)
+@mixin text-adjustments($alignment: null, $decoration: null, $quiet: false)
   @if $alignment != null
     text-align: $alignment
 
@@ -110,4 +79,5 @@
 
   @if $alignment == null and $decoration == null
     text-decoration: none
-    @warn "No parameters provided for text-adjustments mixin. Default value present."
+    @if $quiet == false
+      @warn "No parameters provided for text-adjustments mixin. Default value present."

package/src/mix/test/_buttons.spec.sass

@@ -1,40 +0,0 @@
-@use 'sass:meta'
-@use '../_buttons' as buttons
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Buttons')
-  @include true.test('Applies base button styling')
-    @include true.assert
-      @include true.output
-        button
-          @include buttons.base-btn()
-      
-      @include true.expect
-        button
-          
-          border: none
-          margin: 0.5em
-          font-size: 1em
-          cursor: pointer
-          font-weight: bold
-          font-style: normal
-          position: relative
-          padding: 0.5em 1.5em
-          border-radius: 0.5em
-          display: inline-block
-          color: rgb(255, 248, 241)
-          background-color: rgb(252, 245, 235)
-          transition: transform 0.2s cubic-bezier(0.175, 0.885, 0.32, 1.275), background-color 0.2s
-
-          &:hover
-            transform: scale(1.05)
-            background-color: rgb(248.6739130435, 233.9130434783, 212.8260869565)
-
-          &:active
-            transform: scale(0.95)
-            background-color: rgb(245.347826087, 222.8260869565, 190.652173913)
-
-          &:disabled
-            opacity: 0.3
-            cursor: not-allowed
-

package/src/mix/test/_elements.spec.sass

@@ -1,38 +0,0 @@
-@use 'sass:meta'
-@use '../_elements' as elements
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Elements')
-  @include true.test('Applies link colors and properties')
-    @include true.assert
-      @include true.output
-        @include elements.link-color(rgb(0, 0, 255), rgb(0, 0, 200), rgb(0, 0, 150), rgb(128, 0, 128))
-      
-      @include true.expect
-        a
-          color: rgb(0, 0, 255)
-          cursor: pointer
-          text-decoration: none
-
-          [aria-disabled="true"]
-            color: rgb(160, 160, 160)
-            cursor: not-allowed
-            pointer-events: none
-            text-decoration: none
-
-          &:active
-            color: rgb(0, 0, 150)
-
-          &.external-link
-            text-decoration: underline
-
-          @media (hover: hover)
-            &:hover
-              color: rgb(0, 0, 200)
-              border-radius: 0.5em
-
-          &:visited
-            color: rgb(128, 0, 128)
-
-          h1, h2, h3, h4, h5, h6
-            color: rgb(0, 0, 255) !important

package/src/mix/test/_generators.spec.sass

@@ -1,63 +0,0 @@
-@use 'sass:meta'
-@use '../_generators' as generators
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Icon Generator')
-  @include true.test('Generates school icon class')
-    @include true.assert
-      @include true.output
-        @include generators.icon-generator('school')
-      
-      @include true.expect
-        .school
-          &::before
-            color: rgb(64, 64, 64) !important
-            font-family: 'bootstrap-icons'
-            content: "\F671"
-
-@include true.test-module('Flexbox Generator')
-  @include true.test('Generates flex-row properties')
-    @include true.assert
-      @include true.output
-        @include generators.flexbox-generator('flex-row')
-      
-      @include true.expect
-        display: flex
-        flex-wrap: nowrap
-        flex-direction: row
-
-@include true.test-module('Input Generator')
-  @include true.test('Generates text input type')
-    @include true.assert
-      @include true.output
-        @include generators.input-generator('text')
-      
-      @include true.expect
-        input[type="text"]
-          cursor: text
-          font-size: 1rem
-          line-height: 1.5
-          padding: 0.5rem 1rem
-          border-radius: 0.5rem
-          box-sizing: border-box
-          focus-outline: rgb(0, 120, 215)
-          background-color: rgb(255, 255, 255)
-          border: rgb(204, 204, 204) solid 0.0625rem
-          outline: 0.0625rem solid rgb(0, 120, 215)
-        
-        input[type="text"]::focus
-          outline: rgb(0, 120, 215)
-        
-        &::-webkit-slider-runnable-track
-          block-size: 0.4rem
-          background: #ddd
-          border-radius: 0.2rem
-        
-        &::-webkit-slider-thumb
-          -webkit-appearance: none
-          inline-size: 1rem
-          block-size: 1rem
-          background: #0078d7
-          border-radius: 50%
-          margin-top: -0.3rem
-

package/src/mix/test/_media.spec.sass

@@ -1,35 +0,0 @@
-@use 'sass:meta'
-@use '../_media' as media
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Media Queries')
-  @include true.test('Generates max-width media query for breakpoint md')
-    @include true.assert
-      @include true.output
-        @include media.media-queries('md')
-          color: blue
-      
-      @include true.expect
-        @media (max-inline-size: 64rem)
-          color: blue
-
-  @include true.test('Generates prefers-color-scheme')
-    @include true.assert
-      @include true.output
-        @include media.prefers-color-scheme(dark)
-          background: black
-      
-      @include true.expect
-        @media (prefers-color-scheme: dark)
-          background: black
-
-  @include true.test('Generates device-media for iphone')
-    @include true.assert
-      @include true.output
-        @include media.device-media('iphone')
-          color: white
-      
-      @include true.expect
-        @media only screen and (min-inline-size: 20rem) and (max-inline-size: 20.125rem) and (min-block-size: 30rem) and (max-block-size: 30.125rem) and (orientation: portrait)
-          color: white
-

package/src/mix/test/_misc-styling.spec.sass

@@ -1,16 +0,0 @@
-@use 'sass:meta'
-@use '../_misc-styling' as misc-styling
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Misc Styling')
-  @include true.test('Applies background and text color')
-    @include true.assert
-      @include true.output
-        .custom-bg
-          @include misc-styling.background-color(rgb(255, 0, 0), rgb(255, 255, 255))
-      
-      @include true.expect
-        .custom-bg
-          color: rgba(255, 255, 255, 1)
-          background-color: rgba(255, 0, 0, 1)
-

package/src/mix/test/_typography.spec.sass

@@ -1,123 +0,0 @@
-@use 'sass:meta'
-@use '../_typography' as typo
-@use '../../../node_modules/sass-true' as true
-
-@include true.test-module('Typography')
-  @include true.test('Generates font styles')
-    @include true.assert
-      @include true.output
-        @include typo.font($size: 2rem, $weight: bold)
-      
-      @include true.expect
-        font-size: 2rem
-        font-weight: bold
-
-  @include true.test('Generates sans-serif styles')
-    @include true.assert
-      @include true.output
-        @include typo.sans-serif('Roboto', $size: 1.5rem)
-      
-      @include true.expect
-        font-family: "Roboto", sans-serif
-        font-size: 1.5rem
-
-  @include true.test('Generates serif styles')
-    @include true.assert
-      @include true.output
-        @include typo.serif('Georgia', $size: 1.2rem)
-      
-      @include true.expect
-        font-family: "Georgia", serif
-        font-size: 1.2rem
-
-  @include true.test('Generates monospace styles')
-    @include true.assert
-      @include true.output
-        @include typo.monospace('Fira Code', $weight: 500)
-      
-      @include true.expect
-        font-family: "Fira Code", monospace
-        font-size: 1rem
-        font-weight: 500
-
-  @include true.test('Returns correct font-family for known font')
-    @include true.assert-equal(typo.font-family-of('Open Sans'), sans-serif)
-
-  @include true.test('Detects generic category names')
-    @include true.assert-equal(typo.font-family-of('mono'), monospace)
-    @include true.assert-equal(typo.font-family-of('serif'), serif)
-
-  @include true.test('Provides fallbacks for unknown fonts in font-family-of')
-    @include true.assert-equal(typo.font-family-of('MyCustomFont'), ('Nunito', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif))
-
-  @include true.test('Generates fallback for unknown font')
-    @include true.assert
-      @include true.output
-        @include typo.font('MyCustomFont')
-      
-      @include true.expect
-        font-family: "MyCustomFont", "Nunito", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif
-
-  @include true.test('Generates fallback for unknown font')
-    @include true.assert
-      @include true.output
-        @include typo.font()
-      
-      @include true.expect
-        font-family: "Nunito", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif
-
-  @include true.test('Does not overwrite explicit fallback override for unknown font')
-    @include true.assert
-      @include true.output
-        @include typo.font('MyCustomFont', $family: serif)
-      
-      @include true.expect
-        font-family: "MyCustomFont", serif
-
-  @include true.test('Generates default fallback stack when no font is provided')
-    @include true.assert
-      @include true.output
-        @include typo.font()
-      
-      @include true.expect
-        font-family: "Nunito", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif
-        font-size: 1rem
-
-  @include true.test('Generates default system sans-serif stack when no font is provided')
-    @include true.assert
-      @include true.output
-        @include typo.sans-serif()
-      
-      @include true.expect
-        font-family: "Roboto", "Helvetica", "Arial", "Work Sans", "Nunito", "Open Sans", "Lato", "Montserrat", "Source Sans Pro", "Inter", "Tahoma", "Verdana", "Gill Sans", "Futura", "Ubuntu", "Noto Sans", "Noto Sans KR", "Noto Sans JP", "Noto Sans SC", "Noto Sans Arabic", "Noto Sans Hebrew", "Bootstrap", "bootstrap-icons", sans-serif
-        font-size: 1rem
-
-  @include true.test('Generates default system serif stack when no font is provided')
-    @include true.assert
-      @include true.output
-        @include typo.serif()
-      
-      @include true.expect
-        font-family: "Georgia", "Times New Roman", "Palatino", "Libre Baskerville", "Merriweather", "PT Serif", "Noto Serif", "Noto Serif KR", "Noto Serif JP", "Noto Serif SC", serif
-        font-size: 1rem
-
-  @include true.test('Generates default system monospace stack when no font is provided')
-    @include true.assert
-      @include true.output
-        @include typo.monospace()
-      
-      @include true.expect
-        font-family: "Courier New", "Consolas", "Ubuntu Mono", "Source Code Pro", "Fira Code", "Inconsolata", "Menlo", "Monaco", "Noto Mono", monospace
-        font-size: 1rem
-
-@include true.test-module('Styling (Native)')
-  @include true.test('Applies typography font styling to figcaption')
-    @include true.assert
-      @include true.output
-        figure figcaption
-          @include typo.font($style: italic)
-      
-      @include true.expect
-        figure figcaption
-          font-style: italic
-

package/src/test/index.spec.sass

@@ -1,11 +0,0 @@
-@use '../../node_modules/sass-true' as true
-
-// Import all colocated Sass tests here
-@use '../mix/test/media.spec'
-@use '../mix/test/buttons.spec'
-@use '../mix/test/elements.spec'
-@use '../mix/test/generators.spec'
-@use '../mix/test/typography.spec'
-@use '../mix/test/misc-styling.spec'
-
-@include true.report