Your digital product needs a team that works efficiently toward your goal. Whether you need design, UXD, or engineering support, we can help. Book a free consult to learn more.
Component-driven development offers the benefits of consistency, reusability, and improved developer experience when building web applications. DockYard utilizes a multidisciplinary approach to component work that involves the Design, UXD, and Engineering teams.
As a UX Developer, our specialty is converting design specs into semantic HTML and CSS that is responsive, accessible, and browser-compatible – which becomes the basis of a component. The base component is then transferred to an engineer who will enhance it to become a fully functional and reusable component.
The handoff to engineering is a critical point in collaboration. It may appear fairly straightforward to pass off a static version of our component to the Engineering team. However, our markup could contain any number of styles, attributes, and state changes with little or no context at a glance. If you’ve ever worked with Tailwind, for example, you could easily inherit significant class lists for even the simplest components.
To that end, we strive to provide an optimal experience for our engineers by providing documentation via comments in our code. This type of documentation improves overall quality and avoids the familiar churn of trying to clarify expectations. When providing this documentation, I like to think in terms of Intentions, Constants, Variants, and Accessibility.
State Your Intention:
Think about what your component does. What is its purpose? What are the use cases? Who is it for? What features are included? What features are not included? At a high level, the expected behavior of your component should be very clear. This information should be kept and maintained within your component. If you or someone new needs to modify this component at any point, they’ll have a decent grasp on what to expect.
Provide a Constant:
For engineering, declare your base markup and styles. Think of the parts of your component that are constants—not likely to change.
Define Your Variants
Think about what can change. Does your component include state changes, such as a success or error state? Do you need to hide or reveal some type of drawer or tab panel? Document which parts of your markup or styles can change and under which circumstances—whether by user interaction or the completion of some process. The next engineer will thank you for this context. You may thank your former self as well.
Include Accessibility
How does your component account for users of assistive technologies? Here, include details such as hover, focus, or
active states. Mention any
ARIA attributes and how these may change or relate to the elements within your component. Think of aria-controls or
aria-selected="false” v aria-selected="true”. Is there consideration for keyboard interactions? What should happen
when a user presses the space bar or escape key when interacting with a modal, for example?
This is not an exhaustive list of all the ways you can comment or document your code, but a starting point to help define and validate your components. This method boosts collaboration and provides a solid base for your favorite engineer to do their best work. It may create a little more effort upfront but will provide great value in the long run.
