katanakit-js 6.4.3 → 6.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "katanakit-js",
-	"version": "6.4.3",
+	"version": "6.7.1",
 	"description": "KatanaKit — a sharp, framework-agnostic TypeScript service toolkit organized with hexagonal architecture.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -112,12 +112,19 @@
 			"import": "./dist/schemas/index.js",
 			"default": "./dist/schemas/index.js"
 		},
+		"./styles.css": "./dist/styles.css",
+		"./dist/styles.css": "./dist/styles.css",
 		"./package.json": "./package.json"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"scss"
+	],
+	"sass": "scss/main.scss",
+	"style": "./dist/styles.css",
+	"sideEffects": [
+		"*.css"
 	],
-	"sideEffects": false,
 	"engines": {
 		"node": ">=22.18.0"
 	},
@@ -130,31 +137,17 @@
 	"scripts": {
 		"prepare": "husky",
 		"predev": "bunx lint-staged",
-		"dev": "concurrently --names api,assistant,tg,wa \"bun run dev:api\" \"bun run assistant:dev\" \"bun run telegram:dev\" \"bun run whatsapp:dev\"",
-		"postdev": "bun run lint",
-		"dev:api": "tsx src/adapters/express/main.ts",
+		"dev": "tsx src/adapters/express/main.ts",
 		"bun:dev": "bun run src/adapters/bun/main.ts",
-		"assistant:dev": "tsx src/adapters/assistant/main.ts",
-		"telegram:dev": "tsx src/adapters/telegram/main.ts",
-		"whatsapp:dev": "tsx src/adapters/whatsapp/main.ts",
-		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-		"lint": "eslint ./src packages/ui/src",
-		"lint:fix": "eslint --fix ./src packages/ui/src",
-		"lint:staged": "lint-staged",
 		"check": "eslint ./src packages/ui/src && tsc6 --noEmit && tsc6 -p packages/ui/tsconfig.json --noEmit && vitest run",
-		"examples:check": "tsc6 -p tsconfig.examples.json && tsc6 -p tsconfig.examples.solid.json",
 		"fix": "eslint --fix ./src packages/ui/src && tsc6 --noEmit && vitest run",
-		"prebuild": "bunx lint-staged",
-		"build": "bun run clean && bun run check && tsc6 -p tsconfig.json && node scripts/generate-release-notes.mjs --sync-versions",
-		"postbuild": "bun run examples:check",
-		"release": "bun run build && node scripts/generate-release-notes.mjs \"v$(node -p \"require('./package.json').version\")\" --write && npm publish --access public",
+		"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun run check && tsc6 -p tsconfig.json && bun run ui:build && node -e \"require('node:fs').copyFileSync('packages/ui/dist/styles.css','dist/styles.css')\" && node scripts/generate-release-notes.mjs --sync-versions && bun run examples:check",
+		"release": "bun run build && node scripts/generate-release-notes.mjs \"v$(node -p \"require('./package.json').version\")\" --write && (npm whoami >/dev/null 2>&1 || npm login) && npm publish --access public",
 		"ui:build": "bun run --filter @katanakit/ui build",
-		"docs:clean": "node scripts/docs.mjs clean",
-		"docs:prepare": "node scripts/docs-prepare.mjs",
+		"examples:check": "tsc6 -p tsconfig.examples.json && tsc6 -p tsconfig.examples.solid.json",
 		"docs:dev": "node scripts/docs.mjs dev",
-		"predocs": "bunx lint-staged",
 		"docs": "node scripts/docs.mjs build",
-		"postdocs": "node -e \"require('node:fs').accessSync('docs/.vitepress/dist/index.html')\"",
+		"docs:clean": "node scripts/docs.mjs clean",
 		"docs:preview": "vitepress preview docs",
 		"docs:gh": "node scripts/docs.mjs gh",
 		"cf:deploy": "bun run build && bun run docs && wrangler pages deploy docs/.vitepress/dist --project-name katanakit-docs --branch main"
@@ -196,8 +189,8 @@
 	"jsdelivr": "./dist/index.js",
 	"dependencies": {
 		"@js-temporal/polyfill": "0.5.1",
-		"@prisma/orm-postgres": "8.0.0-rc.8",
-		"@tanstack/query-core": "5.103.2",
+		"@prisma/orm-postgres": "8.0.0-rc.14",
+		"@tanstack/query-core": "5.104.1",
 		"express-rate-limit": "8.7.0",
 		"zod": "^4.6.5"
 	},
@@ -206,7 +199,7 @@
 		"@faker-js/faker": ">=9.0.0",
 		"@insforge/sdk": ">=1.5.0",
 		"cors": ">=2.8.0",
-		"dotenv": ">=16.0.0",
+		"dotenv": ">=18.0.5",
 		"express": ">=5.0.0",
 		"react": ">=18.0.0",
 		"react-dom": ">=18.0.0",
@@ -258,34 +251,35 @@
 		}
 	},
 	"devDependencies": {
-		"@angular/core": "^22.1.7",
+		"@angular/core": "^22.2.1",
 		"@eslint/js": "^10.0.1",
 		"@faker-js/faker": "^10.6.0",
 		"@insforge/sdk": "^1.5.2",
+		"@prisma/cli-engine": "0.6.2",
 		"@tailwindcss/vite": "^4.3.3",
 		"@testing-library/react": "^16.3.3",
 		"@types/cors": "2.8.19",
 		"@types/express": "5.0.6",
-		"@types/node": "26.6.2",
+		"@types/node": "26.6.4",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
 		"better-auth": "^1.7.7",
 		"bun-types": "^1.4.2",
 		"concurrently": "^10.0.5",
 		"cors": "2.8.6",
-		"dotenv": "18.0.1",
-		"eslint": "^10.11.0",
+		"dotenv": "18.0.5",
+		"eslint": "^10.12.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-prettier": "^5.5.6",
 		"eslint-plugin-simple-import-sort": "^14.0.0",
 		"express": "5.2.1",
-		"globals": "^17.12.0",
+		"globals": "^17.13.0",
 		"husky": "^9.1.7",
-		"jsdom": "^30.1.0",
+		"jsdom": "^30.1.2",
 		"lint-staged": "^17.6.0",
 		"photoswipe": "^5.4.4",
-		"prettier": "^3.9.8",
-		"prisma": "8.0.0-rc.13",
+		"prettier": "^3.9.9",
+		"prisma": "8.0.0-rc.19",
 		"react": "^19.3.0",
 		"react-dom": "^19.3.0",
 		"rxjs": "^7.8.2",
@@ -295,15 +289,15 @@
 		"tslib": "^2.8.1",
 		"tsx": "4.23.15",
 		"typedoc": "^0.28.20",
-		"typedoc-plugin-markdown": "^4.13.0",
+		"typedoc-plugin-markdown": "^4.13.1",
 		"typedoc-vitepress-theme": "^1.1.4",
 		"typescript": "npm:@typescript/typescript6@6.0.2",
-		"typescript-eslint": "^8.70.0",
-		"vite": "8.3.0",
+		"typescript-eslint": "^8.71.0",
+		"vite": "8.3.2",
 		"vitepress": "^1.6.4",
-		"vitest": "5.0.1",
+		"vitest": "5.0.3",
 		"vue": "3.5.43",
-		"wrangler": "4.141.0",
+		"wrangler": "4.147.0",
 		"zone.js": "^0.16.3"
 	}
 }

package/scss/_flags.scss

@@ -0,0 +1,179 @@
+:root {
+  /* ====================================================================
+   * FAMILIA: ROJO (Pantone 485 / Carmesí) - Base: Aragón, Cataluña, etc.
+   * ==================================================================== */
+  --color-aragon-rojo-100: hsla(3, 100%, 97%, 1);
+  --color-aragon-rojo-200: hsla(3, 100%, 94%, 1);
+  --color-aragon-rojo-300: hsla(3, 100%, 86%, 1);
+  --color-aragon-rojo-400: hsla(3, 90%, 70%, 1);
+  --color-aragon-rojo-500: hsla(3, 85%, 60%, 1); /* Tono base claro */
+  --color-aragon-rojo-600: hsla(3, 79%, 48%, 1); /* Tono original de la bandera */
+  --color-aragon-rojo-700: hsla(3, 75%, 40%, 1);
+  --color-aragon-rojo-800: hsla(3, 70%, 32%, 1);
+  --color-aragon-rojo-900: hsla(3, 65%, 24%, 1);
+
+  /* (Aplica el mismo escalado para Cataluña, Baleares, C. Valenciana, Murcia, Navarra, La Rioja, País Vasco, Cantabria, CLM) */
+  --color-catalunya-rojo-100: hsla(3, 100%, 97%, 1);
+  --color-catalunya-rojo-200: hsla(3, 100%, 94%, 1);
+  --color-catalunya-rojo-300: hsla(3, 100%, 86%, 1);
+  --color-catalunya-rojo-400: hsla(3, 90%, 70%, 1);
+  --color-catalunya-rojo-500: hsla(3, 85%, 60%, 1);
+  --color-catalunya-rojo-600: hsla(3, 79%, 48%, 1);
+  --color-catalunya-rojo-700: hsla(3, 75%, 40%, 1);
+  --color-catalunya-rojo-800: hsla(3, 70%, 32%, 1);
+  --color-catalunya-rojo-900: hsla(3, 65%, 24%, 1);
+
+  /* ====================================================================
+   * FAMILIA: ROJO MADRID / CYL (Base: Hue 355)
+   * ==================================================================== */
+  --color-madrid-rojo-100: hsla(355, 100%, 97%, 1);
+  --color-madrid-rojo-200: hsla(355, 100%, 94%, 1);
+  --color-madrid-rojo-300: hsla(355, 100%, 86%, 1);
+  --color-madrid-rojo-400: hsla(355, 90%, 70%, 1);
+  --color-madrid-rojo-500: hsla(355, 85%, 60%, 1);
+  --color-madrid-rojo-600: hsla(355, 82%, 46%, 1); /* Tono original */
+  --color-madrid-rojo-700: hsla(355, 75%, 38%, 1);
+  --color-madrid-rojo-800: hsla(355, 70%, 30%, 1);
+  --color-madrid-rojo-900: hsla(355, 65%, 22%, 1);
+
+  --color-cyl-rojo-100: hsla(355, 100%, 97%, 1);
+  --color-cyl-rojo-200: hsla(355, 100%, 94%, 1);
+  --color-cyl-rojo-300: hsla(355, 100%, 86%, 1);
+  --color-cyl-rojo-400: hsla(355, 90%, 70%, 1);
+  --color-cyl-rojo-500: hsla(355, 85%, 60%, 1);
+  --color-cyl-rojo-600: hsla(355, 82%, 46%, 1);
+  --color-cyl-rojo-700: hsla(355, 75%, 38%, 1);
+  --color-cyl-rojo-800: hsla(355, 70%, 30%, 1);
+  --color-cyl-rojo-900: hsla(355, 65%, 22%, 1);
+
+  /* ====================================================================
+   * FAMILIA: AMARILLO / ORO (Pantone 109 / 116) - Aragón, Asturias, C. Valenciana
+   * ==================================================================== */
+  --color-aragon-amarillo-100: hsla(49, 100%, 95%, 1);
+  --color-aragon-amarillo-200: hsla(49, 100%, 90%, 1);
+  --color-aragon-amarillo-300: hsla(49, 100%, 80%, 1);
+  --color-aragon-amarillo-400: hsla(49, 100%, 65%, 1);
+  --color-aragon-amarillo-500: hsla(49, 100%, 55%, 1); /* Tono base */
+  --color-aragon-amarillo-600: hsla(49, 100%, 50%, 1); /* Tono original */
+  --color-aragon-amarillo-700: hsla(49, 90%, 42%, 1);
+  --color-aragon-amarillo-800: hsla(49, 80%, 32%, 1);
+  --color-aragon-amarillo-900: hsla(49, 70%, 22%, 1);
+
+  --color-asturias-amarillo-100: hsla(46, 100%, 95%, 1);
+  --color-asturias-amarillo-200: hsla(46, 100%, 90%, 1);
+  --color-asturias-amarillo-300: hsla(46, 100%, 80%, 1);
+  --color-asturias-amarillo-400: hsla(46, 100%, 65%, 1);
+  --color-asturias-amarillo-500: hsla(46, 100%, 55%, 1);
+  --color-asturias-amarillo-600: hsla(46, 100%, 50%, 1); /* Tono original */
+  --color-asturias-amarillo-700: hsla(46, 90%, 42%, 1);
+  --color-asturias-amarillo-800: hsla(46, 80%, 32%, 1);
+  --color-asturias-amarillo-900: hsla(46, 70%, 22%, 1);
+
+  /* ====================================================================
+   * FAMILIA: VERDE (Andalucía, Extremadura, País Vasco, La Rioja)
+   * ==================================================================== */
+  --color-andalucia-verde-100: hsla(147, 60%, 95%, 1);
+  --color-andalucia-verde-200: hsla(147, 70%, 85%, 1);
+  --color-andalucia-verde-300: hsla(147, 80%, 70%, 1);
+  --color-andalucia-verde-400: hsla(147, 90%, 45%, 1);
+  --color-andalucia-verde-500: hsla(147, 100%, 30%, 1);
+  --color-andalucia-verde-600: hsla(147, 100%, 20%, 1); /* Tono original */
+  --color-andalucia-verde-700: hsla(147, 90%, 16%, 1);
+  --color-andalucia-verde-800: hsla(147, 80%, 12%, 1);
+  --color-andalucia-verde-900: hsla(147, 70%, 8%, 1);
+
+  --color-pv-verde-100: hsla(141, 50%, 95%, 1);
+  --color-pv-verde-200: hsla(141, 60%, 85%, 1);
+  --color-pv-verde-300: hsla(141, 70%, 70%, 1);
+  --color-pv-verde-400: hsla(141, 80%, 50%, 1);
+  --color-pv-verde-500: hsla(141, 70%, 40%, 1);
+  --color-pv-verde-600: hsla(141, 60%, 30%, 1); /* Tono original */
+  --color-pv-verde-700: hsla(141, 60%, 24%, 1);
+  --color-pv-verde-800: hsla(141, 60%, 18%, 1);
+  --color-pv-verde-900: hsla(141, 60%, 12%, 1);
+
+  /* ====================================================================
+   * FAMILIA: AZUL (Asturias, Canarias, Galicia, Melilla)
+   * ==================================================================== */
+  --color-asturias-azul-100: hsla(219, 100%, 95%, 1);
+  --color-asturias-azul-200: hsla(219, 100%, 85%, 1);
+  --color-asturias-azul-300: hsla(219, 100%, 70%, 1);
+  --color-asturias-azul-400: hsla(219, 100%, 50%, 1);
+  --color-asturias-azul-500: hsla(219, 100%, 40%, 1);
+  --color-asturias-azul-600: hsla(219, 100%, 30%, 1); /* Tono original */
+  --color-asturias-azul-700: hsla(219, 90%, 24%, 1);
+  --color-asturias-azul-800: hsla(219, 80%, 18%, 1);
+  --color-asturias-azul-900: hsla(219, 70%, 12%, 1);
+
+  --color-galicia-azul-100: hsla(215, 60%, 95%, 1);
+  --color-galicia-azul-200: hsla(215, 70%, 85%, 1);
+  --color-galicia-azul-300: hsla(215, 76%, 70%, 1);
+  --color-galicia-azul-400: hsla(215, 76%, 55%, 1);
+  --color-galicia-azul-500: hsla(215, 76%, 50%, 1);
+  --color-galicia-azul-600: hsla(215, 76%, 44%, 1); /* Tono original */
+  --color-galicia-azul-700: hsla(215, 70%, 35%, 1);
+  --color-galicia-azul-800: hsla(215, 60%, 25%, 1);
+  --color-galicia-azul-900: hsla(215, 50%, 15%, 1);
+
+  /* ====================================================================
+   * FAMILIA: MORADO / PÚRPURA (Baleares)
+   * ==================================================================== */
+  --color-baleares-morado-100: hsla(269, 60%, 95%, 1);
+  --color-baleares-morado-200: hsla(269, 70%, 85%, 1);
+  --color-baleares-morado-300: hsla(269, 70%, 70%, 1);
+  --color-baleares-morado-400: hsla(269, 70%, 55%, 1);
+  --color-baleares-morado-500: hsla(269, 66%, 45%, 1);
+  --color-baleares-morado-600: hsla(269, 66%, 36%, 1); /* Tono original */
+  --color-baleares-morado-700: hsla(269, 60%, 28%, 1);
+  --color-baleares-morado-800: hsla(269, 50%, 20%, 1);
+  --color-baleares-morado-900: hsla(269, 40%, 12%, 1);
+
+  /* ====================================================================
+   * FAMILIA: BLANCOS Y NEGROS (Ajuste de grises puros)
+   * ==================================================================== */
+  --color-comun-blanco-100: hsla(0, 0%, 100%, 1); /* Blanco base */
+  --color-comun-blanco-200: hsla(0, 0%, 97%, 1);
+  --color-comun-blanco-300: hsla(0, 0%, 92%, 1);
+  --color-comun-blanco-400: hsla(0, 0%, 85%, 1);
+  
+  --color-comun-negro-500: hsla(0, 0%, 30%, 1); /* Gris oscuro base */
+  --color-comun-negro-600: hsla(0, 0%, 20%, 1);
+  --color-comun-negro-700: hsla(0, 0%, 12%, 1);
+  --color-comun-negro-800: hsla(0, 0%, 6%, 1);
+  --color-comun-negro-900: hsla(0, 0%, 0%, 1);  /* Negro base banderas */
+}
+
+// Prompt Chat ZAI https://chat.z.ai/s/d396b707-2a68-48fa-bd7d-4ccf0d05185f
+:root {
+  /* =========================================
+   * COMUNIDAD DE MADRID (Rojo, Blanco y Amarillo)
+   * (Estrellas blancas sobre fondo rojo)
+   * ========================================= */
+  --madrid-rojo: hsla(355, 82%, 46%, 1);       /* Rojo Carmesí (Pantone 485) */
+  --madrid-blanco: hsla(0, 0%, 100%, 1);       /* Blanco */
+  --madrid-amarillo: hsla(44, 100%, 50%, 1);   /* Amarillo */
+
+  /* =========================================
+   * REGIÓN DE MURCIA (Rojo y Blanco)
+   * ========================================= */
+  --murcia-rojo: hsla(3, 79%, 48%, 1);        /* Rojo (Pantone 485) */
+  --murcia-blanco: hsla(0, 0%, 100%, 1);      /* Blanco */
+
+  /* =========================================
+   * COMUNIDAD FORAL DE NAVARRA (Rojo y Oro/Amarillo)
+   * (Cadenas de oro sobre fondo rojo)
+   * ========================================= */
+  --navarra-rojo: hsla(3, 79%, 48%, 1);       /* Rojo (Pantone 485) */
+  --navarra-oro: hsla(45, 100%, 50%, 1);      /* Oro/Amarillo */
+}
+
+
+/*
+ * 💡 Notas sobre este enfoque:
+El método Tailwind: Tailwind no usa transparencias (Alfa) para sus escalas, sino que reduce la saturación a medida que sube la luminosidad (para evitar que los colores claros se vean "deslavados" o pastel) y aumenta la oscuridad reduciendo luminosidad. Este código replica exactamente esa matemática con tus HSLA.
+Familias unificadas: En lugar de tener --color-murcia-rojo-600 y --color-catalunya-rojo-600 con el mismo valor hexadecimal repetido, puedes usar --color-aragon-rojo-600 (que es el Pantone 485 oficial) para cualquier bandera que use ese mismo rojo, manteniendo tu código CSS mucho más limpio. He incluido Cataluña como ejemplo de cómo se replicaría, pero puedes aplicar la escala de Aragón al resto.
+Blancos y Negros: Para los blancos y negros, al no tener matiz (Hue 0) ni saturación (Sat 0%), la escala de Tailwind se convierte en una simple escala de grises (Lightness). He añadido la variable --color-comun- para estas, ya que el blanco de Extremadura es el mismo que el de Madrid o Canarias.
+ * 
+ * 
+ * 
+ */

package/scss/_functions.scss

@@ -0,0 +1,168 @@
+// ============================================================
+//  _functions.scss
+//  Pure Sass functions: unit conversion, color manipulation and
+//  fluid typography. They emit no CSS by themselves — use them
+//  inside your own rules or mixins.
+// ============================================================
+@use "sass:math";
+@use "sass:color";
+@use "sass:meta";
+@use "sass:string";
+@use "sass:list";
+
+// Root font-size. Must match the --root-font-size you set in the reset
+// (62.5% → 10px on 16px browsers). This makes 1rem = 10px, so rem()
+// and px() produce values where rem ≈ px.
+// Override before importing this module (!default semantics).
+$base-font-size: 10px !default;
+
+// ============================================================
+//  PRIVATE HELPERS
+// ============================================================
+
+// Recursively replaces every occurrence of $search inside $string.
+// Used by to-class() to escape CSS selectors.
+@function _str-replace($string, $search, $replace: "") {
+  $index: string.index($string, $search);
+  @if not $index { @return $string; }
+  @return string.slice($string, 1, $index - 1) + $replace +
+    _str-replace(string.slice($string, $index + string.length($search)), $search, $replace);
+}
+
+// ============================================================
+//  UNIT CONVERSION
+//  Convert between px, rem and other CSS units.
+//  All conversions respect $base-font-size (default 10px).
+// ============================================================
+
+// Convert a px value to rem. Accepts unitless numbers (treated as px)
+// or values with a px unit.
+// Example: f.rem(16px) → 1.6rem (16 / 10).
+@function rem($size) {
+  @if meta.type-of($size) != "number" {
+    @error "rem(): se esperaba un número, recibió #{meta.inspect($size)}.";
+  }
+  $px: if(sass(math.is-unitless($size)): $size; else: math.div($size, 1px));
+  $base: math.div($base-font-size, 1px);
+  @return math.div($px, $base) * 1rem;
+}
+
+// Convert a rem value to px. Unitless numbers are treated as rem.
+// Example: f.px(1.6rem) → 16px (1.6 * 10).
+@function px($size) {
+  @if meta.type-of($size) != "number" {
+    @error "px(): se esperaba un número, recibió #{meta.inspect($size)}.";
+  }
+  $num: if(sass(math.is-unitless($size)): $size; else: math.div($size, 1rem));
+  $base: math.div($base-font-size, 1px);
+  @return $num * $base * 1px;
+}
+
+// Append a unit to a unitless number (values that already have a
+// unit are returned unchanged). Valid units: rem, px, em, %.
+// Example: f.to-unit(4, "rem") → 4rem.
+@function to-unit($value, $unit: "rem") {
+  @if meta.type-of($value) != "number" {
+    @error "to-unit(): se esperaba un número, recibió #{meta.inspect($value)}.";
+  }
+  @if not math.is-unitless($value) { @return $value; }
+  $valid: ("rem", "px", "em", "%");
+  @if not list.index($valid, $unit) {
+    @error "to-unit(): unidad '#{$unit}' no válida. Use: rem, px, em, %.";
+  }
+  @if $unit == "rem" { @return $value * 1rem; }
+  @if $unit == "px"  { @return $value * 1px; }
+  @if $unit == "em"  { @return $value * 1em; }
+  @if $unit == "%"   { @return $value * 1%; }
+  @error "to-unit(): caso no cubierto para '#{$unit}'.";
+}
+
+// Remove the unit from a number by dividing by its own unit.
+// Example: f.strip-unit(16px) → 16.
+@function strip-unit($value) {
+  @if meta.type-of($value) != "number" { @error "strip-unit(): se esperaba un número."; }
+  @return math.div($value, ($value * 0 + 1));
+}
+
+// ============================================================
+//  FLUID TYPOGRAPHY (clamp)
+// ============================================================
+
+// Builds a clamp() value that scales linearly from $min at
+// $min-vw viewport width to $max at $max-vw. Unitless numbers are
+// treated as px. Uses the classic slope/intercept formula:
+// preferred = slope * 100vw ± intercept, clamped between min and max.
+// Example: f.fluid(16, 24) →
+//   clamp(16px, 0.5vw + 14.4px, 24px) between 320px and 1920px.
+@function fluid($min, $max, $min-vw: 320px, $max-vw: 1920px) {
+  $min-val: if(sass(math.is-unitless($min)): $min * 1px; else: $min);
+  $max-val: if(sass(math.is-unitless($max)): $max * 1px; else: $max);
+  $vw-min: if(sass(math.is-unitless($min-vw)): $min-vw * 1px; else: $min-vw);
+  $vw-max: if(sass(math.is-unitless($max-vw)): $max-vw * 1px; else: $max-vw);
+
+  $slope: math.div(
+    strip-unit($max-val) - strip-unit($min-val),
+    strip-unit($vw-max) - strip-unit($vw-min)
+  );
+  $intercept: strip-unit($min-val) - ($slope * strip-unit($vw-min));
+
+  $sign: if(sass($intercept >= 0): "+"; else: "-");
+  $preferred: #{$slope * 100}vw #{$sign} #{math.abs($intercept)}px;
+
+  @return clamp(#{$min-val}, #{$preferred}, #{$max-val});
+}
+
+// ============================================================
+//  COLOR MANIPULATION
+// ============================================================
+
+// Mix a color toward white. $amount is a percentage (unitless
+// numbers are treated as %). f.tint($c, 20%) = 20% white + 80% $c.
+@function tint($color, $amount: 10%) {
+  @if meta.type-of($color) != "color" { @error "tint(): se esperaba un color."; }
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  @return color.mix(white, $color, $pct);
+}
+
+// Mix a color toward black. Inverse of tint().
+@function shade($color, $amount: 10%) {
+  @if meta.type-of($color) != "color" { @error "shade(): se esperaba un color."; }
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  @return color.mix(black, $color, $pct);
+}
+
+// Scale saturation up/down by $amount percentage points.
+@function saturate-color($color, $amount: 10%) { @return color.scale($color, $saturation: $amount); }
+@function desaturate-color($color, $amount: 10%) { @return color.scale($color, $saturation: -$amount); }
+// Hue-rotate the color by 180° (the complementary color).
+@function complement($color) { @return color.complement($color); }
+
+// Returns black or white (or your own pair) depending on which has
+// better contrast against $color, using perceptual luminance weights
+// (0.299/0.587/0.114). Bright colors return $dark, dark ones $light.
+@function contrast($color, $light: white, $dark: black) {
+  $brightness: (color.red($color) * 0.299 + color.green($color) * 0.587 + color.blue($color) * 0.114) / 255;
+  @return if(sass($brightness > 0.5): $dark; else: $light);
+}
+
+// Builds a CSS color-mix() that blends a custom property with
+// another color at runtime. $var-name is accepted with or without
+// the var() wrapper. Example:
+// f.color-mix-var(--purple-500, 20%) →
+//   color-mix(in srgb, var(--purple-500) 80%, white).
+@function color-mix-var($var-name, $amount: 10%, $mix-with: white) {
+  $name: if(sass(string.index($var-name, "var(") == 1): $var-name; else: "var(#{$var-name})");
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  $color-pct: 100% - $pct;
+  @return color-mix(in srgb, #{$name} #{$color-pct}, #{$mix-with});
+}
+
+// Escapes characters that are invalid in CSS class selectors
+// ('.', '/', '%') so a token key can be used as a class name.
+@function to-class($key) {
+  $str: "#{$key}";
+  $str: _str-replace($str, ".", "\\.");
+  $str: _str-replace($str, "/", "\\/");
+  $str: _str-replace($str, "%", "\\%");
+  @return $str;
+}