patternfly / patternfly-quickstarts Goto Github PK
View Code? Open in Web Editor NEWRepository containing the PatternFly Quick Start extension code
License: MIT License
Repository containing the PatternFly Quick Start extension code
License: MIT License
Add axe automated testing to our build and fix the following issues:
Testing tool | Issue | Type | URL | Specific Location | Suggested Solution |
---|---|---|---|---|---|
Axe | Elements must have sufficient color contrast | Color/Design | https://quickstarts.netlify.app/ | Gray time and step number | Consider darker color? |
Axe | Id attribute value must be unique | Doc id issue | https://quickstarts.netlify.app/ | id="description" on card | Check ids and make sure unique |
Axe | <li> elements must be contained in
|
Semantics | https://quickstarts.netlify.app/ | Step numbers in QS | Update structure |
Axe | Aria attributes must conform to valid values | Semantics | https://quickstarts.netlify.app/ | Splitter - PF issue? | This may need to be updated in PF |
Axe | Elements must only use allowed ARIA attributes | Labeling | https://quickstarts.netlify.app/ | Pressing next (with check your work) | Aria-label no longer supported on divs? Look into alternative solution |
Axe | IDs used in ARIA and labels must be unique | Labeling | https://quickstarts.netlify.app/custom-catalog | "Links to external resources" heading | Determine which id it is complaining about and ensure it's unique |
Classes should not begin with .co-*
or .ocs-*
as those come from OpenShift. Use a new prefix instead.
Add support for external content to be displayed inside the quick start drawer. This could be helpful in cases where instead of linking off to documentation you could insert that documentation directly into the quick start, etc. (Could be helpful for products like Managed Kafka)
We should investigate if there's any library changes needed for localization or if it's only up to the consumer to provide localized quick start content.
We should investigate if there is anything that we need to do in order to support dark theme with Quick Starts
#3 Asked for CYW to be optionally visible (i.e. configurable) but user feedback suggests it should always be there before clicking next.
Since @percy/script is now deprecated
See:
https://www.npmjs.com/package/@percy/script
https://docs.percy.io/docs/migrating-to-percy-cli
This collection of issues is a bunch of easy fixes that will help the screen reader experience quite a bit. Some of these are documentation/demo issues but are still important to show consumers the correct way to do it.
Testing tool | Issue | Type | URL | Specific Location | Suggested Solution |
---|---|---|---|---|---|
VO | Headings skip level (1 > 3 > 5) | Structure | all | Page and card headings | Headings should go in sequential order and convey structure |
VO | Show prerequisites buttons should be unique | Labeling | all | preqs button | They should make sense out of context (i.e. "Show {title} prereqs") |
VO | Status select should have a label | Labeling | https://quickstarts.netlify.app/quickstarts-props | Status select/dropdown | Should have some kind of label ("Status"), currently just expanded and collapsed button |
see changes made in #67.
there should be a transpilation pipeline to use TSX content as commonJS in a webpack node process.
also look into creating a module or bundling it into the main quick starts library, so that asciidoc consumers can more easily get these new capabilities
Making note of this quick starts related issue from here so we can keep an eye on it
openshift/console#9723
In our current implementation of the page, there's an issue with the CSS where the background color doesn't fill the page header section. I'm not able to reproduce this issue in the extension demo.
Is it possible to adjust the CSS to use padding instead of margin on the pfext-page-layout__title
element, similar to how spacing is handled for page sections in PF? Or is it possible to use PF components for these page sections instead?
Quick start contents should support rendering an inline alert anywhere within the contents (e.g. within a numbered list), similar to the example shown here: https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/f351c4bd-9840-42ef-bcf2-b0c9be4ee30a#_b4f95791-b992-429d-9e8e-cceb63ae829f
We need to finalize and provide updated designs for the Learning Path Details Pages. Brie had worked on these explorations in the past, but they're a bit outdated and need some refinement.
QuickStartDrawer/catalog should be able to render without quick starts, and once the quick starts have been passed in should let them re-render.
Requirements:
Proposed updates:
You used to be able to configure each task's summary, so that you could either show a success message, or a failure message, like Try the steps again
.
It appears that now there is no success message shown, and on failure is hardcoded to Try the steps again
.
The config looks like this
summary:
success: You have learned about highlighting elements!
failed: Try the steps again.
Also, if a task does not have the review/Check your work section, it still automatically counts as a failure and shows the Try the steps again.
message. I wouldn't expect to see it.
A check your work section for reference:
review:
instructions: |-
- Did you complete the task successfully?
failedTaskHelp: This task isn’t verified yet. Try the task again.
From #50:
And the need for apps to pull in import "@patternfly/quickstarts/dist/quickstarts-bootstrap.min.css";
Create new classes instead that should be bundled into the quickstarts.css
.
Aside from usability issues, the double Next click could have a negative impact on usage metrics.
Thanks for the clarification!
In the case where the user selects no on CYW, I also think the (!) icon and text should be red. It is listed under proposed updates here. Should I go ahead and make that change (along with removing "Try the steps again")?
Yes, let's go with that. There was some feedback in a google doc comment, in favor of having the icon color in the task match the icon color in the CYW section, which makes sense.
There was also some concern raised about using red, but since that requires discussion with the larger design team, I would defer that to a separate issue to update both the icon color and CYW section at the same time. For now I've added an agenda item for the next meeting to discuss.
A remaining case which I am unclear on how to handle is the when the user visits the task, opens the CYW section, but makes no selection before moving on to the next task. (See task 2 from the example screenshot with Review task status.) Should "Try the steps again" be displayed? Should the icon change to (!) like step 3, and if so should we use a different color to indicate a difference in state from Visited task status like task 3?
There was a previous issue to have the CYW prompt always visible (i.e. not require the user to hit Next to see a CYW prompt): #3. This issue is closed, but when I look at the demo, I see the original behavior is still there. @jschuler Can you comment on this? Is that behavior configurable by the consumer?
To answer @CooperRedhat's question, if it is configurable that the CYW section is not always visible, then I would expect these two states to be displayed the same way—with a blue number and a "Try the steps again" statement. As an FYI, we want to review the current quick start behavior with usability testing, so it's possible there will be new insights to inform the design of this.
Originally posted by @jgiardino in #56 (comment)
Whenever a keyboard or screen reader user is moving through a quick start, if they click on a footer action like Next, Back, or Restart, their focus stays on the button, forcing them to go backwards to get to the top of the quick start. Focus should instead shift to the top of the quick start if they're pressing the footer actions.
I think it's fair to assume that if a user is moving through a quick start, they should be following the steps and tasks in the quick start. Perhaps some users may want to quickly click through the footer actions, but I imagine that they may skip actions if they did this. Also, we recently added an auto scroll for mouse users to take them to the top of the content so I think it would make sense to have parity for keyboard and screen reader users.
As a content provider/author for quick starts I would like a way to parameterize certain bits of text (e.g. the product name between community and product.
Note: cloud.redhat.com quick starts provide a default value, and then to override it in the product. We only have about a dozen parameters (e.g. product-short (name), product-long (name)) etc.
Requirements:
Proposed updates:
Start the Monitor your sample application quick start.
It would make sense to explore how we can order and group quick starts into different potential learning paths. For example, three quick starts could make up a course and create structured groupings. (Would be interesting to explore how we can create loose groupings as well.)
There was an OpenShift issue opened on this as well.
Some exploration has been done on this topic in this doc.
PFReact issue to add this functionality: patternfly/patternfly-react#6361
This issue may be fixed after completing #29, but wanted to make sure this doesn't get lost.
Would help the user have a visual queue after pressing the Restart
button on the initial task page.
Found this when I was trying to update allQuickStarts
in the context based on the chosen language. When I changed it didn't rerender. So I had to use QuickStartContainer.
Note: These are visual breaking changes and should be included in a new version release. Design leads should communicate these proposed updates with their product team leads (fyi @kywalker-rh @bmignano).
Currently, the quick start drawer uses the same visual styling as a PF drawer. Given that the quick start drawer can display next to another drawer that is part of the application UI, there isn't much visual differentiation between the two drawers which makes it challenging to identify what part of the UI is from the app and what part is from the quick start.
Proposed updates are captured here: https://marvelapp.com/prototype/cdb107d/screen/80786868
For example by adding comments to
https://github.com/patternfly/patternfly-quickstarts/blob/main/packages/module/src/utils/quick-start-types.ts
Also in what cases should the restart button be shown on initial screen
Currently, "Restart" only displays in the last screen of the drawer. (see example below)
This task is to always display a Restart action in the footer.
During a design review, we discussed only showing "Restart" in the card if the quick start was completed. This means that a quick start in progress would only display the action "Continue". With this action being removed from the card for quick starts that are in progress, having an easy way to jump to the intro screen would be helpful.
cc'ing @bmignano
Currently, prerequisites are not shown in the quick starts drawer. Here are the proposed designs for adding in prerequisites to the quick starts intro, as well as additional task-level prerequisites: https://marvelapp.com/prototype/15agb91j
User Story
As a quick start user, when I'm viewing contents of a quick start, I want know what prerequisites exist so that can make sure I'm not trying to complete a quick start before I'm ready.Requirements
- Prerequisites should be easily visible and accessible from the drawer
- Can be hidden easily if it ends up taking up too much space or away from the context of the intro.
- Users should confirm that they meet the prereqs, esp if not having them in place could break the quick start experience.
- For an individual task (i.e. not intro or conclusion) — If we incorporate a Prerequisites heading, also incorporate a Procedure heading, to be consistent with our quick start presentation on the Customer Portal.
- Include the ability to show prerequisites for the entire quick start in the intro as well as per task. Assumption is that prerequisites captured in individual tasks would capture things they’ve completed in a previous task.
- Innovation - Preqs are automatically checked/verified by the system where possible
- For this design task - how would checked/verified items display
Should there be the ability for Quick Starts to exist on its own separately and be able to follow you through different environments and windows? This would support learning paths across several products and enable users to move through different products that each have a quick start. This could be particularly beneficial to products like OpenShift that branch off into others. If the quick start from OpenShift goes to a specific product we can add some code to (for example to add information that you’re currently part of a learning path/tutorial), that would help.
This would also help support use cases where context could be lost. For example, if you click on step 2 and it goes somewhere else, you could lose the context of the quick starts you're in and the prerequisites you completed are now also lost.
A POC was created on this idea previously, and this doc describes this idea. However, the downside to working on this issue is that it would likely require lots of engineering resources to achieve.
We're using some of the service icons multiple times on the quick start and documentation cards and this currently only supports base-64 formats. This format seems to cause some jagged edges with the icon.
This request is for:
When a user is tabbing through the page, the user should be able to focus on a quick starts card, select it by pressing Enter, and then focus should shift to the Quick Start. (Doing this for keyboard users should likewise translate over to screen reader interaction.)
We show an example of something like this in PF cards here for example.
We need a few updates to allow for localization:
When moving from a task step to another step, the top should be visible
One of the findings identified during a user review related to quick starts was that prerequisites should be communicated in the drawer.
The design task for this update is captured in https://issues.redhat.com/browse/APPDUX-1089
cc @lboehling
A script should be able to run that updates a quick starts prerequisites as the user completes them, giving users updated information about what they still have outstanding to complete before taking the current quick start. (Should be able to also run clean up script so the next person can run it again.)
This also brings up the question of how to handle quick starts that aren't available yet or when prerequisites haven't been completed. Are there any valid use cases for locking quick starts? Given that validation is still not possible, locking quick starts could just invite users to “fake” completion of a quick start to get to the next one. Additionally, we may not want to block advanced users from accessing a quick start later in a course if they don’t need the prior ones. If we find a valid use case for this, we could consider greying out and locking quick starts that users are not yet able to take. (Info on this pulled from OpenShift's Quick start courses exploration doc, page 7 and 8).
Main issue to track ongoing work with integrating quick starts into didact
Additional feature work
Additional items:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.