@incodetech/prizma-core-screens 0.2.4 → 0.2.7

package/dist/FormsLongFormScreen.js

@@ -33,7 +33,9 @@ const PRESET_ROWS = {
         { key: 'idNumber', kind: 'text', requirement: 'required' },
         { key: 'email', kind: 'email', requirement: 'required' },
         { key: 'residence', kind: 'country', requirement: 'required' },
-        { key: 'dob', kind: 'date', requirement: 'required' },
+        // Date of birth carries NO asterisk (owner Elena, 2026-09-30), so the
+        // `emptyError` state flags the other three rows and leaves it at rest.
+        { key: 'dob', kind: 'date', requirement: 'none' },
     ],
 };
 /**
@@ -85,10 +87,19 @@ const OPTIONAL_VARIANT = {
  * into the CTA band — the half a module stylesheet kept losing. It is a no-op
  * on the short `name` preset, whose rows never overflow. DEVIATIONS #DSC-2,
  * restating #CURP-1.
+ *
+ * `emptyError` is the GUIDELINES §6-E empty-submit rule (Elena 2026-09-30):
+ * the user pressed the CTA with the form still empty. Every REQUIRED row
+ * renders empty, with no placeholder, in Core's own error state carrying
+ * `strings.requiredError`; optional and unmarked rows stay on their resting
+ * surface with no error. The CTA greys there and ONLY there: the resting
+ * `default` keeps it enabled, so the user can press it to reach the error —
+ * the `FormsFieldScreen` `emptyError` precedent applied to a stack.
  */
 export const FormsLongFormScreen = forwardRef(({ strings, preset = 'eKyc', state = 'default', values, focusedField, options, countries, screenId = `forms-long-form-${preset}-${state}`, className, overrides, onAction, ...shell }, ref) => {
     const copy = strings.longForm[preset];
     const busy = state === 'loading';
+    const emptyError = state === 'emptyError';
     const countryList = countries ?? [];
     // The Optional / Required pair documents the eKYC form specifically; no
     // other preset draws it, so the override never leaks to a preset whose
@@ -106,20 +117,30 @@ export const FormsLongFormScreen = forwardRef(({ strings, preset = 'eKyc', state
         const fieldCopy = copy.fields[row.key];
         const label = labelFor(row);
         const required = row.requirement === 'required';
-        const value = values?.[row.key] ?? '';
-        const focused = !busy && focusedField === row.key;
+        // `emptyError` is an EMPTY submit: every row renders empty, whatever
+        // values the host passed.
+        const value = emptyError ? '' : (values?.[row.key] ?? '');
+        const focused = !busy && !emptyError && focusedField === row.key;
+        // Only REQUIRED rows flag the empty submit. Their placeholder goes, as
+        // on the drawn `forms.IDnumber.error`; optional rows stay at rest.
+        const invalid = emptyError && required;
+        const errorText = invalid ? strings.requiredError : undefined;
+        const placeholder = invalid ? undefined : fieldCopy?.placeholder;
         switch (row.kind) {
             case 'country':
-                return (_jsx(PrizmaDropdown, { label: label, required: required, requiredHint: strings.requiredHint, placeholder: fieldCopy?.placeholder, options: countryList.map((c) => ({ value: c.code, label: c.name })), value: value || null, searchable: true, searchPlaceholder: copy.searchPlaceholder, disabled: busy, forceState: focused ? 'focused' : undefined, renderLeading: (option) => {
+                return (_jsx(PrizmaDropdown, { label: label, required: required, requiredHint: strings.requiredHint, placeholder: placeholder, options: countryList.map((c) => ({ value: c.code, label: c.name })), value: value || null, searchable: true, searchPlaceholder: copy.searchPlaceholder, disabled: busy, error: invalid, errorText: errorText, forceState: focused ? 'focused' : undefined, renderLeading: (option) => {
                         const match = countryList.find((c) => c.code === option.value);
                         return match ? _jsx(PrizmaCountryFlag, { country: match }) : null;
                     } }, row.key));
             case 'select':
-                return (_jsx(PrizmaDropdown, { label: label, required: required, requiredHint: strings.requiredHint, placeholder: fieldCopy?.placeholder, options: options?.[row.key] ?? [], value: value || null, disabled: busy, forceState: focused ? 'focused' : undefined }, row.key));
+                return (_jsx(PrizmaDropdown, { label: label, required: required, requiredHint: strings.requiredHint, placeholder: placeholder, options: options?.[row.key] ?? [], value: value || null, disabled: busy, error: invalid, errorText: errorText, forceState: focused ? 'focused' : undefined }, row.key));
             case 'date':
-                return (_jsx(PrizmaDateField, { className: focused ? 'prizma-input-datefield--focused' : undefined, label: label, required: required, requiredHint: strings.requiredHint, placeholder: fieldCopy?.placeholder, defaultValue: value, disabled: busy, calendarLabel: copy.calendarLabel }, row.key));
+                return (_jsx(PrizmaDateField, { className: focused ? 'prizma-input-datefield--focused' : undefined, label: label, required: required, requiredHint: strings.requiredHint, 
+                    /* Core falls back to its DD/MM/YYYY mask on an undefined
+                       placeholder, so the error row passes an explicit empty one. */
+                    placeholder: invalid ? '' : fieldCopy?.placeholder, defaultValue: value, disabled: busy, error: invalid, errorText: errorText, calendarLabel: copy.calendarLabel }, row.key));
             default:
-                return (_jsx(PrizmaTextField, { className: focused ? 'prizma-input-textfield--focused' : undefined, label: label, required: required, requiredHint: strings.requiredHint, placeholder: fieldCopy?.placeholder, defaultValue: value, type: row.kind === 'email' ? 'email' : 'text', inputMode: row.kind === 'email' ? 'email' : undefined, autoComplete: row.kind === 'email' ? 'email' : 'off', autoCapitalize: row.kind === 'email' ? 'none' : undefined, spellCheck: false, disabled: busy, 
+                return (_jsx(PrizmaTextField, { className: focused ? 'prizma-input-textfield--focused' : undefined, label: label, required: required, requiredHint: strings.requiredHint, placeholder: placeholder, defaultValue: value, type: row.kind === 'email' ? 'email' : 'text', inputMode: row.kind === 'email' ? 'email' : undefined, autoComplete: row.kind === 'email' ? 'email' : 'off', autoCapitalize: row.kind === 'email' ? 'none' : undefined, spellCheck: false, disabled: busy, error: invalid, errorText: errorText, 
                     /* Figma draws the clear ✕ only on the focused row of
                        `longform.focused`; every other row draws none. */
                     clearable: focused, clearLabel: copy.clearLabel }, row.key));
@@ -134,12 +155,12 @@ export const FormsLongFormScreen = forwardRef(({ strings, preset = 'eKyc', state
         ]
             .filter(Boolean)
             .join(' '), title: copy.title, subtitle: copy.subtitle, ctaLabel: copy.ctaLabel, 
-        /* `longform.default` and `longform.customizable`'s default section grey
-           the CTA until something is entered; `forms.name` draws it ENABLED on
-           the same empty form. Figma contradicts its own "optimistic rule"
-           sticky here, so each section is followed literally — DEVIATIONS
-           #FDE-3. */
-        ctaDisabled: state === 'default' && preset !== 'name', ctaLoading: busy, ctaLoadingLabel: copy.ctaLoadingLabel, 
+        /* GUIDELINES §6-E empty-submit rule (Elena 2026-09-30): the CTA stays
+           ENABLED on the resting empty form, every preset alike, so the user
+           can press it; it greys only on `emptyError`, the state that press
+           leads to. This supersedes the per-section greying #FDE-3 followed
+           on `longform.default` and `longform.customizable`. */
+        ctaDisabled: emptyError, ctaLoading: busy, ctaLoadingLabel: copy.ctaLoadingLabel, 
         /* The four- and five-row stacks are taller than the 844 frame; the
            archetype's variant pans them and keeps Spacing/16 of clear surface
            above the CTA. No module CSS re-declares this. */

package/dist/FormsStrings.d.ts

@@ -80,8 +80,12 @@ export type FormsLongFormPreset = 'name' | 'profile' | 'eKyc';
  * - `loading`  — `longform.loading`: the whole form greyed, spinner in the CTA
  * - `optional` — the "Optional / Required" documentation pair: the same form
  *                with mixed required and optional markers
+ * - `emptyError` — the user pressed the CTA with the form still empty: every
+ *                REQUIRED row renders empty in Core's error state with
+ *                `requiredError`, optional and unmarked rows stay clean, CTA
+ *                greyed (GUIDELINES §6-E empty-submit rule, Elena 2026-09-30)
  */
-export type FormsLongFormState = 'default' | 'focused' | 'filled' | 'loading' | 'optional';
+export type FormsLongFormState = 'default' | 'focused' | 'filled' | 'loading' | 'optional' | 'emptyError';
 /** Copy for one single-field section. */
 export interface FormsFieldCopy {
     /** H2 ("Enter your title", "Enter your email", "Enter your phone number"). */
@@ -161,6 +165,12 @@ export interface FormsStrings {
      * the label string by the screen. See DEVIATIONS #FDE-4.
      */
     optionalHint: string;
+    /**
+     * The error row every REQUIRED field shows on the `emptyError` long-form
+     * state ("This field is required"). Maps to the SDK's
+     * `dynamicForms.fieldRequired` key. GUIDELINES §6-E empty-submit rule.
+     */
+    requiredError: string;
     /** The single-field sections. */
     fields: Record<FormsFieldKey, FormsFieldCopy>;
     /** The choice sections. */

package/dist/GeolocationBrowserStepsScreen.d.ts

@@ -31,9 +31,13 @@ export interface GeolocationBrowserStepsScreenProps extends Omit<PrizmaListScree
  * The rows are Core's `PrizmaCardListCommonIssues` verbatim; only the leading
  * glyph is chosen here, from the canonical bank (see `STEP_ICONS`).
  *
+ * No subtitle: the browser name (`label`) is NOT drawn under the title (owner
+ * call, Elena 2026-09-30). The label stays in the strings as the section's
+ * identifier for hosts and catalogs; the screen itself shows title + steps.
+ *
  * The title block is LEFT-aligned for this whole family. Every
- * `Geolocation.allowLocation.<browser>` section starts the two-line headline —
- * and the browser label under it — flush at the gutter, over left-led step
+ * `Geolocation.allowLocation.<browser>` section starts the two-line headline
+ * flush at the gutter, over left-led step
  * rows; a centred headline above a left-aligned list reads as a mistake. The
  * screen therefore DEFAULTS the archetype's own `align` override to `left`
  * rather than declaring any alignment of its own, and a host that passes

package/dist/GeolocationBrowserStepsScreen.js

@@ -55,9 +55,13 @@ const STEP_ICONS = {
  * The rows are Core's `PrizmaCardListCommonIssues` verbatim; only the leading
  * glyph is chosen here, from the canonical bank (see `STEP_ICONS`).
  *
+ * No subtitle: the browser name (`label`) is NOT drawn under the title (owner
+ * call, Elena 2026-09-30). The label stays in the strings as the section's
+ * identifier for hosts and catalogs; the screen itself shows title + steps.
+ *
  * The title block is LEFT-aligned for this whole family. Every
- * `Geolocation.allowLocation.<browser>` section starts the two-line headline —
- * and the browser label under it — flush at the gutter, over left-led step
+ * `Geolocation.allowLocation.<browser>` section starts the two-line headline
+ * flush at the gutter, over left-led step
  * rows; a centred headline above a left-aligned list reads as a mistake. The
  * screen therefore DEFAULTS the archetype's own `align` override to `left`
  * rather than declaring any alignment of its own, and a host that passes
@@ -85,7 +89,7 @@ export const GeolocationBrowserStepsScreen = forwardRef(({ strings, browser = 's
         ...overrides,
         align: overrides?.align ?? 'left',
     };
-    return (_jsx(PrizmaListScreen, { ref: ref, title: strings.browserSteps.title, subtitle: slice?.label, ctaLabel: strings.browserSteps.ctaLabel, secondaryCtaLabel: showSkip ? strings.browserSteps.skipLabel : undefined, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: alignedOverrides, onAction: onAction, ...shell, children: _jsx(PrizmaCardListCommonIssues, { items: (slice?.steps ?? []).map((step) => ({
+    return (_jsx(PrizmaListScreen, { ref: ref, title: strings.browserSteps.title, ctaLabel: strings.browserSteps.ctaLabel, secondaryCtaLabel: showSkip ? strings.browserSteps.skipLabel : undefined, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: alignedOverrides, onAction: onAction, ...shell, children: _jsx(PrizmaCardListCommonIssues, { items: (slice?.steps ?? []).map((step) => ({
                 icon: STEP_ICONS[step.kind],
                 title: step.label,
                 showSubtitle: false,

package/dist/GeolocationStrings.d.ts

@@ -76,6 +76,9 @@ export interface GeolocationBrowserSteps {
      * rows and would render as one screen three times. Every browser therefore
      * SHOULD carry a label, extending the precedent Figma itself sets on Safari.
      * Still optional so a host that ships its own logo artwork can drop it.
+     *
+     * 2026-09-30 (Elena): the screen no longer RENDERS it as a subtitle. It is
+     * kept as the section's name for catalogs and hosts, not as on-screen copy.
      */
     label?: string;
     /** The steps, in order. */

package/dist/IdCaptureLayout.css

@@ -59,6 +59,46 @@
   gap: var(--prizma-spacing-8); /* Title → instruction, GUIDELINES §5 */
 }
 
+/* ── Short screens: the vertical frame gives up height, never the title ──────
+ * The vertical ID (288:456) and passport (306:420) frames are tall. On a
+ * 320 × 693 phone the column is 272 wide, so the frame alone is ~431 tall and
+ * the stage ran 168px past the bottom, under the shutter strip (Camila,
+ * 2026-09-28). Here the frame is the ONE part of the column that shrinks: it
+ * starts at its full-width height (the column less its two Spacing/24
+ * gutters, over the aspect), and when the screen is too short the flex column
+ * takes the shortfall out of its height; the aspect ratio then narrows its
+ * width to match, so it stays an ID-shaped frame, centred. The title band
+ * keeps its content height. With room to spare (390 × 844) the frame never
+ * needs to shrink, so it sits exactly where it did.
+ *
+ * Scoped to ID + passport with `:not(--poa)`: Document Capture renders the
+ * same stage as `type="poa" isVertical`, so it carries `--vertical` too, but
+ * the PoA frame has NO aspect ratio (it fills the host's height). `width:
+ * auto` there collapsed it to a 0-wide sliver, a grey vertical bar down the
+ * camera screen (Elena, 2026-09-30). Only showed where this file and Document
+ * Capture's CSS ship in the same bundle, i.e. the production build. */
+.prizma-viewfinder__content:has(> .prizma-id-capture--vertical:not(.prizma-id-capture--poa)) {
+  min-height: 0;
+}
+.prizma-viewfinder__content:has(> .prizma-id-capture--vertical:not(.prizma-id-capture--poa)) > .id-capture-band--top {
+  flex-shrink: 0;
+  min-height: min-content;
+}
+.prizma-viewfinder__content > .prizma-id-capture--vertical:not(.prizma-id-capture--poa) {
+  flex: 0 1 auto;
+  min-height: 0;
+}
+.prizma-viewfinder__content > .prizma-id-capture--vertical:not(.prizma-id-capture--poa) .prizma-id-capture__frame {
+  flex: 0 1 auto;
+  min-height: 0;
+  width: auto;
+  max-width: 100%;
+  flex-basis: calc((100cqw - 2 * var(--prizma-spacing-24)) * 456 / 288);
+}
+.prizma-viewfinder__content > .prizma-id-capture--passport.prizma-id-capture--vertical .prizma-id-capture__frame {
+  flex-basis: calc((100cqw - 2 * var(--prizma-spacing-24)) * 420 / 306);
+}
+
 /* ── Camera stage (dark) ───────────────────────────────────────────────────── */
 
 /* The stage's nav row carries only the close X (no logo — the camera owns the

package/dist/ListScreen.d.ts

@@ -64,6 +64,8 @@ export interface PrizmaListScreenProps extends Omit<PrizmaScreenShellProps, 'dar
     /** "verified by" attribution copy for the footer tag. */
     verifiedLabel: string;
     navLabel?: string;
+    /** Opt-in back chevron in the nav (its accessible name). Emits `back`. */
+    backLabel?: string;
     screenId?: string;
     overrides?: PrizmaScreenOverrides;
     onAction?: PrizmaScreenActionHandler;

package/dist/ListScreen.js

@@ -31,7 +31,7 @@ import './ScreenLayout.css';
  * Reach for `PrizmaResultScreen` instead when the middle is a centred verdict
  * rather than a list.
  */
-export const PrizmaListScreen = forwardRef(({ progress, status = 'none', title, subtitle, glyph, children, listAlign = 'start', scrollList = false, disclaimer, ctaLabel, secondaryCtaLabel, linkLabel, verifiedLabel, navLabel, screenId, showHeader = true, showFooter = true, overrides, onAction, ...shell }, ref) => (_jsxs(PrizmaScreenShell, { ref: ref, ...shell, children: [_jsx(PrizmaScreenNav, { reserved: !showHeader, logo: overrides?.logo, navLabel: navLabel }), progress ? (_jsx("div", { className: "prizma-screen-layout__progress", children: progress })) : null, _jsxs("div", { className: "prizma-screen-layout__content", children: [glyph, _jsx(PrizmaTitle, { variant: overrides?.align === 'left' ? 'left' : 'centered', title: title, showSubtitle: Boolean(subtitle), subtitle: subtitle, icon: status === 'loading'
+export const PrizmaListScreen = forwardRef(({ progress, status = 'none', title, subtitle, glyph, children, listAlign = 'start', scrollList = false, disclaimer, ctaLabel, secondaryCtaLabel, linkLabel, verifiedLabel, navLabel, backLabel, screenId, showHeader = true, showFooter = true, overrides, onAction, ...shell }, ref) => (_jsxs(PrizmaScreenShell, { ref: ref, ...shell, children: [_jsx(PrizmaScreenNav, { reserved: !showHeader, logo: overrides?.logo, navLabel: navLabel, backLabel: backLabel, onBack: () => onAction?.({ type: 'back', screenId }) }), progress ? (_jsx("div", { className: "prizma-screen-layout__progress", children: progress })) : null, _jsxs("div", { className: "prizma-screen-layout__content", children: [glyph, _jsx(PrizmaTitle, { variant: overrides?.align === 'left' ? 'left' : 'centered', title: title, showSubtitle: Boolean(subtitle), subtitle: subtitle, icon: status === 'loading'
                         ? { type: 'spinner' }
                         : status === 'none'
                             ? { type: 'none' }

package/dist/PhoneInputLayout.css

@@ -21,6 +21,7 @@
   align-items: flex-start;
   gap: var(--prizma-spacing-8);
   width: 100%;
+  position: relative; /* the country menu's containing block — see below */
 }
 
 /* The dial-code dropdown hugs its content ("🇷🇸 +381"), as Figma draws it.
@@ -47,15 +48,15 @@
   min-width: 0;
 }
 
-/* The open menu must NOT inherit the hugged anchor's width: Core anchors the
- * menu to the trigger, so once the trigger hugs "🇷🇸 +381" the option rows
- * truncate ("+…"). The menu keeps its own readable width — it lists country
- * names and dial codes, which the closed field never shows. Sized to the
- * content and capped at the 342 column so it never escapes the screen.
+/* The open menu spans the WHOLE row (dial code + number field), as Figma's
+ * `Input / Combined` draws it: Core anchors the menu overlay to the trigger's
+ * `__anchor` (`position: relative`, Dropdown.css), so once the trigger hugs
+ * "🇷🇸 +381" the menu came out as narrow as the dial code. Releasing the
+ * anchor's positioning hands the overlay's `left: 0; right: 0` to the row
+ * above (`position: relative`), so the menu matches the row's width exactly.
+ * Core's own overlay offset (`top: 100% + Spacing/8`) is left untouched.
  * DEVIATIONS #PI-1 (same root cause as the hug).
  */
-.phone-input-combined__country .prizma-dropdown__menu {
-  width: max-content;
-  min-width: 100%;
-  max-width: 342px;
+.phone-input-combined__country .prizma-dropdown__anchor {
+  position: static;
 }

package/dist/PhoneInputStrings.d.ts

@@ -7,8 +7,12 @@
  * - `typing`      — partial value, focused field
  * - `filled`      — complete value
  * - `loading`     — CTA in its loading treatment while the code is requested
+ * - `emptyError`  — "Continue" pressed with no number typed: the phone field
+ *   stays empty (no placeholder) in Core's error state with `requiredError`,
+ *   and the CTA is disabled. The dial code always carries a selection, so it
+ *   takes no error. GUIDELINES §6-E empty-submit rule (Elena, 2026-09-30).
  */
-export type PhoneInputVerifyState = 'default' | 'countryCode' | 'typing' | 'filled' | 'loading';
+export type PhoneInputVerifyState = 'default' | 'countryCode' | 'typing' | 'filled' | 'loading' | 'emptyError';
 /**
  * The `phoneNumber.OTP.*` sections — same layout, different field state:
  * - `typing`     — partial code
@@ -41,6 +45,12 @@ export interface PhoneInputStrings {
     verifiedLabel: string;
     /** Accessible name for the logo nav row. */
     navLabel?: string;
+    /**
+     * Error row under the required field when the primary CTA is pressed with it
+     * still empty (the verify screen's `emptyError` state): "This field is
+     * required". SDK key `dynamicForms.fieldRequired`.
+     */
+    requiredError: string;
     /** phoneNumber.verify.* */
     verify: {
         /** H2 ("Verify your phone number"). */

package/dist/PhoneInputVerifyScreen.d.ts

@@ -36,6 +36,14 @@ export interface PhoneInputVerifyScreenProps extends Omit<PrizmaFormScreenProps,
  * primitives (`PrizmaDropdown`, `PrizmaTextField`) at the designed 56px min
  * height and `Border/Radius/small`, so the module layer contributes only the
  * row that pairs them (`PhoneInputLayout.css`) — no primitive is re-implemented.
+ *
+ * `emptyError` is the empty-submit state (rule from Elena, 2026-09-30,
+ * GUIDELINES §6-E empty-submit rule): "Continue" was pressed with no number
+ * typed. The phone field renders empty with no placeholder, in Core's error
+ * state with `requiredError`, and the primary CTA is disabled, following the
+ * drawn precedent in `FormsFieldScreen`. The dial code always carries a
+ * selection, so it takes no error. The resting `default` keeps the CTA enabled
+ * so the user can reach this state.
  */
 export declare const PhoneInputVerifyScreen: React.ForwardRefExoticComponent<PhoneInputVerifyScreenProps & React.RefAttributes<HTMLDivElement>>;
 export default PhoneInputVerifyScreen;

package/dist/PhoneInputVerifyScreen.js

@@ -29,14 +29,24 @@ const DEFAULT_COUNTRIES = [
  * primitives (`PrizmaDropdown`, `PrizmaTextField`) at the designed 56px min
  * height and `Border/Radius/small`, so the module layer contributes only the
  * row that pairs them (`PhoneInputLayout.css`) — no primitive is re-implemented.
+ *
+ * `emptyError` is the empty-submit state (rule from Elena, 2026-09-30,
+ * GUIDELINES §6-E empty-submit rule): "Continue" was pressed with no number
+ * typed. The phone field renders empty with no placeholder, in Core's error
+ * state with `requiredError`, and the primary CTA is disabled, following the
+ * drawn precedent in `FormsFieldScreen`. The dial code always carries a
+ * selection, so it takes no error. The resting `default` keeps the CTA enabled
+ * so the user can reach this state.
  */
 export const PhoneInputVerifyScreen = forwardRef(({ strings, state = 'default', countries = DEFAULT_COUNTRIES, country, value, screenId = `phone-input-verify-${state}`, overrides, onAction, ...shell }, ref) => {
     const selected = country ?? countries[0]?.value;
     const options = countries.map((c) => ({
         value: c.value,
-        // The closed field shows flag + dial code exactly as Figma draws it
-        // ("🇷🇸 +381"); the open menu row adds the country name.
-        label: [c.flag, c.dialCode].filter(Boolean).join(' '),
+        // The open menu row reads flag + dial code + country name
+        // ("🇷🇸 +381 Serbia"); the closed field keeps only flag + dial code
+        // ("🇷🇸 +381") through Core's `fieldLabel`, exactly as Figma draws it.
+        label: [c.flag, c.dialCode, c.label].filter(Boolean).join(' '),
+        fieldLabel: [c.flag, c.dialCode].filter(Boolean).join(' '),
     }));
     // Figma treats the states as three distinct field treatments, not one:
     // `loading` greys BOTH fields (the request is in flight and the form is
@@ -47,9 +57,12 @@ export const PhoneInputVerifyScreen = forwardRef(({ strings, state = 'default',
     // for none of them — it would grey the resting states too (DEVIATIONS #PI-6).
     const busy = state === 'loading';
     const focused = state === 'typing';
+    // Empty submit: the number field drops its placeholder and takes Core's
+    // error state with the shared "required" row; the CTA greys.
+    const emptyError = state === 'emptyError';
     return (_jsx(PrizmaFormScreen, { ref: ref, title: strings.verify.title, subtitle: strings.verify.subtitle, ctaLabel: strings.verify.ctaLabel, 
         /* Figma's `loading` section swaps the CTA label for Core's spinner. */
-        ctaLoading: busy, ctaLoadingLabel: strings.verify.ctaLoadingLabel, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell, children: _jsxs("div", { className: "phone-input-combined", children: [_jsx(PrizmaDropdown, { className: "phone-input-combined__country", "aria-label": strings.verify.countryLabel, options: options, value: selected, searchable: true, searchPlaceholder: strings.verify.countrySearchPlaceholder, 
+        ctaLoading: busy, ctaDisabled: emptyError, ctaLoadingLabel: strings.verify.ctaLoadingLabel, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell, children: _jsxs("div", { className: "phone-input-combined", children: [_jsx(PrizmaDropdown, { className: "phone-input-combined__country", "aria-label": strings.verify.countryLabel, options: options, value: selected, searchable: true, searchPlaceholder: strings.verify.countrySearchPlaceholder, 
                     /* The `countryCode` section IS the open-menu spec state. */
                     forceOpen: state === 'countryCode', disabled: busy }), _jsx(PrizmaTextField, { className: [
                         'phone-input-combined__number',
@@ -59,11 +72,11 @@ export const PhoneInputVerifyScreen = forwardRef(({ strings, state = 'default',
                         focused ? 'prizma-input-textfield--focused' : '',
                     ]
                         .filter(Boolean)
-                        .join(' '), type: "tel", inputMode: "tel", "aria-label": strings.verify.fieldLabel, placeholder: strings.verify.placeholder, 
+                        .join(' '), type: "tel", inputMode: "tel", "aria-label": strings.verify.fieldLabel, placeholder: emptyError ? undefined : strings.verify.placeholder, 
                     /* Uncontrolled: a screen is one static spec state, and `value`
                        without `onChange` would either warn or force `readOnly`, whose
                        disabled surface is exactly the grey Figma does NOT draw here. */
-                    defaultValue: value ?? '', disabled: busy, 
+                    defaultValue: emptyError ? '' : value ?? '', disabled: busy, error: emptyError, errorText: emptyError ? strings.requiredError : undefined, 
                     /* Figma draws the clear ✕ only while the field is focused. */
                     clearable: focused })] }) }));
 });

package/dist/QualifiedSignatureAcceptScreen.js

@@ -62,6 +62,7 @@ export const QualifiedSignatureAcceptScreen = forwardRef(({ strings, variant = '
     // `loading` makes the whole form inert.
     const busy = state === 'loading';
     const ticked = state !== 'default';
+    const requiredHint = strings.accept.requiredHint;
     return (_jsxs(PrizmaFormScreen, { ref: ref, className: ['qualified-signature-accept', className].filter(Boolean).join(' '), title: copy.title, subtitle: copy.subtitle, ctaLabel: copy.ctaLabel, ctaDisabled: !ticked, ctaLoading: busy, ctaLoadingLabel: copy.ctaLoadingLabel, 
         /* The clause stack pans inside the column — the archetype owns this now
            (`--scroll`), so the module declares no overflow of its own. #QS-1 */
@@ -80,7 +81,11 @@ export const QualifiedSignatureAcceptScreen = forwardRef(({ strings, variant = '
                action outright while the partner's `loading` frame greys it. Two
                Figma readings of one inert state; Core models inert as disabled,
                so both take the greyed treatment and the removal is logged. */
-            _jsx(PrizmaCardDocumentContainer, { filename: filename, actionLabel: strings.accept.viewLabel, actionDisabled: busy, onAction: () => onAction?.({ type: 'tertiary', screenId }) })) : null, _jsx("div", { className: "qualified-signature-terms", role: "group", "aria-label": strings.accept.termsLabel, children: terms.map((term) => (_jsx(PrizmaCheckbox, { size: "L", name: term.id, value: term.id, checked: ticked, disabled: busy, segments: term.segments }, term.id))) })] }));
+            _jsx(PrizmaCardDocumentContainer, { filename: filename, actionLabel: strings.accept.viewLabel, actionDisabled: busy, onAction: () => onAction?.({ type: 'tertiary', screenId }) })) : null, _jsxs("div", { className: "qualified-signature-terms", role: "group", "aria-label": strings.accept.termsLabel, children: [requiredHint && strings.accept.requiredLegend ? (_jsx("p", { className: "qualified-signature-terms__legend", children: strings.accept.requiredLegend })) : null, terms.map((term) => (_jsx(PrizmaCheckbox, { size: "L", name: term.id, value: term.id, checked: ticked, disabled: busy, required: Boolean(requiredHint), 
+                        /* The `*` rides the END of the clause copy, the Data Sharing
+                           Consent idiom — the L card paints no marker of its own beside
+                           the box (owner, 2026-09-02). */
+                        segments: requiredHint ? [...term.segments, ` ${requiredHint}`] : term.segments }, term.id)))] })] }));
 });
 QualifiedSignatureAcceptScreen.displayName = 'QualifiedSignatureAcceptScreen';
 export default QualifiedSignatureAcceptScreen;

package/dist/QualifiedSignatureDocumentScreen.d.ts

@@ -40,11 +40,13 @@ export interface QualifiedSignatureDocumentScreenProps extends Omit<PrizmaListSc
  * overflow constraint, declaring no spacing or size, the same idiom as CURP's
  * taller-than-844 form (DEVIATIONS #CURP-1).
  *
- * THREE deltas from the frames, all reported rather than worked around:
- * 1. Both sections draw a back chevron at the nav's left (and `terms` replaces
- *    the logo row with a chevron + heading bar). GUIDELINES §3 stands: SDK
- *    screens carry no dismiss or back affordance — the standing ruling of
- *    DEVIATIONS #PI-9, which is not re-litigated per module.
+ * THREE deltas from the frames:
+ * 1. Both sections draw a back chevron at the nav's left. It is BUILT (owner
+ *    call 2026-09-29): these are viewers the user opened from the accept
+ *    screen, so they need a way back. It is Core's chevron through the opt-in
+ *    `PrizmaScreenNav.backLabel`, emitting `back`; the logo stays centred.
+ *    `terms` replacing the logo row with a chevron + heading bar is still not
+ *    followed — the title stays the archetype's H2 below the nav.
  * 2. `viewdoc` draws NO heading. GUIDELINES §4 is explicit that every screen has
  *    exactly one H2, and archetype G has no title-less path, so the screen
  *    carries one and the Figma frame is the side to change. (An archetype
@@ -53,10 +55,12 @@ export interface QualifiedSignatureDocumentScreenProps extends Omit<PrizmaListSc
  *    for attribution chrome (#PI-8, #F-30, #F-34), so both variants keep the
  *    header and the footer and nothing shifts between states.
  *
- * `terms` is LEFT-aligned, as Figma draws it: a centred heading over a
- * left-aligned wall of legal text reads as a mistake. The alignment rides the
- * sanctioned `overrides.align` path (types.ts) — nothing is re-styled here — and
- * an explicit host override still wins. The #GEO-2 precedent.
+ * Both variants frame the page in the box Electronic Signature's review screen
+ * uses, so the title is CENTRED on both, like that screen (owner call
+ * 2026-09-29, "take reference from other screens"). Figma's `QSign.T&C` draws
+ * the title left over an unframed wall of text; once the text sits in its own
+ * left-aligned frame the centred title no longer reads as a mistake. An
+ * explicit `overrides.align` from the host still wins.
  */
 export declare const QualifiedSignatureDocumentScreen: React.ForwardRefExoticComponent<QualifiedSignatureDocumentScreenProps & React.RefAttributes<HTMLDivElement>>;
 export default QualifiedSignatureDocumentScreen;

package/dist/QualifiedSignatureDocumentScreen.js

@@ -24,11 +24,13 @@ import './QualifiedSignatureLayout.css';
  * overflow constraint, declaring no spacing or size, the same idiom as CURP's
  * taller-than-844 form (DEVIATIONS #CURP-1).
  *
- * THREE deltas from the frames, all reported rather than worked around:
- * 1. Both sections draw a back chevron at the nav's left (and `terms` replaces
- *    the logo row with a chevron + heading bar). GUIDELINES §3 stands: SDK
- *    screens carry no dismiss or back affordance — the standing ruling of
- *    DEVIATIONS #PI-9, which is not re-litigated per module.
+ * THREE deltas from the frames:
+ * 1. Both sections draw a back chevron at the nav's left. It is BUILT (owner
+ *    call 2026-09-29): these are viewers the user opened from the accept
+ *    screen, so they need a way back. It is Core's chevron through the opt-in
+ *    `PrizmaScreenNav.backLabel`, emitting `back`; the logo stays centred.
+ *    `terms` replacing the logo row with a chevron + heading bar is still not
+ *    followed — the title stays the archetype's H2 below the nav.
  * 2. `viewdoc` draws NO heading. GUIDELINES §4 is explicit that every screen has
  *    exactly one H2, and archetype G has no title-less path, so the screen
  *    carries one and the Figma frame is the side to change. (An archetype
@@ -37,20 +39,20 @@ import './QualifiedSignatureLayout.css';
  *    for attribution chrome (#PI-8, #F-30, #F-34), so both variants keep the
  *    header and the footer and nothing shifts between states.
  *
- * `terms` is LEFT-aligned, as Figma draws it: a centred heading over a
- * left-aligned wall of legal text reads as a mistake. The alignment rides the
- * sanctioned `overrides.align` path (types.ts) — nothing is re-styled here — and
- * an explicit host override still wins. The #GEO-2 precedent.
+ * Both variants frame the page in the box Electronic Signature's review screen
+ * uses, so the title is CENTRED on both, like that screen (owner call
+ * 2026-09-29, "take reference from other screens"). Figma's `QSign.T&C` draws
+ * the title left over an unframed wall of text; once the text sits in its own
+ * left-aligned frame the centred title no longer reads as a mistake. An
+ * explicit `overrides.align` from the host still wins.
  */
 export const QualifiedSignatureDocumentScreen = forwardRef(({ strings, variant = 'document', body, screenId = `qualified-signature-document-${variant}`, overrides, onAction, ...shell }, ref) => {
     const copy = variant === 'terms' ? strings.document.terms : strings.document.document;
-    // The legal wall is left-aligned in Figma; the contract page keeps the
-    // archetype's centred default. An explicit `overrides.align` still wins.
-    const alignedOverrides = {
-        ...overrides,
-        align: overrides?.align ?? (variant === 'terms' ? 'left' : 'centered'),
-    };
-    return (_jsx(PrizmaListScreen, { ref: ref, title: copy.title, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: alignedOverrides, onAction: onAction, ...shell, children: _jsx("div", { className: "qualified-signature-document", children: body }) }));
+    return (_jsx(PrizmaListScreen, { ref: ref, title: copy.title, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, backLabel: strings.document.backLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell, children: _jsx("div", { className: [
+                'qualified-signature-document',
+                'qualified-signature-document--framed',
+                `qualified-signature-document--${variant}`,
+            ].join(' '), role: "region", "aria-label": copy.title, tabIndex: 0, children: body }) }));
 });
 QualifiedSignatureDocumentScreen.displayName = 'QualifiedSignatureDocumentScreen';
 export default QualifiedSignatureDocumentScreen;

package/dist/QualifiedSignatureLayout.css

@@ -57,6 +57,26 @@
   display: flex;
   flex-direction: column;
   gap: var(--prizma-spacing-4);
+  /* The clauses sit at the BOTTOM of the column, on the primary button, not
+   * under the document row (Elena, 2026-09-30). The fields are a flex column,
+   * so the auto margin takes the free space; when the clauses outgrow the frame
+   * (the five-clause reading) there is none and the stack scrolls as before. */
+  margin-top: auto;
+}
+
+/* The required legend leading the group. Core ships no caption block outside a
+ * field, so the line binds the clause copy's own Size-S tokens in the secondary
+ * ink — no new size, no new colour. Spacing/8 more below it than the clauses
+ * keep between themselves, so it reads as the group's header. */
+.qualified-signature-terms__legend {
+  margin: 0 0 var(--prizma-spacing-8);
+  font-family: var(--prizma-checkbox-radio-family);
+  font-weight: var(--prizma-checkbox-radio-s-font-weight);
+  font-size: var(--prizma-checkbox-radio-s-font-size);
+  line-height: var(--prizma-checkbox-radio-s-line-height);
+  letter-spacing: var(--prizma-checkbox-radio-s-letter-spacing);
+  color: var(--prizma-text-body-500-secondary);
+  text-align: left;
 }
 
 /* ── (c) Uploaded-file preview card ──────────────────────────────────────────
@@ -181,6 +201,62 @@
   overscroll-behavior: contain;
 }
 
+/* The document FRAME — the two full-surface document screens draw the page
+ * inside the same box Electronic Signature's review screen uses
+ * (`.electronic-signature-document`): `Border/Neutral/100` hairline,
+ * `Border/Radius/small`, `Surface/Neutral/0`, clipped so the page scrolls INSIDE
+ * it. Without it the contract image floated loose on the screen and the legal
+ * text ran edge to edge as one grey wall (owner-reported 2026-09-29: "take
+ * reference from other screens"). A modifier, not the base class, because the
+ * gated-form exploration reuses `.qualified-signature-document` inside its own
+ * popup, which already carries a frame.
+ *
+ * Spacing/16 bottom margin: the gap Electronic Signature's frame keeps above the
+ * CTA band, here kept above the anchored tag so the frame never touches it.
+ */
+.qualified-signature-document--framed {
+  box-sizing: border-box;
+  background-color: var(--prizma-surface-neutral-0);
+  border: var(--prizma-border-width-regular) solid var(--prizma-border-neutral-100);
+  border-radius: var(--prizma-border-radius-small);
+  margin-bottom: var(--prizma-spacing-16);
+}
+
+/* `terms` — a TEXT agreement needs a gutter inside the frame (Spacing/16) and
+ * the paragraph rhythm Electronic Signature uses (Spacing/12 between blocks). */
+.qualified-signature-document--terms {
+  padding: var(--prizma-spacing-16);
+  text-align: start;
+}
+
+.qualified-signature-document--terms > * {
+  margin: 0;
+}
+
+.qualified-signature-document.qualified-signature-document--terms > * + * {
+  /* Doubled class: `__prose` resets `margin: 0` later in this file at the
+     same specificity, which would otherwise swallow the rhythm. */
+  margin-top: var(--prizma-spacing-12);
+}
+
+/* Section headings inside the form — Headline/H5 on Text/Body/800, the same
+ * pair as `.electronic-signature-document h4`. */
+.qualified-signature-document--terms h4 {
+  font-family: var(--prizma-headline-family);
+  font-weight: var(--prizma-headline-h5-font-weight);
+  font-size: var(--prizma-headline-h5-font-size);
+  line-height: var(--prizma-headline-h5-line-height);
+  letter-spacing: var(--prizma-headline-h5-letter-spacing);
+  color: var(--prizma-text-body-800-primary);
+}
+
+/* Inside the frame the prose drops to Text/Body/500, the secondary ink every
+ * block of Core prose uses (`CardList.css`, `Card.css`) — the heading carries
+ * the hierarchy, as in Electronic Signature. */
+.qualified-signature-document--terms .qualified-signature-document__prose {
+  color: var(--prizma-text-body-500-secondary);
+}
+
 /* The contract page is host-supplied media (an <img> / <canvas> of the rendered
  * PDF, GUIDELINES §10's `cameraSurface` idiom) — it fills the column width and
  * keeps its own aspect. */

package/dist/QualifiedSignatureStrings.d.ts

@@ -128,6 +128,12 @@ export interface QualifiedSignatureStrings {
         viewLabel: string;
         /** Accessible name for the consent stack. */
         termsLabel?: string;
+        /** Suffix appended to every clause, all of them required ("*"). Localizable,
+         *  never baked into the clause copy — Data Sharing Consent's `requiredHint`. */
+        requiredHint?: string;
+        /** The line that leads the clause group and explains the marker ("All terms
+         *  marked with * are required."). Only drawn alongside `requiredHint`. */
+        requiredLegend?: string;
         /** The generic five-clause reading. */
         accept: QualifiedSignatureAcceptCopy;
         /** The partner two-clause reading. */
@@ -148,6 +154,10 @@ export interface QualifiedSignatureStrings {
         terms: {
             title: string;
         };
+        /** Accessible name of the nav's back chevron on both document screens
+         *  ("Back") — they are opened from the accept screen, so they carry a way
+         *  back to it. Emits `back`. Omit to render the logo-only nav. */
+        backLabel?: string;
     };
     /** The two in-flight screens. */
     processing: {