# Field

Own the label, helper text, and error for exactly one form control.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: curated
Source: packages/design-system/src/components/forms/Field/Field.tsx

## Guidance

{
  "summary": "Own the label, helper text, and error for exactly one form control.",
  "when_to_use": [
    "A control needs a visible label or explanatory message.",
    "A validation error should also mark its control invalid.",
    "A field is required or disabled as a unit."
  ],
  "avoid": [
    "Placing two Field-aware controls inside one Field.",
    "Duplicating error text below the Input.",
    "Overriding control IDs or accessible labels without preserving the visible label association."
  ],
  "accessibility": [
    "Field owns stable IDs for its label, description, and control.",
    "An error replaces helper text and is referenced by aria-describedby.",
    "Required markers are decorative; the child receives native required semantics."
  ],
  "constraints": [
    "Compatible controls consume FieldContext at any nesting depth.",
    "Explicit child props take precedence over context values."
  ]
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "label",
      "type": "string",
      "required": false,
      "description": "Visible label text, tied to the control by `htmlFor`. Without it (and `action`) no header renders."
    },
    {
      "name": "helperText",
      "type": "string",
      "required": false,
      "description": "Supporting copy shown below the control when there is no error."
    },
    {
      "name": "error",
      "type": "string",
      "required": false,
      "description": "Error copy shown below the control, announced through aria-describedby, and\npublished to the control so it paints its own invalid treatment."
    },
    {
      "name": "action",
      "type": "React.ReactNode",
      "required": false,
      "description": "Optional action aligned with the label, e.g. \"Add\" or \"Use current\"."
    },
    {
      "name": "required",
      "type": "boolean",
      "required": false,
      "description": "Adds the required marker and passes `required` to compatible controls."
    },
    {
      "name": "disabled",
      "type": "boolean",
      "required": false,
      "description": "Passes disabled state to compatible controls."
    },
    {
      "name": "children",
      "type": "React.ReactNode",
      "required": true,
      "description": "The one control to wrap. It reads its label, description, and validation wiring from\ncontext, which reaches any depth — so two Field-aware controls under one Field would\nboth adopt the same DOM id. Give each control its own Field."
    },
    {
      "name": "id",
      "type": "string",
      "required": false,
      "description": ""
    },
    {
      "name": "className",
      "type": "string",
      "required": false,
      "description": ""
    },
    {
      "name": "testId",
      "type": "string",
      "required": false,
      "description": "Test id for the wrapper only; the control keeps whatever test id it was given."
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Field",
    "public_path": "Field",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Field",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/forms/Field/Field.tsx",
          "line": 45
        },
        "props_type": "FieldProps",
        "props": [
          {
            "name": "label",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Visible label text, tied to the control by `htmlFor`. Without it (and `action`) no header renders.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 13
            }
          },
          {
            "name": "helperText",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Supporting copy shown below the control when there is no error.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 15
            }
          },
          {
            "name": "error",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Error copy shown below the control, announced through aria-describedby, and\npublished to the control so it paints its own invalid treatment.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 20
            }
          },
          {
            "name": "action",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Optional action aligned with the label, e.g. \"Add\" or \"Use current\".",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 22
            }
          },
          {
            "name": "required",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Adds the required marker and passes `required` to compatible controls.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 24
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Passes disabled state to compatible controls.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 26
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "The one control to wrap. It reads its label, description, and validation wiring from\ncontext, which reaches any depth — so two Field-aware controls under one Field would\nboth adopt the same DOM id. Give each control its own Field.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 32
            }
          },
          {
            "name": "id",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 33
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 34
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Test id for the wrapper only; the control keeps whatever test id it was given.",
            "source": {
              "path": "packages/design-system/src/components/forms/Field/Field.tsx",
              "line": 36
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/forms/Field/Field.tsx",
        "line": 11,
        "name": "FieldProps",
        "code": "export interface FieldProps {\n    /** Visible label text, tied to the control by `htmlFor`. Without it (and `action`) no header renders. */\n    label?: string;\n    /** Supporting copy shown below the control when there is no error. */\n    helperText?: string;\n    /**\n     * Error copy shown below the control, announced through aria-describedby, and\n     * published to the control so it paints its own invalid treatment.\n     */\n    error?: string;\n    /** Optional action aligned with the label, e.g. \"Add\" or \"Use current\". */\n    action?: React.ReactNode;\n    /** Adds the required marker and passes `required` to compatible controls. */\n    required?: boolean;\n    /** Passes disabled state to compatible controls. */\n    disabled?: boolean;\n    /**\n     * The one control to wrap. It reads its label, description, and validation wiring from\n     * context, which reaches any depth — so two Field-aware controls under one Field would\n     * both adopt the same DOM id. Give each control its own Field.\n     */\n    children: React.ReactNode;\n    id?: string;\n    className?: string;\n    /** Test id for the wrapper only; the control keeps whatever test id it was given. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Field",
      "status": "preview",
      "version": "2.0.0",
      "summary": "A form-control wrapper that owns visible labelling, optional label-side action, required state, helper copy, and validation — including the invalid state the child control renders."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Stacks header, one compatible control, and one supporting message."
      },
      {
        "id": "header",
        "label": "Header",
        "description": "Aligns the visible label and optional label-side action."
      },
      {
        "id": "label",
        "label": "Label",
        "description": "Provides the persistent visible and programmatic name for the child control."
      },
      {
        "id": "required-mark",
        "label": "Required mark",
        "description": "Visually indicates required input without becoming part of the label text."
      },
      {
        "id": "action",
        "label": "Label-side action",
        "description": "Optional compact action related to the field, such as Add or Use current."
      },
      {
        "id": "control",
        "label": "Child control",
        "description": "Exactly one compatible form control receiving label, message, required, disabled, and invalid wiring."
      },
      {
        "id": "helper-message",
        "label": "Helper message",
        "description": "Supporting copy shown only while there is no error."
      },
      {
        "id": "error-message",
        "label": "Error message",
        "description": "Corrective copy that replaces helper text and marks the control invalid."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "labelled": {
          "label": "Labelled",
          "description": "One field wrapper whose optional parts are configured independently."
        }
      },
      "sizes": {}
    },
    "variants": [
      {
        "id": "labelled",
        "label": "Labelled",
        "description": "Persistent label and message scaffolding around one compatible form control.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "stack-gap",
        "label": "Field stack gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "root",
          "header",
          "control",
          "helper-message",
          "error-message"
        ]
      },
      {
        "id": "header-gap",
        "label": "Label-to-action minimum gap",
        "kind": "exact",
        "token": "--cds-space-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "header",
          "label",
          "action"
        ]
      },
      {
        "id": "required-mark-gap",
        "label": "Label-to-required-mark gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "label",
          "required-mark"
        ]
      }
    ],
    "layout": {
      "alignment": "Label begins at the control edge while a label-side action remains trailing; messages align with the control.",
      "flow": "Optional header, exactly one child control, then either helper or error copy.",
      "notes": [
        "Use Field whenever a control needs a persistent visible label, supporting message, or validation; the label itself is optional.",
        "Do not place multiple controls under one Field instance."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Label and messages",
          "description": "Use body-small text for labels, helpers, and validation copy.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Label",
          "description": "Use primary text emphasis for the persistent label.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Helper",
          "description": "Use secondary emphasis for non-critical supporting copy.",
          "token": "--cds-text-secondary"
        },
        {
          "label": "Required and error",
          "description": "Use the readable semantic danger role for error indication in both themes.",
          "token": "--cds-text-danger"
        }
      ]
    },
    "states": [
      {
        "id": "default",
        "label": "Default",
        "description": "Shows the label and child control without supporting copy."
      },
      {
        "id": "helper",
        "label": "Helper",
        "description": "Associates non-critical supporting copy with the control."
      },
      {
        "id": "required",
        "label": "Required",
        "description": "Shows the visual mark and forwards required semantics."
      },
      {
        "id": "error",
        "label": "Error",
        "description": "Replaces helper copy, associates the error, and puts the child control into its invalid treatment."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Forwards disabled state while retaining label and supporting context."
      }
    ],
    "behavior": [
      {
        "label": "Child wiring",
        "description": "Publish id, disabled, required, labelled-by, described-by, and invalid to the child control, which fills in only the values it does not set itself."
      },
      {
        "label": "Invalid propagation",
        "description": "Publish invalid state to the child control so the control renders its own invalid treatment without the caller setting the error twice. A control that sets invalid itself keeps its own value. The wiring travels by context, so it still reaches a control nested inside a wrapper component."
      },
      {
        "label": "Message precedence",
        "description": "Show and associate error copy instead of helper copy whenever an error is present."
      },
      {
        "label": "Label-side action",
        "description": "Keep the optional action separate from the child control and give the action its own name and test identifier."
      }
    ],
    "accessibility": [
      {
        "label": "Persistent name",
        "description": "Bind the visible label to the child control through id and labelled-by relationships."
      },
      {
        "label": "Message relationship",
        "description": "Associate the one visible helper or error message through described-by."
      },
      {
        "label": "Required mark",
        "description": "Hide the decorative asterisk from assistive technology and forward required state to the control."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Long labels",
        "description": "Allow the label to wrap while preserving space for a compact trailing action."
      },
      {
        "label": "Corrective errors",
        "description": "Write errors as specific correction guidance rather than repeating the label."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Message replacement",
          "description": "Helper and error copy may replace one another without animating or moving the child control independently."
        }
      ],
      "haptics": [
        {
          "label": "No intrinsic feedback",
          "description": "Field owns no interaction; the child control and label-side action own their haptics."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Web associates the label and messages with DOM id and ARIA references; native implementations use platform accessibility labels, values, hints, and errors.",
        "rationale": "The visible hierarchy is shared while each platform uses its native form relationship APIs."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-space-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    },
    {
      "name": "--cds-text-danger",
      "light": "#b83100",
      "dark": "color-mix(in srgb, #b83100 60%, #ffffff)"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "preview",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-forms-field--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [With Helper Text](/storybook/iframe.html?id=cloaked-design-system-forms-field--with-helper-text&viewMode=story) | export: WithHelperText | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [With Action](/storybook/iframe.html?id=cloaked-design-system-forms-field--with-action&viewMode=story) | export: WithAction | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [With Error](/storybook/iframe.html?id=cloaked-design-system-forms-field--with-error&viewMode=story) | export: WithError | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Without Label](/storybook/iframe.html?id=cloaked-design-system-forms-field--without-label&viewMode=story) | export: WithoutLabel | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Do Field Owns Error](/storybook/iframe.html?id=cloaked-design-system-forms-field--do-field-owns-error&viewMode=story) | export: DoFieldOwnsError | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Dont Hand Roll The Message](/storybook/iframe.html?id=cloaked-design-system-forms-field--dont-hand-roll-the-message&viewMode=story) | export: DontHandRollTheMessage | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Required](/storybook/iframe.html?id=cloaked-design-system-forms-field--required&viewMode=story) | export: Required | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Disabled](/storybook/iframe.html?id=cloaked-design-system-forms-field--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [State Matrix](/storybook/iframe.html?id=cloaked-design-system-forms-field--state-matrix&viewMode=story) | export: StateMatrix | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Long Label And Helper](/storybook/iframe.html?id=cloaked-design-system-forms-field--long-label-and-helper&viewMode=story) | export: LongLabelAndHelper | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-forms-field--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/forms/Field/Field.stories.tsx

## Field and Input playground

Source: packages/design-system/examples/InputPlayground.tsx

```tsx
import { useState } from 'react';
import { Field, Input } from '../src';
import { DemoFrame, SelectControl } from './DemoFrame';
import { inputExampleCode, type InputExampleProps } from './code';

export function InputPlayground() {
  const [email, setEmail] = useState('');
  const [size, setSize] = useState<InputExampleProps['size']>('md');
  const [state, setState] = useState<InputExampleProps['state']>('default');
  const error = state === 'invalid' ? 'Enter an email address, such as name@example.com.' : undefined;
  return <DemoFrame code={inputExampleCode({ size, state })} controls={<>
    <SelectControl label="Size" value={size} options={['md', 'sm']} onChange={value => setSize(value as InputExampleProps['size'])} />
    <SelectControl label="State" value={state} options={['default', 'invalid', 'disabled']} onChange={value => setState(value as InputExampleProps['state'])} />
  </>}>
    <div className="demo-input-stage">
      <Field label="Email address" helperText="Use the address you check regularly." error={error} disabled={state === 'disabled'}>
        <Input type="email" size={size} value={email} onChange={setEmail} autoComplete="email" />
      </Field>
    </div>
  </DemoFrame>;
}
```

## Create a protected email

Source: packages/design-system/examples/ProtectedEmailFlow.tsx

```tsx
import { useEffect, useLayoutEffect, useRef, useState, type FormEvent } from 'react';
import { Button, Field, Input } from '../src';
import { DemoFrame } from './DemoFrame';
import { createSampleIdentity, validateIdentity, type IdentityDraft, type IdentityErrors } from './protected-email';

const EMPTY_DRAFT: IdentityDraft = { name: '', website: '' };

export function ProtectedEmailFlow() {
  const [draft, setDraft] = useState<IdentityDraft>(EMPTY_DRAFT);
  const [errors, setErrors] = useState<IdentityErrors>({});
  const [stage, setStage] = useState<'editing' | 'loading' | 'success'>('editing');
  const form = useRef<HTMLFormElement>(null);
  const success = useRef<HTMLHeadingElement>(null);
  useEffect(() => {
    if (stage !== 'loading') return;
    const timer = window.setTimeout(() => setStage('success'), 700);
    return () => window.clearTimeout(timer);
  }, [stage]);
  useEffect(() => { if (stage === 'success') success.current?.focus(); }, [stage]);
  useLayoutEffect(() => {
    if (Object.keys(errors).length) form.current?.querySelector<HTMLInputElement>('[aria-invalid="true"]')?.focus();
  }, [errors]);
  const restart = () => {
    setDraft(EMPTY_DRAFT); setErrors({}); setStage('editing');
    requestAnimationFrame(() => form.current?.querySelector<HTMLInputElement>('input')?.focus());
  };
  const submit = (event: FormEvent) => {
    event.preventDefault();
    if (stage !== 'editing') return;
    const nextErrors = validateIdentity(draft);
    setErrors(nextErrors);
    if (Object.keys(nextErrors).length) return;
    setStage('loading');
  };
  return <DemoFrame><section className="demo-flow" aria-label="Create a protected email example">
    <p className="demo-sample-note">Interactive example · Sample data only. Nothing is sent or saved.</p>
    {stage === 'success' ? <FlowSuccess draft={draft} headingRef={success} restart={restart} /> :
      <form ref={form} noValidate onSubmit={submit} aria-busy={stage === 'loading'}>
        <FlowHeading />
        <FlowFields draft={draft} errors={errors} loading={stage === 'loading'} change={setDraft} submit={() => form.current?.requestSubmit()} />
        <Button variant="primary" size="md" fullWidth loading={stage === 'loading'} onPress={() => form.current?.requestSubmit()}>Create protected email</Button>
        <p className="demo-feedback" role="status">{stage === 'loading' ? 'Creating your sample address…' : 'Your personal email stays yours.'}</p>
      </form>}
  </section></DemoFrame>;
}

function FlowHeading() {
  return <div className="demo-flow-heading">
    <span className="demo-symbol" aria-hidden="true">@</span>
    <span className="demo-eyebrow">A little more privacy</span>
    <h2>An email for this part of your life.</h2>
    <p>Give it a name so you know where you used it.</p>
  </div>;
}

function FlowFields({ draft, errors, loading, change, submit }: {
  draft: IdentityDraft; errors: IdentityErrors; loading: boolean;
  change: (draft: IdentityDraft) => void; submit: () => void;
}) {
  return <div className="demo-flow-fields">
    <Field label="Name" helperText="For example, shopping or a newsletter." error={errors.name} required disabled={loading}>
      <Input value={draft.name} onChange={name => change({ ...draft, name })} placeholder="Shopping"
        name="identity-name" autoComplete="off" maxLength={80} enterKeyHint="next" />
    </Field>
    <Field label="Website (optional)" helperText="A reminder of where you'll use this address." error={errors.website} disabled={loading}>
      <Input value={draft.website} onChange={website => change({ ...draft, website })} placeholder="example.com"
        name="identity-website" autoComplete="off" inputMode="url" autoCapitalize="none" maxLength={200}
        enterKeyHint="done" enterBehavior="callback" onEnter={submit} />
    </Field>
  </div>;
}

function FlowSuccess({ draft, headingRef, restart }: {
  draft: IdentityDraft; headingRef: React.RefObject<HTMLHeadingElement>; restart: () => void;
}) {
  const identity = createSampleIdentity(draft);
  return <div className="demo-flow-success">
    <span className="demo-symbol demo-symbol-success" aria-hidden="true">✓</span>
    <span className="demo-eyebrow">Ready to use</span>
    <h2 ref={headingRef} tabIndex={-1}>A fresh address for {identity.name}.</h2>
    <p>This sample address demonstrates the result. It cannot receive email.</p>
    <div className="demo-email-result"><span>Protected email</span><strong>{identity.email}</strong></div>
    <Button variant="secondary" size="md" fullWidth onPress={restart}>Try the flow again</Button>
  </div>;
}
```

## Surfaces

Source: packages/design-system/examples/foundations/FoundationSurfaces.tsx

```tsx
import { useState } from 'react';
import { Field, Input, Text } from '../../src';
import { FoundationFrame } from './FoundationShared';

export function FoundationSurfaces() {
  const [name, setName] = useState('Shopping');
  return <FoundationFrame code={`const page = { background: 'var(--cds-bg-page)', color: 'var(--cds-text-primary)' };\nconst card = { background: 'var(--cds-bg-surface)' };\nconst inverse = { background: 'var(--cds-bg-inverse)', color: 'var(--cds-text-inverse)' };`}>
    <div className="foundation-surface-page">
      <code>--cds-bg-page</code>
      <div className="foundation-surface-card">
        <code>--cds-bg-surface</code>
        <Text as="h2" variant="h3-serif">Give your address a home.</Text>
        <Field label="Address name" helperText="A useful label makes it easier to find later.">
          <Input value={name} onChange={setName} placeholder="Shopping" autoComplete="off" />
        </Field>
        <code>Input → --cds-input-container</code>
      </div>
    </div>
    <div className="foundation-surface-inverse" data-testid="surface-inverse" style={{ background: 'var(--cds-bg-inverse)', color: 'var(--cds-text-inverse)' }}>
      <div><span className="demo-eyebrow">A deliberate change of context</span><Text as="h2" variant="h3-serif">Private feels different.</Text></div>
      <code>--cds-bg-inverse + --cds-text-inverse</code>
    </div>
    <p className="foundation-caption">Page, card, and input surfaces adapt to the selected theme. An inverse surface stays dark and keeps its own light foreground in both themes.</p>
  </FoundationFrame>;
}
```

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.