NoRedInk/noredink-ui
1
1
Fork 0
mirror of https://github.com/NoRedInk/noredink-ui.git synced 2024-11-26 17:25:04 +03:00
Code Issues Packages Projects Releases Wiki Activity

🎨

Browse Source
This commit is contained in:
Brian Hicks 2023-05-10 08:36:55 -05:00
parent f75ba6a7c9
commit a2389224c0
No known key found for this signature in database
GPG Key ID: C4F324B9CAAB0D50
1 changed files with 29 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -8,6 +8,7 @@ Given this ownership and responsibility, A11ybats will provide guidance and supp
[The Component Catalog application can be found here](https://noredink-ui.netlify.app/). [The Component Catalog application can be found here](https://noredink-ui.netlify.app/).
## Component Library Foundations ## Component Library Foundations
- Adherence to the component library [accessibility policy](#accessibility-policy) - Adherence to the component library [accessibility policy](#accessibility-policy)
- Adherence to the [NoRedInk UI Style Guide](https://paper.dropbox.com/doc/UI-Style-Guide-and-Caveats-PvOLxeX3oyujYEzdJx5pu) and [Guidelines for Sharing User-Facing Changes with Design](https://paper.dropbox.com/doc/Guidelines-for-Sharing-User-Facing-Changes-with-Design-bdKGQtYH9qO9I00hUkA6k) - Adherence to the [NoRedInk UI Style Guide](https://paper.dropbox.com/doc/UI-Style-Guide-and-Caveats-PvOLxeX3oyujYEzdJx5pu) and [Guidelines for Sharing User-Facing Changes with Design](https://paper.dropbox.com/doc/Guidelines-for-Sharing-User-Facing-Changes-with-Design-bdKGQtYH9qO9I00hUkA6k)
- Interoperability and consistency of components with each other and with the NoRedInk app - Interoperability and consistency of components with each other and with the NoRedInk app
@ -18,12 +19,14 @@ Given this ownership and responsibility, A11ybats will provide guidance and supp
- Test coverage and testability of each component and of [the Component Catalog](https://noredink-ui.netlify.app/) - Test coverage and testability of each component and of [the Component Catalog](https://noredink-ui.netlify.app/)
## Accessibility policy ## Accessibility policy
- No new components will be added to the component library if they do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). Similarly, no existing components will be modified such that the component falls out of conformance with these guidelines. - No new components will be added to the component library if they do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). Similarly, no existing components will be modified such that the component falls out of conformance with these guidelines.
- For new components, UX designers & stakeholders are responsible for making their best faith effort to follow the [Accessibility Guidelines for Product Development](https://paper.dropbox.com/doc/PlcoE22OpOhB6eWCF4rFj?noDesktopRedirect=1) to include accessibility details in their spec and code. A11ybats will help fill in any gaps, but your team is responsible for the first pass. - For new components, UX designers & stakeholders are responsible for making their best faith effort to follow the [Accessibility Guidelines for Product Development](https://paper.dropbox.com/doc/PlcoE22OpOhB6eWCF4rFj?noDesktopRedirect=1) to include accessibility details in their spec and code. A11ybats will help fill in any gaps, but your team is responsible for the first pass.
- Existing components that do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) are being updated by A11ybats to be conformant. (We believe we have a comprehensive backlog of updates to make, but feel free to ask us if you think you spot an accessibility issue. 🙏 ) - Existing components that do not conform to [WCAG 2.1 AA accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) are being updated by A11ybats to be conformant. (We believe we have a comprehensive backlog of updates to make, but feel free to ask us if you think you spot an accessibility issue. 🙏 )
- Components in the NoRedInk app which are NOT in the component library but which are shared or could be shared across multiple interfaces may be added to the component library over time by A11ybats or by any team, ideally with any necessary accessibility improvements, in accordance with the [`noredink-ui` versioning policy](#versioning-policy). - Components in the NoRedInk app which are NOT in the component library but which are shared or could be shared across multiple interfaces may be added to the component library over time by A11ybats or by any team, ideally with any necessary accessibility improvements, in accordance with the [`noredink-ui` versioning policy](#versioning-policy).
# Contribution guidelines # Contribution guidelines
## What belongs in the component library? ## What belongs in the component library?
Assume anything that seems like it should be a shared component should probably be a shared component. The remaining contribution guidelines will help you make this determination. Assume anything that seems like it should be a shared component should probably be a shared component. The remaining contribution guidelines will help you make this determination.
@ -59,7 +62,7 @@ Contributing to the component library is characterized by close consultation wit
- A11ybats will review your PR solely for the purposes of ensuring that your new component adheres to the [Component Library Foundations](#component-library-foundations). We may point out bugs if we happen to find them, but that’s not what we’ll be looking for — **your team is ultimately responsible for testing/coordinating testing of your new component**. - A11ybats will review your PR solely for the purposes of ensuring that your new component adheres to the [Component Library Foundations](#component-library-foundations). We may point out bugs if we happen to find them, but that’s not what we’ll be looking for — **your team is ultimately responsible for testing/coordinating testing of your new component**.
- For minor iterations on your new component, there’s no need to request A11ybat PR review again. We’ll keep an eye on smaller changes as you make them. If you aren’t sure if your changes are big enough for another A11ybat PR review, just ask! - For minor iterations on your new component, there’s no need to request A11ybat PR review again. We’ll keep an eye on smaller changes as you make them. If you aren’t sure if your changes are big enough for another A11ybat PR review, just ask!
7. Once your component is in a state that’s ready for production, please request an accessibility review from A11ybats by dropping a note in [#ask-accessibilibats](https://noredink.slack.com/archives/C02NVG4M45U). Our turnaround time should be relatively quick, but in the meantime… 7. Once your component is in a state that’s ready for production, please request an accessibility review from A11ybats by dropping a note in [#ask-accessibilibats](https://noredink.slack.com/archives/C02NVG4M45U). Our turnaround time should be relatively quick, but in the meantime…
8. Start creating a [QA Flightplan](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn) as if this were a new feature. We recommend requesting that the QA team *at least* tests your new component within the Component Catalog netlify branch preview. (You can always request additional QA of your component as implemented in the NoRedInk app later.) Simple components may have a simple flightplan, and that’s okay! 8. Start creating a [QA Flightplan](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn) as if this were a new feature. We recommend requesting that the QA team _at least_ tests your new component within the Component Catalog netlify branch preview. (You can always request additional QA of your component as implemented in the NoRedInk app later.) Simple components may have a simple flightplan, and that’s okay!
9. Once A11ybats have completed their accessibility review, make updates to your QA Flightplan if needed and submit your QA Flightplan to QA according to [QA’s processes](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn). 9. Once A11ybats have completed their accessibility review, make updates to your QA Flightplan if needed and submit your QA Flightplan to QA according to [QA’s processes](https://paper.dropbox.com/doc/QA-landing-page-FAQ--BNKlATfTHdgnJa48lcR5NrVSAg-wLYVa0lEmkaiJB09CXHRn).
10. When you're ready to publish your component, please refer to [the noredink-ui versioning policy](#versioning-policy), which includes guidance on permitted API changes per release. 10. When you're ready to publish your component, please refer to [the noredink-ui versioning policy](#versioning-policy), which includes guidance on permitted API changes per release.
11. A11ybats keep an eye on all noredink-ui updates and may request modifications to your work if it does not adhere to the [Component Library Foundations](#component-library-foundations). 11. A11ybats keep an eye on all noredink-ui updates and may request modifications to your work if it does not adhere to the [Component Library Foundations](#component-library-foundations).
@ -67,6 +70,7 @@ Contributing to the component library is characterized by close consultation wit
# Developing, deploying, & versioning # Developing, deploying, & versioning
## Getting Started ## Getting Started
1. Setup your [development environment](#developing-with-nix) 1. Setup your [development environment](#developing-with-nix)
2. Run some [tests](#tests) 2. Run some [tests](#tests)
3. Check out [some examples](https://noredink-ui.netlify.app/) 3. Check out [some examples](https://noredink-ui.netlify.app/)
@ -92,7 +96,7 @@ It is automatically loaded in the Nix environment.
Here are some things you might need to do: Here are some things you might need to do:
| Task | Command | | Task | Command |
|------|---------| | --------------------------------------------------- | ---------------------------------------------------------- |
| Add a non-npm, non-Elm dependency packaged with Nix | Look if it's in nixpkgs, or `niv add github.com/user/repo` | | Add a non-npm, non-Elm dependency packaged with Nix | Look if it's in nixpkgs, or `niv add github.com/user/repo` |
| Update Nixpkgs | `niv update nixpkgs` | | Update Nixpkgs | `niv update nixpkgs` |
| See all our dependencies | Look in `shell.nix` | | See all our dependencies | Look in `shell.nix` |
@ -106,6 +110,7 @@ The instructions above will work until they're removed from the repo, but if you
## Tests ## Tests
Run tests with Run tests with
- `shake test` - `shake test`
- `elm-test` - `elm-test`
@ -154,10 +159,8 @@ Any NoRedInk engineer can deploy a new version of `noredink-ui`. Generally, we p
- Because of branch protection you will not be able to push a tag like: `git push origin master 22.x.y` (The previous command requires permissions to push directly to master even if you have no changes). - Because of branch protection you will not be able to push a tag like: `git push origin master 22.x.y` (The previous command requires permissions to push directly to master even if you have no changes).
- Instead, please push your new `22.x.y` tag with the following: `git push origin 22.x.y` - Instead, please push your new `22.x.y` tag with the following: `git push origin 22.x.y`
Once you've published, you should see the latest version at <https://package.elm-lang.org/packages/NoRedInk/noredink-ui/>. It can take a few minutes to show up. Once you've published, you should see the latest version at <https://package.elm-lang.org/packages/NoRedInk/noredink-ui/>. It can take a few minutes to show up.
### Troubleshooting a release ### Troubleshooting a release
If you get something like this: If you get something like this:
@ -211,20 +214,21 @@ We should change this process if we feel it's not working for us!
## Moving Widgets to `noredink-ui` ## Moving Widgets to `noredink-ui`
If you are moving in a widget from the monolith: If you are moving in a widget from the monolith:
- Copy the contents of `Nri.SomeModule` and its tests to `Nri.Ui.SomeModule.V1` in `noredink-ui` - Copy the contents of `Nri.SomeModule` and its tests to `Nri.Ui.SomeModule.V1` in `noredink-ui`
- Publish! - Publish!
- If you feel confident upgrading pre-existing usages of the widget, switch over to it everywhere! - If you feel confident upgrading pre-existing usages of the widget, switch over to it everywhere!
- If the new version introduces big changes and you'd rather keep the old one around for now, rename `Nri.SomeModule` to `Nri.DEPRECATEDSomeModule` in the monolith and start using `Nri.Ui.SomeModule.V1` where you need it - If the new version introduces big changes and you'd rather keep the old one around for now, rename `Nri.SomeModule` to `Nri.DEPRECATEDSomeModule` in the monolith and start using `Nri.Ui.SomeModule.V1` where you need it
## Phasing out old versions ## Phasing out old versions
Our goal is to gradually move to the newest version of each widget, and remove the old versions when they are no longer used. Our goal is to gradually move to the newest version of each widget, and remove the old versions when they are no longer used.
This means: This means:
- We should avoid introducing new references to old versions of a widget
- When touching code that uses a widget, prefer upgrading to the latest version - We should avoid introducing new references to old versions of a widget
- If you introduce a new version of a widget, please consider taking the time to upgrade all previous usages - When touching code that uses a widget, prefer upgrading to the latest version
- If you introduce a new version of a widget, please consider taking the time to upgrade all previous usages
- If for some reason this isn't feasible, create a story in your team's backlog so that you can prioritize it separately without disrupting your current work - If for some reason this isn't feasible, create a story in your team's backlog so that you can prioritize it separately without disrupting your current work
- You can delete an old version of a widget when there are no usages left - You can delete an old version of a widget when there are no usages left
- Note: this will be a major version bump, so you may want to batch deletions together - Note: this will be a major version bump, so you may want to batch deletions together