├── README.md └── package.json /README.md: -------------------------------------------------------------------------------- 1 | 2 | # System UI Theme Specification 3 | 4 | https://system-ui.com 5 | 6 | > This specification is a work-in-progress. Please see the related [issue][] for more. 7 | 8 | [issue]: https://github.com/system-ui/theme-specification/issues/1 9 | 10 | The theme object is intended to be a general purpose format for storing design system style values, scales, and/or design tokens. 11 | The object itself is not coupled to any particular library's implementation and can be used 12 | in places where sharing common style values in multiple parts of a code base is desirable. 13 | 14 | ## Scale Objects 15 | 16 | Many CSS style properties accept open-ended values like lengths, colors, and font names. 17 | In order to create a consistent styling system, the theme object is centered around the idea of scales, 18 | such as a typographic (font-size) scale, a spacing scale for margin and padding, and a color object. 19 | These scales can be defined in multiple ways depending on needs, but tend to use arrays for ordinal values like font sizes, 20 | or plain objects for named values like colors, with the option of nesting objects for more complex systems. 21 | 22 | ```js 23 | // example fontSizes scale as an array 24 | fontSizes: [ 25 | 12, 14, 16, 20, 24, 32 26 | ] 27 | ``` 28 | 29 | ```js 30 | // example colors object 31 | colors: { 32 | blue: '#07c', 33 | green: '#0fa', 34 | } 35 | ``` 36 | 37 | ```js 38 | // example nested colors object 39 | colors: { 40 | blue: '#07c', 41 | blues: [ 42 | '#004170', 43 | '#006fbe', 44 | '#2d8fd5', 45 | '#5aa7de', 46 | ] 47 | } 48 | ``` 49 | 50 | ### Scale Aliases 51 | 52 | For typically ordinal values like font sizes that are stored in arrays, it can be helpful to create aliases by adding named properties to the object. 53 | 54 | ```js 55 | // example fontSizes aliases 56 | fontSizes: [ 57 | 12, 14, 16, 20, 24, 32 58 | ] 59 | // aliases 60 | fontSizes.body = fontSizes[2] 61 | fontSizes.display = fontSizes[5] 62 | ``` 63 | 64 | ### Excluded Values 65 | 66 | Some CSS properties accept only a small, finite number of valid CSS values and should *not* be included as a scale object. 67 | For example, the `text-align` property accepts the following values: 68 | `left`, `right`, `center`, `justify`, `justify-all`, `start`, `end`, or `match-parent`. 69 | Other properties that are intentionally excluded from this specification include: `float`, `clear`, `display`, `overflow`, `position`, `vertical-align`, `align-items`, `justify-content`, and `flex-direction`. 70 | 71 | ## Keys 72 | 73 | The keys in the theme object should typically correspond with the CSS properties they are used for, and follow a plural naming convention. 74 | For example, the CSS property `font-size` is expected to use values from the `fontSizes` scale, and the `color` property uses values from the `colors` scale. 75 | 76 | Some keys can be used for multiple CSS properties, where the data type is the same. 77 | The `color` object is intended to be used with any property that accepts a CSS color value, such as `background-color` or `border-color`. 78 | 79 | 80 | ### Space 81 | 82 | The `space` key is a specially-named scale intended for use with margin, padding, and other layout-related CSS properties. 83 | A space scale can be defined as either a plain object or an array, but by convention an array is preferred. 84 | This is an intentional constraint that makes it difficult to add *"one-off"* or *"in-between"* sizes that could lead to unwanted and rippling affects to layout. 85 | 86 | > Note: other names under consideration include *spacing*, *spaces*, and *lengths*. 87 | 88 | When defining space scales as an array, it is conventional to use the value `0` as the first value so that `space[0] === 0`. 89 | 90 | ```js 91 | // example space scale 92 | space: [ 93 | 0, 4, 8, 16, 32, 64 94 | ] 95 | ``` 96 | 97 | ```js 98 | // example space scale object 99 | space: { 100 | small: 4, 101 | medium: 8, 102 | large: 16, 103 | } 104 | ``` 105 | 106 | ```js 107 | // example space scale with aliases 108 | space: [ 109 | 0, 4, 8, 16, 32 110 | ] 111 | space.small = space[1] 112 | space.medium = space[2] 113 | space.large = space[3] 114 | ``` 115 | 116 | ### Breakpoints 117 | 118 | Breakpoints are CSS lengths intended for use in media queries. 119 | Commonly, the breakpoints scale is used to create mobile-first responsive media queries based on array values. 120 | 121 | #### Media Queries 122 | 123 | For convenience and for use with other styling approaches, a `mediaQueries` scale derived from the `breakpoints` scale can be added to the theme object. 124 | 125 | ```js 126 | breakpoints: [ '40em', '52em', '64em' ] 127 | 128 | mediaQueries: { 129 | small: `@media screen and (min-width: ${breakpoints[0]})`, 130 | medium: `@media screen and (min-width: ${breakpoints[1]})`, 131 | large: `@media screen and (min-width: ${breakpoints[2]})`, 132 | } 133 | ``` 134 | 135 | ### Key Reference 136 | 137 | The following is a list of theme object keys and their corresponding CSS properties. 138 | This list may be non-exhaustive. 139 | 140 | Theme Key | CSS Properties 141 | ------------------|-------------- 142 | `space` | `margin`, `margin-top`, `margin-right`, `margin-bottom`, `margin-left`, `padding`, `padding-top`, `padding-right`, `padding-bottom`, `padding-left`, `grid-gap`, `grid-column-gap`, `grid-row-gap` 143 | `fontSizes` | `font-size` 144 | `colors` | `color`, `background-color`, `border-color` 145 | `fonts` | `font-family` 146 | `fontWeights` | `font-weight` 147 | `lineHeights` | `line-height` 148 | `letterSpacings` | `letter-spacing` 149 | `sizes` | `width`, `height`, `min-width`, `max-width`, `min-height`, `max-height` 150 | `borders` | `border`, `border-top`, `border-right`, `border-bottom`, `border-left` 151 | `borderWidths` | `border-width` 152 | `borderStyles` | `border-style` 153 | `radii` | `border-radius` 154 | `shadows` | `box-shadow`, `text-shadow` 155 | `zIndices` | `z-index` 156 | `transitions` | `transition` 157 | 158 | ### Prior Art 159 | 160 | Prior art includes, but is not limited to the following. Please open an issue or pull request to help ensure this list is inclusive. 161 | 162 | - [Theo](https://github.com/salesforce-ux/theo) 163 | - [Style Dictionary](https://amzn.github.io/style-dictionary/) 164 | - [Lona](https://github.com/airbnb/Lona) 165 | - [Universal Design Tokens](https://github.com/universal-design-tokens/udt) 166 | - [Styled System](https://styled-system.com) 167 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@system-ui/theme", 3 | "version": "0.0.4", 4 | "description": "A specification for defining theme objects for use with UI components", 5 | "main": "README.md", 6 | "repository": { 7 | "type": "git", 8 | "url": "git+https://github.com/system-ui/theme-specification.git" 9 | }, 10 | "license": "MIT" 11 | } 12 | --------------------------------------------------------------------------------