Skip to content

Update Typography and Content component descriptions (2026-04-rc)#4284

Open
sordaz00 wants to merge 1 commit into2026-04-rcfrom
typography-web-components-2026-04-rc
Open

Update Typography and Content component descriptions (2026-04-rc)#4284
sordaz00 wants to merge 1 commit into2026-04-rcfrom
typography-web-components-2026-04-rc

Conversation

@sordaz00
Copy link
Copy Markdown
Contributor

@sordaz00 sordaz00 commented Apr 10, 2026

Summary

  • Updates JSDoc descriptions for all Typography and Content web components (Text, Heading, Paragraph, Abbreviation, OrderedList, UnorderedList, ListItem, Time, Details, Summary, SkeletonParagraph, Chip, ClickableChip) to match admin quality bar
  • Enriches shared property descriptions (id, color, tone, accessibilityVisibility, display, fontVariantNumeric, lang, dir, lineClamp) to align with admin
  • Converts all @see tags to inline "Learn more" links, fixes PascalCase component names in prose, uses "A callback fired when..." pattern for events
  • Adds value descriptions for ParagraphType and TextType union members in source (requires surgical v2 JSON patching for visibility until generator supports type union JSDoc)

Test plan

  • yarn build passes
  • Regen CA and CO docs locally, verify Typography descriptions appear correctly in v2 JSON
  • Verify no generated files are included in this PR (source .d.ts and .doc.ts files only)
  • Spot-check component pages in local world preview for description quality

Made with Cursor

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 10, 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! 🙏

mcvinci
mcvinci approved these changes Apr 10, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci 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! I found a few areas where it might be worthwhile revisiting a few descriptions. Let me know if you have any questions! ❤️

packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts
@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base

declare const tagName = "s-paragraph";
/**
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci Apr 10, 2026

Choose a reason for hiding this comment

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

Noticed a few descriptions on the paragraph component that could be revisited:

Values could be reordered in the way they're presented:

Image Image

I think we might have missed updating the description (and a nested description) here:

Image

Copy link
Copy Markdown
Contributor Author

@sordaz00 sordaz00 Apr 13, 2026

Choose a reason for hiding this comment

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

The missing description is because of this issue, where some definitions aren't flowing to world. I'm surgically adding them, but they get erased every regen. https://shopify.slack.com/archives/C099RJCHAKE/p1775840928446659?thread_ts=1775663494.383649&cid=C099RJCHAKE

packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts
@@ -44,41 +44,38 @@ export interface ToggleArgumentsEvent {

declare const tagName = "s-details";
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci Apr 10, 2026

Choose a reason for hiding this comment

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

Noticed this one which can have the values reordered as well:

Image

packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts
@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base

declare const tagName = "s-heading";
/**
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci Apr 10, 2026

Choose a reason for hiding this comment

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

Similar re-ordering issue here, and let's also add a description for heading:
Image

packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts
@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base

declare const tagName = "s-text";
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci Apr 10, 2026

Choose a reason for hiding this comment

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

A few descriptions that could use revisiting for order of values presented:

Image Image

Also, I think we missed updating this description:

Image

packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts
declare const tagName = "s-time";
/**
* The element props interface for the Time component.
* Configure the following properties on the time component.
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci Apr 10, 2026

Choose a reason for hiding this comment

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

Not sure if we missed updating this one, but it looked a bit sparse. Also, I think this would be a datetime string?

Image

This was referenced Apr 10, 2026
Open
Open
@sordaz00 sordaz00 force-pushed the typography-web-components-2026-04-rc branch 2 times, most recently from 1948ff6 to 439176d Compare April 13, 2026 15:17
@sordaz00
Update Typography and Content component descriptions to match admin q…
19e579e 
…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-04-rc branch from 439176d to 19e579e Compare April 13, 2026 16:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mcvinci mcvinci mcvinci approved these changes

Assignees

No one assigned

Labels

Customer account UI extensions

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sordaz00 @mcvinci