{"id":13393672,"url":"https://github.com/system-ui/designql","last_synced_at":"2025-10-19T20:03:07.869Z","repository":{"id":66124196,"uuid":"159498562","full_name":"system-ui/designql","owner":"system-ui","description":"[WIP] A self-documenting design system reference implementation for System UI","archived":false,"fork":false,"pushed_at":"2019-03-21T14:41:33.000Z","size":428,"stargazers_count":276,"open_issues_count":0,"forks_count":9,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-26T18:30:32.031Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://system-ui.com/designql","language":"JavaScript","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}},"created_at":"2018-11-28T12:26:28.000Z","updated_at":"2024-05-17T16:48:17.000Z","dependencies_parsed_at":"2024-01-27T11:54:33.901Z","dependency_job_id":null,"html_url":"https://github.com/system-ui/designql","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Fdesignql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Fdesignql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Fdesignql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system-ui%2Fdesignql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/system-ui","download_url":"https://codeload.github.com/system-ui/designql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231907821,"owners_count":18444186,"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":[],"created_at":"2024-07-30T17:00:58.437Z","updated_at":"2025-10-19T20:03:07.768Z","avatar_url":"https://github.com/system-ui.png","language":"JavaScript","readme":"# DesignQL\n\nA self-documenting design system specification for GraphQL.\n\n```gql\nquery {\n  theme {\n    colors\n    boxShadows\n    a11yCombos {\n      contrast\n      backgroundColor\n      color\n    }\n  }\n  component(name: { eq: \"Button\" }) {\n    docs\n    propsTable {\n      key\n      defaultValue\n      description\n      type {\n        name\n        description\n      }\n    }\n    styledApi {\n      permutations\n    }\n  }\n}\n```\n\n## What is it?\n\nDesignQL provides a GraphQL based definition of a design system's primitives that can be queried _and_ written to by all members of a team.\nThis provides a powerful API for documenting components that still remains flexible for design system teams to have control of design and branding.\nIt also provides a convenient mechanism for cloning for prototyping one-offs or experimenting with changes to the design system itself (theme, components, etc.).\n\n## Why?\n\nWhen we build and document design systems we're often forced to reinvent the wheel with bespoke implementations.\nThere are numerous design system and styleguide tools out there, but they often couple you to custom DSLs or lack flexibility.\nDesignQL seeks to provide users with a free and open API to build out design systems and document them with ease.\nTables of props, playgrounds, and much more can be scaffolded out just from the source code and a colocated MDX file.\n\nThese days design and development for teams often have numerous render targets.\nKeeping them in sync can be difficult, especially when attempting to design generatively, access programmatically, or combine with tools lacking read/write APIs.\nFuture goals of this project will include outputting a design system's primitives and tokens to React (styled-components/emotion/css modules), Vue, vanilla HTML/CSS (Tachyons, BEM, Tailwind).\n\nWe want to share it with the community for a few reasons:\n\n- :family: Improve upon it as a community\n- :recycle: Encourage adoption with other design/development tools\n- :wrench: Community-based implementations for other libraries/frameworks/etc\n- :lock: Avoid lock in for users\n\n## Table of contents\n\n- [Features](#features)\n- [How does it work?](#how-does-it-work)\n  - [Implementation](#implementation)\n  - [Naming conventions](#namingconventions)\n- [Specification](#specification)\n  - [Types](#types)\n    - [DesignSystem](#designsystem)\n    - [Component](#component)\n    - [Theme](#theme)\n    - [Branding](#branding)\n    - [StyledFunction](#styledfunction)\n    - [Primitives](#primitives)\n      - [ColorMap](#colormap)\n      - [JSON](#json)\n\n## How does it work?\n\nA design system typically consists of the same key parts:\n\n- :art: theme\n- :nail_care: branding\n- :ballot_box: components\n- :books: documentation\n- :trophy: icons\n\nDesignQL boils this down to a schema that can be shared amongst a team and their projects.\nIt exposes a GraphQL API that can be used to document React code with many CSS-in-JS libraries and down the road export to other render targets like (Atomic CSS, React Native, Vue).\n\nMore importantly, it defines and provides an interface for programmatic access mentioned earlier.\n\n### Implementation\n\nDesignQL consists of multiple libraries that handle different types of source files.\n\nLibraries:\n\n- react-docgen\n- styled-system\n- MDX\n- Gatsby\n\n#### Example\n\nHere's an example Button component:\n\n```js\nimport styled from 'styled-components'\nimport { color, space } from 'styled-system'\nimport { variant, size } from './styled-functions'\n\n/* @component */\nexport const Button = styled.button`\n  appearance: button;\n\n  ${color}\n  ${space}\n  ${variant}\n  ${size}\n`\n\nButton.displayName = 'Button'\n\nButton.defaultProps = {\n  variant: 'primary',\n  size: 'md'\n}\nButton.propTypes = {\n  color: color.propTypes,\n  variant: variant.propTypes,\n  size: size.propTypes,\n  ...space.propTypes\n}\n```\n\n### Naming conventions\n\nIn order to keep the MVP as simple as possible, DesignQL currently expects a particular layout structure:\n\n- `src/Button.js`\n- `src/Button.mdx`\n\nIf there isn't a colocated MDX file it's no problem, DesignQL will do its best to parse out metadata.\n\n### Future\n\n- Source theme data from numerous locations\n  - CSS Stats\n  - Figma\n  - Sketch\n  - Framer\n\n## Specification\n\nThe DesignQL is defined by the following GraphQL schema:\n\n### Types\n\nThe following types are used to define styling, styled functions, components, and theming.\n\n#### DesignSystem\n\nThe DesignSystem is the top level type that contains a theme, components, and docs.\n\n```gql\ntype DesignSystem: {\n  theme: Theme!\n  branding: Branding!\n  components: [Components!]\n}\n```\n\n#### Component\n\nComponents are elements that have a name, props, styling, styled functions and documentation.\n\n```gql\ntype Component: {\n  \"\"\"\n  Name of the component, Pascal cased\n  \"\"\"\n  name: String!\n  \"\"\"\n  Description of the component\n  \"\"\"\n  description: String\n  \"\"\"\n  HTML element type, also accepts react native primitive types\n  \"\"\"\n  element: String!\n  \"\"\"\n  Default props to apply to the component\n  \"\"\"\n  defaultProps: JSON\n  \"\"\"\n  Property types that the component accepts\n  \"\"\"\n  propTypes: JSON\n  \"\"\"\n  Property control API of the component, defined as a static property\n  \"\"\"\n  propertyControls: JSON\n  \"\"\"\n  List of StyledFunctions for the component\n  \"\"\"\n  StyledFunctions: [StyledFunction!]\n  \"\"\"\n  Additional metadata for the component, including information like status\n  \"\"\"\n  metadata: JSON\n  \"\"\"\n  Component specific documentation\n  \"\"\"\n  docs: String\n  \"\"\"\n  Location of the source file on disk\n  \"\"\"\n  srcPath: String!\n  \"\"\"\n  Location of the MDX file on disk\n  \"\"\"\n  docsPath: String\n}\n```\n\n#### Theme\n\nThemes are objects that define the values used by style props.\nThemes ensure consistent margin, padding, colors, font sizes, and other UI constants.\n\nA design system can also define multiple themes.\nFor example, a team might have a theme for apps and a theme for marketing pages.\n\n```gql\ntype Theme: {\n  \"\"\"typography\"\"\"\n  fonts: JSON\n  fontSizes: JSON\n  fontWeights: JSON\n  lineHeights: JSON\n  letterSpacings: JSON\n  \n  \"\"\"skins\"\"\"\n  colors: ColorMap\n  shadows: JSON\n\n  \"\"\"layout\"\"\"\n  space: JSON\n  widths: JSON\n  minWidths: JSON\n  maxWidths: JSON\n  heights: JSON\n  minHeights: JSON\n  maxHeights: JSON\n\n  \"\"\"borders\"\"\"\n  borders: JSON\n  radii: JSON\n\n  \"\"\"variants\"\"\"\n  variants: JSON\n\n  \"\"\"media queries\"\"\"\n  mediaQueries: [String!]\n}\n```\n\n#### Branding\n\nBranding consists of a brand's primary colors and its logos.\nQueries can be made that automatically return the proper logo type and its color based on parameters.\n\nFor example, if the background where the logo will be placed is a dark purple, the white logo is returned to ensure proper contrast.\n\n```gql\ntype Branding {\n  \"\"\"\n  List of Logos\n  \"\"\"\n  logos: [Logo!]\n  \"\"\"\n  Branding specific colors\n  \"\"\"\n  colors: ColorMap!\n  \"\"\"\n  Documentation for branding\n  \"\"\"\n  docs: String\n}\n```\n\n#### Styled Function\n\nA styled function is based on Styled System.\nStyled functions have access to the theme, props, and optionally core Styled System functions.\nThey return a JSON object.\n\n```gql\ntype StyledFunction {\n  \"\"\"\n  Name for the function\n  \"\"\"\n  name: String!\n  \"\"\"\n  Component property\n  \"\"\"\n  prop: String!\n  \"\"\"\n  Name of core styled-system function\n  \"\"\"\n  styledSystem: String\n  \"\"\"\n  JSON property to set, defaults to prop\n  \"\"\"\n  JSONProp: String\n  \"\"\"\n  Convert numbers to px values\n  \"\"\"\n  toPx: Boolean\n  \"\"\"\n  Variant key (for example: buttons)\n  \"\"\"\n  variantKey: String\n  \"\"\"\n  Does this map to a theme key\n  \"\"\"\n  themeKey: String\n  \"\"\"\n  Documentation for the function\n  \"\"\"\n  docs: String\n}\n```\n\n### Primitive Types\n\n- ColorMap\n- JSON\n\n#### ColorMap\n\nColorMap consists of an object with nested objects, arrays, and strings.\nA color can be represented in hex, rgb, rgba, hsl, or a color name.\n\nValues can only be strings.\n\nHere's an example:\n\n```js\n{\n  base: 'black',\n  bg: 'white',\n  blue: '#07c',\n  grays: [\n    '#999',\n    '#555',\n    '#111'\n  ]\n}\n```\n\n#### JSON\n\nJSON properties can be an Int, Float, or String so we introduce a `JSONProperty` type.\n\n```js\nimport { GraphQLJSON } from 'designql'\n\nconst typeDef = `\nscalar JSON\n`\n\nconst resolvers = {\n  JSON: GraphQLJSON\n}\n```\n\n## Authors\n\n- John Otander\n\n## License\n\nMIT\n","funding_links":[],"categories":["JavaScript","🌐 Web Development - Frontend"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem-ui%2Fdesignql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystem-ui%2Fdesignql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem-ui%2Fdesignql/lists"}