hasadna/datacity-businessgate

Friendly chat-bot to help entrepreneurs get all the information they need to start a small business in Beer Sheba

Hasadna monorepo

Installation

Install Bazel. That's it!

Build & Test

• Build everything: ./compile.sh build
• Run all tests: ./compile.sh test

About monorepos

A monorepo is a software development approach where all code is stored in a single repository. Some things are easier to do in a monorepo, such as sharing a proto file across front-end and backend, some things are harder, such as per-repo control over collaborators, email notifications, commit history etc.

Some monorepo etiquette:

1. Don't store large files in the repo (>500kb), or many small files. Until we figure out a way to deal with them, you can store them in a different repo.
2. If you use code belonging to another project, talk to the people of that project about it. If you don't, they might accidentally break your code.
3. If you change code common to multiple projects, do it thoughfully.
4. Kindly provide a LICENSE file for your project.

Some good reads about the monorepo approach:

• trunkbaseddevelopment.com/monorepos
• Why Google stores billions of lines of code in a single repository

Platforms

While Bazel supports Linux, Mac and Windows, this repo supports Linux and Mac. If you're on Windows 10, you can use Windows Subsystem for Linux (WSL). It gives you a Linux environment, without the overhead of a virtual machine.

Installing Windows Subsystem for Linux:

Please follow the guide. Note: You may have to do a Windows upgrade. If you need it, it will ask for it at the beginning of the installation.

Contributing

You're welcome to contribute and in doing so, learn these technologies. You can have a look at the issues list, or at the project milestones.

Happy coding!

datacity-businessgate's Issues

Missing alt text for images

Problem description:

Several images on the website are missing alt text so an assistive technology like a screen reader can report them properly. This includes but not limited to:

• The first image that a screen reader meets (because it's the first element in the DOM from its perspective) witch is kind of a logo if I remember correctly
• Many image logos at the end of the page
• The icon for some person we came across while testing
• And so on...

Solution:

• Give all none decorative images a none empty alt text describing meeningfully the image in a way that a screen reader user needs to hear
• Give the image an empty alt text in case it's decorative and a screen reader should ignore

Menu accessibility issues

Problem description:

The menu has several accessibility issues:

• The menu content seems to be available for a screen reader in all the cases
• Not sure if this is due to the content being hidden visually but not from screen reader
• or because that the menu opens automatically once it receives focus, although this is a bit unlikely
• The button for opening the menu has no label and it doesn't seem to be in the tab order
• Within the menu, there is an image without alt text, which has been covered in a previous issue
• The screen reader reports some strange text which comes before the empty link which opens the menu from a DOM perspective. The text is the number "0"

Solution:

• Make sure to hide the menu content when it's visually hidden maybe by using aria-hidden
• Provide a label for the button which opens the menu maybe by using aria-label
• Make sure to include the link for opening the menu in the tab order by maybe using tabindex=0
• Handle images as covered by previous issue
• Hide unnecessary content from a screen reader which seems to be also visually hidden (the "0" in our case) by maybe using aria-hidden. See the link above
• Make sure that the menu can be navigated using the keyboard:
  • Opening the menu should be possible using the keyboard by including the open button in the tab order as mentioned above. Also the button should respond properly to keyboard clicks
  • The menu also should be closable using the keyboard, preferably also with the Escape key
• make sure also to apply the same considerations to the mobile view of the site

The cards for choosing a place for the business

Problem description:

When reaching the question which asks about whether you want to hear about the different areas in the town where you can have your business in, a map with a set of cards corresponding to the different regions is displayed.
The map and the cards view have the following accessibility issues:

• The map and the cards is not linked in a meaningful way. Maybe considering defining the map in figure and the cards as a figcaption is a good idea?
• Each card title is defined as h1 - which is semantically not correct I guess, thus a confusing experience for a screen reader user
• The button for choosing a specific card in each card lacks semantic and keyboard interaction:
  • It has no role to be identified by assistive technologies
  • Not reachable by the keyboard
  • Has no focus visible effect so a sighted keyboard user can tell whether it has focus

Solution:

• somehow link the map to the cards it includes
• Fix the heading level hierarchy issue
• Fix the button for choosing a card by:
  • Add a role using the role attribute
  • Add tabindex = 0 to have it in the tab order
  • Add styling in CSS for focus outline when the button gets focus

Questions about this repo

Hey,
Looks like this repo contains compiled code for the asakim.datacity.org.il chatbot, as part of the DataCity project:

There have been several pushes to this repo (about 5 this month), such that every push deletes the previous commits history.

Let me know if my understanding is incorrect.

1. Is the open source code published by Hasadna?
2. In general, does Hasadna do closed-sourced development in the DataCity project?

Thanks!

The spin button for specifying the area of the property

Problem description:

The spin button (input field) for specifying the area of the property in meter squared has the following accessibility issues:

• It has no proper label. There is only a placeholder - a problematic technique from an accessibility perspective as discussed before
• The "submit" button has no label for assistive technologies

Solution:

• Specify a label using accessibility approved technique
• Add a label for the "submit" button maybe with aria-label

Accessibility of the Combobox for choosing business type

Problem description:

The Combobox for choosing business type suffers from the following accessibility issues:

• It doesn't seem that it has a proper label. There is however a placeholder, a technique which fails the accessibility standards due to several reasons:
  • The most obvious one is that it disappears when content is inputted to the field it corresponds to
  • The second reason is that the color of the placeholder text compared to the background color doesn't reach the required ratio by the standard
• It doesn't seem that the combobox can be operated with the keyboard
• No aria markup is defined for the component so a screen reader can report the currently selected value

Solution:

• Maybe the Combobox can be defined as the one in the following example
• If another Combobox type is desired, I think the site has all sorts of examples
• Please also note the accessibility features of the Combobox for different types of interactions, be it using only the keyboard with and without a screen reader

Hidden content visually is not hidden from a screen reader

Problem description:

As I understand, the dialogue with the chatbot is a sequence of dialogs one displayed each step in the process. For a screen reader, the content of other dialogs is always available even though they are visually hidden.

Solution:

• The availability of the content should be the same both visually and semantically, that is for a screen reader, in most cases
• To achieve this in the mentioned case, you can add the aria-modal attribute to the div of the visually displayed modal
• See aria-modal - MDN
• The keyboard focus in a case of a dialog shouldn't be able to reach content which is visually hidden
• See this dialog example from w3

The Checkboxes for the conversation topics

Problem description:

When reaching the question where the user needs to check and uncheck the topics they want to have information on, the Checkboxes for the different topics have the following accessibility issues:

• They are not reachable by the keyboard
• They have no semantic information like role and state
• they don't have focus visible effect

Solution:

• The checkboxes can be defined with aria as in this example
• Please note the keyboard handlers and navigation needed
• Please also add the CSS styling for the focus visible effect for sighted keyboard users when the checkbox receives focus

The button for copying the link for the conversation

Problem description:

The button for copying the link for the conversation after the user finishes answering the questions is not accessible:

• It's only defined as an image for a screen reader
• It has no label and proper role
• can't be operated with the keyboard

Solution:

• Add the button for the tab order so it can be reached via the keyboard and implement keyboard click handlers
• Add semantic information for the button (role and label) using the role and aria-label attributes respectively
• Add an outline for the button when it gets focus to have the focus visible effect

The cards collected by the system after the user answers all questions

Problem description:

After the user answers all the questions provided by the chatbot, the system collects a set of cards which have the following accessibility issues:

• The headings hierarchy is problematic - as each card has its title as h1
• each card can be expanded and collapsed - however, this information regarding expand / collapse is not available for a screen reader, and the operation can't be completed using only the keyboard
• The component which expands and collapses the information has no semantic information for assistive technologies like role and state
• The information revealed after expanding a card is not adjacent from a DOM perspective to the component which reveals it, so a screen reader user might not find it at all

Solution:

• Fix the heading hierarchy
• Add semantic information for the component which expands the information:
  • A role like a link or a button
  • A state with aria-expanded = true when it's expanded, and false when it's collapsed
• Ad the component to the tab order with tabindex = 0, and implement keyboard click handlers
• Add a CSS styling to accommodate for the focus visible effect
• It's very important to define the section the link or the button reveals adjacent to the button or the link itself in the DOM, so a screen reader user reaches the revealed content immediately after it's revealed