@aiaiai-pt/design-system 0.17.0 → 0.18.0

package/components/ActionFormRenderer.svelte

@@ -73,6 +73,18 @@
      *  in submit modes. */
     captcha?: Snippet;
     submitLabel?: string;
+    /** Forwarded VERBATIM to every `geo` parameter's MapPicker (the renderer
+     *  stays generic — boundary/overlay semantics live in the consumer):
+     *  `boundary` draws the dashed tenant-boundary overlay and arms the
+     *  out-of-bounds check; `layers` are ordered GeoJSON overlays (unbounded);
+     *  `onoutofbounds(outside, coords)` fires on every point placement when a
+     *  boundary is set — NON-blocking, the consumer owns surfacing/gating. */
+    boundary?: unknown;
+    layers?: unknown[];
+    onoutofbounds?: (outside: boolean, coords: [number, number]) => void;
+    /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
+     *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
+    geoError?: string;
   }
 
   let {
@@ -86,6 +98,10 @@
     uploadFile = undefined,
     captcha = undefined,
     submitLabel = "Submit",
+    boundary = undefined,
+    layers = [],
+    onoutofbounds = undefined,
+    geoError = undefined,
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
@@ -381,6 +397,11 @@
   {@const parameter = rawParameter as Entity}
   {@const key = parameterKey(parameter)}
   {@const type = parameterType(parameter)}
+  <!-- A11y (#244 C7 / Selo item 4): required fields are marked
+       `aria-required` on the control itself, so a screen reader announces
+       "required" on the field — not just the disconnected visual hint below.
+       Passed through the DS field components' `{...rest}` onto the input. -->
+  {@const ariaRequired = parameter.required ? "true" : undefined}
   {#if type === "enum" || type === "select" || enumOptions(parameter).length}
     <Select
       label={String(parameter.label ?? key)}
@@ -389,6 +410,7 @@
       options={enumOptions(parameter)}
       placeholder="Select value"
       onchange={(value: string) => setValue(key, value)}
+      aria-required={ariaRequired}
     />
   {:else if type === "number" || type === "integer"}
     <Input
@@ -400,6 +422,7 @@
         const value = (event.target as HTMLInputElement).value;
         setValue(key, value === "" ? "" : Number(value));
       }}
+      aria-required={ariaRequired}
     />
   {:else if type === "bool" || type === "boolean"}
     <Select
@@ -411,12 +434,20 @@
         { value: "false", label: "No" },
       ]}
       onchange={(value: string) => setValue(key, value === "true")}
+      aria-required={ariaRequired}
     />
   {:else if type === "file"}
     <!-- `file` parameter (#75 M5 slice 4b): upload-as-you-attach. The keys
          ride payload.attachment_keys; raw_values never sees this param. -->
-    <div class="afr-file-param">
-      <span class="afr-file-label">{String(parameter.label ?? key)}</span>
+    <!-- A11y: the file param is a labelled group (the FileUpload's own input
+         can't take a `for`/label from here), so SR users get the field name +
+         required state when they enter it. -->
+    <div class="afr-file-param" role="group" aria-labelledby={`${key}-file-label`}>
+      <span id={`${key}-file-label`} class="afr-file-label"
+        >{String(parameter.label ?? key)}{parameter.required
+          ? " (required)"
+          : ""}</span
+      >
       {#each fileUploads[key] ?? [] as f (f.key)}
         <FileUploadItem
           name={f.name}
@@ -451,6 +482,10 @@
     <MapPicker
       mode="point"
       height="20rem"
+      {boundary}
+      {layers}
+      {onoutofbounds}
+      error={geoError}
       label={String(parameter.label ?? key)}
       center={Array.isArray(parameter.default_value)
         ? (parameter.default_value as [number, number])
@@ -471,6 +506,7 @@
       name={key}
       value={String(values[key] ?? "")}
       oninput={(event: Event) => setValue(key, (event.target as HTMLInputElement).value)}
+      aria-required={ariaRequired}
     />
   {/if}
   {#if mode === "public-submit"}
@@ -506,7 +542,14 @@
     <p class="muted">This action has no fields yet.</p>
   {:else}
     {@const Layout = resolvedLayout.component}
-    <form class="rendered-form">
+    <!-- A11y: name the form region so SR users land on a labelled form, not an
+         anonymous group of inputs (Selo item 4 / WCAG 1.3.1). -->
+    <form
+      class="rendered-form"
+      aria-label={String(
+        renderedAction?.label ?? renderedAction?.key ?? "Form",
+      )}
+    >
       <Layout {sections} field={fieldRow} />
     </form>
   {/if}
@@ -524,6 +567,15 @@
         {#if captcha}
           <div class="submit-captcha">{@render captcha()}</div>
         {/if}
+        <!-- A11y: a disabled submit gives no reason on its own. This polite
+             status spells out the gate (and disappears when satisfied), so SR
+             users know WHY they can't submit yet — paired with the per-field
+             `aria-required` that marks which fields are needed. -->
+        {#if !canSubmit && !submitting}
+          <p class="submit-hint" role="status">
+            Fill in all required fields to submit.
+          </p>
+        {/if}
         <Button
           variant="primary"
           loading={submitting}
@@ -622,6 +674,12 @@
     color: var(--color-text-muted);
   }
 
+  .submit-hint {
+    color: var(--color-text-secondary);
+    font-size: var(--type-body-sm-size);
+    margin: 0;
+  }
+
   .rendered-form,
   .admin-preview,
   .preview-block,

package/components/ActionFormRenderer.svelte.d.ts

@@ -58,6 +58,18 @@ interface Props {
      *  in submit modes. */
     captcha?: Snippet;
     submitLabel?: string;
+    /** Forwarded VERBATIM to every `geo` parameter's MapPicker (the renderer
+     *  stays generic — boundary/overlay semantics live in the consumer):
+     *  `boundary` draws the dashed tenant-boundary overlay and arms the
+     *  out-of-bounds check; `layers` are ordered GeoJSON overlays (unbounded);
+     *  `onoutofbounds(outside, coords)` fires on every point placement when a
+     *  boundary is set — NON-blocking, the consumer owns surfacing/gating. */
+    boundary?: unknown;
+    layers?: unknown[];
+    onoutofbounds?: (outside: boolean, coords: [number, number]) => void;
+    /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
+     *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
+    geoError?: string;
 }
 declare const ActionFormRenderer: import("svelte").Component<Props, {}, "">;
 type ActionFormRenderer = ReturnType<typeof ActionFormRenderer>;

package/components/ContrastToggle.svelte

@@ -0,0 +1,36 @@
+<!--
+  @component ContrastToggle
+
+  Citizen high-contrast preference (#244 C7 accessibility pack). A single on/off
+  switch: "on" asks for a high-contrast rendering (max text/surface separation,
+  stronger borders, underlined links) on top of the active light/dark scheme.
+
+  Presentational, mirrors the scheme/motion controls: it reports the new value
+  via `onchange`; the consumer persists it (cookie) and applies the
+  `:root[data-contrast="high"]` layer (tokens/semantic.css) server-side, so SSR
+  paints it with no flash. The label is a prop for i18n (default English).
+
+  @example
+  <ContrastToggle high={prefs.contrast === "high"} onchange={(v) => setContrast(v)} />
+-->
+<script>
+  import Toggle from "./Toggle.svelte";
+
+  let {
+    /** @type {boolean} Whether high-contrast is currently on. */
+    high = false,
+    /** @type {((high: boolean) => void) | undefined} */
+    onchange = undefined,
+    /** @type {string} Accessible label (i18n). */
+    label = "High contrast",
+    ...rest
+  } = $props();
+</script>
+
+<Toggle
+  checked={high}
+  {label}
+  {onchange}
+  data-testid="contrast-toggle"
+  {...rest}
+/>

package/components/ContrastToggle.svelte.d.ts

@@ -0,0 +1,30 @@
+export default ContrastToggle;
+type ContrastToggle = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ContrastToggle
+ *
+ * Citizen high-contrast preference (#244 C7 accessibility pack). A single on/off
+ * switch: "on" asks for a high-contrast rendering (max text/surface separation,
+ * stronger borders, underlined links) on top of the active light/dark scheme.
+ *
+ * Presentational, mirrors the scheme/motion controls: it reports the new value
+ * via `onchange`; the consumer persists it (cookie) and applies the
+ * `:root[data-contrast="high"]` layer (tokens/semantic.css) server-side, so SSR
+ * paints it with no flash. The label is a prop for i18n (default English).
+ *
+ * @example
+ * <ContrastToggle high={prefs.contrast === "high"} onchange={(v) => setContrast(v)} />
+ */
+declare const ContrastToggle: import("svelte").Component<{
+    high?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    high?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>;

package/components/FileUpload.svelte

@@ -158,6 +158,20 @@
   }
 </script>
 
+<!-- The file input is a SIBLING of the trigger button, not a child: a focusable
+     <input> nested inside a <button> is a nested-interactive a11y violation
+     (axe, #244 S5). It is visually hidden + pointer-events:none and is opened
+     via the `inputEl` ref from the button's onclick, so behaviour is unchanged. -->
+<input
+  bind:this={inputEl}
+  type="file"
+  {accept}
+  {multiple}
+  class="fileupload-input"
+  onchange={handleInputChange}
+  tabindex={-1}
+  aria-hidden="true"
+/>
 <button
   type="button"
   class="fileupload {className}"
@@ -171,16 +185,6 @@
   {...rest}
   onclick={handleClick}
 >
-  <input
-    bind:this={inputEl}
-    type="file"
-    {accept}
-    {multiple}
-    class="fileupload-input"
-    onchange={handleInputChange}
-    tabindex={-1}
-    aria-hidden="true"
-  />
   {#if children}
     {@render children()}
   {:else}

package/components/LinkHighlightToggle.svelte

@@ -0,0 +1,37 @@
+<!--
+  @component LinkHighlightToggle
+
+  Citizen "underline links" preference (#244 C7 accessibility pack). A single
+  on/off switch: "on" forces a visible underline on every in-content link, so
+  links are distinguishable by more than colour (WCAG 1.4.1 Use of Colour /
+  Selo item 6 — hyperlinks should not rely on colour alone).
+
+  Presentational, mirrors the scheme/motion controls: it reports the new value
+  via `onchange`; the consumer persists it (cookie) and applies the
+  `:root[data-link-highlight="on"]` layer (tokens/semantic.css) server-side, so
+  SSR paints it with no flash. The label is a prop for i18n (default English).
+
+  @example
+  <LinkHighlightToggle on={prefs.linkHighlight} onchange={(v) => setLinkHighlight(v)} />
+-->
+<script>
+  import Toggle from "./Toggle.svelte";
+
+  let {
+    /** @type {boolean} Whether link-underlining is currently on. */
+    on = false,
+    /** @type {((on: boolean) => void) | undefined} */
+    onchange = undefined,
+    /** @type {string} Accessible label (i18n). */
+    label = "Underline links",
+    ...rest
+  } = $props();
+</script>
+
+<Toggle
+  checked={on}
+  {label}
+  {onchange}
+  data-testid="link-highlight-toggle"
+  {...rest}
+/>

package/components/LinkHighlightToggle.svelte.d.ts

@@ -0,0 +1,31 @@
+export default LinkHighlightToggle;
+type LinkHighlightToggle = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * LinkHighlightToggle
+ *
+ * Citizen "underline links" preference (#244 C7 accessibility pack). A single
+ * on/off switch: "on" forces a visible underline on every in-content link, so
+ * links are distinguishable by more than colour (WCAG 1.4.1 Use of Colour /
+ * Selo item 6 — hyperlinks should not rely on colour alone).
+ *
+ * Presentational, mirrors the scheme/motion controls: it reports the new value
+ * via `onchange`; the consumer persists it (cookie) and applies the
+ * `:root[data-link-highlight="on"]` layer (tokens/semantic.css) server-side, so
+ * SSR paints it with no flash. The label is a prop for i18n (default English).
+ *
+ * @example
+ * <LinkHighlightToggle on={prefs.linkHighlight} onchange={(v) => setLinkHighlight(v)} />
+ */
+declare const LinkHighlightToggle: import("svelte").Component<{
+    on?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    on?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>;

package/components/MapCluster.svelte

@@ -15,7 +15,7 @@
 <script>
   import { fromLonLat } from 'ol/proj.js';
   import { boundingExtent } from 'ol/extent.js';
-  import { createTileLayer, createMapStyles, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {{ id: string, lon: number, lat: number, label?: string, [key: string]: any }[]} */
@@ -31,6 +31,12 @@
     distance = 40,
     /** @type {import('./map-utils.js').TileSourceConfig} */
     tileSource = { type: 'osm' },
+    /** @type {import('./map-utils.js').OverlayLayerDef[]} — ordered GeoJSON
+     *  overlays rendered between the tiles and the cluster layer. Each
+     *  entry: inline `data` or a `url` (e.g. the platform's
+     *  `/{app}/public/layers/{id}/features`), optional flat or GeoStyler
+     *  `style`. Unbounded — render as many as the consumer configures. */
+    layers = [],
     /** @type {((marker: { id: string, lon: number, lat: number, label?: string }) => void) | undefined} */
     onclick = undefined,
     /** @type {string} */
@@ -50,11 +56,40 @@
   let _vectorSource = $state();
   /** @type {any} — Cluster source */
   let _clusterSource = $state();
+  /** @type {any} — shared style factory (set at mount, consumed by the
+   *  overlay owner effect) */
+  let _styles = $state();
   /** @type {any} — Feature constructor */
   let _Feature;
   /** @type {any} — Point constructor */
   let _Point;
 
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the cluster layer — overlays never
+      // cover the markers.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   // Reactive: animate when the CALLER's center/zoom props change. Guarded
   // against the mount-time run — with no explicit `center` the view was
   // initialised to the markers' extent/mean, and animating to the prop
@@ -135,6 +170,7 @@
       // Store refs for reactive effects
       _vectorSource = vectorSource;
       _clusterSource = clusterSource;
+      _styles = styles;
       _Feature = Feature;
       _Point = Point;
 
@@ -186,6 +222,8 @@
 
       map = new OlMap({
         target: container,
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the cluster layer.
         layers: [tileLayer, clusterLayer],
         overlays: [tooltipOverlay],
         view: new View({

package/components/MapCluster.svelte.d.ts

@@ -23,7 +23,9 @@ declare const MapCluster: import("svelte").Component<{
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;
+    layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>, {}, "">;
@@ -33,7 +35,9 @@ type $$ComponentProps = {
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;
+    layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>;

package/components/MapDisplay.svelte

@@ -41,6 +41,38 @@
   /** @type {HTMLElement | undefined} */
   let container = $state();
 
+  // Hoisted references for the overlay owner effect
+  /** @type {import('ol/Map.js').default | undefined} */
+  let _map = $state();
+  /** @type {any} — shared style factory (set at mount) */
+  let _styles = $state();
+
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the marker/polygon vector layer —
+      // overlays never cover the marker.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container) return;
 
@@ -77,8 +109,7 @@
       ]);
       if (disposed) return;
 
-      const overlayLayers = await createOverlayLayers(layers, styles);
-      if (disposed) return;
+      _styles = styles;
 
       /** @type {Feature[]} */
       const features = [];
@@ -103,20 +134,23 @@
 
       map = new OlMap({
         target: container,
-        layers: [tileLayer, ...overlayLayers, vectorLayer],
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the vector layer.
+        layers: [tileLayer, vectorLayer],
         view: new View({
           center: fromLonLat(center),
           zoom,
         }),
         controls: [],
       });
+      _map = map;
 
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorLayer.getSource()?.changed();
         // Token-styled overlays (no custom style) re-read via the shared
         // styles object; poke their sources so OL repaints.
-        for (const l of overlayLayers) l.getSource()?.changed();
+        for (const l of _overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapDisplay', /** @type {Error} */ (err)); } })();
 

package/components/MapHeatmap.svelte

@@ -21,7 +21,7 @@
 -->
 <script>
   import { fromLonLat } from 'ol/proj.js';
-  import { createTileLayer, getHeatmapGradient, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, getHeatmapGradient, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {{ lon: number, lat: number, weight?: number }[]} */
@@ -38,6 +38,12 @@
     gradient = undefined,
     /** @type {import('./map-utils.js').TileSourceConfig} */
     tileSource = { type: 'osm' },
+    /** @type {import('./map-utils.js').OverlayLayerDef[]} — ordered GeoJSON
+     *  overlays rendered between the tiles and the heatmap layer. Each
+     *  entry: inline `data` or a `url` (e.g. the platform's
+     *  `/{app}/public/layers/{id}/features`), optional flat or GeoStyler
+     *  `style`. Unbounded — render as many as the consumer configures. */
+    layers = [],
     /** @type {number} — max zoom when auto-fitting to points extent */
     maxZoom = 17,
     /** @type {string} */
@@ -50,6 +56,38 @@
   /** @type {HTMLElement | undefined} */
   let container = $state();
 
+  // Hoisted references for the overlay owner effect
+  /** @type {import('ol/Map.js').default | undefined} */
+  let _map = $state();
+  /** @type {any} — shared style factory (set at mount) */
+  let _styles = $state();
+
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the heatmap layer — overlays never
+      // cover the heat surface.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container) return;
 
@@ -81,6 +119,12 @@
       const tileLayer = await createTileLayer(tileSource);
       if (disposed) return;
 
+      // Style factory only feeds overlay fallback styles here — the heatmap
+      // layer itself styles via gradient tokens.
+      const styles = await createMapStyles(container);
+      if (disposed) return;
+      _styles = styles;
+
       // Non-linear weight normalization: sqrt lifts low values so they're
       // visible while preserving relative ordering. OL expects 0-1.
       const maxWeight = Math.max(...points.map(p => p.weight ?? 1), 1);
@@ -106,12 +150,15 @@
 
       map = new OlMap({
         target: container,
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the heatmap layer.
         layers: [tileLayer, heatmapLayer],
         view: new View({
           center: fromLonLat(center),
           zoom,
         }),
       });
+      _map = map;
 
       // Auto-fit view to points extent
       if (points.length > 0) {

package/components/MapHeatmap.svelte.d.ts

@@ -32,6 +32,7 @@ declare const MapHeatmap: import("svelte").Component<{
     blur?: number;
     gradient?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     maxZoom?: number;
     height?: string;
     class?: string;
@@ -44,6 +45,7 @@ type $$ComponentProps = {
     blur?: number;
     gradient?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     maxZoom?: number;
     height?: string;
     class?: string;

package/components/MapPicker.svelte

@@ -95,6 +95,9 @@
   let container = $state();
   /** @type {import('ol/Map.js').default | undefined} */
   let _map = $state();
+  /** @type {any} — shared style factory (set at mount, consumed by the
+   *  overlay owner effect) */
+  let _styles = $state();
   /** @type {any} — VectorSource for placing markers via search */
   let _vectorSource;
   /** @type {any} */
@@ -142,6 +145,56 @@
     onoutofbounds(!pointInRings(coords, boundaryRings), coords);
   }
 
+  // The dashed boundary overlay has ONE owner: this effect. Consumers
+  // typically FETCH the boundary (it arrives after map init), so a
+  // mount-time-only build silently drops it — the overlay must track
+  // `boundaryRings` for as long as the map lives. The sequence counter
+  // drops stale async builds when the rings change mid-flight.
+  /** @type {any} */
+  let _boundaryLayer = null;
+  let _boundarySeq = 0;
+  $effect(() => {
+    const rings = boundaryRings;
+    const map = _map;
+    if (!map || !container) return;
+    const seq = ++_boundarySeq;
+    void (async () => {
+      const layer = rings.length ? await createBoundaryLayer(rings, container) : null;
+      if (seq !== _boundarySeq || _map !== map) return;
+      if (_boundaryLayer) map.removeLayer(_boundaryLayer);
+      _boundaryLayer = layer;
+      if (layer) {
+        // Just below the pin/draw vector layer — boundary never covers the pin.
+        const coll = map.getLayers();
+        coll.insertAt(coll.getLength() - 1, layer);
+      }
+    })();
+  });
+
+  // The `layers` overlays get the same single-owner treatment as the
+  // boundary above: consumers typically RESOLVE overlay defs asynchronously
+  // (layer codes → url defs, after a fetch), so a mount-time-only build
+  // silently drops them.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the boundary/pin layers — overlays
+      // never cover the pin.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container || disabled) return;
 
@@ -178,11 +231,10 @@
       ]);
       if (disposed) return;
 
-      const [overlayLayers, boundaryLayer] = await Promise.all([
-        createOverlayLayers(layers, styles),
-        createBoundaryLayer(boundaryRings, container),
-      ]);
-      if (disposed) return;
+      // Neither the boundary overlay NOR the `layers` overlays are built
+      // here — the reactive owner effects above track their late-arriving
+      // props for as long as the map lives.
+      _styles = styles;
 
       const vectorSource = new VectorSource();
       _vectorSource = vectorSource;
@@ -240,12 +292,7 @@
 
       map = new OlMap({
         target: container,
-        layers: [
-          tileLayer,
-          ...overlayLayers,
-          ...(boundaryLayer ? [boundaryLayer] : []),
-          vectorLayer,
-        ],
+        layers: [tileLayer, vectorLayer],
         view: new View({
           center: initialCenter,
           zoom,
@@ -258,7 +305,7 @@
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorSource.changed();
-        for (const l of overlayLayers) l.getSource()?.changed();
+        for (const l of _overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapPicker', /** @type {Error} */ (err)); } })();
 

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.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";

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.0",
+  "version": "0.18.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

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 */
+}