diff --git a/docs/demo.md b/docs/demo.md index b82f11ee5..b28c08119 100644 --- a/docs/demo.md +++ b/docs/demo.md @@ -4,13 +4,68 @@ title: Demo sidebar_position: 3 --- -# Demo application +# Demo Application -The Mobile UI library includes a demo application to showcase all the components. This application can be used to see the components on action. +The Mobile UI library includes a **demo application** that showcases all the components available in the library. This application allows you to see the components in action and understand how they can be integrated into your projects. ![](resources/showcase.png) -Each release of the Mobile UI has artifacts for some of the targets. -These artifacts can be found at the end of each [Release page](https://github.com/dhis2/dhis2-mobile-ui/releases) on Github, on the Assets section. +## Downloading the Demo Application + +Each release of the Mobile UI library provides artifacts for various targets, including Android and desktop platforms. You can download the demo application from the **Assets** section at the bottom of each [release page](https://github.com/dhis2/dhis2-mobile-ui/releases) on GitHub. ![](resources/assets.png) + +### Steps to Download: + +1. **Visit the Releases Page**: Go to the [Mobile UI releases page](https://github.com/dhis2/dhis2-mobile-ui/releases) on GitHub. +2. **Select a Release**: Choose the release version you are interested in. +3. **Scroll to Assets**: At the bottom of the release notes, find the **Assets** section. +4. **Download the Artifact**: Click on the appropriate file for your platform: + - **Android**: Download the `Android.APK.zip` file. + - **Desktop (Windows)**: Download the `Desktop.jar.-.Windows.zip` file. + +## Installing the Demo Application + +### On Android: + +1. **Unzip the APK**: Unzip the `.zip` file to extract the `.apk` file inside. +2. **Transfer the APK**: Move the downloaded `.apk` file to your Android device if you downloaded it on another device. +3. **Enable Unknown Sources**: On your device, go to **Settings > Security**, and enable **Unknown Sources** to allow installations outside of the Google Play Store. +4. **Install the APK**: + - Open a file manager app and navigate to the `.apk` file. + - Tap the file to begin the installation process. + - Follow the on-screen instructions to complete the installation. + +### On Desktop: + +1. **Ensure Java is Installed**: + + - The demo application requires the Java Runtime Environment (JRE) to run. + - Download and install Java from the [official website](https://www.java.com/en/download/) if you haven't already. + +2. **Extract the ZIP File**: + + - Locate the downloaded `.zip` file. + - Right-click and select **Extract All**, or use your preferred extraction tool to unzip the contents. + +3. **Run the JAR File**: + + - Open the extracted folder to find the `.jar` file. + - **Double-Click Method**: + - Simply double-click the `.jar` file to launch the application. + - **Command Line Method**: + - Open a terminal or command prompt. + - Navigate to the directory containing the `.jar` file. + - Run the command: + ``` + java -jar your-demo-application.jar + ``` + + **Note**: If double-clicking the `.jar` file doesn't work, ensure that the file association for `.jar` files is correctly set to the Java Runtime Environment. + +## Using the Demo Application + +1. **Launch the App**: Open the demo application on your device. +2. **Explore Components**: Browse through the various components showcased in the app. +3. **Interactive Examples**: Interact with the components to see how they behave and respond. diff --git a/docs/design-system.md b/docs/design-system.md index 2210a75f1..e57c94dca 100644 --- a/docs/design-system.md +++ b/docs/design-system.md @@ -4,7 +4,63 @@ title: Design system sidebar_position: 4 --- -# Design system +# Design System -**DHIS2 Mobile UI library** is based in -the [DHIS2 Mobile Design System Figma library](https://www.figma.com/file/eRk6bt0B8BJlTO9PZXirHN/DHIS2-Mobile-Design-System). +The **DHIS2 Mobile UI Library** is built upon the [DHIS2 Mobile Design System Figma library](https://www.figma.com/file/eRk6bt0B8BJlTO9PZXirHN/DHIS2-Mobile-Design-System). This design system offers a comprehensive set of guidelines, components, and best practices to ensure consistency and enhance user experience across all DHIS2 mobile applications. + +![](resources/design-system.png) + +--- + +## Overview + +The design system encompasses a wide array of elements that contribute to a cohesive and intuitive user interface. Below is an organized list of the key components and design principles included in the system: + +### Foundations + +1. **Color**: A curated palette of neutral colors used consistently throughout the UI to convey meaning and improve usability. +2. **Elevation**: Guidelines for applying shadows and depth effects to create a visual hierarchy and indicate interactivity. +3. **Icons**: A standardized set of icons representing common actions, objects, and statuses to enhance recognition and reduce cognitive load. +4. **Typography**: Consistent font styles and text hierarchies for headings, body text, and captions to improve readability and accessibility. +5. **Shape**: Principles for using shapes, such as rounded corners and specific aspect ratios, to maintain a consistent look and feel. + +### Components + +7. **Badges**: Small indicators that display numerical values or statuses, often attached to icons or avatars. +8. **Bottom Sheets**: Modal surfaces that slide up from the bottom of the screen to present supplementary content or actions without navigating away. +9. **Buttons**: Interactive elements that trigger actions, available in various styles like text, outlined, and contained buttons. +10. **Checkboxes**: Controls that allow users to select one or multiple options from a list, indicating selection with a checkmark. +11. **Chips**: Compact elements representing inputs, attributes, or actions, often used for filters or selections. +12. **Filter Bar** (WIP): A component that enables users to refine content displayed on the screen based on specific criteria. +13. **Forms**: Structured layouts for data entry, including input fields, dropdowns, and validation messages. They allow easily capture data for all the data entry types in the DHIS2 world. +14. **Indicators**: Used to provide specific information like feedback or program indicators. +15. **Info Bar**: A horizontal component that displays brief messages, alerts, or notifications to the user. +16. **Navigation Bar**: A bar located at the bottom of the screen for primary navigation between app sections. +17. **Progress Indicators**: Linear and circular indicators that show the progress of a task or process. +18. **Radio Buttons**: Controls that allow users to select a single option from a set, displaying the selection with a filled circle. +19. **Lists**: Organized collections of items, and cards to display text, images, or interactive elements, ready for DHIS2 objects. +20. **Menu**: A list of options or actions presented contextually or via a dedicated button, often used for secondary navigation. +21. **Search Bar**: An input field where users can enter queries to search and filter content within the app. +22. **Section Title (WIP)**: Headers that introduce and label different sections or groupings of content for better organization. +23. **Sections**: Divisions within a page or screen that group related content or functionality together. +24. **Snackbar**: Temporary messages that appear at the bottom of the screen to provide brief feedback about an operation. +25. **Switches**: Toggles that allow users to turn options or settings on or off, indicating the current state immediately. +26. **Tags**: Labels used to categorize, organize, or filter content, displayed as small, rounded rectangles. +27. **Top Bar**: The header area at the top of the screen, usually containing the app title, navigation controls, and action items. + +--- + +## Getting Started + +To incorporate the DHIS2 Mobile Design System into your project: + +1. **Explore the Figma Library**: Familiarize yourself with the available components and styles by accessing the [Figma library](https://www.figma.com/file/eRk6bt0B8BJlTO9PZXirHN/DHIS2-Mobile-Design-System). +2. **Follow the Guidelines**: Apply the design principles and component guidelines to ensure a consistent and user-friendly interface. +3. **Maintain Accessibility**: Ensure all design elements meet accessibility standards for color contrast, font sizes, and interactive elements. +4. **Collaborate and Contribute**: Share feedback, suggest improvements, or contribute new components to help evolve the design system. + +--- + +For more information or feedback, please visit the [DHIS2 Community of Practice](https://community.dhis2.org/c/development/10). + +--- \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index 2b6e2b961..139b5a15d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -28,3 +28,7 @@ Multiplatform library seamlessly integrates with Android Studio and the Android **DHIS2 Mobile UI library** also supports desktop applications. When targeting desktop, you use a similar set of Compose APIs, but with desktop-specific configuration. It is designed to work exclusively with Kotlin Multiplatform (KMP) projects. + +## Feedback and Contributions + +We welcome feedback to improve the Mobile UI library and its showcase application. Feel free to [open issues](https://dhis2.atlassian.net/jira/software/c/projects/ANDROAPP/boards/113?quickFilter=730) on Jira. diff --git a/docs/resources/assets.png b/docs/resources/assets.png index 82b02a857..16789f6d7 100644 Binary files a/docs/resources/assets.png and b/docs/resources/assets.png differ diff --git a/docs/resources/design-system.png b/docs/resources/design-system.png new file mode 100644 index 000000000..8071d46a9 Binary files /dev/null and b/docs/resources/design-system.png differ diff --git a/docs/resources/showcase.png b/docs/resources/showcase.png index c0a3ee0da..75a2a82bc 100644 Binary files a/docs/resources/showcase.png and b/docs/resources/showcase.png differ