lets find another way to do this: https://github.com/mapbox/base-core/blob/c556b84dc4240eced6a61d25a5492a8b82033cfa/base-core.css#L84

Let's create a documentation page for best practices.

Principles:

• Try to stick with 20px baseline grid
• .prose class for 'prose' styled text elements, otherwise keep all text elements unstyled.
• light + regular headlines https://github.com/mapbox/www.mapbox.com/blob/mb-pages/css/base/latest/base.css#L134-L150

The only SVGs we have right now are dummy icons I downloaded to get the icon system going. We'll need to real ones.

Do we want to continue using an icon font, or has that worn on people?

I only know of one alternative that provides the same sizing/coloring flexibility (more, actually): I've had great success in the past with the icon system described here — create a file of <defs> and use icons with <use>. However, I know of two problems for our purposes:

In order to use the icon, you have to do something like this in HTML:

<svg><use xlink:href="#shape-codepen"></use></svg>

A little ugly. With React it's totally fine because you can create an Icon component. But we're not building this for React. Might be tolerable, though, if we all just keep a stiff upper lip. Looks like Material Design does this.

Another problem is that the SVG sprite file doesn't load itself, so base users would have to include a JS file or copy-paste some JS — OR if we are comfortable making base only work with JS enabled, we could deliver base.js instead of base.css and make that script load the CSS and the SVGs.

As we rebuild base, lets build a set of 'ideal use cases' and make sure they work great. use-cases include:

• Brochure page (like mapbox.com)
• App with left-aligned toolbar and condensed form (like studio)
• Data dashboard
• Full-width signup form with lots of options
• Blog feed with images that bleed out from left and right
• Documentation site with scrolling left sidebar

Right now I have positioning rules that look like this:

/**
 * Positioning utility classes
 * @namespace Positioning
 * @memberof Utilities
*/
.fix { position: fixed; }
.abs { position: absolute; }

/*
Zero out positioning
*/
.top    { top: 0; }
.right  { right: 0; }
.left   { left: 0; }
.bottom { bottom: 0; }

so instead of pin-topright, you'd write abs top right. I think this is nice, but it sorta breaks the rules. abs pos-top pos-right would be more aligned with convention.

By "aligning curly braces" I mean this:

.bg-blue   { background-color: #0077cc; }
.bg-purple { background-color: #5500cc; }

instead of this:

.bg-blue { background-color: #0077cc; }
.bg-purple { background-color: #5500cc; }

Here are some disadvantages, I think:

• You have to do it.
• It's easy to mess up but hard to automatically enforce.
• Diffs are less useful when you add a new, longer-named class but end up changing several unrelated lines by one space because of the new positioning (if you remember).
• You have to ask yourself questions about when to align what with what, e.g. after line breaks — instead of not thinking about it at all.

I don't know of any advantages (?).

So, I guess I'm in favor of using an easily-enforceable, no-thought-required convention of putting the curly brace one space after the selector. What do you think?

Widths and heights

Double or single?

@tristen you probably have some strong feelings?

tablet-pad-top-5 or pad-top-5-tablet?

I'm running into some troubles caused by the multiple-repository approach.

1. The build process in place here in base-core is presumably going to have to be duplicated in base-mapbox. That's a pain, right? (cc @samanpwbb)
2. I wonder if we should move the documentation generator code into this repository? That way we can

• Use base v2 for its theme as we build it. It's kind of a weird problem for a CSS documentation generator, actually, that it might require CSS for a theme that breaks the documented CSS, or the other way around.
• Not worry about genericizing.
• Not worry about versioning.
  @tmcw

Do we think that open-sourcing parts of base is worth these troubles? Or do you see a way to make these troubles less troublesome?

examples:

col-* for col rules
mar-* for margin rules
pad-* for pad rules
fix for fixed positioning

Being strict about 3 character rule will make rules easier to remember.

We need to decide if we're serious about following through on #26 and other class naming convention proposals, and then get the linting to start passing. We're still committing code willy-nilly that we will just need to go back and modify later. Most of our CSS rules are simple enough that they're only worth writing the right way, once, rather than revisiting a bunch of times.

Here's our selector-class-pattern right now:

/^[a-z]+$|^[a-z]{3}-((?!md-|sm-|lg-)[a-z-]*)[0-9]*(-sm|-md|-lg)?$/

This says (I think):

• Allow a single word, all lowercase, with no hyphens.
• Anything with hyphens must start with a 3 character prefix (#26).
• Sizes are suffixes, only allowed at the very end.
• Numbers are also suffixes, only allowed at the end, but before sizes.

My impression is that the only part of this that might be controversial right now is the 3 character prefix (correct me if I'm wrong!).

@samanpwbb thought:

Being strict about 3 character rule will make rules easier to remember.

Agree? Disagree?

Let's hash this out before we produce a lot more code we'll have to revise. (Either way, we'll need to revise ... e.g. I'd change .icn classes to .icon if we drop this rule.)

Menlo is ugly.

Anonymous: http://www.marksimonson.com/fonts/view/anonymous-pro
Source code pro: https://fonts.google.com/specimen/Source+Code+Pro
Inconsolata: http://levien.com/type/myfonts/inconsolata.html

the code class style is also pretty ugly. I wonder if we can add simple color options, like code text-red, code text-blue ....

• absolute positioning
• fixed positioning
• vertical and horizontal centering
• margins
• padding
• display types

Our mobile media query @media only screen and (max-width: 640px) is not sufficient. We need to be more specific. Same with tablet media query.

It's possible to include a min/max + an orientation: @media (max-width: 640px) and (orientation: portrait) { ... }.

Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries

Lets make this an issue for dropping in design patterns that current base is bad at.

Just a question. https://github.com/mapbox/base-core/blob/mb-pages/src/layout.css#L12

I think that everybody agreed it would be a good idea to use a linter (right?). stylelint is the open-source CSS linter that I created & lead-maintain. There are a lot of rules. I'm pretty sure it's the best around by a longshot (not much competition).

I suggest we start by copy-pasting stylelint-config-standard and then add, remove, and reconfigure rules as we work on the CSS together and find our groove.

(There are some editor plugins. I have experience using Atom's and it works great.)

Of all the things I'm least excited to type in class names, left, top, right, and bottom top the list.

If we're thinking we might want to take an abbreviated approach to classnames (e.g. with the 3-character prefix), how about abbreviating these words everywhere they occur with single letters?

Even if we don't restrict the prefix or don't abbreviate many other things, maybe this one is work doing, if we're 100% consistent, since those words get repeated quite a lot?

For JS build scripts.

for running the linter.

We could potentially duplicate every class across every media query. Where do we draw the line? I'm adding some basic positioning and display classes:

.inline { display: inline; }
.block { display: block; }
.inline-block { display: inline-block; }
.flex { display: flex; }
.hidden { display: none; }

hidden-sm, inline-sm, block-sm, inline-block-sm definitely make sense... flex-sm less so, but maybe. Do we need to tackle this case-by case? Where do we draw the line?

for base mapbox or mapbox logos base addon.

@mayagao is working on some design for this, I understand.

Here's a list of form elements I can think of:

• Label
• Input
• Select
• Text area
• Radio button
• Set of radio buttons (fieldset)
• Checkbox
• Set of checkboxes (fieldset)

Others?

I think we'll need regular and short styles.

We'll need disabled, hover, and focus states.

I know how we could use :checked to customize checkboxes and radio buttons, but that's going to require some kind of prescribed HTML pattern. Do people like the current pattern that requires the next sibling to be the label (esp. non-Studio folks)?

<!-- Next element must be the <label>  -->
<input id="checker" type='checkbox' class="frm-checkbox">
<label for="checker">Checkbox</label>

I don't think position: sticky is supported enough for use: http://caniuse.com/#search=sticky Am I missing something? https://github.com/mapbox/base-core/blob/487931c5353fc7cd9bccf466623a90e82ee2018c/src/positioning.css#L17

We talked about using Autoprefixer. That means we'll be running the CSS through a PostCSS pipeline — which means we could add other PostCSS plugins, if we want to.

There are a lot of PostCSS plugins, doing everything from approximating features of CSS spec drafts to all the stuff that Sass does. If something really annoys you about CSS and you can think of a way you think it should be done, that can probably happen with an existing or new PostCSS plugin.

Is anybody interested in any PostCSS plugins other than Autoprefixer?

(I want to hold off on offering my own opinions to listen to what others think.)

Base will be composed of at least two separate CSS stylesheets: base-core.css which will be in an open source repo, and base-mapbox.css which will be in a closed source repo at https://github.com/mapbox/base-mapbox.

The base-mapbox project will require base-core.css via NPM, and build base-combined.css. base-mapbox then will provide base-combined.css via NPM and also provide a hosted version of base-combined at mapbox.com/base-mapbox/{versionnumber}/base-combined.css.

This way, Mapbox team can easily take advantage of all of base without needing to reference two stylesheets or do any of the build steps themselves.

I found "Cabin" to be similar to Brandon but turns out it looks like a deflated version of Open Sans Bold. Ticketing as reminder to find something that is a little more visually appealing

Consider anything that isn't a single declaration a component.

Inline components should:

• be compostable into groups – i should be able to make a group with multiple buttons, a button and a text input, ect.
• optional left or right aligned icons
• optional left or right aligned labels
• 3 sizes: 20px high, 30px high, 40px high
• in some cases, combinable on a single element: a button checkbox should give me a checkbox that is visually styled like a button.

All form components should:

• have hover, active, disabled, and focus states
• be easy to nicely line up in a row, with labels and various form types, without hacky custom css. Look at studio's form UI for example. Will likely require flexbox layout.
• built-in subtle animations that can be cancelled out with something like a no-animate class.

Definites:

• Tooltips
• Modals
• Tabs
• Tables
• Buttons
• Text input
  • text input with button
  • text input with icon
  • text input with spinner
• textarea
• checkboxes (i like checkboxes that can be combined with buttons for checkbox buttons)
• rounded toggles
• radio buttons
• rage slider
• select buttons
• Video container for standard video sizes
• Special layout classes (like right-bleed-image)
• Navigation patterns
  • breadcrumb
  • underline links (like studio)
• Lists (esp. with icons to left)
• Loading spinner (large and small, compostable with form elements)

Maybes:

• tokens / "chips" (like https://cloud.githubusercontent.com/assets/108094/20930607/0bc4cd72-bb9c-11e6-8b38-d0760736a71a.png)
• Loading bar
• Nice blockquotes (see https://github.com/mapbox/blog/blob/88b2ee379e53fe9cc1517d78f76c85cdee9a606f/blog.css#L3-L46)

What rules do we all follow when writing styles for base.

• Specifically define a class naming convention. Something like BEM but that also resembles existing base naming convention.

• Only class selectors allowed.

• Minimize classes that dramatically change the children are rendered (I.E. no more .dark).

• More coming soon...

at 1600px, a col1 is 133.33333 px wide. It should be a clean number, ideally falling on a multiple of ten.

There's a problem with base's links, especially when used inside .dark class. They don't have enough contrast. I think defaulting to underlined links, at least in prose, and then providing another non-underlined link style would be best.

• Usage: how to get started
• Principles: general info on how base is designed and how meant to be used.
• Documentation:
  • Basic elements (divs, a, code, p, ul, img, ect)
  • Typography (text styling, or basic elements when inside .prose class)
  • Grid ( + also vertical tiles) #11
  • Sizing (width, height)
  • Position (absolute and fixed positioning, ect)
  • layout utilities (margin, padding, display, ect )
  • Theming utilities (borders, border radius, box shadows, ect)
  • Icons (base icons, multiple sizes)
  • Colors (all mapbox brand colors as both text and background colors)
  • state utilities (hover, active, .active, ect)
  • Components (forms, tooltips, modals, ect)
• Examples (see #3)

The 'documentation' sections would be auto-generated from comments in css. Examples would not be.

re-base should automatically generate documentation from CSS code comments. It should both parse keywords / tags like documentation.js, and also parse html inside comments into real html documentation.

• IE 11+
• All the modern browsers.

Do we need to be more specific than this?

For reference: https://www.netmarketshare.com/browser-market-share.aspx?qprid=2&qpcustomd=0

Base has a dark class that modifies almost everything else, from font color, to keylines, to default button styling. Instead of dark, do we simply offer many color options for everything, including text, and expect user to consistently use their, say, txt-white class everywhere?

We probably want these 🙈

• Should bor-all-* be reduced to bor-*? I think that might fit the convention elsewhere: we have pad-10 instead of pad-all-10.
• How about bor-*-transparent? I find myself wanting to use that sometimes — usually when an element is only going to have a border in a certain state. Do others?
• Do we want to allow people to put different colored borders on the same element? If not, we could very significantly reduce the number of rules required, I think.
• Should uncolored classes, like bor-all-2, take currentColor (the equivalent of no specific color, e.g. 2px solid) instead of the dark color?

Turns out the attribute selectors might be too clever after all ... I feel like I let some important things slip my mind.

I made a div with classes bor2-bottom-red bg-yellow, thinking that I'd get a yellow background and a red border. But instead I got a yellow border. This is because the rule [class^='bor'][class$='-yellow'] { border-color: #ffeb3b; } ends up targeting this element, whose class name starts does start with bor and does end with -yellow!

So that's a problem that might seem specific to the border selectors. But I realized some other problems:

• We shouldn't use ^=, because that means the class attribute must start with the string we're targeting. It's not that a single class name starts with the string, but the whole attribute value.
• By using *= we open ourselves to weird problems. Like ,*='col' could end up targeting my class colorize, and the selector *='bor' will end up targeting my class boring.
• By using attribute selectors we are making the rules more difficult to override. I don't think you can override two selectors with a single class, for example.

Because of all the above, I'm in favor of banishing attribute selectors and just being explicit about our class names.

Thoughts?

hovers, actives, focuses, as rules, detached from any specific component.

The stylesheet we provide in base-core need to include the following features:

• Standard CSS reset
• Flexible, mobile-friendly grid system
• Classes for styling all HTML5 form components
• Base icon set classes
• Custom Typographic scale using freely available fonts
• Basic set of color fill classes
• Style utility classes for keylines, borders, rounded corners, transparency, shadows, ect.
• Layout utility classes for padding, margin, centering and alignment
• Component classes for commonly used components (tooltips, popovers, modals, blockquotes, ect, loading spinner)
• Syntax highlighting (?)
• Animation classes (?)

The stylesheet we provide in mapbox-base needs to include the following features:

• Classes for placing the Mapbox logo at various sizes onto the page
• Mapbox brand color palette
• Typography overrides using Mapbox's brand fonts
• classes for mapbox customer logos. See https://github.com/mapbox/www.mapbox.com/tree/mb-pages/_includes/logos for how we handle logos now. (?)
• classes for credit card icons (we have this in base now, not sure we need to keep them) (?)

• border radiuses (3px, 6px, round left and right, round top and bottom, fully round)
• keylines (multiple colors, 1px and 2px sizes)
• shadows (multiple colors, sizes, intensities)

<meta name='viewport' content='initial-scale=1,maximum-scale=1,user-scalable=no' /> has some issues. I do think users should be able to scale the UI in some cases? Need to do some research here.

Right now we don't have sourcemaps coming out of the CSS processing pipeline. Because something nasty is going on.

We're going to build our grid system using Flexbox. Mostly because it happily does what you'd expect: containers of variable heights flow evenly. I'm just going to get started using it for our column rules!

The goal is to create something like this:

In a clean and efficient way using base. Establish a grid, be able to break out of the grid and still line up evenly against columns in the container.

Notes

Naming cols, col-2

A parent container cols defines the Flexbox properties how immediate child columns should operate. each column container has col- followed by the number it takes up.

Gutters cols-gut-10

Gutters provide proper spacing between the content within containers. If a gutter is defined it should create the spacing in-between each column and still be flush to the left and right of the parent container. Frameworks typically use negative margins to get around this. I'll look into other possibilities but will probably use a margin right with nth-child(Nn+N) selector to zero out margins on last elements.

Limiters

limiter name should be explicit by pixel width (i.e limiter-1500 where width is 1500px). There should be a handful of limiter widths we can use.

Breakpoints

Breakpoints supported are: mobile, tablet, & wide. Adapting to the number of columns you should see for each of these breakpoints should be explicit and to the choice of the content creator by a class naming convention like col-mobile-4.

per #12, includes:

• table
• code
• ul
• a
• img
• blockquote
• kbd
• hr