kni-cascade 1.0.0

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged || { echo 'Commit failed: lint-staged errors'; exit 1; }

package/.stylelintrc.cjs

@@ -0,0 +1,38 @@
+module.exports = {
+  extends: ['stylelint-config-standard-scss'],
+  ignoreFiles: [
+    '**/*.{js,mjs,jsx,ts,tsx,json,md,mdx}',
+    'test/*.{css,css.map}',
+  ],
+  rules: {
+    'annotation-no-unknown': [true, { ignoreAnnotations: ['default'] }],
+    'scss/at-import-no-partial-leading-underscore': null,
+    'custom-property-pattern': null,
+    'declaration-block-no-redundant-longhand-properties': null,
+    'function-no-unknown': null,
+    'function-name-case': null,
+    'keyframes-name-pattern': null,
+    'no-descending-specificity': null,
+    'property-no-vendor-prefix': null,
+    'selector-no-vendor-prefix': null,
+    'scss/no-global-function-names': null,
+    'scss/at-if-no-null': null,
+    'unit-no-unknown': [true, { ignoreUnits: ['pxv'] }],
+    'media-query-no-invalid': null,
+    'media-feature-range-notation': null,
+    'no-empty-source': null,
+    'max-nesting-depth': 4,
+    'declaration-no-important': null,
+    'selector-class-pattern': null,
+    'selector-id-pattern': null,
+    'selector-max-id': 2,
+    'scss/dollar-variable-colon-space-after': 'at-least-one-space',
+    'scss/dollar-variable-colon-space-before': 'never',
+  },
+  overrides: [
+    {
+      files: ['**/*.scss'],
+      customSyntax: 'postcss-scss',
+    },
+  ],
+};

package/gulpfile.js

@@ -0,0 +1,160 @@
+/**
+ * 🧠 KNI Cascade — Gulpfile
+ * Local dev / test harness for the Cascade engine.
+ *
+ * - test/styles.scss is the entry for local testing
+ * - test/styles.scss should `@use '../scss/styles' as *;`
+ * - Compiles test/styles.scss -> test/styles.css
+ * - Applies postcss-pxv
+ * - Uses .stylelintrc.cjs for linting (auto-resolved by Stylelint)
+ */
+
+const gulp = require('gulp');
+const plumber = require('gulp-plumber');
+const gulpSass = require('gulp-dart-sass');
+const sourcemaps = require('gulp-sourcemaps');
+const postcss = require('gulp-postcss');
+const browserSync = require('browser-sync').create();
+const { exec } = require('child_process');
+const colors = require('ansi-colors');
+const path = require('path');
+const postcssPxv = require('postcss-pxv');
+
+// --------------------------
+// 🔍 Paths (engine-local)
+// --------------------------
+const paths = {
+  scssSrc: path.resolve(__dirname, 'scss'),
+  entry: path.resolve(__dirname, 'test/styles.scss'),
+  dist: path.resolve(__dirname, 'test'),
+  cssOutput: 'styles.css',
+};
+
+const sassSrcFile = paths.entry;
+const sassOutDir = paths.dist;
+
+const sassWatchDir = [
+  path.join(paths.scssSrc, '**/*.scss'),
+  path.resolve(__dirname, 'test/**/*.scss'),
+];
+
+const htmlWatchDir = './test/**/*.html';
+
+// --------------------------
+// 🔍 Lint SCSS (non-blocking)
+// --------------------------
+gulp.task('lint-css-fix', function (done) {
+  const lintCmd = [
+    'npx stylelint',
+    `"${paths.scssSrc}/**/*.scss"`,
+    '"test/**/*.scss"',
+    '--fix',
+    '--formatter string',
+  ].join(' ');
+
+  exec(lintCmd, function (err, stdout, stderr) {
+    if (stdout) {
+      const coloredOutput = stdout
+        .replace(/✖/g, colors.red('✖'))
+        .replace(/⚠️/g, colors.yellow('⚠️'))
+        .replace(/\.scss/g, colors.cyan('.scss'))
+        .replace(/\(\S+\)/g, (match) => colors.dim(match));
+      console.log(coloredOutput);
+    }
+
+    if (stderr) console.error(colors.red(stderr));
+
+    if (err) {
+      console.log(
+        colors.yellow(
+          '⚠️  Stylelint reported/fixed issues (non-blocking for build)',
+        ),
+      );
+    } else {
+      console.log(
+        colors.green(
+          '✅  Stylelint clean — all formatting issues resolved',
+        ),
+      );
+    }
+
+    done();
+  });
+});
+
+// --------------------------
+// 🧩 Build SCSS → CSS
+// --------------------------
+gulp.task('build-sass', async function () {
+  const postcssPlugins = [
+    postcssPxv({
+      writeVars: false,
+    }),
+  ];
+
+  return await gulp
+    .src(sassSrcFile)
+    .pipe(sourcemaps.init())
+    .pipe(plumber())
+    .pipe(
+      gulpSass({ outputStyle: 'expanded' }).on(
+        'error',
+        gulpSass.logError,
+      ),
+    )
+    .pipe(postcss(postcssPlugins))
+    .pipe(
+      sourcemaps.write('./', {
+        includeContent: true,
+        sourceRoot: '../scss',
+      }),
+    )
+    .pipe(gulp.dest(sassOutDir))
+    .pipe(browserSync.stream())
+    .on('end', () => {
+      console.log(
+        colors.green(
+          `✅ Built test/styles.scss → ${path.join(
+            sassOutDir,
+            paths.cssOutput,
+          )}`,
+        ),
+      );
+    });
+});
+
+// --------------------------
+// ⚙️ Serve + Watch (local dev)
+// --------------------------
+gulp.task(
+  'serve',
+  gulp.series('lint-css-fix', 'build-sass', function () {
+    browserSync.init({
+      server: { baseDir: './test' },
+      open: false,
+      notify: false,
+    });
+
+    gulp
+      .watch(sassWatchDir)
+      .on('change', (changedFile) => {
+        console.log(
+          colors.cyan(
+            `📂 File changed: ${path.relative(
+              __dirname,
+              changedFile,
+            )}`,
+          ),
+        );
+      })
+      .on('change', gulp.series('lint-css-fix', 'build-sass'));
+
+    gulp.watch(htmlWatchDir).on('change', browserSync.reload);
+  }),
+);
+
+// --------------------------
+// 🎯 Tasks
+// --------------------------
+gulp.task('build', gulp.series('lint-css-fix', 'build-sass'));
+gulp.task('default', gulp.series('serve'));

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "kni-cascade",
+  "version": "1.0.0",
+  "description": "KNI Cascade — an opinionated SCSS engine and single source of truth for design scaling.",
+  "main": "scss",
+  "engines": {
+    "node": ">=18 <=22",
+    "npm": ">=8 <=10"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "build": "npm run gulp-build",
+    "deploy": "npm run stylelint && npm run build",
+    "gulp": "gulp",
+    "gulp-build": "gulp build-sass",
+    "http-server": "http-server",
+    "serve": "cd test && npm run http-server",
+    "stylelint": "npx stylelint \"**/*.{css,sass,scss}\"",
+    "prepare": "husky install && npm run husky:init",
+    "husky:init": "test -f .husky/pre-commit || npm run husky:create",
+    "husky:create": "npx husky add .husky/pre-commit \"npx lint-staged || { echo 'Commit failed: lint-staged errors'; exit 1; }\" && chmod +x .husky/pre-commit",
+    "prepublishOnly": "npm install && npm run build",
+    "postinstall": "echo '\n✅ KNI Cascade ready — Husky & lint-staged configured!\n'"
+  },
+  "author": "Daniel Box",
+  "license": "ISC",
+  "dependencies": {
+    "gulp": "^4.0.2",
+    "gulp-purge-sourcemaps": "^1.0.0",
+    "gulp-rename": "^2.0.0",
+    "postcss-pxv": "^2.0.0"
+  },
+  "devDependencies": {
+    "browser-sync": "^3.0.4",
+    "caniuse-lite": "^1.0.30001746",
+    "gulp-autoprefixer": "^8.0.0",
+    "gulp-dart-sass": "^1.1.0",
+    "gulp-insert": "^0.5.0",
+    "gulp-plumber": "^1.2.1",
+    "gulp-postcss": "^9.0.1",
+    "gulp-sourcemaps": "^3.0.0",
+    "http-server": "^14.1.1",
+    "husky": "^8.0.3",
+    "lint-staged": "^13.0.3",
+    "postcss": "^8.4.28",
+    "sass": "^1.69.5",
+    "stylelint": "^16.25.0",
+    "stylelint-config-standard": "^36.0.1",
+    "stylelint-config-standard-scss": "^14.0.0",
+    "stylelint-scss": "^6.2.1"
+  },
+  "lint-staged": {
+    "*.{scss,css}": [
+      "stylelint --fix"
+    ]
+  }
+}

package/pull_request_template.md

@@ -0,0 +1,3 @@
+## Required items for every merge
+
+- [ ] Update `package.json` and `package-lock.json` version accordingly.

package/readme.md

@@ -0,0 +1,125 @@
+# KNI Cascade
+
+A modern front-end architecture creating a single source of truth for all our CSS — across **WordPress**, **React**, **static**, or any future builds.
+
+KNI Cascade unifies structure, tooling, and logic into a maintainable, portable system for all front-end projects.  
+It’s designed for **clarity, scalability, and minimal friction** — a single shared foundation that powers every KNI build.
+
+## What We Package
+
+<table>
+  <thead>
+    <tr>
+      <th>Category</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>SCSS Boilerplate</strong></td>
+      <td>
+        <ul>
+          <li>Modern, layered structure that fixes inheritance issues</li>
+          <li>Clear separation of responsibility → <BR><code>00-config → 01-base → 02-components → 03-modules → 04-pages</code></li>
+          <li>Config-first system — tokens, mixins, and primitives power everything downstream</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Sass (SCSS)</strong></td>
+      <td>
+        <ul>
+          <li>Clean, familiar syntax and developer experience</li>
+          <li>Zero CSS output from config layer ensures predictable, isolated overrides</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td><strong>PostCSS PXV</strong></td>
+      <td>Our custom viewport unit plugin
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Stylelint config</strong></td>
+      <td>Centralized configs for Stylelint
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Folder Structure
+
+```plaintext
+scss/
+├── 00-config/      # Tokens, mixins, functions, no CSS output
+├── 01-base/        # Resets, type, layout, and core utilities
+├── 02-components/  # Reusable UI building blocks
+├── 03-modules/     # Larger composite regions (header, hero, footer)
+├── 04-pages/       # Page-specific overrides
+└── styles.scss    # Public entry file for final CSS build
+```
+
+---
+
+## 🧩 Core Features
+
+- **Fluid Typography** – Scales seamlessly across breakpoints using `$type-scale` maps
+- **Viewport-Based Units (`pxv`)** – Uniform responsive sizing with fallback support
+- **Token-Driven Architecture** – Edit `_settings.scss` to update a project globally
+- **Predictable Cascade** – Each layer builds safely on the one before it
+- **Framework-Agnostic** – Single source of truth across any kni boilerplate
+
+---
+
+## ⚙️ Local Build Setup
+
+```bash
+# install dependencies
+npm install
+
+# run local dev build
+npx gulp
+```
+
+By default, **Gulp** runs:
+
+- `sass` → compile SCSS → CSS
+- `postcss` → apply pxv
+- `stylelint` → lint & auto-fix code style
+- `browsersync` → live-reload for local development
+
+---
+
+## Design Principles
+
+1. **Settings-first** – All editable project values live in `_settings.scss`.
+2. **No CSS output in config** – Logic, not styling.
+3. **Token inheritance** – Everything flows from primitives to components.
+4. **Small overrides > big rewrites** – The cascade should always work with you.
+5. **Readable by default** – Comments are documentation.
+
+---
+
+## 🧰 Requirements
+
+- Node v18+
+- npm or pnpm
+- Gulp CLI (global)
+
+---
+
+## 🧑‍💻 Contributing
+
+1. Clone this repo
+2. Create a new branch
+3. Run `npx gulp` and make your changes
+4. Submit a PR with a clear summary
+
+---
+
+## 🪄 Quick Philosophy
+
+> _“If it’s visual, it lives in base.  
+> If it’s reusable, it lives in components.  
+> If it’s page-specific, it lives in pages.  
+> And if it defines how the system works — it lives in config.”_

package/scss/00-config/_index.scss

@@ -0,0 +1,4 @@
+@forward 'settings';
+@forward 'primitives';
+@forward 'mixins';
+@forward 'functions';

package/scss/00-config/_mixins.scss

@@ -0,0 +1,112 @@
+@use 'settings' as *;
+@use 'primitives' as *;
+@use "sass:map";
+
+// Powers all type-sizing - see settings map
+@mixin type-scale($token, $mq: $type-scale-breakpoint) {
+  $scale: map.get($type-scale, $token);
+
+  @if $scale == null {
+    @warn "⚠️ Unknown token: #{$token}.";
+  } @else {
+    $desktop-size: map.get($scale, desktop);
+    $mobile-size: map.get($scale, mobile);
+
+    --font-size: #{$mobile-size}pxv;
+
+    @media (min-width: #{$mq}px) {
+      --font-size: #{$desktop-size}pxv;
+    }
+  }
+}
+
+// Fluid type - no edit
+@mixin fluid-type {
+  :where(*, *::before, *::after) {
+    font-size: clamp(var(--font-min-clamp), var(--font-size), var(--font-max-clamp));
+  }
+}
+
+@mixin touch-device {
+  @media (hover: none) {
+    @content;
+  }
+}
+
+// Breakpoint mixins used across layout - add your own
+@mixin sm {
+  @media (max-width: #{$tm - 1}px) {
+    @content;
+  }
+}
+
+@mixin lg {
+  @media (min-width: #{$tm}px) {
+    @content;
+  }
+}
+
+@mixin max {
+  @media (min-width: #{$desktop-max}px) {
+    @content;
+  }
+}
+
+@mixin screen-reader-only {
+  position: absolute;
+  overflow: hidden;
+  top: auto;
+  left: -10000px;
+  clip: rect(1px, 1px, 1px, 1px);
+  clip-path: inset(50%);
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+}
+
+@mixin focus {
+  &:focus,
+  > *:focus {
+    outline: none;
+  }
+
+  &:focus > * {
+    box-shadow: 0 0 0 2px #0061c7;
+    border-radius: 2px;
+  }
+}
+
+@mixin no-focus {
+  &:focus,
+  > *:focus {
+    outline: none;
+  }
+
+  &:focus > * {
+    box-shadow: none;
+    border-radius: 0;
+  }
+}
+
+@mixin abs-full {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+@mixin wp-admin-bar {
+  #wpadminbar {
+    position: fixed !important;
+    opacity: 0.3 !important;
+    transition: transform 0.3s, opacity 0.3s;
+    transform: translateY(-80%) !important;
+
+    &:hover {
+      opacity: 1 !important;
+      transform: none !important;
+    }
+  }
+}

package/scss/00-config/_primitives.scss

@@ -0,0 +1,53 @@
+@use 'settings' as *;
+
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// 📄 _primitives.scss
+// System-level "physics" of the design system — how scaling, pxv units,
+// and fluid typography behave under the hood. You normally don’t edit this.
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+
+// 🧩  Breakpoints for Sassy mqs - see mixins
+// -----------------------------------------------------------------------------
+$ms: 320 !default; // Mobile small
+$mm: 375 !default; // Mobile medium
+$ml: 500 !default; // Mobile large
+$ts: 600 !default; // Tablet small
+$tm: 768 !default; // Tablet medium
+$tl: 1024 !default; // Tablet large
+$dxs: $tl !default; // Desktop x-small
+$ds: 1280 !default; // Desktop small
+$dm: 1440 !default; // Desktop medium
+$dl: 1600 !default; // Desktop large
+$dxl: 1800 !default; // Desktop x-large
+
+$type-scale-breakpoint: $tm !default;
+
+:root {
+  // pxv unit primitives
+  --site-min: var(--mobile-min);
+  --site-basis: var(--mobile-basis);
+  --site-max: var(--mobile-max);
+
+  // pxv settings - Match figma
+  --mobile-min: 0;
+  --mobile-basis: 375; // Figma mobile
+  --mobile-max: 767;
+  --desktop-min: 768;
+  --desktop-basis: 1440; // Figma desktop
+  --desktop-max: #{$desktop-max}; // Edit this in settings
+
+  // pxv unit
+  @if $enable-pxv {
+    --pxv-unit: clamp(calc(1px * var(--site-min) / var(--site-basis)), calc((100 / var(--site-basis)) * 1vw), calc(1px * var(--site-max) / var(--site-basis)));
+  } @else {
+    --pxv-unit: 1px; // effectively disables fluid scaling
+  }
+
+  // Fluid type primitives
+  --font-max-clamp: 9999px; // no touch
+  --font-size: 16pxv; // fluid-type base font size
+
+  // system font stacks
+  --font-family-system: system-ui, helvetica, arial, sans-serif;
+  --font-family-monospace: ui-monospace, sfmono-regular, menlo, monaco, consolas, 'Liberation Mono', 'Courier New', monospace;
+}

package/scss/00-config/_settings.scss

@@ -0,0 +1,47 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// 📄 _settings.scss
+// Project-level controls and design tokens — the file to edit.
+// Turn these knobs to adjust site behavior, type scales, or theme values.
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+
+// Where should the site stop scaling?
+$desktop-max: 1600;
+
+// Scale everything
+$enable-fluid-type: true !default;
+$enable-pxv: true !default;
+
+// Type scale map
+// Note: these values exist in Figma vars, edit per project. Add any as needed!!
+$type-scale: (
+  heading-xxl: (desktop: 60, mobile: 34),
+  heading-xl:  (desktop: 48, mobile: 30),
+  heading-l:   (desktop: 38, mobile: 26),
+  heading-m:   (desktop: 32, mobile: 22),
+  heading-s:   (desktop: 26, mobile: 20),
+  heading-xs:  (desktop: 20, mobile: 18),
+  heading-xxs: (desktop: 18, mobile: 16),
+  body-l:     (desktop: 18, mobile: 16),
+  body-m:     (desktop: 16, mobile: 14),
+  body-s:     (desktop: 14, mobile: 12),
+  body-xs:    (desktop: 12, mobile: 11),
+  body-xxs:   (desktop: 11, mobile: 10),
+  body-xxxs:  (desktop: 10, mobile: 10)
+);
+
+:root {
+  // defaults
+  --easing: cubic-bezier(0.23, 1, 0.32, 1); // Michael Jordan Magic Johnson
+  --border-radius: 5pxv;
+
+  // default type settings
+  --font-min-clamp: 11px; // default min-size for all type
+  --line-height: 1.5; // default line height
+  --text-wrap: pretty; // default
+  --letter-spacing: normal; // 0.01em etc - match figma
+  --type-margin: 15pxv; // Bottom spacing under type elements todo: replace with spacing var
+
+  // container settings:
+  --container-size: 1280pxv;
+  --mobile-gutters: 5%;
+}

package/scss/01-base/_index.scss

@@ -0,0 +1,5 @@
+/* this is base index */
+@forward 'reset';
+@forward 'typography';
+@forward 'layout';
+@forward 'utilities';