PDS proposals
← All proposals

Section Message

A copy of the PDS v2 Section Message (pds-section-message, same class names, props and behavior) with an agentic type (AI gradient border on a surface fill, the Agent Avatar as its leading icon (decided 2026-10-21; iconName picks its icon), the standard secondary Button as the CTA, a silver-muted Badge) and an avatarProps option for the avatar (halo, shape, size).

Extends a PDS componentOpen in Storybook

proposals/SectionMessage/HANDOFF.md75 lines · View on GitHub

Handoff: SectionMessage

What and why

A copy of the PDS v2 Section Message (v2.0.0-beta.12) with one addition, for an agent's notice in an interface: type='agentic', the AI gradient as a 1px border on a surface fill, the Agent Avatar as its leading icon (iconName picks the avatar's icon, zappy or sparklesSolid; avatarProps sets its halo, shape or size), the standard secondary Button as the CTA and a silver-muted Badge. Everything else is the v2 Section Message, unchanged. Figma: Section Message page (6 stories, light only; captures of Storybook, with the library's zappy and clock icons swapped in). Context: context.md.

Decided (2026-10-21): the agentic message uses the Agent Avatar in place of the icon. It is the standard, not an option under review: every story shows it.

Exploration and decisions

  • agentic is a new value of type, not an isAgentic boolean: type already controls this component's color, icon and announced label, and agentic replaces all three, like discovery.
  • Surface fill with a gradient border keeps it distinct from the purple discovery message and keeps text contrast in light and dark. The border uses the same pattern as the agentic Button and Panel (transparent border, gradient on the border-box, surface layer over the padding-box). Static.
  • The agentic CTA keeps the Button's gradient border (an override inside .pds-section-message--agentic).
  • The role stays status; text and icon stay in the default foreground.
  • The Agent Avatar is the agentic message's leading icon (decided 2026-10-21, after comparing it with the plain icon). Its screen-reader label is the type's label (typeLabels.agentic, translatable); its size is m with a title and s without. avatarProps (partial Agent Avatar props) overrides any of that.
  • Colors were already semantic; the root takes pds-copy-s instead of declaring font primitives (the title keeps its size and weight, no class matches a semibold m).

Full list and reasons: decisions.md.

API

The v2 SectionMessage props, unchanged, plus these. (See the PDS Section Message for the rest: badgeIcon, badgeLabel, ctaButton, ctaIcon, dismissLabel, id, isDismissible, message, onDismiss, secondaryCta, title, typeLabels.)

Prop Type Default Purpose
avatarProps Partial<AgentAvatarProps> none Options for the Agent Avatar of the agentic type (hasHalo, shape, size, label). Passing it on another type shows the avatar there.
iconName 'sparklesSolid' | 'zappy' zappy Icon of the Agent Avatar of type='agentic': zappy for Pantheon agents, sparklesSolid for third-party agents. Ignored for the other types.
type 'agentic' | 'critical' | 'discovery' | 'info' | 'success' | 'warning' 'info' agentic is new.

Variants and states: six types; with and without title, CTA, CTA icon, secondary action, badge; dismissible. Stories: Default, WithoutTitle, WithCTA, WithCTAIcon, WithSecondaryAction, WithBadge.

Tokens used

  • --pds-border-radius-container
  • --pds-border-width-default
  • --pds-color-foreground-default
  • --pds-color-status-{critical,discovery,info,success,warning}-{background,border,foreground}
  • --pds-color-surface-default
  • --pds-gradient-ai-active (new, for agentic)
  • --pds-spacing-{3xs,2xs,xs,s,m,l,xl}
  • --pds-typography-fw-semibold
  • --pds-typography-size-{s,m}

Full list: npm run check:tokens -- --report SectionMessage.

Impact

From impact.md: no existing component is changed. The additions are opt-in: .pds-section-message--agentic, and the rule that keeps the call to action the standard secondary Button in the agentic and discovery types. No --pds-* token is redefined. No other proposal builds on SectionMessage. SectionMessage itself builds on Badge (silver-muted for the agentic type), AgentAvatar and Icon, all ready for dev; port those first.

Reused vs net-new

  • Reused: the v2 Section Message in full; the package CloseButton; the PDS Button and the local Badge, AgentAvatar and Icon proposals (the call to action is the standard secondary Button).
  • Net-new: .pds-section-message--agentic; props avatarProps, iconName and the agentic value of type (which renders the Agent Avatar). Raw values kept, same as v2: 0.125rem and 0.0625rem, small optical nudges with no spacing token. Details in custom.md.

Accessibility

Unchanged from the v2 Section Message: a status region, a type label read by screen readers (typeLabels, now including agentic), a labelled dismiss button. The avatar's screen-reader text is the type's label by default, so it always has one. The agentic text and icon stay in the default foreground on a surface fill, so contrast matches a normal message. The a11y panel has not been run, and light and dark were not checked by eye in a session.

Decisions and open questions

For the engineer or designer to settle:

  • Badge color (decided 2026-10-21): the title badge of the agentic message is the neutral silver-muted, not the gradient agentic-filled; the other types keep the color that matches type.
  • Background awareness (not built). The fill of the agentic message is the default surface color for now. We might need a prop to make it background aware: on a message that sits on a secondary surface base, it uses the default surface fill; on a default surface base it would use the secondary fill; and then the reverse treatment on a reverse surface. That would be a prop that says what the message sits on (for example background: 'default' | 'secondary' | 'reverse'), so the fill, border and text colors can be picked to keep contrast. Decide with the engineer whether it is a prop, or something the surrounding surface passes down (a CSS variable or context).
  • Is type='agentic' the right place for it, given avatarProps works with every type?
  • The default agentic icon is zappy; sparklesSolid (third-party agents) is a new icon that is not in the PDS icon set or the Figma library yet (see the Icon proposal).

Port notes

Changes the existing PDS SectionMessage (src/components/notifications/SectionMessage/): add agentic to SectionMessageType (and its label in typeLabels), add iconName and avatarProps, render the Agent Avatar as the leading icon of the agentic type (and of any type given avatarProps), use the standard secondary Button as the CTA and color='silver-muted' to the Badge for the agentic type, and add the .pds-section-message--agentic rules. Differences from v2 to undo: local mergeClasses, StatusTypeLabels (it also lacked agentic) and the icon types (use the real ones); (min-width: 768px) and (max-width: 767px) back to --pds-bp-m and --pds-bp-s-only; onDismiss is typed with a DOM Event here (v2 types it with a MouseEvent); the CTA icon cast; and the dead error key in the type-class map is gone (replaced by agentic). pds-copy-s is !important, so a rule on the root cannot override size or weight. No generator needed.

Preview

npm run storybook, story Component Proposals / Section Message. Figma: https://www.figma.com/design/AMGWJbraJoi2PKWnxo29Ah/PDS-Proposals?node-id=363-44, page Section Message.