Skip to content

Conversation

@pixelflips
Copy link
Member

Description

This PR adds a "Technical Notes" section to the pds-icon documentation to clarify the intentional differences in icon usage between React and web components.

Motivation: Developers may be confused about why React components use the icon property while web components use the name attribute. This documentation update explains the reasoning behind this design decision and helps developers understand the framework-specific optimizations.

Changes:

  • Added a new "Technical Notes" section to pds-icon.mdx
  • Documented that React uses icon property with imported icon objects for type safety, autocomplete, and tree-shaking
  • Documented that web components use name attribute with string values for HTML-like syntax
  • Clarified that using name in React triggers a warning and has no effect

No new dependencies are required for this change.

Fixes #(issue)

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update (documentation-only change)

How Has This Been Tested?

  • tested manually - Reviewed documentation rendering in Storybook
  • unit tests
  • e2e tests
  • accessibility tests
  • other:

Test Configuration:

  • Pine versions: Current development version
  • OS: macOS
  • Browsers: N/A (documentation change)
  • Screen readers: N/A
  • Misc: Verified MDX syntax and formatting

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing tests pass locally with my changes
  • Design has QA'ed and approved this PR

@pixelflips pixelflips self-assigned this Nov 24, 2025
@netlify
Copy link

netlify bot commented Nov 24, 2025

Deploy Preview for pine-design-system ready!

Name Link
🔨 Latest commit c723f8f
🔍 Latest deploy log https://app.netlify.com/projects/pine-design-system/deploys/6924e504a1c48c0008f86a8f
😎 Deploy Preview https://deploy-preview-596--pine-design-system.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions bot added documentation Improvements or additions to documentation package: core Changes have been made to the Core package labels Nov 24, 2025
@pixelflips pixelflips marked this pull request as ready for review November 24, 2025 23:30
Copy link
Contributor

@QuintonJason QuintonJason left a comment

Choose a reason for hiding this comment

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

Nice docs!

@pixelflips pixelflips merged commit 5415381 into main Nov 25, 2025
24 of 26 checks passed
@pixelflips pixelflips deleted the docs/icon-technical-notes branch November 25, 2025 19:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation package: core Changes have been made to the Core package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants