@aiaiai-pt/design-system 0.24.0 → 0.25.0

package/components/ActionFormRenderer.svelte

@@ -85,6 +85,22 @@
     /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
      *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
     geoError?: string;
+    /** Service-flow wizard (#105 P6): render ONLY the section whose
+     *  name (its label, falling back to its key) matches — one screen per
+     *  step. The value bag still spans ALL parameters (so answers persist
+     *  across steps and the final payload is complete); only the DISPLAY is
+     *  scoped. Null (default) renders every section, byte-identical to today. */
+    activeSectionKey?: string | null;
+    /** Service-flow wizard (#105 P6): suppress the renderer's own submit
+     *  button / captcha / error — the wizard shell owns the nav and posts the
+     *  payload once at the end. Default false (the standalone form keeps its
+     *  button). */
+    hideSubmit?: boolean;
+    /** Service-flow wizard (#105 P6): fires with the freshly built payload
+     *  whenever a value or attachment changes, so the wizard always holds the
+     *  complete payload (incl. attachment_keys) to review and submit. Read-only
+     *  consumers omit it. */
+    onchange?: (payload: Record<string, unknown>) => void;
   }
 
   let {
@@ -102,6 +118,9 @@
     layers = [],
     onoutofbounds = undefined,
     geoError = undefined,
+    activeSectionKey = null,
+    hideSubmit = false,
+    onchange = undefined,
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
@@ -125,7 +144,9 @@
   // consumer wired an apply. Preview modes (admin-preview/adapter-preview) and a
   // missing onApply stay read-only — the button never renders.
   const isSubmitMode = $derived(mode === "public-submit" || mode === "admin-execute");
-  const showSubmit = $derived(isSubmitMode && onApply !== undefined);
+  // The wizard (#105 P6) suppresses the internal button via hideSubmit — it
+  // owns the nav and posts once at the end.
+  const showSubmit = $derived(isSubmitMode && onApply !== undefined && !hideSubmit);
 
   const renderedAction = $derived((schema?.action as Entity | null | undefined) ?? action);
   const renderedPlacement = $derived((schema?.placement as Entity | null | undefined) ?? placement);
@@ -146,9 +167,23 @@
   );
   const schemaSections = $derived(schemaSectionsFromContract());
   const sections = $derived(schemaSections ?? groupIntoSections(visibleParameters));
+  // Wizard pagination (#105 P6): when a section is active, render only it. The
+  // value bag is unaffected — every parameter is still seeded and submitted.
+  const displaySections = $derived(
+    activeSectionKey == null
+      ? sections
+      : sections.filter((section) => section.name === activeSectionKey),
+  );
   const payload = $derived(buildPayload());
   const payloadJson = $derived(JSON.stringify(payload, null, 2));
 
+  // Wizard (#105 P6): surface the live payload so the shell can review + submit
+  // it. Reading `payload` registers the dependency; the effect re-runs whenever
+  // a value or attachment changes.
+  $effect(() => {
+    onchange?.(payload);
+  });
+
   // Client-side submit gate (layer 1 — see the ADL): every required, visible
   // parameter must have a non-empty value. Server-side submission criteria are
   // enforced by the BFF on submit and surfaced via `submitError`.
@@ -520,21 +555,26 @@
 {/snippet}
 
 <div class="renderer" data-testid={`action-form-renderer-${mode}`} data-layout={resolvedLayout.key}>
-  <div class="renderer-header">
-    <div>
-      <!-- The placement-preview eyebrow + surface badge are operator chrome —
-           hidden in public-submit so a citizen sees a clean form title. -->
+  <!-- Wizard pagination (#105 P6): the ServiceFlow shell owns the step
+       heading, so the renderer's own action-title header is suppressed when a
+       section is active to avoid a duplicate heading per step. -->
+  {#if activeSectionKey == null}
+    <div class="renderer-header">
+      <div>
+        <!-- The placement-preview eyebrow + surface badge are operator chrome —
+             hidden in public-submit so a citizen sees a clean form title. -->
+        {#if mode !== "public-submit"}
+          <p class="eyebrow">Placement preview</p>
+        {/if}
+        <h3>{String(renderedAction?.label ?? renderedAction?.key ?? "Select an action")}</h3>
+      </div>
       {#if mode !== "public-submit"}
-        <p class="eyebrow">Placement preview</p>
+        <Badge variant={renderedPlacement ? "info" : "neutral"}>
+          {String(renderedPlacement?.surface ?? "No placement")}
+        </Badge>
       {/if}
-      <h3>{String(renderedAction?.label ?? renderedAction?.key ?? "Select an action")}</h3>
     </div>
-    {#if mode !== "public-submit"}
-      <Badge variant={renderedPlacement ? "info" : "neutral"}>
-        {String(renderedPlacement?.surface ?? "No placement")}
-      </Badge>
-    {/if}
-  </div>
+  {/if}
 
   {#if !renderedAction}
     <p class="muted">Select an action to preview its placement-aware form contract.</p>
@@ -550,7 +590,7 @@
         renderedAction?.label ?? renderedAction?.key ?? "Form",
       )}
     >
-      <Layout {sections} field={fieldRow} />
+      <Layout sections={displaySections} field={fieldRow} />
     </form>
   {/if}
 

package/components/ActionFormRenderer.svelte.d.ts

@@ -70,6 +70,22 @@ interface Props {
     /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
      *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
     geoError?: string;
+    /** Service-flow wizard (#105 P6): render ONLY the section whose
+     *  name (its label, falling back to its key) matches — one screen per
+     *  step. The value bag still spans ALL parameters (so answers persist
+     *  across steps and the final payload is complete); only the DISPLAY is
+     *  scoped. Null (default) renders every section, byte-identical to today. */
+    activeSectionKey?: string | null;
+    /** Service-flow wizard (#105 P6): suppress the renderer's own submit
+     *  button / captcha / error — the wizard shell owns the nav and posts the
+     *  payload once at the end. Default false (the standalone form keeps its
+     *  button). */
+    hideSubmit?: boolean;
+    /** Service-flow wizard (#105 P6): fires with the freshly built payload
+     *  whenever a value or attachment changes, so the wizard always holds the
+     *  complete payload (incl. attachment_keys) to review and submit. Read-only
+     *  consumers omit it. */
+    onchange?: (payload: Record<string, unknown>) => void;
 }
 declare const ActionFormRenderer: import("svelte").Component<Props, {}, "">;
 type ActionFormRenderer = ReturnType<typeof ActionFormRenderer>;

package/components/CheckAnswers.svelte

@@ -0,0 +1,197 @@
+<!--
+  @component CheckAnswers
+
+  The "review your answers before submitting" summary — a grouped description
+  list of every answer the citizen gave, each with a "Change" link back to the
+  step that captured it. Vertical-agnostic: it renders whatever label/value
+  pairs the consumer collected (from the action's parameter labels), grouped by
+  the flow's sections. Pure presentation — no state, no network.
+
+  Accessibility (WCAG 3.3.4, Error Prevention): every answer is reviewable and
+  editable before the irreversible submit. Each "Change" control carries an
+  accessible name that includes WHAT it changes (the visible "Change" plus a
+  visually-hidden field label), so a screen-reader user never meets a row of
+  identical "Change" links. Answers are a `<dl>` (the semantic structure for
+  term/description pairs); section headings are `<h3>` under the widget's `h2`.
+
+  @example
+  <CheckAnswers
+    label="Check your answers"
+    groups={[
+      { label: "About you", items: [
+        { key: "name", label: "Full name", value: "Ana Silva", onChange: () => goTo(0) },
+      ]},
+      { label: "Your idea", items: [
+        { key: "title", label: "Title", value: "Bike lanes", onChange: () => goTo(1) },
+      ]},
+    ]}
+  />
+-->
+<script module>
+  /**
+   * @typedef {{ key: string, label: string, value: string, onChange?: () => void }} AnswerItem
+   * @typedef {{ label?: string, items: AnswerItem[] }} AnswerGroup
+   */
+</script>
+
+<script>
+  let {
+    /** @type {AnswerGroup[]} The collected answers, grouped by section. */
+    groups = [],
+    /** @type {string} Accessible name for the review region (localize it). */
+    label = "Check your answers",
+    /** @type {string} Visible text on each change control (localize it). */
+    changeLabel = "Change",
+    /** @type {string} Shown when there are no answers yet (localize it). */
+    emptyText = "There are no answers to review yet.",
+    /** @type {string} Placeholder for an answer the citizen left blank (localize it). */
+    blankText = "Not provided",
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const hasAnswers = $derived(groups.some((g) => g.items.length > 0));
+</script>
+
+<section class="check-answers {className}" aria-label={label} {...rest}>
+  {#if hasAnswers}
+    {#each groups as group (group.label ?? group.items[0]?.key)}
+      {#if group.items.length > 0}
+        <div class="check-answers-group">
+          {#if group.label}
+            <h3 class="check-answers-group-heading">{group.label}</h3>
+          {/if}
+          <dl class="check-answers-list">
+            {#each group.items as item (item.key)}
+              <div class="check-answers-row">
+                <dt class="check-answers-term">{item.label}</dt>
+                <dd class="check-answers-value">
+                  {item.value || blankText}
+                </dd>
+                <dd class="check-answers-action">
+                  {#if item.onChange}
+                    <button
+                      type="button"
+                      class="check-answers-change"
+                      onclick={() => item.onChange?.()}
+                    >
+                      {changeLabel}<span class="check-answers-sr"
+                        >&nbsp;{item.label}</span
+                      >
+                    </button>
+                  {/if}
+                </dd>
+              </div>
+            {/each}
+          </dl>
+        </div>
+      {/if}
+    {/each}
+  {:else}
+    <p class="check-answers-empty">{emptyText}</p>
+  {/if}
+</section>
+
+<style>
+  .check-answers {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .check-answers-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .check-answers-group-heading {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .check-answers-list {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .check-answers-row {
+    display: grid;
+    grid-template-columns: minmax(8rem, 1fr) 2fr auto;
+    gap: var(--space-sm);
+    align-items: start;
+    padding: var(--space-sm) 0;
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .check-answers-term {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+    margin: 0;
+  }
+
+  .check-answers-value {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+    margin: 0;
+    overflow-wrap: anywhere;
+  }
+
+  .check-answers-action {
+    margin: 0;
+    justify-self: end;
+  }
+
+  .check-answers-change {
+    appearance: none;
+    background: none;
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-accent);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  .check-answers-change:hover {
+    color: var(--color-accent-hover);
+  }
+
+  .check-answers-empty {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text-muted);
+    margin: 0;
+  }
+
+  /* Visually-hidden text that screen readers still announce (WCAG 3.3.4). */
+  .check-answers-sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  @media (max-width: 30rem) {
+    .check-answers-row {
+      grid-template-columns: 1fr auto;
+    }
+    .check-answers-term {
+      grid-column: 1 / -1;
+    }
+  }
+</style>

package/components/CheckAnswers.svelte.d.ts

@@ -0,0 +1,60 @@
+export default CheckAnswers;
+export type AnswerItem = {
+    key: string;
+    label: string;
+    value: string;
+    onChange?: () => void;
+};
+export type AnswerGroup = {
+    label?: string;
+    items: AnswerItem[];
+};
+type CheckAnswers = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * CheckAnswers
+ *
+ * The "review your answers before submitting" summary — a grouped description
+ * list of every answer the citizen gave, each with a "Change" link back to the
+ * step that captured it. Vertical-agnostic: it renders whatever label/value
+ * pairs the consumer collected (from the action's parameter labels), grouped by
+ * the flow's sections. Pure presentation — no state, no network.
+ *
+ * Accessibility (WCAG 3.3.4, Error Prevention): every answer is reviewable and
+ * editable before the irreversible submit. Each "Change" control carries an
+ * accessible name that includes WHAT it changes (the visible "Change" plus a
+ * visually-hidden field label), so a screen-reader user never meets a row of
+ * identical "Change" links. Answers are a `<dl>` (the semantic structure for
+ * term/description pairs); section headings are `<h3>` under the widget's `h2`.
+ *
+ * @example
+ * <CheckAnswers
+ *   label="Check your answers"
+ *   groups={[
+ *     { label: "About you", items: [
+ *       { key: "name", label: "Full name", value: "Ana Silva", onChange: () => goTo(0) },
+ *     ]},
+ *     { label: "Your idea", items: [
+ *       { key: "title", label: "Title", value: "Bike lanes", onChange: () => goTo(1) },
+ *     ]},
+ *   ]}
+ * />
+ */
+declare const CheckAnswers: import("svelte").Component<{
+    groups?: any[];
+    label?: string;
+    changeLabel?: string;
+    emptyText?: string;
+    blankText?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    groups?: any[];
+    label?: string;
+    changeLabel?: string;
+    emptyText?: string;
+    blankText?: string;
+    class?: string;
+} & Record<string, any>;

package/components/Confirmation.svelte

@@ -0,0 +1,172 @@
+<!--
+  @component Confirmation
+
+  The receipt panel shown after a successful submission: a success banner with
+  the citizen's reference number front-and-centre, a "what happens next" body,
+  and an optional link to track the submission. Vertical-agnostic — it knows
+  nothing about proposals or occurrences, only "here is your reference and what
+  to expect". Pure presentation; the consumer fetched the reference.
+
+  Accessibility: a `<section>` region named by `label`; the success heading is
+  an `<h2>` (the page `<h1>` is the consumer's, same split as the other account
+  widgets) carrying a decorative check. The reference is emphasised text inside
+  a labelled block, not colour alone. Semantic tokens throughout, so the
+  success styling survives dark / high-contrast schemes (#244).
+
+  @example
+  <Confirmation
+    label="Submission received"
+    title="Your proposal has been submitted"
+    reference="PRP-2026-0042"
+    referenceLabel="Your reference number"
+    body="We've sent a confirmation. The committee will review your proposal."
+    trackHref="/participacao/acompanhar/PRP-2026-0042"
+    trackLabel="Track this proposal"
+  />
+-->
+<script>
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {string} Accessible name for the confirmation region (localize it). */
+    label = "Confirmation",
+    /** @type {string} The success headline (localize it). */
+    title = "Submission received",
+    /** @type {string} The reference / tracking number to surface. */
+    reference = "",
+    /** @type {string} Label above the reference number (localize it). */
+    referenceLabel = "Your reference number",
+    /** @type {string} The "what happens next" copy (localize it). */
+    body = "",
+    /** @type {string | undefined} Link to track the submission. */
+    trackHref = undefined,
+    /** @type {string} Label for the track link (localize it). */
+    trackLabel = "Track your submission",
+
+    /** @type {import('svelte').Snippet | undefined} Extra content (e.g. a next-steps list). */
+    children = undefined,
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="confirmation {className}" aria-label={label} {...rest}>
+  <div class="confirmation-banner">
+    <span class="confirmation-icon" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none">
+        <path
+          d="M5 12.5l4.5 4.5L19 7.5"
+          stroke="currentColor"
+          stroke-width="2.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </span>
+    <h2 class="confirmation-title">{title}</h2>
+  </div>
+
+  {#if reference}
+    <div class="confirmation-reference">
+      <span class="confirmation-reference-label">{referenceLabel}</span>
+      <strong class="confirmation-reference-value">{reference}</strong>
+    </div>
+  {/if}
+
+  {#if body}
+    <p class="confirmation-body">{body}</p>
+  {/if}
+
+  {#if children}
+    <div class="confirmation-extra">{@render children()}</div>
+  {/if}
+
+  {#if trackHref}
+    <div class="confirmation-actions">
+      <Button variant="secondary" href={trackHref}>{trackLabel}</Button>
+    </div>
+  {/if}
+</section>
+
+<style>
+  .confirmation {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+    padding: var(--space-xl);
+    border: 1px solid var(--color-success);
+    border-radius: var(--radius-lg);
+    background: var(--color-success-subtle);
+  }
+
+  .confirmation-banner {
+    display: flex;
+    align-items: center;
+    gap: var(--space-md);
+  }
+
+  .confirmation-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: var(--radius-circle);
+    background: var(--color-success);
+    color: var(--color-surface);
+  }
+
+  .confirmation-icon svg {
+    width: 1.5rem;
+    height: 1.5rem;
+  }
+
+  .confirmation-title {
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .confirmation-reference {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+  }
+
+  .confirmation-reference-label {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+  }
+
+  .confirmation-reference-value {
+    font-family: var(--type-data-font);
+    font-size: var(--type-heading-sm-size);
+    letter-spacing: var(--type-data-tracking);
+    color: var(--color-text);
+  }
+
+  .confirmation-body {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    line-height: var(--type-body-leading);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .confirmation-extra {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+  }
+
+  .confirmation-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-sm);
+  }
+</style>

package/components/Confirmation.svelte.d.ts

@@ -0,0 +1,53 @@
+export default Confirmation;
+type Confirmation = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Confirmation
+ *
+ * The receipt panel shown after a successful submission: a success banner with
+ * the citizen's reference number front-and-centre, a "what happens next" body,
+ * and an optional link to track the submission. Vertical-agnostic — it knows
+ * nothing about proposals or occurrences, only "here is your reference and what
+ * to expect". Pure presentation; the consumer fetched the reference.
+ *
+ * Accessibility: a `<section>` region named by `label`; the success heading is
+ * an `<h2>` (the page `<h1>` is the consumer's, same split as the other account
+ * widgets) carrying a decorative check. The reference is emphasised text inside
+ * a labelled block, not colour alone. Semantic tokens throughout, so the
+ * success styling survives dark / high-contrast schemes (#244).
+ *
+ * @example
+ * <Confirmation
+ *   label="Submission received"
+ *   title="Your proposal has been submitted"
+ *   reference="PRP-2026-0042"
+ *   referenceLabel="Your reference number"
+ *   body="We've sent a confirmation. The committee will review your proposal."
+ *   trackHref="/participacao/acompanhar/PRP-2026-0042"
+ *   trackLabel="Track this proposal"
+ * />
+ */
+declare const Confirmation: import("svelte").Component<{
+    label?: string;
+    title?: string;
+    reference?: string;
+    referenceLabel?: string;
+    body?: string;
+    trackHref?: any;
+    trackLabel?: string;
+    children?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label?: string;
+    title?: string;
+    reference?: string;
+    referenceLabel?: string;
+    body?: string;
+    trackHref?: any;
+    trackLabel?: string;
+    children?: any;
+    class?: string;
+} & Record<string, any>;

package/components/ServiceFlow.svelte

@@ -0,0 +1,264 @@
+<!--
+  @component ServiceFlow
+
+  The chrome for a multi-step submit journey (a "service flow"): a step
+  indicator, a progress bar, an error-summary region, the active step's body,
+  and the prev / next / submit navigation. Vertical-agnostic — it renders
+  whatever the consumer puts in the `children` snippet for the active step and
+  never knows what an "eligibility check" or "proposal" is. The consumer owns
+  the wizard STATE (which step, the collected answers) and the network; this
+  shell owns the layout, the accessible step semantics, and focus management.
+
+  Controlled: pass `current` (0-based active step) and the `steps` labels;
+  drive it with `onPrev` / `onNext` (advance) and `onSubmit` (the final step's
+  primary action). `canProceed=false` disables the primary button (e.g. an
+  eligibility gate failed or the step is invalid); `busy=true` shows it loading
+  and locks the nav (a dry-run or the submit is in flight).
+
+  Accessibility (WCAG): a `<section>` region named by `label`; a polite live
+  region announces "Step X of Y"; on every step change focus moves to the step
+  body (or, if the consumer surfaces `errors`, to the error summary — an
+  `role="alert"` list the citizen lands on so the reason is read first). The
+  error summary, the step nav buttons, and the progress bar all ride semantic
+  tokens, so dark / high-contrast schemes (#244) work unchanged.
+
+  @example
+  <ServiceFlow
+    label="Submit a proposal"
+    steps={[{ label: "Eligibility" }, { label: "Your idea" }, { label: "Review" }]}
+    current={step}
+    canProceed={eligible}
+    busy={checking}
+    errors={violations}
+    onPrev={() => step--}
+    onNext={() => step++}
+    onSubmit={() => submit()}
+  >
+    {@render activeStepBody()}
+  </ServiceFlow>
+-->
+<script module>
+  /**
+   * @typedef {{ label: string }} FlowStep
+   */
+</script>
+
+<script>
+  import Stepper from "./Stepper.svelte";
+  import Progress from "./Progress.svelte";
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {FlowStep[]} Ordered step labels for the indicator. */
+    steps = [],
+    /** @type {number} The active step, 0-based. */
+    current = 0,
+    /** @type {string} Accessible name for the flow region (localize it). */
+    label = "Step-by-step form",
+    /** @type {boolean} Whether the primary (next/submit) button is enabled. */
+    canProceed = true,
+    /** @type {boolean} A step action is in flight — locks nav, loads the button. */
+    busy = false,
+    /** @type {string[]} Blocking messages for the error summary (localize them). */
+    errors = [],
+
+    /** @type {string} Label for the error-summary heading (localize it). */
+    errorSummaryLabel = "There is a problem",
+    /** @type {string} Back-button label (localize it). */
+    prevLabel = "Back",
+    /** @type {string} Advance-button label (localize it). */
+    nextLabel = "Continue",
+    /** @type {string} Final-step primary label (localize it). */
+    submitLabel = "Submit",
+    /**
+     * @type {(stepNumber: number, total: number) => string}
+     * Builds the "Step X of Y" announcement (localize it).
+     */
+    progressLabel = (n, total) => `Step ${n} of ${total}`,
+
+    /** @type {(() => void) | undefined} Go to the previous step. */
+    onPrev = undefined,
+    /** @type {(() => void) | undefined} Advance to the next step. */
+    onNext = undefined,
+    /** @type {(() => void) | undefined} Run the final step's primary action. */
+    onSubmit = undefined,
+
+    /** @type {import('svelte').Snippet | undefined} The active step's body. */
+    children = undefined,
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const total = $derived(steps.length || 1);
+  const isFirst = $derived(current <= 0);
+  const isLast = $derived(current >= total - 1);
+  const hasErrors = $derived(errors.length > 0);
+
+  /** Map the flat step labels to the Stepper's status model. */
+  const indicatorSteps = $derived(
+    steps.map((s, i) => ({
+      label: s.label,
+      status:
+        i < current ? "complete" : i === current ? "active" : "upcoming",
+    })),
+  );
+
+  /** @type {HTMLElement | undefined} */
+  let bodyRef = $state(undefined);
+  /** @type {HTMLElement | undefined} */
+  let errorRef = $state(undefined);
+
+  // Focus management: after the first render, every step change (or a newly
+  // surfaced error) moves focus so a keyboard / screen-reader user is taken to
+  // the right place — the error summary when blocked, otherwise the step body.
+  // The initial mount is skipped so the page doesn't steal focus on load.
+  let mounted = false;
+  $effect(() => {
+    // Re-run when the step or the error state changes.
+    void current;
+    void hasErrors;
+    if (!mounted) {
+      mounted = true;
+      return;
+    }
+    const target = hasErrors ? errorRef : bodyRef;
+    target?.focus();
+  });
+</script>
+
+<section class="service-flow {className}" aria-label={label} {...rest}>
+  {#if steps.length > 1}
+    <Stepper steps={indicatorSteps} class="service-flow-stepper" />
+  {/if}
+
+  <Progress
+    value={current + 1}
+    max={total}
+    class="service-flow-progress"
+    aria-label={progressLabel(current + 1, total)}
+  />
+  <p class="service-flow-progress-text" aria-live="polite">
+    {progressLabel(current + 1, total)}
+  </p>
+
+  {#if hasErrors}
+    <div
+      class="service-flow-errors"
+      role="alert"
+      tabindex="-1"
+      bind:this={errorRef}
+    >
+      <h2 class="service-flow-errors-heading">{errorSummaryLabel}</h2>
+      <ul class="service-flow-errors-list">
+        {#each errors as message}
+          <li>{message}</li>
+        {/each}
+      </ul>
+    </div>
+  {/if}
+
+  <div class="service-flow-body" tabindex="-1" bind:this={bodyRef}>
+    {@render children?.()}
+  </div>
+
+  <div class="service-flow-nav">
+    {#if !isFirst}
+      <Button variant="ghost" disabled={busy} onclick={() => onPrev?.()}>
+        {prevLabel}
+      </Button>
+    {/if}
+    {#if isLast}
+      <Button
+        variant="primary"
+        loading={busy}
+        disabled={!canProceed || busy}
+        onclick={() => onSubmit?.()}
+      >
+        {submitLabel}
+      </Button>
+    {:else}
+      <Button
+        variant="primary"
+        loading={busy}
+        disabled={!canProceed || busy}
+        onclick={() => onNext?.()}
+      >
+        {nextLabel}
+      </Button>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .service-flow {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .service-flow-progress-text {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+    margin: calc(-1 * var(--space-sm)) 0 0;
+  }
+
+  .service-flow-errors {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+    padding: var(--space-md);
+    border: 1px solid var(--color-destructive);
+    border-radius: var(--radius-md);
+    background: var(--color-destructive-subtle);
+  }
+
+  /* The alert region is programmatically focusable but shows no focus ring. */
+  .service-flow-errors:focus {
+    outline: none;
+  }
+
+  .service-flow-errors-heading {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .service-flow-errors-list {
+    margin: 0;
+    padding-left: var(--space-lg);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+  }
+
+  .service-flow-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .service-flow-body:focus {
+    outline: none;
+  }
+
+  .service-flow-nav {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: var(--space-sm);
+    padding-top: var(--space-md);
+    border-top: 1px solid var(--color-border);
+  }
+
+  /* When only the primary button shows (first step), keep it right-aligned. */
+  .service-flow-nav:has(> :only-child) {
+    justify-content: flex-end;
+  }
+</style>

package/components/ServiceFlow.svelte.d.ts

@@ -0,0 +1,83 @@
+export default ServiceFlow;
+export type FlowStep = {
+    label: string;
+};
+type ServiceFlow = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ServiceFlow
+ *
+ * The chrome for a multi-step submit journey (a "service flow"): a step
+ * indicator, a progress bar, an error-summary region, the active step's body,
+ * and the prev / next / submit navigation. Vertical-agnostic — it renders
+ * whatever the consumer puts in the `children` snippet for the active step and
+ * never knows what an "eligibility check" or "proposal" is. The consumer owns
+ * the wizard STATE (which step, the collected answers) and the network; this
+ * shell owns the layout, the accessible step semantics, and focus management.
+ *
+ * Controlled: pass `current` (0-based active step) and the `steps` labels;
+ * drive it with `onPrev` / `onNext` (advance) and `onSubmit` (the final step's
+ * primary action). `canProceed=false` disables the primary button (e.g. an
+ * eligibility gate failed or the step is invalid); `busy=true` shows it loading
+ * and locks the nav (a dry-run or the submit is in flight).
+ *
+ * Accessibility (WCAG): a `<section>` region named by `label`; a polite live
+ * region announces "Step X of Y"; on every step change focus moves to the step
+ * body (or, if the consumer surfaces `errors`, to the error summary — an
+ * `role="alert"` list the citizen lands on so the reason is read first). The
+ * error summary, the step nav buttons, and the progress bar all ride semantic
+ * tokens, so dark / high-contrast schemes (#244) work unchanged.
+ *
+ * @example
+ * <ServiceFlow
+ *   label="Submit a proposal"
+ *   steps={[{ label: "Eligibility" }, { label: "Your idea" }, { label: "Review" }]}
+ *   current={step}
+ *   canProceed={eligible}
+ *   busy={checking}
+ *   errors={violations}
+ *   onPrev={() => step--}
+ *   onNext={() => step++}
+ *   onSubmit={() => submit()}
+ * >
+ *   {@render activeStepBody()}
+ * </ServiceFlow>
+ */
+declare const ServiceFlow: import("svelte").Component<{
+    steps?: any[];
+    current?: number;
+    label?: string;
+    canProceed?: boolean;
+    busy?: boolean;
+    errors?: any[];
+    errorSummaryLabel?: string;
+    prevLabel?: string;
+    nextLabel?: string;
+    submitLabel?: string;
+    progressLabel?: Function;
+    onPrev?: any;
+    onNext?: any;
+    onSubmit?: any;
+    children?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    steps?: any[];
+    current?: number;
+    label?: string;
+    canProceed?: boolean;
+    busy?: boolean;
+    errors?: any[];
+    errorSummaryLabel?: string;
+    prevLabel?: string;
+    nextLabel?: string;
+    submitLabel?: string;
+    progressLabel?: Function;
+    onPrev?: any;
+    onNext?: any;
+    onSubmit?: any;
+    children?: any;
+    class?: string;
+} & Record<string, any>;

package/components/index.js

@@ -97,6 +97,13 @@ export { default as NotificationPrefs } from "./NotificationPrefs.svelte";
 // data portability (export) + type-to-confirm account erasure.
 export { default as ConsentManager } from "./ConsentManager.svelte";
 
+// Service-flow steps (#105 Phase 6) — the multi-step submit journey: a wizard
+// shell (step nav + progress + focus mgmt + error summary), the review-before-
+// submit answer list (WCAG 3.3.4 change links), and the success receipt.
+export { default as ServiceFlow } from "./ServiceFlow.svelte";
+export { default as CheckAnswers } from "./CheckAnswers.svelte";
+export { default as Confirmation } from "./Confirmation.svelte";
+
 // Feedback
 export { default as Alert } from "./Alert.svelte";
 export { default as Toast } from "./Toast.svelte";

package/package.json

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