Resources

Working with Ripple

What is Ripple?

Design systems provide a foundation for building the visual aspect and workflows of a product. They consist of small elements composed together to create larger patterns. So, the System includes guidelines for the use of color, typography and iconography which are composed to create a larger button element, which in turn is used in the composition of patterns for forms. Ripple is Watermark’s design system and comprises the Ripple site (with design guidelines and documentation), CSS library and web components. The assets are complementary, and are designed to help you achieve our company-wide objective of having a suite of products with a similar look and feel. Ripple is developed by the Design System team, and we are here to help you from adoption to troubleshooting at any time.

Evolution Through Collaboration

Ripple is a living, evolving system. It is the embodiment of the designs and workflows in all Watermark products and is based entirely on your needs. We, the Design System team, continuously iterate the design patterns and components as you communicate changing needs to us. You will invariably encounter discrepancies between Ripple and your design needs, either regarding an existing part of Ripple or where the system is silent. These are the opportunities that allow Ripple to grow and adapt, and it is therefore essential that we hear from you when this happens.

What to do and what to expect

When you notice a discrepancy between Ripple and your needs, contact someone on the Design System team as soon as possible. Doing so will begin a discussion to explore the matter and find a resolution. There are three possible outcomes:

  1. We will incorporate your needs into Ripple as a pattern or component for all Watermark use. If this happens, expect there to be two phases, design and development (as outlined in Our Process);
  2. We determine that your use is closely related to another pattern and we will work with you to come up with a design that suits your needs and fits with Watermark’s existing design pattern;
  3. We find that your designs, though not counter to any of Ripple's design patterns, are unique to your product and will not be used frequently. For that reason, it will not be added to Ripple. You may implement the design for this particular use case. Even if you already know that your design is unique, it is important to bring it to the attention of the design system team. If in the future other products have a similar design we will consider adding it to Ripple. If you find that you are using it repeatedly, you can ask the Ripple team to include it.

Help us help you

Every conversation helps the development of the system in a number of possible ways. Every time you inform us of your changing needs is an opportunity for us to make Ripple better for you. Iterating on patterns, adding new components, clarifying usage, or being aware of emerging patterns, are just some of the great things we get from you. So, please keep informing us when you have these discrepancies.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.