`, which itself fades in once the page scripts have run) and every `.ak-reveal` element fades up when it scrolls into view. The hidden state only applies under `html.js-reveal`, set by `js/head.js`; nothing else is needed on a new page. +- Tokens: `$transition-duration-fast|base|slow` and `$transition-easing-standard|emphasized` in `src/scss/1-variables/_app.scss`, used as `var(--ak-duration-*)` and `var(--ak-ease-*)`. Write transitions with Bootstrap's `@include transition(...)` so reduced motion turns them off; an animation must not move anything under `prefers-reduced-motion: reduce` (a fade is fine). +- Reveal (`js/modules/reveal.js`, `3-components/_reveal.scss`): every top-level `.card` inside `.reveal-cards` (the layouts put it on `

`, which itself fades in once the page scripts have run) and every `.reveal` element fades up when it scrolls into view. The hidden state only applies under `html.js-reveal`, set by `js/head.js`; nothing else is needed on a new page. - Count-up (`js/modules/count-up.js`): `data-count-up` on an element that holds only a number (with any prefix, suffix, `,` separators and decimals) and sits on its own line. The text stays the final value for screen readers and reduced motion. - Skeletons (`js/modules/skeleton.js`, `3-components/_skeleton.scss`): for content JavaScript draws, put `aria-busy="true"` on the card body and `{{> skeleton }}` inside a `position-relative` element that has the content's final height (a `.chart` or a `min-height`). `adminkit.chartjs()` and `adminkit.vectorMap()` clear it; for anything else call `adminkit.ready(element)`. All of them fire `adminkit:ready`. - Clickable cards: `a.card` or a card with a `.stretched-link` lifts on hover and focus; nothing to add. @@ -75,11 +75,12 @@ Free Bootstrap 5 admin template, published to npm as `@adminkit/core`. - Target: WCAG 2.2 AA in light and dark mode, on every page including the sidebar and navbar: 4.5:1 for text, 3:1 for large text, icons and controls, no serious or critical axe violations. - Check with `@axe-core/playwright` on the built pages in both modes. -- A new color that text or a control is drawn in must pass: use `ak-readable($color, $background)` (`src/scss/1-variables/_functions.scss`) and `$theme-text-colors` / `$theme-text-colors-dark` for theme colors as text; fills with white text must reach 4.5:1 (`ak-text-on()` picks white or dark text). +- A new color that text or a control is drawn in must pass: use `readable($color, $background)` (`src/scss/1-variables/_functions.scss`) and `$theme-text-colors` / `$theme-text-colors-dark` for theme colors as text; fills with white text must reach 4.5:1 (`text-on()` picks white or dark text). - Icon-only links and buttons get an `aria-label`; links that act as buttons get `role="button"`; card titles are `h2.card-title` under the page's `h1`. ## Conventions +- Only CSS custom properties get a prefix: `--ak-*`, like Bootstrap's `--bs-*`. Classes, Sass variables, functions and mixins never do. - Commits follow Conventional Commits; see `CONTRIBUTING.md` for types, scopes and examples. lefthook enforces them. - A PR that changes behaviour adds a line under `Unreleased` in `CHANGELOG.md`. Add it, or ask before opening the PR. - Changelog lines are short, imperative and user-facing, like the released entries: "Add pricing page (/pages-pricing.html)", "Replace Feather icons with Lucide", "Upgrade to Chart.js v4", "Upgrade dependencies". One line per change a template user would notice. No internal tooling (lint, CI, hooks, scripts), no explanations, no implementation details. Notable dependency majors get "Upgrade to X vN"; everything else is "Upgrade dependencies". diff --git a/CHANGELOG.md b/CHANGELOG.md index 8db60b3..337cbb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +- Drop the `ak-` prefix from classes, Sass variables and functions (`.ak-reveal` → `.reveal`); the old names work until v5 - Upgrade dependencies ## [4.0.0] - 2026-10-28 diff --git a/src/js/modules/reveal.js b/src/js/modules/reveal.js index f9cdd05..94aabef 100644 --- a/src/js/modules/reveal.js +++ b/src/js/modules/reveal.js @@ -1,12 +1,14 @@ -// Cards fade up as they scroll into view: every top-level .card inside .ak-reveal-cards (the +// Cards fade up as they scroll into view: every top-level .card inside .reveal-cards (the // layouts put it on

, which itself fades in once the page scripts have run) and any -// element with .ak-reveal. Elements that come into view together are staggered through +// element with .reveal. Elements that come into view together are staggered through // --ak-reveal-index, capped at maxStagger steps. The hidden state is CSS under // html.js-reveal, which js/head.js sets; without JavaScript nothing is hidden. Styles: -// scss/3-components/_reveal.scss. +// scss/3-components/_reveal.scss. .ak-reveal and .ak-reveal-cards are v4 aliases, remove +// them in v5. import { mount } from "./mount"; -const selector = ".ak-reveal, .ak-reveal-cards .card:not(.card .card)"; +const cards = ".reveal-cards, .ak-reveal-cards"; +const selector = `.reveal, .ak-reveal, :is(${cards}) .card:not(.card .card)`; const maxStagger = 8; const reveal = (elements) => { @@ -14,14 +16,14 @@ const reveal = (elements) => { const onTransitionEnd = (event) => { if (event.target === element && event.propertyName === "opacity") { element.removeEventListener("transitionend", onTransitionEnd); - element.classList.remove("ak-revealing"); + element.classList.remove("revealing"); element.style.removeProperty("--ak-reveal-index"); } }; element.addEventListener("transitionend", onTransitionEnd); element.style.setProperty("--ak-reveal-index", Math.min(index, maxStagger)); - element.classList.add("ak-revealed", "ak-revealing"); + element.classList.add("revealed", "revealing"); }); }; @@ -42,6 +44,6 @@ root.classList.add("js-reveal-ready"); // mount() starts after the page scripts that build charts and tables on DOMContentLoaded, so // their layout is in place before the cards become visible if (root.classList.contains("js-reveal")) { - mount(".ak-reveal-cards", (element) => element.classList.add("ak-revealed")); + mount(cards, (element) => element.classList.add("revealed")); mount(selector, (element) => observer.observe(element)); } diff --git a/src/js/modules/skeleton.js b/src/js/modules/skeleton.js index 5561941..a335c27 100644 --- a/src/js/modules/skeleton.js +++ b/src/js/modules/skeleton.js @@ -1,14 +1,14 @@ // Loading placeholders for content that JavaScript draws (charts, maps, tables). The markup -// shows an .ak-skeleton inside an element marked aria-busy="true"; markReady(element) +// shows a .skeleton inside an element marked aria-busy="true"; markReady(element) // removes the placeholders around element, sets aria-busy="false" and fires // adminkit:ready on element. The chart, map and table helpers call it when they have // drawn; call adminkit.ready(element) for your own content. Styles: -// scss/3-components/_skeleton.scss. +// scss/3-components/_skeleton.scss. .ak-skeleton is a v4 alias, remove it in v5. export const markReady = (element) => { const busy = element.closest('[aria-busy="true"]'); if (busy) { - busy.querySelectorAll(".ak-skeleton").forEach((skeleton) => { + busy.querySelectorAll(".skeleton, .ak-skeleton").forEach((skeleton) => { skeleton.remove(); }); busy.setAttribute("aria-busy", "false"); diff --git a/src/layouts/auth.hbs b/src/layouts/auth.hbs index 72c8d8d..79e3eda 100644 --- a/src/layouts/auth.hbs +++ b/src/layouts/auth.hbs @@ -4,7 +4,7 @@ {{> site-meta }} -

diff --git a/src/layouts/default.hbs b/src/layouts/default.hbs index 5184ebb..1218065 100644 --- a/src/layouts/default.hbs +++ b/src/layouts/default.hbs @@ -10,7 +10,7 @@

{{> site-navbar }} -

diff --git a/src/partials/site-footer.hbs b/src/partials/site-footer.hbs index 85cdb2d..0fb766e 100644 --- a/src/partials/site-footer.hbs +++ b/src/partials/site-footer.hbs @@ -1,4 +1,4 @@ -