diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml new file mode 100644 index 0000000..64429a5 --- /dev/null +++ b/.github/workflows/linter.yml @@ -0,0 +1,53 @@ +--- +name: Linting + +on: # yamllint disable-line rule:truthy + pull_request: + branches: + - develop + - main + +jobs: + build: + name: Linting + runs-on: ubuntu-latest + + permissions: + contents: read + packages: read + statuses: write + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Super-linter + uses: super-linter/super-linter@v7.1.0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + LINTER_RULES_PATH: / + MARKDOWN_CONFIG_FILE: '.markdownlint.json' + VALIDATE_CHECKOV: false + VALIDATE_JSCPD: false + VALIDATE_KOTLIN: false + VALIDATE_JSON_PRETTIER: false + VALIDATE_MARKDOWN_PRETTIER: false + VALIDATE_YAML_PRETTIER: false + + - name: Set up JDK + uses: actions/setup-java@v4.4.0 + with: + distribution: zulu + java-version: 21 + cache: gradle + - run: ./gradlew lint + - name: Lint Foundation module + uses: yutailang0119/action-android-lint@v4 + with: + report-path: foundation/build/reports/*.xml + - name: Lint Components module + uses: yutailang0119/action-android-lint@v4 + with: + report-path: components/build/reports/*.xml diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..0b56c18 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "no-duplicate-heading": { + "siblings_only": true + } +} \ No newline at end of file diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md index f4d6f90..22e948f 100644 --- a/CODE-OF-CONDUCT.md +++ b/CODE-OF-CONDUCT.md @@ -17,23 +17,23 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -- Focusing on what is best not just for us as individuals, but for the overall +* Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -- The use of sexualized language or imagery, and sexual attention or advances of +* The use of sexualized language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email address, +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a +* Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities @@ -126,7 +126,11 @@ For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org + [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html + [Mozilla CoC]: https://github.com/mozilla/diversity + [FAQ]: https://www.contributor-covenant.org/faq + [translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66f2f56..0d771ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,10 @@ # Contributing to Android Jetpack Compose Library -Thank you for considering contributing to our Android Jetpack Compose Library project. Your contributions help make this project better for everyone. +Thank you for considering contributing to our Android Jetpack Compose Library +project. Your contributions help make this project better for everyone. ## Table of Contents + 1. [Code of Conduct](#code-of-conduct) 2. [How to Contribute](#how-to-contribute) 3. [Reporting Issues](#reporting-issues) @@ -15,138 +17,178 @@ Thank you for considering contributing to our Android Jetpack Compose Library pr 10. [Creating ADRs](#creating-adrs) ## Code of Conduct -This project adheres to a [Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report any unacceptable behavior to [db-ux-designsystem@deutschebahn.com](mailto:db-ux-designsystem@deutschebahn.com). + +This project adheres to a [Code of Conduct](./CODE_OF_CONDUCT.md). By +participating, you are expected to uphold this code. Please report any +unacceptable behavior +to [db-ux-designsystem@deutschebahn.com](mailto:db-ux-designsystem@deutschebahn.com). ## How to Contribute + ### Reporting Issues -If you find a bug or have a feature request, please open an issue in the [issue tracker](https://github.com/your-repo/compose-library/issues). Be sure to include: -- A descriptive title. -- A detailed explanation of the issue or request. -- Steps to reproduce the issue (if applicable). -- Any relevant screenshots or logs. + +If you find a bug or have a feature request, please open an issue in +the [issue tracker](https://github.com/your-repo/compose-library/issues). Be +sure to include: + +* A descriptive title. +* A detailed explanation of the issue or request. +* Steps to reproduce the issue (if applicable). +* Any relevant screenshots or logs. ### Pull Requests -We welcome your pull requests! To ensure a smooth process, please follow these steps: + +We welcome your pull requests! To ensure a smooth process, please follow these +steps: 1. **Fork the Repository:** - - Create your own copy of the repository by clicking the `Fork` button on GitHub. + * Create your own copy of the repository by clicking the `Fork` button on + GitHub. 2. **Clone the Forked Repository:** - - `git clone https://github.com/your-username/compose-library.git` + * `git clone https://github.com/your-username/compose-library.git` 3. **Create a New Branch:** - - `git checkout -b feature/your-feature-name` + * `git checkout -b feature/your-feature-name` 4. **Make Your Changes:** - - Develop your feature or fix on the new branch. Ensure that you follow the [coding standards](#coding-standards). + * Develop your feature or fix on the new branch. Ensure that you follow + the [coding standards](#coding-standards). 5. **Commit Your Changes:** - - Use clear and concise commit messages. - - `git commit -m "Add a concise and descriptive commit message"` + * Use clear and concise commit messages. + * `git commit -m "Add a concise and descriptive commit message"` 6. **Push Your Changes:** - - `git push origin feature/your-feature-name` + * `git push origin feature/your-feature-name` 7. **Submit a Pull Request:** - - Go to the original repository and click `New pull request`. - - Provide a detailed description of your changes. - - Link to any relevant issues or ADRs if applicable. + * Go to the original repository and click `New pull request`. + * Provide a detailed description of your changes. + * Link to any relevant issues or ADRs if applicable. ## Development Setup + Follow these steps to set up your development environment: 1. **Clone the Repository:** - - `git clone https://github.com/your-repo/compose-library.git` + * `git clone https://github.com/your-repo/compose-library.git` 2. **Navigate to the Project Directory:** - - `cd compose-library` + * `cd compose-library` 3. **Open the Project in Android Studio:** - - Open the project folder in Android Studio: - - File > Open... and select the cloned repository folder. + * Open the project folder in Android Studio: + * File > Open... and select the cloned repository folder. 4. **Sync Project with Gradle Files:** - - Android Studio should automatically resolve and fetch dependencies when you open the project. + * Android Studio should automatically resolve and fetch dependencies when + you open the project. 5. **Run Tests:** - - Ensure all tests pass by selecting `Run > Run...` and choosing the test configuration. + * Ensure all tests pass by selecting `Run > Run...` and choosing the test + configuration. ## Coding Standards + Please adhere to the following coding standards to ensure consistency: -- Follow the Kotlin Coding Conventions. -- Follow Markdown and YAML style guides: - - Markdown: Follow the [Markdown Guide](https://www.markdownguide.org/basic-syntax/). - - YAML: Adhere to typical YAML syntax and style rules. +* Follow the Kotlin Coding Conventions. +* Follow Markdown and YAML style guides: + * Markdown: Follow + the [Markdown Guide](https://www.markdownguide.org/basic-syntax/). + * YAML: Adhere to typical YAML syntax and style rules. ## Code Quality -To maintain high code quality, we use the following linters and tools in our CI/CD pipeline. Please ensure your code adheres to these standards before submitting a pull request: + +To maintain high code quality, we use the following linters and tools in our +CI/CD pipeline. Please ensure your code adheres to these standards before +submitting a pull request: 1. **Android Lint:** - - Android Lint checks the code for potential bugs, stylistic errors, and other issues. - - You can run Android Lint manually using the following command: - ```sh - ./gradlew lint - ``` + * Android Lint checks the code for potential bugs, stylistic errors, and + other issues. + * You can run Android Lint manually using the following command: + + ```sh + ./gradlew lint + ``` 2. **Markdown Lint:** - - Linting for Markdown can be done using `markdownlint-cli`: - ```sh - npm install -g markdownlint-cli - markdownlint '**/*.md' - ``` + * Linting for Markdown can be done using `markdownlint-cli`: + + ```sh + npm install -g markdownlint-cli + markdownlint '**/*.md' + ``` 3. **YAML Lint:** - - Linting for YAML files can be done using `yamllint`: - ```sh - brew install yamllint - yamllint . - ``` + * Linting for YAML files can be done using `yamllint`: + + ```sh + brew install yamllint + yamllint . + ``` ### CI/CD Integration -Our CI/CD pipeline will automatically run these linters on every pull request to ensure code quality. Here is a summary of the checks performed: -- **Android Lint:** Ensures Android code adheres to style and quality guidelines. -- **Markdown Lint:** Checks Markdown files for style and syntax correctness. -- **YAML Lint:** Checks YAML files for syntax errors and style issues. +Our CI/CD pipeline will automatically run these linters on every pull request to +ensure code quality. Here is a summary of the checks performed: + +* **Android Lint:** Ensures Android code adheres to style and quality + guidelines. +* **Markdown Lint:** Checks Markdown files for style and syntax correctness. +* **YAML Lint:** Checks YAML files for syntax errors and style issues. Make sure your code passes these checks before opening a pull request. ## Documentation + Good documentation helps others understand your code. Please: -- Update the `DEVELOPMENT.md` file if your changes affect the development process. -- Ensure your code is well-commented, especially for complex logic. -- Update or create relevant ADRs in the `docs/adr` directory. +* Update the `DEVELOPMENT.md` file if your changes affect the development + process. +* Ensure your code is well-commented, especially for complex logic. +* Update or create relevant ADRs in the `docs/adr` directory. ## Running Tests + To run the test suite: 1. **Open the Project in Android Studio:** - - Open the project folder in Android Studio. + * Open the project folder in Android Studio. 2. **Run Tests:** - - Run the test suite by selecting `Run > Run Tests` or by using the command: - ```sh - ./gradlew testDebugUnitTest - ./gradlew connectedAndroidTest - ``` + * Run the test suite by selecting `Run > Run Tests` or by using the command: + + ```sh + ./gradlew testDebugUnitTest + ./gradlew connectedAndroidTest + ``` Ensure that all tests pass before submitting your pull request. ## Creating ADRs -Architecture Decision Records (ADRs) document significant architectural decisions made during the project. When you need to record an architectural decision, follow these steps: + +Architecture Decision Records (ADRs) document significant architectural +decisions made during the project. When you need to record an architectural +decision, follow these steps: 1. **Create an ADR Document:** - - ADRs should be created in the `docs/adr` directory. - - Use the template provided in `docs/adr-xx-Template.md`. + * ADRs should be created in the `docs/adr` directory. + * Use the template provided in `docs/adr-xx-Template.md`. 2. **Document the Decision:** - - Follow the structure in the template. + * Follow the structure in the template. 3. **Review and Approval:** - - Submit the ADR for review by creating a pull request. - - The ADR must be approved by the Maintainers/Codeowners before it is merged. This ensures that all architectural decisions are aligned with the project's overall strategy. + * Submit the ADR for review by creating a pull request. + * The ADR must be approved by the Maintainers/Codeowners before it is + merged. This ensures that all architectural decisions are aligned with the + project's overall strategy. + +## Thank You -## Thank You! -Thank you for contributing to the Android Jetpack Compose Library project. Your efforts help improve the project for everyone. We appreciate your time and dedication! +Thank you for contributing to the Android Jetpack Compose Library project. Your +efforts help improve the project for everyone. We appreciate your time and +dedication! diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ca329bb..c1ff33c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,6 +1,7 @@ # Development Guide for Android Jetpack Compose Library ## Table of Contents + 1. [Introduction](#introduction) 2. [Project Overview](#project-overview) 3. [Architecture Overview](#architecture-overview) @@ -11,84 +12,116 @@ 8. [Getting Started](#getting-started) ## Introduction -Welcome to the development guide for the Android Jetpack Compose Library of DB UX Design System. This document outlines the development concepts and practices for this framework, helping new developers get up to speed and contribute efficiently. + +Welcome to the development guide for the Android Jetpack Compose Library of DB +UX Design System. This document outlines the development concepts and practices +for this framework, helping new developers get up to speed and contribute +efficiently. ## Project Overview + This SwiftUI-based UX Design System Framework aims to: -- Define design elements such as colors, typography, and spacing as tokens. -- Provide pre-built UI components like buttons, alerts, and chips. -The framework is designed to be user-friendly, leveraging Jetpack Compose for a modern and maintainable codebase. The project is offered as a Compose Library for easy integration. +* Define design elements such as colors, typography, and spacing as tokens. +* Provide pre-built UI components like buttons, alerts, and chips. + +The framework is designed to be user-friendly, leveraging Jetpack Compose for a +modern and maintainable codebase. The project is offered as a Compose Library +for easy integration. ## Architecture Overview -The architecture of this library follows the principles of modularity and separation of concerns. The key components include: -- **Foundation:** Central definition of design elements including colors, typography and spacing. -- **Components:** Essential UI components built with Jetpack Compose, such as buttons, alerts and chips. +The architecture of this library follows the principles of modularity and +separation of concerns. The key components include: + +* **Foundation:** Central definition of design elements including colors, + typography and spacing. +* **Components:** Essential UI components built with Jetpack Compose, such as + buttons, alerts and chips. ## ADR Reference -Significant architectural decisions are documented in Architecture Decision Records (ADRs). These records ensure transparency and consistency throughout the project. Developers are encouraged to document new decisions as ADRs to maintain project integrity. -- All ADRs are located in the `docs/adr` directory of the repository. -- [Refer to ADR Documentation](./docs/adr) +Significant architectural decisions are documented in Architecture Decision +Records (ADRs). These records ensure transparency and consistency throughout the +project. Developers are encouraged to document new decisions as ADRs to maintain +project integrity. + +* All ADRs are located in the `docs/adr` directory of the repository. +* [Refer to ADR Documentation](./docs/adr) ## Implementation Guidelines -To ensure high standards of code quality and consistency, adhere to the following guidelines: -1. **Code Structure:** - - Organize files by feature or module. - - Follow the Android API Design Guidelines and Kotlin coding conventions. +To ensure high standards of code quality and consistency, adhere to the +following guidelines: + +1. **Code Structure:** + * Organize files by feature or module. + * Follow the Android API Design Guidelines and Kotlin coding conventions. 2. **Components:** - - Build UI components using Jetpack Compose. - - Ensure components are reusable and customizable via modifiers. + * Build UI components using Jetpack Compose. + * Ensure components are reusable and customizable via modifiers. 3. **Design Tokens Usage:** - - Consistently apply design tokens (such as colors, typography, and spacing) across all components. + * Consistently apply design tokens (such as colors, typography, and spacing) + across all components. 4. **Documentation:** - - Document all public APIs thoroughly. - - Include inline comments for complex logic. + * Document all public APIs thoroughly. + * Include inline comments for complex logic. ## Code Quality + Maintaining high code quality is crucial. Follow these best practices: 1. **Code Reviews:** All code changes must undergo a rigorous review process. 2. **Unit Tests:** Write unit tests for all critical functionalities. 3. **Linting:** Use Android Lint to enforce a consistent code style. -4. **CI Pipeline:** Implement automated testing and linting for every pull request. +4. **CI Pipeline:** Implement automated testing and linting for every pull + request. ## Contribution Guidelines -We welcome contributions from the community! For details on how to contribute to this project, refer to the `CONTRIBUTING.md` file. It includes information on how to report issues, submit pull requests, and follow coding standards. + +We welcome contributions from the community! For details on how to contribute to +this project, refer to the `CONTRIBUTING.md` file. It includes information on +how to report issues, submit pull requests, and follow coding standards. ## Getting Started + 1. **Prerequisites:** - - Java Development Kit (JDK) 17 or newer - - Android Studio (latest stable version) + * Java Development Kit (JDK) 17 or newer + * Android Studio (latest stable version) 2. **Clone the Repository:** + ```sh git clone https://github.com/your-repo/compose-library.git ``` 3. **Open the Project in Android Studio:** - - Open Android Studio. - - Select `File > Open...`. - - Navigate to the cloned repository and click `Open`. + * Open Android Studio. + * Select `File > Open...`. + * Navigate to the cloned repository and click `Open`. 4. **Sync Project with Gradle Files:** - - Android Studio should automatically sync and resolve dependencies. If not, go to `File > Sync Project with Gradle Files`. + * Android Studio should automatically sync and resolve dependencies. If not, + go to `File > Sync Project with Gradle Files`. 5. **Build the Project:** + ```sh ./gradlew assembleDebug ``` 6. **Run Tests:** - - Unit Tests: - ```sh - ./gradlew testDebugUnitTest - ``` - - UI Tests: - ```sh - ./gradlew connectedAndroidTest - ``` - -Thank you for contributing to our project! Together, we can develop a robust and versatile DB UX Design System using Jetpack Compose. + * Unit Tests: + + ```sh + ./gradlew testDebugUnitTest + ``` + + * UI Tests: + + ```sh + ./gradlew connectedAndroidTest + ``` + +Thank you for contributing to our project! Together, we can develop a robust and +versatile DB UX Design System using Jetpack Compose. diff --git a/README.md b/README.md index f7e7d02..def612b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # DB UX Design System Compose Library -Welcome to the UX Design System Library project for Jetpack Compose! +[![Linting](https://github.com/db-ui/db-ux-design-system-android/actions/workflows/linter.yml/badge.svg)](https://github.com/db-ui/db-ux-design-system-android/actions/workflows/linter.yml) -For detailed development guidelines, please refer to our [DEVELOPMENT.md](./DEVELOPMENT.md) document. +Welcome to the UX Design System Library project for Jetpack Compose! +For detailed development guidelines, please refer to +our [DEVELOPMENT.md](./DEVELOPMENT.md) document. ## License -This project is licensed under [Apache-2.0](LICENSE), Copyright 2024 by DB Systel GmbH. +This project is licensed under [Apache-2.0](LICENSE), Copyright 2024 by DB +Systel GmbH. diff --git a/components/README.md b/components/README.md index f5a9b56..f90d7eb 100644 --- a/components/README.md +++ b/components/README.md @@ -1,4 +1,5 @@ # :components module + ## Dependency graph -![Dependency graph](../docs/images/dependencies/dep_graph_components.svg) \ No newline at end of file +![Dependency graph](../docs/images/dependencies/dep_graph_components.svg) diff --git a/docs/adr/adr-01-colors.md b/docs/adr/adr-01-colors.md index 4f73652..3be8d35 100644 --- a/docs/adr/adr-01-colors.md +++ b/docs/adr/adr-01-colors.md @@ -1,54 +1,84 @@ # ADR-01 - Integration of Color Tokens from Theme Builder ## Decision and justification -We will integrate color tokens exported by the `theme-builder` (https://github.com/db-ui/theme-builder) into our Compose library. These tokens will be defined as `Color` instances prefixed with the exported theme name and used in different color schemes through adaptive themes. + +We will integrate color tokens exported by +the [theme-builder](https://github.com/db-ui/theme-builder) into our Compose +library. These tokens will be defined as `Color` instances prefixed with the +exported theme name and used in different color schemes through adaptive themes. ## Problem description and context -We want to ensure that color definitions from the theme-builder are efficiently integrated into our Compose library. The color tokens should be adaptable to different color modes (e.g., light and dark mode). The structure for colors and themes should be easy to understand and maintain. + +We want to ensure that color definitions from the theme-builder are efficiently +integrated into our Compose library. The color tokens should be adaptable to +different color modes (e.g., light and dark mode). The structure for colors and +themes should be easy to understand and maintain. ## General conditions and decision criteria ### General conditions -- The color tokens must be easily imported from the theme-builder export. -- The naming and mapping of tokens to color schemes should be consistent and clear. -- The structure must be flexible enough to accommodate future changes or expansions. + +* The color tokens must be easily imported from the theme-builder export. +* The naming and mapping of tokens to color schemes should be consistent and + clear. +* The structure must be flexible enough to accommodate future changes or + expansions. ### Decision criteria -- **Clarity**: The integration of color tokens should be clear and understandable. -- **Consistency**: The naming and structure of color tokens and themes should be uniform. -- **Flexibility**: The structure should be easy to extend. -- **Performance**: The implementation should be performant and should not consume unnecessary resources. + +* **Clarity**: The integration of color tokens should be clear and + understandable. +* **Consistency**: The naming and structure of color tokens and themes should be + uniform. +* **Flexibility**: The structure should be easy to extend. +* **Performance**: The implementation should be performant and should not + consume unnecessary resources. ## Alternatives ### A - Direct definition of color tokens in code #### Evaluation -- **Pros:** Simple implementation without additional tools or dependencies. -- **Cons:** Less flexible for changes and not automatically synchronized with the `theme-builder`. + +* **Pros:** Simple implementation without additional tools or dependencies. +* **Cons:** Less flexible for changes and not automatically synchronized with + the `theme-builder`. ### B - Using the export from the `theme-builder` #### Evaluation -- **Pros:** Direct adoption of color tokens from the `theme-builder`, simple maintenance and synchronization. -- **Cons:** Dependency on the `theme-builder` and its export structure. + +* **Pros:** Direct adoption of color tokens from the `theme-builder`, simple + maintenance and synchronization. +* **Cons:** Dependency on the `theme-builder` and its export structure. ## Decision -We choose **Alternative B - Using the export from the `theme-builder`** to directly adopt the color tokens. This ensures simple maintenance and synchronization of color definitions. + +We choose **Alternative B - Using the export from the `theme-builder`** to +directly adopt the color tokens. This ensures simple maintenance and +synchronization of color definitions. ## Consequences -- **Positive:** Using the `theme-builder` export allows for consistent and easy updates of color tokens. The structure enables simple customization and expansion of themes. -- **Negative:** There is a dependency on the `theme-builder` and its export functions. -By implementing this approach, we ensure that our color tokens are clear, consistent and scalable, providing a solid foundation for the color schemes in our design system and facilitating seamless updates. +* **Positive:** Using the `theme-builder` export allows for consistent and easy + updates of color tokens. The structure enables simple customization and + expansion of themes. +* **Negative:** There is a dependency on the `theme-builder` and its export + functions. + +By implementing this approach, we ensure that our color tokens are clear, +consistent and scalable, providing a solid foundation for the color schemes in +our design system and facilitating seamless updates. ## Links -- [Theme-Builder GitHub Repository](https://github.com/db-ui/theme-builder) -- [Jetpack Compose Theming Documentation](https://developer.android.com/jetpack/compose/themes) + +* [Theme-Builder GitHub Repository](https://github.com/db-ui/theme-builder) +* [Jetpack Compose Theming Documentation](https://developer.android.com/jetpack/compose/themes) ## Sample Code 1. **Import Color Tokens:** + ```kotlin val DeutscheBahnColorMap = mapOf( "neutral0" to Color(0xff070709), @@ -62,6 +92,7 @@ By implementing this approach, we ensure that our color tokens are clear, consis ``` 2. **Define ColorScheme Using Color Tokens:** + ```kotlin class DSColorVariant private constructor( val bgBasicLevel1Default: Color, @@ -99,6 +130,7 @@ By implementing this approach, we ensure that our color tokens are clear, consis ``` 3. **Instantiate ColorScheme:** + ```kotlin val NeutralColorsDark = DSColorVariant.dark("neutral") val BrandColorsDark = DSColorVariant.dark("brand") diff --git a/docs/adr/adr-02-accessor.md b/docs/adr/adr-02-accessor.md index 837aff1..525a102 100644 --- a/docs/adr/adr-02-accessor.md +++ b/docs/adr/adr-02-accessor.md @@ -1,79 +1,119 @@ # ADR-02 - Accessor Strategy for Component Styling ## Decision and justification -We need to decide on an accessor strategy for styling components, such as adaptive color or density, throughout our Jetpack Compose library and the app-project. + +We need to decide on an accessor strategy for styling components, such as +adaptive color or density, throughout our Jetpack Compose library and the +app-project. ## Problem description and context -We require a flexible and consistent method to apply styling to our Compose components. The settings, adaptive color and density, must be adjustable and independently set. The structure for colors and themes should be easy to understand and maintain. Apply another density results in adaptive typography and dimensions, such as sizing, spacing and border. + +We require a flexible and consistent method to apply styling to our Compose +components. The settings, adaptive color and density, must be adjustable and +independently set. The structure for colors and themes should be easy to +understand and maintain. Apply another density results in adaptive typography +and dimensions, such as sizing, spacing and border. ## General conditions and decision criteria ### General conditions -- The styling approach must allow easy adjustment of color and density parameters. -- Each styling parameter should be set independently. -- The styling approach must cosider all adaptive tokens: color, typography and dimensions. -- Components should support adaptive identifier that use specific color schemes based on the current theme. -- The solution should balance performance, scalability, flexibility, and maintainability. + +* The styling approach must allow easy adjustment of color and density + parameters. +* Each styling parameter should be set independently. +* The styling approach must cosider all adaptive tokens: color, typography and + dimensions. +* Components should support adaptive identifier that use specific color schemes + based on the current theme. +* The solution should balance performance, scalability, flexibility, and + maintainability. ### Decision criteria -- **Performance:** Minimal performance overhead. -- **Scalability:** Capable of future extensions. -- **Maintainability:** Easy to maintain and understand. -- **Consistency:** Reliable and consistent application of styles. -- **Usability:** Simple for developers to use and integrate with existing Jetpack Compose components. + +* **Performance:** Minimal performance overhead. +* **Scalability:** Capable of future extensions. +* **Maintainability:** Easy to maintain and understand. +* **Consistency:** Reliable and consistent application of styles. +* **Usability:** Simple for developers to use and integrate with existing + Jetpack Compose components. ## Alternatives ### A - Hardcoded Styling in Components #### Evaluation -- **Performance:** High, no additional processing required. -- **Scalability:** Poor, difficult to extend. -- **Maintainability:** Low, hard to manage and update styles. -- **Consistency:** Low, prone to discrepancies. -- **Usability:** Low, not flexible for developers. + +* **Performance:** High, no additional processing required. +* **Scalability:** Poor, difficult to extend. +* **Maintainability:** Low, hard to manage and update styles. +* **Consistency:** Low, prone to discrepancies. +* **Usability:** Low, not flexible for developers. ### B - Centralized Style Accessors #### Evaluation -- **Performance:** Moderate, slight overhead for accessing centralized styles. -- **Scalability:** High, easy to extend with new styles. -- **Maintainability:** High, centralized management of styles. -- **Consistency:** High, uniform application of styles. -- **Usability:** High, provides a flexible and consistent styling interface for developers. -- **Inheritance:** Moderate, needs explicit handling of inheritance for adaptive flags. + +* **Performance:** Moderate, slight overhead for accessing centralized styles. +* **Scalability:** High, easy to extend with new styles. +* **Maintainability:** High, centralized management of styles. +* **Consistency:** High, uniform application of styles. +* **Usability:** High, provides a flexible and consistent styling interface for + developers. +* **Inheritance:** Moderate, needs explicit handling of inheritance for adaptive + flags. ### C - Dynamic Styling via Composition Local #### Evaluation -- **Performance:** Moderate, with minor overhead from Composition Local lookups. -- **Scalability:** High, easily extendable by adding more Composition Local providers. -- **Maintainability:** High, centralized management of styles with local overrides as needed. -- **Consistency:** High, ensures uniform styling with the flexibility of local overrides. -- **Usability:** High, provides a flexible and consistent interface for developers. -- **Inheritance:** High, naturally supports hierarchical inheritance and adaptive flags. + +* **Performance:** Moderate, with minor overhead from Composition Local lookups. +* **Scalability:** High, easily extendable by adding more Composition Local + providers. +* **Maintainability:** High, centralized management of styles with local + overrides as needed. +* **Consistency:** High, ensures uniform styling with the flexibility of local + overrides. +* **Usability:** High, provides a flexible and consistent interface for + developers. +* **Inheritance:** High, naturally supports hierarchical inheritance and + adaptive flags. ## Decision -We choose **Alternative C - Dynamic Styling via Composition Local**. This approach provides the best support for hierarchical inheritance and adaptive flags, ensuring consistent and flexible styling management. It leverages the Composition Local mechanism for efficient state management and propagation through the Compose tree. + +We choose **Alternative C - Dynamic Styling via Composition Local**. This +approach provides the best support for hierarchical inheritance and adaptive +flags, ensuring consistent and flexible styling management. It leverages the +Composition Local mechanism for efficient state management and propagation +through the Compose tree. ## Consequences -- **Positive:** Utilizes Composition Local to provide dynamic and inheritable styling. It simplifies the process of applying complex styling configurations and allows for easy updates and extensions. Ensures adaptive flags are consistently applied through the hierarchy. -- **Negative:** There could be minor performance overhead due to Composition Local lookups, but this is offset by the flexibility and maintainability benefits. + +* **Positive:** Utilizes Composition Local to provide dynamic and inheritable + styling. It simplifies the process of applying complex styling configurations + and allows for easy updates and extensions. Ensures adaptive flags are + consistently applied through the hierarchy. +* **Negative:** There could be minor performance overhead due to Composition + Local lookups, but this is offset by the flexibility and maintainability + benefits. ## Links -- [Theme-Builder GitHub Repository](https://github.com/db-ui/theme-builder) -- [Jetpack Compose Theming Documentation](https://developer.android.com/jetpack/compose/themes) -- [Composition Local Documentation](https://developer.android.com/jetpack/compose/compositionlocal) + +* [Theme-Builder GitHub Repository](https://github.com/db-ui/theme-builder) +* [Jetpack Compose Theming Documentation](https://developer.android.com/jetpack/compose/themes) +* [Composition Local Documentation](https://developer.android.com/jetpack/compose/compositionlocal) ## Sample Code 1. **Define Composition Local Providers:** + ```kotlin val LocalColors = staticCompositionLocalOf { getColorSchemeLight() } - val LocalActiveColor = staticCompositionLocalOf { getColorSchemeLight().neutral } + val LocalActiveColor = + staticCompositionLocalOf { getColorSchemeLight().neutral } ``` 2. **Make it accessible via theme accessor:** + ```kotlin object DesignSystemTheme { val colors: DesignSystemColorScheme @@ -93,7 +133,7 @@ We choose **Alternative C - Dynamic Styling via Composition Local**. This approa fun DesignSystemTheme( density: DSDensity = DSDensity.REGULAR, darkTheme: Boolean = isSystemInDarkTheme(), - content: @Composable () -> Unit + content: @Composable () -> Unit, ) { // Use density to choose correct style for typography and dimensions @@ -113,6 +153,7 @@ We choose **Alternative C - Dynamic Styling via Composition Local**. This approa ``` 3. **Apply Styles in Composable Functions:** + ```kotlin @Composable fun StyledText(text: String) { @@ -128,6 +169,7 @@ We choose **Alternative C - Dynamic Styling via Composition Local**. This approa ``` 4. **Provide Composable to switch between styles:** + ```kotlin @Composable fun AdaptiveLayout( @@ -147,6 +189,7 @@ We choose **Alternative C - Dynamic Styling via Composition Local**. This approa ``` 5. **Provide Adaptive Values in the Composition:** + ```kotlin @Composable fun CriticalExpressiveView() { diff --git a/docs/adr/adr-03-assets.md b/docs/adr/adr-03-assets.md index ad18798..f62d0a8 100644 --- a/docs/adr/adr-03-assets.md +++ b/docs/adr/adr-03-assets.md @@ -1,84 +1,127 @@ # ADR-03 - Integration of Assets (Icons, Fonts) in the Package ## Decision and justification -We need to decide how to integrate assets, specifically icons and fonts, into the package. The assets include functional and illustrative icons (in SVG format) and fonts (in TTF format). + +We need to decide how to integrate assets, specifically icons and fonts, into +the package. The assets include functional and illustrative icons (in SVG +format) and fonts (in TTF format). ## Problem description and context -The package must include assets from internal sources, organized in a way that allows for easy usage, maintainability, and cross-platform support. The assets consist of functional icons that can be colored, illustrative icons that are multi-colored and cannot be re-colored, and fonts. The icons are organized by functional grouping. The icons also have to support light and dark mode. + +The package must include assets from internal sources, organized in a way that +allows for easy usage, maintainability, and cross-platform support. The assets +consist of functional icons that can be colored, illustrative icons that are +multi-colored and cannot be re-colored, and fonts. The icons are organized by +functional grouping. The icons also have to support light and dark mode. ## General conditions and decision criteria ### General conditions -- **Asset Types:** Functional icons (colorable SVG), illustrative icons (multi-colored SVG), and fonts (TTF). -- **Source:** Internal sources, to be added to the package. -- **Formats:** SVG for icons, TTF for fonts. -- **Organization:** Icons are organized by functional grouping. -- **Usage:** Assets need to be easily accessible and usable within the app. -- **Performance:** No specific caching or performance requirements. -- **Build Process:** Assets should be included in the repository and integrated during the build process. -- **Platform Support:** While Jetpack Compose is primarily for Android, extensions or compatibility wrappers should be considered for potential cross-platform requirements. -- **Licensing:** Compliance with any relevant licensing requirements. -- **Scalability:** Support for different screen sizes, resolutions, and themes (e.g., Dark Mode). -- **Future Maintenance:** Assets should be easy to update and maintain. + +* **Asset Types:** Functional icons (colorable SVG), illustrative icons ( + multi-colored SVG), and fonts (TTF). +* **Source:** Internal sources, to be added to the package. +* **Formats:** SVG for icons, TTF for fonts. +* **Organization:** Icons are organized by functional grouping. +* **Usage:** Assets need to be easily accessible and usable within the app. +* **Performance:** No specific caching or performance requirements. +* **Build Process:** Assets should be included in the repository and integrated + during the build process. +* **Platform Support:** While Jetpack Compose is primarily for Android, + extensions or compatibility wrappers should be considered for potential + cross-platform requirements. +* **Licensing:** Compliance with any relevant licensing requirements. +* **Scalability:** Support for different screen sizes, resolutions, and themes ( + e.g., Dark Mode). +* **Future Maintenance:** Assets should be easy to update and maintain. ### Decision criteria -- **Ease of Integration:** Assets should be easily integrated into the package and accessible to developers. -- **Maintainability:** The solution should be easy to maintain and update. -- **Compatibility:** It should support all target platforms. -- **Organization:** The assets should be well-organized and easy to find. -- **Usage:** Assets should be straightforward to use in the app. -- **Scalability:** The solution should support different screen sizes, resolutions, and themes. + +* **Ease of Integration:** Assets should be easily integrated into the package + and accessible to developers. +* **Maintainability:** The solution should be easy to maintain and update. +* **Compatibility:** It should support all target platforms. +* **Organization:** The assets should be well-organized and easy to find. +* **Usage:** Assets should be straightforward to use in the app. +* **Scalability:** The solution should support different screen sizes, + resolutions, and themes. ## Alternatives ### A - Organize Assets in Resource Directories #### Evaluation -- **Ease of Integration:** High, standard practice for Android development, provided that SVG icons are converted to VectorDrawables beforehand. -- **Maintainability:** High, assets are easily updatable in one place. -- **Compatibility:** High, supports all target platforms. -- **Organization:** High, clear separation of assets by type (icons, fonts) and functionality. -- **Usage:** High, straightforward to use assets in Compose. -- **Scalability:** High, supports different screen sizes, resolutions, and themes seamlessly. + +* **Ease of Integration:** High, standard practice for Android development, + provided that SVG icons are converted to VectorDrawables beforehand. +* **Maintainability:** High, assets are easily updatable in one place. +* **Compatibility:** High, supports all target platforms. +* **Organization:** High, clear separation of assets by type (icons, fonts) and + functionality. +* **Usage:** High, straightforward to use assets in Compose. +* **Scalability:** High, supports different screen sizes, resolutions, and + themes seamlessly. ### B - External Asset Management System #### Evaluation -- **Ease of Integration:** Low to Moderate, requires setting up and interfacing with an external system. -- **Maintainability:** High, external systems can manage asset versions and updates. -- **Compatibility:** High, can support various platforms. -- **Organization:** Moderate to High, dependent on the external system's capabilities. -- **Usage:** Moderate, may require additional steps to integrate assets into the app. -- **Scalability:** High, well-managed external systems can handle scaling efficiently. + +* **Ease of Integration:** Low to Moderate, requires setting up and interfacing + with an external system. +* **Maintainability:** High, external systems can manage asset versions and + updates. +* **Compatibility:** High, can support various platforms. +* **Organization:** Moderate to High, dependent on the external system's + capabilities. +* **Usage:** Moderate, may require additional steps to integrate assets into the + app. +* **Scalability:** High, well-managed external systems can handle scaling + efficiently. ## Decision -We choose **Alternative A - Organize Assets in Resource Directories**. This approach aligns with standard Android development practices, ensuring ease of integration, maintenance, and scalability. It allows for clear organization and accessibility of assets, provided that SVG icons are converted to VectorDrawables beforehand. + +We choose **Alternative A - Organize Assets in Resource Directories**. This +approach aligns with standard Android development practices, ensuring ease of +integration, maintenance, and scalability. It allows for clear organization and +accessibility of assets, provided that SVG icons are converted to +VectorDrawables beforehand. ## Consequences -- **Positive:** Organizing assets in resource directories ensures they are easily manageable, well-organized, and consistently updated. This approach supports scalability and is in alignment with Android best practices. -- **Negative:** Initial setup might require some effort to properly organize all assets and convert SVG icons to VectorDrawables, but this setup promotes long-term manageability and usability. + +* **Positive:** Organizing assets in resource directories ensures they are + easily manageable, well-organized, and consistently updated. This approach + supports scalability and is in alignment with Android best practices. +* **Negative:** Initial setup might require some effort to properly organize all + assets and convert SVG icons to VectorDrawables, but this setup promotes + long-term manageability and usability. ## Links -- [Jetpack Compose Documentation](https://developer.android.com/jetpack/compose) -- [Android Asset Management Documentation](https://developer.android.com/studio/write/resource-manager) + +* [Jetpack Compose Documentation](https://developer.android.com/jetpack/compose) +* [Android Asset Management Documentation](https://developer.android.com/studio/write/resource-manager) ## Implementation Plan 1. **Add Icons and Fonts to the Project:** - - Create a `res/drawable` directory for SVG icons. - - Create a `res/font` directory for TTF fonts. - - Organize icons by functional grouping within the `drawable` directory. - - Organize icons by light/dark mode grouping within the `drawable` and `drawable-night` directory. + * Create a `res/drawable` directory for SVG icons. + * Create a `res/font` directory for TTF fonts. + * Organize icons by functional grouping within the `drawable` directory. + * Organize icons by light/dark mode grouping within the `drawable` + and `drawable-night` directory. 2. **Manual Conversion of SVG Files:** - - Use Android Studio to convert SVG files to VectorDrawables. - - Save the converted files in the `res/drawable`/`res/drawable-night` directory. + * Use Android Studio to convert SVG files to VectorDrawables. + * Save the converted files in the `res/drawable`/`res/drawable-night` + directory. 3. **Optimize SVG and TTF Files:** - - Ensure all SVG icons are optimized for performance and meet the required standards. - - Ensure all TTF fonts include necessary style variations (e.g., bold, italic). + * Ensure all SVG icons are optimized for performance and meet the required + standards. + * Ensure all TTF fonts include necessary style variations (e.g., bold, + italic). 4. **Load SVG Icons and TTF Fonts in Compose:** + ```kotlin @Composable fun VectorIconLoader(@DrawableRes iconRes: Int, contentDescription: String?) { @@ -94,10 +137,14 @@ We choose **Alternative A - Organize Assets in Resource Directories**. This appr ``` 5. **Provide Usage Examples:** + ```kotlin @Composable fun ExampleUsage() { - VectorIconLoader(iconRes = R.drawable.ic_functional, contentDescription = "Functional Icon") + VectorIconLoader( + iconRes = R.drawable.ic_functional, + contentDescription = "Functional Icon", + ) DirectoryCustomText(text = "Hello, Compose!") } ``` diff --git a/docs/adr/adr-04-package-structure.md b/docs/adr/adr-04-package-structure.md index 390ad4c..9eceb8e 100644 --- a/docs/adr/adr-04-package-structure.md +++ b/docs/adr/adr-04-package-structure.md @@ -1,54 +1,89 @@ # ADR-04 - Modular Package Structure for UX Design System in Jetpack Compose ## Decision and Justification -To maintain a clean, modular, and reusable codebase for our UX Design System, we have decided to organize design tokens (such as colors, typography, dimension) and complete components (such as buttons and modal dialogs) into separate modules within the Kotlin framework. This separation will facilitate easier integration for developers who may only need specific parts of the design system. + +To maintain a clean, modular, and reusable codebase for our UX Design System, we +have decided to organize design tokens (such as colors, typography, dimension) +and complete components (such as buttons and modal dialogs) into separate +modules within the Kotlin framework. This separation will facilitate easier +integration for developers who may only need specific parts of the design +system. ## Problem Description and Context -Our goal is to implement a ready-made UX Design System specifically for Jetpack Compose. This design system will include design tokens (such as colors, typography, and dimension) and complete UI components (such as buttons and modal dialogs). By modularizing the package, we aim to provide developers with the flexibility to use only the parts they need without importing unnecessary code. This will ensure a more efficient, maintainable, and scalable implementation. -Additionally, this modular structure will make it easier to develop and integrate additional design components independently. Developers will be able to create new components and simply import the existing design tokens, ensuring consistency across all components while maintaining the flexibility to expand the design system as needed. +Our goal is to implement a ready-made UX Design System specifically for Jetpack +Compose. This design system will include design tokens (such as colors, +typography, and dimension) and complete UI components (such as buttons and modal +dialogs). By modularizing the package, we aim to provide developers with the +flexibility to use only the parts they need without importing unnecessary code. +This will ensure a more efficient, maintainable, and scalable implementation. + +Additionally, this modular structure will make it easier to develop and +integrate additional design components independently. Developers will be able to +create new components and simply import the existing design tokens, ensuring +consistency across all components while maintaining the flexibility to expand +the design system as needed. ## General Conditions and Decision Criteria ### General Conditions -- The package must be easy to integrate with existing projects. -- Both design tokens and components should be easily accessible and independently maintainable. -- The package should remain lean, only including necessary dependencies for the specific parts being used. + +* The package must be easy to integrate with existing projects. +* Both design tokens and components should be easily accessible and + independently maintainable. +* The package should remain lean, only including necessary dependencies for the + specific parts being used. ### Decision Criteria -- Modularity: The package structure should allow developers to include only the parts of the system they need. -- Maintainability: Design tokens and components should be maintained separately to promote cleaner code organization. -- Efficiency: The system should minimize unnecessary code inclusion and dependencies. + +* Modularity: The package structure should allow developers to include only the + parts of the system they need. +* Maintainability: Design tokens and components should be maintained separately + to promote cleaner code organization. +* Efficiency: The system should minimize unnecessary code inclusion and + dependencies. ## Alternatives ### A - Monolithic Package Structure #### Evaluation -- **Pros:** Simplified structure with all elements in one place. -- **Cons:** Leads to unnecessary code inclusion, harder maintenance, and more challenging project integration. + +* **Pros:** Simplified structure with all elements in one place. +* **Cons:** Leads to unnecessary code inclusion, harder maintenance, and more + challenging project integration. ### B - Modular Package Structure #### Evaluation -- **Pros:** Encourages clean code separation, easier maintenance, and efficient project integration. -- **Cons:** Initially requires more setup and thoughtful organization. + +* **Pros:** Encourages clean code separation, easier maintenance, and efficient + project integration. +* **Cons:** Initially requires more setup and thoughtful organization. ## Decision -We choose **Alternative B - Modular Package Structure**. This approach ensuring ease of integration, maintenance, and scalability. + +We choose **Alternative B - Modular Package Structure**. This approach ensuring +ease of integration, maintenance, and scalability. ## Consequences -- **Positive:** A modular package will provide flexibility and clarity, making it easier for developers to integrate and maintain. It will ensure minimal code bloat and facilitate independent updates. -- **Negative:** The initial implementation may require more effort and a well-thought-out structure. + +* **Positive:** A modular package will provide flexibility and clarity, making + it easier for developers to integrate and maintain. It will ensure minimal + code bloat and facilitate independent updates. +* **Negative:** The initial implementation may require more effort and a + well-thought-out structure. ## Links -- [Jetpack Compose Documentation](https://developer.android.com/jetpack/compose/documentation) -- [Common modularization patterns](hhttps://developer.android.com/topic/modularization/patterns) + +* [Jetpack Compose Documentation](https://developer.android.com/jetpack/compose/documentation) +* [Common modularization patterns](hhttps://developer.android.com/topic/modularization/patterns) ### Example Code #### Package Structure -``` + +```lang-none MyProject/ ├── foundation/ │ ├── src/ @@ -78,6 +113,7 @@ MyProject/ ``` #### Foundation (foundation/Colors.kt) + ```kotlin import androidx.compose.ui.graphics.Color @@ -89,6 +125,7 @@ object AppColors { ``` #### Component (components/TextField.kt) + ```kotlin import androidx.compose.foundation.text.BasicTextField import androidx.compose.runtime.Composable @@ -119,6 +156,7 @@ fun AppTextField( ``` #### build.gradle Configuration + ```gradle plugins { id 'com.android.library' @@ -148,4 +186,4 @@ dependencies { implementation "androidx.compose.ui:ui-tooling-preview:1.0.0" // More dependencies... } -``` \ No newline at end of file +``` diff --git a/docs/adr/adr-05-accessibility-support.md b/docs/adr/adr-05-accessibility-support.md index 36d1a98..76d0fdb 100644 --- a/docs/adr/adr-05-accessibility-support.md +++ b/docs/adr/adr-05-accessibility-support.md @@ -1,67 +1,102 @@ # ADR-05 - Utilize Native Accessibility APIs in the Design System ## Decision and Justification -We have decided to integrate native accessibility features and settings into our Design System components by leveraging Android's native accessibility APIs. This approach will ensure our colors, dimension, and typography comply with accessibility standards and offer an optimal experience for users with disabilities. + +We have decided to integrate native accessibility features and settings into our +Design System components by leveraging Android's native accessibility APIs. This +approach will ensure our colors, dimension, and typography comply with +accessibility standards and offer an optimal experience for users with +disabilities. ## Problem Description and Context -The Design System must support various accessibility features to comply with accessibility standards and ensure an optimal experience for all users, including those with disabilities. This involves leveraging native APIs for features such as TalkBack, font size adjustments, high contrast text, and more. + +The Design System must support various accessibility features to comply with +accessibility standards and ensure an optimal experience for all users, +including those with disabilities. This involves leveraging native APIs for +features such as TalkBack, font size adjustments, high contrast text, and more. ## General Conditions and Decision Criteria ### General Conditions -- **Target User Groups:** All users, with a focus on those with visual, auditory, motor, and cognitive disabilities. -- **Platforms Supported:** Primarily Android. -- **Native Accessibility Features to be Supported:** - - TalkBack - - Font size adjustments (Text Scaling) - - High contrast text - - Reduce motion - - Color inversion - - Mono audio -- **Affected Components:** Colors, dimension, and typography from the Foundation Package. -- **Standards and Guidelines:** Compliant with WCAG AA standards. -- **Testing and Validation:** Automated testing in the CI pipeline. -- **Documentation:** High-level documentation indicating that accessibility features are implemented. -- **User Customizations:** Support for user customizations and settings for accessibility. + +* **Target User Groups:** All users, with a focus on those with visual, + auditory, motor, and cognitive disabilities. +* **Platforms Supported:** Primarily Android. +* **Native Accessibility Features to be Supported:** + * TalkBack + * Font size adjustments (Text Scaling) + * High contrast text + * Reduce motion + * Color inversion + * Mono audio +* **Affected Components:** Colors, dimension, and typography from the Foundation + Package. +* **Standards and Guidelines:** Compliant with WCAG AA standards. +* **Testing and Validation:** Automated testing in the CI pipeline. +* **Documentation:** High-level documentation indicating that accessibility + features are implemented. +* **User Customizations:** Support for user customizations and settings for + accessibility. ### Decision Criteria -- **Compliance:** The Design System must comply with WCAG AA standards. -- **Ease of Integration:** Attributes related to accessibility should be easily integrated into the Design System. -- **Maintainability:** The solution should be easy to maintain and update. -- **Compatibility:** It should support the features and settings on Android. -- **Scalability:** The solution should support different screen sizes, resolutions, and themes. -- **Testing:** Automated testing for accessibility features. + +* **Compliance:** The Design System must comply with WCAG AA standards. +* **Ease of Integration:** Attributes related to accessibility should be easily + integrated into the Design System. +* **Maintainability:** The solution should be easy to maintain and update. +* **Compatibility:** It should support the features and settings on Android. +* **Scalability:** The solution should support different screen sizes, + resolutions, and themes. +* **Testing:** Automated testing for accessibility features. ## Alternatives ### A - Framework-Specific Accessibility Implementation #### Evaluation -- **Pros:** Tailored solutions for specific frameworks, possibly offering enhanced feature sets. -- **Cons:** Increased complexity and maintenance overhead due to framework-specific implementations. + +* **Pros:** Tailored solutions for specific frameworks, possibly offering + enhanced feature sets. +* **Cons:** Increased complexity and maintenance overhead due to + framework-specific implementations. ### B - Utilize Native Accessibility APIs #### Evaluation -- **Pros:** Ensures compliance with accessibility standards, provides a better user experience, and leverages existing platform capabilities. Simplifies maintenance by using native APIs that are consistently updated by the platform. -- **Cons:** Requires additional development effort and testing to integrate and validate accessibility features. + +* **Pros:** Ensures compliance with accessibility standards, provides a better + user experience, and leverages existing platform capabilities. Simplifies + maintenance by using native APIs that are consistently updated by the + platform. +* **Cons:** Requires additional development effort and testing to integrate and + validate accessibility features. ## Decision -We choose **Alternative B - Utilize Native Accessibility APIs**. This approach ensuring compliance with accessibility standards, provides a better user experience, and leverages existing platform capabilities. + +We choose **Alternative B - Utilize Native Accessibility APIs**. This approach +ensuring compliance with accessibility standards, provides a better user +experience, and leverages existing platform capabilities. ## Consequences -- **Positive:** Utilizing native accessibility APIs will provide a better user experience for all users, ensure compliance with standards, and make it easier to maintain and extend accessibility support. -- **Negative:** There may be an initial increase in development and testing effort. + +* **Positive:** Utilizing native accessibility APIs will provide a better user + experience for all users, ensure compliance with standards, and make it easier + to maintain and extend accessibility support. +* **Negative:** There may be an initial increase in development and testing + effort. ## Links -- [Android Accessibility Overview](https://developer.android.com/guide/topics/ui/accessibility) -- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) -- [Accessibility Scanner](https://play.google.com/store/apps/details?id=com.google.android.apps.accessibility.auditor) + +* [Android Accessibility Overview](https://developer.android.com/guide/topics/ui/accessibility) +* [WCAG 2.1 Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) +* [Accessibility Scanner](https://play.google.com/store/apps/details?id=com.google.android.apps.accessibility.auditor) ## Sample Code ### TalkBack Example -Ensure all interactive elements have appropriate content descriptions, hints, and accessibility roles. + +Ensure all interactive elements have appropriate content descriptions, hints, +and accessibility roles. ```kotlin import androidx.compose.foundation.clickable @@ -84,4 +119,4 @@ fun AccessibleButton(onClick: () -> Unit) { } ) } -``` \ No newline at end of file +``` diff --git a/docs/adr/adr-06-prefix-naming-convention.md b/docs/adr/adr-06-prefix-naming-convention.md index 7326334..1bfc583 100644 --- a/docs/adr/adr-06-prefix-naming-convention.md +++ b/docs/adr/adr-06-prefix-naming-convention.md @@ -1,67 +1,122 @@ # ADR-06 - Prefix Naming Convention for Components & Accessors ## Decision and Justification -We have decided to adopt a systematic naming convention for all components and accessors within our Design System. The names will follow specific rules to make the system intuitive and easy to use, while also preventing naming collisions and ensuring compatibility with Android and Kotlin standards. This approach will ensure clarity, consistency, and scalability. + +We have decided to adopt a systematic naming convention for all components and +accessors within our Design System. The names will follow specific rules to make +the system intuitive and easy to use, while also preventing naming collisions +and ensuring compatibility with Android and Kotlin standards. This approach will +ensure clarity, consistency, and scalability. ## Problem Description and Context -A standardized naming convention is essential for achieving clear identification and avoiding conflicts within the design system. By adopting a consistent naming strategy, we can ensure that all components are easily recognizable as part of the Design System, which aids in both development and maintenance. + +A standardized naming convention is essential for achieving clear identification +and avoiding conflicts within the design system. By adopting a consistent naming +strategy, we can ensure that all components are easily recognizable as part of +the Design System, which aids in both development and maintenance. ## General Conditions and Decision Criteria ### General Conditions -- The naming convention should facilitate easy integration and usage, providing clear and intuitive names for all components and accessors. -- Names must avoid conflicts with existing framework or library names. -- The convention should support future scalability, accommodating the addition of new components without breaking established patterns. + +* The naming convention should facilitate easy integration and usage, providing + clear and intuitive names for all components and accessors. +* Names must avoid conflicts with existing framework or library names. +* The convention should support future scalability, accommodating the addition + of new components without breaking established patterns. ### Decision Criteria -- **Unique Prefix:** Use a unique prefix to categorize components of our design system. -- **Short Names:** Prefer shorter names for brevity and ease of use. -- **Jetpack Compose Alignment:** Names should align with Jetpack Compose conventions to ensure familiarity and ease of integration. -- **Modular Flexibility:** The naming convention should support modularity, ensuring that additional components can be seamlessly integrated. -- **Collision Prevention:** Implement a prefix strategy to avoid potential naming collisions. + +* **Unique Prefix:** Use a unique prefix to categorize components of our design + system. +* **Short Names:** Prefer shorter names for brevity and ease of use. +* **Jetpack Compose Alignment:** Names should align with Jetpack Compose + conventions to ensure familiarity and ease of integration. +* **Modular Flexibility:** The naming convention should support modularity, + ensuring that additional components can be seamlessly integrated. +* **Collision Prevention:** Implement a prefix strategy to avoid potential + naming collisions. ## Alternatives ### A - Company-Specific Prefix (e.g., `DB`) + #### Evaluation -- **Pros:** Clearly identifies components as part of the Deutsche Bahn Design System. -- **Cons:** Could deter other companies from using the Design System due to the company-specific prefix, leading to a sense of ownership by Deutsche Bahn. + +* **Pros:** Clearly identifies components as part of the Deutsche Bahn Design + System. +* **Cons:** Could deter other companies from using the Design System due to the + company-specific prefix, leading to a sense of ownership by Deutsche Bahn. ### B - Neutral Prefix (e.g., `DS` for Design System) + #### Evaluation -- **Pros:** Neutral prefix that can be adopted by any organization, reducing the risk of conflicts with other company-specific prefixes. -- **Cons:** Less immediate brand recognition for Deutsche Bahn components, but increases the system's universality. + +* **Pros:** Neutral prefix that can be adopted by any organization, reducing the + risk of conflicts with other company-specific prefixes. +* **Cons:** Less immediate brand recognition for Deutsche Bahn components, but + increases the system's universality. ### C - No Prefix + #### Evaluation -- **Pros:** Simplifies names by focusing on the type indicator and eliminates potential prefix conflicts. -- **Cons:** May lead to naming collisions with existing Jetpack Compose or third-party components. Less clear association with the design system. + +* **Pros:** Simplifies names by focusing on the type indicator and eliminates + potential prefix conflicts. +* **Cons:** May lead to naming collisions with existing Jetpack Compose or + third-party components. Less clear association with the design system. ### D - Namespace (e.g., via Kotlin package structure) + #### Evaluation -- **Pros:** Provides a clear scope for all design system components, reducing the risk of naming collisions. Namespaces make it clear that components and accessors belong to the design system. -- **Cons:** Adds an extra layer of nesting, which can make usage more verbose and may affect readability. + +* **Pros:** Provides a clear scope for all design system components, reducing + the risk of naming collisions. Namespaces make it clear that components and + accessors belong to the design system. +* **Cons:** Adds an extra layer of nesting, which can make usage more verbose + and may affect readability. ## Decision -We will adopt **Option B - Neutral Prefix (e.g., `DS` for Design System)**. This approach ensures unique identification, also reinforces brand recognition, and provides consistency with our established design system. It balances the need to prevent naming collisions while supporting a modular and scalable design system. + +We will adopt **Option B - Neutral Prefix (e.g., `DS` for Design System)**. This +approach ensures unique identification, also reinforces brand recognition, and +provides consistency with our established design system. It balances the need to +prevent naming collisions while supporting a modular and scalable design system. ## Consequences -- **Positive:** The naming convention will provide clarity and consistency, ensuring easy integration and maintenance. The use of an neutral prefix avoids naming collisions. -- **Negative:** Initial transition to the new naming convention may require updates to existing components and documentation. Less immediate brand recognition for Deutsche Bahn. -By implementing this naming convention, we ensure that our UX Design System remains clear, consistent, and scalable, providing an excellent developer experience and facilitating its adoption across various projects and organizations. +* **Positive:** The naming convention will provide clarity and consistency, + ensuring easy integration and maintenance. The use of an neutral prefix avoids + naming collisions. +* **Negative:** Initial transition to the new naming convention may require + updates to existing components and documentation. Less immediate brand + recognition for Deutsche Bahn. + +By implementing this naming convention, we ensure that our UX Design System +remains clear, consistent, and scalable, providing an excellent developer +experience and facilitating its adoption across various projects and +organizations. ## Naming Convention Guidelines -1. **Prefix with `DS` (Design System):** All components and accessors will be prefixed with `DS`. -3. **Short and Concise:** Names should be as short as possible while still clearly conveying the component's purpose. -4. **Alignment with Jetpack Compose:** Follow Jetpack Compose naming conventions to enhance familiarity and ease of use. -5. **Modular and Extensible:** Ensure the structure supports the addition of new components without breaking the established pattern. -By adhering to this naming convention, we ensure that our components are easily identifiable and maintainable. This makes it easier for developers to navigate and utilize the design system, fostering a more consistent and scalable development environment. +1. **Prefix with `DS` (Design System):** All components and accessors will be + prefixed with `DS`. +2. **Short and Concise:** Names should be as short as possible while still + clearly conveying the component's purpose. +3. **Alignment with Jetpack Compose:** Follow Jetpack Compose naming conventions + to enhance familiarity and ease of use. +4. **Modular and Extensible:** Ensure the structure supports the addition of new + components without breaking the established pattern. + +By adhering to this naming convention, we ensure that our components are easily +identifiable and maintainable. This makes it easier for developers to navigate +and utilize the design system, fostering a more consistent and scalable +development environment. ## Example Code ### Design Tokens (foundation/DSColors.kt) + ```kotlin import androidx.compose.ui.graphics.Color @@ -73,6 +128,7 @@ object DSColors { ``` ### Components/DSTextField.kt + ```kotlin import androidx.compose.foundation.text.BasicTextField import androidx.compose.runtime.Composable @@ -103,6 +159,7 @@ fun DSTextField( ``` ### Modifiers/DSTextFieldModifier.kt + ```kotlin import androidx.compose.foundation.background import androidx.compose.foundation.layout.padding diff --git a/docs/adr/adr-xx-Template.md b/docs/adr/adr-xx-Template.md index 335ec5c..ae6d7f2 100644 --- a/docs/adr/adr-xx-Template.md +++ b/docs/adr/adr-xx-Template.md @@ -10,7 +10,7 @@ ### Decision criteria -- ... +* ... ## Alternatives @@ -24,4 +24,4 @@ ## Consequences -## Links \ No newline at end of file +## Links diff --git a/foundation/README.md b/foundation/README.md index 868eeb5..d235fea 100644 --- a/foundation/README.md +++ b/foundation/README.md @@ -1,4 +1,5 @@ # :foundation module + ## Dependency graph -![Dependency graph](../docs/images/dependencies/dep_graph_foundation.svg) \ No newline at end of file +![Dependency graph](../docs/images/dependencies/dep_graph_foundation.svg) diff --git a/foundation/src/main/java/com/dbsystel/designsystem/foundation/theme/core/DSFont.kt b/foundation/src/main/java/com/dbsystel/designsystem/foundation/theme/core/DSFont.kt index eac2476..cb1996e 100644 --- a/foundation/src/main/java/com/dbsystel/designsystem/foundation/theme/core/DSFont.kt +++ b/foundation/src/main/java/com/dbsystel/designsystem/foundation/theme/core/DSFont.kt @@ -1,12 +1,9 @@ package com.dbsystel.designsystem.foundation.theme.core -import androidx.compose.ui.text.font.Font import androidx.compose.ui.text.font.FontFamily -import androidx.compose.ui.text.font.FontWeight -import com.dbsystel.designsystem.foundation.R internal object DSFont { val dsNeoScreenFlex = FontFamily( - Font(R.font.db_neo_screen_flex, FontWeight.Normal) + // Font(R.font.db_neo_screen_flex, FontWeight.Normal) ) } diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 0449e96..418cc84 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,12 +1,12 @@ [versions] -agp = "8.5.2" -kotlin = "2.0.20" +agp = "8.7.1" +kotlin = "2.0.21" coreKtx = "1.13.1" junit = "4.13.2" junitVersion = "1.2.1" espressoCore = "3.6.1" appcompat = "1.7.0" -composeBom = "2024.09.03" +composeBom = "2024.10.00" material = "1.12.0" [libraries] diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 4b06613..938b650 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ -#Tue Oct 01 16:01:04 CEST 2024 +#Wed Oct 23 16:58:16 CEST 2024 distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists