diff options
| author | Valery Sizov <valery@gitlab.com> | 2016-12-14 12:36:27 +0200 |
|---|---|---|
| committer | Valery Sizov <valery@gitlab.com> | 2016-12-14 12:36:27 +0200 |
| commit | 468d575fc73881900f4a4cb1fa71c187d77429a7 (patch) | |
| tree | 05b00d7f00e04202c34de41e6feb566426e19e3f /doc/development | |
| parent | 8f0cef0b6e5e950efdf3ebfe8f9f846095fff9d9 (diff) | |
| parent | 78f89f7ad900ec2f2993a70caa2eb5dbf9e2496f (diff) | |
| download | gitlab-ce-468d575fc73881900f4a4cb1fa71c187d77429a7.tar.gz | |
Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into bitbucket-oauth2
Diffstat (limited to 'doc/development')
43 files changed, 120 insertions, 107 deletions
diff --git a/doc/development/code_review.md b/doc/development/code_review.md index c5c23b5c0b8..1ef34c79971 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -70,10 +70,36 @@ experience, refactors the existing code). Then: - After a round of line notes, it can be helpful to post a summary note such as "LGTM :thumbsup:", or "Just a couple things to address." - Avoid accepting a merge request before the build succeeds. Of course, "Merge - When Build Succeeds" (MWBS) is fine. -- If you set the MR to "Merge When Build Succeeds", you should take over + When Pipeline Succeeds" (MWPS) is fine. +- If you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. +## The right balance + +One of the most difficult things during code review is finding the right +balance in how deep the reviewer can interfere with the code created by a +reviewee. + +- Learning how to find the right balance takes time; that is why we have + minibosses that become merge request endbosses after some time spent on + reviewing merge requests. +- Finding bugs and improving code style is important, but thinking about good + design is important as well. Building abstractions and good design is what + makes it possible to hide complexity and makes future changes easier. +- Asking the reviewee to change the design sometimes means the complete rewrite + of the contributed code. It's usually a good idea to ask another merge + request endboss before doing it, but have the courage to do it when you + believe it is important. +- There is a difference in doing things right and doing things right now. + Ideally, we should do the former, but in the real world we need the latter as + well. A good example is a security fix which should be released as soon as + possible. Asking the reviewee to do the major refactoring in the merge + request that is an urgent fix should be avoided. +- Doing things well today is usually better than doing something perfectly + tomorrow. Shipping a kludge today is usually worse than doing something well + tomorrow. When you are not able to find the right balance, ask other people + about their opinion. + ## Credits Largely based on the [thoughtbot code review guide]. diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 7bfc9cb361f..0f78e8238af 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -141,51 +141,3 @@ in an initializer._ ### Further reading - Stack Overflow: [Why you should not write inline JavaScript](http://programmers.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting) - -## ID-based CSS selectors need to be a bit more specific - -Normally, because HTML `id` attributes need to be unique to the page, it's -perfectly fine to write some JavaScript like the following: - -```javascript -$('#js-my-selector').hide(); -``` - -However, there's a feature of GitLab's Markdown processing that [automatically -adds anchors to header elements][ToC Processing], with the `id` attribute being -automatically generated based on the content of the header. - -Unfortunately, this feature makes it possible for user-generated content to -create a header element with the same `id` attribute we're using in our -selector, potentially breaking the JavaScript behavior. A user could break the -above example with the following Markdown: - -```markdown -## JS My Selector -``` - -Which gets converted to the following HTML: - -```html -<h2> - <a id="js-my-selector" class="anchor" href="#js-my-selector" aria-hidden="true"></a> - JS My Selector -</h2> -``` - -[ToC Processing]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/lib/banzai/filter/table_of_contents_filter.rb#L31-37 - -### Solution - -The current recommended fix for this is to make our selectors slightly more -specific: - -```javascript -$('div#js-my-selector').hide(); -``` - -### Further reading - -- Issue: [Merge request ToC anchor conflicts with tabs](https://gitlab.com/gitlab-org/gitlab-ce/issues/3908) -- Merge Request: [Make tab target selectors less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2023) -- Merge Request: [Make cross-project reference's clipboard target less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2024) diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md new file mode 100644 index 00000000000..daeb15460c2 --- /dev/null +++ b/doc/development/ux_guide/animation.md @@ -0,0 +1,42 @@ +# Animation + +Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. + +## Timings + +The longer distance an object travel, the timing should be longer for the animation. However, when in doubt, we should avoid large, full screen animations. + +Subtle animations, or objects leaving the screen should take **100-200 milliseconds**. Objects entering the screen, or motion we want to use to direct user attention can take between **200-400 milliseconds**. We should avoid animations of longer than 400 milliseconds as they will make the experience appear sluggish. If a specific animation feels like it will need more than 400 milliseconds, revisit the animation to see if there is a simpler, easier, shorter animation to implement. + +## Easing + +Easing specifies the rate of change of a parameter over time (see [easings.net](http://easings.net/)). Adding an easing curve will make the motion feel more natural. Being consistent with the easing curves will make the whole experience feel more cohesive and connected. + +* When an object is entering the screen, or transforming the scale, position, or shape, use the **easeOutQuint** curve (`cubic-bezier(0.23, 1, 0.32, 1)`) +* When an object is leaving the screen, or transforming the opacity or color, no easing curve is needed. It shouldn't _slow down_ as it is exiting the screen, as that draws attention on the leaving object, where we don't want it. Adding easing to opacity and color transitions will make the motion appear less smooth. Therefore, for these cases, motion should just be **linear**. + +## Types of animations + +### Hover + +Interactive elements (links, buttons, etc.) should have a hover state. A subtle animation for this transition adds a polished feel. We should target a `200ms linear` transition for a color hover effect. + +View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here. + + + +### Dropdowns + +The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with a opacity animation `200ms linear` on the second half of the motion achieves this affect. + +View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here. + + + +### Quick update + +When information is updating in place, a quick, subtle animation is needed. The previous content should cut out, and the new content should have a quick, `200ms linear` fade in. + + + +> TODO: Add guidance for other kinds of animation
\ No newline at end of file diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md index 62ac56a6bce..76b739386a5 100644 --- a/doc/development/ux_guide/basics.md +++ b/doc/development/ux_guide/basics.md @@ -5,8 +5,6 @@ * [Typography](#typography) * [Icons](#icons) * [Color](#color) -* [Motion](#motion) -* [Voice and tone](#voice-and-tone) --- @@ -35,26 +33,15 @@ This is the typeface used for code blocks. GitLab uses the OS default font. ## Icons GitLab uses Font Awesome icons throughout our interface. - -The trash icon is used for destructive actions that deletes information. - - -The pencil icon is used for editing content such as comments. - - -The bell icon is for notifications, such as Todos. - - -The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. - - -The standard RSS icon is used for linking to RSS/atom feeds. - - -An 'x' is used for closing UI elements such as dropdowns. - - -A plus is used when creating new objects, such as issues, projects, etc. +| | | +| :-----------: | :---- | +|  | The trash icon is used for destructive actions that deletes information. | +|  | The pencil icon is used for editing content such as comments.| +|  | The bell icon is for notifications, such as Todos. | +|  | The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. | +|  | The standard RSS icon is used for linking to RSS/atom feeds. | +|  | An 'x' is used for closing UI elements such as dropdowns. | +|  | A plus is used when creating new objects, such as issues, projects, etc. | > TODO: update this section, add more general guidance to icon usage and personality, etc. @@ -62,33 +49,13 @@ A plus is used when creating new objects, such as issues, projects, etc. ## Color - -Blue is used to highlight primary active elements (such as current tab), as well as other organization and managing commands. - - -Green is for actions that create new objects. - - -Orange is used for warnings - - -Red is reserved for delete and other destructive commands - - -Grey, and white (depending on context) is used for netral, secondary elements +| | | +| :------: | :------- | +|  | Blue is used to highlight primary active elements (such as the current tab), as well as other organizational and managing commands.| +|  | Green is for actions that create new objects. | +|  | Orange is used for warnings | +|  | Red is reserved for delete and other destructive commands | +|  | Grey is used for neutral secondary elements. Depending on context, white is sometimes used instead. | > TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. ---- - -## Motion - -Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. - -> TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. - ---- - -## Voice and tone - -The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index 8e51edd23ef..28383ad7dfc 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -75,10 +75,29 @@ Text should be in sentence case, where only the first word is capitalized. "Crea > TODO: Rationalize this. Ensure that we still believe this. ### Colors -Follow the color guidance on the [basics](basics.md#color) page. The default color treatment is the white/grey button. +The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button. + +### Secondary states + +Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed. + +| Values | Info | Success | Warning | Danger | +| :------ | :------: | :------: | :------: | :------: | +| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  |  | +| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  |  | +| Background: `$color-dark` <br> Border: `$border-color-dark` |  |  |  |  | + +Since secondary buttons only have a border on their resting state, their hover and focus states add a background color, which gets darkened on active. + +| Values | Success Secondary | Close | Spam | +| :------ | :------: | :------: | :------: | +| Font: `$border-color-light` <br> Border: `$border-color-light` |  |  |  | +| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  | +| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  | --- + ## Dropdowns Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.) diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index b557fb47120..8896d450f14 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -1,6 +1,8 @@ # Copy -The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab. +The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. + +The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab. >**Note:** We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align. diff --git a/doc/development/ux_guide/img/animation-dropdown.gif b/doc/development/ux_guide/img/animation-dropdown.gif Binary files differnew file mode 100644 index 00000000000..c9b31d26165 --- /dev/null +++ b/doc/development/ux_guide/img/animation-dropdown.gif diff --git a/doc/development/ux_guide/img/animation-hover.gif b/doc/development/ux_guide/img/animation-hover.gif Binary files differnew file mode 100644 index 00000000000..37ad9c76828 --- /dev/null +++ b/doc/development/ux_guide/img/animation-hover.gif diff --git a/doc/development/ux_guide/img/animation-quickupdate.gif b/doc/development/ux_guide/img/animation-quickupdate.gif Binary files differnew file mode 100644 index 00000000000..8db70bc3d24 --- /dev/null +++ b/doc/development/ux_guide/img/animation-quickupdate.gif diff --git a/doc/development/ux_guide/img/button-close--active.png b/doc/development/ux_guide/img/button-close--active.png Binary files differnew file mode 100644 index 00000000000..824bfc8f31b --- /dev/null +++ b/doc/development/ux_guide/img/button-close--active.png diff --git a/doc/development/ux_guide/img/button-close--hover.png b/doc/development/ux_guide/img/button-close--hover.png Binary files differnew file mode 100644 index 00000000000..0291e121894 --- /dev/null +++ b/doc/development/ux_guide/img/button-close--hover.png diff --git a/doc/development/ux_guide/img/button-close--resting.png b/doc/development/ux_guide/img/button-close--resting.png Binary files differnew file mode 100644 index 00000000000..986d7174ce7 --- /dev/null +++ b/doc/development/ux_guide/img/button-close--resting.png diff --git a/doc/development/ux_guide/img/button-danger--active.png b/doc/development/ux_guide/img/button-danger--active.png Binary files differnew file mode 100644 index 00000000000..d3c64424b26 --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--active.png diff --git a/doc/development/ux_guide/img/button-danger--hover.png b/doc/development/ux_guide/img/button-danger--hover.png Binary files differnew file mode 100644 index 00000000000..8506e093306 --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--hover.png diff --git a/doc/development/ux_guide/img/button-danger--resting.png b/doc/development/ux_guide/img/button-danger--resting.png Binary files differnew file mode 100644 index 00000000000..69ad6bb796b --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--resting.png diff --git a/doc/development/ux_guide/img/button-info--active.png b/doc/development/ux_guide/img/button-info--active.png Binary files differnew file mode 100644 index 00000000000..23be20b225c --- /dev/null +++ b/doc/development/ux_guide/img/button-info--active.png diff --git a/doc/development/ux_guide/img/button-info--hover.png b/doc/development/ux_guide/img/button-info--hover.png Binary files differnew file mode 100644 index 00000000000..4cb4e38558c --- /dev/null +++ b/doc/development/ux_guide/img/button-info--hover.png diff --git a/doc/development/ux_guide/img/button-info--resting.png b/doc/development/ux_guide/img/button-info--resting.png Binary files differnew file mode 100644 index 00000000000..5883340aa83 --- /dev/null +++ b/doc/development/ux_guide/img/button-info--resting.png diff --git a/doc/development/ux_guide/img/button-spam--active.png b/doc/development/ux_guide/img/button-spam--active.png Binary files differnew file mode 100644 index 00000000000..55b44898684 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--active.png diff --git a/doc/development/ux_guide/img/button-spam--hover.png b/doc/development/ux_guide/img/button-spam--hover.png Binary files differnew file mode 100644 index 00000000000..3dc8ed34c54 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--hover.png diff --git a/doc/development/ux_guide/img/button-spam--resting.png b/doc/development/ux_guide/img/button-spam--resting.png Binary files differnew file mode 100644 index 00000000000..b6bf10a5b64 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--resting.png diff --git a/doc/development/ux_guide/img/button-success--active.png b/doc/development/ux_guide/img/button-success--active.png Binary files differnew file mode 100644 index 00000000000..895a52831cb --- /dev/null +++ b/doc/development/ux_guide/img/button-success--active.png diff --git a/doc/development/ux_guide/img/button-success--hover.png b/doc/development/ux_guide/img/button-success--hover.png Binary files differnew file mode 100644 index 00000000000..e4c74bd9778 --- /dev/null +++ b/doc/development/ux_guide/img/button-success--hover.png diff --git a/doc/development/ux_guide/img/button-success--resting.png b/doc/development/ux_guide/img/button-success--resting.png Binary files differnew file mode 100644 index 00000000000..2fa971b5347 --- /dev/null +++ b/doc/development/ux_guide/img/button-success--resting.png diff --git a/doc/development/ux_guide/img/button-success-secondary--active.png b/doc/development/ux_guide/img/button-success-secondary--active.png Binary files differnew file mode 100644 index 00000000000..e7383b36946 --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--active.png diff --git a/doc/development/ux_guide/img/button-success-secondary--hover.png b/doc/development/ux_guide/img/button-success-secondary--hover.png Binary files differnew file mode 100644 index 00000000000..4af2a68cf1b --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--hover.png diff --git a/doc/development/ux_guide/img/button-success-secondary--resting.png b/doc/development/ux_guide/img/button-success-secondary--resting.png Binary files differnew file mode 100644 index 00000000000..a5a4ec512c8 --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--resting.png diff --git a/doc/development/ux_guide/img/button-warning--active.png b/doc/development/ux_guide/img/button-warning--active.png Binary files differnew file mode 100644 index 00000000000..5877d46c94d --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--active.png diff --git a/doc/development/ux_guide/img/button-warning--hover.png b/doc/development/ux_guide/img/button-warning--hover.png Binary files differnew file mode 100644 index 00000000000..308e1adc8a3 --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--hover.png diff --git a/doc/development/ux_guide/img/button-warning--resting.png b/doc/development/ux_guide/img/button-warning--resting.png Binary files differnew file mode 100644 index 00000000000..28e5e601520 --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--resting.png diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png Binary files differindex 2ca360173eb..844e926f1f5 100644 --- a/doc/development/ux_guide/img/color-blue.png +++ b/doc/development/ux_guide/img/color-blue.png diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png Binary files differindex 489db8f4343..5c4c23c7067 100644 --- a/doc/development/ux_guide/img/color-green.png +++ b/doc/development/ux_guide/img/color-green.png diff --git a/doc/development/ux_guide/img/color-grey.png b/doc/development/ux_guide/img/color-grey.png Binary files differindex 58c474d5ce9..5247649a0ce 100644 --- a/doc/development/ux_guide/img/color-grey.png +++ b/doc/development/ux_guide/img/color-grey.png diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png Binary files differindex 4c4b772d438..1103c715225 100644 --- a/doc/development/ux_guide/img/color-orange.png +++ b/doc/development/ux_guide/img/color-orange.png diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png Binary files differindex 3440ad48f05..77ecbbc0a20 100644 --- a/doc/development/ux_guide/img/color-red.png +++ b/doc/development/ux_guide/img/color-red.png diff --git a/doc/development/ux_guide/img/icon-add.png b/doc/development/ux_guide/img/icon-add.png Binary files differindex 0d4c1a7692a..bcad5e84591 100644 --- a/doc/development/ux_guide/img/icon-add.png +++ b/doc/development/ux_guide/img/icon-add.png diff --git a/doc/development/ux_guide/img/icon-close.png b/doc/development/ux_guide/img/icon-close.png Binary files differindex 88d2b3b0c6d..dfe1495f5fa 100644 --- a/doc/development/ux_guide/img/icon-close.png +++ b/doc/development/ux_guide/img/icon-close.png diff --git a/doc/development/ux_guide/img/icon-edit.png b/doc/development/ux_guide/img/icon-edit.png Binary files differindex f73be7a10fb..50f6f841868 100644 --- a/doc/development/ux_guide/img/icon-edit.png +++ b/doc/development/ux_guide/img/icon-edit.png diff --git a/doc/development/ux_guide/img/icon-notification.png b/doc/development/ux_guide/img/icon-notification.png Binary files differindex 4758632edd7..6ddfaa44f66 100644 --- a/doc/development/ux_guide/img/icon-notification.png +++ b/doc/development/ux_guide/img/icon-notification.png diff --git a/doc/development/ux_guide/img/icon-rss.png b/doc/development/ux_guide/img/icon-rss.png Binary files differindex c7ac9fb1349..b766488b32d 100644 --- a/doc/development/ux_guide/img/icon-rss.png +++ b/doc/development/ux_guide/img/icon-rss.png diff --git a/doc/development/ux_guide/img/icon-subscribe.png b/doc/development/ux_guide/img/icon-subscribe.png Binary files differindex 5cb277bfd5d..650168296c6 100644 --- a/doc/development/ux_guide/img/icon-subscribe.png +++ b/doc/development/ux_guide/img/icon-subscribe.png diff --git a/doc/development/ux_guide/img/icon-trash.png b/doc/development/ux_guide/img/icon-trash.png Binary files differindex 357289a6fff..b02178ca992 100644 --- a/doc/development/ux_guide/img/icon-trash.png +++ b/doc/development/ux_guide/img/icon-trash.png diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md index 8aed11ebac3..8a849f239dc 100644 --- a/doc/development/ux_guide/index.md +++ b/doc/development/ux_guide/index.md @@ -12,7 +12,17 @@ These guiding principles set a solid foundation for our design system, and shoul --- ### [Basics](basics.md) -The basic ingredients of our experience establish our personality and feel. This section includes details about typography, color, and motion. +The basic ingredients of our experience establish our personality and feel. This section includes details about typography, iconography, and color. + +--- + +### [Animation](animation.md) +Guidance on the timing, curving and motion for GitLab. + +--- + +### [Copy](copy.md) +Conventions on text and messaging within labels, buttons, and other components. --- @@ -26,11 +36,6 @@ The GitLab experience is broken apart into several surfaces. Each of these surfa --- -### [Copy](copy.md) -Conventions on text and messaging within labels, buttons, and other components. - ---- - ### [Features](features.md) The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. |
