maverick-wave 3.3.0 → 3.3.2

package/.claude/skills/maverick-wave/references/theming.md

@@ -0,0 +1,192 @@
+# Theming, tokens & partial imports
+
+## The model
+
+Twelve colours are configured, everything else is derived from them **at
+runtime** with `color-mix()`. Overriding a root token therefore retunes its
+whole family - hover tone, translucent backgrounds, borders. That is the
+difference to pre-3.4.0, where derived values were baked in at compile time and
+a palette switch meant setting 41 variables.
+
+```css
+/* loaded after maverick-wave.min.css */
+:root {
+  --mw-primary-color: #0f766e; /* also retunes hover, backgrounds, border accent */
+  --mw-secondary-color: #f39c12;
+
+  --mw-success-color: #218838;
+  --mw-warning-color: #d4a310;
+  --mw-danger-color: #c82333;
+  --mw-info-color: #17a2b8;
+
+  --mw-gray-color: #565656;
+
+  --mw-dark-page-background: #0b111a;
+  --mw-dark-text-color: #d6dbdf;
+  --mw-light-page-background: #d2d1e1;
+  --mw-light-text-color: #1a1a1d;
+
+  --mw-form-elements-background: #efefef;
+
+  /* text on every solid coloured surface */
+  --mw-accent-text-color: #ffffff;
+
+  --mw-font-family-base: 'Inter', sans-serif;
+}
+```
+
+## Which token for what
+
+| Token                                                                                                                                                                              | Role                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--mw-primary-color`                                                                                                                                                               | Brand colour: primary buttons, table headers, focus rings, active states                                                                         |
+| `--mw-primary-color-hover`                                                                                                                                                         | Solid hover surface (derived: base + 18% black)                                                                                                  |
+| `--mw-primary-background`                                                                                                                                                          | 20% tint - focus halo, scrollbar tracks                                                                                                          |
+| `--mw-primary-background-hover`                                                                                                                                                    | 50% tint - row and list hover                                                                                                                    |
+| `--mw-primary-info-background`                                                                                                                                                     | 70% tint - alert and info surfaces                                                                                                               |
+| `--mw-border-accent`                                                                                                                                                               | Translucent accent **line**: panel rules, dividers, tab underlines                                                                               |
+| `--mw-secondary-*`                                                                                                                                                                 | Same set for the second brand colour                                                                                                             |
+| `--mw-success/warning/danger/info-color`                                                                                                                                           | Status colours, each with `-color-hover`, `-info-background`, `-info-background-hover`                                                           |
+| `--mw-accent-text-color`                                                                                                                                                           | Text on any solid coloured surface (buttons, table/panel headers, badges, stepper dots)                                                          |
+| `--mw-gray-color`                                                                                                                                                                  | Neutral foreground: muted icons, tooltips                                                                                                        |
+| `--mw-gray-background`                                                                                                                                                             | Subtle neutral surface (20% alpha): zebra rows, disabled fields, tracks, skeletons                                                               |
+| `--mw-overlay-background`                                                                                                                                                          | Heavy scrim (60%) behind modals and blocking spinners                                                                                            |
+| `--mw-page-background`, `--mw-card-background`, `--mw-footer-background`, `--mw-border`, `--mw-shadow`, `--mw-text-color`, `--mw-text-muted-color`, `--mw-hero-overlay-background` | The **active theme** - aliases pointing at the `--mw-dark-*` or `--mw-light-*` set                                                               |
+| `--mw-header-*`                                                                                                                                                                    | Header chrome: `background`, `text-color`, `navbar-list-color`, `navbar-list-active-color`, `burgerbutton-color`, `border` - dark in both themes |
+| `--mw-form-elements-background`, `--mw-form-elements-color`                                                                                                                        | Form controls stay light in both themes and therefore have their own pair                                                                        |
+| `--mw-font-family-base`, `-heading`, `-mono`                                                                                                                                       | Font stacks (default: system stacks - no font is bundled)                                                                                        |
+| `--mw-hero-background`                                                                                                                                                             | Hero image (`url(...)`)                                                                                                                          |
+| `--mw-transition`                                                                                                                                                                  | Global transition (`all 0.3s ease`)                                                                                                              |
+| `--mw-table-scroll-height`                                                                                                                                                         | Per-table height cap for `mw-table-responsive-scroll`                                                                                            |
+| `--mw-internal-theme-mode`                                                                                                                                                         | Read-only: what `$mw-theme-mode` was compiled to                                                                                                 |
+
+Two rules that prevent most colour bugs:
+
+1. **Surfaces are opaque, lines are translucent.** For a coloured surface use
+   `--mw-*-color` / `--mw-*-color-hover`; for a rule or outline use
+   `--mw-border-accent` or `--mw-border`.
+2. **`--mw-text-muted-color` is only for text on theme surfaces** (cards, page
+   background) - it follows the theme. On a colour surface that stays the same
+   in both themes it is always wrong: use `--mw-accent-text-color`, or `opacity`
+   for a disabled look.
+
+## Light & dark
+
+- Dark is the base. Light is applied by putting `mw-theme-light` on `<body>` -
+  that class only re-points the theme aliases at the `--mw-light-*` set.
+- Header, footer chrome and form controls deliberately stay dark/light
+  respectively in both themes.
+- Persisting the choice, the toggle UI and the initial class are the
+  application's job in a SPA (`examples/angular-services.md`). The shipped JS
+  does it for static pages using `localStorage` under the key `mw-theme`.
+
+```ts
+document.body.classList.toggle('mw-theme-light', isLight);
+```
+
+## SCSS configuration
+
+Only `@use ... with (...)` works - a plain assignment before the `@use` has no
+effect, because the root colours are declared with `!default`.
+
+```scss
+@use 'maverick-wave/src/scss/main' with (
+  $mw-theme-mode: 'switchable',
+  // 'switchable' | 'dark' | 'light'
+  $primary-color: #0f766e,
+  $secondary-color: #f39c12,
+  $success-color: #218838,
+  $warning-color: #d4a310,
+  $danger-color: #c82333,
+  $info-color: #17a2b8,
+  $gray-color: #565656,
+  $dark-background: #0b111a,
+  $dark-text-color: #d6dbdf,
+  $light-background: #d2d1e1,
+  $light-text-color: #1a1a1d,
+  $form-elements-background: #efefef,
+  $mw-hero-image: url('/assets/hero.jpg')
+);
+```
+
+`$mw-theme-mode: 'dark'` or `'light'` compiles a single theme - the other set of
+variables is omitted and `mw-theme-light` has no effect. The theme toggle
+component reads `--mw-internal-theme-mode` and disables itself.
+
+Overriding a value that is not on the list above is done in CSS afterwards -
+they are all `var()` references anyway:
+
+```scss
+@use 'maverick-wave/src/scss/main' with (
+  $primary-color: #0f766e
+);
+
+:root {
+  /* break out of the derived scale for one token */
+  --mw-primary-background-hover: color-mix(
+    in srgb,
+    var(--mw-primary-color) 35%,
+    transparent
+  );
+}
+```
+
+## Importing only what you need
+
+The full stylesheet is ~147 kB raw / ~22.5 kB gzipped. Marketing components
+(`blog-post`, `gallery`, `content-slider`, `techstack-bucket`, `tiles`,
+`coming-soon`, `ratings`, `home`, `hero`) are dead weight in an application, and
+Angular bundle budgets notice.
+
+Every layer forwards one module per file, and no `@extend` crosses a file
+boundary, so partial imports are safe. **The one thing you must not drop is
+`base`** - it carries the `:root` tokens; without it every component renders
+colourless.
+
+```scss
+// styles.scss - configure first, then pick
+@use 'maverick-wave/src/scss/abstracts/variables' with (
+  $primary-color: #0f766e
+);
+
+@use 'maverick-wave/src/scss/base'; // :root tokens + reset + typography
+
+@use 'maverick-wave/src/scss/layout/grid';
+@use 'maverick-wave/src/scss/layout/main';
+@use 'maverick-wave/src/scss/layout/page-header';
+@use 'maverick-wave/src/scss/layout/section';
+
+@use 'maverick-wave/src/scss/components/alerts';
+@use 'maverick-wave/src/scss/components/buttons';
+@use 'maverick-wave/src/scss/components/cards';
+@use 'maverick-wave/src/scss/components/empty-state';
+@use 'maverick-wave/src/scss/components/modals';
+@use 'maverick-wave/src/scss/components/panels';
+@use 'maverick-wave/src/scss/components/skeleton';
+@use 'maverick-wave/src/scss/components/spinners';
+@use 'maverick-wave/src/scss/components/tables';
+@use 'maverick-wave/src/scss/components/tags';
+@use 'maverick-wave/src/scss/components/toasts';
+
+@use 'maverick-wave/src/scss/form-elements'; // or single files
+@use 'maverick-wave/src/scss/utilities';
+```
+
+That set compiles to ~98 kB raw / ~15 kB gzipped - a third off the full build.
+
+Details worth knowing:
+
+- **Configuration has to come first.** `abstracts/variables` must be configured
+  before any other module loads it, so the `with (...)` line goes at the top of
+  the file. Configuring `main` instead pulls in everything again.
+- `base` forwards `reset`, `base` and `typography`. If you already have your own
+  reset, `@use '.../base/base'` gives you the `:root` block alone (~9 kB with a
+  component or two).
+- Module names are the file names without the leading underscore:
+  `components/_buttons.scss` becomes `components/buttons`.
+- Layer index files (`components`, `form-elements`, `layout`, `utilities`,
+  `base`) pull in their whole layer - convenient for the small ones
+  (`utilities`, `form-elements`), wasteful for `components`.
+- Some components expect a sibling: `lists` styles checkbox rows and looks best
+  with `form-elements/checkbox`; `tags` uses `mw-btn-mini` from `buttons` for
+  its remove button.

package/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      # Fails on any Sass error, so a broken @use or an unknown function
+      # never reaches a release
+      - name: Build
+        run: npm run build
+
+      # Token and class consistency between the built CSS and the markup
+      - name: Verify
+        run: npm run verify
+
+      - name: Upload build output
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

package/CHANGELOG.md

@@ -6,6 +6,19 @@ Patch releases are only for test purposes - here I only document major and minor
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.0] - 2026-08-04
+
+### Added
+
+- Claude Code skill
+- some new elements
+
+### Changed
+
+- Big update!
+- A few claude code ideas from a few other private projects
+- Small fixes
+
 ## [3.3.0] - 2026-04-12
 
 ### Fixed

package/README.md

@@ -63,48 +63,128 @@ Download `maverick-wave.min.css` and `maverick-wave.min.js` from the [latest rel
 
 ### CSS Custom Properties
 
-Override framework variables in your own stylesheet (load it **after** `maverick-wave.min.css`):
+There are thirteen root color tokens. Everything else — hover tones, translucent
+backgrounds, borders, muted text — is derived from them at runtime with
+`color-mix()`, so overriding a root token is enough. Load your stylesheet
+**after** `maverick-wave.min.css`:
 
 ```css
 :root {
-  --mw-primary-color: #your-brand-color;
-  --mw-secondary-color: #your-secondary-color;
+  /* brand */
+  --mw-primary-color: #e94560;
+  --mw-secondary-color: #f39c12;
+
+  /* status */
+  --mw-success-color: #218838;
+  --mw-warning-color: #d4a310;
+  --mw-danger-color: #c82333;
+  --mw-info-color: #17a2b8;
+
+  /* neutrals and themes */
+  --mw-gray-color: #565656;
   --mw-dark-page-background: #1a1a2e;
-  --mw-dark-card-background: #2a2a4a;
+  --mw-dark-text-color: #d6dbdf;
+  --mw-light-page-background: #f8f9fa;
+  --mw-light-text-color: #1a1a1d;
+  --mw-form-elements-background: #ffffff;
+
+  /* text on solid colored surfaces: buttons, table and panel headers */
+  --mw-accent-text-color: #ffffff;
+
   --mw-font-family-base: 'Your Font Name', sans-serif;
 }
 ```
 
+Setting `--mw-primary-color` alone also retunes `--mw-primary-color-hover`,
+`--mw-primary-background`, `--mw-primary-background-hover`,
+`--mw-primary-info-background` and `--mw-border-accent`. The same holds for
+`--mw-dark-page-background`, which drives the dark card, footer and border
+tones. Each derived token can still be overridden individually if you want to
+break out of the scale.
+
 ### SCSS Source
 
-For full control, clone the repository and integrate `src/scss/main.scss` into your Sass build (Dart Sass required). MaverickWave uses modern `@use`/`@forward` syntax. Set your variable overrides before the `@use` statement:
+For full control, clone the repository and integrate `src/scss/main.scss` into your Sass build (Dart Sass required). MaverickWave uses modern `@use`/`@forward` syntax. Pass your overrides through `with`:
 
 ```scss
 // your styles.scss
 
-// Optional: choose theme mode ('switchable' | 'dark' | 'light')
-$mw-theme-mode: 'switchable';
+@use 'path/to/maverick-wave/src/scss/main' with (
+  // Optional: choose theme mode ('switchable' | 'dark' | 'light')
+  $mw-theme-mode: 'switchable',
+
+  // Override root colors
+  $primary-color: #e94560,
+  $secondary-color: #f39c12,
+  $dark-background: #1f1f2e,
+  $light-background: #f8f9fa
+);
+```
+
+> Plain variable assignments before `@use` have no effect — the framework
+> declares its root colors with `!default`, which only `@use ... with` feeds.
+
+### Importing Only What You Need
 
-// Override base colors
-$primary-color: #e94560;
-$secondary-color: #f39c12;
-$dark-background: #1f1f2e;
-$light-background: #f8f9fa;
+Every layer forwards one module per file and no `@extend` crosses a file
+boundary, so components can be imported individually. Applications typically
+have no use for the marketing components (`blog-post`, `gallery`,
+`content-slider`, `techstack-bucket`, `tiles`, `coming-soon`, `ratings`,
+`home`), and Angular bundle budgets notice the difference.
 
-// Import the framework
-@use 'path/to/maverick-wave/src/scss/main';
+```scss
+// styles.scss — configuration first, then pick
+@use 'maverick-wave/src/scss/abstracts/variables' with (
+  $primary-color: #0f766e
+);
+
+@use 'maverick-wave/src/scss/base'; // required: :root tokens, reset, typography
+
+@use 'maverick-wave/src/scss/layout/grid';
+@use 'maverick-wave/src/scss/layout/page-header';
+@use 'maverick-wave/src/scss/components/buttons';
+@use 'maverick-wave/src/scss/components/cards';
+@use 'maverick-wave/src/scss/components/modals';
+@use 'maverick-wave/src/scss/components/tables';
+@use 'maverick-wave/src/scss/components/tags';
+@use 'maverick-wave/src/scss/form-elements';
+@use 'maverick-wave/src/scss/utilities';
 ```
 
+A typical application subset like the one above compiles to roughly 98 kB raw /
+15 kB gzipped, against 147 kB / 22.5 kB for the full build.
+
+> **`base` is not optional.** It carries the `:root` custom properties — without
+> it every component renders without colors. If you bring your own reset, use
+> `@use 'maverick-wave/src/scss/base/base'` for the token block alone.
+> The `with (...)` configuration has to be the first statement in the file,
+> because every module loads `abstracts/variables` itself.
+
 ### Angular Integration
 
-Copy `maverick-wave.min.css` and `maverick-wave.min.js` into your Angular project (e.g. `src/assets/`) and reference them in `angular.json`:
+Reference the stylesheet in `angular.json` (or import the SCSS source as shown
+above):
 
 ```json
-"styles": ["src/assets/maverick-wave.min.css", "src/styles.scss"],
-"scripts": ["src/assets/maverick-wave.min.js"]
+"styles": ["src/assets/maverick-wave.min.css", "src/styles.scss"]
 ```
 
-MaverickWave automatically styles Angular Reactive Forms state classes (`.ng-invalid.ng-touched`, `.ng-valid.ng-touched.ng-dirty`). Use the `mw-field` wrapper pattern:
+> **Do not add `maverick-wave.min.js` to a SPA.** It wires everything up once on
+> `DOMContentLoaded` and writes straight into the DOM: components rendered later
+> are never initialized, and the theme toggle mutates the DOM behind Angular's
+> change detection. The behaviors it covers (accordion, tabs, modal close, mobile
+> nav, scroll spy, theme toggle, progress bars, sliders, alerts, galleries) are a
+> few lines each in a component — the framework's state classes are the whole
+> contract. Theme switching, for example, is a single class on `<body>`:
+
+```typescript
+// theme.service.ts
+document.body.classList.toggle('mw-theme-light', isLight);
+```
+
+The `mw-field` wrapper groups label, control, hint and error. Bind the error
+state yourself — the framework does not style Angular's `ng-invalid` /
+`ng-touched` classes:
 
 ```html
 <div
@@ -113,13 +193,19 @@ MaverickWave automatically styles Angular Reactive Forms state classes (`.ng-inv
 >
   <label class="mw-field-label mw-required" for="email">Email</label>
   <input id="email" type="email" class="mw-input" formControlName="email" />
-  <span class="mw-field-error" *ngIf="email.invalid && email.touched">
+  @if (email.invalid && email.touched) {
+  <span class="mw-field-error">
     <i class="fas fa-exclamation-circle"></i> Please enter a valid email
     address.
   </span>
+  }
 </div>
 ```
 
+A complete usage guide for AI coding assistants — every component, token,
+integration pattern and example — ships with the package as a Claude Code skill
+in `.claude/skills/maverick-wave/`.
+
 ## Development
 
 ### Prerequisites
@@ -143,9 +229,14 @@ npm run start     # Start Gulp watcher (recompiles on changes)
 npm run showcase  # Serve the built dist/ on http://localhost:8888
 npm run build     # Full clean build → dist/
 npm run format    # Format all source files with Prettier
+npm run verify    # Check dist/ for unused/undefined tokens and unknown classes
 npm run release   # Build non-minified release files to project root
 ```
 
+`npm run verify` runs against `dist/`, so build first. It fails when a token is
+referenced but never defined, when a token is defined but never used, or when
+the showcase or the docs use a `mw-*` class the CSS does not generate.
+
 ## Project Structure
 
 ```
@@ -164,7 +255,10 @@ maverick-wave/
 │       ├── utilities/      # Spacing, flex, display helpers
 │       └── main.scss       # SCSS entry point
 ├── .claude/
-│   └── commands/mw.md      # Claude Code slash command for Angular projects
+│   ├── commands/mw.md      # Claude Code slash command (Angular quick reference)
+│   └── skills/
+│       └── maverick-wave/  # Claude Code skill: full usage guide + examples
+├── scripts/verify.js       # Class and token consistency check (npm run verify)
 ├── .prettierrc.json        # Prettier configuration
 ├── gulpfile.js             # Gulp tasks configuration
 ├── index.html              # Showcase entry point
@@ -177,7 +271,7 @@ Contributions are welcome!
 
 1. Fork the repository.
 2. Create a new branch for your feature or fix.
-3. Make your changes and run `npm run format`.
+3. Make your changes and run `npm run format`, then `npm run build && npm run verify`.
 4. Commit using Conventional Commits (e.g., `feat: add new component`).
 5. Push and open a Pull Request.
 

package/index.html

@@ -67,7 +67,7 @@
         top: -24px;
         right: 13%;
         background: var(--mw-primary-color);
-        color: var(--mw-primary-text-color);
+        color: var(--mw-accent-text-color);
         font-size: 1.1rem;
         padding: 0.3rem 0.7rem;
         border-radius: 0.4rem;
@@ -128,14 +128,14 @@
 
     <main class="mw-main">
       <!-- Home section -->
-      <section id="home">
+      <section id="home" class="mw-section">
         <div class="mw-container">
           @@include('./src/partials/home-container.html')
         </div>
       </section>
 
       <!-- Get started section -->
-      <section id="get-started">
+      <section id="get-started" class="mw-section">
         <div class="mw-container">
           <h2 class="mw-section-title">Get started</h2>
           @@include('./src/partials/get-started-container.html')
@@ -143,7 +143,7 @@
       </section>
 
       <!-- Documentation section -->
-      <section id="documentation" class="mw-section-alternate">
+      <section id="documentation" class="mw-section mw-section-alternate">
         <div class="mw-container">
           <h2 class="mw-section-title">Documentation</h2>
           @@include('./src/partials/documentation-container.html')
@@ -151,7 +151,7 @@
       </section>
 
       <!-- Foundations section -->
-      <section id="foundations">
+      <section id="foundations" class="mw-section">
         <div class="mw-container">
           <h2 class="mw-section-title">Foundations</h2>
           <nav class="mw-section-nav">
@@ -198,7 +198,7 @@
       </section>
 
       <!-- Layout section -->
-      <section id="layout" class="mw-section-alternate">
+      <section id="layout" class="mw-section mw-section-alternate">
         <div class="mw-container">
           <h2 class="mw-section-title">Layout</h2>
           <nav class="mw-section-nav">
@@ -265,7 +265,7 @@
       </section>
 
       <!-- Components section -->
-      <section id="components">
+      <section id="components" class="mw-section">
         <div class="mw-container">
           <h2 class="mw-section-title">Components</h2>
           <nav class="mw-section-nav">
@@ -340,7 +340,7 @@
       </section>
 
       <!-- Forms section -->
-      <section id="forms" class="mw-section-alternate">
+      <section id="forms" class="mw-section mw-section-alternate">
         <div class="mw-container">
           <h2 class="mw-section-title">Forms</h2>
           <nav class="mw-section-nav">
@@ -375,10 +375,11 @@
       </section>
 
       <!-- Data & display section -->
-      <section id="data-display">
+      <section id="data-display" class="mw-section">
         <div class="mw-container">
           <h2 class="mw-section-title">Data & Display</h2>
           <nav class="mw-section-nav">
+            <a href="#page-header" class="mw-section-btn">Page Header</a>
             <a href="#meta-info" class="mw-section-btn">Meta Info</a>
             <a href="#tables" class="mw-section-btn">Tables</a>
             <a href="#pagination" class="mw-section-btn">Pagination</a>
@@ -391,6 +392,11 @@
             <a href="#blog-posts" class="mw-section-btn">Blog Posts</a>
           </nav>
 
+          <!-- Page Header container -->
+          <div id="page-header">
+            @@include('./src/partials/page-header-container.html')
+          </div>
+
           <!-- Meta Info container -->
           <div id="meta-info">
             @@include('./src/partials/meta-info-container.html')