This document will guide on where and how to create global resources to be used throughout the app.
Note that resources should only be added this way if they are meant to be used everywhere in the app, in other modules.
If the resources being added are specific to a feature, those should be added to that feature's -ui module, or if shared between a few modules, -ui-slice module instead.
As a general guideline, these are the global resources as handed to dev by the design team. See resource specific sections for more details.
Color values and names can be found in the Figma side-bar under the Colors section.
// FIGMA COLOR IMAGE
The name used will be the second part of this name: primaryRed.
Colors are added in adp-ds-ui module, in the macys_colors.xml file. Use the name as described above for the color name and the hex value for the value.
We already use a 8-point dimension pattern. They are all defined in adp-ds-ui in the dimens.xml file. There we have many multiples of 8.
In addition, this file can contain meaningful dimensions like page padding, when those are widely used. Those should be added to the bottom of that file with an appropriate name.
Note that only a few dimensions will be global enough to be added here. For screen-specific sizing, use the predefined 8-point dimensions like usual. For custom sizes that for some reason do not fall in the 8-point system, define the custom dimension in the features -ui module.
Typography can be found in the Figma sidebar, under Typography section.
// FIGMA TYPOGRAPHY IMAGE
The first line is the name of the current Typography style. This should be used to create the resource name in the code. For example:
- App/Body -> TextAppearance.Macys.Body
- App/Links/Body Small Link -> TextAppearance.Macys.Links.BodySmallLink
Those should be extending the parent, and adding the changes as needed. For example, TextAppearance.Macys.Links.BodySmallLink extends a parent TextAppearance.Macys.Links
These text styles are in the adp-ds-ui module in the macys_text_appearance.xml file.
At the time this is written, there's only two button styles. Primary and Secondary.
These are defined in adp-ds-ui module in the macys_buttons.xml file.
If any more need to be added the should follow the same format as those and be added to that file.
If the button is local and only used in a specific feature, it should instead be added to that feature's -ui module.
Image and Drawable locations are really dependent on the use-case. Usually images that are used in a feature should be in that feature's -ui module's drawables directory. If they are used in a few related features, they could be moved to a -ui-slice module instead.
In the case where an icon or image is used very widely in the app, across features and modules, those should be added in the adp-ds-ui module's drawables directories.
In the case an image started local to a feature and then became global, it can simply be moved to the desired folder, and if the module dependencies are set up correctly, no code-changes should be needed for the move.
Examples of global images at the time this is written are icons/backgrounds of dialogs and toasts and the star icons for loyalty tiers.
In the case when we need a global component that is more complex that the categories above, or one composed by many of those, we have a few options.
If the component is completely domain agnostic (could be used in a non-macys Android application), those should be added to the adp-da-core-android module if they are not UI-related, and in the adp-da-ui if they are related to UI of some sort.
Currently, examples of these are the abstractions that we have for a tab layout, our generic RecyclerView adapter and the snackbar helper methods.
On the other hand, if the component is domain-specific, the implementation should be added to the adp-ds-ui module.
Examples of those currently are the MacysTooltip, some Notification classes and a ratings widget.
When the complex component has to do with UI, generally we try to implement using an entry-point layout file, which accepts a controller class through data binding that controls the behavior. Those should both exist in the same module. This way, to use it, we would define the controller class in our VM, configure it as needed and then <include/> the layout and pass it the controller instance through data binding.
If this is not enough for the use-case, we can explore extending View classes or SubClasses and adding functionality, but considering this can get really complex when configuration and nested data binding is involved, before going down this road, we should be exploring the effort size vs benefits we get from performing the abstraction.
A special case of globally used helpers are 3rd party abstractions. Usually when we integrate a 3rd party SDK, we try not to use it directly in our code, since we'd have to add the dependency to multiple modules and if we ever replace it, the refactoring effort would be big.
Instead, we define an interface describing the actions we use the SDK for, and then an implementation injected by Dagger that will use the SDK. This way, if we need to migrate to a different 3rd party provider that provides similar capabilities, we can just change that implementation and swap the two out, without changes in every module.
The location for these heavily depends on the type of implementation. For example, anything to do with performance monitoring should be in adp-ds-performance-analytics , or something that has to do with storage, should go to adp-da-storage etc.