Code Conventions

This page contains a compilation of code conventions we try to maintain to keep a good code structure in our android modules. As a start the CONTRIBUTING needs to be followed.

Skapa public modules

Component and file naming

• Use Skapa names for components. Both the .kt file and public Composable functions should be named the same way. The component name should be the same across all platforms. The names can be found on Skapa hub.
• If still necessary to diverge the naming, it’s best to document the reason. The decision should be taken together with all stakeholders.
• Note: There are some exceptions to naming components, eg. SkapaImage. This is however not a complete component in the android library but merely a guide on how to implement one. This is because of its requirement of an external image fetching/rendering/caching library.

Code structure

Within each component file we strive to have the distribution as follows.

1. public components functions. Eg. PriceModule()
2. private/internal functions that builds up the component such as implementations of different variants or orientations. Eg. private PriceModuleRegular() and private PriceModuleList()
3. public enum classes/sealed classes used for variants. Eg. sealed class PriceModuleVariant
4. Additional private/internal data/enum/sealed classes and helper functions.
5. private object *Props. The props object prefixed with the component name eg. PriceModuleProps usually contains sizing, padding, color tokens and other static values needed. Additionally functions used for styling different variants also live here. Eg. PriceModuleProps.style().
6. At the bottom of the file we place all the @Preview() functions to render the component in the Design tab of Android Studio. These functions should generally be private.
7. A component should be paired with a <componentName>Sample.kt file with a sample explaining how to use the component. The sample file should be referred in the component documentation as @sample net.ikea.skapa.ui.samples.<ComponentSampleFunction>.
8. Every component should have an entry in the Demo app, following the structure listed on Demo app.

Components files should be placed in the net.ikea.skapa.ui.components package for design module. When adding new components they should start their journey with ExperimentalSkapaApi annotation added to all public functions. Read more in Annotations.

Apart from the Skapa components there are additional source code files that complements our offering.

Component sample files in net.ikea.skapa.ui.samples that showcases usage examples for each component.

Util files in the net.ikea.skapa.ui.util package and the net.ikea.skapa.ui.Util.kt file outside of that package. These are used as helper files and are either internal or public accompanied by the @InternalSkapaApi annotation, see Annotations.

Annotations

This project also uses similar annotations as Compose Libraries use such as ExperimentalMaterialApi, ExperimentalComposeUiApi, ExperimentalFoundationApi where want an explicit OptIn to be able to use those functions and their limitations.

• ExperimentalSkapaApi is used for work-in-progress components (and other functions) in all our packages (both stable packages and experimental package). Functions using this annotation and subject to change without notice.
• InternalSkapaApi is used to reuse functions between our own Skapa packages, projects outside of Skapa are allowed to use them but we do not guarantee their longevity.

Test module - design-test

Both Unit and Snapshots tests are located in the design-test module with SkapaTestHelper as the entry point.

• Package net.ikea.skapa.ui.components has the test wrapper for the components.
• Package net.ikea.skapa.ui.snapshots implementations of the Snapshot tests.
• Package net.ikea.skapa.ui.unittests implementations of the Unit tests.

When adding tests, especially snapshot tests, try to test features combinations and avoid adding tests that overlap with other tests. Eg. try to combine testing several features in one test to reduce the total test suite duration. Make sure to run tests in both Light and Dark mode. Check this file to get a better understanding how screenshot are run and updated /scripts/run-screenshot-test-light-dark.sh. Also make sure to run the tests on compatible device /.github/workflows/test-pipeline.yml due to rendering differences with other device combinations.

Demo app

Code conventions are maybe less important in the app code since it is not being exposed outside the team but we still try to maintain a good structure.

The code of the Demo app is split into a few different sections with main screen entrypoint being net.ikea.skapa.example.navigation.SkapaScreen.kt

• Foundation screens - showcases design tokens from foundation, icons, fonts modules.
• Components screens - showcases components from the design module
• Home as XML screen is used to present the main screen with AndroidView design tokens instead of Compose.
• Debug screen needs to be enabled from Settings to be visible. This screen should contain all Skapa components in one screen.

Component screens

The entrypoint for these screens is net.ikea.skapa.example.fragments.components.ComponentsScreen.kt. All components are ordered with the same grouping as in Skapa hub.

• Anatomy
• Variants
• Sizes
• Other features and examples
• RTL
• Demos of each component usually with real use cases and in combinations with other components