@incodetech/prizma-core-screens 0.2.4 → 0.2.12

package/src/DigitalIdUploadStrings.ts

@@ -0,0 +1,88 @@
+// Digital ID Upload module — copy contract.
+//
+// Every Digital ID Upload screen receives the SAME `strings:
+// DigitalIdUploadStrings` object (rule: all copy via props, no hardcoded
+// English — GUIDELINES.md §9).
+//
+// Authoritative screens: the "Web Happy Path - Light Mode" purple section of
+// the Upload Digital ID Figma file (wxFsHRvllern4VnjRqM4JO, node 25351:14721)
+// — covers `tutorial` and the `review` / `analyzing` / `success` stages of
+// the confirm flow — plus TWO separate `Errors` sections: node 25874:11955
+// (`ID type is not accepted`) and node 26083:3981 (`File Limit Error`, "File
+// is too large"). Three frames of the happy-path section are NOT part of
+// this contract: `1-1-1-how to verify` (a verification-method chooser shared
+// with ID Capture — see IdCaptureDocumentSelectionScreen.tsx, which is one
+// row short of this Figma's version), a native iOS file-browser frame (OS
+// chrome, DEVIATIONS.md #DC-20 precedent), and `1-18-1-id-hold-on` (ID
+// Capture's own server-side-wait screen — dropped from this module by
+// product decision, not a gap to fill).
+
+/** The three stages the confirm flow's screen shares — matches
+ *  `PrizmaReviewScreen`'s own `PrizmaReviewStage` (ReviewScreen.tsx). Kept as
+ *  a separate module-scoped type rather than importing it, same convention as
+ *  `DocumentCaptureConfirmStage` (DocumentCaptureStrings.ts). */
+export type DigitalIdUploadConfirmStage = 'review' | 'analyzing' | 'success';
+
+export interface DigitalIdUploadStrings {
+  /** Accessible name for the logo nav region (i18n — no baked-in English). */
+  navLabel?: string;
+  /** "verified by" attribution copy for the footer tag. */
+  verifiedLabel: string;
+
+  /** `Tutorial Screen` (node 25351:14722). */
+  tutorial: {
+    title: string;
+    subtitle?: string;
+    /** "Upload PDF" */
+    ctaLabel: string;
+  };
+
+  /** `Review Document` / `Analyzing` / `Success` (nodes
+   *  25351:14725/14726/14727) — one screen, three stages. */
+  review: {
+    /** `review` title ("Review document"). */
+    title: string;
+    /** `review` description. Figma draws no subtitle on `analyzing` or
+     *  `success` — the shared `PrizmaReviewScreen` archetype already only
+     *  shows one on `review`, so this needs no per-stage handling here. */
+    subtitle?: string;
+    /** Loading-bar caption on `analyzing` ("Analyzing.."). */
+    analyzingLabel: string;
+    /** H2 on `success` ("Successfully processed!"). */
+    successTitle: string;
+    /** Secondary CTA on `review` ("Replace file"). */
+    replaceLabel: string;
+    /** Primary CTA on `review` / `success` ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** `Errors` section, `Error` frame (node 25874:11957) — the uploaded file
+   *  itself was rejected (wrong document type). Built on the SAME
+   *  `PrizmaReviewScreen` archetype as `review`, stage `"error"`: the card
+   *  reuses `PrizmaCaptureDigitalId state="error"` (red 4px border), not a
+   *  generic archetype-F verdict screen (DigitalIdUploadErrorScreen.tsx). */
+  error: {
+    /** "ID type is not accepted" */
+    title: string;
+    /** "Please try scanning a different document" */
+    subtitle?: string;
+    /** "Scan your ID" */
+    ctaLabel: string;
+  };
+
+  /** `Errors` section, `File Limit Error` frame (node 26083:3981) — the file
+   *  was never uploaded at all (client-side size check), so there is no
+   *  rejected document to show. Built on Archetype F (`PrizmaResultScreen`,
+   *  ResultScreen.tsx) rather than the review archetype `error` uses above —
+   *  Figma centres the status + title + subtitle in the full available
+   *  height with no media stage at all, exactly F's shape, not H's
+   *  header-above-a-card one (DigitalIdUploadFileTooLargeScreen.tsx). */
+  fileTooLarge: {
+    /** "File is too large" */
+    title: string;
+    /** "The selected file is larger than 5 MB, please upload a smaller one" */
+    subtitle?: string;
+    /** "Choose another file" */
+    ctaLabel: string;
+  };
+}

package/src/DigitalIdUploadTutorialScreen.tsx

@@ -0,0 +1,59 @@
+import React, { forwardRef } from 'react';
+import { PrizmaCaptureDigitalId } from '@incodetech/prizma-core-web/capture-digital-id';
+import { PrizmaTutorialScreen, type PrizmaTutorialScreenProps } from './TutorialScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { DigitalIdUploadStrings } from './DigitalIdUploadStrings';
+import './ScreenLayout.css';
+
+export interface DigitalIdUploadTutorialScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    'title' | 'subtitle' | 'ctaLabel' | 'illustration' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `tutorial` slice (+ shared labels). */
+  strings: DigitalIdUploadStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Digital ID Upload — tutorial, built on the `PrizmaTutorialScreen` archetype
+ * (GUIDELINES.md §6-A). Figma: `Upload Digital ID` file
+ * (wxFsHRvllern4VnjRqM4JO), "Web Happy Path - Light Mode" section, `Tutorial
+ * Screen` (node 25351:14722).
+ *
+ * The illustration slot is Core's own `PrizmaCaptureDigitalId` in its
+ * `tutorial` state — the Figma file names this exact instance "Capture /
+ * Digital ID" (node 26161:10686, Figma description: "Incode specific
+ * component for Digital ID module experience"), the same managed component
+ * already shipped as `core/platforms/web/src/CaptureDigitalId.tsx`. No module
+ * illustration is drawn here — the component owns its own tutorial artwork
+ * (`PrizmaIllustrationDigitalId`).
+ */
+export const DigitalIdUploadTutorialScreen = forwardRef<
+  HTMLDivElement,
+  DigitalIdUploadTutorialScreenProps
+>(
+  (
+    { strings, screenId = 'digital-id-upload-tutorial', overrides, onAction, ...shell },
+    ref,
+  ) => (
+    <PrizmaTutorialScreen
+      ref={ref}
+      title={strings.tutorial.title}
+      subtitle={strings.tutorial.subtitle}
+      ctaLabel={strings.tutorial.ctaLabel}
+      illustration={<PrizmaCaptureDigitalId state="tutorial" />}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+DigitalIdUploadTutorialScreen.displayName = 'DigitalIdUploadTutorialScreen';
+
+export default DigitalIdUploadTutorialScreen;

package/src/DocumentCaptureIllustration.tsx

@@ -7,7 +7,7 @@ import './DocumentCaptureLayout.css';
  *
  * WHY IT LIVES IN THE MODULE LAYER: `prizma-core-web` ships
  * `PrizmaIllustrationSelfie`, `…IdTutorial`, `…IdIntro`, `…IdFlip`,
- * `…IdHint`, `…IdFeedback`, `…NfcScan`, `…NfcIssue`, `…Geolocation`,
+ * `…IdHint`, `…IdFeedback`, `…NfcScan`, `…Geolocation`,
  * `…DigitalId` and `…Avatar` — there is NO document / proof-of-address
  * illustration. GUIDELINES.md §10 is the standing asset rule for that gap
  * ("Illustrations…: inline SVG React components (Figma-sourced), tintable via

package/src/EkybAddressDetailsScreen.tsx

@@ -82,6 +82,13 @@ export interface EkybAddressDetailsScreenProps
  * segment 2 solid, segment 3 grey) is Core's `PrizmaStepper` at
  * `currentState={2}`, composed into the archetype's `progress` slot. This is
  * step 2 of 3.
+ *
+ * `emptyError` is Continue pressed with the fields still empty (Elena,
+ * 2026-09-30, GUIDELINES §6-E empty-submit rule; precedent `FormsFieldScreen`'s
+ * `emptyError`): every field renders empty, the five REQUIRED ones (State
+ * included) in Core's `error` state with `requiredError` and no placeholder,
+ * Address line 2 unflagged (optional, DEVIATIONS #EKC-6's rule), and Continue
+ * disabled. `empty` keeps Continue enabled so the press can happen.
  */
 export const EkybAddressDetailsScreen = forwardRef<
   HTMLDivElement,
@@ -91,9 +98,10 @@ export const EkybAddressDetailsScreen = forwardRef<
     {
       strings,
       state = 'empty',
-      values,
+      values: valuesProp,
       states = [],
       screenId = `ekyb-address-${state}`,
+      ctaDisabled,
       className,
       overrides,
       onAction,
@@ -102,6 +110,14 @@ export const EkybAddressDetailsScreen = forwardRef<
     ref,
   ) => {
     const copy = strings.address;
+    const emptyError = state === 'emptyError';
+    const values = emptyError ? undefined : valuesProp;
+    // Core's own error treatment, spread AFTER each required field's own
+    // placeholder so the error state shows none (the `FormsFieldScreen`
+    // precedent). Address line 2 never receives it.
+    const missing = emptyError
+      ? { error: true, errorText: strings.requiredError, placeholder: undefined }
+      : {};
 
     return (
       <PrizmaFormScreen
@@ -122,6 +138,8 @@ export const EkybAddressDetailsScreen = forwardRef<
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
+        /* Disabled only after the empty submit; `empty` keeps it enabled. */
+        ctaDisabled={emptyError || ctaDisabled}
         linkContent={
           <PrizmaButton
             variant="secondary"
@@ -136,17 +154,20 @@ export const EkybAddressDetailsScreen = forwardRef<
         screenId={screenId}
         overrides={{ align: overrides?.align ?? 'left', logo: overrides?.logo }}
         onAction={onAction}
-        /* Exploration ekyb-desktop: on a wide frame only State + Postal code
-           share a row (Figma 6407:43637); the four text fields above span the
-           column. On the phone nothing changes. */
+        /* Exploration ekyb-desktop: on a wide frame the fields pair up in
+           three rows, Street + House number, Address line 2 + City (Elena,
+           2026-09-28), and State + Postal code (Figma 6407:43637). On the
+           phone nothing changes. */
         responsive
         {...shell}
       >
+        <PrizmaFormRow>
         <PrizmaTextField
           label={copy.street.label}
           placeholder={copy.street.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.street ?? ''}
         />
@@ -155,9 +176,12 @@ export const EkybAddressDetailsScreen = forwardRef<
           placeholder={copy.houseNumber.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.houseNumber ?? ''}
         />
+        </PrizmaFormRow>
+        <PrizmaFormRow>
         {/* The one field 6340:50731 draws without an asterisk. */}
         <PrizmaTextField
           label={copy.addressLine2.label}
@@ -170,15 +194,18 @@ export const EkybAddressDetailsScreen = forwardRef<
           placeholder={copy.city.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.city ?? ''}
         />
+        </PrizmaFormRow>
         <PrizmaFormRow>
         <PrizmaDropdown
           label={copy.state.label}
           placeholder={copy.state.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           options={states}
           /* Both sections draw the placeholder unless the host supplies a
              value — see the docstring note on 6340:38197. */
@@ -193,6 +220,7 @@ export const EkybAddressDetailsScreen = forwardRef<
           placeholder={copy.postalCode.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.postalCode ?? ''}
         />

package/src/EkybBusinessDetailsScreen.tsx

@@ -2,7 +2,7 @@ import React, { forwardRef } from 'react';
 import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
 import { PrizmaButton } from '@incodetech/prizma-core-web/button';
 import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
-import { PrizmaFormScreen, PrizmaFormRow, type PrizmaFormScreenProps } from './FormScreen';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type { EkybBusinessState, EkybBusinessValues, EkybStrings } from './EkybStrings';
 import './ScreenLayout.css';
@@ -69,6 +69,12 @@ export interface EkybBusinessDetailsScreenProps
  * bar is at `currentState="Start"`: segment 1 filled, segments 2 and 3 grey,
  * exactly what 5919:68599 renders. Both offsets around it live in
  * `ScreenLayout.css`, never here.
+ *
+ * `emptyError` is Continue pressed with the fields still empty (Elena,
+ * 2026-09-30, GUIDELINES §6-E empty-submit rule; precedent `FormsFieldScreen`'s
+ * `emptyError`): both REQUIRED fields render empty in Core's `error` state with
+ * `requiredError` under them, and Continue is disabled. `empty` keeps Continue
+ * enabled so the press can happen.
  */
 export const EkybBusinessDetailsScreen = forwardRef<
   HTMLDivElement,
@@ -78,8 +84,9 @@ export const EkybBusinessDetailsScreen = forwardRef<
     {
       strings,
       state = 'empty',
-      values,
+      values: valuesProp,
       screenId = `ekyb-business-${state}`,
+      ctaDisabled,
       overrides,
       onAction,
       ...shell
@@ -87,6 +94,13 @@ export const EkybBusinessDetailsScreen = forwardRef<
     ref,
   ) => {
     const copy = strings.business;
+    const emptyError = state === 'emptyError';
+    const values = emptyError ? undefined : valuesProp;
+    // Core's own error treatment, spread onto the REQUIRED fields only; the
+    // error state shows no placeholder (the `FormsFieldScreen` precedent).
+    const missing = emptyError
+      ? { error: true, errorText: strings.requiredError, placeholder: undefined }
+      : {};
 
     return (
       <PrizmaFormScreen
@@ -104,6 +118,8 @@ export const EkybBusinessDetailsScreen = forwardRef<
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
+        /* Disabled only after the empty submit; `empty` keeps it enabled. */
+        ctaDisabled={emptyError || ctaDisabled}
         linkContent={
           <PrizmaButton
             variant="secondary"
@@ -121,16 +137,18 @@ export const EkybBusinessDetailsScreen = forwardRef<
         overrides={{ align: overrides?.align ?? 'left', logo: overrides?.logo }}
         onAction={onAction}
         /* Exploration ekyb-desktop: on a tablet or desktop frame the two
-           fields share a row; on the phone nothing changes. */
+           fields stay on two rows, each spanning the column (Elena,
+           2026-09-28); `responsive` still pairs Continue and Back. On the
+           phone nothing changes. */
         responsive
         {...shell}
       >
-        <PrizmaFormRow>
         <PrizmaTextField
           label={copy.businessName.label}
           placeholder={copy.businessName.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.businessName ?? ''}
         />
@@ -139,10 +157,10 @@ export const EkybBusinessDetailsScreen = forwardRef<
           placeholder={copy.taxId.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.taxId ?? ''}
         />
-        </PrizmaFormRow>
       </PrizmaFormScreen>
     );
   },

package/src/EkybCountryScreen.tsx

@@ -1,5 +1,6 @@
 import React, { forwardRef } from 'react';
 import { PrizmaDropdown } from '@incodetech/prizma-core-web/dropdown';
+import { PrizmaCountryFlag } from '@incodetech/prizma-core-web/combined';
 import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type { EkybCountryState, EkybOption, EkybStrings } from './EkybStrings';
@@ -55,14 +56,22 @@ export interface EkybCountryScreenProps
  *    live interaction) — the same mechanism Phone Input's `countryCode` and
  *    CURP's `Gene.dropdown` sections use. The search bar Figma draws inside the
  *    menu is Core's own `searchable`.
- * 3. The closed field and the menu row are DIFFERENT faces of one option:
- *    5707:54174 draws "🇺🇸 United States" in the field while the rows read
- *    "🇺🇸 +1 United States". That is Core's `PrizmaDropdownOption.fieldLabel`,
- *    so nothing is hand-composed. The flag travels inside the label text
- *    because Core still ships no country-flag primitive (#PI-3).
+ * 3. Menu rows and the closed field read the same flag + "United States",
+ *    no dial code. Figma 5707:54174 draws the rows with Phone Input's "+1"
+ *    prefixes, dropped by the owner (Elena, 2026-09-28) because a country of
+ *    registration has no phone prefix. The flag is Core's raster in the
+ *    dropdown's leading slot, not an emoji in the label (Elena, 2026-10-23;
+ *    #PI-3, the WatchlistBusinessFormScreen precedent).
  *
  * This page is the only eKYB form page with NO "Back" secondary and NO Stepper —
  * it is step 0, before the three-step wizard starts.
+ *
+ * `emptyError` is Continue pressed with no country chosen (Elena, 2026-09-30,
+ * GUIDELINES §6-E empty-submit rule; precedent `FormsFieldScreen`'s
+ * `emptyError`): the dropdown renders empty, with no placeholder, in Core's
+ * `error` state with `requiredError` under it, and Continue is disabled. The
+ * field draws no `*`, but it is the page's only input and the flow cannot go on
+ * without it, so it is treated as required. `empty` keeps Continue enabled.
  */
 export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenProps>(
   (
@@ -72,6 +81,7 @@ export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenPro
       countries = [],
       value,
       screenId = `ekyb-country-${state}`,
+      ctaDisabled,
       overrides,
       onAction,
       ...shell
@@ -81,7 +91,9 @@ export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenPro
     const copy = strings.country;
     // `empty` is the only section drawn on the placeholder; both other sections
     // draw a chosen country in the closed field.
-    const selected = state === 'empty' ? null : (value ?? countries[0]?.value ?? null);
+    const emptyError = state === 'emptyError';
+    const selected =
+      state === 'empty' || emptyError ? null : (value ?? countries[0]?.value ?? null);
 
     return (
       <PrizmaFormScreen
@@ -89,6 +101,8 @@ export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenPro
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
+        /* Disabled only after the empty submit; `empty` keeps it enabled. */
+        ctaDisabled={emptyError || ctaDisabled}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
         screenId={screenId}
@@ -102,7 +116,15 @@ export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenPro
       >
         <PrizmaDropdown
           label={copy.field.label}
-          placeholder={copy.field.placeholder}
+          /* Required, but UNMARKED: a single-input screen shows no asterisk
+             and no legend (Core pattern "Optimistic submission", single-input
+             screens; Elena 2026-09-30). The requirement surfaces on submit,
+             through the empty-submit error. */
+          /* The error state draws the field with nothing in it, not even the
+             placeholder (the `FormsFieldScreen` precedent). */
+          placeholder={emptyError ? undefined : copy.field.placeholder}
+          error={emptyError}
+          errorText={emptyError ? strings.requiredError : undefined}
           options={countries}
           /* Uncontrolled: a screen is one static spec state, so no `onChange` is
              needed. Core's `readOnly`/`disabled` are NOT used to freeze it —
@@ -114,6 +136,22 @@ export const EkybCountryScreen = forwardRef<HTMLDivElement, EkybCountryScreenPro
           clearSearchLabel={copy.clearSearchLabel}
           /* The `dropdown` section IS the open-menu spec state. */
           forceOpen={state === 'dropdown'}
+          /* Core's canonical flag raster in the closed field and every menu
+             row (see note 3). A country outside the bank falls back to its
+             `flag` emoji. */
+          renderLeading={(option) => {
+            const match = countries.find((c) => c.value === option.value);
+            return match ? (
+              <PrizmaCountryFlag
+                country={{
+                  code: match.value,
+                  name: match.label,
+                  dialCode: '',
+                  flag: match.flag ?? '',
+                }}
+              />
+            ) : null;
+          }}
         />
       </PrizmaFormScreen>
     );

package/src/EkybOwnersScreen.tsx

@@ -59,6 +59,14 @@ export interface EkybOwnersScreenProps
  * - `loading`        5663:94390 — `directorFilled` with the submission in
  *   flight: every field, both "Add another" links and "Back" go inert, and the
  *   spinner rides the CTA, never a field (the Phone Input lesson, #PI-5)
+ * - `uboEmptyError` / `directorEmptyError` (no frame) — `uboEmpty` /
+ *   `directorEmpty` after Continue was pressed with the fields still empty
+ *   (Elena, 2026-09-30, GUIDELINES §6-E empty-submit rule; precedent
+ *   `FormsFieldScreen`'s `emptyError`): every field renders empty, the two
+ *   REQUIRED UBO fields in Core's `error` state with `requiredError` and no
+ *   placeholder, the optional Director fields unflagged, and Continue
+ *   disabled. The `*Empty` states keep Continue enabled so the press can
+ *   happen.
  *
  * Four things are deliberate:
  *
@@ -99,8 +107,9 @@ export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps
     {
       strings,
       state = 'uboEmpty',
-      values,
+      values: valuesProp,
       screenId = `ekyb-owners-${state}`,
+      ctaDisabled,
       className,
       overrides,
       onAction,
@@ -111,8 +120,20 @@ export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps
     const copy = strings.owners;
     const busy = state === 'loading';
     const secondUbo = state === 'uboAdded';
+    const emptyError = state === 'uboEmptyError' || state === 'directorEmptyError';
+    const values = emptyError ? undefined : valuesProp;
     const showDirector =
-      state === 'directorEmpty' || state === 'directorFilled' || secondUbo || busy;
+      state === 'directorEmpty' ||
+      state === 'directorFilled' ||
+      state === 'directorEmptyError' ||
+      secondUbo ||
+      busy;
+    // Core's own error treatment, spread AFTER each required UBO field's own
+    // placeholder so the error state shows none (the `FormsFieldScreen`
+    // precedent). The Director fields are optional and never receive it.
+    const missing = emptyError
+      ? { error: true, errorText: strings.requiredError, placeholder: undefined }
+      : {};
 
     return (
       <PrizmaFormScreen
@@ -134,6 +155,9 @@ export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
+        /* Disabled only after the empty submit; the `*Empty` states keep it
+           enabled. */
+        ctaDisabled={emptyError || ctaDisabled}
         /* `loading` swaps the CTA label for Core's designed spinner. */
         ctaLoading={busy}
         ctaLoadingLabel={copy.ctaLoadingLabel}
@@ -164,14 +188,19 @@ export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps
           placeholder={copy.uboName.placeholder}
           required
           requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.uboName ?? ''}
           disabled={busy}
         />
-        {/* Figma draws no asterisk on the surname — it is optional. */}
+        {/* Required since 2026-09-28 (Elena): the frames drew no asterisk on the
+            surname, but a beneficial owner needs both names. */}
         <PrizmaTextField
           label={copy.uboSurname.label}
           placeholder={copy.uboSurname.placeholder}
+          required
+          requiredHint={strings.requiredHint}
+          {...missing}
           autoComplete="off"
           defaultValue={values?.uboSurname ?? ''}
           disabled={busy}
@@ -192,6 +221,8 @@ export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps
               <PrizmaTextField
                 label={copy.uboSurname.label}
                 placeholder={copy.uboSurname.placeholder}
+                required
+                requiredHint={strings.requiredHint}
                 autoComplete="off"
                 defaultValue={values?.secondUboSurname ?? ''}
               />

package/src/EkybStrings.ts

@@ -34,15 +34,21 @@
  * - `dropdown` — the same selection with the MENU OPEN over the form: search
  *   bar plus the country rows (Core's documentation-only `forceOpen`, since a
  *   screen is one static spec state and never a live interaction)
+ * - `emptyError` — Continue was pressed with no country chosen (GUIDELINES
+ *   §6-E empty-submit rule, Elena 2026-09-30): the dropdown in Core's error
+ *   state with `requiredError`, Continue disabled. Not a Figma frame.
  */
-export type EkybCountryState = 'empty' | 'filled' | 'dropdown';
+export type EkybCountryState = 'empty' | 'filled' | 'dropdown' | 'emptyError';
 
 /** The two `eKYB.Bdetails` (business identity) sections: every field on its
- *  resting empty surface, or every field carrying a value. */
-export type EkybBusinessState = 'empty' | 'filled';
+ *  resting empty surface, or every field carrying a value — plus `emptyError`,
+ *  Continue pressed with the fields empty (empty-submit rule, 2026-09-30):
+ *  every required field in Core's error state, Continue disabled. */
+export type EkybBusinessState = 'empty' | 'filled' | 'emptyError';
 
-/** The two address sections (the SECOND `eKYB.Bdetails` parent). Same axis. */
-export type EkybAddressState = 'empty' | 'filled';
+/** The two address sections (the SECOND `eKYB.Bdetails` parent). Same axis,
+ *  same `emptyError` (the optional Address line 2 shows no error). */
+export type EkybAddressState = 'empty' | 'filled' | 'emptyError';
 
 /**
  * The `eKYB.UBO.*` and `eKYB.director.*` sections — one screen family, because
@@ -63,6 +69,11 @@ export type EkybAddressState = 'empty' | 'filled';
  *   flight, so EVERY field, both "Add another" links and "Back" go inert and
  *   the spinner rides the CTA, never a field (the Phone Input lesson,
  *   DEVIATIONS #PI-5)
+ * - `uboEmptyError` / `directorEmptyError` — `uboEmpty` / `directorEmpty` after
+ *   Continue was pressed with the fields empty (GUIDELINES §6-E empty-submit
+ *   rule, Elena 2026-09-30): the two REQUIRED UBO fields in Core's error state
+ *   with `requiredError`, the optional Director fields unflagged, Continue
+ *   disabled. Not Figma frames.
  */
 export type EkybOwnersState =
   | 'uboEmpty'
@@ -70,7 +81,9 @@ export type EkybOwnersState =
   | 'directorEmpty'
   | 'directorFilled'
   | 'uboAdded'
-  | 'loading';
+  | 'loading'
+  | 'uboEmptyError'
+  | 'directorEmptyError';
 
 /**
  * One selectable row in the country / state menus. Runtime data, not copy — the
@@ -84,10 +97,14 @@ export interface EkybOption {
   /** The row label as drawn in the open menu. */
   label: string;
   /** Compact face for the CLOSED field when it differs from the menu row —
-   *  Core's own `PrizmaDropdownOption.fieldLabel`. `eKYB.country.dropdown`
-   *  draws "🇺🇸 +1 United States" in the row and "🇺🇸 United States" in the
-   *  field. */
+   *  Core's own `PrizmaDropdownOption.fieldLabel`. The eKYB country list
+   *  does not need it: rows and field both read "United States" after the
+   *  flag. */
   fieldLabel?: string;
+  /** Country menus only: the emoji fallback for a `value` outside Core's
+   *  flag raster bank. The country screen draws the bank's flag by `value`,
+   *  so this never travels inside `label`. */
+  flag?: string;
 }
 
 /** The values the business-identity page carries. Runtime data, never copy. */
@@ -139,6 +156,13 @@ export interface EkybStrings {
    * localizable and never hardcoded in a screen.
    */
   requiredHint?: string;
+  /**
+   * Under every empty REQUIRED field once the primary was pressed with it
+   * still empty — the `emptyError` states (GUIDELINES §6-E empty-submit rule,
+   * Elena 2026-09-30). Core's own `errorText` slot; SDK key
+   * `dynamicForms.fieldRequired`.
+   */
+  requiredError: string;
   /** Shared "Back" secondary action drawn under "Continue" on every page except
    *  `country`. Emits `secondary`. */
   backLabel: string;
@@ -217,7 +241,7 @@ export interface EkybStrings {
     title: string;
     subtitle?: string;
     uboName: EkybFieldStrings;
-    /** Figma draws NO `*` on the surname — it is optional. */
+    /** Required, like the name (Elena, 2026-09-28); the frames drew no `*`. */
     uboSurname: EkybFieldStrings;
     /** The tertiary link under the UBO block ("Add another UBO (Optional)"). */
     addUboLabel: string;