brainly / style-guide

:art: Brainly Front-End Style Guide

This project is a living style guide of all basic front-end components used at Brainly.

Documentation

Documentation is an esential part of this project. You can see its latest version on styleguide.brainly.com. New version of the docs is deployed with every merge to master. You can also browse older versions by changing version number in the URL. Documentation is splitted into four sections:

• Basics - colors, fonts, icons, simple components
• Components - complex components
• Containers - components that host other components
• Interactive - interactive version of the style guide docs that we are experimenting with

Storybook

Current version of storybook is hosted under following dev URL - styleguide.brainly.com

How to use it

All components can be used in both HTML and JSX. In both cases you have to include main CSS file, as described on the main docs page, in the head section of your page. In case of HTML, you just have to follow style-guide markup which you can easily copy by clicking on any component in the docs. If you prefer to use React instead, you'll have to add this repository as a dependency in package.json and import components into your JSX file.

Supported Browsers

We officially support the following browsers (based on real user trafic from our analytics):

Browser	Versions
Google Chrome	28+
Safari	7+
Samsung Internet	1.1+
YaBrowser	15+
Android Webview	30+
Firefox	42+
UCBrowser	8+
Android Browser	4.0+
Opera	33+
Opera Mini	7+
Edge	12+

Note: You can find all recent stats in our analytics (INTERNAL)

Contributing

We welcome all issue reports and pull requests ❤️ If you'd like to contribute, please start with this doc.

Caveats

• Package "s3" has been forked to @brainly organization. One of dependencies of this package (graceful-fs) was causing our builds to fail. Since this package is no longer maintained, we decided to fork it and make needed updates. As a long-term solution, we need to switch "s3" package to something more up-to-date.

Codemods

We created a CLI tool that runs codemods with jscodeshift to batch refactor code. Usage:

yarn sg-codemod [...options]

where options are:

• --help - display help
• --dry - dry run (no changes are made to files)
• --glob - use glob pattern to match files
• --jscodeshift - pass options directly to jscodeshift

Read more here.

style-guide's Issues

Add an modifier for footer with ad

Designing containers

We should bear in mind (and tell out designers), that any container should be designed for this cases:

• zero children
• one children
• many children

The same goes for text containers, it will help handle overflows.

.mint-button-secondary--peach-inverse should have white background

See legacy-api project for backport

Fix button with stars

On hovering over first area one star should be active, on second 5 stars should be active

New avatars

Avatars have changed.
See brainly/web-client#111 and brainly/symfony#1511 https://github.com/brainly/symfony/issues/1624
brainly/web-client#103

Summ up:

• Change sizes
• Change default avatar icon

Edit:
According to Janusz:
Ok. Final decision is: we have three sizes of avatars:

1. 24px with 1px border inside
2. 32px with 1px border inside
3. 48px with 2px border inside

Add @fix-font mixin to deal with text centering

We have a problem with our font's baseline (and all general labels we have): the line-height and font-size does not play well together, forcing the baseline to shift 1px.

If we fix line-height, font-size and height of the text wrapping elements we can get more precise centering (see gray area for the rightmost number):

Create icons components

Icons can be wrapped in elements with predefined color, so that we can use actual elements instead of :before and have centralized styles for icons

Stickers on avatars are a bit to high

It broke after some laetest changes in master (buttons refactor?).

Buttons do not have mint- prefix

@aju @mr-mig
Other elements come with the mint- prefix, but buttons does not.
We should fix this IMO

buttons, vertical-align:inherit

vertical-align: inherit should be changed for buttons as it ruins alignment:

'Rating' and 'Thanks' buttons do not scale correctly

Change badge to not use vertical-alignment

New colors to styleguide

We should add colors used in dropdowns (mint-select) to basic palette

Text Bit in black color

Text Bit in black color (used in tasks/landing in symfony)

Add logo for small devices

Clarify the approach for mobile/non-mobile components

If the element is a part of container, then the hole in the container can have mint-hidden-for-desktop applied
If the element has two different forms on mobile/desktop, or it has different parts visible - then it's better to hide those parts with the breakpoints inside the component

Does it make sense?

See here:
https://github.com/brainly/symfony/pull/1679/files#diff-9aa9b1ef9b373bcfcaa5a2900c65fce6R8

Add variables for media queries

This stuff would be really needed as soon as we start mobile-first approach

Add separator

It should be 1px dotted $grayPrimary, used mainly in streams

home-button component should be called mint-home-button

🍭

Vertical rhytm

It would be really cool to define vertical rhytm in the styleguide.

You can find an example here:
http://www.sitepoint.com/using-sass-build-custom-type-scale-vertical-rhythm/
http://typecast.com/blog/4-simple-steps-to-vertical-rhythm

We will need this stuff as a baseline for mobile-first components in BEM.

Example:

.bem-block {
  @include base-font(); // <--- this should define the vertical rhythm in the component with relevant media queries
}

Fix indent in atoms

User nick should have 16px margin to avatar.
Text content below should be in the same line with user nick.

Check behaviour of context-box container for mobile

See overflow issues on brainly/web-client#119

Colors on buttons (states)

We need to review states of buttons (border and icon colors), Joanna proposed inversion of current colors (border darker on active/focus the same as on inputs). Also we need to discuss how "best" button should act on active/hover etc.

cc. @matzimowski

Add new colors in styleguide

See https://github.com/brainly/symfony/issues/1657 and #142

We need to change name for those gray colors like grayText, grayElementBorder, etc

subject icons should not be separate

IMO subject icons should be just added to the default icon set. I don't see any reason to keep them separate. Also, currently they are made using background-image instead of content: '' which makes it impossible to change their color (if we'll ever need that).

Andrzej's argument was that subjects are used only on the main page so we don't have to load them for ppl only visiting the question page reducing page size. Hovers, IMO that's a premature optimization and judging from the mocks, the assumption that subjects are used only on the main page wasn't true:

Moving components variables to the components

I think it would be better to move components variables to component scss file. Things like $buttonFont: $mintFontPrimary;

The benefits we get:

• Components and their "settings" are encapsulated in a single file
  • Easier to reason about variable dependencies
  • Easier to change component-related configuration
  • Easier to grasp component parameterization
• Global configuration is separated from local

WDYT? @kdzwinel @aju @matzimowski @vergilius

Change font-size for input element

See brainly/symfony#1567 for details

New size for subject icons: 24px

See https://github.com/brainly/symfony/issues/1649

Create icons components

Icons can be wrapped in elements with predefined color, so that we can use actual elements instead of :before and have centralized styles for icons

Remove defs/style from svg's

SVG's are generated with unnecessary piece of code that adds weight to it

Text padding issue

When we have a text elements (e.g. mint-text-description) or a container with text content (see mint-content-box__content), we have a problem with padding.

According to mockup, the exact padding between text and avatars is 12px:

But in HTML we have additional padding for text, which cannot be overriden (smth like 1-2px).
Additionaly we have the offset for the font baseline approx. 2-3px.
You can see how those padding add up to 12px gap giving us unconsistend paddings for text content:

Use mint-logo for not logged in user main page header

Badge animation breaks avatars

While badge animation (katie) is running avatars are square instead of round. Reproducible on the styleguide components page.

Add code quality tools

Smth like https://github.com/brigade/scss-lint to eliminate unused variables/duplicates...

Add default height to all components

We have problems in some cases trying to align different components vertically as they tend to have very weird and different heights, like 18px and 19px (this is magnified by font issues, when baseline get 1px at the top or bottom depending on oddness of the font size).

I'd propose to add explicit height to the @component so that we have at least some default height for all things.

Flex-box for layouting

I would propose to use flexbox styles for vertical and inline positioning of components (push to left/right/botton, centering) instead of relying on inline-block + position/vertical-align.

Refactor buttons to be containers

A button should be a container with a label/textblock inside

Generic "holes" for containers with unlimited number of components in a single row

I'd propose to have a &__hole element for every container in those sections, which can hold multiple (and dynamic) number of items. Think of it as it is li with fixed margin/padding for all holes except first-child.

WDYT?

Make all :before-based icons `display:block`

If icons will remain inline-block they inherit the baseline and get additional pixels at top/bottom, which ruins the vertical centering.

We need to make all icons to be display:block to get closer to pixel-perfect centering

Add text-decoration: none for buttons

Every state focus, hover, active should have no text decoration. We need this for the case when buttons are links.

floating + button - make link a block element

Default spacing for content-box

content-box is being used all over the place in web-client and I have to set margins/padding/etc. by hand. We should have these in the styleguide.

Discussion: https://github.com/brainly/web-client/pull/90

Remove old logo files

Hi,

I thing it's better to serve #404 error than old logo.
So please remove all files with logo :)

Remove text decoration for buttons

In case links are used a button elements there is an underline, which looks weird...

@component override line-height

Fix docs to use resources from src

Create set of font sizes

We need to make new font sizes for mobile devices and discuss it with designers.

Change docs-block to have flexbox display

We've checked this snippet:

.docs-block {
    display: flex;
    flex-wrap: wrap;
    align-items: flex-start;
}

It works ok but requires some changes to the htmls and some element fixes

Having a single %component placeholder

Given a nature of components we have, it seems we can base all our block on smth like that:

%component {
  box-sizing: border-box;
  display: inline-block;
  position: relative;
  overflow: hidden;
  text-overflow: ellipsis;
}

WDYT?
Do we need to add resets there as well?

icon-as-a-button with rotated icon does not work on Firefox

For specific font sizes (e.g. 18px) you get this:

instead of this: