├── README.md ├── guides └── alerts.md └── principles ├── README.md └── design-team.md /README.md: -------------------------------------------------------------------------------- 1 | # Archival 2 | This repo was archived by the Apollo Security team on 2023-05-26 3 | 4 | 5 | 6 | # Design principles 7 | 8 | This is a place to track Apollo (the company) design principles (i.e. individual values) and design guides (i.e. implementation specific principles) for how we build and ship software together. 9 | 10 | | Principles | 11 | |---| 12 | | [README](principles/README.md) | 13 | | [Design Team](principles/design-team.md) | 14 | 15 | | Guides | 16 | |---| 17 | | [Alerts](guides/alerts.md) | 18 | -------------------------------------------------------------------------------- /guides/alerts.md: -------------------------------------------------------------------------------- 1 | # Alerts design principles 2 | 3 | An alert is a type of notice that displays a short, important message in a way that attracts the user's attention without interrupting the user's task. 4 | 5 | It should be used specifically when the information or actions it contains is relevant to the users immediate actions or workflow (as opposed to notifications, audit logs, or other more persistent information). 6 | 7 | Alert types and their usage: 8 | 9 | ## :information_source: Informational 10 | 11 | Informational alerts present general info about something you are doing or working with. It is neutral and conveys no implications of success or failure. 12 | 13 | **When to use:** Use when further information is available about the users action or workflow that is relevant to what they are doing and not otherwise obvious in the UI. 14 | 15 | **Style:** 16 | - color association: blue 17 | - icon: [IconInfoSolid](https://space-kit.netlify.app/?path=/story/components-icons--icon-info-solid) 18 | 19 | ## :warning: Warning 20 | 21 | Warning alerts present information about the action that is about to be taken that alerts the user to consequences of the action and asks for confirmation that the action still be taken in light of the consequences. 22 | 23 | **When to use:** Use in any instance where it would be best to ensure the user is fully informed of the implications of the action, especially if the action may be destructive or irreversible. 24 | 25 | **Style:** 26 | - color association: orange 27 | - icon: [IconWarningSolid](https://space-kit.netlify.app/?path=/story/components-icons--icon-warning-solid) 28 | 29 | ## :x: Error 30 | 31 | Error alerts let the user know that something has gone wrong or is blocked in the given workflow they are trying to complete. When possible, error alerts should contain helpful information about what has happened to help unblock the user (such as steps to resolve or a link to a docs article). 32 | 33 | **When to use:** Use when it is not clear from any other available and obvious component in the UI that an action has failed. 34 | 35 | **Style:** 36 | - color association: red 37 | - icon: [IconErrorSolid](https://space-kit.netlify.app/?path=/story/components-icons--icon-error-solid) 38 | 39 | ## :white_check_mark: Success 40 | 41 | Success alerts are confirmation that the action the user was trying to take has succeeded. 42 | 43 | **When to use:** Use when it is not obvious from any other part of the UI that success has occurred (e.g. in Studio, successfully running an operation results in a visible Response, so a success alert is not necessary). 44 | 45 | **Style:** 46 | - color association: green 47 | - icon: [IconSuccessSolid](https://space-kit.netlify.app/?path=/story/components-icons--icon-success-solid) 48 | 49 | ## :clock3: Neutral 50 | 51 | Neutral alerts are intended to provide a passive notification to the user, most often as it relates to the freshness of data, but can be expanded to include additional scenarios. 52 | 53 | **When to use:** Use when it is helpful to inform users that settings and/or configurations have changed since the generation of a given artifact. 54 | 55 | **Style:** 56 | - color association: gray 57 | - icon: [IconTimeSolid](https://space-kit.netlify.app/?path=/story/components-icons--icon-time-solid) 58 | 59 | --- 60 | 61 | Worthwhile reading for reference: 62 | - [Material UI approach to Alerts](https://material-ui.com/components/alert/) 63 | - [Primer Design System: Messaging](https://primer.style/design/ui-patterns/messaging) 64 | - [Bootstrap Toasts](https://getbootstrap.com/docs/4.2/components/toasts/) 65 | - [Primer Toasts](https://primer.style/css/components/toasts) 66 | 67 | --- 68 | 69 | # Design implementation 70 | 71 | Here are some examples for how Alerts can be implemented, starting with the two main use cases: 72 | 73 | ## Alert banners 74 | 75 | Alert banners are primarily for situations where there is nothing you can do in the UI to immediately fix or change the state (e.g. deprecation warnings, account status alerts, etc). 76 | 77 | ![alert-banners-image-light-and-dark](https://user-images.githubusercontent.com/1319791/133327896-f0346b15-4847-432a-b6f7-aa0916f0ed98.png) 78 | 79 | 80 | - [see AlertBanner](https://space-kit.netlify.app/?path=/docs/components-alertbanner--info-light) in SpaceKit Storybook. 81 | - see in [Sketch Cloud](https://www.sketch.com/s/aa84f7e1-c1aa-4f8c-a252-b62955de353a/a/ew5w0x), and see also [version with CTA button](https://www.sketch.com/s/aa84f7e1-c1aa-4f8c-a252-b62955de353a/a/l3RVwe) 82 | 83 | ## Full-page banners 84 | 85 | Full-page banners are a form of alert banner reserved for situations where the message pertains to app-level or page-level situations. These banners display a persistent message that cannot be manually dismissed by the user. These banners inherit the same type themes and iconography as standard alert banners, with the addition of a neutral type (gray), used for displaying information about the freshness of page content. 86 | 87 | Full-page banners are appended to the base of the page header, and like the page header, should stay fixed in view even if the contents of the page scroll. 88 | 89 | ||| 90 | |---|---| 91 | |![full-page-alerts-light](https://user-images.githubusercontent.com/1319791/133329067-24c475ce-9dca-4c1f-8e33-5ce5a9b81d8f.png)|![full-page-alerts-dark](https://user-images.githubusercontent.com/1319791/133329098-e8eb6f2b-de05-472c-a56b-0d279482a420.png)| 92 | 93 | ## Alert toast cards 94 | 95 | Toast cards appear in the middle of your workflow when an action you’ve taken prompts a message, or when a state that your account, graph, or data is in prompts a message. 96 | 97 | Toast cards can have several variations: 98 | - just a message that can be dismissed 99 | - a message with a primary (and optionally a secondary) call to action button 100 | - or an expanded content variant that allows for longer form instructions or messaging (used when the content requires more than a single paragraph) 101 | 102 | ||| 103 | |---|---| 104 | |![alert-toast-card-examples-light](https://user-images.githubusercontent.com/1319791/133328528-0ea33b49-334b-4146-b15a-a837138415b1.png)|![alert-toast-card-examples-dark](https://user-images.githubusercontent.com/1319791/133328572-4829de4c-7f6b-4eba-945e-ac5cca8e2c5a.png)| 105 | 106 | - [see in AlertCard](https://space-kit.netlify.app/?path=/docs/components-alertcard--info-light) in SpaceKit Storybook. -------------------------------------------------------------------------------- /principles/README.md: -------------------------------------------------------------------------------- 1 | # Apollo Design Principles 2 | 3 | ## What are design principles? 4 | 5 | These principles are meant to help guide and inform design decisions, and how we build and ship product at Apollo. They are about starting from [first principles](https://en.wikipedia.org/wiki/First_principle), and they are the principles we can always go back to and start from. To learn more, see [Prior Art](#prior-art). 6 | 7 | ## Context 8 | 9 | We initially set out to come up with a list of unified principles for our design group, but during our first exercise it became clear that seeing each person's principles was really valuable as a way to understand how each team member sees and thinks. 10 | 11 | We decided to preserve this format and run with it, inviting each team to document the individual principles of their own team members. This repository is a work in progress to that end. 12 | 13 | Over time as each team and team member adds their own principles, we should notice common themes emerging. Eventually we could extract and codify a set of unified company-wide principles that represent our aggregate set, and align with other company wide ideals (like our values). 14 | 15 | ## How to contribute your principles 16 | 17 | *(for Apollo staff only)* 18 | 19 | Check to see if your team has already started a principles doc (check the repository root files list above). 20 | 21 | If so, feel free to add your name and principles to the doc by editing the document (here on GitHub, or by checking out the repository locally) and then opening a [pull request](https://github.com/apollographql/design-principles/pulls). Over time, you can always add to or edit your list as you gain clarity on your own principles (part of the joy and intention behind this exercise is to help us think and see with design principles lenses more intentionally! :sparkles::eyeglasses::sparkles:) 22 | 23 | If your team does not have a principles doc yet, feel free to be the first to add one! There are two ways to approach this with your team, and it's quite up to you (and your team). 24 | 25 | The first way is to simply add a new markdown file, drop your name in, and add your princples. Then share the link with your team in Slack and let them know you've kicked it off. 26 | 27 | The second way is a more hands on option. If you think your team might enjoy and benefit from working collaboratively together on your team design principles, you could setup a 45 minute design principles workshop together to kick it off! 28 | 29 | Don't worry, there are [facilitation guidelines](#facilitating-a-design-principles-workshop-with-your-team) below and it's a pretty simple exercise. The benfit of this option is that it gives your team a chance to come together synchronously and think from the same starting point. It does require everyone having time in their schedule to meet this way, so please be sure to check with your team (or team manager) out of consideration before you plan it. 30 | 31 | ## Facilitating a design principles workshop with your team 32 | 33 | If you've decided to do a design principles workshop, here are some recommendations for format and how to facilitate it. Feel free to customize your experience, these are just general guidelines, not rules. :wink: 34 | 35 | - Find a time that works for your whole team to meet for 45-60 minutes (45 minutes is a nice block to aim for, plus it gives you some buffer if conversation goes over). 36 | - Prior to the session, open a pull request in this repo to add a placeholder file for your team's principles. 37 | - Start the exercise by reviewing what design principles are, and take a look at some of the existing examples together (you could review some of our team's existing principles, and some of the examples from prior art). *Approx 10 minutes* 38 | - Next, set a timer, for 15 minutes and give everyone a chance to write their own principles (playing some [chill music](https://soundcloud.com/search?q=chill%20hop) can be a nice touch for this part). *15 min* 39 | - Consider using a collaborative space where everyone can work together, like a Google Doc, a Quip file, or a post-it notes board in [Whimsical](https://whimsical.com/). For example, when we did this exercise with the design group, our space [looked like this](https://www.dropbox.com/s/mw66r9rjsmagljc/Screen%20Shot%202020-09-02%20at%208.27.11%20AM.png?dl=0). 40 | - Refer to the [getting started questions](#getting-started-questions) to help give your team a baseline to build their principles from. 41 | - Finally, once everone has finished writing their principles, take the remaining time to let each team member share their principles and any comments or context they'd like to provide. *Aprox 15-25 min* 42 | - After the session, invite your team to add their principles to your team's file in the repository. As the facilitator you could offer to add principles for anyone who is not entirely comfortable with editing files on GitHub, or offer to walk them through it so they can learn. It's also helpful to encourage team members to add their own principles so they can feel a sense of ownership in the shared project artifact, and so they can feel comfortable with editing the file later as they refine their principles. 43 | 44 | If you have any questions about facilitating the exercise, or anything else related to this project, feel free to ping [@jglovier](http://github.com/jglovier/) or another member of the design team for help. :smile: 45 | 46 | ## Getting started questions 47 | 1. What guiding principles do you use in your practice of design creation that would be helpful to codify into a principle? 48 | 2. What patterns have you noticed in executing work with your team that would be helpful to acknowledge and codify into a principle? 49 | 3. What external constraints do we regularly face that would be helpful to account for by codifying into a principle? 50 | 4. What measures of success do we use that would be helpful to codify into a principle? 51 | 5. What values do we have that could be helpful to codify into a principle? 52 | 53 | ### Prior art 54 | - [The Zen of Python](https://legacy.python.org/dev/peps/pep-0020/) 55 | - [Taste and The Zen of GitHub](https://warpspire.com/posts/taste) 56 | - [The Zen of GitHub](https://ben.balter.com/2015/08/12/the-zen-of-github/) 57 | -------------------------------------------------------------------------------- /principles/design-team.md: -------------------------------------------------------------------------------- 1 | ## Joel's principles 2 | (*needs some consolidation*) 🙈 3 | - Identify the jobs a feature or workflow needs to solve. Don't give the feature/workflow/UI component too many jobs (keep a relatively simple mapping of job to component). 4 | - Identify constraints and work within them. ("Embrace constraints") 5 | - Always be shipping. 6 | - Iterate often. 7 | - Favor unblocking over blocking. 8 | - Design is a communication tool, not just implementation instructions. Use design to drive the conversation, and help people communicate their vision. 9 | - Favor unblocking over blocking. Momentum is precious. 10 | - Disagree and commit. 11 | - Simplify wherever possible. Aim for approachable when simple is not possible. 12 | - Time is of the essence. 13 | - Focus on workflows, not features. 14 | - Workflows happen in the context of story, so be sure to tell the story. 15 | - Show what's possible. Dream big. 16 | - User research is everyone's responsiblity. We are all advocates for our customers. 17 | - Prioritize customers problems over theoretical use cases. 18 | - Anything added dilutes everything else. 19 | - Throughput beats perfection. 20 | - Shorten the journey by removing friction. 21 | - All feedback is a gift. 22 | - Suprise and delight. 23 | - Use whimsey to create a fun space to work. 24 | - Copy is UI too. 25 | - Embrace the journey. The best experiences are often cultivated over time, not simply launched at once. 26 | - Listen carefully to others, listen for their perspective and look at what they are seeing, and include it in your own perspective. Tell a compelling story, and bring everyone along for the ride. 27 | - Shaping the product by giving it form. Distinction helps the shaping, and helps users become familiar with the shape. Lack of form, shape, and distinction makes it easy to get lost. 28 | 29 | ## Danielle's principles 30 | 31 | - The details make the cake. Micro interactions matter. 32 | - "Anyone Can Design" –– as in, great ideas and inspiration can come from anywhere and unexpected places. 33 | - "Whack the moles". We should fix small, easy wins on the spot instead of walking by them. 34 | - Disagree and commit. 35 | - Ship and iterate. The work is never done, but it's good to know when to stop. 36 | - Favor doing over deliberating (asking forgiveness, not permission). 37 | - Sometimes you have to prototype something to really know what it feels like. 38 | - Don't reinvent the wheel. Use browser APIs and other existing systems when possible. 39 | 40 | ## Zari's principles 41 | 42 | - Design is a partner, not a service 43 | - Consistent is better than custom 44 | - Overcommunication is better than ambiguity 45 | - Showing/disabling is better than hiding 46 | - Just because you can, doesn't mean you should 47 | - Never lose sight of the new user when designing for the power user 48 | - The work is never done, but it's good to know when to stop 49 | - Asking questions demonstrates strength, not ignorance 50 | - Accessibility is not optional 51 | 52 | ## Tim's principles 53 | 54 | - Determine user needs first. 55 | - Consistency is key. 56 | - Try things, learn, and iterate later. 57 | - Solicit feedback shamelessly. 58 | - Make (informed) decisions for users. 59 | - Great products offer simplicity and transparency. 60 | - Don't aim for "Wow!" Aim for "Of course!" 61 | - Scalability matters. Design for the future. 62 | - Obvious--and preferably singular--solutions. 63 | 64 | ## Carlos' principles 65 | - Empower others. 66 | - Take in to consideration your user’s mental model. 67 | - Transparency over ambiguity. 68 | - Fail fast, fail early. 69 | - Aim to minimize the possibility of errors but they are bound to happen, help users overcome them. 70 | - Don’t be afraid of change. 71 | - It's never a bad time for feedback. 72 | 73 | ## Desiree's principles 74 | - Strive for intuitive solutions 75 | - Design for everyone, understand accessibility 76 | - Always seek feedback 77 | - Details make the experience 78 | - Be mindful of the design process 79 | - Be consistent, not uniform 80 | 81 | ## Ana's principles 82 | - Ethical design helps us move beyond empathy and towards compassion for the user 83 | - Focus on inclusive design, on creating access and preventing (or removing) obstacles 84 | - Ensure every design decision, no matter how small, is rooted in intentionality and advocacy 85 | - Consider accessibility from the start, and factor it into every decision 86 | - Prioritize functionality and must-haves, but remember that details matter 87 | - Focus on asking and answering *why* before moving into *how* 88 | - Design is a conversation—it's important to build and maintain our relationship with users (Ship → Learn → Iterate → Repeat!) 89 | - Design is a strategic business partner that can help drive impactful outcomes and metrics 90 | - Consistency and familiarity are essential (question/challenge patterns when appropriate) 91 | - Constraints are opportunities for creativity 92 | --------------------------------------------------------------------------------