Skip to content

Latest commit

 

History

History
88 lines (68 loc) · 5.6 KB

README.md

File metadata and controls

88 lines (68 loc) · 5.6 KB
Raw

Design tokens

How to update the design tokens

The expected workflow is that UX team runs a GitHub action in their repository, which will invoke our Import design tokens action. This action will upload the generated files and create a new PR with the changes.

What to do if you find an issue in some token

First of all, you have to find where is the problem, there are two main places:

  • The token is wrong in the mistica-design repository
    • In this case, you have to talk with design core team to fix it and generate the tokens again using the GitHub Action
  • The token is ok in the mistica-design repository but wrong in our code. In this case, there are two possible problems:
    • The tokens are not updated with the last changes of mistica-design repo. To fix it, run the GitHub Action to update them.
    • There is some issue in the tokens generator code. In this case, you will have to fix it in this repository.

How to add support for new type of tokens

If the design team adds a new type of token, for example, they want to include some animation duration as a token, we will have to add support for it.

Some points that you should have in mind in this case:

  • Usually a new key will be added at the top level of the JSON (light, dark, radius, etc). You will have to update the DTO to deserialize it.
  • Before starting to write code to generate the code and XMLs automatically, you will have to think about how to give support to this new token in Mistica, for example, which attributes you will have to create for example. Once you have this clear, you will be able to start generating that code that could be written manually if this generator didn't exist.
  • As we support XML and Compose, we have to give support to this new token in both systems. For that, we have two main classes GenerateXMLFiles and GenerateComposeFiles. You will have to modify them to add support for the new type of token.
  • To test your development easily, you can download the tokens files into /temp/mistica-design/tokens directory and run ./gradlew generateMisticaTokens.

How to add a new brand

This is not a common scenario, but in case you need to add a new brand, you can see this PR as a real example. For a detailed explanation, this is the required boilerplate:

val BRANDS = listOf(
    // ... 
    Brand(name = "pepito", file = "pepito") // file name must match the json file name from mistica-design repo
)

  • Push your branch and execute import-design-tokens.yml GitHub Workflow.

    • This will create a new Pull Request against your current branch.
    • Some reviewers will be added so you can wait for their approval or you can just merge this autogenerated PR against your previous branch and add those reviewers to the final PR later on.

  • Add a new enum entry to AbstractMisticaComposeView styleable

<declare-styleable name="AbstractMisticaComposeView">
        <attr name="composeBrand" format="enum">
            <!-- ... other entries-->
            <enum name="pepito" value="n + 1" /> <!--Important! previous value + 1-->
        </attr>
    </declare-styleable>

  • Create MisticaTheme.Pepito_Customizations xml theme:

    • It must inherit from autogenerated MisticaTheme.Pepito_Base theme
    • You can check existing "customizations" themes to see which are the attributes that need to be defined there.

  • Create its Compose brand by creating a new Kotlin object that must implement com.telefonica.mistica.compose.theme.brand.Brand interface inside its same package.

object PepitoBrand : Brand { // Name should follow XXXBrand naming convention
    override val compatibilityTheme: Int
        get() = R.style.MisticaTheme_Pepito
  
    // ... Compiler will force you to override every other property
}
  • Add new enum entry to com.telefonica.mistica.compose.theme.brand.BrandType enum class.
enum class BrandType {
  // ...
  PEPITO,
}
  • Add new ComponentStyle entry to available styles inside CatalogMainActivity::configureThemeDropDown method using autogenerated MisticaTheme.Pepito theme and the recently created BrandType value.
ComponentStyle("Pepito", R.style.MisticaTheme_Pepito, PEPITO),
  • Add required mapping from BrandType to compose Brand inside ComponentCatalogActivity::setUpThemes method
PEPITO -> PepitoBrand
  • Add PepitoBrand to the list of brands returned by TestUtils::getAllBrands method
  • Create MisticaTheme.Brand.test xml theme inside library/src/test/res/values/ folder. You can use existing test xml themes as reference.
  • Fix every required test class that may need support for this new brand.
  • Update screenshots baseline by triggering update_screenshot_baseline.yml GitHub workflow. This job will push a commit in your branch.