Education– Improving our naming conventions and logic for variants & their properties – Related to #3460

[SeamusLeonardHPE]

Purpose
 Our figma files, naming and build logic should map as closely as possible to grommet(hpe theme), or at very least guided by development principles for consistency. Standardising  our naming conventions will:

• Make it easier for design system consumers to use variants with overrides (less likely to detach components)
• This will help dev consume our figma files and bring us close to 1/1 parity.
• Meaning will be conveyed in layer and variant property name.
• This discipline will help designers understand the functionality, state, layout and style of each component as it is delivered on the web.
• Using the same names for layers inside variants allows designers to override text or styles and have those changes persist if the switch between variants. Its also allows prototyping to work correctly in 'smart animate' mode.
• Documenting this process will create standards for acceptance for newly created or modified components/variants.
• Documentation will act as an educational tool for onboarding new staff.

    Tasks 

Review our current naming standards if any exist and aggregate links/documentation into single place.   Review naming conventions in grommet and how properties are named and applied to various html elements (eg. xsmall, small, medium, )  

• 
Explore and document best use case for following figma variant properties, in a way that maps to grommets implementation:
Variant
• Boolean
• Instance swap
• Text

    Considerations

• 
Text layers: should be semantic and reflect the type of data that will fill them. (never inheriting the text copy)
• Frame Layer Names: should be semantic and contextual.

• Icon Layers: Should be contextual to their location & use, not just inheriting their default name.

• Shapes: Should all have the same name if they are able to be replace/overridden in the component.

Deliverable

• [x] First draft of written guidance for best practices, who to talk to for naming decisions, etc. (just a written document draft)

[ashifalinadaf]

Have collected some rough topics/ideas to include in education document. Figma

[SeamusLeonardHPE]

Hey @MikeKingdom this ticket is still in its early stages, but the goal is to create a best practice guide for designers to keep our work clean and comprehensible for hand off to devs. If you have time to work with @ashifalinadaf and @KennyAtHPE in the coming weeks to guide us as we help aim toward 1/1 parity between figma and grommet.

Some considerations are:

• [ ] How we can best name components & layers to match html elements or react components.
• [ ] How to name state/logic/props in our variants that match grommet, or at least are dev oriented.
• [ ] Anywhere we can bring our design files closer to code (reduce layers, use of autolayout etc).
• [ ] Guidance for us to design, structure and document semantically.
• [ ] Encourage design sign-off with the same attention to detail as a code (review for build quality not just visual).

Ashifs work on name value pairs provided some good lessons for us, @KennyAtHPE if there are some old components that need refactored into variants, or any problems areas that could be used as candidates for this as a housecleaning & documenting process that would be a good starting point.

Im happy to sit in on any sessions where we can discuss an approach and research/develop best practices.

Layer3674212 ☠️

[KennyAtHPE]

A couple of thoughts on how we should generally be building our Figma components

1. From the start, there should be dev and designer alignment on:
   • The function and implementation of the current component
   • How many components are needed + what type of components are needed (i.e. slot components, unpublished, and published components)
   • What props the component contains (https://v2.grommet.io/components)
2. From here, designers should draft out what variants, component properties, and variables are needed to build the component BEFORE building the component
   • Goal of this ticket is to better define this step. We should make a quick list of common variants, component properties, and variables that are used ubiquitously across all our components.
3. Again, connect with devs on this component outline before building said component
4. Now once all the prework has been done, the component can start being built. Note down all areas where it may be too complex to have parity with Grommet. The focus should not be on how we should solve these issues, the priority is to get something up and running first. If something proves to be too complex, be sure to reach out to devs and designers. Let's share our knowledge instead of working in silos.
5. Review with other designers on build and usability. Review with devs on layer naming, grouping, sizing, and spacing/margins (variants, component properties, and variables should have already been defined in step 2!!!).
6. If needed, test with stakeholders on flexibility and usability.
7. Publish and announce the component

[KennyAtHPE]

@SeamusLeonardHPE @vavalos5 ☝ please review the direction. P.S. I purposely omitted steps for deprecation, don't think we should include that here.

[ashifalinadaf]

Had a talk with Kenny on this, will be focusing on collecting common naming conventions to align more with grommet.

[SeamusLeonardHPE]

Thanks for the update and insight on this ticket @KennyAtHPE @ashifalinadaf Here is a fantastic article that promotes and explains the virtues of the type of consistency we are aiming for.

https://www.alicepackarddesign.com/blog/12-ways-to-make-your-figma-components-more-delightful-to-use

Its quite in-depth, I think we can trim some of those points down into guidance and education for our standards. For example this point is great, and something I struggled to verbalise so neatly. "First you need to understand the mechanics behind overrides and swapping: Figma decides whether or not to preserve overrides during a swap based on the layer architecture and layer names of the instance you're swapping out"

[KennyAtHPE]

@SeamusLeonardHPE Thanks for the article, we'll include these points in the guide we're building. To that example you mentioned, we do currently follow that rule specifically for our icons so that when the user uses the instance swap property all of their icons will maintain the same size and color. Definitely good to make note of in our guidance.

[vavalos5]

A couple of thoughts on how we should generally be building our Figma components

1. From the start, there should be dev and designer alignment on:

   • The function and implementation of the current component
   • How many components are needed + what type of components are needed (i.e. slot components, unpublished, and published components)
   • What props the component contains (https://v2.grommet.io/components)

2. From here, designers should draft out what variants, component properties, and variables are needed to build the component BEFORE building the component

   • Goal of this ticket is to better define this step. We should make a quick list of common variants, component properties, and variables that are used ubiquitously across all our components.
3. Again, connect with devs on this component outline before building said component
4. Now once all the prework has been done, the component can start being built. Note down all areas where it may be too complex to have parity with Grommet. The focus should not be on how we should solve these issues, the priority is to get something up and running first. If something proves to be too complex, be sure to reach out to devs and designers. Let's share our knowledge instead of working in silos.
5. Review with other designers on build and usability. Review with devs on layer naming, grouping, sizing, and spacing/margins (variants, component properties, and variables should have already been defined in step 2!!!).
6. If needed, test with stakeholders on flexibility and usability.
7. Publish and announce the component

I would 💯 support these steps and agree with them Kenny.

The idea of drafting what components and props are needed are going to make building the component and dev/designer discussions much easier. It should also become a part of component implementation tickets as well moving forward. On top of that, it helps us understand pros/cons and even complexities there might be if we were to build the components with Slots for example. Great list!

[KennyAtHPE]

Connected with Taylor. notes:

• In grommet, props are lowercased
• If a prop has multiple words it is camel cased with no spaces (ex. defaultSuggestion)
• When thinking of new prop names, the philosophy is to use 'plain English.' Keep it simple and intuitive for users, avoid flashy terminology.

[KennyAtHPE]

Created an initial outline for this internal guide. Please review @ashifalinadaf and begin filling in content. I'd start by reviewing and jotting down similarities within both our refactored figma components as well as Grommet component props.

Requesting eyes from @SeamusLeonardHPE

[SeamusLeonardHPE]

@KennyAtHPE that looks like a good outline. I added in a section for text layers naming as it is important for variants & prototypes.

Adding in this link to review, covers some of the topics we are tackling, might provide some inspiration for copy or deliverable layout.

https://www.figma.com/proto/NwJmqtzJkID8Y3Pc4UrLNU/Guide%3A-Layer-naming-conventions-(Community)?page-id=0%3A1&type=design&node-id=5-533&viewport=-572%2C349%2C0.21&t=2Bk4sxOnQyh1QbUi-1&scaling=scale-down&mode=design

[KennyAtHPE]

@SeamusLeonardHPE looks like the section you added is directly related to the "Layers" section I've outlined. Will combine the two sections but I am hesitant about including "setting resizing & autoflow & truncate rules to facilitate responsive design" since that doesn't seem entirely related to the rest of the guide (primarily just rules on naming conventions). Perhaps this should be included in a more general "how to build Figma components" guide.

[KennyAtHPE]

Connected w/ Asif, we are currently collecting common variants and component properties + their values to include in the guide as a cheat sheet.

[ashifalinadaf]

Collecting the common naming fro the variants of components. File

[vavalos5]

Adding the component/variant properties examples I’ve created in the education Figma file.

The idea was to create a list of common properties we utilize in the design system and include a description of how it is to be used and examples. In addition, I added small descriptions of what are component properties vs variants and a yes/no chart w/ examples.

[KennyAtHPE]

The outline for this document has been created and finalized. Created a follow on ticket to fill out the content. #3505

Closing out this ticket.