Skip to content

Update Typography and Content component descriptions (2026-07-rc)#4296

Merged
sordaz00 merged 2 commits into2026-07-rcfrom
typography-web-components-2026-07-rc
Apr 14, 2026
Merged

Update Typography and Content component descriptions (2026-07-rc)#4296
sordaz00 merged 2 commits into2026-07-rcfrom
typography-web-components-2026-07-rc

Conversation

@sordaz00
Copy link
Copy Markdown
Contributor

@sordaz00 sordaz00 commented Apr 14, 2026

Summary

  • Cascades Typography and Content component description updates to the new 2026-07-rc branch
  • Enriches all interface, property, event, and slot descriptions to match admin quality bar
  • Adds inline value descriptions for type union properties directly in source

Test plan

  • yarn build passes
  • Verify no generated files included
  • Regen docs locally to verify descriptions

Made with Cursor

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 14, 2026

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

  • If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
  • If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

rennyG
rennyG approved these changes Apr 14, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@rennyG rennyG left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @sordaz00! Left mostly nitty style comments, but some where we could be a bit more clear.

Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts Outdated
* `newState` will be `closed`.
*
* Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
* Learn more about the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
Copy link
Copy Markdown
Contributor

@rennyG rennyG Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Learn more about the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
* Learn more about the [`newState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState) properties.

Confirming we don't need to retain the mention and link to toggle event like we do here?

Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts
Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts Outdated
export interface AccessibilityVisibilityProps {
/**
* Changes the visibility of the element.
* The visibility mode of the element for both visual and assistive technology users.
Copy link
Copy Markdown
Contributor

@rennyG rennyG Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finding this one a bit confusing, I'm not sure if we're meaning to day visual technology and assistive technology users, or visual and assistive technology users. Or sighted people and people who use assistive technology like screen readers?

Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts
Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts Outdated
Comment thread packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts
Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts Outdated
* `newState` will be `closed`.
*
* Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
* Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and the [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
Copy link
Copy Markdown
Contributor

@rennyG rennyG Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and the [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
* Learn more about the [`toggle` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), and the [`newState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [`oldState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState) properties.

There are a number of references to things that require code formatting throughout the PR, similar to this.

Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts
Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts
Comment thread packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts
@rennyG rennyG mentioned this pull request Apr 14, 2026
Merged
3 tasks
@sordaz00
Update Typography and Content component descriptions to match admin q…
857d74a 
…uality

Updates JSDoc descriptions for all Typography and Content web components
(Text, Heading, Paragraph, Abbreviation, OrderedList, UnorderedList,
ListItem, Time, Details, Summary, SkeletonParagraph, Chip, ClickableChip).

- Replace old "element props interface" pattern with "Configure the following
  properties on the [name] component." across all 13 .d.ts files
- Enrich Details events interface and toggle/aftertoggle descriptions
- Add Chip/ClickableChip slots interface descriptions
- Align shared property descriptions with admin quality (id, color, tone,
  accessibilityVisibility, display, fontVariantNumeric, lang, dir, lineClamp)
- Convert all @see tags to inline "Learn more" links
- Fix PascalCase component names in prose to lowercase
- Enrich type value descriptions (ParagraphType, TextType) in source
- Fix CA doc files (Time casing, OrderedList/UnorderedList grammar)

Made-with: Cursor
@sordaz00 sordaz00 force-pushed the typography-web-components-2026-07-rc branch from a7b1b79 to 857d74a Compare April 14, 2026 23:35
@sordaz00 sordaz00 force-pushed the typography-web-components-2026-07-rc branch from 1369432 to 86bbf62 Compare April 14, 2026 23:56
@sordaz00 sordaz00 merged commit bf1b89b into 2026-07-rc Apr 14, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rennyG rennyG rennyG approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sordaz00 @rennyG