-
Notifications
You must be signed in to change notification settings - Fork 2.9k
UI Component Library
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.
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.
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 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.
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.
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.
You should add the code under the ComponentLibrary
folder in BrowserKit
, following the guidelines:
- 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. - 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.
- Localized strings and accessibility labels should be injected from the Client application, since translations live there. Injection should happen through the view model.
- 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. - 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). - 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. - 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.
You will need to close the Client application to be able to navigate
BrowserKit
in the Sample application when you openSample app xcodeproj
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.
- 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. - Add a new component view model following the
ComponentViewModel
protocol. - Make sure the
ComponentData
data array includes your new view model. - Bravo! You are now ready to test accessibility on your component following the components guidelines.