@aiaiai-pt/design-system 0.50.0 → 0.51.1

package/components/KpiRegister.svelte

@@ -1,113 +1,155 @@
 <!--
   @component KpiRegister
 
-  A StatCard-variant register for KPI values where a measured reading
-  visually out-ranks a projected value (larger display text, higher position
-  in the visual hierarchy).
-
-  BOUNDARY ELEMENT: throws when a projected value is provided without a seal.
-  This is the enforcement point for the seal rule (prd.md §5.1): no unsealed
-  projected value may cross this boundary into the rendering surface. The throw
-  is unconditional — production code must never pass an unsealed projected value
-  here; the guard exists to catch contract violations early.
+  The two-register composition for one KPI: the more authoritative value above,
+  the less authoritative beneath. It is where "measured out-ranks projected"
+  becomes concrete — in type SIZE, in POSITION, and in SCREEN-READER READING
+  ORDER, all three.
+
+  The ranking is enforced STRUCTURALLY, by evidence class, not by word. A
+  reading outranks a model output, which outranks a forecast
+  (EVIDENCE_CLASS_RANK in @aiaiai-pt/widget-system/core). That ordering holds
+  under every enumeration in the corpus, so this component needs no vocabulary
+  to enforce it — and it throws if a caller tries to seat a more authoritative
+  value in the lower register.
+
+  BOUNDARY ELEMENT: throws when a value that requires a seal is handed over
+  without one. No unsealed seal-required value crosses this boundary onto a
+  rendering surface.
 
   H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
-  References sistema#67 for .type-overline (--type-overline-* tokens).
+  Uses --type-overline-* tokens (sistema#67) for the overline label.
 
-  @example Measured only
-  <KpiRegister label="ENERGY OUTPUT" measuredValue="2.3 MW" />
+  @example A reading alone
+  <KpiRegister label="WATER LEVEL" primaryValue="+14 cm/h" />
 
-  @example With sealed projected value
+  @example Reading above a sealed forecast, why one tap away
   <KpiRegister
-    label="ENERGY OUTPUT"
-    measuredValue="2.3 MW"
-    projectedValue="4.1 MW"
-    projectedSeal={{ evidence: 'projected', stale: false }}
+    label="WATER LEVEL"
+    primaryValue="+14 cm/h"
+    secondaryValue="−18 cm"
+    secondarySeal={resolveSeal(assignment, vocabulary)}
+    secondaryWhy="derived from the 14:00–16:00 tide model run"
   />
 -->
 <script>
   import SealChip from './SealChip.svelte';
 
   /**
-   * @typedef {'measured' | 'inferred' | 'projected'} EvidenceState
-   * @typedef {{ evidence: EvidenceState; stale: boolean }} SealRef
+   * @typedef {'direct_reading' | 'model_derived' | 'future_window'} EvidenceClass
+   * @typedef {'positive' | 'info' | 'caution' | 'neutral'} SealTone
+   * @typedef {{ value: string, label: string, tone?: SealTone }} SealTerm
+   * @typedef {{ evidence: SealTerm, evidenceClass: EvidenceClass, probability?: SealTerm, stale: boolean }} ResolvedSeal
    */
 
   let {
     /** @type {string} — overline label (KPI name / dimension) */
     label,
-    /** @type {string} — the measured (authoritative) value; always required */
-    measuredValue,
-    /** @type {string | undefined} — a projected value for the same KPI */
-    projectedValue = undefined,
+    /** @type {string} — the more authoritative value; always required */
+    primaryValue,
+    /**
+     * @type {ResolvedSeal | undefined}
+     * Seal for the primary value. Omit only when the value needs none — a
+     * direct reading of a current or past window (assignSeal.sealRequired).
+     */
+    primarySeal = undefined,
+    /** @type {string | undefined} — the less authoritative value for the same KPI */
+    secondaryValue = undefined,
     /**
-     * @type {SealRef | undefined}
-     * Seal metadata for the projected value. REQUIRED when projectedValue
-     * is provided. The boundary guard throws when this is absent.
-     * Obtain from assignSeal() in @aiaiai-pt/widget-system/core.
+     * @type {ResolvedSeal | undefined}
+     * Seal for the secondary value. REQUIRED when secondaryValue is provided:
+     * a value seated in the lower register is, by construction, not a plain
+     * current reading.
      */
-    projectedSeal = undefined,
+    secondarySeal = undefined,
+    /**
+     * @type {string | undefined}
+     * The provenance one-liner behind the secondary value's seal — what makes
+     * the «why» reachable one tap from the seal.
+     */
+    secondaryWhy = undefined,
     /** @type {string} */
     class: className = '',
     ...rest
   } = $props();
 
+  /** Structural authority order — highest first. Mirrors EVIDENCE_CLASS_RANK. */
+  const RANK = {
+    direct_reading: 3,
+    model_derived: 2,
+    future_window: 1,
+  };
+
   /*
-   * BOUNDARY GUARD — the seal rule enforcement point.
-   *
-   * Runs synchronously at component initialisation. Also runs reactively
-   * via $effect so prop changes after mount are also checked.
-   *
-   * Throws unconditionally when projectedValue is provided without a seal;
-   * production surfaces must never reach this state (prd.md §5.1 #3:
-   * "the product, deterministically" assigns the seal — a missing seal
-   * means the caller skipped assignSeal, which is the defect).
+   * BOUNDARY GUARDS. Both run synchronously at initialisation and again
+   * reactively, so a prop change after mount cannot smuggle a violation in.
    */
-  if (projectedValue !== undefined && projectedSeal == null) {
-    throw new Error(
-      '[KpiRegister] A projected value must carry a seal. ' +
-        'Provide the `projectedSeal` prop (result of assignSeal()). ' +
-        'An unsealed projected value may not cross this boundary.',
-    );
-  }
-
-  $effect(() => {
-    if (projectedValue !== undefined && projectedSeal == null) {
+  const assertRegisters = (
+    /** @type {string | undefined} */ secondary,
+    /** @type {ResolvedSeal | undefined} */ secSeal,
+    /** @type {ResolvedSeal | undefined} */ primSeal,
+  ) => {
+    // 1. No unsealed value in the lower register.
+    if (secondary !== undefined && secSeal == null) {
       throw new Error(
-        '[KpiRegister] A projected value must carry a seal. ' +
-          'Provide the `projectedSeal` prop (result of assignSeal()). ' +
-          'An unsealed projected value may not cross this boundary.',
+        '[KpiRegister] The secondary value must carry a seal. Pass ' +
+          '`secondarySeal` (from resolveSeal()). An unsealed value may not ' +
+          'cross this boundary onto a rendering surface.',
       );
     }
-  });
+    // 2. The lower register may never out-rank the upper one.
+    if (secSeal != null && primSeal != null) {
+      const secRank = RANK[secSeal.evidenceClass];
+      const primRank = RANK[primSeal.evidenceClass];
+      if (secRank > primRank) {
+        throw new Error(
+          `[KpiRegister] The secondary value's evidence class ` +
+            `"${secSeal.evidenceClass}" out-ranks the primary's ` +
+            `"${primSeal.evidenceClass}". The more authoritative value takes ` +
+            'the upper register — swap them.',
+        );
+      }
+    }
+  };
+
+  assertRegisters(secondaryValue, secondarySeal, primarySeal);
+  $effect(() => assertRegisters(secondaryValue, secondarySeal, primarySeal));
 </script>
 
 <div class="kpi-register {className}" {...rest}>
-  <!--
-    Overline label — micro-heading above the value.
-    Uses --type-overline-* tokens directly (sistema#67 .type-overline utility).
-  -->
+  <!-- Overline label — micro-heading above the value (sistema#67 tokens). -->
   <span class="kpi-register-label">{label}</span>
 
   <!--
-    Measured value: the authoritative reading.
-    Display-scale type — visually out-ranks the projected row.
+    The primary register: display-scale type, first in the DOM, and therefore
+    first in reading order. Out-ranks the secondary on all three axes.
   -->
-  <div class="kpi-register-measured">
-    <span class="kpi-register-measured-value">{measuredValue}</span>
+  <div class="kpi-register-primary">
+    {#if primarySeal != null}
+      <SealChip
+        class="kpi-register-primary-value"
+        value={primaryValue}
+        evidence={primarySeal.evidence}
+        probability={primarySeal.probability}
+        stale={primarySeal.stale}
+      />
+    {:else}
+      <span class="kpi-register-primary-value">{primaryValue}</span>
+    {/if}
   </div>
 
   <!--
-    Projected row: subordinate to the measured value (smaller type, lower position).
-    Only rendered when a sealed projected value is provided.
-    projectedSeal is guaranteed non-null here (boundary guard above).
+    The secondary register: body-scale, lower position, read last.
+    secondarySeal is guaranteed non-null here by the boundary guard.
   -->
-  {#if projectedValue !== undefined && projectedSeal != null}
-    <div class="kpi-register-projected">
+  {#if secondaryValue !== undefined && secondarySeal != null}
+    <div class="kpi-register-secondary">
       <SealChip
-        value={projectedValue}
-        evidence={projectedSeal.evidence}
-        stale={projectedSeal.stale}
+        value={secondaryValue}
+        evidence={secondarySeal.evidence}
+        probability={secondarySeal.probability}
+        stale={secondarySeal.stale}
+        why={secondaryWhy}
       />
     </div>
   {/if}
@@ -126,8 +168,8 @@
 
   /*
    * Overline label — consumes --type-overline-* tokens (sistema#67).
-   * Equivalent to the .type-overline utility class from utilities.css,
-   * declared here so the component is self-contained.
+   * Equivalent to the .type-overline utility, declared here so the component
+   * is self-contained.
    */
   .kpi-register-label {
     font-family: var(--type-overline-font);
@@ -139,8 +181,9 @@
     color: var(--stat-label-color);
   }
 
-  /* Measured value: display scale — the dominant visual element */
-  .kpi-register-measured-value {
+  /* Primary: display scale — the dominant element. */
+  .kpi-register-primary :global(.kpi-register-primary-value),
+  .kpi-register-primary .kpi-register-primary-value {
     font-family: var(--stat-value-font);
     font-size: var(--stat-value-size);
     font-weight: var(--stat-value-weight);
@@ -149,8 +192,8 @@
     line-height: 1;
   }
 
-  /* Projected row: body-scale — subordinate to the measured value */
-  .kpi-register-projected {
+  /* Secondary: body scale — subordinate to the primary register. */
+  .kpi-register-secondary {
     display: flex;
     align-items: center;
     margin-top: var(--space-2xs);

package/components/KpiRegister.svelte.d.ts

@@ -6,41 +6,52 @@ type KpiRegister = {
 /**
  * KpiRegister
  *
- * A StatCard-variant register for KPI values where a measured reading
- * visually out-ranks a projected value (larger display text, higher position
- * in the visual hierarchy).
+ * The two-register composition for one KPI: the more authoritative value above,
+ * the less authoritative beneath. It is where "measured out-ranks projected"
+ * becomes concrete — in type SIZE, in POSITION, and in SCREEN-READER READING
+ * ORDER, all three.
  *
- * BOUNDARY ELEMENT: throws when a projected value is provided without a seal.
- * This is the enforcement point for the seal rule (prd.md §5.1): no unsealed
- * projected value may cross this boundary into the rendering surface. The throw
- * is unconditional — production code must never pass an unsealed projected value
- * here; the guard exists to catch contract violations early.
+ * The ranking is enforced STRUCTURALLY, by evidence class, not by word. A
+ * reading outranks a model output, which outranks a forecast
+ * (EVIDENCE_CLASS_RANK in @aiaiai-pt/widget-system/core). That ordering holds
+ * under every enumeration in the corpus, so this component needs no vocabulary
+ * to enforce it — and it throws if a caller tries to seat a more authoritative
+ * value in the lower register.
+ *
+ * BOUNDARY ELEMENT: throws when a value that requires a seal is handed over
+ * without one. No unsealed seal-required value crosses this boundary onto a
+ * rendering surface.
  *
  * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
- * References sistema#67 for .type-overline (--type-overline-* tokens).
+ * Uses --type-overline-* tokens (sistema#67) for the overline label.
  *
- * @example Measured only
- * <KpiRegister label="ENERGY OUTPUT" measuredValue="2.3 MW" />
+ * @example A reading alone
+ * <KpiRegister label="WATER LEVEL" primaryValue="+14 cm/h" />
  *
- * @example With sealed projected value
+ * @example Reading above a sealed forecast, why one tap away
  * <KpiRegister
- *   label="ENERGY OUTPUT"
- *   measuredValue="2.3 MW"
- *   projectedValue="4.1 MW"
- *   projectedSeal={{ evidence: 'projected', stale: false }}
+ *   label="WATER LEVEL"
+ *   primaryValue="+14 cm/h"
+ *   secondaryValue="−18 cm"
+ *   secondarySeal={resolveSeal(assignment, vocabulary)}
+ *   secondaryWhy="derived from the 14:00–16:00 tide model run"
  * />
  */
 declare const KpiRegister: import("svelte").Component<{
     label: any;
-    measuredValue: any;
-    projectedValue?: any;
-    projectedSeal?: any;
+    primaryValue: any;
+    primarySeal?: any;
+    secondaryValue?: any;
+    secondarySeal?: any;
+    secondaryWhy?: any;
     class?: string;
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
     label: any;
-    measuredValue: any;
-    projectedValue?: any;
-    projectedSeal?: any;
+    primaryValue: any;
+    primarySeal?: any;
+    secondaryValue?: any;
+    secondarySeal?: any;
+    secondaryWhy?: any;
     class?: string;
 } & Record<string, any>;

package/components/Popover.svelte

@@ -25,6 +25,8 @@
    * @typedef {'bottom-start' | 'bottom-end' | 'top-start' | 'top-end'} Placement
    */
 
+  import { calculatePopoverPosition } from './popover-position.js';
+
   let {
     /** @type {boolean} */
     open = $bindable(false),
@@ -52,6 +54,7 @@
 
   let posX = $state(0);
   let posY = $state(0);
+  let posMaxHeight = /** @type {number | undefined} */ ($state(undefined));
   let width = $state(0);
 
   function reposition() {
@@ -66,27 +69,19 @@
       width = rect.width;
     }
 
-    const isTop = placement.startsWith('top');
-    const isEnd = placement.endsWith('end');
-
-    let x = isEnd ? rect.right - (matchWidth ? rect.width : popRect.width) : rect.left;
-    let y = isTop ? rect.top - popRect.height - offset : rect.bottom + offset;
-
-    // Flip vertical if out of viewport
-    if (!isTop && y + popRect.height > viewportH) {
-      y = rect.top - popRect.height - offset;
-    } else if (isTop && y < 0) {
-      y = rect.bottom + offset;
-    }
-
-    // Clamp horizontal
-    if (x + popRect.width > viewportW) {
-      x = viewportW - popRect.width - offset;
-    }
-    if (x < 0) x = offset;
+    const { x, y, maxHeight } = calculatePopoverPosition(
+      rect,
+      { width: popRect.width, height: popRect.height },
+      viewportH,
+      viewportW,
+      placement,
+      offset,
+      matchWidth,
+    );
 
     posX = x;
     posY = y;
+    posMaxHeight = maxHeight;
   }
 
   // Position + close listeners
@@ -157,6 +152,8 @@
     style:left="{posX}px"
     style:top="{posY}px"
     style:width={matchWidth ? `${width}px` : undefined}
+    style:max-height={posMaxHeight != null ? `${posMaxHeight}px` : undefined}
+    style:overflow-y={posMaxHeight != null ? 'auto' : undefined}
     {...rest}
   >
     {#if children}{@render children()}{/if}

package/components/Popover.svelte.d.ts

@@ -1,4 +1,5 @@
 export default Popover;
+export type Placement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
 type Popover = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;

package/components/SealChip.svelte

@@ -1,70 +1,221 @@
 <!--
   @component SealChip
 
-  Renders a value paired with its evidence seal as ONE phrase.
+  The one seal renderer for every value surface — KPI registers, map badges,
+  paths-strip columns, record lines, citations, saved projections, briefs.
+  No surface renders a seal any other way.
 
-  The seal must survive quotation: an sr-only span adjacent to the value
-  carries the evidence state word so copying or citing the value also
-  carries the seal (prd.md §5.1 #5: "a citation carries the seal of the
-  value it cites").
+  THIS COMPONENT KNOWS NO SEAL WORDS. The design system owns the LAWS and a
+  presentation tone scale; it does not own the vocabulary. Terms arrive as
+  declared data — `{ value, label, tone }` resolved from ontology vocabulary
+  rows at read time — so widening an axis or re-wording a term is a declaration
+  change with zero code change and no package release.
 
-  DS-owned evidence vocabulary: measured | inferred | projected.
-  Built over --badge-* + --seal-* component tokens.
+  The laws it does enforce, all of which hold under every enumeration in the
+  corpus:
+    · two orthogonal axes, rendered as two adjacent chips, never one phrase
+    · never label-alone — a seal never appears without its evidence chip
+    · evidence alone is valid; probability alone is not
+    · the seal rides the DATUM, not the styling — it is adjacent DOM text, so
+      it survives re-render, copy, quotation and screen readers
+    · a «why» is always one tap away, keyboard-reachable
 
-  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+  Value and seal read to a screen reader as ONE stitched phrase:
+  «{value} — {evidence}[, {probability}][, stale]».
+
+  `stale` is a separate orthogonal state, never a member of either vocabulary.
 
-  @example Measured reading
-  <SealChip value="2.3 MW" evidence="measured" />
+  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
 
-  @example Projected (future window)
-  <SealChip value="4.1 MW" evidence="projected" />
+  @example A reading, using whatever terms the deployment declares
+  <SealChip value="+14 cm/h" evidence={{ value: 'measured', label: 'medido', tone: 'positive' }} />
 
-  @example Stale seal (horizon has passed)
-  <SealChip value="1.9 MW" evidence="projected" stale />
+  @example Both axes, horizon passed, why one tap away
+  <SealChip
+    value="2,1 m"
+    evidence={{ value: 'inferred', label: 'inferido', tone: 'info' }}
+    probability={{ value: 'uncertain', label: 'incerto' }}
+    stale
+    why="the 16:00 window has already passed"
+  />
 -->
 <script>
   /**
-   * @typedef {'measured' | 'inferred' | 'projected'} EvidenceState
+   * @typedef {'positive' | 'info' | 'caution' | 'neutral'} SealTone
+   * @typedef {{ value: string, label: string, tone?: SealTone }} SealTerm
    */
 
   let {
     /** @type {string} — the formatted display value */
     value,
-    /** @type {EvidenceState} — evidence state (from assignSeal) */
+    /**
+     * @type {SealTerm}
+     * The declared evidence term. Required: a seal never appears without its
+     * evidence chip. Resolve it with `resolveSeal` from
+     * `@aiaiai-pt/widget-system/core` — never construct one from a literal.
+     */
     evidence,
+    /**
+     * @type {SealTerm | undefined}
+     * The declared probability term. Orthogonal to evidence and rendered as its
+     * own adjacent chip. Optional because evidence alone is a valid seal.
+     */
+    probability = undefined,
     /** @type {boolean} — true when the validity window has passed */
     stale = false,
+    /**
+     * @type {string | undefined}
+     * The provenance one-liner behind the seal. When supplied, the chip is a
+     * real button that discloses it — the «why», one tap away.
+     */
+    why = undefined,
+    /**
+     * @type {string}
+     * Accessible name for the why trigger. Localized by the caller, since this
+     * package owns no product copy. `{term}` is replaced by the evidence label.
+     */
+    whyLabel = 'why — {term}',
+    /** @type {string} — accessible name for the disclosure's close affordance */
+    closeLabel = 'Close',
+    /** @type {string} — screen-reader word for the stale state; localized by the caller */
+    staleLabel = 'stale',
     /** @type {string} */
     class: className = '',
     ...rest
   } = $props();
 
-  const EVIDENCE_LABELS = /** @type {Record<EvidenceState, string>} */ ({
-    measured: 'measured',
-    inferred: 'inferred',
-    projected: 'projected',
-  });
+  const TONES = ['positive', 'info', 'caution', 'neutral'];
+
+  /**
+   * BOUNDARY GUARD — "never label-alone; a seal never appears without evidence
+   * chips", and "evidence alone is valid, probability alone is not".
+   *
+   * Without this, an absent term renders an empty badge and an empty sr-text:
+   * a value dressed as a sealed datum, carrying no evidence and announcing
+   * nothing to a screen reader. That failure is silent, which is exactly why
+   * it is a throw and not a fallback.
+   *
+   * The guard checks SHAPE, never membership — this component has no opinion
+   * about which words are legal, only that a term is present and renderable.
+   */
+  const assertTerm = (
+    /** @type {unknown} */ term,
+    /** @type {string} */ axis,
+  ) => {
+    const ok =
+      typeof term === 'object' &&
+      term !== null &&
+      typeof (/** @type {SealTerm} */ (term).label) === 'string' &&
+      /** @type {SealTerm} */ (term).label.trim() !== '';
+    if (!ok) {
+      throw new Error(
+        `[SealChip] The ${axis} axis needs a declared term ` +
+          '{ value, label, tone? } with a non-empty label. Received ' +
+          `${JSON.stringify(term)}. Resolve it from the declared vocabulary ` +
+          'with resolveSeal(); this component enumerates no seal words.',
+      );
+    }
+    const tone = /** @type {SealTerm} */ (term).tone;
+    if (tone !== undefined && !TONES.includes(tone)) {
+      throw new Error(
+        `[SealChip] Unknown tone ${JSON.stringify(tone)} on the ${axis} axis. ` +
+          `The design system's tone scale is ${TONES.join(' | ')}.`,
+      );
+    }
+  };
+
+  const assertSeal = (/** @type {unknown} */ ev, /** @type {unknown} */ prob) => {
+    // Evidence first: probability-alone must fail as a MISSING EVIDENCE error,
+    // because that is the law it breaks.
+    assertTerm(ev, 'evidence');
+    if (prob !== undefined) assertTerm(prob, 'probability');
+  };
+
+  assertSeal(evidence, probability);
+  $effect(() => assertSeal(evidence, probability));
+
+  const evidenceTone = $derived(evidence?.tone ?? 'neutral');
+  const probabilityTone = $derived(probability?.tone ?? 'neutral');
+
+  /**
+   * The stitched phrase AT reads and a citation carries:
+   * «{value} — {evidence}[, {probability}][, stale]».
+   */
+  const srPhrase = $derived(
+    [
+      `${value} — ${evidence.label}`,
+      probability?.label,
+      stale ? staleLabel : undefined,
+    ]
+      .filter(Boolean)
+      .join(', '),
+  );
+
+  const whyTriggerLabel = $derived(whyLabel.replace('{term}', evidence.label));
+
+  /** Disclosure state lives here, never in a DOM attribute. */
+  let open = $state(false);
+  /** @type {HTMLButtonElement | undefined} */
+  let trigger = $state();
 
-  const evidenceLabel = $derived(EVIDENCE_LABELS[evidence] ?? evidence);
+  const panelId = $props.id();
 
-  /** Label as spoken by AT and included in citations. */
-  const srLabel = $derived(stale ? `${evidenceLabel} (stale)` : evidenceLabel);
+  const closeWhy = () => {
+    open = false;
+    trigger?.focus();
+  };
+
+  /** Esc anywhere inside the open disclosure closes it (cascade slot 2). */
+  const onDocumentKeydown = (/** @type {KeyboardEvent} */ event) => {
+    if (event.key === 'Escape' && open) closeWhy();
+  };
 </script>
 
+<svelte:document onkeydown={onDocumentKeydown} />
+
+{#snippet chips()}
+  <span class="seal-chip-badge seal-tone-{evidenceTone}" aria-hidden="true"
+    >{evidence.label}{stale ? ` (${staleLabel})` : ''}</span
+  >{#if probability}<span
+      class="seal-chip-probability seal-tone-{probabilityTone}"
+      aria-hidden="true">{probability.label}</span
+    >{/if}
+{/snippet}
+
 <!--
-  The chip is one inline phrase. Structure:
-    [value text]
-    [visual badge — aria-hidden, not read by AT]
-    [sr-only span — read by AT; position:absolute but in DOM so text
-     travels with the value when the surrounding content is copied]
+  One inline phrase. The visible value and chips are aria-hidden so the
+  stitched sr-text is the single thing announced — nothing reads twice.
+  The sr-text follows the value in DOM order, so a sweep or a copy captures
+  «value seal» in that order.
 -->
 <span
-  class="seal-chip seal-chip-{evidence} {stale ? 'seal-chip-stale' : ''} {className}"
+  class="seal-chip {stale ? 'seal-chip-stale' : ''} {className}"
+  data-evidence={evidence.value}
   {...rest}
 >
-  <span class="seal-chip-value">{value}</span><!--
-  --><span class="seal-chip-badge" aria-hidden="true">{evidenceLabel}{stale ? ' (stale)' : ''}</span><!--
-  --><span class="seal-chip-sr-text">&thinsp;{srLabel}</span>
+  <span class="seal-chip-value" aria-hidden="true">{value}</span><!--
+  -->{#if why}<button
+      type="button"
+      class="seal-chip-why-trigger"
+      aria-expanded={open}
+      aria-controls={panelId}
+      aria-label={whyTriggerLabel}
+      bind:this={trigger}
+      onclick={() => (open = !open)}>{@render chips()}</button
+    >{:else}{@render chips()}{/if}<!--
+  --><span class="seal-chip-sr-text">&thinsp;{srPhrase}</span>
+
+  {#if why && open}
+    <span id={panelId} class="seal-chip-why-panel">
+      <span class="seal-chip-why-text">{why}</span>
+      <button
+        type="button"
+        class="seal-chip-why-close"
+        aria-label={closeLabel}
+        onclick={closeWhy}>×</button
+      >
+    </span>
+  {/if}
 </span>
 
 <style>
@@ -75,13 +226,11 @@
     position: relative;
   }
 
-  /* Value text: no override — reads as its context's surrounding type */
-  .seal-chip-value {
-    /* intentionally empty */
-  }
+  /* Value text carries no override — it reads as its surrounding type. */
 
-  /* Visual evidence badge — seen by sighted users; hidden from AT */
-  .seal-chip-badge {
+  /* Both axes share one chip shape; only the tone differs. */
+  .seal-chip-badge,
+  .seal-chip-probability {
     display: inline-flex;
     align-items: center;
     font-family: var(--badge-font);
@@ -93,32 +242,106 @@
     line-height: 1;
   }
 
-  /* Evidence-state colours via --seal-* component tokens */
-  .seal-chip-measured .seal-chip-badge {
-    color: var(--seal-measured-text);
-    background: var(--seal-measured-bg);
+  /* The second axis is always its own element beside the first, so the two
+     never merge into one phrase. */
+  .seal-chip-probability {
+    margin-left: var(--space-2xs);
   }
 
-  .seal-chip-inferred .seal-chip-badge {
-    color: var(--seal-inferred-text);
-    background: var(--seal-inferred-bg);
+  /*
+   * TONES — the presentation scale the design system owns. Which declared term
+   * wears which tone is data, declared beside the word and never inferred from
+   * it, so these rules carry no vocabulary.
+   */
+  .seal-tone-positive {
+    color: var(--seal-positive-text);
+    background: var(--seal-positive-bg);
   }
 
-  .seal-chip-projected .seal-chip-badge {
-    color: var(--seal-projected-text);
-    background: var(--seal-projected-bg);
+  .seal-tone-info {
+    color: var(--seal-info-text);
+    background: var(--seal-info-bg);
   }
 
-  /* Stale modifier: muted on all evidence states */
+  .seal-tone-caution {
+    color: var(--seal-caution-text);
+    background: var(--seal-caution-bg);
+  }
+
+  .seal-tone-neutral {
+    color: var(--badge-neutral-text);
+    background: var(--badge-neutral-bg);
+  }
+
+  /* Stale is an orthogonal state, not a vocabulary member: it mutes whatever
+     tone the evidence term carries. The word carries the meaning; the wash is
+     redundant emphasis. */
   .seal-chip-stale .seal-chip-badge {
     color: var(--seal-stale-text);
     background: var(--seal-stale-bg);
   }
 
+  /*
+   * The why trigger is a real button wrapping the chips — the whole seal is
+   * the affordance, so the «why» is one tap away from the seal itself.
+   */
+  .seal-chip-why-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2xs);
+    padding: 0;
+    border: none;
+    background: none;
+    font: inherit;
+    color: inherit;
+    cursor: pointer;
+  }
+
+  .seal-chip-why-trigger:focus-visible,
+  .seal-chip-why-close:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+    border-radius: var(--radius-sm);
+  }
+
+  /* The provenance one-liner. Plain text plus a visible close (Esc/X parity). */
+  .seal-chip-why-panel {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    z-index: 1;
+    display: inline-flex;
+    align-items: flex-start;
+    gap: var(--space-xs);
+    margin-top: var(--space-2xs);
+    padding: var(--space-xs) var(--space-sm);
+    max-width: 32ch;
+    border: var(--elevation-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface-secondary);
+    color: var(--color-text-secondary);
+    font-family: var(--type-caption-font);
+    font-size: var(--type-caption-size);
+    font-weight: var(--type-caption-weight);
+    line-height: var(--type-caption-leading);
+    letter-spacing: var(--type-caption-tracking);
+    text-align: left;
+  }
+
+  .seal-chip-why-close {
+    padding: 0;
+    border: none;
+    background: none;
+    font: inherit;
+    line-height: 1;
+    color: inherit;
+    cursor: pointer;
+  }
+
   /*
    * sr-only — visually hidden but present in the DOM so the text travels
-   * with the value when content is copied or cited (prd.md §5.1 #5).
-   * clip-path: inset(50%) is the modern replacement for deprecated clip: rect().
+   * with the value when content is copied or cited: a citation carries the
+   * seal of the value it cites.
    */
   .seal-chip-sr-text {
     position: absolute;

package/components/SealChip.svelte.d.ts

@@ -6,36 +6,63 @@ type SealChip = {
 /**
  * SealChip
  *
- * Renders a value paired with its evidence seal as ONE phrase.
+ * The one seal renderer for every value surface — KPI registers, map badges,
+ * paths-strip columns, record lines, citations, saved projections, briefs.
+ * No surface renders a seal any other way.
  *
- * The seal must survive quotation: an sr-only span adjacent to the value
- * carries the evidence state word so copying or citing the value also
- * carries the seal (prd.md §5.1 #5: "a citation carries the seal of the
- * value it cites").
+ * THIS COMPONENT KNOWS NO SEAL WORDS. The design system owns the LAWS and a
+ * presentation tone scale; it does not own the vocabulary. Terms arrive as
+ * declared data — `{ value, label, tone }` resolved from ontology vocabulary
+ * rows at read time — so widening an axis or re-wording a term is a declaration
+ * change with zero code change and no package release.
  *
- * DS-owned evidence vocabulary: measured | inferred | projected.
- * Built over --badge-* + --seal-* component tokens.
+ * The laws it does enforce, all of which hold under every enumeration in the
+ * corpus:
+ *   · two orthogonal axes, rendered as two adjacent chips, never one phrase
+ *   · never label-alone — a seal never appears without its evidence chip
+ *   · evidence alone is valid; probability alone is not
+ *   · the seal rides the DATUM, not the styling — it is adjacent DOM text, so
+ *     it survives re-render, copy, quotation and screen readers
+ *   · a «why» is always one tap away, keyboard-reachable
  *
- * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+ * Value and seal read to a screen reader as ONE stitched phrase:
+ * «{value} — {evidence}[, {probability}][, stale]».
+ *
+ * `stale` is a separate orthogonal state, never a member of either vocabulary.
  *
- * @example Measured reading
- * <SealChip value="2.3 MW" evidence="measured" />
+ * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
  *
- * @example Projected (future window)
- * <SealChip value="4.1 MW" evidence="projected" />
+ * @example A reading, using whatever terms the deployment declares
+ * <SealChip value="+14 cm/h" evidence={{ value: 'measured', label: 'medido', tone: 'positive' }} />
  *
- * @example Stale seal (horizon has passed)
- * <SealChip value="1.9 MW" evidence="projected" stale />
+ * @example Both axes, horizon passed, why one tap away
+ * <SealChip
+ *   value="2,1 m"
+ *   evidence={{ value: 'inferred', label: 'inferido', tone: 'info' }}
+ *   probability={{ value: 'uncertain', label: 'incerto' }}
+ *   stale
+ *   why="the 16:00 window has already passed"
+ * />
  */
 declare const SealChip: import("svelte").Component<{
     value: any;
     evidence: any;
+    probability?: any;
     stale?: boolean;
+    why?: any;
+    whyLabel?: string;
+    closeLabel?: string;
+    staleLabel?: string;
     class?: string;
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
     value: any;
     evidence: any;
+    probability?: any;
     stale?: boolean;
+    why?: any;
+    whyLabel?: string;
+    closeLabel?: string;
+    staleLabel?: string;
     class?: string;
 } & Record<string, any>;

package/components/index.js

@@ -16,7 +16,8 @@ export { default as Skeleton } from "./Skeleton.svelte";
 export { default as KeyValue } from "./KeyValue.svelte";
 
 // Evidence seal (H1 Slice 2 — westeuropeco/atelier-urban-workspace#57)
-// DS-owned evidence vocabulary: measured | inferred | projected
+// These own the LAWS and a presentation tone scale. They own NO seal
+// vocabulary: terms arrive as declared data resolved by resolveSeal().
 export { default as SealChip } from "./SealChip.svelte";
 export { default as KpiRegister } from "./KpiRegister.svelte";
 export { default as CaminhoStateChip } from "./CaminhoStateChip.svelte";

package/components/popover-position.d.ts

@@ -0,0 +1,35 @@
+/**
+ * calculatePopoverPosition — pure positioning algorithm for Popover.svelte.
+ *
+ * Returns the fixed-position coordinate (x, y) for the popover, plus an
+ * optional maxHeight cap (in px) when neither the preferred nor the
+ * opposite side fits and we must scroll the popover content in-place.
+ *
+ * Preference order:
+ *   1. Preferred side (from `placement`) if it fits.
+ *   2. Opposite side if that fits.
+ *   3. Side with more room — capped to that room, overflow-y scrollable.
+ *
+ * @param {{ top: number, bottom: number, left: number, right: number, width: number }} anchorRect
+ * @param {{ width: number, height: number }} popRect
+ * @param {number} viewportH
+ * @param {number} viewportW
+ * @param {string} placement  — 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
+ * @param {number} offset  — gap between anchor and popover (px)
+ * @param {boolean} [matchWidth]
+ * @returns {{ x: number, y: number, maxHeight: number | undefined }}
+ */
+export function calculatePopoverPosition(anchorRect: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+}, popRect: {
+    width: number;
+    height: number;
+}, viewportH: number, viewportW: number, placement: string, offset: number, matchWidth?: boolean): {
+    x: number;
+    y: number;
+    maxHeight: number | undefined;
+};

package/components/popover-position.js

@@ -0,0 +1,93 @@
+/**
+ * calculatePopoverPosition — pure positioning algorithm for Popover.svelte.
+ *
+ * Returns the fixed-position coordinate (x, y) for the popover, plus an
+ * optional maxHeight cap (in px) when neither the preferred nor the
+ * opposite side fits and we must scroll the popover content in-place.
+ *
+ * Preference order:
+ *   1. Preferred side (from `placement`) if it fits.
+ *   2. Opposite side if that fits.
+ *   3. Side with more room — capped to that room, overflow-y scrollable.
+ *
+ * @param {{ top: number, bottom: number, left: number, right: number, width: number }} anchorRect
+ * @param {{ width: number, height: number }} popRect
+ * @param {number} viewportH
+ * @param {number} viewportW
+ * @param {string} placement  — 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
+ * @param {number} offset  — gap between anchor and popover (px)
+ * @param {boolean} [matchWidth]
+ * @returns {{ x: number, y: number, maxHeight: number | undefined }}
+ */
+export function calculatePopoverPosition(
+  anchorRect,
+  popRect,
+  viewportH,
+  viewportW,
+  placement,
+  offset,
+  matchWidth = false,
+) {
+  const isTop = placement.startsWith("top");
+  const isEnd = placement.endsWith("end");
+
+  // Horizontal: preserve matchWidth behaviour for end-aligned placement
+  let x = isEnd
+    ? anchorRect.right - (matchWidth ? anchorRect.width : popRect.width)
+    : anchorRect.left;
+
+  // Available room on each side (gap to viewport edge after the offset)
+  const roomAbove = anchorRect.top - offset;
+  const roomBelow = viewportH - anchorRect.bottom - offset;
+
+  const fitsAbove = popRect.height <= roomAbove;
+  const fitsBelow = popRect.height <= roomBelow;
+
+  let y;
+  let maxHeight = undefined;
+
+  if (isTop) {
+    if (fitsAbove) {
+      // Preferred side fits
+      y = anchorRect.top - popRect.height - offset;
+    } else if (fitsBelow) {
+      // Flip to below
+      y = anchorRect.bottom + offset;
+    } else {
+      // Neither fits: open on the side with more room and cap
+      if (roomAbove >= roomBelow) {
+        maxHeight = roomAbove;
+        y = anchorRect.top - maxHeight - offset; // = anchorRect.top - (anchorRect.top - offset) - offset = 0
+      } else {
+        y = anchorRect.bottom + offset;
+        maxHeight = roomBelow;
+      }
+    }
+  } else {
+    // Bottom placement
+    if (fitsBelow) {
+      // Preferred side fits
+      y = anchorRect.bottom + offset;
+    } else if (fitsAbove) {
+      // Flip to above
+      y = anchorRect.top - popRect.height - offset;
+    } else {
+      // Neither fits: open on the side with more room and cap
+      if (roomBelow >= roomAbove) {
+        y = anchorRect.bottom + offset;
+        maxHeight = roomBelow;
+      } else {
+        maxHeight = roomAbove;
+        y = anchorRect.top - maxHeight - offset; // = 0
+      }
+    }
+  }
+
+  // Clamp horizontal
+  if (x + popRect.width > viewportW) {
+    x = viewportW - popRect.width - offset;
+  }
+  if (x < 0) x = offset;
+
+  return { x, y, maxHeight };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.50.0",
+  "version": "0.51.1",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
     "packages/widget-system"
   ],
   "scripts": {
-    "build:types": "rm -f components/*.d.ts components/renderer/*.d.ts && svelte-package --input . --output dist && cp dist/components/*.d.ts components/ && cp dist/components/renderer/*.d.ts components/renderer/ && rm -rf dist",
+    "build:types": "rm -rf node_modules/@aiaiai-pt/design-system packages/widget-system/node_modules/@aiaiai-pt/design-system && rm -f components/*.d.ts components/renderer/*.d.ts && svelte-package --input . --output dist && cp dist/components/*.d.ts components/ && cp dist/components/renderer/*.d.ts components/renderer/ && rm -rf dist",
     "test": "vitest run",
     "prepublishOnly": "npm run build:types"
   },

package/tokens/base.css

@@ -96,6 +96,10 @@
   --raw-font-size-18: 1.125rem;
   --raw-font-size-24: 1.5rem;
   --raw-font-size-36: 2.25rem;
+  /* Marketing steps. Application surfaces stop at 36; these exist for public
+     pages where the headline is the message, not a page title. */
+  --raw-font-size-48: 3rem;
+  --raw-font-size-64: 4rem;
 
   /* ─── Typography: Font Weights ─── */
   --raw-font-weight-regular: 400;

package/tokens/components.css

@@ -248,17 +248,23 @@
   --badge-neutral-bg: var(--color-surface-tertiary);
   --badge-neutral-text: var(--color-text-secondary);
 
-  /* Evidence Seal — DS-owned vocabulary: measured | inferred | projected
+  /* Evidence Seal — TONES, not seal words.
      H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+
+     The design system owns the presentation scale (positive / info / caution /
+     stale); it does NOT own the seal vocabulary. Which word wears which tone is
+     declared data resolved outside this package, so widening or re-wording an
+     axis is a declaration change and never a DS release.
+
      Defaults resolve via semantic color tokens so they work for every theme.
      UBP dark scheme overrides below in tokens/themes/ubp.css to maintain
      WCAG AA on the cool-steel dark surface (#0b182a). */
-  --seal-measured-text: var(--color-success);
-  --seal-measured-bg: var(--color-success-subtle);
-  --seal-inferred-text: var(--color-info);
-  --seal-inferred-bg: var(--color-info-subtle);
-  --seal-projected-text: var(--color-warning);
-  --seal-projected-bg: var(--color-warning-subtle);
+  --seal-positive-text: var(--color-success);
+  --seal-positive-bg: var(--color-success-subtle);
+  --seal-info-text: var(--color-info);
+  --seal-info-bg: var(--color-info-subtle);
+  --seal-caution-text: var(--color-warning);
+  --seal-caution-bg: var(--color-warning-subtle);
   /* stale modifier: muted regardless of base evidence state */
   --seal-stale-text: var(--color-text-muted);
   --seal-stale-bg: var(--color-surface-secondary);

package/tokens/semantic.css

@@ -63,7 +63,21 @@
   --font-sans: var(--raw-font-sans);
   --font-mono: var(--raw-font-mono);
 
-  /* Type scale — categorical */
+  /* Type scale — categorical.
+     display-2xl / display-xl are MARKETING roles: public pages where the
+     headline is the message. Application surfaces start at `display`. */
+  --type-display-2xl-size: var(--raw-font-size-64);
+  --type-display-2xl-weight: var(--raw-font-weight-semibold);
+  --type-display-2xl-leading: var(--raw-line-height-tight);
+  --type-display-2xl-tracking: var(--raw-tracking-tight);
+  --type-display-2xl-font: var(--font-sans);
+
+  --type-display-xl-size: var(--raw-font-size-48);
+  --type-display-xl-weight: var(--raw-font-weight-semibold);
+  --type-display-xl-leading: var(--raw-line-height-tight);
+  --type-display-xl-tracking: var(--raw-tracking-tight);
+  --type-display-xl-font: var(--font-sans);
+
   --type-display-size: var(--raw-font-size-36);
   --type-display-weight: var(--raw-font-weight-semibold);
   --type-display-leading: var(--raw-line-height-tight);

package/tokens/themes/ubp.css

@@ -149,12 +149,12 @@
      Contrast on subtle backgrounds (AA = 4.5:1 for small badge text):
        measured  #256f20 (green-700) on #f0fdf4 (success-subtle): ~5.46:1 [AA]
        projected #9e6308 (amber-700) on #fffbeb (warning-subtle): ~4.79:1 [AA]
-     --seal-inferred-text inherits --color-info (#2e63a3): 5.66:1 on
+     --seal-info-text inherits --color-info (#2e63a3): 5.66:1 on
      info-subtle (#f0f5fa) — no override needed.
      --seal-stale-text inherits --color-text-muted (≥3.0:1 non-essential).
      ═══════════════════════════════════════════════════════════════ */
-  --seal-measured-text: #256f20; /* green-700 → 5.46:1 on success-subtle [AA] */
-  --seal-projected-text: #9e6308; /* amber-700 → 4.79:1 on warning-subtle [AA] */
+  --seal-positive-text: #256f20; /* green-700 → 5.46:1 on success-subtle [AA] */
+  --seal-caution-text: #9e6308; /* amber-700 → 4.79:1 on warning-subtle [AA] */
 }
 
 /* Desktop density: compact button heights for toolbar/sidebar layouts.
@@ -254,12 +254,12 @@
        projected #fbbf24 (amber-400)  lum ≈ 0.598 → ~11.14:1 [AAA]
        stale     inherits --seal-stale-text: var(--color-text-muted) = #60758a (3.74:1)
      ═══════════════════════════════════════════════════════════════ */
-  --seal-measured-text: #4ade80;
-  --seal-measured-bg: color-mix(in srgb, #4ade80 12%, #0b182a);
-  --seal-inferred-text: #60a5fa;
-  --seal-inferred-bg: color-mix(in srgb, #60a5fa 12%, #0b182a);
-  --seal-projected-text: #fbbf24;
-  --seal-projected-bg: color-mix(in srgb, #fbbf24 12%, #0b182a);
+  --seal-positive-text: #4ade80;
+  --seal-positive-bg: color-mix(in srgb, #4ade80 12%, #0b182a);
+  --seal-info-text: #60a5fa;
+  --seal-info-bg: color-mix(in srgb, #60a5fa 12%, #0b182a);
+  --seal-caution-text: #fbbf24;
+  --seal-caution-bg: color-mix(in srgb, #fbbf24 12%, #0b182a);
   /* stale: inherits --seal-stale-text (--color-text-muted = #60758a, 3.74:1 non-essential)
             and --seal-stale-bg (--color-surface-secondary = #1a2a3a) */
 }

package/tokens/utilities.css

@@ -984,6 +984,36 @@
    Instrument Sans is the quiet backdrop for prose.
    ═══════════════════════════════════════════════ */
 
+/* Marketing roles — public pages where the headline is the message.
+   Application surfaces start at .type-display. Both step down one role at
+   narrow viewports, which holds a headline near its intended line count
+   rather than doubling it. */
+.type-display-2xl {
+  font-family: var(--type-display-2xl-font);
+  font-size: var(--type-display-2xl-size);
+  font-weight: var(--type-display-2xl-weight);
+  line-height: var(--type-display-2xl-leading);
+  letter-spacing: var(--type-display-2xl-tracking);
+}
+
+.type-display-xl {
+  font-family: var(--type-display-xl-font);
+  font-size: var(--type-display-xl-size);
+  font-weight: var(--type-display-xl-weight);
+  line-height: var(--type-display-xl-leading);
+  letter-spacing: var(--type-display-xl-tracking);
+}
+
+@media (max-width: 900px) {
+  .type-display-2xl {
+    font-size: var(--type-display-xl-size);
+  }
+
+  .type-display-xl {
+    font-size: var(--type-display-size);
+  }
+}
+
 .type-display {
   font-family: var(--type-display-font);
   font-size: var(--type-display-size);