After exploring various solutions to simplify the maintenance of our component guidelines images, here are the options I've identified:

Op.1: Replace the images with coded demos

Pros:

• The demo will be automatically updated every time we update the component in code.
• Responsiveness will work properly in these demos.

Cons:

• Demos don’t cover all our needs (e.g. they cannot be used to illustrate the “Specifications” or “Interaction States” sections), So we will need to create some images anyway.
• The component in the demo will be displayed in its default state (e.g. collapsed). So in case we need to represent an expanded or active state in the guidelines, users will need to interact with the demo to understand how the component behaves.
• We will need support from developers to create the demos for the first time we include the demos in the Guidelines. Then the demos included will be automatically updated. |

Op.2: Embed Figma (example)

*We need to ensure the Figma file containing the embedded Figma frames is made public so that any user can access the embedded view. I'm not sure if this might cause any additional issues, but I wanted to mention it here just in case.

Pros:

• We can easily include any type of image, so embedded Figma images cover all our needs (including the “Specifications” or “Interaction States” sections).
• Embedded images will be automatically updated when we update its design in the Figma frame embedded.
• Responsiveness will work properly since the user can zoom in and out on them.

Cons:

• Load Time: Large Figma designs can increase page load times. We will need to optimize the size of the embedded frame or use lazy loading techniques.
• Accessibility: how we can include Alt text within an embed Figma?

Op.3: Just use images when they are really needed (example)

Pros:

• Easier to maintain: guidelines will be easier to maintain since they will be mostly text.
• We can design any type of image if needed, so we can cover all our needs (including the “Specifications” or “Interaction States” sections).

Cons:

• Guidelines will be less visual in some cases: Since they will be text in mostly of the cases, they will be less illustrative. The user could play with the demo, but they might need visual representation in other cases.
• Hard to maintain: although we would reduce the use of images, these will need to be updated anyway if we update the component. We will need to be careful with its SVG export as well to avoid export errors.
• Responsiveness: the images used in some of the guidelines will not be enough readable on mobile in some cases.

After analyzing all the options, it seems Option 2 (Figma embed) is the best one in terms of maintainability, but it might not be the best one in terms of visibility or accessibility. So in case we want to use embed Figma images, we should test this in some way before implementing it in al components pages in Codex. @mwilliams let me know your thoughts.

@bmartinezcalvo Option 2 seems super reasonable to me! I haven't seen this done in practice - like you've mentioned, perhaps testing this for a certain component and sharing back here might be the best way to ensure this is the right decision.

Since we explored Figma embeds in T358027 and we decided to refrain from using them due to the load time, we will continue utilizing images in the guidelines for now since it seems that there is currently no better alternative.

Considering that we are actively contributing patches to improve Codex design guidelines, it would be beneficial to streamline the workflow for updating images so we can simplify the process for designers when updating images for component guidelines, reducing optimization issues or errors during the patch submission for image updates.