@aiaiai-pt/design-system 0.17.1 → 0.19.0

package/components/TextSizeAdjuster.svelte

@@ -0,0 +1,150 @@
+<!--
+  @component TextSizeAdjuster
+
+  Citizen text-size control (#244 C7 accessibility pack). Three buttons —
+  decrease (A−), reset (A), increase (A+) — step the root font scale across four
+  rungs (100–160%), so a citizen can enlarge the rem-based type system without
+  breaking the layout (WCAG 1.4.4 Resize Text). The classic pt-gov
+  "diminuir / normal / aumentar" pattern.
+
+  Presentational: it reports the chosen size via `onchange`; the consumer
+  persists it (cookie) and applies the `:root[data-text-size="N"]` layer
+  (tokens/semantic.css) server-side, so SSR paints it with no flash. Controls
+  disable at the bounds; a polite live region announces the current size for
+  screen-reader users. Labels are props for i18n (default English).
+
+  @example
+  <TextSizeAdjuster size={prefs.textSize} onchange={(n) => setTextSize(n)} />
+-->
+<script>
+  import {
+    DEFAULT_TEXT_SIZE,
+    normalizeTextSize,
+    increaseTextSize,
+    decreaseTextSize,
+    isMinTextSize,
+    isMaxTextSize,
+  } from "./text-size.js";
+
+  let {
+    /** @type {number} Current size step (percent). Off-ladder values normalize. */
+    size = DEFAULT_TEXT_SIZE,
+    /** @type {((size: number) => void) | undefined} */
+    onchange = undefined,
+    /** @type {string} Group label (i18n). */
+    label = "Text size",
+    /** @type {string} Decrease-button accessible label (i18n). */
+    decreaseLabel = "Decrease text size",
+    /** @type {string} Reset-button accessible label (i18n). */
+    resetLabel = "Reset text size",
+    /** @type {string} Increase-button accessible label (i18n). */
+    increaseLabel = "Increase text size",
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const current = $derived(normalizeTextSize(size));
+  const atMin = $derived(isMinTextSize(current));
+  const atMax = $derived(isMaxTextSize(current));
+  const atDefault = $derived(current === DEFAULT_TEXT_SIZE);
+
+  function emit(next) {
+    if (next !== current) onchange?.(next);
+  }
+</script>
+
+<div
+  class="text-size-adjuster {className}"
+  role="group"
+  aria-label={label}
+  data-testid="text-size-adjuster"
+  {...rest}
+>
+  <button
+    type="button"
+    class="ts-btn ts-decrease"
+    aria-label={decreaseLabel}
+    disabled={atMin}
+    onclick={() => emit(decreaseTextSize(current))}
+  >A<span aria-hidden="true">&minus;</span></button>
+  <button
+    type="button"
+    class="ts-btn ts-reset"
+    aria-label={resetLabel}
+    disabled={atDefault}
+    onclick={() => emit(DEFAULT_TEXT_SIZE)}
+  >A</button>
+  <button
+    type="button"
+    class="ts-btn ts-increase"
+    aria-label={increaseLabel}
+    disabled={atMax}
+    onclick={() => emit(increaseTextSize(current))}
+  >A<span aria-hidden="true">+</span></button>
+  <span class="sr-only" aria-live="polite" data-testid="text-size-readout"
+    >{current}%</span
+  >
+</div>
+
+<style>
+  .text-size-adjuster {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2xs);
+  }
+
+  .ts-btn {
+    display: inline-flex;
+    align-items: baseline;
+    justify-content: center;
+    min-width: var(--space-lg);
+    font: inherit;
+    color: var(--color-text-secondary);
+    background: none;
+    border: var(--border-width-thin, 1px) solid var(--color-border);
+    border-radius: var(--radius-md);
+    padding: var(--space-2xs) var(--space-xs);
+    cursor: pointer;
+    line-height: 1;
+  }
+
+  /* The glyph "A" sizes telegraph the control: smaller on decrease, larger on
+     increase, so the affordance reads without relying on the +/− alone. */
+  .ts-decrease {
+    font-size: var(--type-body-sm-size);
+  }
+  .ts-reset {
+    font-size: var(--type-body-size);
+  }
+  .ts-increase {
+    font-size: var(--type-heading-sm-size);
+  }
+
+  .ts-btn:hover:not(:disabled) {
+    color: var(--color-text);
+    background: var(--color-surface-secondary);
+  }
+
+  .ts-btn:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .ts-btn:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+</style>

package/components/TextSizeAdjuster.svelte.d.ts

@@ -0,0 +1,42 @@
+export default TextSizeAdjuster;
+type TextSizeAdjuster = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * TextSizeAdjuster
+ *
+ * Citizen text-size control (#244 C7 accessibility pack). Three buttons —
+ * decrease (A−), reset (A), increase (A+) — step the root font scale across four
+ * rungs (100–160%), so a citizen can enlarge the rem-based type system without
+ * breaking the layout (WCAG 1.4.4 Resize Text). The classic pt-gov
+ * "diminuir / normal / aumentar" pattern.
+ *
+ * Presentational: it reports the chosen size via `onchange`; the consumer
+ * persists it (cookie) and applies the `:root[data-text-size="N"]` layer
+ * (tokens/semantic.css) server-side, so SSR paints it with no flash. Controls
+ * disable at the bounds; a polite live region announces the current size for
+ * screen-reader users. Labels are props for i18n (default English).
+ *
+ * @example
+ * <TextSizeAdjuster size={prefs.textSize} onchange={(n) => setTextSize(n)} />
+ */
+declare const TextSizeAdjuster: import("svelte").Component<{
+    size?: typeof DEFAULT_TEXT_SIZE;
+    onchange?: any;
+    label?: string;
+    decreaseLabel?: string;
+    resetLabel?: string;
+    increaseLabel?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    size?: typeof DEFAULT_TEXT_SIZE;
+    onchange?: any;
+    label?: string;
+    decreaseLabel?: string;
+    resetLabel?: string;
+    increaseLabel?: string;
+    class?: string;
+} & Record<string, any>;
+import { DEFAULT_TEXT_SIZE } from "./text-size.js";

package/components/index.d.ts

@@ -21,6 +21,9 @@ export { default as AppFrame } from "./AppFrame.svelte";
 export { default as SiteHeader } from "./SiteHeader.svelte";
 export { default as SiteFooter } from "./SiteFooter.svelte";
 export { default as SkipLink } from "./SkipLink.svelte";
+export { default as TextSizeAdjuster } from "./TextSizeAdjuster.svelte";
+export { default as ContrastToggle } from "./ContrastToggle.svelte";
+export { default as LinkHighlightToggle } from "./LinkHighlightToggle.svelte";
 export { default as ServiceNavigation } from "./ServiceNavigation.svelte";
 export { default as Link } from "./Link.svelte";
 export { default as Hero } from "./Hero.svelte";
@@ -47,6 +50,7 @@ export { default as Tabs } from "./Tabs.svelte";
 export { default as TabList } from "./TabList.svelte";
 export { default as Tab } from "./Tab.svelte";
 export { default as TabPanel } from "./TabPanel.svelte";
+export { default as FeedView } from "./FeedView.svelte";
 export { default as Alert } from "./Alert.svelte";
 export { default as Toast } from "./Toast.svelte";
 export { default as ToastManager } from "./ToastManager.svelte";

package/components/index.js

@@ -38,6 +38,9 @@ export { default as AppFrame } from "./AppFrame.svelte";
 export { default as SiteHeader } from "./SiteHeader.svelte";
 export { default as SiteFooter } from "./SiteFooter.svelte";
 export { default as SkipLink } from "./SkipLink.svelte";
+export { default as TextSizeAdjuster } from "./TextSizeAdjuster.svelte";
+export { default as ContrastToggle } from "./ContrastToggle.svelte";
+export { default as LinkHighlightToggle } from "./LinkHighlightToggle.svelte";
 export { default as ServiceNavigation } from "./ServiceNavigation.svelte";
 export { default as Link } from "./Link.svelte";
 export { default as Hero } from "./Hero.svelte";
@@ -72,6 +75,7 @@ export { default as Tabs } from "./Tabs.svelte";
 export { default as TabList } from "./TabList.svelte";
 export { default as Tab } from "./Tab.svelte";
 export { default as TabPanel } from "./TabPanel.svelte";
+export { default as FeedView } from "./FeedView.svelte";
 
 // Feedback
 export { default as Alert } from "./Alert.svelte";

package/components/map-utils.d.ts

@@ -73,6 +73,77 @@ export function cssPx(el: Element, prop: string, fallback: number): number;
  * @returns {string[]}
  */
 export function getHeatmapGradient(el: Element): string[];
+/**
+ * @typedef {object} OverlayLayerStyle
+ * Flat style subset applied to a whole overlay layer. Colors are CSS color
+ * strings (they come from layer DATA — geolayers GeoStyler styles — not
+ * from design tokens; absent values fall back to the DS-tokened defaults).
+ * @property {string} [pointColor]
+ * @property {number} [pointRadius]
+ * @property {string} [strokeColor]
+ * @property {number} [strokeWidth]
+ * @property {string} [fillColor]
+ *
+ * @typedef {object} OverlayLayerDef
+ * One ordered overlay rendered between the tile layer and the component's
+ * own interactive vector layer. v1 is GeoJSON-only — the platform's citizen
+ * data plane serves GeoJSON (`/{app}/public/layers/{id}/features`); WMS/tile
+ * overlays arrive with the per-tenant raster principal (spec open question).
+ * @property {string} [id]
+ * @property {'geojson'} [type]
+ * @property {object} [data] — inline GeoJSON (Feature/FeatureCollection)
+ * @property {string} [url] — fetched when `data` is absent
+ * @property {OverlayLayerStyle | object} [style] — flat style or GeoStyler
+ *   JSON (best-effort subset via `geoStylerToFlat`)
+ * @property {boolean} [visible]
+ */
+/**
+ * Best-effort GeoStyler → flat style. Reads the first symbolizer of the
+ * first rule — enough for the platform's single-rule layer styles. Unknown
+ * shapes return {} so the DS-tokened defaults apply.
+ *
+ * @param {any} style
+ * @returns {OverlayLayerStyle}
+ */
+export function geoStylerToFlat(style: any): OverlayLayerStyle;
+/**
+ * Builds OL vector layers for `layers` overlay defs, ordered as given.
+ * URL-sourced layers load asynchronously into their source; a fetch failure
+ * leaves that overlay empty and logs a warning (the map still renders).
+ *
+ * @param {OverlayLayerDef[]} defs
+ * @param {import('./map-utils.js').MapStyles} styles — DS default styles
+ * @returns {Promise<import('ol/layer/Vector.js').default[]>}
+ */
+export function createOverlayLayers(defs: OverlayLayerDef[], styles: import("./map-utils.js").MapStyles): Promise<import("ol/layer/Vector.js").default[]>;
+/**
+ * Normalises a boundary prop into polygon rings (lon/lat WGS84).
+ * Accepts: raw ring `number[][]`, GeoJSON Polygon / MultiPolygon,
+ * Feature, or FeatureCollection (first polygonal feature per entry).
+ *
+ * @param {any} boundary
+ * @returns {number[][][]} — array of outer rings (one per polygon)
+ */
+export function boundaryToRings(boundary: any): number[][][];
+/**
+ * Ray-casting point-in-polygon over WGS84 rings (outer rings only — holes
+ * are out of scope for the boundary gate; the BFF hard-gate is authoritative).
+ *
+ * @param {[number, number]} lonLat
+ * @param {number[][][]} rings — from `boundaryToRings`
+ * @returns {boolean} true when the point is inside ANY ring
+ */
+export function pointInRings(lonLat: [number, number], rings: number[][][]): boolean;
+/**
+ * Builds the boundary overlay layer (dashed outline, faint fill — distinct
+ * from the selection polygon so "the edge of the allowed area" reads as
+ * context, not content). Token-driven: --map-boundary-*.
+ *
+ * @param {number[][][]} rings
+ * @param {Element} el — token read context
+ * @returns {Promise<import('ol/layer/Vector.js').default | null>}
+ */
+export function createBoundaryLayer(rings: number[][][], el: Element): Promise<import("ol/layer/Vector.js").default | null>;
 export type OsmSource = {
     type: "osm";
 };
@@ -98,3 +169,39 @@ export type MapStyles = {
      */
     refresh: () => void;
 };
+/**
+ * Flat style subset applied to a whole overlay layer. Colors are CSS color
+ * strings (they come from layer DATA — geolayers GeoStyler styles — not
+ * from design tokens; absent values fall back to the DS-tokened defaults).
+ */
+export type OverlayLayerStyle = {
+    pointColor?: string;
+    pointRadius?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    fillColor?: string;
+};
+/**
+ * One ordered overlay rendered between the tile layer and the component's
+ * own interactive vector layer. v1 is GeoJSON-only — the platform's citizen
+ * data plane serves GeoJSON (`/{app}/public/layers/{id}/features`); WMS/tile
+ * overlays arrive with the per-tenant raster principal (spec open question).
+ */
+export type OverlayLayerDef = {
+    id?: string;
+    type?: "geojson";
+    /**
+     * — inline GeoJSON (Feature/FeatureCollection)
+     */
+    data?: object;
+    /**
+     * — fetched when `data` is absent
+     */
+    url?: string;
+    /**
+     * — flat style or GeoStyler
+     * JSON (best-effort subset via `geoStylerToFlat`)
+     */
+    style?: OverlayLayerStyle | object;
+    visible?: boolean;
+};

package/components/text-size.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Clamp an arbitrary value to a valid ladder step. The cookie can carry junk or
+ * a numeric string (`"120"`), so coerce + validate; anything off-ladder falls
+ * back to the default. Idempotent.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function normalizeTextSize(value: unknown): number;
+/**
+ * The next step up, clamped at the top rung.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function increaseTextSize(value: unknown): number;
+/**
+ * The next step down, clamped at the bottom rung.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function decreaseTextSize(value: unknown): number;
+/**
+ * Whether the value is at the bottom rung (decrease control should be disabled).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isMinTextSize(value: unknown): boolean;
+/**
+ * Whether the value is at the top rung (increase control should be disabled).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isMaxTextSize(value: unknown): boolean;
+/**
+ * Text-size preference ladder (#244 C7 — DS accessibility pack).
+ *
+ * Four steps spanning 100–160% let a citizen scale the rem-based type system
+ * (WCAG 1.4.4 Resize Text) without breaking the layout. Pure logic: the
+ * `TextSizeAdjuster` component renders the controls, and the consumer persists
+ * the choice (cookie) + applies it as a root font-scale via the
+ * `:root[data-text-size="N"]` layer in tokens/semantic.css. Kept dependency-free
+ * + framework-agnostic so it is unit-testable with `node:test`.
+ */
+/** The valid text-size steps, ascending (percent of the base root font-size). */
+export const TEXT_SIZE_STEPS: number[];
+/**
+ * The default (no preference) — the bottom rung. Derived from the ladder (not a
+ * literal `100`) so its inferred type stays `number`: consumers bind it to a
+ * `number`-typed prop, and a literal type would reject any other rung.
+ */
+export const DEFAULT_TEXT_SIZE: number;

package/components/text-size.js

@@ -0,0 +1,72 @@
+/**
+ * Text-size preference ladder (#244 C7 — DS accessibility pack).
+ *
+ * Four steps spanning 100–160% let a citizen scale the rem-based type system
+ * (WCAG 1.4.4 Resize Text) without breaking the layout. Pure logic: the
+ * `TextSizeAdjuster` component renders the controls, and the consumer persists
+ * the choice (cookie) + applies it as a root font-scale via the
+ * `:root[data-text-size="N"]` layer in tokens/semantic.css. Kept dependency-free
+ * + framework-agnostic so it is unit-testable with `node:test`.
+ */
+
+/** The valid text-size steps, ascending (percent of the base root font-size). */
+export const TEXT_SIZE_STEPS = [100, 120, 140, 160];
+
+/**
+ * The default (no preference) — the bottom rung. Derived from the ladder (not a
+ * literal `100`) so its inferred type stays `number`: consumers bind it to a
+ * `number`-typed prop, and a literal type would reject any other rung.
+ */
+export const DEFAULT_TEXT_SIZE = TEXT_SIZE_STEPS[0];
+
+/**
+ * Clamp an arbitrary value to a valid ladder step. The cookie can carry junk or
+ * a numeric string (`"120"`), so coerce + validate; anything off-ladder falls
+ * back to the default. Idempotent.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function normalizeTextSize(value) {
+  const n = Number(value);
+  return TEXT_SIZE_STEPS.includes(n) ? n : DEFAULT_TEXT_SIZE;
+}
+
+/**
+ * The next step up, clamped at the top rung.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function increaseTextSize(value) {
+  const i = TEXT_SIZE_STEPS.indexOf(normalizeTextSize(value));
+  return TEXT_SIZE_STEPS[Math.min(i + 1, TEXT_SIZE_STEPS.length - 1)];
+}
+
+/**
+ * The next step down, clamped at the bottom rung.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function decreaseTextSize(value) {
+  const i = TEXT_SIZE_STEPS.indexOf(normalizeTextSize(value));
+  return TEXT_SIZE_STEPS[Math.max(i - 1, 0)];
+}
+
+/**
+ * Whether the value is at the bottom rung (decrease control should be disabled).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isMinTextSize(value) {
+  return normalizeTextSize(value) === TEXT_SIZE_STEPS[0];
+}
+
+/**
+ * Whether the value is at the top rung (increase control should be disabled).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isMaxTextSize(value) {
+  return (
+    normalizeTextSize(value) === TEXT_SIZE_STEPS[TEXT_SIZE_STEPS.length - 1]
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -403,6 +403,25 @@
   --tabs-trigger-transition: var(--duration-instant) var(--easing-default);
   --tabs-content-padding-top: var(--space-md);
 
+  /* ═══════════════════════════════════════════════
+     FEEDVIEW (segmented view-switch — list ⇄ map)
+     ═══════════════════════════════════════════════ */
+
+  --feedview-bg: var(--color-surface-secondary);
+  --feedview-radius: var(--radius-md);
+  --feedview-padding: var(--space-2xs);
+  --feedview-tab-font: var(--type-label-font);
+  --feedview-tab-size: var(--type-label-size);
+  --feedview-tab-tracking: var(--type-label-tracking);
+  --feedview-tab-height: 32px;
+  --feedview-tab-padding-x: var(--space-md);
+  --feedview-tab-radius: var(--radius-sm);
+  --feedview-tab-color: var(--color-text-secondary);
+  --feedview-tab-color-active: var(--color-text);
+  --feedview-tab-bg-active: var(--color-surface);
+  --feedview-tab-shadow-active: var(--elevation-raised);
+  --feedview-tab-transition: var(--duration-instant) var(--easing-default);
+
   /* ═══════════════════════════════════════════════
      MODAL (centered overlay)
      ═══════════════════════════════════════════════ */

package/tokens/semantic.css

@@ -255,6 +255,15 @@
   --color-text-secondary: var(--raw-color-neutral-400);
   --color-text-muted: var(--raw-color-neutral-500);
 
+  /* Status colours lifted one ramp step (600 → 400) for dark surfaces. The
+     light -600 values are too dark on the dark (or dark-tinted -subtle) surface
+     a badge/alert sits on — e.g. info blue-600 #2e63a3 was 2.57:1, an AA fail
+     (axe #244 S5). The -400 ramp reads as the status colour AND clears 4.5:1. */
+  --color-destructive: var(--raw-color-red-400);
+  --color-success: var(--raw-color-green-400);
+  --color-warning: var(--raw-color-amber-400);
+  --color-info: var(--raw-color-blue-400);
+
   /* Subtle washes — derived from the LIVE hue (theme-set or default),
      mixed into the dark surface instead of the light-only raw tints. */
   --color-accent-subtle: color-mix(
@@ -284,6 +293,72 @@
   );
 }
 
+/* ═══════════════════════════════════════════════
+   ACCESSIBILITY PREFERENCE LAYERS — #244 C7
+   ═══════════════════════════════════════════════
+
+   Citizen-selectable a11y affordances, each driven by a `data-*` attribute the
+   consumer stamps on <html> server-side (from a cookie, no flash) and toggles
+   live. Independent of scheme/theme — they LAYER on whatever brand + light/dark
+   is active. Placed after the dark block so a tie on specificity resolves here.
+
+   - text-size   → `:root[data-text-size="N"]` scales the root font-size; the
+                   whole rem-based type system grows with it (WCAG 1.4.4).
+   - contrast    → `:root[data-contrast="high"]` re-maps the neutral roles to a
+                   black-on-white (or white-on-black in dark) maximum, kills the
+                   muted greys that fail AA, and strengthens borders (the
+                   "alto contraste" pattern). A second selector handles the dark
+                   pairing; (0,2,0) beats the generic dark layer.
+   - link-mark   → `:root[data-link-highlight="on"] a` underlines every in-content
+                   link so it is distinguishable by more than colour (1.4.1). */
+
+:root[data-text-size="100"] {
+  font-size: 100%;
+}
+:root[data-text-size="120"] {
+  font-size: 120%;
+}
+:root[data-text-size="140"] {
+  font-size: 140%;
+}
+:root[data-text-size="160"] {
+  font-size: 160%;
+}
+
+:root[data-contrast="high"] {
+  --color-text: #000000;
+  --color-text-secondary: #000000;
+  --color-text-muted: #1a1a1a;
+  --color-surface: #ffffff;
+  --color-surface-secondary: #ffffff;
+  --color-surface-tertiary: #ffffff;
+  --color-surface-raised: #ffffff;
+  --color-border: #000000;
+  --color-border-strong: #000000;
+  --focus-ring-color: #000000;
+}
+
+:root[data-contrast="high"][data-scheme="dark"] {
+  --color-text: #ffffff;
+  --color-text-secondary: #ffffff;
+  --color-text-muted: #e6e6e6;
+  --color-surface: #000000;
+  --color-surface-secondary: #000000;
+  --color-surface-tertiary: #000000;
+  --color-surface-raised: #000000;
+  --color-border: #ffffff;
+  --color-border-strong: #ffffff;
+  --focus-ring-color: #ffffff;
+}
+
+/* High contrast implies link distinction — underline links even if the citizen
+   hasn't separately enabled the link-highlight pref. */
+:root[data-contrast="high"] a,
+:root[data-link-highlight="on"] a {
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
 /* ─── Tablet (768px+) ─── */
 @media (min-width: 768px) {
   :root {

package/tokens/themes/valongo.css

@@ -34,7 +34,9 @@
   /* ─── Text ─── */
   --color-text: #1c241b;
   --color-text-secondary: #44513f;
-  --color-text-muted: #71806b;
+  /* Muted hits 4.5:1 even on the secondary/tertiary surfaces it sits on
+     (#f4f6f3 → 5.2:1) — the old #71806b was 3.86:1, an AA fail (axe #244 S5). */
+  --color-text-muted: #5e6b57;
 
   /* ─── Overlay + focus follow the brand ─── */
   --color-overlay: rgba(28, 36, 27, 0.5);
@@ -42,3 +44,28 @@
 
   /* Total overrides: 14 tokens. Still an aiaiai product, in Valongo's colours. */
 }
+
+/*
+ * Dark-scheme brand override (#244 C7 + S5 contrast remediation).
+ *
+ * The generic dark layer (`:root[data-scheme="dark"]` in semantic.css) re-derives
+ * surfaces/text/borders from the neutral ramp but leaves the BRAND accent
+ * untouched, and the light civic green (#2e7d32) is too dark on dark surfaces.
+ *
+ * The accent is DUAL-USE — link text (on a dark surface) AND fill (a button,
+ * with `--color-text-on-accent` text). Those pull opposite ways: link text wants
+ * a LIGHT accent (≥4.5:1 vs the surface), white-on-fill wants a DARK one. So lift
+ * the accent for link contrast (#57bb5d clears 4.5:1 even on the lightest dark
+ * surface, neutral-800) AND flip `--color-text-on-accent` to dark, so fills read
+ * dark-on-light-green (the standard dark-mode resolution). Validated by axe.
+ *
+ * Selector (0,2,0) ties the theme block + beats the generic dark layer (both
+ * (0,1,1)). `auto` is resolved before paint, so this only matches a real
+ * `data-scheme="dark"`. The portal injects the equivalent at runtime; this seeds.
+ */
+[data-theme="valongo"][data-scheme="dark"] {
+  --color-accent: #57bb5d; /* link text ≥4.5:1 on every dark surface (4.78 on n-800) */
+  --color-accent-hover: #81c784;
+  --color-accent-subtle: #15311a;
+  --color-text-on-accent: #14210f; /* dark text on the lighter accent fill */
+}