-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
5 changed files
with
98 additions
and
46 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,3 @@ | ||
| # VA Mobile Temporary | ||
| # VA Mobile Libraries | ||
|
|
||
| [Read documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/Intro) | ||
|
|
||
|
|
||
| ## Versioning Policy | ||
| The VA Mobile Libraries use [semantic versioning](https://semver.org/) at a per package level. | ||
|
|
||
| --- | ||
| **Guidance in this section to be retired at version 1.0.0** | ||
|
|
||
| Despite technically being in production, the design system is still in early, rapidly iterative phases. With only the VA Health & Benefits app leveraging and close team contact, through at least Q1 2024 we plan to use a pre-launch versioning (major version 0) as follows: | ||
| - Version 0.1.0 will be a level set of the package highlighting it's in a workable state with baseline functionality that has been proven consumable by an outside project | ||
| - For components: Segmented Control ready to use | ||
| - For tokens: Baseline set of color tokens available | ||
| - For other packages: When the package has a core piece of functionality and is stably leveraged by an outside project | ||
| - Any/all breaking changes will be minor version increments with tickets created for the VA Flagship Mobile Team providing specific guidance of necessary adjustments | ||
| - Aside from breaking changes, semver is updated according to long term guidance below | ||
|
|
||
| This policy will allow flexibility around anticipated growing pains that may entail more frequent breaking changes than more mature design systems. Once initial adoption challenges have been addressed and the packages have reached a degree of maturity in terms of content, version 1.0.0 will be published and follow the guidelines established below. | ||
|
|
||
| --- | ||
|
|
||
| The guidance around versioning for the VA Mobile Libraries shall be as follows: | ||
| - Major | ||
| - Breaking changes, large or small, that *may* require app-level changes to upgrade; examples: | ||
| - Non-backwards compatible update to an existing component property; e.g. renaming or restructuring how data is passed | ||
| - Removal of deprecated token(s)/component(s)/etc. | ||
| - Underlying dependency update introducing incompatibility; e.g. new version of `react-native` that breaks compatibility to app-level version | ||
| - In exceptional cases, may be incremented for a very significant package enhancement or totality of modest ones that comprise a bonafide "release" even without breaking changes | ||
| - Minor | ||
| - Substantive functionality enhancements that are fully backward compatible, examples: | ||
| - New token(s)/component(s)/etc. | ||
| - Enhancing a component with a new variant | ||
| - Patch | ||
| - Minor functionality enhancements that are fully backward compatible, examples: | ||
| - Adding a new property of minor impact | ||
| - Updating an existing component property with new values that have a minor impact | ||
| - Fixing internal bugs | ||
| - Alpha | ||
| - Internal design system team testing build denoted by a `-alpha.#` appended to the semver | ||
| - Should not be used in production | ||
| - Beta | ||
| - External team testing build denoted by a `-beta.#` appended to the semver | ||
| - Should not be used in production outside exceptional circumstances | ||
|
|
||
| The Figma Design Library will also follow this versioning guidance except only reflecting major/minor levels. Patch changes are likely to result in no visual changes or the design was correct while minor technical tweaks were made. | ||
| See the [Design System section of the VA Mobile documentation site](https://department-of-veterans-affairs.github.io/va-mobile-app/design/Intro) for the most organized form of the documentation. The [engineering documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/For%20engineers/overview) there also exists in this repo either in the `documentation` folder or as `README`'s tied to particular packages. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| A folder for general design system documentation not specifically tied to a package. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # Contributing Code | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| # For engineers | ||
|
|
||
| ## Overview | ||
|
|
||
| Welcome to the engineering section of the VA Mobile Design System documentation! | ||
|
|
||
| First things first: from an engineering perspective, what is the design system? | ||
|
|
||
| Fundamentally, the design system is a collection of NPM packages that can be added to a project like any other. These packages are created to support making native mobile apps that adhere to VA design principles, provide an accessible user experience, and streamline app development by providing UI building blocks to maximize time for delivering features. | ||
|
|
||
| Currently and on the roadmap for foreseeable future, the mobile design system components rely on React Native--the most popular mobile framework for complex, multiplatform native mobile apps. | ||
|
|
||
| The VA Mobile Design System is in early stages and far from maturity; as such, feedback on experience using the packages and this documentation is very welcomed to continually improve the experience! The ideal avenue for feedback is our [DSVA Slack channel](https://dsva.slack.com/archives/C05HF9ULKJ4) (#va-mobile-app-shared-systems). | ||
|
|
||
| Lastly, the [va-mobile-library repo](https://github.com/department-of-veterans-affairs/va-mobile-library) houses the VA Mobile Design System codebase and [our Storybook](https://department-of-veterans-affairs.github.io/va-mobile-library/) demonstrates them functionally. | ||
|
|
||
| ### Packages | ||
|
|
||
| So, what is currently being offered? | ||
|
|
||
| Our packages: | ||
| - assets | ||
| - Package containing static assets (e.g. fonts, SVG icons) for VA mobile apps | ||
| - Peer dependency (required) to components for appropriate function | ||
| - [Documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/For%20engineers/assets) | ||
| - [NPM](https://www.npmjs.com/package/@department-of-veterans-affairs/mobile-assets) | ||
| - [Code](https://github.com/department-of-veterans-affairs/va-mobile-library/tree/main/packages/assets) | ||
| - components | ||
| - Package containing the components of the design system | ||
| - [Documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/For%20engineers/components) | ||
| - [NPM](https://www.npmjs.com/package/@department-of-veterans-affairs/mobile-component-library) | ||
| - [Code](https://github.com/department-of-veterans-affairs/va-mobile-library/tree/main/packages/components) | ||
| - linting | ||
| - Package containing an eslint plugin to issue deprecation notices as part of linting | ||
| - [Documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/For%20engineers/linting) | ||
| - [NPM](https://www.npmjs.com/package/@department-of-veterans-affairs/eslint-config-mobile) | ||
| - [Code](https://github.com/department-of-veterans-affairs/va-mobile-library/tree/main/packages/linting) | ||
| - tokens | ||
| - Package containing atomic, tokenized building blocks used for components so any app can build screens or custom components adhering to the same underlying styling fundamentals | ||
| - [Documentation](https://department-of-veterans-affairs.github.io/va-mobile-app/design/For%20engineers/tokens) | ||
| - [NPM](https://www.npmjs.com/package/@department-of-veterans-affairs/mobile-tokens) | ||
| - [Code](https://github.com/department-of-veterans-affairs/va-mobile-library/tree/main/packages/tokens) | ||
|
|
||
| Each package's documentation page contains more specialized guidance both for users of the package as well as documentation for getting set up locally for contributing. | ||
|
|
||
| All packages use [ISC licenses](https://en.wikipedia.org/wiki/ISC_license): | ||
| > Copyright 2023 Department of Veterans Affairs | ||
| > | ||
| > Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. | ||
| > | ||
| > THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # Versioning Policy | ||
| The VA Mobile Libraries use [semantic versioning](https://semver.org/) at a per package level. | ||
|
|
||
| --- | ||
| **Guidance in this section to be retired at version 1.0.0** | ||
|
|
||
| Despite technically being in production, the design system is still in early, rapidly iterative phases. With only the VA Health & Benefits app leveraging and close team contact, through at least Q1 2024 we plan to use a pre-launch versioning (major version 0) as follows: | ||
| - Version 0.1.0 will be a level set of the package highlighting it's in a workable state with baseline functionality that has been proven consumable by an outside project | ||
| - For components: Segmented Control ready to use | ||
| - For tokens: Baseline set of color tokens available | ||
| - For other packages: When the package has a core piece of functionality and is stably leveraged by an outside project | ||
| - Any/all breaking changes will be minor version increments with tickets created for the VA Flagship Mobile Team providing specific guidance of necessary adjustments | ||
| - Aside from breaking changes, semver is updated according to long term guidance below | ||
|
|
||
| This policy will allow flexibility around anticipated growing pains that may entail more frequent breaking changes than more mature design systems. Once initial adoption challenges have been addressed and the packages have reached a degree of maturity in terms of content, version 1.0.0 will be published and follow the guidelines established below. | ||
|
|
||
| --- | ||
|
|
||
| The guidance around versioning for the VA Mobile Libraries shall be as follows: | ||
| - Major | ||
| - Breaking changes, large or small, that *may* require app-level changes to upgrade; examples: | ||
| - Non-backwards compatible update to an existing component property; e.g. renaming or restructuring how data is passed | ||
| - Removal of deprecated token(s)/component(s)/etc. | ||
| - Underlying dependency update introducing incompatibility; e.g. new version of `react-native` that breaks compatibility to app-level version | ||
| - In exceptional cases, may be incremented for a very significant package enhancement or totality of modest ones that comprise a bonafide "release" even without breaking changes | ||
| - Minor | ||
| - Substantive functionality enhancements that are fully backward compatible, examples: | ||
| - New token(s)/component(s)/etc. | ||
| - Enhancing a component with a new variant | ||
| - Patch | ||
| - Minor functionality enhancements that are fully backward compatible, examples: | ||
| - Adding a new property of minor impact | ||
| - Updating an existing component property with new values that have a minor impact | ||
| - Fixing internal bugs | ||
| - Beta | ||
| - External team testing build denoted by a `-beta.#` appended to the semver | ||
| - Should not be used in production outside exceptional circumstances | ||
| - Alpha | ||
| - Internal design system team testing build denoted by a `-alpha.#` appended to the semver | ||
| - Should not be used in production | ||
|
|
||
| The Figma Design Library will also follow this versioning guidance except only reflecting major/minor levels. Patch changes are likely to result in no visual changes or the design was correct while minor technical tweaks were made. |