@usefillo/react 0.20.0 → 0.21.0

package/dist/index.d.ts

@@ -23,6 +23,8 @@ interface FilloApi {
     isFirstPage: boolean;
     isLastPage: boolean;
     next: () => void;
+    /** Available on local preview controllers; a no-op unless explicitly enabled. */
+    skipPreviewPage?: () => void;
     back: () => void;
     submit: () => Promise<void>;
     status: FormStatus;
@@ -163,6 +165,8 @@ interface FilloFormBaseProps {
     uploadFileSizeLimitMb?: number;
     onChange?: (data: ResponseData) => void;
     onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
+    /** Observe a page change after the native renderer moves focus. Index is zero-based. */
+    onPageChange?: (pageIndex: number) => void;
     /** Observe load and code-form sync failures (otherwise only logged). */
     onError?: (error: FilloError) => void;
     /**
@@ -196,6 +200,12 @@ interface FilloFormBaseProps {
      * previews; real embeds need either `formId` or `defineForm()` + `client`.
      */
     renderOnly?: boolean;
+    /**
+     * Add a Skip action for browsing later pages without answering. Only enabled
+     * with explicit renderOnly. Native Next still validates and follows branches;
+     * Skip visits the next schema page, including pages outside the current route.
+     */
+    previewNavigation?: boolean;
     /**
      * @internal Builder/test preview: let "Next" move between pages without
      * client-side validation. Submission and branding are still authoritative.
@@ -209,6 +219,7 @@ type HostedFormProps = FilloFormBaseProps & {
     form?: undefined;
     client?: FilloClient;
     renderOnly?: false;
+    previewNavigation?: false;
     skipValidation?: false;
 };
 type InlineTargetedFormProps = FilloFormBaseProps & {
@@ -217,6 +228,7 @@ type InlineTargetedFormProps = FilloFormBaseProps & {
     formId: string;
     client?: FilloClient;
     renderOnly?: false;
+    previewNavigation?: false;
     skipValidation?: false;
 };
 type CodeBackedFormProps = FilloFormBaseProps & {
@@ -225,6 +237,7 @@ type CodeBackedFormProps = FilloFormBaseProps & {
     client: FilloClient;
     formId?: undefined;
     renderOnly?: false;
+    previewNavigation?: false;
     skipValidation?: false;
 };
 type RenderOnlyFormProps = FilloFormBaseProps & {
@@ -241,6 +254,7 @@ type LegacyPreviewFormProps = FilloFormBaseProps & {
     client?: FilloClient;
     formId?: string;
     renderOnly?: boolean;
+    previewNavigation?: false;
     skipValidation: true;
 };
 type FilloFormProps = HostedFormProps | InlineTargetedFormProps | CodeBackedFormProps | RenderOnlyFormProps | LegacyPreviewFormProps;
@@ -269,7 +283,7 @@ type ContentProps = {
 };
 /** Inert: rendering one throws; they exist to be read by the compiler. */
 type Inert<P> = (props: P) => never;
-interface FilloJsxFormBaseProps extends Omit<FilloFormProps, "form" | "formId" | "client" | "renderOnly" | "skipValidation"> {
+interface FilloJsxFormBaseProps extends Omit<FilloFormProps, "form" | "formId" | "client" | "renderOnly" | "skipValidation" | "previewNavigation"> {
     /** Project handle — the form's identity across syncs. */
     id: string;
     title?: string;
@@ -282,14 +296,17 @@ type FilloJsxFormProps = FilloJsxFormBaseProps & ({
     client: FilloClient;
     renderOnly?: false;
     skipValidation?: false;
+    previewNavigation?: false;
 } | {
     client?: FilloClient;
     renderOnly: true;
     skipValidation?: boolean;
+    previewNavigation?: boolean;
 } | {
     client?: FilloClient;
     renderOnly?: boolean;
     skipValidation: true;
+    previewNavigation?: false;
 });
 declare function JsxForm(props: FilloJsxFormProps): react.JSX.Element;
 declare function defineFormFromJsx(element: ReactElement<FilloJsxFormProps>): CodeForm;
@@ -351,6 +368,8 @@ interface ControllerOptions {
     getHoneypot?: () => string;
     /** @internal Preview-only page navigation escape hatch. Submission still validates. */
     skipValidation?: boolean;
+    /** Enable the explicit Skip action in a transportless local preview. */
+    previewNavigation?: boolean;
     /**
      * Embedding surface, recorded per response for measurement. Defaults to
      * "headless" (your own markup), matching @usefillo/core — the framed

package/dist/index.js

@@ -249,6 +249,7 @@ function useFilloController(options) {
       onSubmitted: (id, d) => optsRef.current.onSubmitted?.(id, d),
       getHoneypot: () => optsRef.current.getHoneypot?.() ?? "",
       skipValidation: options.skipValidation,
+      previewNavigation: options.previewNavigation,
       surface: options.surface ?? "headless",
       // Wrapped so the engine (created once) always calls the latest resolver.
       resolveFormId: options.resolveFormId ? () => optsRef.current.resolveFormId() : void 0,
@@ -295,6 +296,7 @@ function useFilloController(options) {
       setValue: store.setValue,
       setUploading: store.setUploading,
       next: store.next,
+      skipPreviewPage: store.skipPreviewPage,
       back: store.back,
       submit: store.submit,
       flushDraft: store.flushDraft,
@@ -1781,6 +1783,25 @@ function ChoiceIcon({ icon }) {
     }
   );
 }
+function SelectionCheck() {
+  return /* @__PURE__ */ jsx6(
+    "svg",
+    {
+      className: "fillo-option-check",
+      width: "1em",
+      height: "1em",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "square",
+      strokeLinejoin: "miter",
+      "aria-hidden": "true",
+      focusable: "false",
+      children: /* @__PURE__ */ jsx6("path", { d: "M4 12l5 5L20 6" })
+    }
+  );
+}
 function SingleChoice({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const appearance = useFilloAppearance();
@@ -1826,10 +1847,10 @@ function SingleChoice({ field, value, error, setValue, ids: providedIds }) {
                 }
               ),
               /* @__PURE__ */ jsx6(ChoiceIcon, { icon: opt.icon }),
+              /* @__PURE__ */ jsx6("span", { className: slotClass2("fillo-option-label", appearance, { slot: "optionLabel", kind: field.kind, fieldId: field.id }), "data-fillo": "optionLabel", children: opt.label }),
               opt.icon && value === opt.id && // Icon-mode hides the native input, so its check state is
               // otherwise color-only (forfeits forced-colors' own indicator).
-              /* @__PURE__ */ jsx6("span", { className: "fillo-option-check", "aria-hidden": "true", children: "\u2713" }),
-              /* @__PURE__ */ jsx6("span", { className: slotClass2("fillo-option-label", appearance, { slot: "optionLabel", kind: field.kind, fieldId: field.id }), "data-fillo": "optionLabel", children: opt.label })
+              /* @__PURE__ */ jsx6(SelectionCheck, {})
             ]
           },
           opt.id
@@ -1929,10 +1950,10 @@ function MultiChoice({ field, value, error, setValue, ids: providedIds }) {
                 }
               ),
               /* @__PURE__ */ jsx6(ChoiceIcon, { icon: opt.icon }),
+              /* @__PURE__ */ jsx6("span", { className: slotClass2("fillo-option-label", appearance, { slot: "optionLabel", kind: field.kind, fieldId: field.id }), "data-fillo": "optionLabel", children: opt.label }),
               opt.icon && selected.includes(opt.id) && // Icon-mode hides the native input, so its check state is
               // otherwise color-only (forfeits forced-colors' own indicator).
-              /* @__PURE__ */ jsx6("span", { className: "fillo-option-check", "aria-hidden": "true", children: "\u2713" }),
-              /* @__PURE__ */ jsx6("span", { className: slotClass2("fillo-option-label", appearance, { slot: "optionLabel", kind: field.kind, fieldId: field.id }), "data-fillo": "optionLabel", children: opt.label })
+              /* @__PURE__ */ jsx6(SelectionCheck, {})
             ]
           },
           opt.id
@@ -3084,6 +3105,7 @@ function FilloForm(props) {
       theme,
       formId: renderOnly ? void 0 : syncedFormId ?? formId,
       renderOnly,
+      previewNavigation: props.renderOnly === true && props.previewNavigation === true,
       skipValidation: renderOnly ? true : props.skipValidation,
       poweredBy,
       brandLabel: branding?.label,
@@ -3166,6 +3188,7 @@ function ResolvedForm(props) {
   const { schema, theme } = props;
   const displayOnly = props.displayOnly === true;
   const renderOnly = props.renderOnly === true;
+  const previewNavigation = renderOnly && !displayOnly && props.previewNavigation === true;
   const instanceId = useId2().replace(/:/g, "");
   const devEnv = useIsDevEnv();
   const devChrome = !displayOnly && (props.preview === true || devEnv);
@@ -3269,6 +3292,7 @@ function ResolvedForm(props) {
     onChange: props.onChange,
     onSubmitted: props.onSubmitted,
     skipValidation: props.skipValidation,
+    previewNavigation,
     getHoneypot: () => hpRef.current?.value ?? "",
     // Framed renderer: Fillo draws the layout (and badge), so the surface is
     // "default", never the bare-engine "headless".
@@ -3337,10 +3361,10 @@ function ResolvedForm(props) {
   const submitted = api.status === "submitted";
   const liveSubmit = submitted && !api.restoredSubmission;
   useEffect9(() => {
-    if (!liveSubmit || !settings.redirectUrl || typeof window === "undefined") return;
+    if (renderOnly || !liveSubmit || !settings.redirectUrl || typeof window === "undefined") return;
     const url = safeHttpUrl(settings.redirectUrl);
     if (url) window.location.assign(url);
-  }, [liveSubmit, settings.redirectUrl]);
+  }, [liveSubmit, settings.redirectUrl, renderOnly]);
   const successRef = useRef9(null);
   useEffect9(() => {
     if (liveSubmit) successRef.current?.focus();
@@ -3353,10 +3377,12 @@ function ResolvedForm(props) {
     const container = blocksRef.current?.parentElement;
     const heading = container?.querySelector(".fillo-page-title, .fillo-title");
     const target = heading ?? blocksRef.current;
-    if (!target) return;
-    if (!target.hasAttribute("tabindex")) target.setAttribute("tabindex", "-1");
-    target.focus();
-  }, [api.pageIndex]);
+    if (target) {
+      if (!target.hasAttribute("tabindex")) target.setAttribute("tabindex", "-1");
+      target.focus();
+    }
+    props.onPageChange?.(api.pageIndex);
+  }, [api.pageIndex, props.onPageChange]);
   const appearance = props.appearance;
   if (api.status === "submitted") {
     return /* @__PURE__ */ jsxs7(
@@ -3399,11 +3425,10 @@ function ResolvedForm(props) {
   const multiPage = api.pageCount > 1;
   const autoSubmit = settings.submitMode === "auto";
   const showChallenge = challengeRequired && api.isLastPage;
-  const showPrimaryButton = !autoSubmit || !api.isLastPage || needsExplicitSubmit(reachableFields(api.form, api.data)) || // A challenge needs an explicit Submit even on an otherwise button-less
-  // auto-submit form — you can't one-tap past a human check.
-  showChallenge;
-  const showFooter = showPrimaryButton || multiPage && !api.isFirstPage;
-  const progressSeq = reachablePageSequence(api.form, api.data);
+  const showPrimaryButton = previewNavigation || !autoSubmit || !api.isLastPage || needsExplicitSubmit(reachableFields(api.form, api.data)) || showChallenge;
+  const showPreviewSkip = previewNavigation && api.pageIndex < api.pageCount - 1;
+  const showFooter = showPrimaryButton || multiPage && !api.isFirstPage || showPreviewSkip;
+  const progressSeq = previewNavigation ? schema.pages.map((page) => page.id) : reachablePageSequence(api.form, api.data);
   const progressTotal = Math.max(progressSeq.length, 1);
   const progressPos = progressSeq.indexOf(api.page.id);
   const progressStep = progressPos >= 0 ? progressPos + 1 : Math.min(api.pageIndex + 1, progressTotal);
@@ -3594,6 +3619,21 @@ function ResolvedForm(props) {
               children: strings.back
             }
           ),
+          showPreviewSkip && /* @__PURE__ */ jsx8(
+            "button",
+            {
+              type: "button",
+              className: slotClass3("fillo-button fillo-button--ghost", appearance, {
+                slot: "button",
+                variant: "ghost"
+              }),
+              "data-fillo": "button",
+              "data-fillo-preview-skip": "",
+              onClick: api.skipPreviewPage,
+              disabled: api.status === "submitting",
+              children: strings.previewSkip
+            }
+          ),
           showPrimaryButton && /* @__PURE__ */ jsx8(
             "button",
             {
@@ -3603,10 +3643,7 @@ function ResolvedForm(props) {
                 variant: "primary"
               }),
               "data-fillo": "button",
-              disabled: api.status === "submitting" || api.uploading || // Wait for the human check before enabling submit (never
-              // "Next"). The server rejects a tokenless submit regardless —
-              // this is UX only.
-              showChallenge && !challengeToken,
+              disabled: api.status === "submitting" || api.uploading || showChallenge && !challengeToken,
               children: api.uploading ? strings.uploading : api.status === "submitting" ? strings.submitting : api.isLastPage ? settings.submitLabel ?? strings.submit : strings.next
             }
           )
@@ -3615,20 +3652,15 @@ function ResolvedForm(props) {
     ),
     props.poweredBy && /* @__PURE__ */ jsx8(PoweredBy, { label: props.brandLabel, href: props.brandHref })
   ] });
-  return /* @__PURE__ */ jsx8(FilloContext.Provider, { value: api, children: /* @__PURE__ */ jsx8(FilloChromeContext.Provider, { value: chromeValue, children: /* @__PURE__ */ jsx8(FilloAnnounceContext.Provider, { value: announce, children: /* @__PURE__ */ jsx8(FilloStringsContext.Provider, { value: strings, children: /* @__PURE__ */ jsx8(FilloAppearanceContext.Provider, { value: appearance, children: /* @__PURE__ */ jsx8(FilloInstanceIdContext.Provider, { value: instanceId, children: displayOnly ? (
-    // Display-only preview: a plain div (no form element to submit) with
-    // every control inside a natively disabled fieldset — unfocusable
-    // and unfillable even without the stylesheet or inert support.
-    /* @__PURE__ */ jsx8(
-      "div",
-      {
-        className: rootClass,
-        "data-fillo": "preview-form",
-        "data-state": "preview",
-        ...themed,
-        children: /* @__PURE__ */ jsx8("fieldset", { disabled: true, className: "fillo-not-open-fields", children: formBody })
-      }
-    )
+  return /* @__PURE__ */ jsx8(FilloContext.Provider, { value: api, children: /* @__PURE__ */ jsx8(FilloChromeContext.Provider, { value: chromeValue, children: /* @__PURE__ */ jsx8(FilloAnnounceContext.Provider, { value: announce, children: /* @__PURE__ */ jsx8(FilloStringsContext.Provider, { value: strings, children: /* @__PURE__ */ jsx8(FilloAppearanceContext.Provider, { value: appearance, children: /* @__PURE__ */ jsx8(FilloInstanceIdContext.Provider, { value: instanceId, children: displayOnly ? /* @__PURE__ */ jsx8(
+    "div",
+    {
+      className: rootClass,
+      "data-fillo": "preview-form",
+      "data-state": "preview",
+      ...themed,
+      children: /* @__PURE__ */ jsx8("fieldset", { disabled: true, className: "fillo-not-open-fields", children: formBody })
+    }
   ) : /* @__PURE__ */ jsx8(
     "form",
     {

package/dist/styles.css

@@ -93,22 +93,25 @@
   }
 
   .fillo-header { display: flex; flex-direction: column; gap: 0.5rem; }
-  .fillo-title { font-size: 1.6em; font-weight: 650; letter-spacing: 0; margin: 0; }
+  /* Text roles: title 1.5em, heading 1.125em, body 1em, helper 0.875em,
+     metadata 0.75em. Nested helper text inherits its container size.
+     Glyphs used as icons (stars, flags, carets) have independent sizes. */
+  .fillo-title { font-size: 1.5em; font-weight: 600; letter-spacing: 0; margin: 0; }
   .fillo-form-description { color: var(--fillo-muted); margin: 0; line-height: 1.55; }
-  .fillo-page-title { font-size: 1.2em; font-weight: 600; margin: 0; }
+  .fillo-page-title { font-size: 1.125em; font-weight: 600; margin: 0; }
 
   .fillo-blocks { display: flex; flex-direction: column; gap: 1.5rem; }
 
   /* ---------- Field chrome ---------- */
   .fillo-field { display: flex; flex-direction: column; gap: 0.45rem; }
-  .fillo-label { font-weight: 550; font-size: 0.95em; }
+  .fillo-label { font-weight: 500; font-size: 1em; }
   :where(.fillo-field--error) .fillo-label { color: var(--fillo-error); }
   /* Fillo marks the few optional fields rather than starring the many required
      ones — so a clean label reads as required by default. */
-  .fillo-optional { color: var(--fillo-muted); font-weight: 400; font-size: 0.85em; }
-  .fillo-description { color: var(--fillo-muted); font-size: 0.85em; margin: 0; line-height: 1.5; }
-  .fillo-error { color: var(--fillo-error); font-size: 0.85em; font-weight: 500; line-height: 1.4; margin: 0; }
-  .fillo-submit-error { color: var(--fillo-error); font-size: 0.85em; font-weight: 500; margin: 0; }
+  .fillo-optional { color: var(--fillo-muted); font-weight: 400; font-size: 0.875em; }
+  .fillo-description { color: var(--fillo-muted); font-size: 0.875em; margin: 0; line-height: 1.5; }
+  .fillo-error { color: var(--fillo-error); font-size: 0.875em; font-weight: 500; line-height: 1.4; margin: 0; }
+  .fillo-submit-error { color: var(--fillo-error); font-size: 0.875em; font-weight: 500; margin: 0; }
 
   /* ---------- Inputs ---------- */
   .fillo-input {
@@ -326,7 +329,7 @@
     gap: 0.55rem;
   }
   :where(.fillo-option--with-other) .fillo-option-label {
-    font-weight: 550;
+    font-weight: 500;
   }
 
   /* ---------- Toggle checkbox ---------- */
@@ -447,7 +450,7 @@
     min-width: 0;
     padding: 0.5rem 0.15rem;
     font: inherit;
-    font-size: 0.92em;
+    font-size: 1em;
     font-variant-numeric: tabular-nums;
     text-align: center;
     border: 1px solid var(--fillo-border);
@@ -476,7 +479,7 @@
     display: flex;
     justify-content: space-between;
     color: var(--fillo-muted);
-    font-size: 0.78em;
+    font-size: 0.875em;
     margin-top: 0.35rem;
   }
 
@@ -499,8 +502,8 @@
     border-radius: 999px;
     background: color-mix(in srgb, var(--fillo-primary) 10%, transparent);
     color: var(--fillo-primary);
-    font-size: 0.78em;
-    font-weight: 650;
+    font-size: 0.875em;
+    font-weight: 600;
     font-variant-numeric: tabular-nums;
   }
   .fillo-ranking-label { flex: 1; font-size: 1em; }
@@ -522,13 +525,13 @@
 
   /* ---------- Matrix ---------- */
   .fillo-matrix-wrap { overflow-x: auto; }
-  .fillo-matrix { border-collapse: collapse; width: 100%; font-size: 0.9em; }
+  .fillo-matrix { border-collapse: collapse; width: 100%; font-size: 1em; }
   :where(.fillo-matrix) th, :where(.fillo-matrix) td {
     padding: 0.55rem 0.7rem;
     text-align: center;
     border-bottom: 1px solid var(--fillo-border);
   }
-  .fillo-matrix thead th { color: var(--fillo-muted); font-weight: 500; font-size: 0.89em; }
+  .fillo-matrix thead th { color: var(--fillo-muted); font-weight: 500; font-size: 0.875em; }
   .fillo-matrix tbody th { text-align: start; font-weight: 500; }
   .fillo-matrix tbody tr:last-child th, .fillo-matrix tbody tr:last-child td { border-bottom: none; }
   .fillo-matrix-cell:focus-within {
@@ -542,7 +545,7 @@
   /* A quiet computed-value line, not a control: no border or input chrome —
      the slightly heavier tabular number is the only emphasis. */
   .fillo-calculated-value {
-    font-size: 1.05em;
+    font-size: 1em;
     font-weight: 600;
     font-variant-numeric: tabular-nums;
     color: var(--fillo-text);
@@ -571,7 +574,7 @@
     display: grid;
     place-items: center;
     color: var(--fillo-muted);
-    font-size: 0.85em;
+    font-size: 0.875em;
     pointer-events: none;
   }
   .fillo-signature-clear {
@@ -579,7 +582,7 @@
     top: 0.4rem;
     inset-inline-end: 0.4rem;
     font: inherit;
-    font-size: 0.75em;
+    font-size: 0.875em;
     border: 1px solid var(--fillo-border);
     border-radius: calc(var(--fillo-radius) * 0.6);
     background: var(--fillo-control-bg);
@@ -598,7 +601,7 @@
   }
   .fillo-signature-type-label {
     color: var(--fillo-muted);
-    font-size: 0.8em;
+    font-size: 0.875em;
   }
   .fillo-signature-type-input {
     margin-top: 0;
@@ -638,8 +641,8 @@
     outline: none;
   }
   .fillo-dropzone--disabled { cursor: not-allowed; opacity: 0.6; }
-  .fillo-dropzone-title { font-weight: 550; font-size: 0.95em; }
-  .fillo-dropzone-hint { color: var(--fillo-muted); font-size: 0.82em; }
+  .fillo-dropzone-title { font-weight: 500; font-size: 1em; }
+  .fillo-dropzone-hint { color: var(--fillo-muted); font-size: 0.875em; }
 
   .fillo-files { list-style: none; display: flex; flex-direction: column; gap: 0.45rem; margin: 0; padding: 0; }
   .fillo-file {
@@ -650,7 +653,7 @@
     border: 1px solid var(--fillo-border);
     border-radius: var(--fillo-radius);
     padding: 0.625rem 0.75rem;
-    font-size: 0.88em;
+    font-size: 1em;
     background: var(--fillo-control-bg);
     box-sizing: border-box;
     min-width: 0;
@@ -710,7 +713,7 @@
   }
   .fillo-file-error {
     color: var(--fillo-error);
-    font-size: 0.93em;
+    font-size: 0.875em;
     line-height: 1.35;
     overflow-wrap: anywhere;
   }
@@ -745,7 +748,7 @@
     cursor: pointer;
     color: var(--fillo-primary);
     font: inherit;
-    font-weight: 550;
+    font-weight: 500;
     padding: 0 0.5rem;
   }
   .fillo-file-retry:hover { text-decoration: underline; }
@@ -765,7 +768,7 @@
   }
 
   /* ---------- Content blocks ---------- */
-  .fillo-heading { font-size: 1.15em; font-weight: 600; margin: 0.5rem 0 0; }
+  .fillo-heading { font-size: 1.125em; font-weight: 600; margin: 0.5rem 0 0; }
   .fillo-paragraph { color: var(--fillo-muted); line-height: 1.6; margin: 0; }
   .fillo-divider { border: none; border-top: 1px solid var(--fillo-border); margin: 0.25rem 0; }
 
@@ -773,7 +776,7 @@
   .fillo-footer { display: flex; justify-content: flex-end; gap: 0.6rem; }
   .fillo-button {
     font: inherit;
-    font-weight: 550;
+    font-weight: 500;
     border-radius: var(--fillo-radius);
     padding: 0.6rem 1.4rem;
     cursor: pointer;
@@ -839,7 +842,7 @@
     padding: 2rem 1rem;
     text-align: center;
   }
-  .fillo-not-open-title { margin: 0; font-size: 1.05em; font-weight: 650; letter-spacing: 0; }
+  .fillo-not-open-title { margin: 0; font-size: 1.125em; font-weight: 600; letter-spacing: 0; }
   .fillo-not-open-body {
     max-width: 26rem;
     margin: 0;
@@ -867,7 +870,7 @@
     border-bottom: 2.5px solid var(--fillo-primary-contrast);
     transform: translateY(-0.09rem) rotate(-45deg);
   }
-  .fillo-success-title { margin: 0; font-size: 1.05em; letter-spacing: 0; }
+  .fillo-success-title { margin: 0; font-weight: 600; font-size: 1.125em; letter-spacing: 0; }
   .fillo-success-message { margin: 0; font-size: 0.875em; color: var(--fillo-muted); }
 
   /* Honeypot — off-screen, never display:none (bots check that) */
@@ -947,12 +950,12 @@
     border-radius: var(--fillo-radius);
     background: #fffbeb;
     color: #92400e;
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
   .fillo-devwarning code {
     font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-    font-size: 0.92em;
+    font-size: 1em;
     background: #fef3c7;
     padding: 0.05em 0.3em;
     border-radius: 4px;
@@ -966,7 +969,7 @@
     border-radius: 999px;
     background: #fef3c7;
     color: #92400e;
-    font-size: 0.7em;
+    font-size: 0.75em;
     font-weight: 600;
     letter-spacing: 0.06em;
     text-transform: uppercase;
@@ -984,7 +987,7 @@
     border-radius: var(--fillo-radius);
     background: var(--fillo-control-bg);
     color: var(--fillo-muted);
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
   .fillo-resume-clear {
@@ -1024,7 +1027,7 @@
   .fillo-turnstile-error {
     margin: 0;
     color: var(--fillo-error);
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
 
@@ -1045,7 +1048,7 @@
     justify-content: space-between;
     gap: 0.5rem;
   }
-  .fillo-group-instance-title { margin: 0; font-size: 0.95em; font-weight: 600; }
+  .fillo-group-instance-title { margin: 0; font-size: 1.125em; font-weight: 600; }
   .fillo-group-add {
     align-self: flex-start;
     font: inherit;
@@ -1133,7 +1136,7 @@
     .fillo-matrix tbody th { padding: 0.55rem 0 0.15rem; }
     .fillo-matrix td { display: flex; align-items: center; gap: 0.5rem; }
     .fillo-matrix td::before { content: attr(data-label);
-      flex: 1 1 auto; font-size: 0.85em; }
+      flex: 1 1 auto; font-size: 0.875em; }
     /* Deviates from the spec's literal ".fillo-matrix .fillo-matrix-cell"
        text (two bare fillo-* classes, no :where()) — that fails this file's
        own specificity lint (styles-lint.test.mjs: "wrap qualifiers in

package/dist/styles.unlayered.css

@@ -93,22 +93,25 @@
   }
 
   .fillo-header { display: flex; flex-direction: column; gap: 0.5rem; }
-  .fillo-title { font-size: 1.6em; font-weight: 650; letter-spacing: 0; margin: 0; }
+  /* Text roles: title 1.5em, heading 1.125em, body 1em, helper 0.875em,
+     metadata 0.75em. Nested helper text inherits its container size.
+     Glyphs used as icons (stars, flags, carets) have independent sizes. */
+  .fillo-title { font-size: 1.5em; font-weight: 600; letter-spacing: 0; margin: 0; }
   .fillo-form-description { color: var(--fillo-muted); margin: 0; line-height: 1.55; }
-  .fillo-page-title { font-size: 1.2em; font-weight: 600; margin: 0; }
+  .fillo-page-title { font-size: 1.125em; font-weight: 600; margin: 0; }
 
   .fillo-blocks { display: flex; flex-direction: column; gap: 1.5rem; }
 
   /* ---------- Field chrome ---------- */
   .fillo-field { display: flex; flex-direction: column; gap: 0.45rem; }
-  .fillo-label { font-weight: 550; font-size: 0.95em; }
+  .fillo-label { font-weight: 500; font-size: 1em; }
   :where(.fillo-field--error) .fillo-label { color: var(--fillo-error); }
   /* Fillo marks the few optional fields rather than starring the many required
      ones — so a clean label reads as required by default. */
-  .fillo-optional { color: var(--fillo-muted); font-weight: 400; font-size: 0.85em; }
-  .fillo-description { color: var(--fillo-muted); font-size: 0.85em; margin: 0; line-height: 1.5; }
-  .fillo-error { color: var(--fillo-error); font-size: 0.85em; font-weight: 500; line-height: 1.4; margin: 0; }
-  .fillo-submit-error { color: var(--fillo-error); font-size: 0.85em; font-weight: 500; margin: 0; }
+  .fillo-optional { color: var(--fillo-muted); font-weight: 400; font-size: 0.875em; }
+  .fillo-description { color: var(--fillo-muted); font-size: 0.875em; margin: 0; line-height: 1.5; }
+  .fillo-error { color: var(--fillo-error); font-size: 0.875em; font-weight: 500; line-height: 1.4; margin: 0; }
+  .fillo-submit-error { color: var(--fillo-error); font-size: 0.875em; font-weight: 500; margin: 0; }
 
   /* ---------- Inputs ---------- */
   .fillo-input {
@@ -326,7 +329,7 @@
     gap: 0.55rem;
   }
   :where(.fillo-option--with-other) .fillo-option-label {
-    font-weight: 550;
+    font-weight: 500;
   }
 
   /* ---------- Toggle checkbox ---------- */
@@ -447,7 +450,7 @@
     min-width: 0;
     padding: 0.5rem 0.15rem;
     font: inherit;
-    font-size: 0.92em;
+    font-size: 1em;
     font-variant-numeric: tabular-nums;
     text-align: center;
     border: 1px solid var(--fillo-border);
@@ -476,7 +479,7 @@
     display: flex;
     justify-content: space-between;
     color: var(--fillo-muted);
-    font-size: 0.78em;
+    font-size: 0.875em;
     margin-top: 0.35rem;
   }
 
@@ -499,8 +502,8 @@
     border-radius: 999px;
     background: color-mix(in srgb, var(--fillo-primary) 10%, transparent);
     color: var(--fillo-primary);
-    font-size: 0.78em;
-    font-weight: 650;
+    font-size: 0.875em;
+    font-weight: 600;
     font-variant-numeric: tabular-nums;
   }
   .fillo-ranking-label { flex: 1; font-size: 1em; }
@@ -522,13 +525,13 @@
 
   /* ---------- Matrix ---------- */
   .fillo-matrix-wrap { overflow-x: auto; }
-  .fillo-matrix { border-collapse: collapse; width: 100%; font-size: 0.9em; }
+  .fillo-matrix { border-collapse: collapse; width: 100%; font-size: 1em; }
   :where(.fillo-matrix) th, :where(.fillo-matrix) td {
     padding: 0.55rem 0.7rem;
     text-align: center;
     border-bottom: 1px solid var(--fillo-border);
   }
-  .fillo-matrix thead th { color: var(--fillo-muted); font-weight: 500; font-size: 0.89em; }
+  .fillo-matrix thead th { color: var(--fillo-muted); font-weight: 500; font-size: 0.875em; }
   .fillo-matrix tbody th { text-align: start; font-weight: 500; }
   .fillo-matrix tbody tr:last-child th, .fillo-matrix tbody tr:last-child td { border-bottom: none; }
   .fillo-matrix-cell:focus-within {
@@ -542,7 +545,7 @@
   /* A quiet computed-value line, not a control: no border or input chrome —
      the slightly heavier tabular number is the only emphasis. */
   .fillo-calculated-value {
-    font-size: 1.05em;
+    font-size: 1em;
     font-weight: 600;
     font-variant-numeric: tabular-nums;
     color: var(--fillo-text);
@@ -571,7 +574,7 @@
     display: grid;
     place-items: center;
     color: var(--fillo-muted);
-    font-size: 0.85em;
+    font-size: 0.875em;
     pointer-events: none;
   }
   .fillo-signature-clear {
@@ -579,7 +582,7 @@
     top: 0.4rem;
     inset-inline-end: 0.4rem;
     font: inherit;
-    font-size: 0.75em;
+    font-size: 0.875em;
     border: 1px solid var(--fillo-border);
     border-radius: calc(var(--fillo-radius) * 0.6);
     background: var(--fillo-control-bg);
@@ -598,7 +601,7 @@
   }
   .fillo-signature-type-label {
     color: var(--fillo-muted);
-    font-size: 0.8em;
+    font-size: 0.875em;
   }
   .fillo-signature-type-input {
     margin-top: 0;
@@ -638,8 +641,8 @@
     outline: none;
   }
   .fillo-dropzone--disabled { cursor: not-allowed; opacity: 0.6; }
-  .fillo-dropzone-title { font-weight: 550; font-size: 0.95em; }
-  .fillo-dropzone-hint { color: var(--fillo-muted); font-size: 0.82em; }
+  .fillo-dropzone-title { font-weight: 500; font-size: 1em; }
+  .fillo-dropzone-hint { color: var(--fillo-muted); font-size: 0.875em; }
 
   .fillo-files { list-style: none; display: flex; flex-direction: column; gap: 0.45rem; margin: 0; padding: 0; }
   .fillo-file {
@@ -650,7 +653,7 @@
     border: 1px solid var(--fillo-border);
     border-radius: var(--fillo-radius);
     padding: 0.625rem 0.75rem;
-    font-size: 0.88em;
+    font-size: 1em;
     background: var(--fillo-control-bg);
     box-sizing: border-box;
     min-width: 0;
@@ -710,7 +713,7 @@
   }
   .fillo-file-error {
     color: var(--fillo-error);
-    font-size: 0.93em;
+    font-size: 0.875em;
     line-height: 1.35;
     overflow-wrap: anywhere;
   }
@@ -745,7 +748,7 @@
     cursor: pointer;
     color: var(--fillo-primary);
     font: inherit;
-    font-weight: 550;
+    font-weight: 500;
     padding: 0 0.5rem;
   }
   .fillo-file-retry:hover { text-decoration: underline; }
@@ -765,7 +768,7 @@
   }
 
   /* ---------- Content blocks ---------- */
-  .fillo-heading { font-size: 1.15em; font-weight: 600; margin: 0.5rem 0 0; }
+  .fillo-heading { font-size: 1.125em; font-weight: 600; margin: 0.5rem 0 0; }
   .fillo-paragraph { color: var(--fillo-muted); line-height: 1.6; margin: 0; }
   .fillo-divider { border: none; border-top: 1px solid var(--fillo-border); margin: 0.25rem 0; }
 
@@ -773,7 +776,7 @@
   .fillo-footer { display: flex; justify-content: flex-end; gap: 0.6rem; }
   .fillo-button {
     font: inherit;
-    font-weight: 550;
+    font-weight: 500;
     border-radius: var(--fillo-radius);
     padding: 0.6rem 1.4rem;
     cursor: pointer;
@@ -839,7 +842,7 @@
     padding: 2rem 1rem;
     text-align: center;
   }
-  .fillo-not-open-title { margin: 0; font-size: 1.05em; font-weight: 650; letter-spacing: 0; }
+  .fillo-not-open-title { margin: 0; font-size: 1.125em; font-weight: 600; letter-spacing: 0; }
   .fillo-not-open-body {
     max-width: 26rem;
     margin: 0;
@@ -867,7 +870,7 @@
     border-bottom: 2.5px solid var(--fillo-primary-contrast);
     transform: translateY(-0.09rem) rotate(-45deg);
   }
-  .fillo-success-title { margin: 0; font-size: 1.05em; letter-spacing: 0; }
+  .fillo-success-title { margin: 0; font-weight: 600; font-size: 1.125em; letter-spacing: 0; }
   .fillo-success-message { margin: 0; font-size: 0.875em; color: var(--fillo-muted); }
 
   /* Honeypot — off-screen, never display:none (bots check that) */
@@ -947,12 +950,12 @@
     border-radius: var(--fillo-radius);
     background: #fffbeb;
     color: #92400e;
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
   .fillo-devwarning code {
     font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-    font-size: 0.92em;
+    font-size: 1em;
     background: #fef3c7;
     padding: 0.05em 0.3em;
     border-radius: 4px;
@@ -966,7 +969,7 @@
     border-radius: 999px;
     background: #fef3c7;
     color: #92400e;
-    font-size: 0.7em;
+    font-size: 0.75em;
     font-weight: 600;
     letter-spacing: 0.06em;
     text-transform: uppercase;
@@ -984,7 +987,7 @@
     border-radius: var(--fillo-radius);
     background: var(--fillo-control-bg);
     color: var(--fillo-muted);
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
   .fillo-resume-clear {
@@ -1024,7 +1027,7 @@
   .fillo-turnstile-error {
     margin: 0;
     color: var(--fillo-error);
-    font-size: 0.82em;
+    font-size: 0.875em;
     line-height: 1.45;
   }
 
@@ -1045,7 +1048,7 @@
     justify-content: space-between;
     gap: 0.5rem;
   }
-  .fillo-group-instance-title { margin: 0; font-size: 0.95em; font-weight: 600; }
+  .fillo-group-instance-title { margin: 0; font-size: 1.125em; font-weight: 600; }
   .fillo-group-add {
     align-self: flex-start;
     font: inherit;
@@ -1133,7 +1136,7 @@
     .fillo-matrix tbody th { padding: 0.55rem 0 0.15rem; }
     .fillo-matrix td { display: flex; align-items: center; gap: 0.5rem; }
     .fillo-matrix td::before { content: attr(data-label);
-      flex: 1 1 auto; font-size: 0.85em; }
+      flex: 1 1 auto; font-size: 0.875em; }
     /* Deviates from the spec's literal ".fillo-matrix .fillo-matrix-cell"
        text (two bare fillo-* classes, no :where()) — that fails this file's
        own specificity lint (styles-lint.test.mjs: "wrap qualifiers in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/react",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Headless React components for embedding Fillo forms natively in your product.",
   "license": "MIT",
   "keywords": [
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@usefillo/core": "^0.20.0"
+    "@usefillo/core": "^0.21.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",