@aiaiai-pt/design-system 0.49.0 → 0.50.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,158 @@
+<!--
+  @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.
+
+  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+  References sistema#67 for .type-overline (--type-overline-* tokens).
+
+  @example Measured only
+  <KpiRegister label="ENERGY OUTPUT" measuredValue="2.3 MW" />
+
+  @example With sealed projected value
+  <KpiRegister
+    label="ENERGY OUTPUT"
+    measuredValue="2.3 MW"
+    projectedValue="4.1 MW"
+    projectedSeal={{ evidence: 'projected', stale: false }}
+  />
+-->
+<script>
+  import SealChip from './SealChip.svelte';
+
+  /**
+   * @typedef {'measured' | 'inferred' | 'projected'} EvidenceState
+   * @typedef {{ evidence: EvidenceState; stale: boolean }} SealRef
+   */
+
+  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 {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.
+     */
+    projectedSeal = undefined,
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  /*
+   * 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).
+   */
+  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) {
+      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.',
+      );
+    }
+  });
+</script>
+
+<div class="kpi-register {className}" {...rest}>
+  <!--
+    Overline label — micro-heading above the value.
+    Uses --type-overline-* tokens directly (sistema#67 .type-overline utility).
+  -->
+  <span class="kpi-register-label">{label}</span>
+
+  <!--
+    Measured value: the authoritative reading.
+    Display-scale type — visually out-ranks the projected row.
+  -->
+  <div class="kpi-register-measured">
+    <span class="kpi-register-measured-value">{measuredValue}</span>
+  </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).
+  -->
+  {#if projectedValue !== undefined && projectedSeal != null}
+    <div class="kpi-register-projected">
+      <SealChip
+        value={projectedValue}
+        evidence={projectedSeal.evidence}
+        stale={projectedSeal.stale}
+      />
+    </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 class from utilities.css,
+   * 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);
+  }
+
+  /* Measured value: display scale — the dominant visual element */
+  .kpi-register-measured-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;
+  }
+
+  /* Projected row: body-scale — subordinate to the measured value */
+  .kpi-register-projected {
+    display: flex;
+    align-items: center;
+    margin-top: var(--space-2xs);
+  }
+</style>

package/components/KpiRegister.svelte.d.ts

@@ -0,0 +1,46 @@
+export default KpiRegister;
+type KpiRegister = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * 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.
+ *
+ * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+ * References sistema#67 for .type-overline (--type-overline-* tokens).
+ *
+ * @example Measured only
+ * <KpiRegister label="ENERGY OUTPUT" measuredValue="2.3 MW" />
+ *
+ * @example With sealed projected value
+ * <KpiRegister
+ *   label="ENERGY OUTPUT"
+ *   measuredValue="2.3 MW"
+ *   projectedValue="4.1 MW"
+ *   projectedSeal={{ evidence: 'projected', stale: false }}
+ * />
+ */
+declare const KpiRegister: import("svelte").Component<{
+    label: any;
+    measuredValue: any;
+    projectedValue?: any;
+    projectedSeal?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label: any;
+    measuredValue: any;
+    projectedValue?: any;
+    projectedSeal?: any;
+    class?: string;
+} & Record<string, any>;

package/components/SealChip.svelte

@@ -0,0 +1,133 @@
+<!--
+  @component SealChip
+
+  Renders a value paired with its evidence seal as ONE phrase.
+
+  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").
+
+  DS-owned evidence vocabulary: measured | inferred | projected.
+  Built over --badge-* + --seal-* component tokens.
+
+  H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+
+  @example Measured reading
+  <SealChip value="2.3 MW" evidence="measured" />
+
+  @example Projected (future window)
+  <SealChip value="4.1 MW" evidence="projected" />
+
+  @example Stale seal (horizon has passed)
+  <SealChip value="1.9 MW" evidence="projected" stale />
+-->
+<script>
+  /**
+   * @typedef {'measured' | 'inferred' | 'projected'} EvidenceState
+   */
+
+  let {
+    /** @type {string} — the formatted display value */
+    value,
+    /** @type {EvidenceState} — evidence state (from assignSeal) */
+    evidence,
+    /** @type {boolean} — true when the validity window has passed */
+    stale = false,
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  const EVIDENCE_LABELS = /** @type {Record<EvidenceState, string>} */ ({
+    measured: 'measured',
+    inferred: 'inferred',
+    projected: 'projected',
+  });
+
+  const evidenceLabel = $derived(EVIDENCE_LABELS[evidence] ?? evidence);
+
+  /** Label as spoken by AT and included in citations. */
+  const srLabel = $derived(stale ? `${evidenceLabel} (stale)` : evidenceLabel);
+</script>
+
+<!--
+  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]
+-->
+<span
+  class="seal-chip seal-chip-{evidence} {stale ? 'seal-chip-stale' : ''} {className}"
+  {...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>
+
+<style>
+  .seal-chip {
+    display: inline-flex;
+    align-items: baseline;
+    gap: var(--space-xs);
+    position: relative;
+  }
+
+  /* Value text: no override — reads as its context's surrounding type */
+  .seal-chip-value {
+    /* intentionally empty */
+  }
+
+  /* Visual evidence badge — seen by sighted users; hidden from AT */
+  .seal-chip-badge {
+    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;
+  }
+
+  /* Evidence-state colours via --seal-* component tokens */
+  .seal-chip-measured .seal-chip-badge {
+    color: var(--seal-measured-text);
+    background: var(--seal-measured-bg);
+  }
+
+  .seal-chip-inferred .seal-chip-badge {
+    color: var(--seal-inferred-text);
+    background: var(--seal-inferred-bg);
+  }
+
+  .seal-chip-projected .seal-chip-badge {
+    color: var(--seal-projected-text);
+    background: var(--seal-projected-bg);
+  }
+
+  /* Stale modifier: muted on all evidence states */
+  .seal-chip-stale .seal-chip-badge {
+    color: var(--seal-stale-text);
+    background: var(--seal-stale-bg);
+  }
+
+  /*
+   * 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().
+   */
+  .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,41 @@
+export default SealChip;
+type SealChip = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * SealChip
+ *
+ * Renders a value paired with its evidence seal as ONE phrase.
+ *
+ * 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").
+ *
+ * DS-owned evidence vocabulary: measured | inferred | projected.
+ * Built over --badge-* + --seal-* component tokens.
+ *
+ * H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+ *
+ * @example Measured reading
+ * <SealChip value="2.3 MW" evidence="measured" />
+ *
+ * @example Projected (future window)
+ * <SealChip value="4.1 MW" evidence="projected" />
+ *
+ * @example Stale seal (horizon has passed)
+ * <SealChip value="1.9 MW" evidence="projected" stale />
+ */
+declare const SealChip: import("svelte").Component<{
+    value: any;
+    evidence: any;
+    stale?: boolean;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    value: any;
+    evidence: any;
+    stale?: boolean;
+    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,12 @@ 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)
+// DS-owned evidence vocabulary: measured | inferred | projected
+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.50.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -248,6 +248,21 @@
   --badge-neutral-bg: var(--color-surface-tertiary);
   --badge-neutral-text: var(--color-text-secondary);
 
+  /* Evidence Seal — DS-owned vocabulary: measured | inferred | projected
+     H1 Slice 2 — westeuropeco/atelier-urban-workspace#57.
+     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);
+  /* 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/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-inferred-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] */
 }
 
 /* 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-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);
+  /* stale: inherits --seal-stale-text (--color-text-muted = #60758a, 3.74:1 non-essential)
+            and --seal-stale-bg (--color-surface-secondary = #1a2a3a) */
+}