Conversation
Falah-Zaidan
added
the
maintenance
There was a problem hiding this comment.
Pull request overview
Adds Android-facing contribution documentation for adding new design-system components, and links it from the Android README.
Changes:
- Add a new guide:
android/docs/adding_source_components.mdwith step-by-step component addition flow. - Add a “Contributing” section to
android/README.mdlinking to the new guide.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| android/docs/adding_source_components.md | New documentation describing the process to add Source components. |
| android/README.md | Adds a Contributing link pointing to the new documentation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| - 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 |
There was a problem hiding this comment.
These list items are indented by 4 spaces, which renders as a code block in Markdown rather than a bulleted list. Remove the extra indentation (or use a proper nested list) so the repository structure renders correctly.
| - 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 | |
| - 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 |
| 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. |
There was a problem hiding this comment.
Typo: “heirarchies” should be “hierarchies”.
| - daynight contains our `AppColourMode` wrapper for dark mode, which composable heirarchies should be wrapped in to enable dark mode support. | |
| - daynight contains our `AppColourMode` wrapper for dark mode, which composable hierarchies should be wrapped in to enable dark mode support. |
| ```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 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The example code is internally inconsistent: it defines MyNewComponentPreview(onBack: () -> Unit) but later snapshots/calls NewComponentPreview() and also introduces a Destination object with the same name. Please make the example names consistent and ensure the preview/test snippets would compile if copied.
| **[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). |
There was a problem hiding this comment.
This link hardcodes blob/main, which breaks for forks/branches and when viewing the README locally. Prefer a relative link to docs/adding_source_components.md (similar to the other relative links in this README).
| 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). |
| @@ -0,0 +1,89 @@ | |||
| # 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. | |||
There was a problem hiding this comment.
This doc says there is a “separate repository” called source-apps, but this file lives inside the source-apps repo. Please reword to avoid implying contributors should look elsewhere, and describe the modules within this repository instead.
| 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. |
| - 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 |
There was a problem hiding this comment.
The section numbering is inconsistent: this is the second “### 2.” heading under “Outline”. Please renumber this section (and any subsequent references) to keep the outline unambiguous.
| ### 2. Code implementation | |
| ### 3. Code implementation |
Description
This PR adds documentation on how to contribute to the repository (android)