@aiaiai-pt/design-system 0.49.0 → 0.51.0

package/components/CaminhoStateChip.svelte

@@ -0,0 +1,89 @@
+<!--
+  @component CaminhoStateChip
+
+  A Badge-variant chip rendering the four verification states as WORDS.
+
+  The four-state machine (H1 Slice 6 / verification surface):
+    to-verify    — horizon not yet reached; awaiting observation
+    verified     — observed and confirmed at the horizon
+    not-verified — horizon passed; observation explicitly absent
+    not-done     — path discarded; verification not applicable
+
+  States are rendered as English words, not icons or abbreviations.
+  Screen readers announce the full word; no icon-only encoding.
+
+  Built over --badge-* component tokens. English-only canonical state names
+  (shared-by-default doctrine — no urban vocabulary here).
+
+  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+
+  @example All four states
+  <CaminhoStateChip state="to-verify" />
+  <CaminhoStateChip state="verified" />
+  <CaminhoStateChip state="not-verified" />
+  <CaminhoStateChip state="not-done" />
+-->
+<script>
+  /**
+   * @typedef {'to-verify' | 'verified' | 'not-verified' | 'not-done'} CaminhoState
+   */
+
+  let {
+    /** @type {CaminhoState} */
+    state,
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  /** @type {Record<CaminhoState, string>} */
+  const STATE_LABELS = {
+    'to-verify':    'To verify',
+    'verified':     'Verified',
+    'not-verified': 'Not verified',
+    'not-done':     'Not done',
+  };
+
+  const label = $derived(STATE_LABELS[state] ?? state);
+</script>
+
+<span class="caminho-chip caminho-chip-{state} {className}" {...rest}>
+  {label}
+</span>
+
+<style>
+  .caminho-chip {
+    display: inline-flex;
+    align-items: center;
+    font-family: var(--badge-font);
+    font-size: var(--badge-size);
+    letter-spacing: var(--badge-tracking);
+    border-radius: var(--badge-radius);
+    padding: var(--badge-padding-y) var(--badge-padding-x);
+    white-space: nowrap;
+  }
+
+  /* to-verify: informational — horizon pending */
+  .caminho-chip-to-verify {
+    background: var(--color-info-subtle);
+    color: var(--color-info);
+  }
+
+  /* verified: success — observation confirmed */
+  .caminho-chip-verified {
+    background: var(--color-success-subtle);
+    color: var(--color-success);
+  }
+
+  /* not-verified: destructive — horizon passed, no observation */
+  .caminho-chip-not-verified {
+    background: var(--color-destructive-subtle);
+    color: var(--color-destructive);
+  }
+
+  /* not-done: neutral — path discarded, verification not applicable */
+  .caminho-chip-not-done {
+    background: var(--badge-neutral-bg);
+    color: var(--badge-neutral-text);
+  }
+</style>

package/components/CaminhoStateChip.svelte.d.ts

@@ -0,0 +1,38 @@
+export default CaminhoStateChip;
+type CaminhoStateChip = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * CaminhoStateChip
+ *
+ * A Badge-variant chip rendering the four verification states as WORDS.
+ *
+ * The four-state machine (H1 Slice 6 / verification surface):
+ *   to-verify    — horizon not yet reached; awaiting observation
+ *   verified     — observed and confirmed at the horizon
+ *   not-verified — horizon passed; observation explicitly absent
+ *   not-done     — path discarded; verification not applicable
+ *
+ * States are rendered as English words, not icons or abbreviations.
+ * Screen readers announce the full word; no icon-only encoding.
+ *
+ * Built over --badge-* component tokens. English-only canonical state names
+ * (shared-by-default doctrine — no urban vocabulary here).
+ *
+ * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+ *
+ * @example All four states
+ * <CaminhoStateChip state="to-verify" />
+ * <CaminhoStateChip state="verified" />
+ * <CaminhoStateChip state="not-verified" />
+ * <CaminhoStateChip state="not-done" />
+ */
+declare const CaminhoStateChip: import("svelte").Component<{
+    state: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    state: any;
+    class?: string;
+} & Record<string, any>;

package/components/KpiRegister.svelte

@@ -0,0 +1,201 @@
+<!--
+  @component KpiRegister
+
+  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.
+  Uses --type-overline-* tokens (sistema#67) for the overline label.
+
+  @example A reading alone
+  <KpiRegister label="WATER LEVEL" primaryValue="+14 cm/h" />
+
+  @example Reading above a sealed forecast, why one tap away
+  <KpiRegister
+    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 {'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 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 {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.
+     */
+    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 GUARDS. Both run synchronously at initialisation and again
+   * reactively, so a prop change after mount cannot smuggle a violation in.
+   */
+  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] 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 (sistema#67 tokens). -->
+  <span class="kpi-register-label">{label}</span>
+
+  <!--
+    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-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>
+
+  <!--
+    The secondary register: body-scale, lower position, read last.
+    secondarySeal is guaranteed non-null here by the boundary guard.
+  -->
+  {#if secondaryValue !== undefined && secondarySeal != null}
+    <div class="kpi-register-secondary">
+      <SealChip
+        value={secondaryValue}
+        evidence={secondarySeal.evidence}
+        probability={secondarySeal.probability}
+        stale={secondarySeal.stale}
+        why={secondaryWhy}
+      />
+    </div>
+  {/if}
+</div>
+
+<style>
+  .kpi-register {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+    padding: var(--stat-padding);
+    border: var(--stat-border);
+    border-radius: var(--stat-radius);
+    background: var(--stat-bg);
+  }
+
+  /*
+   * Overline label — consumes --type-overline-* tokens (sistema#67).
+   * Equivalent to the .type-overline utility, declared here so the component
+   * is self-contained.
+   */
+  .kpi-register-label {
+    font-family: var(--type-overline-font);
+    font-size: var(--type-overline-size);
+    font-weight: var(--type-overline-weight);
+    line-height: var(--type-overline-leading);
+    letter-spacing: var(--type-overline-tracking);
+    text-transform: uppercase;
+    color: var(--stat-label-color);
+  }
+
+  /* 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);
+    letter-spacing: var(--stat-value-tracking);
+    color: var(--color-text);
+    line-height: 1;
+  }
+
+  /* Secondary: body scale — subordinate to the primary register. */
+  .kpi-register-secondary {
+    display: flex;
+    align-items: center;
+    margin-top: var(--space-2xs);
+  }
+</style>

package/components/KpiRegister.svelte.d.ts

@@ -0,0 +1,57 @@
+export default KpiRegister;
+type KpiRegister = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * KpiRegister
+ *
+ * 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.
+ * Uses --type-overline-* tokens (sistema#67) for the overline label.
+ *
+ * @example A reading alone
+ * <KpiRegister label="WATER LEVEL" primaryValue="+14 cm/h" />
+ *
+ * @example Reading above a sealed forecast, why one tap away
+ * <KpiRegister
+ *   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;
+    primaryValue: any;
+    primarySeal?: any;
+    secondaryValue?: any;
+    secondarySeal?: any;
+    secondaryWhy?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label: any;
+    primaryValue: any;
+    primarySeal?: any;
+    secondaryValue?: any;
+    secondarySeal?: any;
+    secondaryWhy?: any;
+    class?: string;
+} & Record<string, any>;

package/components/SealChip.svelte

@@ -0,0 +1,356 @@
+<!--
+  @component SealChip
+
+  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.
+
+  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.
+
+  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
+
+  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.
+
+  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+
+  @example A reading, using whatever terms the deployment declares
+  <SealChip value="+14 cm/h" evidence={{ value: 'measured', label: 'medido', tone: 'positive' }} />
+
+  @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 {'positive' | 'info' | 'caution' | 'neutral'} SealTone
+   * @typedef {{ value: string, label: string, tone?: SealTone }} SealTerm
+   */
+
+  let {
+    /** @type {string} — the formatted display value */
+    value,
+    /**
+     * @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 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 panelId = $props.id();
+
+  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}
+
+<!--
+  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 {stale ? 'seal-chip-stale' : ''} {className}"
+  data-evidence={evidence.value}
+  {...rest}
+>
+  <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>
+  .seal-chip {
+    display: inline-flex;
+    align-items: baseline;
+    gap: var(--space-xs);
+    position: relative;
+  }
+
+  /* Value text carries no override — it reads as its surrounding type. */
+
+  /* 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);
+    font-size: var(--badge-size);
+    letter-spacing: var(--badge-tracking);
+    border-radius: var(--badge-radius);
+    padding: var(--badge-padding-y) var(--badge-padding-x);
+    white-space: nowrap;
+    line-height: 1;
+  }
+
+  /* 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);
+  }
+
+  /*
+   * 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-tone-info {
+    color: var(--seal-info-text);
+    background: var(--seal-info-bg);
+  }
+
+  .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: a citation carries the
+   * seal of the value it cites.
+   */
+  .seal-chip-sr-text {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+</style>

package/components/SealChip.svelte.d.ts

@@ -0,0 +1,68 @@
+export default SealChip;
+type SealChip = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * SealChip
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ *
+ * 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.
+ *
+ * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+ *
+ * @example A reading, using whatever terms the deployment declares
+ * <SealChip value="+14 cm/h" evidence={{ value: 'measured', label: 'medido', tone: 'positive' }} />
+ *
+ * @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.d.ts

@@ -3,6 +3,9 @@ export { default as Tag } from "./Tag.svelte";
 export { default as Status } from "./Status.svelte";
 export { default as Skeleton } from "./Skeleton.svelte";
 export { default as KeyValue } from "./KeyValue.svelte";
+export { default as SealChip } from "./SealChip.svelte";
+export { default as KpiRegister } from "./KpiRegister.svelte";
+export { default as CaminhoStateChip } from "./CaminhoStateChip.svelte";
 export { default as Button } from "./Button.svelte";
 export { default as Input } from "./Input.svelte";
 export { default as Textarea } from "./Textarea.svelte";

package/components/index.js

@@ -15,6 +15,13 @@ export { default as Status } from "./Status.svelte";
 export { default as Skeleton } from "./Skeleton.svelte";
 export { default as KeyValue } from "./KeyValue.svelte";
 
+// Evidence seal (H1 Slice 2 — westeuropeco/atelier-urban-workspace#57)
+// 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";
+
 // Form controls
 export { default as Button } from "./Button.svelte";
 export { default as Input } from "./Input.svelte";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "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,6 +248,27 @@
   --badge-neutral-bg: var(--color-surface-tertiary);
   --badge-neutral-text: var(--color-text-secondary);
 
+  /* 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-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);
+
   /* Tag */
   --tag-font: var(--type-label-font);
   --tag-size: var(--type-label-size);

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

@@ -138,6 +138,23 @@
   /* Total color overrides: 22. Elevation: 2. Focus alias: 1.
      Grand total: ~25 tokens. Typography/motion/spacing/grid unchanged.
      --color-info and --color-info-subtle NOT overridden (inherit DS teal-blue). */
+
+  /* ═══════════════════════════════════════════════════════════════
+     EVIDENCE SEAL — light-scheme text overrides (H1 Slice 2, uw#57)
+     --color-success (#16a34a) and --color-warning (#ca8a04) are
+     "large UI only" on the steel surface (3.15:1 and 2.83:1 resp.).
+     Seal badge text tokens use darker variants to clear WCAG AA (≥4.5:1)
+     on their respective subtle backgrounds.
+
+     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-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-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.
@@ -222,3 +239,27 @@
   /* Focus ring: accent blue, visible on all dark surfaces */
   --focus-ring-color: var(--color-accent);
 }
+
+[data-theme="ubp"][data-scheme="dark"] {
+  /* ═══════════════════════════════════════════════════════════════
+     EVIDENCE SEAL — dark-scheme overrides (H1 Slice 2, uw#57)
+     Text tokens lifted to 400-series for WCAG AA/AAA on steel-900
+     (#0b182a). Background tokens use color-mix() and are NOT
+     verified by the automated contrast suite (see ubp-theme-contrast
+     coverage-gap note) — visual QA is the complement.
+
+     Contrast on steel-900 (#0b182a, lum ≈ 0.0082):
+       measured  #4ade80 (green-400)  lum ≈ 0.403 → ~7.76:1 [AAA]
+       inferred  #60a5fa (blue-400)   lum ≈ 0.386 → ~7.49:1 [AAA]
+       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-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);