Get startedFoundationsComponentsPatternsGuidelinesResourcesAI
This site is a work in progress as part of GovTech {build} hackathon. Content may be incomplete or subject to change.

Description list

Description lists pair terms with values in a structured, readable layout.

GitHubGitHub logocomponents/description-list
StorybookStorybook logocomponents/description-list
DesignUsageAccessibilityUpdates

Purpose

Pair labels with values

Description lists present key-value information clearly — names paired with values, terms paired with definitions, attributes paired with data.

Review before submission

Use description lists on confirmation or summary pages to show users exactly what they've entered before they commit.

Detail without clutter

The structured layout keeps dense information readable — labels and values are visually distinct without needing a full table.

Anatomy

Label Value
1

Container

2

Label

3

Value

Configuration

Default

Description lists pair terms with their corresponding values in a structured layout.

Status Active Updated 31 Mar 2026

Renders key-value pairs in a structured, readable layout. Use on confirmation or summary screens to show users what they have entered before they submit.

Playground

BETA
Status Active Updated 31 Mar 2026

Structure

Status Active Updated 31 Mar 2026

Component tokens

Component tokens are specific to each component. Use the table title as the prefix: padding-lg under sgds/description-list means sgds/description-list/padding-lg.

sgds/description-list
CategoryComponent tokenSemantic tokenValuePaddingpadding-lgsgds/padding/lg20pxpadding-xlsgds/padding/xl24pxGapgap-2-xlsgds/gap/2-xl—gap-2-xssgds/gap/2-xs4pxgap-xssgds/gap/xs8pxBorderborder-color-mutedsgds/border-color-muted#DFDFDFborder-radius-mdsgds/border-radius/md8pxborder-width-1sgds/border-width/11pxTypographyfont-size-16sgds/font-size/1616pxfont-size-24sgds/font-size/24—font-weight-regularsgds/font-weight/regular—font-weight-semiboldsgds/font-weight/semibold—line-height-24sgds/line-height/2424pxline-height-32sgds/line-height/32—Colourcolor-defaultsgds/color-default#1A1A1Acolor-subtlesgds/color-subtle#525252Sizedimension-280sgds/dimension/280—

Usage

When to use

  • Use description list when it gives users a clearer, more consistent SGDS interaction for the task at hand.
  • Use the built-in SGDS pattern when it helps users recognise the component quickly and act with confidence.

When not to use

  • Do not use this component when a simpler SGDS pattern would communicate the same thing more clearly.
  • Do not add repeated or decorative instances that compete with the main content.

Best practices

Status Active Updated 31 Mar 2026
Keep the pattern clear

Use one clear, purposeful instance so users can understand the component quickly.

Status Active Updated 31 Mar 2026 Status Active Updated 31 Mar 2026
Do not add noise

Repeated or decorative instances make the interface harder to scan.

Accessibility considerations

Built-in accessibility

  • Description lists present terms and supporting details as paired content.
  • The component does not add custom keyboard behaviour.

Labels and content

  • Use short terms and clear descriptions.
  • Keep each term and description pair complete when read on its own.

Focus and interaction

  • Do not place unrelated interactive controls inside description list values.
  • If a value includes a link, the link should be reachable in normal tab order.

Keyboard interaction

This component does not have a separate keyboard interaction table because:

  • Description lists are structural content for term and detail pairs.
  • Keyboard interaction only applies to links, buttons, or controls placed inside a value.

Updates

DateVersionDescriptionLoading updates…

Roadmap

Planned itemStatusTargetFuture enhancements for description listPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #design-system-feedback

Bug Reports

Found a bug or issue?

Report it on GitHub Issues → sgds/components/description-list

Singapore Government Design System

The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.