# Description list

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/description-list
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=967-2

```tsx
import { Badge } from '@commenda/pathfinder/badge';
import { DescriptionList } from '@commenda/pathfinder/description-list';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

export const DescriptionListDefault = () => (
  <DescriptionList
    items={[
      {
        id: 'name',
        label: 'Entity name',
        value: 'Commenda Technologies Inc.',
        copyConfig: { text: 'Commenda Technologies Inc.' },
      },
      {
        id: 'country',
        label: 'Country',
        value: 'United States',
        leadingIcon: <USFlag size={16} />,
      },
      {
        id: 'status',
        label: 'Status',
        value: <Badge label="Active" tone="success" />,
      },
      { id: 'tax', label: 'Tax ID', value: null },
    ]}
  />
);
```


Import from `@commenda/pathfinder/description-list`, and load the shared stylesheet once.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly DescriptionItem[]` | required | Stable IDs, label, and ReactNode value |
| `layout` | `"inline" \| "auto" \| "stacked"` | optional | `auto`: stack below 480px of container width |
| `size` | `"default" \| "compact"` | optional | Default 36px inline minimum; compact 28px |
| `emptyLabel` | `string` | optional | `Not set`; zero and false remain visible |
| `className` | `string` | optional | Root dl styling |

Each item supports `localLabel`, `help` text, `leadingIcon`, `copyConfig: { text, onCopy?, onError? }`, and `editConfig`. Editable items use `{ kind: 'editable', onEdit }`; protected items use `{ kind: 'locked', reason, onRequestChange }`. The application opens its editor or change-request flow. Copy text is explicit, including when the displayed value is a badge or link.

## Copy and edit [#copy-and-edit]


```tsx
import { useState } from 'react';

import { DescriptionList } from '@commenda/pathfinder/description-list';

export const DescriptionListActions = () => {
  const [status, setStatus] = useState('');

  return (
    <>
      <DescriptionList
        items={[
          {
            id: 'name',
            label: 'Legal name',
            localLabel: 'Registered company name',
            value: 'Acme GmbH',
            help: 'The legal name on registration documents.',
            copyConfig: { text: 'Acme GmbH' },
            editConfig: {
              kind: 'locked',
              reason: 'A registration change requires review.',
              onRequestChange: () => {
                setStatus('Change request opened.');
              },
            },
          },
          {
            id: 'website',
            label: 'Website',
            value: <a href="https://example.com">example.com</a>,
            editConfig: {
              kind: 'editable',
              onEdit: () => {
                setStatus('Website editor opened.');
              },
            },
          },
        ]}
      />
      <output>{status}</output>
    </>
  );
};
```


Copy success appears only after the clipboard write succeeds. Failed writes announce an error. Actions appear on hover, keyboard focus, and touch without moving content. Protected fields remain readable and request a change rather than opening an inline editor.

## Compact panels [#compact-panels]


```tsx
import { DescriptionList } from '@commenda/pathfinder/description-list';

export const DescriptionListCompact = () => (
  <DescriptionList
    size="compact"
    layout="stacked"
    items={[
      { id: 'staff', label: 'Employees', value: 0 },
      { id: 'registration', label: 'Registration verified', value: false },
    ]}
  />
);
```


Use a Card with `padding="none"` for section framing. DescriptionList supplies its own 8px inset. Section titles and section-level Edit actions belong to Card. Read the [record component rules](/docs/components/description-list#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule            | Contract and provenance                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DESCRIPTION-001 | Figma 967:9 / 969:377: 8px list inset, 2px row gaps, 200px inline label column; stack below 480px container width. Default/compact row heights are minimums, allowing wrapping. |
| DESCRIPTION-002 | Native dl/dt/dd; zero/false are values. Actions reserve space and appear on focus/touch as well as hover.                                                                       |
| DESCRIPTION-003 | Copy explicit text, announce real success/failure. Locked edit requests a change; apps own editor surfaces.                                                                     |

### Recorded design decisions [#recorded-design-decisions]

Description row source/provenance, sensitive-value reveal, and edit-history explorations are not combined into the initial approved row interface. Consumers can compose record value content; future named behavior needs a chosen design contract.