Process for adding new components to Maker #158
Replies: 5 comments 1 reply
-
I think creating a new GitHub Issue form to guide contributors with writing a component TAD/RFC is a good idea. Taking a step back, I'm curious what requirements there are for designers/PMs to provide before handing it off to the engineer to implement. For example, I understand designers spec out the component in Figma, but is there a required list of points to address? Thinking of the process holistically can make sure engineers have sufficient knowledge to write a good TAD without being burdened with questions only designers can answer. Holistic process proposalA process that involves PMs/designers and engineers that break down how a new component should be introduced to the design system:
I believe @landondurnan's proposal is Step 3, but contextualizing it with the input/output of the step can help make sure it fits into the process efficiently. |
Beta Was this translation helpful? Give feedback.
-
Steps 1 and 2 are currently happening and managed in Figma right now with the design team. Maybe this could improve with communication between design and engineering. To help standardize that and ensure everyone is on the same page, a minimum amount of eng design / discovery should occur before significant engineering work occurs. I think our internal resource and planning around Maker development is still something we're struggling with on the engineering side, but I think we can improve by following a bit more process and increase communication cross-team and cross-functionally. A design system or open source project can't do all of those things, but I think the template I proposed would help us in that effort. |
Beta Was this translation helpful? Give feedback.
-
I agree with @privatenumber's holistic process proposal, and echo @ashjtan's thoughts. Right now it seems that a lot of designs that are handed off to engineers contain single variations of a component and have a tag that says to put this component in Maker. So step 1 of Hiroki's process is basically skipped and step 2 only has a single variation designed. This leaves eng to work out the different variants/states/errors etc of the component and then we have to kick it back to design for further iteration. Eng feature proposals like Landon suggested can be helpful because reading through one can make it clear that designs are not ready for implementation. However, I would prefer to see this maker eng feature request template focused more solely on the engineering implementation aspects of the feature more so than the design requirements. Instead of asking eng to fill out all of the design questions themselves I think it would make more sense to just have a list of checkboxes regarding the state of the designs.
Along with this change I would very much like to see a more formal maker component request document for PM/Designs to fill out. That way during a design reviews eng can easily push back on any component for Maker that haven't had the proper due diligence put into them yet. |
Beta Was this translation helpful? Give feedback.
-
For clarity, design is working together to consider things holistically and we have regular weekly office hours that anyone can come to where we review all of this. We have many challenges and our process is still being figured out, but one challenge is the hand-off from design to engineering needs more definition and engineering needs to align on the problems and solutions before significant engineering work begins. My proposed template is directly trying to address that. Starting there and then determining other gaps in process can happen iteratively. |
Beta Was this translation helpful? Give feedback.
-
@privatenumber has a done a good job of summarizing some of the feedback in the original PR. I'd like to address each one individually here.
Design works very hard to ensure there is alignment with other designers and engineers prior to hand-off to engineering. This is happening right now through Figma, synchronous meetings, and async conversations. With all that being said -- there is often an engineering specific response to the questions in the template. The Issue template is intended to allow engineers to collaborate with other engineers about the specific functional requirements of a component in their own language. "I need to fire EventA to communicate this status to ComponentB". The same goes for Theming -- there is a translation sometimes necessary to communicate how Theming may impact a component that is beyond the scope of the original design. If a design shows the primary color being used, the designer has communicated usage of the primary color. How we pass data about the primary color to a component is a separate engineering consideration.
This is also happening in Figma and discussed through async / sync conversations. Engineering still has a shared responsibility to do the same amount of research. Consider the functional responsibilities of a component, its reusability, passing data and events around. There's a lot of nuance to decisions about the form and function of a component besides the design. Design may say "this component works like this component from another library", but the details about how other engineers will build with that component or use it with other components may inform different naming conventions, how atomic a component is, how it might work with other components. Something as simple as restructuring what design considers to be a single component may require engineering to break it into several smaller components or utilities. That should cause additional iterations on the design so we're all speaking the same language and are clarifying usage. We don't want a waterfall pattern, but a chance for engineering to clarify, align, and continue to iterate with design.
Design as a whole are doing their due dilligence. The template is intended as a milestone in the process of handing things off from design to engineering. This way more engineers can review, discuss, and align on approach before proceeding. What I'm trying to get out of this discussion is ensuring everyone understands that a lot of work already happens before this template should be filled out by an engineer. The reason an engineer is filling out this template is so they can collaborate with other engineers with a minimum amount of eng design to ensure we save time later when reviewing code based on an agreed spec. |
Beta Was this translation helpful? Give feedback.
-
Motivation
There is currently no formal process for engineering to take a design hand-off of a component into Maker.
Recently, unvetted components have been introduced via pull-request, surfacing a lot of component validation questions in the code-review.
This can cost us a lot of time in code review, and even put a lot of engineering work to waste.
There are a lot of moving parts to this project, so I think we can do more to streamline the process of adding new components.
Proposal
Leverage a "New Component Issue Template" to help outline the overall requirements of the component upfront before significant development states. I created a PR for that here: #152
After Design hand-off to Engineering, the process would be for engineers to leverage the issue template to align and collaborate on the development work.
Looking for feedback from @square/maker-core-contributors and recent contributors: @mbove-square @tatems @ashjtan
Beta Was this translation helpful? Give feedback.
All reactions