Skip to content
This repository was archived by the owner on Jul 19, 2019. It is now read-only.

Commit fb1b0c8

Browse files
author
dmitrizzle
authored
Merge pull request #7 from roast-cms/master
First stable release
2 parents 262d292 + ba208f2 commit fb1b0c8

File tree

10 files changed

+1089
-153
lines changed

10 files changed

+1089
-153
lines changed

‎.npmignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Dependency directories
2+
node_modules/
3+
4+
# Examples folder
5+
examples/
6+
7+
# Raw code
8+
src/
9+
10+
# Design and graphics
11+
graphics/
12+
13+
# Other
14+
.babelrc
15+
.yarnclean
16+
yarn.lock

‎README.md‎

Lines changed: 100 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,113 @@
11
# react-sugar-styled
22
![GitHub version](https://badge.fury.io/gh/roast-cms%2Freact-sugar-styled.svg)
3-
> 🍬 Tools and magic numbers for styled-components theme used within roast-cms React components.
3+
> 🍬 Customizable and extendable theming dictionary for Styled Components.
44
5-
### What is this?
5+
![demo](/graphics/demo.gif?raw=true)
66

7-
This is a list of defaults (colours, sizes, fonts etc.) which all or most React components under `roast-cms` use with help from [https://github.com/styled-components/styled-components](styled-components).
8-
9-
### What you will need.
10-
This package requires `styled-components`.
7+
- Create **more flexible designs** with React and Styled Components.
8+
- **Pre-built design system** that works across all your projects.
9+
- **Focus on design**, not variables.
1110

11+
## Installation:
1212
```
13-
# first you'll need the package:
1413
yarn add @roast-cms/react-sugar-styled
1514
```
15+
Then, in your project:
16+
```javascript
17+
import styled, { ThemeProvider } from "styled-components"
18+
import { Sugar } from "@roast-cms/react-sugar-styled"
19+
//
20+
// you can access the dictionary values from Styled Components within
21+
// any component that's wrapped in <ThemeProvider />
22+
const MyComponent = styled.div`
23+
color: ${props => props.theme.color.brand()};
24+
`
25+
//
26+
// pass the dictionary Sugar() as a theme to your app:
27+
const App = props =>
28+
<ThemeProvider theme={Sugar()}><MyComponent /></ThemeProvider>
29+
```
30+
31+
## Why?
32+
[Styled Components](https://github.com/styled-components/styled-components) lets you apply CSS to your React components with ease. Their [theming support](https://www.styled-components.com/docs/advanced#theming) adds a level of flexibility and organization to your application. You can make your components visually behave in an organized fashion, while remaining independent.
33+
34+
Theming in this context works as defining a dictionary of values which could be reused across the children components. **However**, what those values are is a mystery until you finish building your project.
35+
36+
`react-sugar-styled` provides you with a set of defaults that you can easily customize and extend. They include basics like colours, fonts, key sizes, and more. A set of convenience functions also helps you with responsive design (breakpoints), as well as size and colour modifications.
37+
38+
## Theme globals.
39+
All of the values in the theme object are accessible across all your components which are children of `<ThemeProvider/>`. Here's what they do and how to access them:
40+
41+
To access a value within your CSS (that you wrote with Styled Components) simply include `${props => props.theme.[OBJECT REFERENCE]}`, where **OBJECT REFERENCE** is one of the following:
42+
43+
#### Colours
44+
45+
**OBJECT REFERENCE** | Description | Usage Example
46+
--- | --- | ---
47+
`color.brand(alpha)` | An rgba value for your "special" theme colour. | `color: ${props => props.theme.color.brand()};`
48+
`color.foreground(alpha)` | An rgba value for your foreground colour, typically the colour of your body text. | `color: ${props => props.theme.color.foreground()};`
49+
`color.background(alpha)` | An rgba value for your background colour, typically the colour of your background. | `background: ${props => props.theme.color.background()};`
50+
51+
#### Typography
52+
53+
**OBJECT REFERENCE** | Description | Usage Example
54+
--- | --- | ---
55+
`typography.title.auto` | Return CSS that sets `color`, `font-family`, `letter-spacing`, `line-height`, `font-weight`, and `margin` designed for title/heading tags. | `h1 { ${props => props.theme.typography.title.auto} }`
56+
`typography.text.auto` | Same as above, but for body text. | `p { ${props => props.theme.typography.text.auto} }`
57+
58+
#### Block measuring sizes
59+
**OBJECT REFERENCE** | Description | Usage Example
60+
--- | --- | ---
61+
`size.block.padding` | Returns a number meant to be used as `em` value for standard padding width | `padding: ${props => props.theme.size.block.padding}em;`
62+
`size.block.padding` | Returns a number meant to be used as `em` value for standard spacing between blocks | `margin: ${props => props.theme.size.block.spacing}em;`
63+
`size.block.border` | Returns a number meant to be used as `px` value for standard border widths | `border: ${props => props.theme.size.block.border}px solid;`
64+
`size.block.column.m` | Returns a number meant to be used as `px` value for a medium-width content column | `article { width: ${props => props.theme.size.column.m} }`
65+
`size.block.column.l` | Same as above, but for wider screens | `article { width: ${props => props.theme.size.column.l} }`
66+
67+
#### Complete list can be found [here](/THEME_GLOBALS.md)
68+
69+
## Customizing & extending the theme.
70+
Although you can immediately start designing your components using the default theme dictionary, you may want to customize it. Luckily there's an easy way to do this:
1671

17-
### How to use.
1872
```javascript
19-
import { ThemeProvider } from "styled-components"
20-
import { Sugar } from "../src/index"
73+
<ThemeProvider
74+
theme={Sugar({
75+
color_brand: "rgb(189,67,54)",
76+
color_background: "rgb(44,44,44)",
77+
color_foreground: "rgb(224,213,255)",
78+
//
79+
font_heading: "'Yanone Kaffeesatz', sans-serif",
80+
font_heading_weight: 400,
81+
//
82+
font_body: "'Lobster Two', serif",
83+
//
84+
size_base: 28,
85+
size_column_medium: 700,
86+
size_column_large: 900,
87+
size_block_padding: 2,
88+
size_block_spacing: 1.5,
89+
size_block_border: 10,
90+
//
91+
effects_border_radius: 1
92+
})
93+
}
94+
>
95+
{/* components */}
96+
</ThemeProvider>
97+
```
2198

22-
const ThemedComponent = props =>
23-
<ThemeProvider theme={Sugar}>
24-
Whatever.
25-
</ThemeProvider>
99+
You can also extend the theme with your own dictionary values or system using ES6 spread operator:
100+
101+
```javascript
102+
<ThemeProvider
103+
theme={{
104+
...Sugar(),
105+
font_special: "'Indie Flower', cursive"
106+
}}
107+
>
108+
{/* components */}
109+
</ThemeProvider>
26110
```
27111

28-
### Contributing
29-
PRs and issue reports are welcome. Please submit all PRs to `develop` branch. To test, run `yarn start`
112+
## Contributions welcome!
113+
To get started with the code: clone the repo, run `yarn install` then `yarn start` and open up `http://localhost:3002` in your browser.

‎THEME_GLOBALS.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Theme globals.
2+
All of the values in the theme object are accessible across all your components which are children of `<ThemeProvider/>`. Here's what they do and how to access them:
3+
4+
To access a value within your CSS (that you wrote with Styled Components) simply include `${props => props.theme.[OBJECT REFERENCE]}`, where **OBJECT REFERENCE** is one of the following:
5+
6+
#### Colours
7+
8+
**OBJECT REFERENCE** | Description | Usage Example
9+
--- | --- | ---
10+
`color.brand(alpha)` | An rgba value for your "special" theme colour. | `color: ${props => props.theme.color.brand()};`
11+
`color.foreground(alpha)` | An rgba value for your foreground colour, typically the colour of your body text. | `color: ${props => props.theme.color.foreground()};`
12+
`color.background(alpha)` | An rgba value for your background colour, typically the colour of your background. | `background: ${props => props.theme.color.background()};`
13+
`color.highlight(alpha)` | An rgba value for your highlight colour, typically used for selecting text or items. | `::selection { background: ${props => props.theme.color.highlight()}; }`
14+
15+
#### Opacity
16+
By default all colours have opacity of 1, passing an opacity value into the color function gives it according transparency. The following values can be used to set opacity for colours:
17+
18+
**OBJECT REFERENCE** | Description | Usage Example
19+
--- | --- | ---
20+
`opacity.most` | 0.85 | `color: ${props => props.theme.color.brand(props.theme.opacity.most)};`
21+
`opacity.half` | 0.5 | `color: ${props => props.theme.color.brand(props.theme.opacity.half)};`
22+
`opacity.least` | 0.125 | `color: ${props => props.theme.color.brand(props.theme.opacity.least)};`
23+
24+
#### Typography
25+
26+
**OBJECT REFERENCE** | Description | Usage Example
27+
--- | --- | ---
28+
`typography.title.auto` | Return CSS that sets `color`, `font-family`, `letter-spacing`, `line-height`, `font-weight`, and `margin` designed for title/heading tags. | `h1 { ${props => props.theme.typography.title.auto} }`
29+
`typography.title.lineHeight` | Returns a number to be used when setting `line-height` for headings. | `div { line-height: ${props => props.theme.typography.title.lineHeight}em; }`
30+
`typography.text.auto` | Same as above, but for body text. | `p { ${props => props.theme.typography.text.auto} }`
31+
`typography.title.lineHeight` | Same as above, but for body text. | `div { line-height: ${props => props.theme.typography.text.lineHeight}em; }`
32+
33+
#### Font sizes
34+
**OBJECT REFERENCE** | Description | Usage Example
35+
--- | --- | ---
36+
`size.font.m` | Returns a base font size number, meant to be in pixels | `font-size: ${props => props.theme.size.font.m}px`
37+
`size.font.l` | Same as above, multiplied by a factor of `1.15`| `font-size: ${props => props.theme.size.font.l}px`
38+
`size.font.s` | Same as above, multiplied by a factor of `0.9`| `font-size: ${props => props.theme.size.font.s}px`
39+
`size.font.s` | Same as above, multiplied by a factor of `0.85`| `font-size: ${props => props.theme.size.font.xs}px`
40+
--- | --- | ---
41+
`size.font.make.larger` | Returns a number (2) meant to be used as `em` value in setting relative font sizes. | `h1 { font-size: ${props => props.theme.font.make.larger}em }`
42+
`size.font.make.normal` | Returns a number (1) meant to be used as `em` value in setting relative font sizes. | `h2 { font-size: ${props => props.theme.font.make.normal}em }`
43+
`size.font.make.smaller` | Returns a number (.85) meant to be used as `em` value in setting relative font sizes. | `small { font-size: ${props => props.theme.font.make.smaller}em }`
44+
`size.font.make.tiny` | Returns a number (.5) meant to be used as `em` value in setting relative font sizes. | `.tiny { font-size: ${props => props.theme.font.make.tiny}em }`
45+
--- | --- | ---
46+
`size.font.auto` | Sets corresponding font sizes to appropriate media queries | `.fonts-reset { ${props => props.theme.size.font.auto} }`
47+
48+
#### Block measuring sizes
49+
**OBJECT REFERENCE** | Description | Usage Example
50+
--- | --- | ---
51+
`size.block.padding` | Returns a number meant to be used as `em` value for standard padding width | `padding: ${props => props.theme.size.block.padding}em;`
52+
`size.block.padding` | Returns a number meant to be used as `em` value for standard spacing between blocks | `margin: ${props => props.theme.size.block.spacing}em;`
53+
`size.block.border` | Returns a number meant to be used as `px` value for standard border widths | `border: ${props => props.theme.size.block.border}px solid;`
54+
`size.block.column.m` | Returns a number meant to be used as `px` value for a medium-width content column | `article { width: ${props => props.theme.size.column.m} }`
55+
`size.block.column.l` | Same as above, but for wider screens | `article { width: ${props => props.theme.size.column.l} }`
56+
57+
#### Layering (z-index values)
58+
**OBJECT REFERENCE** | Description | Usage Example
59+
--- | --- | ---
60+
`layer.overlay` | 40: for overlays | `z-index: ${props => props.theme.layer.overlay};`
61+
`layer.card` | 30: to display contextual content menus/cards | `z-index: ${props => props.theme.layer.card};`
62+
`layer.nav` | 20: for navigation menus | `z-index: ${props => props.theme.layer.card};`
63+
`layer.up` | 10: just above main content | `z-index: ${props => props.theme.layer.up};`
64+
`layer.tuck` | -1: tuck under main content | `z-index: ${props => props.theme.layer.card};`
65+
66+
#### Media queries
67+
All media queries use the following labels that define range (in pixels): `xxl: [1601, 160000000]`, `xl: [1081, 1600]`, `l: [751, 1080]`, `m: [521, 750]`, `s: [321, 520]`, `xs: [0, 320]`.
68+
69+
**OBJECT REFERENCE** | Description | Usage Example
70+
--- | --- | ---
71+
`size.breakpoint.exact` | Returns a breakpoint that has `min-width` and `max-width` defined by the label values (above) | `${props =>
72+
props.theme.size.breakpoint.exact.l`[css]`};`
73+
`size.breakpoint.min` | Returns a breakpoint that has `min-width` but no `max-width` | `${props =>
74+
props.theme.size.breakpoint.min.l`[css]`};`
75+
`size.breakpoint.max` | Returns a breakpoint that has `max-width` but no `min-width` | `${props =>
76+
props.theme.size.breakpoint.max.l`[css]`};`
77+
78+
#### Effects
79+
**OBJECT REFERENCE** | Description | Usage Example
80+
--- | --- | ---
81+
`effects.borderRadius.med` | Returns a number meant to be used as `em` to set border radius | `border-radius: ${props => props.theme.effects.borderRadius.med}em;`
82+
`effects.borderRadius.small` | Returns a number meant to be used as `em` to set border radius | `border-radius: ${props => props.theme.effects.borderRadius.small}em;`
83+
84+
85+
86+
87+
**Note** that there are defaults set for all of the above values, so that you don't have to start with a blank slate. All you have to do is customize the theme to suit your needs. _Some values are opinionated and meant to be customized, unless you'd like to extend the theme with your own dictionary set_.

‎examples/index.js‎

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,35 @@
1+
//
12
// tools
23
import React from "react"
34
import { render } from "react-dom"
45
import styled, { ThemeProvider } from "styled-components"
5-
6-
// theme
6+
//
7+
// theming tools and fonts
78
import { Sugar } from "../src/index"
8-
9+
import "typeface-yanone-kaffeesatz"
10+
import "typeface-lobster-two"
11+
import "typeface-indie-flower"
12+
//
13+
// styled components
914
const Main = styled.div`
15+
& > * ::selection {
16+
background: ${props => props.theme.color.highlight()};
17+
color: ${props => props.theme.color.background()};
18+
}
1019
${props => props.theme.size.font.auto} ${props =>
1120
props.theme.typography.text.auto} margin: 0 auto;
12-
max-width: ${props => props.theme.size.block.column.maxwidth.m}px;
21+
max-width: ${props => props.theme.size.block.column.m}px;
1322
${props =>
1423
props.theme.size.breakpoint.min.xxl`max-width: ${props =>
15-
props.theme.size.block.column.maxwidth.l}px;`};
16-
padding: 0 ${props => props.theme.size.block.column.safety}em;
24+
props.theme.size.block.column.l}px;`};
25+
padding: 4em ${props => props.theme.size.block.padding}em;
1726
`
1827
const Article = styled.article`
28+
background: ${props => props.theme.color.background()};
1929
padding: ${props => props.theme.size.block.spacing}em;
2030
border-radius: ${props => props.theme.effects.borderRadius.med}em;
2131
border: ${props => props.theme.size.block.border}px solid
22-
${props => props.theme.color.highlight};
32+
${props => props.theme.color.highlight()};
2333
`
2434
const Title = styled.h1`
2535
${props => props.theme.typography.title.auto} font-size: ${props =>
@@ -30,20 +40,50 @@ const Subtitle = styled.h2`
3040
${props => props.theme.typography.title.auto} font-size: ${props =>
3141
props.theme.size.font.make.larger / 2}em;
3242
`
33-
const Branded = styled.strong`color: ${props => props.theme.color.brand};`
43+
const Branded = styled.strong`color: ${props => props.theme.color.brand()};`
3444
const BrandedFade = styled(Branded)`
35-
color: ${props => props.theme.color.alpha.brand(props.theme.opacity.half)}
45+
color: ${props => props.theme.color.brand(props.theme.opacity.half)};
46+
font-size: ${props => props.theme.size.font.make.smaller}em;
3647
`
37-
48+
const SpecialFont = styled.span`
49+
font-family: ${props => props.theme.font_special};
50+
`
51+
//
52+
// app
3853
render(
3954
<div>
40-
<ThemeProvider theme={Sugar}>
55+
<ThemeProvider
56+
theme={{
57+
...Sugar({
58+
color_brand: "rgb(189,67,54)",
59+
color_background: "rgb(44,44,44)",
60+
color_foreground: "rgb(224,213,255)",
61+
//
62+
font_heading: "'Yanone Kaffeesatz', sans-serif",
63+
font_heading_weight: 400,
64+
//
65+
font_body: "'Lobster Two', serif",
66+
//
67+
size_base: 28,
68+
size_column_medium: 700,
69+
size_column_large: 900,
70+
size_block_padding: 2,
71+
size_block_spacing: 1.5,
72+
size_block_border: 10,
73+
//
74+
effects_border_radius: 1
75+
}),
76+
font_special: "'Indie Flower', cursive"
77+
}}
78+
>
4179
<Main>
4280
<Article>
4381
<Title>Title</Title>
4482
<Subtitle>Subtitle</Subtitle>
4583
<p>
46-
Paragraph text. <Branded>Brand colour</Branded>, <BrandedFade>faded brand clour</BrandedFade>.
84+
Paragraph text. <Branded>Brand colour</Branded>,{" "}
85+
<BrandedFade>faded brand clour</BrandedFade>.{" "}
86+
<SpecialFont>Special font</SpecialFont>.
4787
</p>
4888
</Article>
4989
</Main>

‎graphics/demo.gif‎

955 KB
Loading

‎package.json‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@roast-cms/react-sugar-styled",
3-
"version": "0.1.1",
3+
"version": "1.0.0",
44
"description": "Tools and magic numbers for styled-components theme used with roast-cms React components.",
55
"main": "dist/index.js",
66
"repository": "https://github.com/roast-cms/react-sugar-styled.git",
@@ -14,17 +14,25 @@
1414
"babel-plugin-transform-object-rest-spread": "^6.26.0",
1515
"babel-preset-es2015": "^6.24.1",
1616
"babel-preset-react": "^6.24.1",
17-
"webpack": "^3.11.0",
18-
"webpack-dev-server": "^2.11.1",
17+
"css-loader": "^0.28.11",
18+
"file-loader": "^1.1.11",
1919
"react": "^16.0.0",
2020
"react-dom": "^16.0.0",
21-
"styled-components": "3.0.2"
21+
"style-loader": "^0.20.3",
22+
"styled-components": "3.0.2",
23+
"typeface-lobster-two": "^0.0.54",
24+
"typeface-yanone-kaffeesatz": "^0.0.54",
25+
"typeface-indie-flower": "^0.0.54",
26+
"webpack": "^3.11.0",
27+
"webpack-dev-server": "^2.11.1",
28+
"url-loader": "^1.0.1"
2229
},
2330
"peerDependencies": {
2431
"styled-components": "3.0.2"
2532
},
2633
"scripts": {
2734
"start": "webpack-dev-server",
2835
"prepare": "babel src --presets babel-preset-es2015 --out-dir dist"
29-
}
36+
},
37+
"dependencies": {}
3038
}

0 commit comments

Comments
 (0)