@incodetech/prizma-core-screens 0.1.0

package/src/EkycDetailsScreen.tsx

@@ -0,0 +1,178 @@
+import React, { forwardRef } from 'react';
+import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
+import { PrizmaDateField } from '@incodetech/prizma-core-web/date-field';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkycDetailsState, EkycDetailsValues, EkycStrings } from './EkycStrings';
+import './ScreenLayout.css';
+import './EkycLayout.css';
+
+export interface EkycDetailsScreenProps
+  extends Omit<
+    PrizmaFormScreenProps,
+    | 'title'
+    | 'subtitle'
+    | 'ctaLabel'
+    | 'ctaLoading'
+    | 'ctaLoadingLabel'
+    | 'verifiedLabel'
+    | 'children'
+    | 'navLabel'
+    | 'linkLabel'
+    | 'linkContent'
+    | 'progress'
+  > {
+  /** Module copy — this screen reads the `details` slice. */
+  strings: EkycStrings;
+  /** Which page-1 purple section to render. Default `default`. */
+  state?: EkycDetailsState;
+  /** The values the fields start with. Empty renders the resting empty field. */
+  values?: EkycDetailsValues;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYC — page 1, the applicant's identity data, built on the Form archetype
+ * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
+ *
+ * ONE screen for all three page-1 purple sections (`default` 2101:7877,
+ * `focused` 2101:8159, `filled` 5849:60225): measured against the 390 frames
+ * they share an identical skeleton — nav → Title → Spacing/32 → four labelled
+ * fields at Spacing/16 → "Continue" → tag (the archetype's own offsets, and the
+ * exact ones Figma draws: `middle container` puts Title at 8, `container 1` at
+ * 99, and stacks the fields at 0 / 94 / 188 / 282, i.e. 78-tall fields with a
+ * flat 16 between) — and differ ONLY in field content and field treatment.
+ *
+ * Four things are deliberate, each one a lesson an earlier module paid for:
+ *
+ * 1. The fields are UNCONTROLLED (`defaultValue`). A screen is one static spec
+ *    state, so no `onChange` is needed — and Core's `readOnly`, the other way
+ *    to freeze a field, paints the DISABLED grey surface on sections Figma
+ *    draws white (#PI-6). Page 1 greys nothing, so nothing here is `disabled`.
+ * 2. `focused` gets Core's OWN `--focused` modifier through `className` — the
+ *    class its CSS already implements beside `:focus-within`. `PrizmaTextField`
+ *    still has no `forceState` prop, unlike `PrizmaDropdown` (#PI-7); nothing
+ *    is re-styled here.
+ * 3. The clear ✕ is asked for ONLY on the focused field, the one field
+ *    2101:8159 draws it in. `clearable` alone would be a prop that silently
+ *    does nothing — Core reveals the button under `:focus-within`, a guard a
+ *    static spec state can never satisfy — so `EkycLayout.css` releases that
+ *    one guard, the same idiom (and the same Core request) as
+ *    `CurpLayout.css`'s error rule. No ✕ glyph is declared here.
+ * 4. Date of Birth is Core's `PrizmaDateField`, not a text field with a bolted-on
+ *    icon: the frame's trailing glyph is the date kind's own calendar
+ *    affordance, and the DD/MM/YYYY value Figma fills in ("14/03/1989") is the
+ *    mask that kind applies.
+ *
+ * The required asterisk is Core's `requiredHint` suffix on a `required` field —
+ * the label row Figma draws as "First name *" — so Middle name, the one
+ * optional field, correctly renders none.
+ *
+ * Figma draws a two-segment journey bar between the nav and the title on every
+ * page-1 frame, and it is the only chrome that separates page 1 from page 2.
+ * Archetype E had no slot above the title; the gap is now CLOSED in the
+ * archetype (`PrizmaFormScreen.progress`, offsets in `ScreenLayout.css`) rather
+ * than worked around here, and the bar itself is Core's shipped `PrizmaStepper`
+ * — no two-div bar is hand-rolled. All three page-1 sections draw segment 1
+ * solid brand blue and segment 2 grey, i.e. `steps={2} currentState="Start"`,
+ * with the icons row off (the frames draw the bar alone). DEVIATIONS #EK-1.
+ */
+export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenProps>(
+  (
+    {
+      strings,
+      state = 'default',
+      values,
+      screenId = `ekyc-details-${state}`,
+      className,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    // The one field treatment that varies across the three sections: 2101:8159
+    // rings First name blue and shows its clear ✕; the other two draw every
+    // field resting.
+    const focused = state === 'focused';
+
+    return (
+      <PrizmaFormScreen
+        ref={ref}
+        /* Scopes the single rule that lets the focused field keep the clear ✕
+           Figma draws inside it. See EkycLayout.css. */
+        className={['ekyc-details', focused ? 'ekyc-details--focused' : '', className]
+          .filter(Boolean)
+          .join(' ')}
+        /* Page 1 of 2: segment 1 filled, segment 2 still grey — Core's own
+           `Start` state at `steps={2}`. `showIcons={false}` because the frames
+           draw the bar with no glyph row (and it keeps the icon lookup, which
+           has no id+2 sequence, out of the render entirely). */
+        progress={
+          <PrizmaStepper
+            steps={2}
+            currentState="Start"
+            showIcons={false}
+            aria-label={strings.stepperLabel}
+          />
+        }
+        title={strings.details.title}
+        subtitle={strings.details.subtitle}
+        ctaLabel={strings.details.ctaLabel}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        /* Every eKYC form frame LEFT-aligns its title block, while the archetype
+           defaults to centred. The module supplies its designed alignment through
+           the sanctioned override rather than declaring any layout, and a host
+           that passes its own `align` still wins. */
+        overrides={{ align: overrides?.align ?? 'left', logo: overrides?.logo }}
+        onAction={onAction}
+        {...shell}
+      >
+        <PrizmaTextField
+          className={focused ? 'prizma-input-textfield--focused' : undefined}
+          label={strings.details.firstNameLabel}
+          required
+          requiredHint={strings.details.requiredHint}
+          defaultValue={values?.firstName ?? ''}
+          autoComplete="off"
+          /* Only 2101:8159 draws the ✕, and only in this field. */
+          clearable={focused}
+          clearLabel={strings.details.clearLabel}
+        />
+        <PrizmaTextField
+          label={strings.details.middleNameLabel}
+          defaultValue={values?.middleName ?? ''}
+          autoComplete="off"
+          clearable={false}
+        />
+        <PrizmaTextField
+          label={strings.details.lastNameLabel}
+          required
+          requiredHint={strings.details.requiredHint}
+          defaultValue={values?.lastName ?? ''}
+          autoComplete="off"
+          clearable={false}
+        />
+        <PrizmaDateField
+          label={strings.details.dateOfBirthLabel}
+          required
+          requiredHint={strings.details.requiredHint}
+          defaultValue={values?.dateOfBirth ?? ''}
+          autoComplete="off"
+          /* No `onCalendarClick`: a screen is a static spec state with no
+             picker to open, and Core renders the glyph as a decorative
+             aria-hidden span in that case — so `calendarLabel` would be a prop
+             that silently does nothing and is deliberately not passed. */
+        />
+      </PrizmaFormScreen>
+    );
+  },
+);
+EkycDetailsScreen.displayName = 'EkycDetailsScreen';
+
+export default EkycDetailsScreen;

package/src/EkycErrorScreen.tsx

@@ -0,0 +1,64 @@
+import React, { forwardRef } from 'react';
+import { PrizmaResultScreen, type PrizmaResultScreenProps } from './ResultScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkycStrings } from './EkycStrings';
+import './ScreenLayout.css';
+
+export interface EkycErrorScreenProps
+  extends Omit<
+    PrizmaResultScreenProps,
+    'status' | 'title' | 'subtitle' | 'ctaLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `error` slice. */
+  strings: EkycStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYC — the failure verdict, built on the Result archetype
+ * (GUIDELINES.md §6-F, `PrizmaResultScreen`).
+ *
+ * Figma: the purple `eKYC.error` section (2101:7979), which holds exactly ONE
+ * screen — a centred negative mark + H2 ("Something went wrong") over the "Try
+ * again" CTA band. The module draws no connectivity section anywhere in the
+ * file, so this screen ships no `variant` axis and no Wi-Fi glyph: adding one
+ * would invent a state the spec does not have (the #EI-5 precedent).
+ *
+ * Two things Figma draws are deliberately NOT reproduced, both owner-settled:
+ * the nav's close ✕ (GUIDELINES §3 forbids it — the standing #PI-9 ruling) and
+ * the missing verified tag, since the chrome stays constant across a module's
+ * screens (#PI-8, #F-34). The header and the tag stay.
+ *
+ * The mark is Core's outline status icon; the module Figma still draws the
+ * two-tone filled disc, one icon sweep behind (DEVIATIONS #15).
+ */
+export const EkycErrorScreen = forwardRef<HTMLDivElement, EkycErrorScreenProps>(
+  (
+    {
+      strings,
+      screenId = 'ekyc-error',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaResultScreen
+      ref={ref}
+      status="error"
+      title={strings.error.title}
+      ctaLabel={strings.error.ctaLabel}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+EkycErrorScreen.displayName = 'EkycErrorScreen';
+
+export default EkycErrorScreen;

package/src/EkycLayout.css

@@ -0,0 +1,39 @@
+/* eKYC — module layout additions.
+ *
+ * ONE rule, and it declares no spacing: the content column, the 24px gutters,
+ * the title → fields Spacing/32, the 16 between fields, the CTA column and the
+ * anchored footer all stay the foundation's (`ScreenLayout.css`,
+ * `FormScreen.css`). Nothing here re-declares an archetype value, invents a
+ * primitive or repaints one — the rule RELEASES a Core constraint that a purple
+ * eKYC section contradicts, the same idiom as `CurpLayout.css`'s error rule and
+ * Phone Input's `width: auto` on Core's fill-width Dropdown (DEVIATIONS #PI-1).
+ */
+
+/* ── The focused First-name field keeps its clear ✕ ──────────────────────────
+ * `eKYC.focused` (2101:8159) draws three things at once: the blue focus ring on
+ * First name, the partial value ("Juli") AND the grey clear ✕ at the field's
+ * right edge. Core renders that button (`PrizmaTextField clearable`) but reveals
+ * it only under `:focus-within` (TextField.css:121) — a guard a STATIC spec
+ * state can never satisfy, because nothing in a gallery card ever takes real
+ * DOM focus. Left alone, `clearable` would be a prop that silently does nothing,
+ * which is the exact defect the CURP build was pulled up on.
+ *
+ * This releases the guard for that ONE section, and only where Core has already
+ * decided the button should exist: `__clear--show` is Core's own state class,
+ * set only when the field has a value. It is Core's button, icon, box, size and
+ * color token — no ✕ glyph is declared here, no geometry, no spacing; only
+ * Core's `display: none` is lifted. Every other eKYC field asks for
+ * `clearable={false}` and gets no button in the DOM at all, exactly as
+ * 2101:7877 / 5849:60225 / 5849:51109 / 5849:66890 / 5849:71925 draw them.
+ *
+ * CORE REQUEST (already open as DEVIATIONS #PI-7): `PrizmaTextField` needs the
+ * `forceState` prop `PrizmaDropdown` has, so a documentation/spec surface can
+ * render the designed focused state — ring AND clear affordance — without a
+ * consumer releasing a CSS guard. Every module with a "focused" purple section
+ * hits this.
+ */
+.ekyc-details--focused
+  .prizma-input-textfield--focused
+  .prizma-input-textfield__clear--show {
+  display: inline-flex;
+}

package/src/EkycLicenseScreen.tsx

@@ -0,0 +1,164 @@
+import React, { forwardRef } from 'react';
+import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
+import { PrizmaDateField } from '@incodetech/prizma-core-web/date-field';
+import { PrizmaDropdown } from '@incodetech/prizma-core-web/dropdown';
+import { PrizmaStepper, type PrizmaStepperState } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  EkycLicenseState,
+  EkycLicenseStateOption,
+  EkycLicenseValues,
+  EkycStrings,
+} from './EkycStrings';
+import './ScreenLayout.css';
+import './EkycLayout.css';
+
+export interface EkycLicenseScreenProps
+  extends Omit<
+    PrizmaFormScreenProps,
+    | 'title'
+    | 'subtitle'
+    | 'ctaLabel'
+    | 'ctaLoading'
+    | 'ctaLoadingLabel'
+    | 'verifiedLabel'
+    | 'children'
+    | 'navLabel'
+    | 'linkLabel'
+    | 'linkContent'
+    | 'progress'
+  > {
+  /** Module copy — this screen reads the `license` slice. */
+  strings: EkycStrings;
+  /** Which page-2 purple section to render. Default `default`. */
+  state?: EkycLicenseState;
+  /** The values the fields start with. */
+  values?: EkycLicenseValues;
+  /** The jurisdictions the state chooser offers. Runtime data, never copy. */
+  stateOptions?: EkycLicenseStateOption[];
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYC — page 2, the document's own fields, built on the Form archetype
+ * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
+ *
+ * ONE screen for all three page-2 purple sections (`default` 5849:51109,
+ * `filled` 5849:66890, `loading` 5849:71925): the frames share page 1's
+ * skeleton exactly — nav → Title → Spacing/32 → labelled fields at Spacing/16
+ * → "Continue" → tag — with a three-field stack (text · chooser · date) and no
+ * subtitle, and they differ ONLY in field content and CTA state.
+ *
+ * Three things are deliberate:
+ *
+ * 1. The middle field is Core's `PrizmaDropdown`, the chooser Figma draws
+ *    (`Dropdown`, 342×78, trailing chevron), not a text field. It is left
+ *    UNCONTROLLED via `defaultValue` for the same reason the text fields are.
+ * 2. `loading` is the ONE section Figma greys, so it is the only one that sets
+ *    `disabled` — on all three fields, exactly as drawn (#PI-6: `readOnly` is
+ *    never used to freeze a field, because it greys sections drawn white).
+ * 3. The in-flight spinner rides the CTA (`ctaLoading`), never a field — the
+ *    standing #PI-5 ruling, and what 5849:71925 draws: the button's label is
+ *    replaced by the spinner while every field stays put.
+ *
+ * Page 2 draws NO required asterisks — 5849:51109's three label rows are bare —
+ * so no field here is `required`, and the page carries no "* are required"
+ * subtitle either.
+ *
+ * As on page 1, the two-segment journey bar rides the archetype's `progress`
+ * slot (`PrizmaFormScreen.progress`, offsets in `ScreenLayout.css`) and is
+ * Core's shipped `PrizmaStepper`. Page 2 advances it: 5849:51109 and 5849:66890
+ * draw segment 1 pale (Core's `past` — brand blue at 0.5) and segment 2 solid
+ * brand blue, which is `currentState={2}`; 5849:71925 turns BOTH segments green,
+ * which is Core's `Completed`. The bar is therefore what tells `loading` apart
+ * from `filled` at a glance, on top of the greyed fields and the CTA spinner.
+ * DEVIATIONS #EK-1.
+ */
+/** Page-2 section → the journey-bar state Figma paints on it. */
+const STEPPER_STATE: Record<EkycLicenseState, PrizmaStepperState> = {
+  /* 5849:51109 / 5849:66890 — segment 1 pale ("past"), segment 2 solid. */
+  default: 2,
+  filled: 2,
+  /* 5849:71925 — both segments green. */
+  loading: 'Completed',
+};
+
+export const EkycLicenseScreen = forwardRef<HTMLDivElement, EkycLicenseScreenProps>(
+  (
+    {
+      strings,
+      state = 'default',
+      values,
+      stateOptions = [],
+      screenId = `ekyc-license-${state}`,
+      className,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    const busy = state === 'loading';
+
+    return (
+      <PrizmaFormScreen
+        ref={ref}
+        className={['ekyc-license', className].filter(Boolean).join(' ')}
+        /* Page 2 of 2 — advanced past page 1, and green once the submit is in
+           flight. `showIcons={false}`: the frames draw the bar alone. */
+        progress={
+          <PrizmaStepper
+            steps={2}
+            currentState={STEPPER_STATE[state]}
+            showIcons={false}
+            aria-label={strings.stepperLabel}
+            completedValueText={strings.stepperCompletedLabel}
+          />
+        }
+        title={strings.license.title}
+        ctaLabel={strings.license.ctaLabel}
+        /* 5849:71925 swaps the CTA label for Core's designed spinner. */
+        ctaLoading={busy}
+        ctaLoadingLabel={strings.license.ctaLoadingLabel}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        /* Left-aligned title block, same as page 1; a host `align` still wins. */
+        overrides={{ align: overrides?.align ?? 'left', logo: overrides?.logo }}
+        onAction={onAction}
+        {...shell}
+      >
+        <PrizmaTextField
+          label={strings.license.numberLabel}
+          defaultValue={values?.number ?? ''}
+          autoComplete="off"
+          spellCheck={false}
+          disabled={busy}
+          /* No section on this page draws the clear ✕. */
+          clearable={false}
+        />
+        <PrizmaDropdown
+          label={strings.license.stateLabel}
+          options={stateOptions}
+          defaultValue={values?.state ?? null}
+          disabled={busy}
+        />
+        <PrizmaDateField
+          label={strings.license.expirationLabel}
+          defaultValue={values?.expirationDate ?? ''}
+          autoComplete="off"
+          disabled={busy}
+          /* No `onCalendarClick` — see the note in `EkycDetailsScreen`: Core
+             renders the calendar as a decorative aria-hidden glyph without one,
+             so `calendarLabel` would do nothing and is not passed. */
+        />
+      </PrizmaFormScreen>
+    );
+  },
+);
+EkycLicenseScreen.displayName = 'EkycLicenseScreen';
+
+export default EkycLicenseScreen;

package/src/EkycProcessingScreen.tsx

@@ -0,0 +1,60 @@
+import React, { forwardRef } from 'react';
+import {
+  PrizmaProcessingScreen,
+  type PrizmaProcessingScreenProps,
+} from './ProcessingScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkycStrings } from './EkycStrings';
+import './ScreenLayout.css';
+
+export interface EkycProcessingScreenProps
+  extends Omit<
+    PrizmaProcessingScreenProps,
+    'status' | 'title' | 'subtitle' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `processing` slice. */
+  strings: EkycStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYC — the submitted data is being checked, built on the Processing archetype
+ * (GUIDELINES.md §6-C, `PrizmaProcessingScreen`).
+ *
+ * Figma: the purple `eKYC.processing` section (2101:7959). A centred spinner
+ * over a bare H2 ("Processing…") with **no subtitle and no CTA** — exactly the
+ * pure no-button case §6-F reserves for C rather than the Result archetype.
+ *
+ * The title block is centred here, unlike the module's two form pages: the
+ * verdict frames draw the mark and the status line on the screen's centre line,
+ * so the archetype's own default is the designed one and nothing is overridden.
+ */
+export const EkycProcessingScreen = forwardRef<HTMLDivElement, EkycProcessingScreenProps>(
+  (
+    {
+      strings,
+      screenId = 'ekyc-processing',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaProcessingScreen
+      ref={ref}
+      status="loading"
+      title={strings.processing.title}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+EkycProcessingScreen.displayName = 'EkycProcessingScreen';
+
+export default EkycProcessingScreen;

package/src/EkycStrings.ts

@@ -0,0 +1,157 @@
+// eKYC — copy contract.
+//
+// Figma: `👁️ eKYC / 💼 eKYB - Screens specs + Localization`
+// (`TWgYZVhurQCizfC4tfLEut`, page `2003:12082`). The file holds THREE top-level
+// sections; only the two eKYC ones are this module's scope:
+//   `2098:20865` 👁️ eKYC Initial screen options — the field-option catalogue
+//                 (V1 references · dashboard options · the "all options" matrix).
+//                 A spec board, not screens: every 390 frame it feeds is drawn
+//                 in the section below.
+//   `2101:7869` 👁️ eKYC - Screens specs + Localization — the nine 390×844
+//                 frames this module builds.
+//   `2116:23785` 💼 eKYB — a DIFFERENT module, deliberately untouched.
+//
+// The nine eKYC frames, by their 390×844 node id:
+//   2101:7877  eKYC.default  (page 1 — personal details, empty)
+//   2101:8159  eKYC.focused  (page 1 — First name focused, partial value)
+//   5849:60225 eKYC.filled   (page 1 — all four values)
+//   5849:51109 eKYC.default  (page 2 — driver's-licence details, empty)
+//   5849:66890 eKYC.filled   (page 2 — all three values)
+//   5849:71925 eKYC.loading  (page 2 — fields inert, spinner in the CTA)
+//   2101:7959  eKYC.processing
+//   2101:7979  eKYC.error
+//   2101:7969  eKYC.success
+//
+// The module is a TWO-PAGE form: the data-capture pages are archetype E
+// (`PrizmaFormScreen`), the two no-button verdicts are archetype C
+// (`PrizmaProcessingScreen`) and the failure verdict is archetype F
+// (`PrizmaResultScreen`) — the same C/F split `EmailInputSuccessScreen` and
+// `EmailInputErrorScreen` settled (DEVIATIONS #EI-4/#EI-5).
+//
+// No hardcoded English anywhere in a screen: every visible string arrives here,
+// so the host's locale pack drives the module (the Figma file ships ES + PT
+// columns alongside EN).
+
+/**
+ * The page-1 sections (`eKYC.default` / `eKYC.focused` / `eKYC.filled`). All
+ * three draw the SAME layout — nav → Title (H2 + H5) → Spacing/32 → four
+ * labelled fields at Spacing/16 → "Continue" → tag — and differ only in field
+ * content and field treatment, which is what GUIDELINES §6-E means by "states
+ * are separate screens sharing the identical layout":
+ * - `default` — every field empty
+ * - `focused` — First name carries the blue focus ring, a partial value and
+ *               the clear ✕ (2101:8159 draws the OS keyboard over the CTA; the
+ *               keyboard is OS chrome, never a screen element)
+ * - `filled`  — all four fields resting with their values
+ */
+export type EkycDetailsState = 'default' | 'focused' | 'filled';
+
+/**
+ * The page-2 sections (`eKYC.default` / `eKYC.filled` / `eKYC.loading`), same
+ * layout with the document field set:
+ * - `default` — licence number, state chooser and expiry all empty
+ * - `filled`  — all three resting with their values
+ * - `loading` — the submit is in flight: Figma greys all three fields and swaps
+ *               the CTA label for the spinner (the spinner rides the CTA, never
+ *               a field — the standing #PI-5 ruling)
+ */
+export type EkycLicenseState = 'default' | 'filled' | 'loading';
+
+/** One row of the licence-state chooser. Runtime data, never copy — the host
+ *  supplies the jurisdictions its tenant accepts, exactly as Phone Input's
+ *  `PhoneInputCountry` supplies dial codes. */
+export interface EkycLicenseStateOption {
+  value: string;
+  label: string;
+}
+
+/** Page-1 field values. A screen is one static spec state, so these are the
+ *  UNCONTROLLED starting values of Core's fields — no `onChange` is wired and
+ *  `readOnly` is never used to freeze them (it paints Core's DISABLED grey on
+ *  sections Figma draws white — the standing #PI-6 ruling). */
+export interface EkycDetailsValues {
+  firstName?: string;
+  middleName?: string;
+  lastName?: string;
+  dateOfBirth?: string;
+}
+
+/** Page-2 field values. Same contract as `EkycDetailsValues`. */
+export interface EkycLicenseValues {
+  /** The licence number as printed on the document. */
+  number?: string;
+  /** `value` of one `EkycLicenseStateOption`. */
+  state?: string;
+  /** Masked DD/MM/YYYY, the mask Core's date field applies. */
+  expirationDate?: string;
+}
+
+export interface EkycStrings {
+  /** "verified by" attribution in the footer tag. */
+  verifiedLabel: string;
+  /** Accessible name for the logo nav row. */
+  navLabel?: string;
+
+  /**
+   * Accessible name for the two-segment journey bar the six form frames draw
+   * between the nav and the title (Core's `PrizmaStepper`, `role="progressbar"`).
+   * The bar is the ONLY chrome that separates page 1 from page 2, so it carries
+   * a real name rather than none — supplied here because it is copy.
+   */
+  stepperLabel: string;
+  /**
+   * `aria-valuetext` the same bar announces once both segments are green — the
+   * page-2 `loading` section (5849:71925). Same contract as Video Selfie's
+   * `stepperCompletedLabel`.
+   */
+  stepperCompletedLabel: string;
+
+  /** `eKYC.*` page 1 — the applicant's name and date of birth. */
+  details: {
+    /** H2 screen title. */
+    title: string;
+    /** H5 description under the title. */
+    subtitle: string;
+    /**
+     * Suffix Core appends to a REQUIRED field's label — Figma draws a bare
+     * asterisk ("First name *") and the subtitle explains it. Configurable
+     * because it is visible copy: a locale may prefer "(obligatorio)".
+     */
+    requiredHint: string;
+    firstNameLabel: string;
+    middleNameLabel: string;
+    lastNameLabel: string;
+    dateOfBirthLabel: string;
+    /** Accessible name for the clear ✕ inside the focused field. */
+    clearLabel: string;
+    ctaLabel: string;
+  };
+
+  /** `eKYC.*` page 2 — the document's own fields. */
+  license: {
+    /** H2 screen title. */
+    title: string;
+    numberLabel: string;
+    stateLabel: string;
+    expirationLabel: string;
+    ctaLabel: string;
+    /** Visible/accessible copy while the submit is in flight. */
+    ctaLoadingLabel: string;
+  };
+
+  /** `eKYC.processing` — spinner over the status line, no button. */
+  processing: {
+    title: string;
+  };
+
+  /** `eKYC.success` — positive mark over the status line, no button. */
+  success: {
+    title: string;
+  };
+
+  /** `eKYC.error` — negative mark, status line and the retry CTA. */
+  error: {
+    title: string;
+    ctaLabel: string;
+  };
+}