@incodetech/prizma-core-screens 0.2.3 → 0.2.7

package/src/QualifiedSignatureDocumentScreen.tsx

@@ -60,11 +60,13 @@ export interface QualifiedSignatureDocumentScreenProps
  * 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
@@ -73,10 +75,12 @@ export interface QualifiedSignatureDocumentScreenProps
  *    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<
   HTMLDivElement,
@@ -96,12 +100,6 @@ export const QualifiedSignatureDocumentScreen = forwardRef<
   ) => {
     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: PrizmaScreenOverrides = {
-      ...overrides,
-      align: overrides?.align ?? (variant === 'terms' ? 'left' : 'centered'),
-    };
 
     return (
       <PrizmaListScreen
@@ -109,12 +107,24 @@ export const QualifiedSignatureDocumentScreen = forwardRef<
         title={copy.title}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
+        backLabel={strings.document.backLabel}
         screenId={screenId}
-        overrides={alignedOverrides}
+        overrides={overrides}
         onAction={onAction}
         {...shell}
       >
-        <div className="qualified-signature-document">{body}</div>
+        <div
+          className={[
+            'qualified-signature-document',
+            'qualified-signature-document--framed',
+            `qualified-signature-document--${variant}`,
+          ].join(' ')}
+          role="region"
+          aria-label={copy.title}
+          tabIndex={0}
+        >
+          {body}
+        </div>
       </PrizmaListScreen>
     );
   },

package/src/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/src/QualifiedSignatureStrings.ts

@@ -169,6 +169,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. */
@@ -186,6 +192,10 @@ export interface QualifiedSignatureStrings {
     document: { title: string };
     /** QSign.T&C ("Certificate Application Form"), left-aligned in Figma. */
     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. */

package/src/ScreenNav.css

@@ -28,6 +28,14 @@
   width: 100%;
 }
 
+/* With the opt-in back chevron the nav sits on the content column's 24px
+ * gutter, so the chevron lines up with the title and content below it. Core's
+ * nav already pads its row by Spacing/2, hence the subtraction. A logo-only nav
+ * is centred and needs no gutter, so nothing else moves. */
+.prizma-screen-nav--back {
+  padding-inline: calc(var(--prizma-spacing-24) - var(--prizma-spacing-2));
+}
+
 .prizma-screen-nav__custom-logo {
   display: flex;
   align-items: center;

package/src/ScreenNav.tsx

@@ -1,4 +1,9 @@
-import React, { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import React, {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type MouseEventHandler,
+  type ReactNode,
+} from 'react';
 import { PrizmaNavigation } from '@incodetech/prizma-core-web/navigation';
 import './ScreenNav.css';
 
@@ -18,25 +23,50 @@ export interface PrizmaScreenNavProps extends ComponentPropsWithoutRef<'header'>
    * only the logo disappears, and the row leaves the a11y tree.
    */
   reserved?: boolean;
+  /**
+   * Opt-in back chevron at the nav's LEFT — Core's own
+   * (`PrizmaNavigation.showLeftIcon`, IconChevronLeft). Passing the label turns
+   * it on; it is the button's accessible name (i18n). Off by default, so every
+   * existing screen keeps the logo-only nav. For a screen the user OPENED from
+   * another one (Qualified Signature's document viewers, reached from "View"
+   * and from the application-form link) — a way back to where they came from,
+   * not a dismiss of the flow, which stays out (#PI-9). Owner call 2026-09-29.
+   */
+  backLabel?: string;
+  /** Click handler for the back chevron. */
+  onBack?: MouseEventHandler<HTMLButtonElement>;
 }
 
 /**
  * ScreenNav — the logo header of every SDK screen.
  * Sits 12px below the top of the shell (the host frame owns the OS status
- * bar), logo centered, no back/close buttons (GUIDELINES.md §3).
+ * bar), logo centered, no close button (GUIDELINES.md §3). A back chevron is
+ * opt-in through `backLabel`, for opened sub-screens only.
  */
 export const PrizmaScreenNav = forwardRef<HTMLElement, PrizmaScreenNavProps>(
-  ({ logo, navLabel, reserved = false, className, ...rest }, ref) => (
+  ({ logo, navLabel, reserved = false, backLabel, onBack, className, ...rest }, ref) => (
     <header
       ref={ref}
       aria-hidden={reserved || undefined}
-      className={['prizma-screen-nav', className ?? ''].filter(Boolean).join(' ')}
+      className={[
+        'prizma-screen-nav',
+        backLabel && !reserved ? 'prizma-screen-nav--back' : '',
+        className ?? '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
       {...rest}
     >
       {reserved ? null : logo ? (
         <span className="prizma-screen-nav__custom-logo">{logo}</span>
       ) : (
-        <PrizmaNavigation showIncodeLogo aria-label={navLabel} />
+        <PrizmaNavigation
+          showIncodeLogo
+          aria-label={navLabel}
+          showLeftIcon={Boolean(backLabel)}
+          backLabel={backLabel}
+          onLeftIconClick={onBack}
+        />
       )}
     </header>
   ),

package/src/VideoSelfieIdCaptureScreen.tsx

@@ -3,15 +3,18 @@ import {
   PrizmaIdCapture,
   type PrizmaIdCaptureState,
 } from '@incodetech/prizma-core-web/id-capture';
+import { PrizmaCaptureFeedback } from '@incodetech/prizma-core-web/capture-feedback';
 import { PrizmaLoadingSpinner } from '@incodetech/prizma-core-web/loading-spinner';
-import { PrizmaSnackbar } from '@incodetech/prizma-core-web/snackbar';
 import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
 import { PrizmaTag } from '@incodetech/prizma-core-web/tag';
+import { PrizmaTitle } from '@incodetech/prizma-core-web/title';
 import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type {
   VideoSelfieDocumentType,
-    VideoSelfieIdErrorSeverity,
+  VideoSelfieIdCondition,
+  VideoSelfieIdErrorReason,
+  VideoSelfieIdErrorSeverity,
   VideoSelfieIdSide,
   VideoSelfieStrings,
 } from './VideoSelfieStrings';
@@ -19,13 +22,52 @@ import './ScreenLayout.css';
 import './ViewfinderScreen.css';
 import './VideoSelfieLayout.css';
 
-/** Which purple stage section to render (groups 3, 5 and 6). */
+/** Which purple stage section to render (groups 3, 5 and 6), plus the live
+ *  coaching beat the full-flow frames draw between them. */
 export type VideoSelfieIdCaptureState =
   | 'default'
   | 'shown'
   | 'processing'
   | 'allGood'
-  | 'error';
+  | 'error'
+  | 'condition';
+
+/**
+ * Condition → the Core treatment that already exists for it.
+ *
+ * Four are `PrizmaIdCapture`'s own error states. `blurry` is the plain error
+ * border: blur is a DETECTION result, not a framing mistake, and the owner's
+ * 2026-07-28 call is that those pair the plain border with the feedback
+ * bubble rather than inventing a semantic overlay (`IdCapture.tsx`, the note
+ * above `error`). Either way the message is the bubble's, never the frame's.
+ */
+const CONDITION_STATE: Record<VideoSelfieIdCondition, PrizmaIdCaptureState> = {
+  wrongSide: 'error-wrong-side',
+  notAligned: 'error-not-aligned',
+  glare: 'error-glare',
+  tooDark: 'error-too-dark',
+  blurry: 'error',
+};
+
+/** Condition → the bubble's own variant. All six of Core's are used: the
+ *  wrong-side bubble names the face the user SHOULD be showing, so it flips
+ *  with the leg — `show-front` on the front, `show-back` on the back. */
+const CONDITION_FEEDBACK: Record<
+  VideoSelfieIdCondition,
+  'not-aligned' | 'blurry' | 'glare' | 'too-dark'
+> = {
+  wrongSide: 'not-aligned', // unused — the wrong-side variant is side-keyed below
+  notAligned: 'not-aligned',
+  blurry: 'blurry',
+  glare: 'glare',
+  tooDark: 'too-dark',
+};
+
+/** The wrong-side bubble, per leg. */
+const WRONG_SIDE_FEEDBACK: Record<VideoSelfieIdSide, 'show-front' | 'show-back'> = {
+  front: 'show-front',
+  back: 'show-back',
+};
 
 /** Purple stage state → Core `PrizmaIdCapture` state. The frame border, the
  *  analyzing sweep, the scrim and the encrypted row are ALL Core's. */
@@ -35,6 +77,8 @@ const CAPTURE_STATE: Record<VideoSelfieIdCaptureState, PrizmaIdCaptureState> = {
   processing: 'analyzing',
   allGood: 'success',
   error: 'error',
+  // Replaced per-condition below — the map needs an entry for every key.
+  condition: 'error',
 };
 
 /** Which beat of the seven-step journey each side occupies — front is step 2
@@ -56,6 +100,12 @@ export interface VideoSelfieIdCaptureScreenProps
   /** Whether the rejection invites a retry (`6.1`/`6.3`) or is terminal
    *  (`6.2`/`6.4`). Read only when `state="error"`. */
   errorSeverity?: VideoSelfieIdErrorSeverity;
+  /** WHY the read was rejected — the `.1`–`.4` suffix of the group 6 section.
+   *  Read only when `state="error"`. Default `scan`. */
+  errorReason?: VideoSelfieIdErrorReason;
+  /** Which live condition to coach the user out of. Read only when
+   *  `state="condition"`. Default `notAligned`. */
+  condition?: VideoSelfieIdCondition;
   /** Live camera feed (<video>) or sample still (<img>) behind the frame. */
   camera?: ReactNode;
   /** The captured document still, for the states Core draws one in. */
@@ -118,6 +168,8 @@ export const VideoSelfieIdCaptureScreen = forwardRef<
       documentType = 'id',
       state = 'default',
       errorSeverity = 'tryAgain',
+      errorReason = 'scan',
+      condition = 'notAligned',
       camera,
       still,
       screenId = `video-selfie-id-capture-${side}-${state}`,
@@ -128,7 +180,15 @@ export const VideoSelfieIdCaptureScreen = forwardRef<
     },
     ref,
   ) => {
-    const errorLabel = strings.idCapture.errors[errorSeverity];
+    const errorLabel = strings.idCapture.errors[errorReason][errorSeverity];
+    /* Only the wrong-side bubble is keyed by side — it is the one that names
+       the face to show. The other four describe the shot. */
+    const conditionCopy =
+      condition === 'wrongSide'
+        ? strings.idCapture.conditions.wrongSide[side]
+        : strings.idCapture.conditions[condition];
+    const conditionFeedback =
+      condition === 'wrongSide' ? WRONG_SIDE_FEEDBACK[side] : CONDITION_FEEDBACK[condition];
 
     return (
       <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
@@ -149,50 +209,76 @@ export const VideoSelfieIdCaptureScreen = forwardRef<
             .filter(Boolean)
             .join(' ')}
         >
-          <div className="video-selfie-band" />
+          {/* The frame is CENTRED in the air between the stepper and the tag,
+              not bottom-anchored: Figma seats `ID Capture Frame` at y 172–627
+              of a 91–708 content area, dead centre. One flexible band either
+              side is the whole geometry — no offset is declared. */}
+          {/* The coaching bubble sits in the band ABOVE the frame, which is
+              where the five condition frames draw it — Core's own
+              `PrizmaCaptureFeedback`, the same piece ID Capture's stage uses
+              for the same job (`IdCaptureStageScreen`). The frame underneath
+              takes the matching red treatment, so the two say one thing:
+              what is wrong, and what to do about it. */}
+          <div className="video-selfie-band">
+            {state === 'condition' ? (
+              <div className="video-selfie-feedback">
+                <PrizmaCaptureFeedback
+                  feedback={conditionFeedback}
+                  title={conditionCopy.title}
+                  subtitle={conditionCopy.subtitle}
+                />
+              </div>
+            ) : null}
+          </div>
           <PrizmaIdCapture
+            className="video-selfie-stage"
             type={documentType}
-            state={CAPTURE_STATE[state]}
+            state={state === 'condition' ? CONDITION_STATE[condition] : CAPTURE_STATE[state]}
             isVertical
             mode="overlay"
             scrim
             showEncryptedLabel={false}
             still={still}
           />
+          <div className="video-selfie-band" />
           {/* Centred ON the frame, not below it — `3.2`/`5.2` put the spinner
               and its caption over the document (DEVIATIONS #VS-7). */}
           {state === 'processing' ? (
             <div className="video-selfie-stage-status">
-              <PrizmaLoadingSpinner
-                showTitle
-                titleText={strings.idCapture.processingLabel}
-                loadingLabel={strings.idCapture.processingLabel}
-              />
+              <div className="video-selfie-stage-status__card">
+                <PrizmaLoadingSpinner
+                  showTitle
+                  titleText={strings.idCapture.processingLabel}
+                  loadingLabel={strings.idCapture.processingLabel}
+                />
+              </div>
             </div>
           ) : null}
           {/* `3.3`/`5.3` and every `6.x` draw the verdict in the SAME dark card,
               centred on the document, as `3.2`/`5.2` draw the spinner — three
               identical Figma treatments had become two different ones once the
-              spinner moved (owner QA 2026-08-19). DEVIATIONS #VS-13. */}
+              spinner moved (owner QA 2026-08-19). DEVIATIONS #VS-13.
+
+              The card's CONTENT is Core's `PrizmaTitle` with its status icon,
+              not a Snackbar: Figma stacks the mark ABOVE the label, centred,
+              with the label free to wrap onto two or three lines ("ID photo
+              verification failed, try again"). A Snackbar is a one-line ROW —
+              icon beside text — so it printed the copy across the full column
+              and had to be told, by a prop, whether its own text would wrap
+              (#VS-9). The stacked status block is what Core already ships for
+              this shape, and it is the same piece the liveness ring uses on
+              the same beat. DEVIATIONS #VS-19. */}
           {state === 'allGood' || state === 'error' ? (
             <div className="video-selfie-stage-status">
-              {state === 'allGood' ? (
-                <PrizmaSnackbar state="success" role="status">
-                  {strings.idCapture.successLabel}
-                </PrizmaSnackbar>
-              ) : (
-                /* NOT `isMultiline`: that modifier switches the row to
-                 `align-items: flex-start` so an icon anchors to the top of
-                 WRAPPED text. The rejection copy renders on ONE line, so it
-                 only pushed the icon 6.9px below the text centre
-                 (owner-reported 2026-08-19: "the text is not even aligned to
-                 the icon"). CORE REQUEST: have the Snackbar follow actual
-                 wrapping rather than a prop the caller has to predict.
-                 DEVIATIONS #VS-9. */
-                <PrizmaSnackbar state="error" role="alert">
-                  {errorLabel}
-                </PrizmaSnackbar>
-              )}
+              <div
+                className="video-selfie-stage-status__card"
+                role={state === 'error' ? 'alert' : 'status'}
+              >
+                <PrizmaTitle
+                  title={state === 'allGood' ? strings.idCapture.successLabel : errorLabel}
+                  icon={{ type: 'status', status: state === 'allGood' ? 'success' : 'error' }}
+                />
+              </div>
             </div>
           ) : null}
         </div>