Thank you for your interest in the Skapa android project. Your contributions are highly welcome.
If you have any questions regarding contributing to this inner source project or would like to chat with us, please reach out on Slack if you have access #support-skapa-designsystem-android or through the Skapa hub.
Please read about this on the project root page and its LICENSE terms before making a contribution.
When you're ready to contribute, please create a GitHub issue in the repository and describe your contribution. This approach allows our developers to easily participate, answer questions, and provide early feedback.
Fixing bugs is one of the best ways to contribute. If you want to help improve the Skapa libraries please create a pull request with your fix as described in section Contribute code below. If you encounter other bugs in the code please submit an bug report. To report a defect go to https://skapa.ikea.net/connect/contribute/#1-report-an-issue or submit one directly in the issues tab.
Code improvements that does not affect functionality or UI can also be contributed the same ways as with Bug Fixes but we suggest reaching out in beforehand to suggesting your solution. Get in contact with us either via Slack or posting an issue in the issues tab here in the repo with a proposed solution.
For new features that adds functionally, changes the UI and/or might affect other platforms please use this form to request a new features https://skapa.ikea.net/connect/request/request-a-new-feature/.
The main structure and deliverables of this project are described in the README (or root page when not accessed from Github repo page) and here we are going a bit deeper into the repository structure to provide a better overview from a contributor point of view.
Foundation module ./skapa/foundation
This package contains all the Skapa Colours, Typography, Spacing, Borders and Motion tokens. Read more on Skapa hub. At this point the Colour tokens are updated through automatic PRs from the skapa-design-tokens repo when global or alias token colours are added or changed. However other design tokens are planned to undergo the same automation in the future.
Worth noting is that the Skapa Icons have its own module due to more frequent updates.
Dependencies: Noto IKEA Latin font package
Design module ./skapa/design
This is the main components package with 30+ components.
Dependencies: Foundation
Dependencies: Design, Foundation
Icons module ./skapa/icons
Contains the approved Skapa Icons from Figma (700+ icons). All icons are available in both Light and Dark mode. Worth noting that a subset of the icons are multi-coloured. Apart from the Skapa icons this package also includes the Social media icons but not the External payment providers.
In addition to Xml Vector Drawable files there is also an enum class SkapaIcons with mapping to the resource file for additional ways of initiating the icons. This enum class is a generated file so make sure not to change it manually.
Font modules ./skapa/fonts
These modules can be used independently and does contain any code apart from FontFamily wrapper and the .ttf files.
Test module ./skapa/design-test
Both Unit and Snapshots tests are located in the design-test module.
Demo app ./app
The Skapa demo app for Android is used to both showcase our modules, components and other features but more importantly a way for us to test our components in an app-like environment. This app is also available in the Firebase test environment and can be reached by signing up here.
Apart from following the Jetpack compose API guidelines together with Kotlin guidelines there are some additional Skapa guidelines.
We use some linters and code style plugins to to enforce code structure and to keep source code consistent - ktLint, lint and detekt.
Also check this specific file targeting Code conventions.
We strive to make our components accessible and usable for everyone. This means that we follow the latest WCAG 2.2 standards guidelines (AA standards) and use the Android Accessibility Guidelines as a reference. Also have a look at our Skapa Accessibility guidelines.
As we also provide support for RTL languages we also follow the Android RTL guidelines and our Skapa RTL guidelines.
To mitigate the risks of releasing bugs to production - that could be easily identified - we have implemented Unit & Instrumented tests. These tests make sure the Skapa components are following the correct guidelines, colours, design tokens, behaviour, and are accessible.
To execute these tests you can run the following commands:
Unit Tests - ./gradlew clean skapa:foundation:testDebugUnitTest skapa:design-test:testDebugUnitTest --continue
Screenshot/Instrumented Tests - ./gradlew skapa:design-test:pixel6api35DebugAndroidTest
However, we advice to setup your own AVD as the above script does not save the AVD it is running on but merely creates it for the Gradle test task and discards it afterwards.
How to set up devices for Screenshot test: Note! You need to use exactly this setup in order to make screenshot comparable with the baseline images. Unfortunately the one currently used has been removed in later releases so we need to use this workaround to create it.
The tests can now be run directly from Android studio.
Ktlint is integrated into the build task process in this project through the Ktlint Gradle Plugin.
Therefore, every build will run an incremental ktlintCheck task to validate the kotlin rules.
To validate your code you can execute ./gradlew ktlintCheck --continue in your terminal and it will check if the code is compliant with kotlin coding conventions.
Ktlint provides another task called ktlintFormat to format all SourceSet's Kotlin files in the project according
to the code styles. This task fixes for free most of your kotlin lint issues.
As opposite to ktlintCheck, ktlintFormat doesn't run automatically with our PR builds to prevent undesirable code changes.
Thus, it is the developers' responsibility to fix manually lint issues or run this task and validate the result.
To fix automatically Ktlint issues, you can execute ./gradlew ktlintFormat command in the terminal.
detekt is another plugin with a highly customisable rule set that we use to detect code smells in our code base.
Is a similar fashion as ktlint, detekt can be run with the command: ./gradlew detekt
These plugins can also be run locally with the script ./scripts/code-quality.sh from the project root. This command runs ktLintCheck, lint and detekt.
This section contains thing you should consider before submitting a pull request and what documentation is needed in the pull request in terms of testing, traceability etc.
android-skapa repository on GitHub.documentation folder.cd android-skapa/documentation/; git submodule init; git submodule updateIt is always best to discuss your plans beforehand, to ensure that your contribution is in line with our goals.
main). This branch should reference an issue number. Eg. feature/issue-7234 or bugfix/issue-4325.main and describe your contribution. Use the PR template provided and follow the steps. Provide links to discussions, Figma, Jira etc. where applicable. Changes affecting UI, please provide before/after screenshots.skip-changelog label../scripts/code-quality.sh from the project root before pushing your changes. This command runs ktLintCheck, lint and detekt.Thank you for your contributions!