npm - @nonsuch/component-library - Versions diffs - 0.2.1 → 0.4.0 - Mend

@nonsuch/component-library 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +159 -15
package/dist/nonsuch-components.css +1 -1
package/dist/nonsuch-components.js +330 -11
package/fonts/global.css +2 -2
package/package.json +6 -3
package/src/tokens/tokens.css +236 -0

package/README.md CHANGED Viewed

@@ -12,9 +12,9 @@ pnpm add @nonsuch/component-library
 pnpm add quasar @quasar/extras @quasar/vite-plugin
 ```
-### Vite Configuration
+### Quick Start (Recommended)
-In your `vite.config.ts`, register the Quasar Vite plugin as usual:
+#### Vite Configuration
 ```ts
 import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
@@ -25,25 +25,89 @@ export default defineConfig({
 })
 ```
-### App Entry
-Register Quasar in your Vue app:
+#### App Entry
 ```ts
 import { createApp } from 'vue'
 import { Quasar } from 'quasar'
+import { createNonsuch, createQuasarConfig } from '@nonsuch/component-library'
+import '@nonsuch/component-library/tokens.css'
 import 'quasar/src/css/index.sass'
 const app = createApp(App)
-app.use(Quasar, { plugins: {} })
+app.use(Quasar, createQuasarConfig())  // Token-aligned Quasar brand colours
+app.use(createNonsuch())               // Locale + library setup
+app.mount('#app')
+```
+That's it — components, tokens, locale (defaults to `en-CA`), and Quasar brand colours are all wired up.
+#### Use Components
+```vue
+<script setup>
+import { NsButton, NsInput, NsCard } from '@nonsuch/component-library'
+</script>
+<template>
+  <NsCard title="Welcome">
+    <NsInput v-model="name" label="Your name" />
+    <template #actions>
+      <NsButton label="Submit" />
+    </template>
+  </NsCard>
+</template>
+```
+### Plugin Options
+`createNonsuch()` accepts options for locale:
+```ts
+import { createNonsuch, nsLocaleFrCA } from '@nonsuch/component-library'
+app.use(createNonsuch({ locale: nsLocaleFrCA }))
+```
+`createQuasarConfig()` accepts brand colour overrides and extra Quasar config:
+```ts
+import { createQuasarConfig } from '@nonsuch/component-library'
+app.use(Quasar, createQuasarConfig({
+  brand: { primary: '#1a73e8' },
+  plugins: { Notify: {} },
+}))
 ```
-Then import custom components as needed:
+### Dark Mode
 ```ts
-import { NsButton } from '@nonsuch/component-library'
+import { useNsDarkMode } from '@nonsuch/component-library'
+const { isDark, toggle, useSystem } = useNsDarkMode()
 ```
+The composable persists the user's choice to `localStorage` and syncs with `prefers-color-scheme`. Design tokens switch automatically via the `dark` class on `<html>`.
+### NsThemeProvider
+For section-level locale overrides without a plugin:
+```vue
+<script setup>
+import { NsThemeProvider, nsLocaleFrCA } from '@nonsuch/component-library'
+</script>
+<template>
+  <NsThemeProvider :locale="nsLocaleFrCA">
+    <!-- All Ns components here use French strings -->
+  </NsThemeProvider>
+</template>
+```
+### Manual Setup (Advanced)
 ### Fonts (Optional)
 The library ships [Fixel](https://fixel.macpaw.com/) as the Nonsuch brand font with Roboto as a fallback. Three integration options:
@@ -86,6 +150,77 @@ Or use Quasar components directly — they aren't re-exported through this libra
 import { QInput, QSelect } from 'quasar'
 ```
+### Translations (i18n)
+The library ships its own locale system — **no dependency on vue-i18n**. Components that render user-visible text accept optional string props with built-in defaults from the active locale.
+**Built-in locales:** `en-CA` (default) and `fr-CA`.
+**Option 1: Use the defaults** — components use English (Canada) strings out of the box with no setup:
+```vue
+<NsButton>Add to cart</NsButton>
+<!-- internal labels like loading text already default to English -->
+```
+**Option 2: Switch locale globally** — provide a locale pack at the app root:
+```ts
+import { createApp } from 'vue'
+import { provideNsLocale, nsLocaleFrCA } from '@nonsuch/component-library'
+const app = createApp(App)
+// Inside your root component's setup():
+provideNsLocale(nsLocaleFrCA)
+```
+**Option 3: Custom / partial locale** — supply your own translations by implementing the `NsLocaleMessages` interface:
+```ts
+import type { NsLocaleMessages } from '@nonsuch/component-library'
+import { nsLocaleEnCA, provideNsLocale } from '@nonsuch/component-library'
+const myLocale: NsLocaleMessages = {
+  ...nsLocaleEnCA,
+  product: {
+    ...nsLocaleEnCA.product,
+    addToCart: 'Add to bag', // override just what you need
+  },
+}
+provideNsLocale(myLocale)
+```
+**Option 4: Override per-component** — pass a string prop directly to bypass the locale:
+```vue
+<!-- This label is always "Ajouter" regardless of the active locale -->
+<NsButton label="Ajouter" />
+```
+The locale interface covers four sections: `common`, `product`, `media`, and `validation`. See the full type in `NsLocaleMessages`.
+### Design Tokens (Optional)
+Import CSS custom properties for colours, typography, spacing, border-radius, shadows, and motion:
+```ts
+import '@nonsuch/component-library/tokens.css'
+```
+All tokens use the `--ns-` prefix and support light/dark mode automatically. Current values are placeholders — token names are stable.
+```css
+.my-card {
+  border-radius: var(--ns-radius-md);
+  box-shadow: var(--ns-shadow-sm);
+  padding: var(--ns-space-4);
+}
+```
+Dark mode activates via `class="dark"`, `data-theme="dark"`, Quasar's `.q-dark`, or `prefers-color-scheme: dark`.
 ## Development
 ```bash
@@ -110,13 +245,22 @@ pnpm build:storybook
 ```markdown
 src/
-index.ts # Library entry — exports all custom components
-components/
-NsButton/
-NsButton.vue # Component implementation
-NsButton.stories.ts # Storybook story
-NsButton.test.ts # Vitest unit test
-index.ts # Re-export
+  index.ts             # Library entry — exports all public API
+  plugin.ts            # createNonsuch() Vue plugin
+  quasarConfig.ts      # createQuasarConfig() helper
+  components/
+    NsButton/          # Styled QBtn wrapper
+    NsCard/            # Card with title/subtitle/actions slots
+    NsInput/           # Styled QInput wrapper
+    NsSkeleton/        # Loading skeleton with animation
+    NsThemeProvider/   # Renderless locale provider
+  composables/
+    useNsLocale.ts     # Locale injection/provision
+    useNsDarkMode.ts   # Dark mode with persistence
+    useNsDefaults.ts   # Default value helper
+  locale/              # en-CA, fr-CA string packs
+  tokens/              # Design token CSS + TS helpers
+  fonts/               # Fixel font files + CSS
 ```
 Each custom component lives in its own directory with co-located story and test files. The `Ns` prefix distinguishes library components from Quasar's `Q` prefix.

package/dist/nonsuch-components.css CHANGED Viewed

	@@ -1 +1 @@
1	- .ns-button[data-v-~~e1d8675d~~]{font-family:~~Fixel Text,Roboto,sans~~-~~serif~~;font-weight:~~500~~;letter-spacing~~:.02em~~}
1	+ .ns-button[data-v-7f6c2760]{font-family:var(--ns-font-family-text);font-weight:var(--ns-font-weight-medium);letter-spacing:var(--ns-letter-spacing-wide)}.ns-skeleton[data-v-62627927]{border-radius:var(--ns-radius-md)}.ns-input[data-v-7ebf3284],.ns-input[data-v-7ebf3284] .q-field__label{font-family:var(--ns-font-family-text)}.ns-input[data-v-7ebf3284] .q-field__control{border-radius:var(--ns-radius-md)}.ns-card[data-v-41ecea50]{border-radius:var(--ns-radius-lg);box-shadow:var(--ns-shadow-sm);font-family:var(--ns-font-family-text);transition:box-shadow var(--ns-duration-normal) var(--ns-easing-default)}.ns-card[data-v-41ecea50]:hover{box-shadow:var(--ns-shadow-md)}.ns-card--flat[data-v-41ecea50],.ns-card--flat[data-v-41ecea50]:hover{box-shadow:none}.ns-card__header[data-v-41ecea50]{font-family:var(--ns-font-family-display)}

package/dist/nonsuch-components.js CHANGED Viewed

@@ -1,35 +1,354 @@
-import a from "quasar/src/components/btn/QBtn.js";
-import { defineComponent as d, openBlock as u, createBlock as l, mergeProps as s, withCtx as c, renderSlot as f } from "vue";
-const p = /* @__PURE__ */ d({
+import Q from "quasar/src/components/btn/QBtn.js";
+import { defineComponent as c, openBlock as s, createBlock as d, mergeProps as p, withCtx as u, renderSlot as i, createVNode as B, unref as T, provide as V, inject as q, createSlots as z, renderList as R, normalizeProps as D, guardReactiveProps as M, createElementVNode as O, toDisplayString as w, createElementBlock as F, createCommentVNode as v, computed as _, ref as C, onMounted as x, onUnmounted as j, readonly as I } from "vue";
+import K from "quasar/src/components/spinner/QSpinnerDots.js";
+import U from "quasar/src/components/skeleton/QSkeleton.js";
+import Z from "quasar/src/components/input/QInput.js";
+import $ from "quasar/src/components/card/QCardSection.js";
+import G from "quasar/src/components/card/QCardActions.js";
+import H from "quasar/src/components/card/QCard.js";
+const Y = /* @__PURE__ */ c({
   __name: "NsButton",
   props: {
     color: { default: "primary" },
     size: { default: "md" },
     unelevated: { type: Boolean, default: !0 },
     noCaps: { type: Boolean, default: !0 },
-    rounded: { type: Boolean, default: !0 }
+    rounded: { type: Boolean, default: !0 },
+    loading: { type: Boolean, default: !1 }
   },
   setup(e) {
-    return (t, o) => (u(), l(a, s(t.$attrs, {
+    return (t, o) => (s(), d(Q, p(t.$attrs, {
       color: e.color,
       size: e.size,
       unelevated: e.unelevated,
       "no-caps": e.noCaps,
       rounded: e.rounded,
+      loading: e.loading,
       class: "ns-button"
     }), {
-      default: c(() => [
-        f(t.$slots, "default", {}, void 0, !0)
+      loading: u(() => [
+        i(t.$slots, "loading", {}, () => [
+          B(T(K), { color: "white" })
+        ], !0)
+      ]),
+      default: u(() => [
+        i(t.$slots, "default", {}, void 0, !0)
       ]),
       _: 3
-    }, 16, ["color", "size", "unelevated", "no-caps", "rounded"]));
+    }, 16, ["color", "size", "unelevated", "no-caps", "rounded", "loading"]));
   }
-}), i = (e, t) => {
+}), g = (e, t) => {
   const o = e.__vccOpts || e;
   for (const [n, r] of t)
     o[n] = r;
   return o;
-}, B = /* @__PURE__ */ i(p, [["__scopeId", "data-v-e1d8675d"]]);
+}, me = /* @__PURE__ */ g(Y, [["__scopeId", "data-v-7f6c2760"]]), J = /* @__PURE__ */ c({
+  __name: "NsSkeleton",
+  props: {
+    type: { default: "rect" },
+    animation: { default: "wave" },
+    square: { type: Boolean, default: !1 },
+    bordered: { type: Boolean, default: !1 },
+    width: { default: void 0 },
+    height: { default: void 0 }
+  },
+  setup(e) {
+    return (t, o) => (s(), d(U, p(t.$attrs, {
+      type: e.type,
+      animation: e.animation,
+      square: e.square,
+      bordered: e.bordered,
+      width: e.width,
+      height: e.height,
+      class: "ns-skeleton"
+    }), null, 16, ["type", "animation", "square", "bordered", "width", "height"]));
+  }
+}), pe = /* @__PURE__ */ g(J, [["__scopeId", "data-v-62627927"]]), y = {
+  common: {
+    loading: "Loading…",
+    retry: "Retry",
+    cancel: "Cancel",
+    confirm: "Confirm",
+    save: "Save",
+    delete: "Delete",
+    edit: "Edit",
+    search: "Search",
+    noResults: "No results found",
+    showMore: "Show more",
+    showLess: "Show less"
+  },
+  product: {
+    addToCart: "Add to cart",
+    outOfStock: "Out of stock",
+    inStock: "In stock",
+    quantity: "Quantity",
+    price: "Price",
+    sale: "Sale"
+  },
+  media: {
+    zoomIn: "Zoom in",
+    zoomOut: "Zoom out",
+    fullscreen: "Fullscreen",
+    exitFullscreen: "Exit fullscreen",
+    previousImage: "Previous image",
+    nextImage: "Next image"
+  },
+  validation: {
+    required: "This field is required",
+    invalidEmail: "Please enter a valid email address",
+    tooShort: "Too short",
+    tooLong: "Too long"
+  }
+}, S = /* @__PURE__ */ Symbol("ns-locale");
+function W(e) {
+  V(S, e);
+}
+function X() {
+  return q(S, y);
+}
+const ge = /* @__PURE__ */ c({
+  __name: "NsThemeProvider",
+  props: {
+    locale: { default: () => y }
+  },
+  setup(e) {
+    return W(e.locale), (o, n) => i(o.$slots, "default");
+  }
+}), ee = /* @__PURE__ */ c({
+  __name: "NsInput",
+  props: {
+    label: { default: void 0 },
+    modelValue: { default: void 0 },
+    outlined: { type: Boolean, default: !0 },
+    dense: { type: Boolean, default: !1 },
+    rules: { default: void 0 }
+  },
+  emits: ["update:modelValue"],
+  setup(e) {
+    return (t, o) => (s(), d(Z, p(t.$attrs, {
+      "model-value": e.modelValue,
+      label: e.label,
+      outlined: e.outlined,
+      dense: e.dense,
+      rules: e.rules,
+      class: "ns-input",
+      "onUpdate:modelValue": o[0] || (o[0] = (n) => t.$emit("update:modelValue", n))
+    }), z({ _: 2 }, [
+      R(t.$slots, (n, r) => ({
+        name: r,
+        fn: u((l) => [
+          i(t.$slots, r, D(M(l ?? {})), void 0, !0)
+        ])
+      }))
+    ]), 1040, ["model-value", "label", "outlined", "dense", "rules"]));
+  }
+}), ve = /* @__PURE__ */ g(ee, [["__scopeId", "data-v-7ebf3284"]]), te = { class: "text-h6" }, oe = {
+  key: 0,
+  class: "text-subtitle2 text-grey"
+}, ne = /* @__PURE__ */ c({
+  __name: "NsCard",
+  props: {
+    title: { default: void 0 },
+    subtitle: { default: void 0 },
+    flat: { type: Boolean, default: !1 }
+  },
+  setup(e) {
+    return (t, o) => (s(), d(H, p(t.$attrs, {
+      class: ["ns-card", { "ns-card--flat": e.flat }]
+    }), {
+      default: u(() => [
+        e.title || t.$slots.header ? (s(), d($, {
+          key: 0,
+          class: "ns-card__header"
+        }, {
+          default: u(() => [
+            i(t.$slots, "header", {}, () => [
+              O("div", te, w(e.title), 1),
+              e.subtitle ? (s(), F("div", oe, w(e.subtitle), 1)) : v("", !0)
+            ], !0)
+          ]),
+          _: 3
+        })) : v("", !0),
+        B($, null, {
+          default: u(() => [
+            i(t.$slots, "default", {}, void 0, !0)
+          ]),
+          _: 3
+        }),
+        t.$slots.actions ? (s(), d(G, {
+          key: 1,
+          align: "right"
+        }, {
+          default: u(() => [
+            i(t.$slots, "actions", {}, void 0, !0)
+          ]),
+          _: 3
+        })) : v("", !0)
+      ]),
+      _: 3
+    }, 16, ["class"]));
+  }
+}), he = /* @__PURE__ */ g(ne, [["__scopeId", "data-v-41ecea50"]]);
+function ye(e = {}) {
+  const { locale: t = y } = e;
+  return {
+    install(o) {
+      o.provide(S, t);
+    }
+  };
+}
+const re = {
+  primary: "#3b82f6",
+  // PLACEHOLDER — matches --ns-color-primary
+  secondary: "#8b5cf6",
+  // PLACEHOLDER — matches --ns-color-secondary
+  accent: "#f59e0b",
+  // PLACEHOLDER — matches --ns-color-accent
+  dark: "#1e293b",
+  // PLACEHOLDER — matches --ns-color-neutral-800
+  "dark-page": "#0f172a",
+  // PLACEHOLDER — matches --ns-color-neutral-900
+  positive: "#22c55e",
+  // PLACEHOLDER — matches --ns-color-success
+  negative: "#ef4444",
+  // PLACEHOLDER — matches --ns-color-error
+  info: "#3b82f6",
+  // PLACEHOLDER — matches --ns-color-info
+  warning: "#f59e0b"
+  // PLACEHOLDER — matches --ns-color-warning
+};
+function Se(e = {}) {
+  const { brand: t = {}, plugins: o = {}, ...n } = e;
+  return {
+    config: {
+      brand: {
+        ...re,
+        ...t
+      }
+    },
+    plugins: o,
+    ...n
+  };
+}
+const ke = {
+  common: {
+    loading: "Chargement…",
+    retry: "Réessayer",
+    cancel: "Annuler",
+    confirm: "Confirmer",
+    save: "Enregistrer",
+    delete: "Supprimer",
+    edit: "Modifier",
+    search: "Rechercher",
+    noResults: "Aucun résultat trouvé",
+    showMore: "Afficher plus",
+    showLess: "Afficher moins"
+  },
+  product: {
+    addToCart: "Ajouter au panier",
+    outOfStock: "Rupture de stock",
+    inStock: "En stock",
+    quantity: "Quantité",
+    price: "Prix",
+    sale: "Solde"
+  },
+  media: {
+    zoomIn: "Agrandir",
+    zoomOut: "Réduire",
+    fullscreen: "Plein écran",
+    exitFullscreen: "Quitter le plein écran",
+    previousImage: "Image précédente",
+    nextImage: "Image suivante"
+  },
+  validation: {
+    required: "Ce champ est requis",
+    invalidEmail: "Veuillez entrer une adresse courriel valide",
+    tooShort: "Trop court",
+    tooLong: "Trop long"
+  }
+};
+function be(e, t) {
+  const o = X();
+  return _(() => {
+    const n = e();
+    if (n != null) return n;
+    const r = t.split(".");
+    let l = o;
+    for (const f of r)
+      l = l[f];
+    return l;
+  });
+}
+const h = "ns-dark-mode";
+function Ne() {
+  const e = C(!1), t = C("system");
+  let o = null, n = null;
+  function r(a) {
+    if (e.value = a, typeof document < "u") {
+      const m = document.documentElement;
+      m.classList.toggle("dark", a), m.setAttribute("data-theme", a ? "dark" : "light");
+    }
+  }
+  function l() {
+    return typeof window > "u" ? !1 : window.matchMedia("(prefers-color-scheme: dark)").matches;
+  }
+  function f() {
+    if (typeof localStorage > "u") return null;
+    const a = localStorage.getItem(h);
+    return a === "true" ? !0 : a === "false" ? !1 : null;
+  }
+  function k(a) {
+    typeof localStorage < "u" && localStorage.setItem(h, String(a));
+  }
+  function E() {
+    typeof localStorage < "u" && localStorage.removeItem(h);
+  }
+  function b() {
+    t.value = "user", k(!0), r(!0);
+  }
+  function N() {
+    t.value = "user", k(!1), r(!1);
+  }
+  function L() {
+    e.value ? N() : b();
+  }
+  function A() {
+    E(), t.value = "system", r(l());
+  }
+  function P() {
+    const a = f();
+    a !== null ? (t.value = "storage", r(a)) : (t.value = "system", r(l())), typeof window < "u" && (o = window.matchMedia("(prefers-color-scheme: dark)"), n = (m) => {
+      f() === null && (t.value = "system", r(m.matches));
+    }, o.addEventListener("change", n));
+  }
+  return x(P), j(() => {
+    o && n && o.removeEventListener("change", n);
+  }), {
+    isDark: I(e),
+    source: I(t),
+    enable: b,
+    disable: N,
+    toggle: L,
+    useSystem: A
+  };
+}
+function we(e, t = document.documentElement) {
+  return getComputedStyle(t).getPropertyValue(e).trim();
+}
 export {
-  B as NsButton
+  me as NsButton,
+  he as NsCard,
+  ve as NsInput,
+  S as NsLocaleKey,
+  pe as NsSkeleton,
+  ge as NsThemeProvider,
+  ye as createNonsuch,
+  Se as createQuasarConfig,
+  we as getToken,
+  y as nsLocaleEnCA,
+  ke as nsLocaleFrCA,
+  W as provideNsLocale,
+  Ne as useNsDarkMode,
+  be as useNsDefault,
+  X as useNsLocale
 };

package/fonts/global.css CHANGED Viewed

@@ -14,7 +14,7 @@
 /* Apply Fixel Text as the default body font */
 body {
-  font-family: 'Fixel Text', 'Roboto', sans-serif;
+  font-family: var(--ns-font-family-text, 'Fixel Text', 'Roboto', sans-serif);
 }
 /* Apply Fixel Display to headings */
@@ -30,5 +30,5 @@ h6,
 .text-h4,
 .text-h5,
 .text-h6 {
-  font-family: 'Fixel Display', 'Roboto', sans-serif;
+  font-family: var(--ns-font-family-display, 'Fixel Display', 'Roboto', sans-serif);
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@nonsuch/component-library",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "A Vue 3 component library built on Quasar with opinionated defaults and custom components.",
   "type": "module",
   "sideEffects": false,
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "fonts"
+    "fonts",
+    "src/tokens/tokens.css"
   ],
   "main": "./dist/nonsuch-components.js",
   "module": "./dist/nonsuch-components.js",
@@ -24,7 +25,8 @@
     "./style.css": "./dist/style.css",
     "./fonts.css": "./fonts/fonts.css",
     "./fonts/global.css": "./fonts/global.css",
-    "./fonts/quasar-overrides": "./fonts/_quasar-overrides.sass"
+    "./fonts/quasar-overrides": "./fonts/_quasar-overrides.sass",
+    "./tokens.css": "./src/tokens/tokens.css"
   },
   "scripts": {
     "dev": "storybook dev -p 6006",
@@ -67,6 +69,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-vue": "^10.7.0",
     "happy-dom": "^20.5.3",
+    "postcss-rtlcss": "^5.7.1",
     "prettier": "^3.8.1",
     "quasar": "^2.18.6",
     "sass-embedded": "^1.97.3",

package/src/tokens/tokens.css ADDED Viewed

@@ -0,0 +1,236 @@
+/*
+ * Nonsuch Design Tokens
+ *
+ * CSS custom properties for the Nonsuch component library.
+ * All tokens use the `--ns-` prefix to avoid collisions with
+ * Quasar's `--q-` namespace and app-level variables.
+ *
+ * Import in your app:
+ *   import '@nonsuch/component-library/tokens.css'
+ *
+ * Current values are PLACEHOLDERS — they will be updated
+ * when brand designs are finalised. Token *names* are stable.
+ */
+/* --------------------------------------------------------
+ * LIGHT MODE (default)
+ * ------------------------------------------------------ */
+:root {
+  /* — Brand colours — */
+  --ns-color-primary: #3b82f6; /* PLACEHOLDER */
+  --ns-color-primary-hover: #2563eb; /* PLACEHOLDER */
+  --ns-color-secondary: #8b5cf6; /* PLACEHOLDER */
+  --ns-color-secondary-hover: #7c3aed; /* PLACEHOLDER */
+  --ns-color-accent: #f59e0b; /* PLACEHOLDER */
+  --ns-color-accent-hover: #d97706; /* PLACEHOLDER */
+  /* — Semantic colours — */
+  --ns-color-success: #22c55e; /* PLACEHOLDER */
+  --ns-color-warning: #f59e0b; /* PLACEHOLDER */
+  --ns-color-error: #ef4444; /* PLACEHOLDER */
+  --ns-color-info: #3b82f6; /* PLACEHOLDER */
+  /* — Surface / background — */
+  --ns-color-background: #ffffff; /* PLACEHOLDER */
+  --ns-color-surface: #ffffff; /* PLACEHOLDER */
+  --ns-color-surface-variant: #f8fafc; /* PLACEHOLDER */
+  /* — On-colours (text/icons on top of the corresponding colour) — */
+  --ns-color-on-primary: #ffffff; /* PLACEHOLDER */
+  --ns-color-on-secondary: #ffffff; /* PLACEHOLDER */
+  --ns-color-on-accent: #000000; /* PLACEHOLDER */
+  --ns-color-on-background: #0f172a; /* PLACEHOLDER */
+  --ns-color-on-surface: #0f172a; /* PLACEHOLDER */
+  /* — Neutral scale — */
+  --ns-color-neutral-50: #f8fafc; /* PLACEHOLDER */
+  --ns-color-neutral-100: #f1f5f9; /* PLACEHOLDER */
+  --ns-color-neutral-200: #e2e8f0; /* PLACEHOLDER */
+  --ns-color-neutral-300: #cbd5e1; /* PLACEHOLDER */
+  --ns-color-neutral-400: #94a3b8; /* PLACEHOLDER */
+  --ns-color-neutral-500: #64748b; /* PLACEHOLDER */
+  --ns-color-neutral-600: #475569; /* PLACEHOLDER */
+  --ns-color-neutral-700: #334155; /* PLACEHOLDER */
+  --ns-color-neutral-800: #1e293b; /* PLACEHOLDER */
+  --ns-color-neutral-900: #0f172a; /* PLACEHOLDER */
+  /* — Typography — */
+  --ns-font-family-text: 'Fixel Text', 'Roboto', sans-serif; /* PLACEHOLDER */
+  --ns-font-family-display: 'Fixel Display', 'Roboto', sans-serif; /* PLACEHOLDER */
+  --ns-font-size-xs: 0.75rem; /* 12px — PLACEHOLDER */
+  --ns-font-size-sm: 0.875rem; /* 14px — PLACEHOLDER */
+  --ns-font-size-md: 1rem; /* 16px — PLACEHOLDER */
+  --ns-font-size-lg: 1.125rem; /* 18px — PLACEHOLDER */
+  --ns-font-size-xl: 1.25rem; /* 20px — PLACEHOLDER */
+  --ns-font-size-2xl: 1.5rem; /* 24px — PLACEHOLDER */
+  --ns-font-size-3xl: 1.875rem; /* 30px — PLACEHOLDER */
+  --ns-font-weight-regular: 400; /* PLACEHOLDER */
+  --ns-font-weight-medium: 500; /* PLACEHOLDER */
+  --ns-font-weight-semibold: 600; /* PLACEHOLDER */
+  --ns-font-weight-bold: 700; /* PLACEHOLDER */
+  --ns-line-height-tight: 1.25; /* PLACEHOLDER */
+  --ns-line-height-normal: 1.5; /* PLACEHOLDER */
+  --ns-line-height-relaxed: 1.75; /* PLACEHOLDER */
+  --ns-letter-spacing-tight: -0.01em; /* PLACEHOLDER */
+  --ns-letter-spacing-normal: 0; /* PLACEHOLDER */
+  --ns-letter-spacing-wide: 0.02em; /* PLACEHOLDER */
+  /* — Spacing (4px grid) — */
+  --ns-space-1: 0.25rem; /* 4px */
+  --ns-space-2: 0.5rem; /* 8px */
+  --ns-space-3: 0.75rem; /* 12px */
+  --ns-space-4: 1rem; /* 16px */
+  --ns-space-5: 1.25rem; /* 20px */
+  --ns-space-6: 1.5rem; /* 24px */
+  --ns-space-8: 2rem; /* 32px */
+  --ns-space-10: 2.5rem; /* 40px */
+  --ns-space-12: 3rem; /* 48px */
+  --ns-space-16: 4rem; /* 64px */
+  /* — Border radius — */
+  --ns-radius-none: 0;
+  --ns-radius-sm: 0.25rem; /* 4px — PLACEHOLDER */
+  --ns-radius-md: 0.5rem; /* 8px — PLACEHOLDER */
+  --ns-radius-lg: 0.75rem; /* 12px — PLACEHOLDER */
+  --ns-radius-xl: 1rem; /* 16px — PLACEHOLDER */
+  --ns-radius-full: 9999px;
+  /* — Shadows / elevation — */
+  --ns-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); /* PLACEHOLDER */
+  --ns-shadow-md:
+    0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); /* PLACEHOLDER */
+  --ns-shadow-lg:
+    0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1); /* PLACEHOLDER */
+  --ns-shadow-xl:
+    0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1); /* PLACEHOLDER */
+  /* — Motion / transitions — */
+  --ns-duration-fast: 100ms; /* PLACEHOLDER */
+  --ns-duration-normal: 200ms; /* PLACEHOLDER */
+  --ns-duration-slow: 400ms; /* PLACEHOLDER */
+  --ns-easing-default: cubic-bezier(0.4, 0, 0.2, 1); /* PLACEHOLDER */
+  --ns-easing-in: cubic-bezier(0.4, 0, 1, 1); /* PLACEHOLDER */
+  --ns-easing-out: cubic-bezier(0, 0, 0.2, 1); /* PLACEHOLDER */
+  --ns-easing-in-out: cubic-bezier(0.4, 0, 0.2, 1); /* PLACEHOLDER */
+}
+/* --------------------------------------------------------
+ * DARK MODE
+ *
+ * Activated by any of:
+ *   <html class="dark">
+ *   <html data-theme="dark">
+ *   OS-level prefers-color-scheme: dark
+ *
+ * Only colour tokens change — typography, spacing, radius,
+ * and motion are shared between modes.
+ * ------------------------------------------------------ */
+:root.dark,
+[data-theme='dark'],
+.q-dark {
+  /* — Brand colours (dark) — */
+  --ns-color-primary: #60a5fa; /* PLACEHOLDER */
+  --ns-color-primary-hover: #93c5fd; /* PLACEHOLDER */
+  --ns-color-secondary: #a78bfa; /* PLACEHOLDER */
+  --ns-color-secondary-hover: #c4b5fd; /* PLACEHOLDER */
+  --ns-color-accent: #fbbf24; /* PLACEHOLDER */
+  --ns-color-accent-hover: #fcd34d; /* PLACEHOLDER */
+  /* — Semantic colours (dark) — */
+  --ns-color-success: #4ade80; /* PLACEHOLDER */
+  --ns-color-warning: #fbbf24; /* PLACEHOLDER */
+  --ns-color-error: #f87171; /* PLACEHOLDER */
+  --ns-color-info: #60a5fa; /* PLACEHOLDER */
+  /* — Surface / background (dark) — */
+  --ns-color-background: #0f172a; /* PLACEHOLDER */
+  --ns-color-surface: #1e293b; /* PLACEHOLDER */
+  --ns-color-surface-variant: #334155; /* PLACEHOLDER */
+  /* — On-colours (dark) — */
+  --ns-color-on-primary: #0f172a; /* PLACEHOLDER */
+  --ns-color-on-secondary: #0f172a; /* PLACEHOLDER */
+  --ns-color-on-accent: #0f172a; /* PLACEHOLDER */
+  --ns-color-on-background: #f1f5f9; /* PLACEHOLDER */
+  --ns-color-on-surface: #f1f5f9; /* PLACEHOLDER */
+  /* — Neutral scale (dark — inverted) — */
+  --ns-color-neutral-50: #0f172a; /* PLACEHOLDER */
+  --ns-color-neutral-100: #1e293b; /* PLACEHOLDER */
+  --ns-color-neutral-200: #334155; /* PLACEHOLDER */
+  --ns-color-neutral-300: #475569; /* PLACEHOLDER */
+  --ns-color-neutral-400: #64748b; /* PLACEHOLDER */
+  --ns-color-neutral-500: #94a3b8; /* PLACEHOLDER */
+  --ns-color-neutral-600: #cbd5e1; /* PLACEHOLDER */
+  --ns-color-neutral-700: #e2e8f0; /* PLACEHOLDER */
+  --ns-color-neutral-800: #f1f5f9; /* PLACEHOLDER */
+  --ns-color-neutral-900: #f8fafc; /* PLACEHOLDER */
+  /* — Shadows (dark — lighter opacity looks better on dark bg) — */
+  --ns-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3); /* PLACEHOLDER */
+  --ns-shadow-md:
+    0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.3); /* PLACEHOLDER */
+  --ns-shadow-lg:
+    0 10px 15px -3px rgb(0 0 0 / 0.4), 0 4px 6px -4px rgb(0 0 0 / 0.3); /* PLACEHOLDER */
+  --ns-shadow-xl:
+    0 20px 25px -5px rgb(0 0 0 / 0.4), 0 8px 10px -6px rgb(0 0 0 / 0.3); /* PLACEHOLDER */
+}
+/* --------------------------------------------------------
+ * prefers-color-scheme fallback
+ *
+ * Applies dark tokens when the OS is in dark mode and
+ * no explicit class/attribute override is set.
+ * ------------------------------------------------------ */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']):not(.light) {
+    /* — Brand colours (dark) — */
+    --ns-color-primary: #60a5fa;
+    --ns-color-primary-hover: #93c5fd;
+    --ns-color-secondary: #a78bfa;
+    --ns-color-secondary-hover: #c4b5fd;
+    --ns-color-accent: #fbbf24;
+    --ns-color-accent-hover: #fcd34d;
+    /* — Semantic colours (dark) — */
+    --ns-color-success: #4ade80;
+    --ns-color-warning: #fbbf24;
+    --ns-color-error: #f87171;
+    --ns-color-info: #60a5fa;
+    /* — Surface / background (dark) — */
+    --ns-color-background: #0f172a;
+    --ns-color-surface: #1e293b;
+    --ns-color-surface-variant: #334155;
+    /* — On-colours (dark) — */
+    --ns-color-on-primary: #0f172a;
+    --ns-color-on-secondary: #0f172a;
+    --ns-color-on-accent: #0f172a;
+    --ns-color-on-background: #f1f5f9;
+    --ns-color-on-surface: #f1f5f9;
+    /* — Neutral scale (dark — inverted) — */
+    --ns-color-neutral-50: #0f172a;
+    --ns-color-neutral-100: #1e293b;
+    --ns-color-neutral-200: #334155;
+    --ns-color-neutral-300: #475569;
+    --ns-color-neutral-400: #64748b;
+    --ns-color-neutral-500: #94a3b8;
+    --ns-color-neutral-600: #cbd5e1;
+    --ns-color-neutral-700: #e2e8f0;
+    --ns-color-neutral-800: #f1f5f9;
+    --ns-color-neutral-900: #f8fafc;
+    /* — Shadows (dark) — */
+    --ns-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3);
+    --ns-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.3);
+    --ns-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.4), 0 4px 6px -4px rgb(0 0 0 / 0.3);
+    --ns-shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.4), 0 8px 10px -6px rgb(0 0 0 / 0.3);
+  }
+}