design

Note

Read this page carefully and expect to return to it often.

Hello designer! We're excited to have your help envisioning a new and improved Wordplay.

Design is about what we make and why. It's about serving our key stakeholder communities: secondary teachers and their students, especially multilingual students, English learners, students with disabilities, and neurodivergent learners. It spans every aspect of Wordplay's design, from its visual design language and user interfaces to the programming language and API designs to the learning experiences and documentation. Design is not Figma — that is just a tool for doing user interface design, not a tool that is useful for all design problems.

Here's the current flow of design work in this project that we expect you to follow:

Choose an issue

All issues are in this repository on the issues page.

Our current top-level design priorities are:

1. WCAG 2.2 level AA compliance (to ensure Wordplay is accessible to everyone, regardless of abilities)
2. Support all of the world's natural languages (to ensure everyone can use Wordplay, regardless of language fluency)
3. Enable rich secondary-level teaching and learning experiences (grades 6-12) (to ensure everyone has opportunities to learn computing through school)

Wordplay's issues reflect smaller parts of achieving these larger design goals. All of the issues tagged needs design need design work. (There may also be some missing that tag, but it also needs design work.) Some are tagged enhancement, which means they are new features that could be added to Wordplay. Others are tagged defect, which means there's something broken that needs a redesign. Issues in the 1.0 backlog are the highest priority.

Of course, many design opportunities in Wordplay still need to be resolved. If you have an idea for a new feature or an improvement, create a new issue, and we'll review it to see if we should include it. We need your voice on the design to make it better!

Once you've chosen a needs design issue that you'd like to be responsible for (or create one yourself), note who else is assigned and communicate with them, asking them to join the team if they are looking for helpers if you're not also acting as the issue's developer, you may want to find a developer to collaborate with so you can design around engineering constraints. When you're ready to request to join, tag a maintainer, explaining that you'd like to work on it so everyone knows why you're assigned; they will assign you or have a discussion with you about whether it's a good fit for your skills and goals.

Important

Some issues are tagged needs research. These issues may require 6+ months of full-time research to resolve successfully and may have no solution. They are best left to undergraduate research assistants, doctoral students, postdocs, and other researchers who can invest significant time in reading, invention, study, and scholarship.

Research the problem

Read the issue and its history closely. Find the other people who've contributed to the issue. Should the problem scope be more significant or more minor? Who's needs would it address? Capture all of this in comments, and revise them so there's clear documentation about the need. Ensure you understand how any existing Wordplay functionality works in depth before redesigning anything. Please do not assume that the research on the issue is correct or complete; it's your job to fully understand the nature of the problem before proposing designs.

One reasonable part of research is engaging with stakeholders (e.g., youth and teachers). If you want to do this (and for most design issues, you should), do not go rogue: consult with maintainers about how to engage community. Talking to youth requires careful planning, talking to teachers requires careful consideration of their limited time, and talking to partners such as not-for-profit organizations requires long-term professional communication and engagement planning. Please do not take these kinds of outreach lightly; poor interaction with a person, community, or organization can permanently harm our ability to learn with communities. That's why we manage these relationships centrally.

If you cannot talk to stakeholders directly, study other existing research, learn from online communities discussing the issue, and consult the leadership team for suggested resources. There's a lot of knowledge in the world that can be gained about a problem. (If you're an Informatics student, INFO 300 Research Methods is the best preparation for this work.)

Propose designs

As you research the need, you'll generate concrete ideas. Your job is to envision concrete designs or redesigns that address the problem and post them as new comments on an issue.

Which tools to use to do design depends on what you are designing. Some designs might be programming language features; you only need text code examples to sketch designs. Some might be user interface designs; you might use Figma. Another design might be writing; you can write text in GitHub. You can choose the tool that best enables you to express your vision.

All design proposals should be embedded in an GitHub issue comment. If you need to include an image, include a description so contributors who rely on descriptions of visuals can understand what you're proposing.

Important

Do not link to PDFs. PDFs are not accessible to people who use screen readers without significant effort, so anyone trying to read your design with a screen reader will be unable to. Please don't link to external web links, as links bit rot and have permissions barriers. Everything must be embedded as accessible text and images.

Important

Do not link to Fimga designs unless you include screenshots from GitHub. It's okay to create interface designs in Figma, and include them as images with alt text, but we do not want external links in issues, as permissions change, designs get deleted. We need a self-contained archive of the proposal in an issue.

Important

Do not link to Google Docs. All text and content should be in GitHub issues so everyone has full context for the discussion and proposals. The communication can't count on random Google Docs linked to your accounts to be available in the future, but we can count on GitHub comments being available.

When you have a design sketch, consult with developers (including Amy) on its feasibility. They may have perspectives on what is and isn't possible or questions that your sketch does not yet answer.

Iterate

When you have a design ready for review, tag Amy or other design leads for design review.

Expect our design review to go as follows:

• We'll check to ensure the design specification complies with the guidelines above.
• We'll read the design specification and generate a list of ambiguities, inconsistencies within the existing design, and violations of the project's core design goals, writing a comment to describe them.
• You'll iteratively address design issues until the list is empty 🙂

Once there are no more concerns, we will remove needs design and add the tag buildable, which signals developers that it's ready for engineering.

Build

See if you can recruit someone in a develop role to collaborate with, and if you succeed, collaborate with them to ensure the implementation meets your vision. This should be a collaborative process, not something you toss over to engineering; regular communication and testing are essential, as you may need to revise your design as constraints and feasibility become more visible. A successful design project will ship the feature and end with a high five between designers and developers.

Your job is done when either 1) you and a developer have submitted a pull request successfully merged into the main branch or 2) you still need to find a developer to work on it.

Repeat

Once you're done, move on to another issue!