From 483222ba9541c973dfb9cb676c58012aa8bd589c Mon Sep 17 00:00:00 2001 From: Falah Zaidan Date: Tue, 10 Mar 2026 12:26:55 +0000 Subject: [PATCH 1/5] add file and link to it from the android README.md --- android/README.md | 5 +- android/docs/adding_source_components.md | 88 ++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 android/docs/adding_source_components.md diff --git a/android/README.md b/android/README.md index 769113327..4e77b7bee 100644 --- a/android/README.md +++ b/android/README.md @@ -41,6 +41,9 @@ The design presets are available name spaced under the `com.gu.Source` object, e **[Full API documentation is available here.](https://guardian.github.io/source-apps/android/docs/index.html)** +## Contributing +If you want to add new components to the Source library, please follow the guide in [Adding Source components](https://github.com/guardian/source-apps/blob/main/android/docs/adding_source_components.md). + --- ## Presets @@ -193,7 +196,7 @@ AlertBanner( google() } ``` - + ### Other notes 1. We use the `com.gu` package name and group id so we can use the Guardian's Sonatype infra for signing and publishing the library. See [this comment](https://github.com/guardian/source-android/pull/10/files?w=1#r1567071142) for reference. diff --git a/android/docs/adding_source_components.md b/android/docs/adding_source_components.md new file mode 100644 index 000000000..8918c0b72 --- /dev/null +++ b/android/docs/adding_source_components.md @@ -0,0 +1,88 @@ +# Adding Source Components + +Developers may wish to add components to our design system for use throughout the app. We have a separate repository for this called `source-apps`, which contains the Android and iOS components from a core library defined in Figma. The process to add components is outlined there, but is also here for reference. + +## Outline + +### 1. Verify Design Source of Truth + +As a developer, you should refer to the apps library Figma file which contains all of our components here: [Apps library](https://www.figma.com/design/kSmjgtoTWiG8N7HXxFoGEE/%E2%97%90-Apps-library?node-id=103-89&p=f&t=b9BxsPXbamFK9Zkw-0) +We also have a Core library that defines core components: [Figma Core Library](https://www.figma.com/design/b2qv2OMLoNCYnP01ipfrP7/%E2%97%88-Core-library?node-id=4229-96590&t=Yx6Rt423B9TxRRqz-0) + +### 2. Familiarize yourself with the source-apps repository structure + +The `source-apps` repository contains the Android and iOS components. The Android source project is in the `android` module. +In the `source` module, note the folders components, foundation and daynight. + - foundation contains icons (for icons), palette (for colours) and typography (for fonts and text styles). + - components contains the UI components that we can use in our apps (from the Figma apps library). + - daynight contains our `AppColourMode` wrapper for dark mode, which composable heirarchies should be wrapped in to enable dark mode support. + +### 2. Code implementation + +**Overview** +To implement a new component from the Figma Apps Library or core library, there are three steps + 1) Create the component (composable, preview and snapshot test) + 2) Add it to the sample (nav graph) + 3) Create or update the README and link from root README + +Note: all PRs that make changes to system design components should be reviewed by a member of the design system team (in the PR review process or directly). + +Once the component is implemented in the source library, you can do a preview release and use it in the android-news-app or feast apps. See [Here](https://github.com/guardian/source-apps/blob/main/android/RELEASING.md#preview-releases) +When the component is ready for release, you can do a production release as described [Here](https://github.com/guardian/source-apps/blob/main/android/RELEASING.md#production-release) + +*Example Implementation steps* + +- Checkout a new branch in the `source-apps` repository. +- Create a new Composable component in the source module, in the `components` folder: + + ```kotlin + @Composable + fun MyNewComponent(text: String) { + // ...implementation + } + ``` + +- Create a preview for it in the sample module, in the `previews` directory: + + ```kotlin + @Composable + fun MyNewComponentPreview(onBack: () -> Unit) { + MyNewComponent(text = "Hello, World!") + } + ``` + +- Add a snapshot test for the component (in a mirroring directory in the test directory): + + ```kotlin + @Test + fun newComponent() { + paparazzi.snapshot { + NewComponentPreview() + } + } + ``` + +- Add a serializable destination for it in `Destination.kt`: + + ```kotlin + @Serializable + object NewComponentPreview : Destination + ``` + +- Add an entry in `MainActivity` (this is how we are able to navigate to the component preview from the home screen): + + ```kotlin + entry(Destination.NewComponentPreview) { + NewComponentPreview(navigator::popBackStack) + } + ``` + +- Add a `SourceButton` to `Home` to add a button to navigate to the component when clicked: + + ```kotlin + SourceButton( + text = "Text buttons", + priority = SourceButton.Priority.TertiaryOnWhite, + onClick = { navigate(Destination.NewComponentPreview) }, + ) + ``` \ No newline at end of file From 0931d3a9165f69c3d0b730e95228346eb30e0725 Mon Sep 17 00:00:00 2001 From: Falah Zaidan Date: Tue, 10 Mar 2026 12:29:12 +0000 Subject: [PATCH 2/5] make title bold --- android/docs/adding_source_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/android/docs/adding_source_components.md b/android/docs/adding_source_components.md index 8918c0b72..f920c2f5b 100644 --- a/android/docs/adding_source_components.md +++ b/android/docs/adding_source_components.md @@ -30,7 +30,7 @@ Note: all PRs that make changes to system design components should be reviewed b Once the component is implemented in the source library, you can do a preview release and use it in the android-news-app or feast apps. See [Here](https://github.com/guardian/source-apps/blob/main/android/RELEASING.md#preview-releases) When the component is ready for release, you can do a production release as described [Here](https://github.com/guardian/source-apps/blob/main/android/RELEASING.md#production-release) -*Example Implementation steps* +**Example Implementation steps** - Checkout a new branch in the `source-apps` repository. - Create a new Composable component in the source module, in the `components` folder: From d8f70634143486063757efefb7a9fd3202126faa Mon Sep 17 00:00:00 2001 From: Falah Zaidan Date: Tue, 10 Mar 2026 12:30:55 +0000 Subject: [PATCH 3/5] add space --- android/docs/adding_source_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/android/docs/adding_source_components.md b/android/docs/adding_source_components.md index f920c2f5b..5f7fae23f 100644 --- a/android/docs/adding_source_components.md +++ b/android/docs/adding_source_components.md @@ -20,6 +20,7 @@ In the `source` module, note the folders components, foundation and daynight. ### 2. Code implementation **Overview** + To implement a new component from the Figma Apps Library or core library, there are three steps 1) Create the component (composable, preview and snapshot test) 2) Add it to the sample (nav graph) From 41a75d08c75ea3d68ae6583303b13bf3bd06f6a5 Mon Sep 17 00:00:00 2001 From: Falah Zaidan Date: Tue, 17 Mar 2026 18:10:21 +0000 Subject: [PATCH 4/5] PR amendments/formatting --- android/docs/adding_source_components.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/android/docs/adding_source_components.md b/android/docs/adding_source_components.md index 5f7fae23f..ef9716016 100644 --- a/android/docs/adding_source_components.md +++ b/android/docs/adding_source_components.md @@ -1,15 +1,15 @@ # Adding Source Components -Developers may wish to add components to our design system for use throughout the app. We have a separate repository for this called `source-apps`, which contains the Android and iOS components from a core library defined in Figma. The process to add components is outlined there, but is also here for reference. +Developers may wish to add components to our design system for use throughout the app. This repository, `source-apps`, contains the Android and iOS components derived from our core libraries defined in Figma. The process to add components to these modules is outlined below for reference. ## Outline -### 1. Verify Design Source of Truth +### Verify Design Source of Truth As a developer, you should refer to the apps library Figma file which contains all of our components here: [Apps library](https://www.figma.com/design/kSmjgtoTWiG8N7HXxFoGEE/%E2%97%90-Apps-library?node-id=103-89&p=f&t=b9BxsPXbamFK9Zkw-0) We also have a Core library that defines core components: [Figma Core Library](https://www.figma.com/design/b2qv2OMLoNCYnP01ipfrP7/%E2%97%88-Core-library?node-id=4229-96590&t=Yx6Rt423B9TxRRqz-0) -### 2. Familiarize yourself with the source-apps repository structure +### Familiarize yourself with the source-apps repository structure The `source-apps` repository contains the Android and iOS components. The Android source project is in the `android` module. In the `source` module, note the folders components, foundation and daynight. @@ -17,7 +17,7 @@ In the `source` module, note the folders components, foundation and daynight. - components contains the UI components that we can use in our apps (from the Figma apps library). - daynight contains our `AppColourMode` wrapper for dark mode, which composable heirarchies should be wrapped in to enable dark mode support. -### 2. Code implementation +### Code implementation **Overview** @@ -58,7 +58,7 @@ When the component is ready for release, you can do a production release as desc @Test fun newComponent() { paparazzi.snapshot { - NewComponentPreview() + MyNewComponentPreview() } } ``` @@ -74,7 +74,7 @@ When the component is ready for release, you can do a production release as desc ```kotlin entry(Destination.NewComponentPreview) { - NewComponentPreview(navigator::popBackStack) + MyNewComponentPreview(navigator::popBackStack) } ``` From 5750bdcd6efe1ea1abe93c0353748b6ddaab2ec3 Mon Sep 17 00:00:00 2001 From: Falah Zaidan Date: Tue, 17 Mar 2026 18:12:11 +0000 Subject: [PATCH 5/5] use a relative path to the android source components docs from the android README --- android/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/android/README.md b/android/README.md index 4e77b7bee..dde89b975 100644 --- a/android/README.md +++ b/android/README.md @@ -42,7 +42,7 @@ The design presets are available name spaced under the `com.gu.Source` object, e **[Full API documentation is available here.](https://guardian.github.io/source-apps/android/docs/index.html)** ## Contributing -If you want to add new components to the Source library, please follow the guide in [Adding Source components](https://github.com/guardian/source-apps/blob/main/android/docs/adding_source_components.md). +If you want to add new components to the Source library, please follow the guide in [Adding Source components](docs/adding_source_components.md). ---