Decisions: Section Message

Start from an unchanged copy of v2 Section Message

• Decision: Copied SectionMessage.tsx, section-message.css and the stories from the reference checkout (v2.0.0-beta.12) without behavior changes. CloseButton comes from the package; Badge and Button are the local proposals (see the agentic note below).
• Why: The designer asked for a copy of the PDS Section Message to work from.
• Port impact: Local stand-ins replace mergeClasses, StatusType and StatusTypeLabels (the package does not export them), and the icon type comes from the local Icon wrapper. The CSS uses (min-width: 768px) and (max-width: 767px) in place of the --pds-bp-m and --pds-bp-s-only custom media, which do not work in this repo; the port restores the token form. onDismiss is typed with a DOM Event (it fires from animationend), and the CTA's icon prop takes a cast to accept the local icon type.

Add type='agentic' (2026-10-19)

• Decision: agentic is a new value of type (not an isAgentic boolean). The AI gradient is a 1px border on a surface fill, static. Text and icon stay in the default foreground. The leading icon is zappy by default; a new iconName prop (zappy or sparklesSolid) picks it, and is ignored for the other types. The CTA is the agentic Button (isAgentic) and the badge is the filled agentic Badge color. The role stays status.
• Why: type already controls this component's color, icon and announced label, and agentic replaces all three, like discovery. A surface fill keeps it distinct from the purple discovery message and keeps text contrast in light and dark. The border pattern matches the agentic Button and Panel.
• Port impact: adds agentic to SectionMessageType and iconName to the props. The component now imports the local Button (for isAgentic) and the local Badge (for agentic-filled), so it ports with those two proposals. Adds .pds-section-message--agentic to the CSS, including an override that keeps the agentic CTA's gradient border.

Agent Avatar in place of the icon, as a suggestion to review (2026-10-19)

• Decision: avatarProps (the Agent Avatar props, label required) swaps the leading icon for the Agent Avatar (any type). Everything else is the same. The size defaults to m (24px, the title row height) with a title and s (20px) without; avatarProps.size overrides it. Shown under every story (a story decorator renders the same message again with avatarProps, captioned "Suggestion") for the designer to review with the engineer. The decorator is story-only and goes away once one option is chosen.
• Why: the designer wants to compare the plain icon with the avatar. It follows AvatarLabel, which takes avatarProps.
• Port impact: the component imports the local AgentAvatar, so it ports with that proposal. If the avatar is chosen, the iconName prop could be dropped (the avatar has its own iconName).

Third suggestion: discovery palette with the Agent Avatar (2026-10-19)

• Decision: the second suggestion panel under every story is type='discovery' (the purple status palette) with the Agent Avatar as the icon. avatarProps now works with any type, not only agentic. The CTA is a regular message-colored Button (the agentic Button is only used for agentic), and a badge would take the discovery color.
• Why: the designer wants a purple option to compare against the gradient border. It needs no new CSS, since discovery already exists.
• Port impact: none beyond avatarProps working for every type.

Fourth suggestion: discovery palette with the gradient border (2026-10-21)

• Decision: a third panel under every story: type='discovery' with the Agent Avatar and the AI gradient as the border (a copy of suggestion 2 with the border swapped). New boolean hasAgenticBorder paints the gradient border over any type and keeps that type's fill and text colors. The gradient painting is shared with type='agentic' in the CSS. The border shimmers (the same loop as the animated agentic Panel, off for reduced motion); type='agentic' itself stays static.
• Why: the designer wants to compare the purple palette with a plain purple border against the same palette with the agentic border.
• Port impact: adds hasAgenticBorder and .pds-section-message--agenticBorder. Goes away with the story decorator if another option is chosen.

Semantic tokens (2026-10-19)

• Decision: colors were already semantic (status, foreground, surface, gradient tokens). The root now takes the pds-copy-s class instead of declaring font-family, and the message text drops its size and line-height declarations (it inherits copy-s). The title keeps --pds-typography-size-m and fw-semibold, because no semantic class matches a semibold m in the default family. The two small offsets stay as raw rem values (listed in custom.md).
• Why: the designer asked for semantic tokens over primitives where they exist.
• Port impact: the pds-copy-s class is !important; the title is a child, so its own size and weight still apply.

Open questions

• Which for the agentic message: gradient border with icon, gradient border with Agent Avatar, discovery palette with Agent Avatar, or discovery palette with gradient border and Agent Avatar? (designer, with engineer)

The agentic CTA is the AgenticButton (2026-10-21, superseded: it is now the standard secondary Button, see the last section)

• Decision: the call to action of the agentic type is the AgenticButton component (it was a Button with isAgentic, which was removed). Other types keep the secondary Button. The rule that keeps its gradient border now targets .pds-agentic-button.
• Port impact: SectionMessage imports AgenticButton, so it ports after it.

Secondary surface fill instead of the purple (2026-10-21)

• Decision: the designer does not like the discovery (purple) fill. The two discovery suggestions under every story (2 and 3) now use the secondary surface color (--pds-color-surface-default-secondary) as the fill instead, through a new boolean hasSurfaceFill. The type's border and text colors are kept (so they are still purple for discovery), to change only the fill. Suggestion 3 also keeps the gradient border. The --message-bg variable carries it, so the CTA button follows.
• Why: the designer wants to try a neutral fill in place of the purple.
• Port impact: adds hasSurfaceFill and .pds-section-message--surface-fill. If this is chosen, the discovery suggestions may not be needed at all, and the agentic type could take the fill directly.
• Open: keep the purple border and text with the grey fill, or make the border and text neutral too?

Default surface fill for now, and a background-aware prop later (2026-10-21)

• Decision: the fill of the two suggestions (hasSurfaceFill) is the default surface color (--pds-color-surface-default), not the secondary surface (the designer's call after trying the secondary one). The type's border and text colors are kept.
• Open, for later: the message may need to be background aware. On a screen whose base is the secondary surface, the default surface fill still reads as a card; on a default surface base it would not stand out, so it would use the secondary fill, and then, on the reverse surface, a reverse treatment. That would be a prop (for example a background value of default, secondary or reverse, telling the message what it sits on) that picks the fill. Not built; recorded in the handoff.

Discovery CTA is the standard secondary Button (2026-10-21)

• Decision: in a discovery message the call to action is the standard PDS secondary Button, not tinted with the message's purple. The other types keep the v2 behavior (the CTA takes the message's colors), and the agentic type's CTA is the AgenticButton.
• Why: the designer does not want the purple button.
• Port impact: the v2 rule that colors the CTA now excludes .pds-section-message--discovery. If the same is wanted for every type, drop the rule.
• Open: should every type use the standard secondary Button, not only discovery?

One suggestion left, and the standard secondary Button as the CTA (2026-10-21)

• Decision: the story decorator now shows only the first suggestion (the Agent Avatar in place of the icon) under each story. The discovery suggestions were dropped, and with them the story-only props hasSurfaceFill and hasAgenticBorder and their CSS (the surface-fill rule, the border-only class, the shimmer). The call to action of the agentic message is the standard PDS secondary Button (not the AgenticButton, and not tinted with the message colors); the same holds for discovery. The other types keep the v2 behavior. SectionMessage no longer imports the AgenticButton.
• Why: the designer's call from reviewing the suggestions.
• Port impact: one dependency fewer (AgenticButton). The v2 rule that colors the CTA now excludes the agentic and discovery types.
• Open: the icon or the avatar? And should every type use the standard secondary Button?

The Agent Avatar is the agentic message's icon (2026-10-21)

• Decision: the comparison is over. The agentic message shows the Agent Avatar in place of the icon, as the standard: the story decorator that repeated each story with a "Suggestion" caption was removed, and every story shows the avatar. The component renders it by default for type='agentic': iconName picks the avatar's icon, the avatar's label is the type's label (typeLabels.agentic, so it is translatable), and avatarProps (now partial) overrides the halo, shape, size or label. The avatar-only story controls (halo, icon, shape, size) went with the decorator; avatarProps is an object control.
• Why: the designer decided the avatar is the one we want.
• Port impact: the agentic type imports the AgentAvatar (already a dependency); avatarProps is optional and partial. The plain zappy icon is no longer rendered for agentic.
• Closed: the open question about icon or avatar.

The agentic badge is silver-muted (2026-10-21)

• Decision: the title badge of the agentic message is the Badge's neutral silver-muted, not the gradient agentic-filled (the designer found it too colorful; eight neutral colors were compared and this one chosen). The other types keep the badge color that matches type. The comparison story and its badgeColor prop were removed.
• Why: a quieter badge, from the PDS colors.
• Port impact: the Section Message's badge uses color='silver-muted' for agentic; the Badge's agentic-filled is no longer used here.