Hi all,

I have been working in an easier to use component spec sheets structure and I have created different examples with different type of components as not all components need to have the same info and structure.

I send you the Figma file link with the new spec sheet proposals: https://www.figma.com/file/jZGkd6eLRbPJJleyKc7XdY/Spec-sheet-examples?node-id=7%3A3694

I have created the following spec sheet examples for simple components (responsive behavior is not needed here):

• Buttons. In this example I have tried to improved the organization of the component, organizing them in 3 sections: progressive, destructive and neutral (all with Solid and outline variants). Also, I have tried to clean the spec sheet, making it easy to understand (for example, I have explained that we can have with or without icon variants, but is not needed to explain it with all type of buttons, so I just explained it once). Also, I have added here 320px spec sheets for mobile buttons, as we have desktop and mobile variants.

Example of spec sheet for more complex components (with responsive behaviors):

• Message
• Header (Vector skin)
• Header (Minerva skin)

*I know Vector header is for desktop and Minerva for mobile, but it's important to explain always all breakpoints in both headers.
*These breakpoints and grids are only an invented example, we will add the definitive ones when we define our breakpoints and grids.

If you all agree with this new structure, the next step would be apply this new structure and design to the most prioritized components (noted all in the task description).

I'm loving the level of detail and organization that goes into these new spec sheets!

Some things I especially like:

• The maximum examples are SO useful; I often wonder how I'm supposed to handle cases like this
• Same for the use cases; it's very helpful to have these documented so I can quickly gain an understanding of how the component should be used from a design standpoint
• Noting when something is the same for all variants (e.g. for button spacing) is helpful
• Responsive behavior for stuff like the header and messages is great too

Basically, I feel like this allows me to get the information I need to in an efficient manner. Awesome!

A couple of questions:

• For components that offer more complex interactivity, like form elements and dialogs, do you see the spec sheet as the place for defining things like keyboard navigation and details of UX upon interaction?
• Are these sheets solely for the design process and design/development handoff? I ask because one of the good things about the old versions is that they convey a lot of information in a short space, which is useful for a context like the Design Style Guide. I wonder if, for a context like that, we might want to present the most important info in a concise manner first, then allow people to drill down to the details if they want to?

Hi @AnneT

Thank you for your feedback, I'm glad this new structure fits you.

I answer your questions:

-For components that offer more complex interactivity, like form elements and dialogs, do you see the spec sheet as the place for defining things like keyboard navigation and details of UX upon interaction?

I have created these new spec sheets examples for Dropdown and Menu components so you can view use cases of more complex components with some navigation details and UX interactions. This is only a quick example to show how each component spec sheet is different from the others. The idea is that the specification sheet for each component has the necessary information to understand the behavior of that component, so there are no rules to build exactly each spec sheet but each spec sheet will have one info or another depending on the component.

• Are these sheets solely for the design process and design/development handoff? I ask because one of the good things about the old versions is that they convey a lot of information in a short space, which is useful for a context like the Design Style Guide. I wonder if, for a context like that, we might want to present the most important info in a concise manner first, then allow people to drill down to the details if they want to?

The idea with these new spec sheets was that they served both for the development handoff and for the documentation of our Figma design system, so they will be the documentation that designers will use to read the info about a component (they will also be able to use the Codex demo, but we need well defined Figma spec sheets too).

Thanks for the info and for adding those additional spec sheets! I think this looks great. I can only think of 2 additional things I'd like to see:

First is keyboard navigation details. I saw the table that @Sarai-WMDE posted as an example, and it's very effective—I like that it lays out what to do for each navigation type in terms of "if [scenario], do [action]."

The other thing is best described by an example: we recently had a discussion about the Lookup component, and what should happen when the user selects an option, then changes the input value. This could be described as "complex user interaction," but I think it also suggest that we need to document what the value of a form element means and should correlate with (e.g. for Lookup, it is the value of the currently selected option, and when the input value changes, the selection should be cleared.) Unfortunately, I'm not entirely sure how to best document this kind of thing, or even how to identify all necessary items to document. Perhaps we can talk about this when we discuss design/dev handoff?

Hi @AnneT thank you for your feedbacks.

First is keyboard navigation details. I saw the table that @Sarai-WMDE posted as an example, and it's very effective—I like that it lays out what to do for each navigation type in terms of "if [scenario], do [action]."

I have added this table explaining the keyboard shortcuts available for this component. This table is based in Sarai's. You can review the spec sheet to view how this table would integrate with the rest of the content. You can view this tablet updated in the Figma spec sheet here.

(e.g. for Lookup, it is the value of the currently selected option, and when the input value changes, the selection should be cleared.)

Also, I have added the Selected state to the component states to explain how would be viewed the selector with an option selected. I don't know if it would be enough to explain complex cases or not. If not, tell me another example and I will think in a new solution.

Awesome, I really like the key navigation table.

Having the selected state represented is critical, so this is a great addition. In terms of further complex user interaction, I think what Sarai is doing in the TypeaheadSearch designs under "Interaction" is effective: spelling out what happens when the user takes certain actions, with visual aids. I'm hoping that most components won't need this level of documentation, though!

I have been reading the "Interaction" section in the TypeheadSearch and I have added the scroll interaction in the Menu and Select components, explaining in the maximum examples that when there are more than 5 menu items a scroll bar will appear.

We will have to study each component in depth and we will have to apply some interactions or others according to the need of each component.

Thanks for sharing this new spec sheet format @bmartinezcalvo!
I think it makes sense for the user job story of a designer or developer learning about the design system to familiarise themselves with the component by looking it up on the Figma spec file. In regards to @AnneT's question about how to document more complex interactions, speaking for myself, while I think it would be good to see it documented in the Figma too, but what is probably better is to see and interact with a live demo, so I was happy to see incorporated in the spec sheet. Maybe there is some rubric/rule of thumb for how much into edge cases/complex interactions these sheets should get into the detail of, and what is left to something like a Storybook?

Relatedly and for future though, in the scenario where a developer/designer is looking at a product UI and selects a component, is it the case that the main component will have documentation text and link added to it so that for example one could navigate directly to the Button spec sheet or Storybook?

Example instance of a component that has documentation text and link to some demo/additional documentation	the main component with text and link fields filled in

@RHo thank you for your feedback, it's super useful to us knowing all the posible feedback before starting to add this spec sheet structure in our components.

Relatedly and for future though, in the scenario where a developer/designer is looking at a product UI and selects a component, is it the case that the main component will have documentation text and link added to it so that for example one could navigate directly to the Button spec sheet or Storybook?

About adding the documentation in the component, yes sure, we can add in all the components a brief description and a link to the component demo. Great idea.

Just for clarification, the Figma file was a (time-intense, but still) quick shot to bring over the OOUI component sheet to Figma and also add both, desktop and mobile components in a clearer way. There was not much discussion about it, it was mainly done to enable designers to work with Figma and have the components ready.
The structure to compare with from the past (with several flaws, but many iterations and thoughts baked into) is captured in the Sketch file and exported to SVG for quick lookup comparison.

Hi all,

I have been applying the new spec sheets design and structure to all our WikimediaUI components (Figma file), focused on the prioritized components listed in the task description.

I have done the following improvements:

• Cover: here we can view the cover and changelog (same than we have in the main file).
• Introduction: here I have explained some useful info for designers about the library and how to use its components and styles.
• Guidelines: here we will add all tokens (styles) when we have them in Codex (T293127)
• Components: here, in each tab, I have explained the behaviors of the different components that we already had in our library (NOTE: I haven't update any title, states, paddings.. nothing, I have only explained the components behaviors, and all possible improvements have been listed in this Notion so we can update them step by step). I have updated both the prioritized components in the task description list and the rest of the components in the library, with the idea of ​​being able to share the improvements in the library with all the updated component files.
• Patterns: here I have explained in each tab each skin patterns components.
• Templates: here I have explained each skin (New Vector, Vector Legacy and Minerva) with the different examples we already had in the library. Also, I have added some info about each skin.

You can view the Figma branch here. Once we review it I will merge it with the main WikimediaUI components file.

cc: @iamjessklein @Sarai-WMDE @Volker_E if you can take a quick look to see if you miss some important info in the spec sheets or see something that doesn't fit. I would like to merge this version with the main fail before our Codex Alpha Kikoff tomorrow. Also, I would like to present this new spec sheets to the design team tomorrow during our Design Practice & System Meetup, so if you agree we can move forward with this version and make all the improvements little by little once these new spec sheets have been shared.