@aiaiai-pt/design-system 0.17.1 → 0.18.0

package/components/ActionFormRenderer.svelte

@@ -397,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)}
@@ -405,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
@@ -416,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
@@ -427,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}
@@ -491,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"}
@@ -526,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}
@@ -544,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}
@@ -642,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/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.d.ts

@@ -25,6 +25,7 @@ declare const MapCluster: import("svelte").Component<{
     tileSource?: Record<string, any>;
     layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>, {}, "">;
@@ -36,6 +37,7 @@ type $$ComponentProps = {
     tileSource?: Record<string, any>;
     layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>;

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.1",
+  "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 */
+}