@arbor-education/design-system.components 4.9.2 → 5.0.0

package/src/components/formField/inputs/time/TimeInput.stories.tsx

@@ -20,10 +20,11 @@ const DESCRIPTION_INTRO = [
   'TimeInput is a flexible time-entry field that operates in **two distinct modes** depending on',
   'whether the `options` prop is supplied.',
   '',
-  '**Native mode** (no `options`) renders a browser-native `<input type="time">` decorated with a',
-  'clock icon. The browser handles the picker UI, spin-button keyboard navigation, and locale-aware',
-  'display. This mode supports `min`, `max`, `granularity`, `className`, a forwarded `ref`, and the',
-  'native `onChange` event.',
+  '**Native mode** (no `options`) renders a plain text field decorated with a clock icon. Typed input is',
+  'limited to digits and colons, so no browser time picker appears and every browser shows the same',
+  'single control. Like the other input components, it does not validate the value: range checks and',
+  'error messages belong to the consuming code, which presents them through `hasError` and `aria-invalid`.',
+  'This mode supports `granularity`, `className`, a forwarded `ref`, and `onChange`.',
   '',
   '**Combobox mode** (`options` provided) replaces the native input with a searchable Combobox.',
   'The user can type to filter or click to select from a predefined list of time values. This mode',
@@ -37,8 +38,8 @@ const DESCRIPTION_INTRO = [
 const USAGE_GUIDANCE = [
   '### When to use',
   '',
-  '- **Any valid time** — use native mode (the default). The browser enforces valid time entry and',
-  '  supports `min`/`max` bounds for school hours (e.g. `min="08:00" max="17:00"`).',
+  '- **Free-text time entry** — use native mode (the default). Validate and normalise the typed text in',
+  '  your own code, and present errors with `hasError` and `aria-invalid`.',
   '- **Fixed set of allowed times** — use combobox mode with `options`. Ideal for lesson periods,',
   '  appointment slots, or any scenario where only specific times are valid.',
   '- **Inside a form** — always wrap in `<FormField inputType="time">` so label, error text, and',
@@ -52,7 +53,7 @@ const USAGE_GUIDANCE = [
   '|---|---|',
   '| Date + time combined | Separate `DateInput` and `TimeInput` fields |',
   '| Free-form duration entry | `TextInput` with format hint |',
-  '| More than ~50 time options | Native mode with `min`/`max` bounds |',
+  '| More than ~50 time options | Native mode, validating the range in your own code |',
   '| Status or category selection | `SelectDropdown` with meaningful labels |',
 ].join('\n');
 
@@ -64,44 +65,46 @@ const DEVELOPER_NOTES = [
   '',
   '| Prop | Native mode | Combobox mode |',
   '|---|---|---|',
-  '| `granularity` | Sets `step={1}` for second-level precision | **Ignored** |',
-  '| `min` / `max` | Restricts picker range | **Ignored** — filter `options` array instead |',
+  '| `granularity` | Sets the placeholder to `HH:mm` or `HH:mm:ss` | **Ignored** |',
+  '| `min` / `max` / `step` | Passed to the `<input>` but a text field ignores them. Enforce ranges in your own code | **Ignored** — filter `options` array instead |',
   '| `className` | Applied to the wrapper `<div>` | **Ignored** |',
-  '| `ref` (forwarded) | Attached to the `<input>` element | **Ignored** |',
+  '| `ref` (forwarded) | Attached to the visible text `<input>` | **Ignored** |',
   '| `onChange` | Native `ChangeEvent<HTMLInputElement>` | **Ignored** — use `onValueChange` |',
   '| `searchType` | **Ignored** | Controls `prefix`/`substring` matching |',
   '| `highlightStringMatches` | **Ignored** | Bolds matched characters in dropdown |',
   '| `onValueChange` | Fires with the string value | Fires with the string value |',
   '',
-  '**`aria-invalid` is NOT automatic.** When using TimeInput standalone (outside FormField),',
-  '`hasError` only applies visual error styling. It does NOT set `aria-invalid`:',
+  '### Validation (native mode)',
+  '',
+  'TimeInput only filters characters: keystrokes and pasted text are limited to digits and colons, so',
+  '`abc` and `9.05` never reach the field. It does not parse, normalise or validate the result, so `25:00`',
+  'is emitted as typed. The component never sets `aria-invalid`, so range validation is the consumer\'s job:',
   '',
   '```tsx',
-  '// Standalone — set aria-invalid yourself:',
-  '<TimeInput hasError aria-invalid={true} aria-label="Start time" />',
+  '// Standalone — validate in your code and present the result:',
+  '<TimeInput hasError={!isValid} aria-invalid={!isValid} aria-label="Start time" value={text} onValueChange={setText} />',
   '',
-  '// Inside FormField — aria-invalid is set automatically when errorText is present:',
-  '<FormField label="Start time" id="start" inputType="time" errorText="Required." inputProps={{}} />',
+  '// Inside FormField — pass errorText and FormField sets hasError and aria-invalid:',
+  '<FormField label="Start time" id="start" inputType="time" errorText="Enter a valid time." inputProps={{}} />',
   '```',
   '',
-  '**`onValueChange` is the preferred callback** — it works in both modes and receives the plain',
-  'string value (`HH:MM` or `HH:MM:SS`). The native `onChange` event is only available in native',
-  'mode and is not forwarded in combobox mode.',
+  '**`onValueChange` is the preferred callback** — it works in both modes and receives the string value.',
+  '`onChange` is only available in native mode and is not forwarded in combobox mode.',
   '',
-  '**`TimeValue` is format-shaped, not strictly validated.** The TypeScript type',
-  '`` `${string}:${string}` `` accepts `"99:99"` without complaint. The browser rejects it at render',
-  'time for `<input type="time">`, but the component itself does no validation.',
+  '**`TimeValue` is format-shaped.** The TypeScript type `` `${string}:${string}` `` accepts any string',
+  'containing a colon, so it does not guarantee a valid time.',
   '',
   '---',
   '',
   '### Accessibility',
   '',
   '- Always provide a visible label via `<FormField>` or `aria-label` / `aria-labelledby`.',
-  '- In native mode, the browser\'s built-in time picker is fully keyboard-navigable (arrow keys',
-  '  cycle through the hour/minute/second segments; AM/PM toggles with A/P).',
+  '- In native mode the field is a text input, so screen readers announce the text exactly as typed.',
+  '  Errors are announced only when the consumer sets `aria-invalid`. The clock button is a labelled',
+  '  button ("Select time") that moves focus to the field and selects the hours.',
   '- In combobox mode, the Combobox component implements the ARIA combobox pattern',
   '  (`role="combobox"`, `aria-expanded`, `aria-activedescendant`).',
-  '- The clock icon is decorative and carries `aria-hidden="true"`.',
+  '- The clock icon is decorative; the clock button is labelled "Select time".',
   '- Pair `hasError` with `aria-invalid={true}` when used standalone — one is visual, the other',
   '  is for screen readers. `<FormField>` handles this automatically when `errorText` is set.',
   '',
@@ -171,7 +174,7 @@ const meta = {
   argTypes: {
     'value': {
       description: [
-        'Controlled value in `HH:MM` or `HH:MM:SS` format.',
+        'Controlled text value, limited to digits and colons. Pass `HH:MM` or `HH:MM:SS` for a time.',
         'Pair with `onValueChange` to keep state in sync.',
         'If `undefined`, the component manages its own state (uncontrolled).',
       ].join(' '),
@@ -194,7 +197,8 @@ const meta = {
     },
     'onValueChange': {
       description: [
-        'Callback fired with the plain string value on every change.',
+        'Callback fired with the plain string value whenever the committed value changes.',
+        'In native mode it is the digits and colons entered, with no parsing or range validation.',
         'Works in **both** native and combobox modes.',
         'Prefer this over the native `onChange` event for cross-mode compatibility.',
       ].join(' '),
@@ -207,8 +211,8 @@ const meta = {
     'options': {
       description: [
         'Array of `TimeValue` strings to display as selectable options.',
-        'Providing this prop switches to **combobox mode** — the native `<input type="time">` is',
-        'replaced by a searchable Combobox. Omit to use the browser-native time picker.',
+        'Providing this prop switches to **combobox mode** — the text field is',
+        'replaced by a searchable Combobox. Omit to type a time into the text field.',
       ].join(' '),
       control: 'object',
       table: {
@@ -219,7 +223,7 @@ const meta = {
     'granularity': {
       description: [
         '**Native mode only.** Controls the precision of the time input.',
-        '`"second"` sets `step={1}` so the seconds segment is visible.',
+        '`"second"` sets the placeholder to `HH:mm:ss`.',
         'Silently ignored when `options` is provided.',
       ].join(' '),
       control: { type: 'select' },
@@ -257,7 +261,7 @@ const meta = {
     'hasError': {
       description: [
         'Applies error-state visual styling (red border).',
-        'Does **not** set `aria-invalid` automatically when used standalone outside FormField.',
+        'Does **not** set `aria-invalid` for errors you supply when used standalone outside FormField.',
         'Always pair with `aria-invalid={true}` for screen-reader coverage.',
       ].join(' '),
       control: 'boolean',
@@ -292,7 +296,7 @@ const meta = {
       },
     },
     'placeholder': {
-      description: 'Placeholder text shown when no value is selected. Most useful in combobox mode.',
+      description: 'Placeholder text shown while the field is empty, e.g. `HH:mm`. It disappears once a value is entered.',
       control: 'text',
       table: {
         type: { summary: 'string' },
@@ -311,8 +315,7 @@ const meta = {
     'aria-invalid': {
       description: [
         'Marks the input as invalid for screen readers.',
-        'Must be set manually when used standalone — FormField sets this automatically',
-        'when `errorText` is provided.',
+        'Never set by TimeInput. Set it when validating the text yourself, or let FormField set it when `errorText` is provided.',
       ].join(' '),
       control: 'boolean',
       table: {
@@ -409,26 +412,6 @@ const GranularitySecondTemplate = () => {
   );
 };
 
-const WithMinMaxBoundsTemplate = () => {
-  const [value, setValue] = useState<TimeValue | ''>('');
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
-      <TimeInput
-        min="08:00"
-        max="17:00"
-        value={value}
-        onValueChange={v => setValue(v as TimeValue | '')}
-        id="bounded-time"
-        name="school-time"
-        aria-label="School hours time"
-      />
-      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
-        Restricted to school hours: 08:00 – 17:00
-      </p>
-    </div>
-  );
-};
-
 const WithOptionsTemplate = () => {
   const [value, setValue] = useState<TimeValue | ''>('');
   return (
@@ -697,39 +680,7 @@ export default PreciseTimeInputExample;
     },
     render: () => <GranularitySecondTemplate />,
   },
-  'Setting `granularity="second"` adds a seconds segment to the native time input (`step={1}`). Use this for stopwatch-style timing or precise event logging. **Native mode only** — silently ignored when `options` is provided.',
-);
-
-export const WithMinMaxBounds: Story = withDescription(
-  {
-    parameters: {
-      controls: { disable: true },
-      docs: {
-        source: {
-          language: 'tsx',
-          code: `
-import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
-
-function BoundedTimeInputExample() {
-  return (
-    <TimeInput
-      min="08:00"
-      max="17:00"
-      id="school-time"
-      name="school-time"
-      aria-label="School hours time"
-    />
-  );
-}
-
-export default BoundedTimeInputExample;
-          `.trim(),
-        },
-      },
-    },
-    render: () => <WithMinMaxBoundsTemplate />,
-  },
-  'The `min` and `max` props restrict the selectable range in the native browser picker to school hours. **Native mode only** — in combobox mode, restrict available times by filtering the `options` array instead.',
+  'Setting `granularity="second"` sets the placeholder to `HH:mm:ss`. Seconds are typed by the user, and only digits and colons are accepted. **Native mode only** — silently ignored when `options` is provided.',
 );
 
 export const WithError: Story = withDescription(

package/src/components/formField/inputs/time/TimeInput.test.tsx

@@ -19,17 +19,22 @@ describe('TimeInput', () => {
     vi.restoreAllMocks();
   });
 
-  test('renders a native time input by default', () => {
+  test('renders a text input so no browser picker is drawn', () => {
     render(<TimeInput aria-label="Start time" />);
-    const input = screen.getByLabelText('Start time');
 
-    expect(input).toHaveAttribute('type', 'time');
-    expect(input).toHaveAttribute('step', '60');
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('type', 'text');
+  });
+
+  test('shows HH:mm as the placeholder by default', () => {
+    render(<TimeInput aria-label="Start time" />);
+
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('placeholder', 'HH:mm');
   });
 
-  test('uses one-second stepping when granularity is second', () => {
+  test('shows HH:mm:ss as the placeholder when granularity is second', () => {
     render(<TimeInput aria-label="Start time" granularity="second" />);
-    expect(screen.getByLabelText('Start time')).toHaveAttribute('step', '1');
+
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('placeholder', 'HH:mm:ss');
   });
 
   test('native mode emits the string value when changed', () => {
@@ -43,6 +48,70 @@ describe('TimeInput', () => {
     expect(onValueChange).toHaveBeenCalledWith('14:30');
   });
 
+  test('blocks keystrokes other than digits and colons', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimeInput aria-label="Start time" onValueChange={onValueChange} />);
+
+    await user.type(screen.getByLabelText('Start time'), '9.7x:a');
+
+    expect(onValueChange).toHaveBeenLastCalledWith('97:');
+    expect(screen.getByLabelText('Start time')).toHaveValue('97:');
+  });
+
+  test('strips non-time characters from pasted text', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimeInput aria-label="Start time" onValueChange={onValueChange} />);
+    const input = screen.getByLabelText('Start time');
+
+    await user.click(input);
+    await user.paste('abc14:30');
+
+    expect(onValueChange).toHaveBeenLastCalledWith('14:30');
+    expect(input).toHaveValue('14:30');
+  });
+
+  test('a typed colon is accepted', async () => {
+    const user = userEvent.setup();
+    render(<TimeInput aria-label="Start time" />);
+
+    await user.type(screen.getByLabelText('Start time'), '14:30');
+
+    expect(screen.getByLabelText('Start time')).toHaveValue('14:30');
+  });
+
+  test('does not set aria-invalid itself, so validation stays with the consumer', async () => {
+    const user = userEvent.setup();
+    render(<TimeInput aria-label="Start time" />);
+    const input = screen.getByLabelText('Start time');
+
+    await user.type(input, 'abc');
+
+    expect(input).not.toHaveAttribute('aria-invalid');
+  });
+
+  test('applies error styling from hasError and reflects aria-invalid passed by the consumer', () => {
+    render(<TimeInput aria-label="Start time" hasError aria-invalid />);
+    const input = screen.getByLabelText('Start time');
+
+    expect(input).toHaveClass('ds-input--error');
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  test('submits the typed text under the field name', async () => {
+    const user = userEvent.setup();
+    render(
+      <form aria-label="Schedule">
+        <TimeInput aria-label="Start time" name="start" />
+      </form>,
+    );
+
+    await user.type(screen.getByLabelText('Start time'), '9:05');
+
+    expect(new FormData(screen.getByRole<HTMLFormElement>('form')).get('start')).toBe('9:05');
+  });
+
   test('clicking the clock icon focuses the input and selects the hour segment when supported', async () => {
     const user = userEvent.setup();
     const setSelectionRange = vi.spyOn(HTMLInputElement.prototype, 'setSelectionRange').mockImplementation(() => {});

package/src/components/formField/inputs/time/TimeInput.tsx

@@ -2,7 +2,7 @@ import classNames from 'classnames';
 import { Combobox } from 'Components/combobox/Combobox';
 import type { ComboboxOption, ComboboxSearchType } from 'Components/combobox/types';
 import { Icon } from 'Components/icon/Icon';
-import { forwardRef, useCallback, useMemo, useRef, useState, type ChangeEvent, type InputHTMLAttributes } from 'react';
+import { forwardRef, useCallback, useMemo, useRef, useState, type ChangeEvent, type InputHTMLAttributes, type KeyboardEvent } from 'react';
 
 /** Expected string `HH:MM` or `HH:MM:SS`; format-shaped versus strict time validation. */
 export type TimeValue = `${string}:${string}` | `${string}:${string}:${string}`;
@@ -22,6 +22,14 @@ export type TimeInputProps = {
 
 const clockIcon = <Icon name="clock-3" size={16} />;
 
+const TIME_CHARACTER_PATTERN = /^[0-9:]$/;
+const NON_TIME_CHARACTERS_PATTERN = /[^0-9:]/g;
+
+const NATIVE_PLACEHOLDER_BY_GRANULARITY: Record<TimeGranularity, string> = {
+  minute: 'HH:mm',
+  second: 'HH:mm:ss',
+};
+
 /** The forwarded ref is attached in native mode but when `options` is provided, no input ref is exposed. */
 export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, ref) => {
   const {
@@ -32,6 +40,7 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     searchType = 'prefix',
     highlightStringMatches = false,
     onChange,
+    onKeyDown,
     className,
     disabled = false,
     id,
@@ -76,8 +85,22 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     } as ChangeEvent<HTMLInputElement>);
   }, [isControlled, onChange, onValueChange]);
 
+  const handleNativeKeyDown = useCallback((event: KeyboardEvent<HTMLInputElement>) => {
+    const isShortcut = event.ctrlKey || event.metaKey || event.altKey;
+    const isPrintable = event.key.length === 1;
+    if (isPrintable && !isShortcut && !TIME_CHARACTER_PATTERN.test(event.key)) {
+      event.preventDefault();
+    }
+    onKeyDown?.(event);
+  }, [onKeyDown]);
+
   const handleNativeChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
-    updateValue(event.currentTarget.value, event);
+    const { value } = event.currentTarget;
+    const timeCharacters = value.replace(NON_TIME_CHARACTERS_PATTERN, '');
+    if (timeCharacters !== value) {
+      event.currentTarget.value = timeCharacters;
+    }
+    updateValue(timeCharacters, event);
   }, [updateValue]);
 
   const focusAndSelectHours = useCallback(() => {
@@ -87,11 +110,7 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     }
 
     input.focus();
-
-    try {
-      input.setSelectionRange(0, 2);
-    }
-    catch { /* Some browsers do not expose selection APIs on time inputs. */ }
+    input.setSelectionRange(0, 2);
   }, []);
 
   const timeOptions = useMemo<ComboboxOption[]>(
@@ -139,18 +158,18 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
         ref={setRefs}
         id={id}
         name={name}
-        type="time"
+        type="text"
         value={currentValue}
-        step={granularity === 'second' ? 1 : 60}
         disabled={disabled}
         aria-describedby={ariaDescribedBy}
         aria-invalid={ariaInvalid}
         aria-label={ariaLabel}
-        placeholder={placeholder}
+        placeholder={placeholder ?? NATIVE_PLACEHOLDER_BY_GRANULARITY[granularity]}
         className={classNames('ds-input', 'ds-input--M', 'ds-time-input__input', {
           'ds-input--error': hasError,
         })}
         onChange={handleNativeChange}
+        onKeyDown={handleNativeKeyDown}
       />
       <button
         type="button"

package/src/components/formField/inputs/time/timeInput.scss

@@ -4,13 +4,7 @@
 }
 
 .ds-time-input__input {
-  appearance: none;
   padding-right: calc(var(--form-field-text-medium-height) + var(--spacing-small));
-
-  &::-webkit-calendar-picker-indicator {
-    display: none;
-    appearance: none;
-  }
 }
 
 .ds-time-input__icon-button {

package/src/components/kvpList/KVPList.stories.tsx

@@ -33,6 +33,7 @@ const TERM_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
   '| `children` | `ReactNode` | — | The key/label text |',
+  '| `prominence` | `\'neutral\' \\| \'strong\'` | `\'neutral\'` | `neutral` = body text; `strong` = bold body weight, e.g. a totals row label |',
   '| `className` | `string` | — | Additional CSS classes on the `<dt>` element |',
   '| `...HTMLAttributes<dt>` | | | All standard element attributes forwarded |',
 ].join('\n');
@@ -372,6 +373,59 @@ export default StrongProminenceExample;
   '`prominence="strong"` applies h2-scale typography to the definition — rendered as `<dd>` semantically but visually dominant. Use for the primary metric value in a list; `"neutral"` for supporting context.',
 );
 
+export const TotalsRow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KVPList } from '@arbor-education/design-system.components';
+
+function TotalsRowExample() {
+  return (
+    <KVPList aria-label="Basket totals">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Subtotal</KVPList.Term>
+        <KVPList.Definition>£40.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Delivery</KVPList.Term>
+        <KVPList.Definition>£2.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term prominence="strong">Total</KVPList.Term>
+        <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  );
+}
+export default TotalsRowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <KVPList aria-label="Basket totals">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>
+    ),
+  },
+  '`prominence="strong"` on `KVPList.Term` applies the bold body weight token (`--type-body-bold-weight`) so the label of a totals row balances a strong definition. Unemphasised terms are unchanged.',
+);
+
 export const IsRow: Story = withDescription(
   {
     parameters: {

package/src/components/kvpList/KVPList.test.tsx

@@ -51,6 +51,58 @@ describe('KVPList', () => {
     expect(container.querySelector('.ds-kvp-list__description--row')).toBeInTheDocument();
   });
 
+  test('applies the strong modifier to a term with strong prominence', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).toHaveClass('ds-kvp-list__term', 'ds-kvp-list__term--strong');
+  });
+
+  test('does not forward prominence to the term element', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).not.toHaveAttribute('prominence');
+  });
+
+  test('leaves a term without prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term className="custom-term">Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Subtotal')).toHaveAttribute('class', 'ds-kvp-list__term custom-term');
+  });
+
+  test('leaves a term with neutral prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="neutral">Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Delivery')).toHaveAttribute('class', 'ds-kvp-list__term');
+  });
+
   test('does not add group semantics when no accessible label is provided', () => {
     render(
       <KVPList>

package/src/components/kvpList/KVPList.tsx

@@ -11,6 +11,7 @@ export type KVPListRowProps = React.HTMLAttributes<HTMLDListElement> & {
 
 export type KVPListTermProps = React.HTMLAttributes<HTMLElement> & {
   children?: React.ReactNode;
+  prominence?: 'neutral' | 'strong';
 };
 
 export type KVPListDefinitionProps = React.HTMLAttributes<HTMLElement> & {
@@ -60,9 +61,17 @@ const KVPListRow = ({
 const KVPListTerm = ({
   children,
   className,
+  prominence = 'neutral',
   ...rest
 }: KVPListTermProps): React.JSX.Element => (
-  <dt className={classNames('ds-kvp-list__term', className)} {...rest}>
+  <dt
+    className={classNames(
+      'ds-kvp-list__term',
+      { 'ds-kvp-list__term--strong': prominence === 'strong' },
+      className,
+    )}
+    {...rest}
+  >
     {children}
   </dt>
 );

package/src/components/kvpList/kvpList.scss

@@ -21,6 +21,10 @@
   line-height: var(--type-body-line-height);
 }
 
+.ds-kvp-list__term--strong {
+  font-weight: var(--type-body-bold-weight);
+}
+
 .ds-kvp-list__description--strong {
   color: var(--kvp-list-color-text-strong);
   font-family: var(--type-headings-h2-family);