Spec for Detail Text

[gloriliale]

Review request: spec for new Detail Text component

The UX Infrastructure team will be releasing a new Detail Text component based on the spec doc linked below. Please review the spec and leave any comments and feedback in this thread or on the document itself.

Links

• Detail Text spec document

The time estimate of this review is short (5-10 min).

Please complete your review by Tuesday Jan 24th. Many thanks!

[deeleman]

I like very much this component and find it quite useful, particularly in the absence of higher specificity elements for tables and images, respectively. I have some questions regarding patterns and use guidelines:

1. In the Examples section we feature an example of using Detail Text to add a caption element below an image. According to the W3C guidelines <figcaption> can be placed either above or below the captioned image. What is the guidance for Paste, particularly? Will consumers have freedom of choice to place detail text either way or should the Paste patterns advocate for a stricter approach for images (eg. always at the bottom) for the sake of consistency?
2. As any other descriptor element, the Detail Text element could be annotated with an id matching the value of an aria-labelledby or aria-describedby attribute decorating the element being captioned. Should the Accessibility section make an explicit reference to this, in order to help consumers better cope with a11y?
3. Since the <CaptionText> element (as we see it at CodeSandbox) is leveraging the Text primitive under the hood, I assume we can use it for captioning tables as well. Eg:

<Table tableLayout="fixed" variant="default">
  <CaptionText as="caption">My table caption</CaptionText>
  <THead>
    <Tr verticalAlign="middle">
      <Th>Etc...</Th>

If so, should an example be included in the component spec as well? On the other hand, positioning of caption elements inside tables is governed by the caption-side CSS property with top and bottom as directional values (same as within <figcaption> elements but those require the parent <figure> to feature a table display then, which I guess is out of the scope of this discussion). Therefore, have you considered adding a surface prop to the API to allow consumers to customise positioning or will the component rather take a safer, opinionated approach for use cases within tables?

Kudos to the Paste team! 🚀

[gloriliale]

Thanks for your detailed feedback, @deeleman! It is very appreciated! Some responses:

1. This is a good question. We typically try to leave the component as composable as possible and then offer guidance on best use. I'll discuss the placement of a caption in relation to its image with designers to determine if there are any guidelines we should add in this section for more consistent usage, and add the update here as well.
2. This would be a great addition to the accessibility section, we'll be adding it!
3. Let me discuss this with our engineering team and get back to you.

I'll circle back soon when I've got more intel.

[gloriliale]

Hi @deeleman! Wanted to circle back with our results here:
Question 1. We've added guidance on placing the Detail Text below images to encourage a consistent experience across Twilio. Thank you for this callout!

Question 3. This is a good question- we do encourage this to be used for captions but it is not the component's only role. I'll continue discussing it with the engineers to see if there's a way to support attributes like this, but it might be out of scope for the first pass of Detail Text. For more context: how often do you use caption-side at the moment?

[deeleman]

RE question 3 - Short answer: very rarely I'd say. TBH and after giving it a second thought I would advocate to provide no option at all and only revisit this opinionated approach if a well reasoned argument for it arises in the future. Thanks!

[gloriliale]

Of course, we appreciate you bringing it up so that we could think it through! 🧠

[serifluous]

A few questions around examples:

1. The spec includes an example of "Detail Text below a card". Are there examples of products doing this right now?
2. I feel like one of the most common use cases of "secondary text" is in a table, like this screenshot shown in the kickoff:

Is this meant to covered by the "Detail Text as a footnote" example, or not a recommended use of Detail Text at all?

[mel510]

+1 to more explicit details in Do/Don't section. I'm assuming it's not recommended to use Detail Text for stylistic purposes within a body and I think this could be more clearly called out.

[gloriliale]

Thanks @serifluous and @mel510!

1. Good question- nothing specific comes to mind, lemme do a little more digging
2. I think this is a valid use of DetailText that isn't covered yet; I'll add it as an example.

@Mel150 this is a good callout- I've added more explicit language in the do/don'ts and also in the About section to point this out!

[gloriliale]

@serifluous To close the loop on question 1: we haven't found use cases of "Detail Text below a card" and have replaced that example with the one you described in question 2, with it below some primary content in a table cell. Ty!

[mel510]

This might be more clear once images are added, but what is the recommendation for using the marginBottom prop?

[gloriliale]

@mel510 this question sparked a lot of thought- I talked about it during the sync and brought it to the team, and we determined that a marginTop prop, a la Help Text, actually makes more sense for Detail Text. I've updated the spec to reflect this. We will have space30 as the default, since many use cases have the secondary text below the primary content, but allow it to be removed if needed by setting it to space0. Let me know how that sounds to you!

[gloriliale]

Thank you for contributing to Paste, everyone! This thread is now closed. Keep your eyes out for Detail Text in the near future!