@incodetech/prizma-core-screens 0.2.4 → 0.2.12

package/src/PermissionsStrings.ts

@@ -12,20 +12,26 @@
 // is the ID Capture-flavoured copy of the same skeleton; it stays where it is so
 // nothing that imports it breaks (DEVIATIONS #IDC-26).
 //
-// The section's seven frames collapse onto THREE built screens:
+// The section's seven frames collapse onto FOUR built screens:
 //
+//   1-3-1-id-permission-modal         → PermissionsAskScreen       (the sheet)
 //   1-3-2-id                          → PermissionsRequiredScreen  (reason rows)
 //   1-3-2-id-allow-camera             → PermissionsAllowScreen     (subtitle)
 //   1-4-2-id (+ 4 Android siblings)   → PermissionsBrowserStepsScreen
 //
-// The other four are OS chrome and are NOT built:
+// The other three are OS chrome and are NOT built:
 //
-//   1-3-1-id-permission-modal   the browser's own "Allow camera access" sheet
 //   1-4-1-id                    the iOS "…Would Like to Access the Camera" alert
 //   1-3-2-id-quit-process       an iOS confirm alert layered over 1-3-2-id
 //   1-3-2-id-allow-camera-quit  the same alert layered over the allow screen
 //
-// None of them is a Prizma surface: their chrome does not exist in Core and
+// `1-3-1-id-permission-modal` was on this list until 2026-10-07. It is not the
+// browser's prompt: it is the SDK's own camera pre-permission sheet (the SDK
+// release notes call it "the camera permission sheet", shown by every module
+// that asks for the camera), drawn with Core's Bottom Sheet dialog and Button
+// Group. So it is built, from those two components (DEVIATIONS #GEN-1).
+//
+// None of the remaining three is a Prizma surface: their chrome does not exist in Core and
 // rebuilding it would mean inventing primitives and shipping platform rasters,
 // both forbidden (rule 1, GUIDELINES §10). Same call as Document Capture's iOS
 // action sheets (#DC-20) and Geolocation's system alert. Core Lab draws them as
@@ -49,18 +55,30 @@ export interface PermissionsReasonRow {
 }
 
 /**
- * Which browser's "turn it back on" journey to show. `safariIos` is the base
- * `1-4-2-id` frame; the other four are the `Android browsers` section of the
- * Web flow (4:8159). Re-enabling a permission is a different journey in every
- * browser, which is why one screen carries five step lists rather than five
- * screens carrying one skeleton.
+ * Which browser's "turn it back on" journey to show. The SAME nine browsers,
+ * keys and order as Geolocation's (`GeolocationBrowser`), because a refused
+ * camera and a refused location are the same journey through the same browser
+ * settings; only the permission's name changes (Camila, 2026-10-07). The
+ * Permissions Figma draws five of them (`1-4-2-id` for Safari plus the four
+ * `Android browsers` frames, 4:8159); the other four follow Geolocation.
  */
 export type PermissionsBrowser =
   | 'safariIos'
+  | 'chromeIos'
+  | 'firefoxIos'
+  | 'operaIos'
   | 'chromeAndroid'
   | 'firefoxAndroid'
+  | 'operaAndroid'
   | 'samsungAndroid'
-  | 'operaAndroid';
+  | 'unrecognizedAndroid'
+  // Desktop browsers. Not in Geolocation's set: a phone's lists send the user
+  // to the Settings app on an iPhone, which means nothing on a computer, so the
+  // desktop flow carries its own four (2026-10-07).
+  | 'chromeDesktop'
+  | 'edgeDesktop'
+  | 'firefoxDesktop'
+  | 'safariMac';
 
 /**
  * Step kind → canonical bank glyph, resolved in
@@ -73,6 +91,7 @@ export type PermissionsBrowser =
  * than inventing a second one.
  */
 export type PermissionsStepKind =
+  | 'addressBar'
   | 'settings'
   | 'browser'
   | 'menu'
@@ -90,7 +109,7 @@ export interface PermissionsStep {
 
 export interface PermissionsBrowserSteps {
   /** Names the browser under the headline. Figma labels the section, not the
-   *  screen; the label keeps five otherwise near-identical cards apart. */
+   *  screen; the label keeps nine otherwise near-identical cards apart. */
   label: string;
   steps: PermissionsStep[];
 }
@@ -101,6 +120,17 @@ export interface PermissionsStrings {
   /** "verified by" attribution copy for the footer tag. */
   verifiedLabel: string;
 
+  /** `1-3-1-id-permission-modal` — the pre-permission sheet, the very first
+   *  ask. Its "Allow" is what raises the real OS prompt. */
+  ask: {
+    title: string;
+    subtitle?: string;
+    /** Primary — raises the OS prompt. */
+    allowLabel: string;
+    /** Secondary — declines; the flow moves on to `required`. */
+    denyLabel: string;
+  };
+
   /** `1-3-2-id` — the permission was refused and the flow explains why it needs it. */
   required: {
     title: string;
@@ -112,7 +142,7 @@ export interface PermissionsStrings {
     ctaLabel: string;
   };
 
-  /** `1-3-2-id-allow-camera` — the first ask, before any refusal. */
+  /** `1-3-2-id-allow-camera` — the softer ask after the REAL OS prompt was refused. */
   allow: {
     title: string;
     subtitle?: string;

package/src/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/src/PhoneInputOtpScreen.tsx

@@ -19,6 +19,14 @@ export interface PhoneInputOtpScreenProps
   value?: string;
   /** How many digits the code carries. Default 6. */
   length?: number;
+  /**
+   * Seconds left before the code can be resent. While it is above 0 (and the
+   * copy carries `otp.resendCountdownLabel`), the resend line becomes one
+   * disabled link, "Resend code in 30s", exactly as Figma draws
+   * `phoneNumber.OTP.typing`. The host owns the timer; the screen only draws
+   * the number it is given.
+   */
+  resendIn?: number;
   screenId?: string;
   overrides?: PrizmaScreenOverrides;
   onAction?: PrizmaScreenActionHandler;
@@ -47,13 +55,16 @@ export const PhoneInputOtpScreen = forwardRef<HTMLDivElement, PhoneInputOtpScree
       state = 'typing',
       value,
       length = 6,
+      resendIn,
       screenId = `phone-input-otp-${state}`,
       overrides,
       onAction,
       ...shell
     },
     ref,
-  ) => (
+  ) => {
+    const counting = (resendIn ?? 0) > 0 && Boolean(strings.otp.resendCountdownLabel);
+    return (
     <PrizmaFormScreen
       ref={ref}
       title={strings.otp.title}
@@ -70,8 +81,16 @@ export const PhoneInputOtpScreen = forwardRef<HTMLDivElement, PhoneInputOtpScree
          than `linkLabel` (a full-width 56px button cannot sit inside a line of
          body text, and one button could not tell the two actions apart —
          DEVIATIONS #PI-10). */
+      /* While the resend timer runs, the line is ONE disabled link (Figma
+         `OTP.typing`: Tertiary / Link · Disabled), not the composed sentence. */
+      linkLabel={
+        counting
+          ? strings.otp.resendCountdownLabel!.replace('{{time}}', String(resendIn))
+          : undefined
+      }
+      linkDisabled={counting}
       linkContent={
-        strings.otp.resendPrompt ? (
+        !counting && strings.otp.resendPrompt ? (
           <p className="prizma-screen-layout__inline-prompt">
             {strings.otp.resendPrompt}{' '}
             {strings.otp.resendLabel ? (
@@ -119,7 +138,8 @@ export const PhoneInputOtpScreen = forwardRef<HTMLDivElement, PhoneInputOtpScree
         errorText={state === 'error' ? strings.otp.errorText : undefined}
       />
     </PrizmaFormScreen>
-  ),
+    );
+  },
 );
 PhoneInputOtpScreen.displayName = 'PhoneInputOtpScreen';
 

package/src/PhoneInputStrings.ts

@@ -20,13 +20,18 @@
  * - `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';
+  | 'loading'
+  | 'emptyError';
 
 /**
  * The `phoneNumber.OTP.*` sections — same layout, different field state:
@@ -45,8 +50,9 @@ export type PhoneInputOtpState = 'typing' | 'filled' | 'processing' | 'error';
 export type PhoneInputErrorVariant = 'tryAgain' | 'unknown' | 'noNetwork';
 
 /** One selectable country in the dial-code dropdown. Runtime data, not copy —
- *  the host supplies its own list; `flag` is the emoji Figma draws (Core has no
- *  country-flag primitive — DEVIATIONS #PI-3). */
+ *  the host supplies its own list. The screen draws the flag from Core's
+ *  raster bank by `value` (`PrizmaCountryFlag`, DEVIATIONS #PI-3); `flag` is
+ *  only the emoji fallback for a country outside the bank. */
 export interface PhoneInputCountry {
   /** Stable value, e.g. an ISO 3166-1 alpha-2 code. */
   value: string;
@@ -54,7 +60,7 @@ export interface PhoneInputCountry {
   dialCode: string;
   /** Country name for the open menu row. */
   label: string;
-  /** Emoji flag, e.g. `🇷🇸`. */
+  /** Emoji fallback, e.g. `🇷🇸`, drawn only when the bank has no raster. */
   flag?: string;
 }
 
@@ -63,6 +69,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: {
@@ -116,6 +128,13 @@ export interface PhoneInputStrings {
     resendSeparator?: string;
     /** Second link — returns to phone entry. Emits `tertiary`. */
     changeNumberLabel?: string;
+    /**
+     * While the resend timer runs, the resend line is replaced by ONE disabled
+     * link: "Resend code in {{time}}s" (Figma `phoneNumber.OTP.typing`). The
+     * `{{time}}` placeholder is the SDK's own (`otp.resendCountdown`) and is
+     * filled with the screen's `resendIn` seconds.
+     */
+    resendCountdownLabel?: string;
     /** Primary CTA. */
     ctaLabel: string;
     /** Accessible / visible busy copy while the code is checked (`processing`). */

package/src/PhoneInputVerifyScreen.tsx

@@ -1,6 +1,7 @@
 import React, { forwardRef } from 'react';
 import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
 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 {
@@ -55,6 +56,14 @@ const DEFAULT_COUNTRIES: PhoneInputCountry[] = [
  * 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<HTMLDivElement, PhoneInputVerifyScreenProps>(
   (
@@ -74,9 +83,14 @@ export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerif
     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" after the flag); the closed field keeps only flag +
+      // dial code ("+381") through Core's `fieldLabel`, as Figma draws it.
+      // The flag is not text: it rides the leading slot below (DEVIATIONS
+      // #PI-3), so it is Core's raster on every OS instead of an emoji that
+      // Windows draws as the letters "RS".
+      label: [c.dialCode, c.label].join(' '),
+      fieldLabel: c.dialCode,
     }));
 
     // Figma treats the states as three distinct field treatments, not one:
@@ -88,6 +102,9 @@ export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerif
     // 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 (
       <PrizmaFormScreen
@@ -97,6 +114,7 @@ export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerif
         ctaLabel={strings.verify.ctaLabel}
         /* Figma's `loading` section swaps the CTA label for Core's spinner. */
         ctaLoading={busy}
+        ctaDisabled={emptyError}
         ctaLoadingLabel={strings.verify.ctaLoadingLabel}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
@@ -119,6 +137,22 @@ export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerif
             searchPlaceholder={strings.verify.countrySearchPlaceholder}
             /* The `countryCode` section IS the open-menu spec state. */
             forceOpen={state === 'countryCode'}
+            /* Core's canonical flag raster in the closed field and every menu
+               row, the WatchlistBusinessFormScreen precedent. 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: match.dialCode,
+                    flag: match.flag ?? '',
+                  }}
+                />
+              ) : null;
+            }}
             disabled={busy}
           />
           <PrizmaTextField
@@ -134,12 +168,14 @@ export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerif
             type="tel"
             inputMode="tel"
             aria-label={strings.verify.fieldLabel}
-            placeholder={strings.verify.placeholder}
+            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 ?? ''}
+            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/src/QualifiedSignatureAcceptScreen.tsx

@@ -118,6 +118,7 @@ export const QualifiedSignatureAcceptScreen = forwardRef<
     // `loading` makes the whole form inert.
     const busy = state === 'loading';
     const ticked = state !== 'default';
+    const requiredHint = strings.accept.requiredHint;
 
     return (
       <PrizmaFormScreen
@@ -177,6 +178,12 @@ export const QualifiedSignatureAcceptScreen = forwardRef<
           role="group"
           aria-label={strings.accept.termsLabel}
         >
+          {/* The legend LEADS the group (Elena, 2026-09-30, picked from four
+              placements): it sits where the markers are and, on the five-clause
+              reading that scrolls, is still on screen on arrival. */}
+          {requiredHint && strings.accept.requiredLegend ? (
+            <p className="qualified-signature-terms__legend">{strings.accept.requiredLegend}</p>
+          ) : null}
           {terms.map((term) => (
             <PrizmaCheckbox
               key={term.id}
@@ -185,7 +192,11 @@ export const QualifiedSignatureAcceptScreen = forwardRef<
               value={term.id}
               checked={ticked}
               disabled={busy}
-              segments={term.segments}
+              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}
             />
           ))}
         </div>

package/src/QualifiedSignatureDocumentScreen.tsx

@@ -55,16 +55,21 @@ export interface QualifiedSignatureDocumentScreenProps
  *
  * Archetype G is the fit: its `__list` middle is "content filling the space
  * between the title block and the CTA band", which is exactly what a document
- * page is, and both sections carry no CTA at all so the band never renders. The
+ * page is, and the band carries only the "Back" secondary (delta 1). The
  * body is allowed to scroll inside that middle — one module rule RELEASING an
  * 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. These are viewers
+ *    the user opened from the accept screen, so they need a way back (owner
+ *    call 2026-09-29). It ships as a full-width SECONDARY "Back" button in the
+ *    CTA band instead, emitting `secondary` (owner call 2026-10-08): the person
+ *    reads and returns to sign, and a real button at the thumb is easier to
+ *    find than a chevron. "Back" over "Done" because nothing is finished here;
+ *    the signature still waits on the accept screen. The nav stays logo-only.
+ *    `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 +78,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,25 +103,30 @@ 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
         ref={ref}
         title={copy.title}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
+        secondaryCtaLabel={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. */