@cobdfamily/clf-core
v7.1.202606142205
Published
Common Look and Feel core: design tokens, theming runtime, COBD custom elements (theme toggle, font-scale toggle, font-scale-paint, <cobd-nav>, <cobd-support>, <cobd-embed>, <cobd-lwe-prompt>, plus the form elements), bundled nav metadata, and shared chro
Readme
@cobdfamily/clf-core
Common Look and Feel toolkit for Bowen Community, BlindHub, and COBD apps. One design-token source feeds every consumer: Ionic apps, WordPress themes, Keycloak login pages, Hugo sites, Moodle themes, CiviCRM Standalone, and Capacitor-wrapped iframe shells.
What ships:
- Tokens for colour / spacing / typography / radii / shadows / motion, in CSS / SCSS / JSON.
- Theming runtime for light / dark / hc-light / hc-dark + a three-step font-size scale.
- Custom elements -- all Light-DOM, all
auto-detect Ionic, all framework-neutral:
<cobd-theme-toggle><cobd-font-scale-toggle><cobd-nav>(renders a COBD nav)<cobd-lwe-prompt>(login-with-email entry: resolves an address to its upstream IdP and continues withkc_idp_hint+login_hint)<cobd-textfield><cobd-textarea><cobd-select><cobd-checkbox><cobd-submit>(form elements, Form-Associated via ElementInternals)
- Nav metadata (the cobd.ca + more-cobd navs
as JSON) + the
getNav()runtime accessor. - Chrome i18n strings the engines + clf-factory build pipeline consume.
For maintainers: see HOW-IT-WORKS.md.
Install
npm install @cobdfamily/clf-coreQuick start
For any consumer that wants CSS variables (works in every build setup, no Sass needed):
@import url("https://cdn.blindhub.ca/clf-core/<version>/tokens.css");Or via the npm package:
import "@cobdfamily/clf-core/tokens.css";Then reference the custom properties anywhere in your styles:
.button {
background: var(--cobd-color-primary);
color: var(--cobd-color-primary-contrast);
}Token exports
The same token set ships in three formats so each consumer picks whatever fits its build:
| Path | What for |
|-------------------------------------|------------------------------------------------|
| @cobdfamily/clf-core/tokens.css | Plain CSS custom properties. Recommended. |
| @cobdfamily/clf-core/tokens.scss | SCSS $cobd-... variables. |
| @cobdfamily/clf-core/tokens.json | Flat JSON map. Useful for native apps + tooling. |
All come from the same src/tokens/*.json files
and stay in lockstep automatically.
WordPress block themes get the same palette via
@cobdfamily/clf-factory's WP engine tarball
(theme.json is generated there from clf-core's
tokens at factory build time).
Theming runtime
Programmatic theme control (light / dark / hc-light / hc-dark / auto) plus the toggle custom element:
import {
getThemes,
getThemePreference,
setTheme,
initTheming,
} from "@cobdfamily/clf-core/theming";
initTheming(); // call once at app boot
setTheme("dark"); // activate from code
// Or drop the toggle anywhere:
import "@cobdfamily/clf-core/components/theme-toggle";<cobd-theme-toggle></cobd-theme-toggle>The runtime writes a data-theme attribute on
<html> (or removes it for auto); the CSS in
tokens.css honours both data-theme and
prefers-color-scheme. No framework dependency.
Text-size scale comes with its own toggle:
import "@cobdfamily/clf-core/components/font-scale-toggle";<cobd-font-scale-toggle aria-label="Text size"></cobd-font-scale-toggle>A small pre-paint helper applies the persisted scale before first paint so consumers don't get a flash of medium-sized text:
<script src="https://cdn.blindhub.ca/clf-core/<ver>/theming/font-scale-paint.js"></script>(Classic blocking script; pair with the toggle's
data-cobd-font-scale cookie.)
Nav metadata + <cobd-nav>
The shared navs (cobd.ca, more-cobd) ship as data, plus a custom element that renders them. Three usage shapes:
// Programmatic access (any framework):
import { getNav } from "@cobdfamily/clf-core/navs";
const nav = getNav("cobd.ca");
// Drop-in element:
import "@cobdfamily/clf-core/components/cobd-nav";<cobd-nav path="cobd.ca" aria-label="Primary"></cobd-nav>path accepts:
- a bundled slug (
"cobd.ca"or"more-cobd") - a full URL (
"https://cobd.ca/wp-json/clf/v/menu") to fetch live - the sentinel
"local"-- the element parses its own<ul>/<li>children as the nav source (useful when the host already renders the nav for SEO / noscript)
Render shape depends on Ionic presence:
<ion-list> of <ion-item>s if Ionic is on the
page, plain <ul> of <li><a>s otherwise.
Each bundled nav is a JSON file under src/navs/.
Schema: @cobdfamily/clf-core/schema/nav.json.
Adding a new bundled nav: drop a JSON file in
src/navs/, rebuild, republish.
Form elements
Five Form-Associated custom elements wrap the
common field types. All accept attribute-only
configuration; all auto-detect Ionic (emit
<ion-input> / <ion-select> / etc. when on
the page, plain HTML when not); all participate
in <form> POST natively via ElementInternals.
<form method="post" action="/save">
<cobd-textfield
name="email" type="email" label="Email"
placeholder="[email protected]"
help="We only use this to contact you."
required></cobd-textfield>
<cobd-textarea
name="bio" label="About you" rows="4">
</cobd-textarea>
<cobd-select name="city" label="City">
<option value="van">Vancouver</option>
<option value="vic">Victoria</option>
</cobd-select>
<cobd-checkbox
name="opt_in" label="Send me updates">
</cobd-checkbox>
<cobd-submit label="Save"></cobd-submit>
</form>// Register all five at once:
import "@cobdfamily/clf-core/components/forms";
// Or tree-shake by importing individually:
import "@cobdfamily/clf-core/components/forms/textfield";
import "@cobdfamily/clf-core/components/forms/select";<cobd-submit> also accepts action and method
attrs -- when set, the element wraps itself in
its own <form>, so the button stands alone
without a surrounding form (useful for "post and
go" actions).
Publishing
Every push to main auto-publishes to npm via the
Publish to npm GitHub Action. The patch version
becomes the build timestamp so consumers can pin to
latest and pick up changes on the next install.
NPM_TOKEN secret on the repo enables it.
Apps using CLF today
- BowenCommunity/Ferry -- Ionic + Angular
- BowenCommunity/Lift -- Ionic + Angular
- BowenCommunity/Springboard -- Ionic + Angular
- cobd.ca -- WordPress (via clf-factory's generated theme.json)
- florin -- Angular (via tokens.css)
To add a new consumer:
npm install @cobdfamily/clf-core, pick the
import line above that matches your stack, done.
For consumers that DON'T want to author HTML
themselves (CMS-driven sites, mobile shells), see
@cobdfamily/clf-factory: it compiles pre-baked
header / footer / error fragments for WordPress,
Hugo, Keycloak, Moodle, CiviCRM Standalone, and
the self-contained mockup.
License
AGPL-3.0. See LICENSE.