Skip to content

UI Component Library

Jump to bottom
lmarceau edited this page Sep 12, 2023 · 17 revisions

The UI Component library aims at unifying how we build UI elements in Firefox for iOS. This need arises since over time, UX tech debt was created since different areas of the application uses different looks. Fixing each view takes a lot of developer time since it needs to be done individually. Having standardized components will help us solve that. Developers can access those pre-built components, reducing the time and effort required to create new UI elements from scratch. Those components will be aligned with the Figma components and Acorn, improving collaboration between developers and designers since we’ll have a common language.

What is a component

UI Components are parts of the UI that can be reused in multiple places in the application. They are normally defined by designers. We should use the names from Figma components or Acorn. You can also take a look into the different Android components to ensure we are aligned on all platforms. If we are not, then conversation between related parties should happen, so we become aligned.

As devs, we can have two general categories for components; General components and features components.

General components

As developers, we sometimes need building blocks which aren't technically UX components. For example, a general component could be the base class to enable a certain type of UITableView cell which is then reused for features. Or it could a CardView that is reused in multiple feature components. More to come on that once we have more examples added to the library.

Feature components

Feature components are entirely defined by designers. They can depend on some of the General components (our building blocks). The feature component, when used only for a specific feature should live with the feature code. Example: if we have a Jump back in cell, although it can be based on some general components UI code, it should live with the Jump back in code in the Homepage since it's only used there. If that cell is reused at one point for other features, then we should move it to live under the Component Library.

Is it Component Library worthy?

If your UI component is used for one feature only, then let's keep this component with the feature code. If the UI component you are building has UI elements that can be reused (Example: with a specific type of container, or a specific type of button) then it can be worth moving it to the component library. If there's ambiguity, then you should bring this up with teammates for discussion in #firefox-ios-dev Slack channel or during our weekly engineering meeting.

How to add a new component

Once you have made sure you indeed have a component that should be added to that library, please see previous section first.

When adding a new component, there are two steps you need to be aware of. The first one is adding the component to the actual component library package located in BrowserKit, and the second one is adding the component to the sample application.

Component Library

You should add the code under the ComponentLibrary folder in BrowserKit, following the guidelines:

Guidelines for components

  1. Image identifiers should come from the StandardImageIndentifiers. If the image isn't standard, then it's probably a feature component that shouldn't live in Component Library.
  2. Accessibility identifiers should be customizable and injected from the Client application. Each identifier needs to be unique whenever the component is reused. Injection should happen through the view model.
  3. Localized strings and accessibility labels should be injected from the Client application, since translations live there. Injection should happen through the view model.
  4. Prefer having a configure method on the component rather than making properties public. This will ensure we have a standard way of using components. This will make code easier to maintain and understand over time.
  5. Ensure your component behaves properly with Dynamic Type. This means the component should be able to resize itself dynamically depending on its content size, and cannot have fixed height under any circumstances. Constraints should be done for that in all directions (top, bottom, trailing, leading). If you find yourself using a center constraint, you should make sure this is indeed needed and works properly (hint, extra work needs to be done if you center things only, the component won't behave properly otherwise).
  6. Ensure your component behaves properly with RTL languages. This means using trailing and leading constraints, and ensure images are flipped where ever needed. See imageFlippedForRightToLeftLayoutDirection for more information.
  7. Ensure your component behaves properly with Voice Over. This means we should inject needed identifiers for images to be read out loud to users to have the proper context. As developers, we should ensure the constraints are made properly, so the field highlighted with Voice Over is actually the one being read out loud.

Sample application

Once your component is added under the library, you are now ready to add an example of usage of that component in the sample application. This step is mandatory, to ensure that we have an easy way to keep track of components, know how to use them, and keep them relevant. Sample application could also be used to have screenshot tests at one point to ensure the components looks as they should on different device, with different text size, theme and so on.

How to add a Sample app example

You might need to close the Client application to be able to navigate BrowserKit in the Sample application when you open Sample app xcodeproj

  1. Add a new UIViewController that will show the component you created. Make sure it constrained properly so Dynamic Type will work with it. If there are multiple states to the component, ensure this view controller shows all the components states.
  2. Add a new component view model following the ComponentViewModel protocol.
  3. Make sure the ComponentData data array includes your new view model.
  4. Bravo! You are now ready to test accessibility on your component following the components guidelines.
Clone this wiki locally