{"id":13395204,"url":"https://github.com/system-ui/theme-specification","last_synced_at":"2025-04-04T16:09:34.451Z","repository":{"id":40380479,"uuid":"177318957","full_name":"system-ui/theme-specification","owner":"system-ui","description":"A specification for defining theme objects \u0026 design tokens for use with UI components","archived":false,"fork":false,"pushed_at":"2024-02-15T03:43:22.000Z","size":16,"stargazers_count":532,"open_issues_count":18,"forks_count":19,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-10-13T16:09:44.079Z","etag":null,"topics":["css","design","design-systems","design-tokens","themes","theming"],"latest_commit_sha":null,"homepage":"https://system-ui.com/theme","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/system-ui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-23T17:24:41.000Z","updated_at":"2024-10-13T05:23:49.000Z","dependencies_parsed_at":"2024-10-25T10:17:19.443Z","dependency_job_id":"99ce8c6b-cf71-4d92-846b-2a5dbc518b69","html_url":"https://github.com/system-ui/theme-specification","commit_stats":{"total_commits":8,"total_committers":2,"mean_commits":4.0,"dds":0.125,"last_synced_commit":"05fbbc7b6290492d9b6449920c4b05b8fe349e19"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Ftheme-specification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Ftheme-specification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Ftheme-specification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Ftheme-specification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/system-ui","download_url":"https://codeload.github.com/system-ui/theme-specification/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208143,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","design","design-systems","design-tokens","themes","theming"],"created_at":"2024-07-30T17:01:46.105Z","updated_at":"2025-04-04T16:09:34.418Z","avatar_url":"https://github.com/system-ui.png","language":null,"funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"\n# System UI Theme Specification\n\nhttps://system-ui.com\n\n\u003e This specification is a work-in-progress. Please see the related [issue][] for more.\n\n[issue]: https://github.com/system-ui/theme-specification/issues/1\n\nThe theme object is intended to be a general purpose format for storing design system style values, scales, and/or design tokens.\nThe object itself is not coupled to any particular library's implementation and can be used\nin places where sharing common style values in multiple parts of a code base is desirable.\n\n## Scale Objects\n\nMany CSS style properties accept open-ended values like lengths, colors, and font names.\nIn order to create a consistent styling system, the theme object is centered around the idea of scales,\nsuch as a typographic (font-size) scale, a spacing scale for margin and padding, and a color object.\nThese scales can be defined in multiple ways depending on needs, but tend to use arrays for ordinal values like font sizes,\nor plain objects for named values like colors, with the option of nesting objects for more complex systems.\n\n```js\n// example fontSizes scale as an array\nfontSizes: [\n  12, 14, 16, 20, 24, 32\n]\n```\n\n```js\n// example colors object\ncolors: {\n  blue: '#07c',\n  green: '#0fa',\n}\n```\n\n```js\n// example nested colors object\ncolors: {\n  blue: '#07c',\n  blues: [\n    '#004170',\n    '#006fbe',\n    '#2d8fd5',\n    '#5aa7de',\n  ]\n}\n```\n\n### Scale Aliases\n\nFor 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.\n\n```js\n// example fontSizes aliases\nfontSizes: [\n  12, 14, 16, 20, 24, 32\n]\n// aliases\nfontSizes.body = fontSizes[2]\nfontSizes.display = fontSizes[5]\n```\n\n### Excluded Values\n\nSome CSS properties accept only a small, finite number of valid CSS values and should *not* be included as a scale object.\nFor example, the `text-align` property accepts the following values:\n`left`, `right`, `center`, `justify`, `justify-all`, `start`, `end`, or `match-parent`.\nOther properties that are intentionally excluded from this specification include: `float`, `clear`, `display`, `overflow`, `position`, `vertical-align`, `align-items`, `justify-content`, and `flex-direction`.\n\n## Keys\n\nThe keys in the theme object should typically correspond with the CSS properties they are used for, and follow a plural naming convention.\nFor 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.\n\nSome keys can be used for multiple CSS properties, where the data type is the same.\nThe `color` object is intended to be used with any property that accepts a CSS color value, such as `background-color` or `border-color`.\n\n\n### Space\n\nThe `space` key is a specially-named scale intended for use with margin, padding, and other layout-related CSS properties.\nA space scale can be defined as either a plain object or an array, but by convention an array is preferred.\nThis 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.\n\n\u003e Note: other names under consideration include *spacing*, *spaces*, and *lengths*.\n\nWhen defining space scales as an array, it is conventional to use the value `0` as the first value so that `space[0] === 0`.\n\n```js\n// example space scale\nspace: [\n  0, 4, 8, 16, 32, 64\n]\n```\n\n```js\n// example space scale object\nspace: {\n  small: 4,\n  medium: 8,\n  large: 16,\n}\n```\n\n```js\n// example space scale with aliases\nspace: [\n  0, 4, 8, 16, 32\n]\nspace.small = space[1]\nspace.medium = space[2]\nspace.large = space[3]\n```\n\n### Breakpoints\n\nBreakpoints are CSS lengths intended for use in media queries.\nCommonly, the breakpoints scale is used to create mobile-first responsive media queries based on array values.\n\n#### Media Queries\n\nFor convenience and for use with other styling approaches, a `mediaQueries` scale derived from the `breakpoints` scale can be added to the theme object.\n\n```js\nbreakpoints: [ '40em', '52em', '64em' ]\n\nmediaQueries: {\n  small: `@media screen and (min-width: ${breakpoints[0]})`,\n  medium: `@media screen and (min-width: ${breakpoints[1]})`,\n  large: `@media screen and (min-width: ${breakpoints[2]})`,\n}\n```\n\n### Key Reference\n\nThe following is a list of theme object keys and their corresponding CSS properties.\nThis list may be non-exhaustive.\n\nTheme Key         | CSS Properties\n------------------|--------------\n`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`\n`fontSizes`       | `font-size`\n`colors`          | `color`, `background-color`, `border-color`\n`fonts`           | `font-family`\n`fontWeights`     | `font-weight`\n`lineHeights`     | `line-height`\n`letterSpacings`  | `letter-spacing`\n`sizes`           | `width`, `height`, `min-width`, `max-width`, `min-height`, `max-height`\n`borders`         | `border`, `border-top`, `border-right`, `border-bottom`, `border-left`\n`borderWidths`    | `border-width`\n`borderStyles`    | `border-style`\n`radii`           | `border-radius`\n`shadows`         | `box-shadow`, `text-shadow`\n`zIndices`        | `z-index`\n`transitions`     | `transition`\n\n### Prior Art\n\nPrior art includes, but is not limited to the following. Please open an issue or pull request to help ensure this list is inclusive.\n\n- [Theo](https://github.com/salesforce-ux/theo)\n- [Style Dictionary](https://amzn.github.io/style-dictionary/)\n- [Lona](https://github.com/airbnb/Lona)\n- [Universal Design Tokens](https://github.com/universal-design-tokens/udt)\n- [Styled System](https://styled-system.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem-ui%2Ftheme-specification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystem-ui%2Ftheme-specification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem-ui%2Ftheme-specification/lists"}