Definition List

Semantic Definition List

Uses dl/dt/dd elements for accessible term-definition pairs with optional icons

Full Name: Mohammed Al-Harbi
Organization: Digital Services Department
Position: Senior Developer
Location: Riyadh


<dl class="nds-definition-list">
  <div class="nds-definition-item">
    <dt>
      <i class="hgi hgi-stroke hgi-user-account"></i>
      <span class="nds-label">Full Name</span>
    </dt>
    <dd>Mohammed Al-Harbi</dd>
  </div>
  <div class="nds-definition-item">
    <dt>
      <i class="hgi hgi-stroke hgi-building-02"></i>
      <span class="nds-label">Organization</span>
    </dt>
    <dd>Digital Services Department</dd>
  </div>
  <div class="nds-definition-item">
    <dt>
      <i class="hgi hgi-stroke hgi-briefcase-02"></i>
      <span class="nds-label">Position</span>
    </dt>
    <dd>Senior Developer</dd>
  </div>
  <div class="nds-definition-item">
    <dt>
      <i class="nds-icon nds-hgi-location-01" aria-hidden="true"></i>
      <span class="nds-label">Location</span>
    </dt>
    <dd>Riyadh</dd>
  </div>
</dl>

Feature List

Uses class-based markup for icon grids, feature highlights, and content that doesn't need term-definition semantics

Accessibility

WCAG 2.1 compliant with full keyboard navigation and screen reader support.

Security

Built-in XSS protection and content security policy headers.

Performance

Lazy loading and staggered initialization for fast page loads.

Theming

CSS custom properties for full visual customization without overrides.


<div class="nds-definition-list nds-divided nds-grid" style="--max-col:2;--mid-col:1;--min-col:1; --dl-icon-size:24px; --row-gap:24px; --col-gap:32px;">
  <div class="nds-definition-item">
    <span class="nds-item-title">
      <i class="nds-icon nds-hgi-checkmark-circle-02" aria-hidden="true"></i>
      <span class="nds-label">Accessibility</span>
    </span>
    <p class="nds-item-desc">WCAG 2.1 compliant with full keyboard navigation and screen reader support.</p>
  </div>
  <div class="nds-definition-item">
    <span class="nds-item-title">
      <i class="hgi hgi-stroke hgi-shield-01"></i>
      <span class="nds-label">Security</span>
    </span>
    <p class="nds-item-desc">Built-in XSS protection and content security policy headers.</p>
  </div>
  <div class="nds-definition-item">
    <span class="nds-item-title">
      <i class="nds-icon nds-hgi-clock-01" aria-hidden="true"></i>
      <span class="nds-label">Performance</span>
    </span>
    <p class="nds-item-desc">Lazy loading and staggered initialization for fast page loads.</p>
  </div>
  <div class="nds-definition-item">
    <span class="nds-item-title">
      <i class="hgi hgi-stroke hgi-star"></i>
      <span class="nds-label">Theming</span>
    </span>
    <p class="nds-item-desc">CSS custom properties for full visual customization without overrides.</p>
  </div>
</div>

Built-in Features

Table View Layout

Two-column grid with CSS subgrid for perfect alignment across all term-definition pairs.

Responsive Table View

Breakpoint variants let you choose when the table view activates: mobile only, tablet and up, or desktop and up.

Divided Borders

Optional border separators between items. Works in both default and table view layouts, including responsive variants.

Grid Layout

Multi-column responsive grid with configurable breakpoints via --max-col, --mid-col, and --min-col properties.

CSS Custom Properties

Control icon size, gap, title font size, and row spacing through custom properties without overriding styles.

Automatic Icon Indent

Descriptions auto-indent to align with the label text when icons are present in stacked layout.

Item Action

Wrap a description and its trailing action buttons in .nds-item-action to place them in a flex row. Any number of buttons share a single gap and stay aligned with the value.

Profile URL: https://example.gov.sa/profile
Email: user@example.gov.sa


<dl class="nds-definition-list nds-divided">
  <div class="nds-definition-item">
    <dt>
      <i class="hgi hgi-stroke hgi-link-01"></i>
      <span class="nds-label">Profile URL</span>
    </dt>
    <dd>
      <div class="nds-item-action">
        <span>https://example.gov.sa/profile</span>
        <button class="nds-btn nds-subtle nds-sm" aria-label="Copy URL">
          <i class="hgi hgi-stroke hgi-copy-01"></i>
        </button>
        <button class="nds-btn nds-subtle nds-sm" aria-label="Share URL">
          <i class="hgi hgi-stroke hgi-share-01"></i>
        </button>
      </div>
    </dd>
  </div>
  <div class="nds-definition-item">
    <dt>
      <i class="hgi hgi-stroke hgi-edit-01"></i>
      <span class="nds-label">Email</span>
    </dt>
    <dd>
      <div class="nds-item-action">
        <span>user@example.gov.sa</span>
        <button class="nds-btn nds-subtle nds-sm" aria-label="Edit email">
          <i class="hgi hgi-stroke hgi-edit-01"></i>
        </button>
      </div>
    </dd>
  </div>
</dl>

Usage Guidelines

Best Practices

Use semantic markup (<dl>/<dt>/<dd>) for data display like user profiles, service details, or specifications where screen reader semantics matter
Use generic markup (.nds-item-title / .nds-item-desc) for feature lists, highlights, or content grids where semantic term-definition relationships don't apply
Use default layout for vertical stacking when descriptions vary in length or include multiple lines
Use table view (nds-tableView) for compact side-by-side key-value display. Subgrid keeps all columns aligned
Use responsive table view variants to control when the two-column layout activates: nds-tableView-md for tablet and up (stacked on mobile), nds-tableView-lg for desktop and up, or nds-tableView-sm for mobile only
Use row view (nds-rowView) for compact inline label/value pairs where each item flows on its own wrappable row. No shared columns across items, so short pairs stay tight and long values wrap naturally beside the label. Good for card meta
Use size modifiers (nds-md, nds-sm) to scale icon size, title font size, and row gap in step. Default (no class) is large. Individual CSS custom properties (--dl-icon-size, --dl-title-FS, --row-gap) still override size defaults when you need finer control
Use grid layout (nds-grid) for multi-column responsive grids. Configure breakpoints with --max-col, --mid-col, --min-col
Do not use definition list for navigation or action items. Use a Dropmenu or standard list instead
Combine styles independently with any layout: nds-divided for border separators, nds-card nds-stroke on items for card appearance
The nds-divided style adapts automatically to responsive table view variants, showing stacked dividers outside the active breakpoint and table view dividers inside it
Add icons to titles for visual identification. The component auto-indents descriptions to align with the label text in stacked layout

Modifier Classes

Class	Description
`nds-tableView`	Two-column key-value grid layout at all screen sizes
`nds-tableView-sm`	Table view on mobile only (max-width: 600px), stacked on larger screens
`nds-tableView-md`	Table view from tablet and up (min-width: 601px), stacked on mobile
`nds-tableView-lg`	Table view from desktop and up (min-width: 961px), stacked below
`nds-rowView`	Each item places dt and dd on a single wrappable row. Looser than table view: no shared columns across items
`nds-divided`	Adds border separators between items. Adapts styling for table view and stacked layouts
`nds-md`	Medium size: 18px icon (floored, no visual change from lg), medium title font, medium row gap
`nds-sm`	Small size: 18px icon (floored, no visual change from lg/md), small title font, small row gap
`nds-last-row`	On a `.nds-definition-item`, strips the bottom border in divided layout when the item is not the last child (for example when a wrapping `.nds-card` breaks CSS `:last-child`)
`nds-loading`	On `.nds-definition-list`: animates skeleton bars over terms and descriptions, hides icons. Equivalent to `data-state="loading"`
`nds-item-action`	On a wrapper inside `.nds-definition-item`: flex row that places a description value alongside one or more trailing action buttons (copy, edit, share) with a shared gap

CSS Custom Properties

Property	Default	Description
`--dl-icon-size`	20px (lg) / 18px (md) / 18px (sm)	Width and height of title icons. Floored at 18px; icons never render smaller, even when this value or a size modifier requests less
`--dl-icon-gap`	half of icon size	Gap between the icon and label text
`--dl-title-FS`	--typo-text-lg-FS (lg) / --typo-text-clamp-md-FS (md) / --typo-text-clamp-sm-FS (sm)	Font size of term/title text
`--dl-desc-FS`	--typo-text-md-FS (lg) / --typo-text-md-FS inherited (md) / --typo-text-sm-FS (sm)	Font size of description/value text. The large and medium sizes default to `--typo-text-md-FS`; small explicitly sets `--typo-text-sm-FS`
`--row-gap`	--spacing-lg	Vertical spacing between items
`--col-gap`	--spacing-xl (table view) / --spacing-sm (row view)	Horizontal spacing between dt and dd in table view and row view

Definition List - National Design System

Semantic Definition List

Feature List

Built-in Features

Item Action

Usage Guidelines

Best Practices

Modifier Classes

CSS Custom Properties