diff --git a/.github/workflows/parser-listing.yml b/.github/workflows/parser-listing.yml new file mode 100644 index 00000000..21aecbeb --- /dev/null +++ b/.github/workflows/parser-listing.yml @@ -0,0 +1,40 @@ +name: 'Parser Listing' +on: + push: + branches: + - master + pull_request: + types: ['ready_for_review', 'opened', 'synchronize', 'reopened'] +env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} +jobs: + list: + runs-on: ubuntu-latest + if: github.event.pull_request.draft == false + steps: + - uses: actions/checkout@main + - name: Extract branch name + shell: bash + run: echo "branch=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT + id: extract_branch + - name: Install + run: yarn install --frozen-lockfile + - name: Create Listing + run: yarn list-parsers + - uses: technote-space/get-diff-action@v6 + id: diff + with: + FILES: | + SUMMARY.md + - name: Pushes parser list + uses: dmnemec/copy_file_to_another_repo_action@main + if: steps.diff.outputs.diff + env: + API_TOKEN_GITHUB: ${{ secrets.GH_PARSERS_TOKEN }} + with: + source_file: 'output/parsers.md' + destination_repo: 'Specifyapp/Documentation' + destination_folder: 'concepts' + user_email: 'allan.michay@gmail.com' + user_name: 'AllanMichay' + commit_message: 'feat(parsers): update parsers list' diff --git a/output/.gitkeep b/output/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/output/PARSERS.md b/output/PARSERS.md new file mode 100644 index 00000000..fc7ee14f --- /dev/null +++ b/output/PARSERS.md @@ -0,0 +1,106 @@ +--- +description: >- + Parsers are functions allowing you to transform design tokens and assets + coming from Specify to fit your needs and company standards. +--- + +# Parsers + +## Why you need parsers + +

Parsers help you transform raw design tokens and assets returned by Specify to match your company standards

+ +By default, without any parsers, Specify will return your design data as raw data: + +- Design tokens are returned in JSON +- Assets are returned as files + +There are high chances you need to transform those design data to fit your needs. Parsers help you do just that. + +## What are parsers? + +Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards. + +

An example output pipeline that pulls colors from Specify, sorts them alphabetically and transforms them as CSS Custom Properties

+ +A parser does the following job: + +1. Receives design data as input +2. Transforms this design data +3. Returns the transformed data + +The data returned by a parser can either be: + +- Design data that can be used by another parser coming next in your transformation pipeline +- A file so it can be used by people, frameworks, or scripts + +{% hint style="info" %} +Parsers are what make Specify powerful and flexible. They help you be in total control of the design data you pull from Specify. +{% endhint %} + +Parsers are ordered and takes specific input to generate specific output. This way, we can easily test the input coming from the previous parser to check if the whole parsers process will work. + +## Categories + +Parsers are classified in 2 categories: technology and utility. + +### Technology + +Technology parsers help you transform your design tokens to specific technologies and formats (CSS Custom properties, SCSS, Tailwind, a Javascript theme object compatible with React Native...) + +Some examples: + +- [to-react-native](https://github.com/Specifyapp/parsers/tree/master/parsers/to-react-native) +- [to-css-custom-properties](https://github.com/Specifyapp/parsers/tree/master/parsers/to-css-custom-properties) +- [to-scss-variables](https://github.com/Specifyapp/parsers/tree/master/parsers/to-scss-variables) +- [to-tailwind](https://github.com/Specifyapp/parsers/tree/master/parsers/to-tailwind) + +### Utility + +Utility parsers take care of "smaller" transformation. Like converting a pixel value to `rem` or transforming a string to kebabcase. + +Some examples: + +- [convert-font](https://github.com/Specifyapp/parsers/tree/master/parsers/convert-font) +- [kebabcasify](https://github.com/Specifyapp/parsers/tree/master/parsers/kebabcasify) +- [px-to-rem](https://github.com/Specifyapp/parsers/tree/master/parsers/px-to-rem) + +## All parsers available + +All parsers are open source and available on [the following GitHub repository](https://github.com/Specifyapp/parsers). + +| Parser | Description | Usage Example | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| camelcasify | Apply camelcase function on specific keys from a design token. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/camelcasify/README.md#usage) | +| convert-font | Convert font in several formats. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/convert-font/README.md#usage) | +| filter | Filter tokens and assets by their name using a regular expression. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/filter/README.md#usage) | +| inline-css-variables-in-svg | Replace all the `stroke` and `fill` attribute raw color value by its corresponding design token as a CSS variable. If no design token match, the raw value will be left as is. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/inline-css-variables-in-svg/README.md#usage) | +| kebabcasify | Apply kebabcase function on specific keys from a design token. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/kebabcasify/README.md#usage) | +| link-design-tokens | Have design tokens referencing other ones. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/link-design-tokens/README.md#usage) | +| name-assets-files-by-pattern | Set a structured filename on your assets. It won't rename your asset but only add a new `filename` property on the asset object. The filename structure uses [mustache](https://github.com/janl/mustache.js#templates) as a template engine. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/name-assets-files-by-pattern/README.md#usage) | +| omit | Omit keys from a design token not given in parameters. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/omit/README.md#usage) | +| pascalcasify | Apply pascalcase function on specific keys from a design token. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/pascalcasify/README.md#usage) | +| pick | Get only specific keys from a design token given in params. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/pick/README.md#usage) | +| prefix-by | Concatenate two strings. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/prefix-by/README.md#usage) | +| px-to-rem | Convert the value of a measurement design token from pixel to rem. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/px-to-rem/README.md#usage) | +| replace-string | Replace any string matched by a regex by a new string. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/replace-string/README.md#usage) | +| round-number | Round any measurement design token with specific precision. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/round-number/README.md#usage) | +| snakecasify | Apply snakecase function on specific keys from a design token. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/snakecasify/README.md#usage) | +| sort-by | Loop on several design tokens and sort them according to their respective key values. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/sort-by/README.md#usage) | +| suffix-by | Concatenate two strings. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/suffix-by/README.md#usage) | +| svg-to-jsx | Wrap SVG files within a JSX component. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/svg-to-jsx/README.md#usage) | +| svgo | Optimize vectors using [svgo](https://github.com/svg/svgo). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/svgo/README.md#usage) | +| to-css-custom-properties | Transform design tokens in CSS Custom Properties. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-css-custom-properties/README.md#usage) | +| to-css-font-import | Create CSS `@font-face` rules to import your font files. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-css-font-import/README.md#usage) | +| to-css-text-style | Create text styles as CSS classes. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-css-text-style/README.md#usage) | +| to-dsp | Create a [Design System Package (DSP)](https://github.com/AdobeXD/design-system-package-dsp). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-dsp/README.md#usage) | +| to-flutter | Format design tokens to create a theme compatible with the [Flutter specification](https://docs.flutter.dev/cookbook/design/themes). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-flutter/README.md#usage) | +| to-jss | Transform design tokens in JSS. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-jss/README.md#usage) | +| to-react-native | Transform design tokens to a JavaScript `theme` object compatible with [React Native](https://reactnative.dev/). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-react-native/README.md#usage) | +| to-scss-map | Generate `.scss` files containing Scss map and function / mixin to access the values of the tokens. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-scss-map/README.md#usage) | +| to-scss-mixin-text-style | Create text styles formatted as [SCSS mixins](https://sass-lang.com/documentation/at-rules/mixin). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-scss-mixin-text-style/README.md#usage) | +| to-scss-variables | Transform design tokens in SCSS variables. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-scss-variables/README.md#usage) | +| to-style-dictionary | Generate [Style Dictionary](https://amzn.github.io/style-dictionary/#/) configuration files for all your design tokens coming from Specify. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-style-dictionary/README.md#usage) | +| to-tailwind | Format design tokens to create a theme compatible with the [TailwindCSS specification](https://tailwindcss.com/docs/theme). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-tailwind/README.md#usage) | +| to-theme-ui | Format design tokens to create a theme compatible with the [theme-ui specification](https://theme-ui.com/theme-spec). | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-theme-ui/README.md#usage) | +| to-typescript-definition | Format design tokens to create their corresponding TypeScript types. | [Example](https://github.com/Specifyapp/parsers/blob/master/parsers/to-typescript-definition/README.md#usage) | diff --git a/package.json b/package.json index 7765c40e..5c251fa9 100644 --- a/package.json +++ b/package.json @@ -43,6 +43,7 @@ "test": "jest --coverage --runInBand", "generate:seeds": "ts-node ./tests/helper/generate.seed.ts", "format": "prettier '**/*' -u -w", - "prepare": "git config --local core.hooksPath .hooks" + "prepare": "git config --local core.hooksPath .hooks", + "list-parsers": "node ./scripts/list-parsers.js" } } diff --git a/parsers/sort-by/README.md b/parsers/sort-by/README.md index 6c986741..689b99f4 100644 --- a/parsers/sort-by/README.md +++ b/parsers/sort-by/README.md @@ -1,7 +1,8 @@ # Sort By ## Description -This parser helps loop on several design tokens and sort them according to their respective key values. + +This parser helps you loop on several design tokens and sort them according to their respective key values. Learn more about how to configure Specify in the API documentation: [https://specifyapp.com/developers](https://specifyapp.com/developers). @@ -160,7 +161,7 @@ type output = Array<{ [key: string]: any }>; "value": { "unit": "px", "measure": 8 - }, + } }, { "name": "base-space-01", @@ -168,8 +169,8 @@ type output = Array<{ [key: string]: any }>; "value": { "unit": "px", "measure": 4 - }, - }, + } + } ] ``` @@ -183,7 +184,7 @@ type output = Array<{ [key: string]: any }>; "value": { "unit": "px", "measure": 4 // <--- - }, + } }, { "name": "base-space-02", @@ -191,7 +192,7 @@ type output = Array<{ [key: string]: any }>; "value": { "unit": "px", "measure": 8 // <--- - }, - }, + } + } ] ``` diff --git a/parsers/to-flutter/README.md b/parsers/to-flutter/README.md index 382d0672..82cf8b12 100644 --- a/parsers/to-flutter/README.md +++ b/parsers/to-flutter/README.md @@ -2,7 +2,7 @@ ## Description -Format design tokens to create a theme compatible with the [Flutter specification](https://docs.flutter.dev/cookbook/design/themes). +This parser helps you format design tokens to create a theme compatible with the [Flutter specification](https://docs.flutter.dev/cookbook/design/themes). Learn more about how to configure Specify in the API documentation: [https://specifyapp.com/developers](https://specifyapp.com/developers). diff --git a/parsers/to-tailwind/README.md b/parsers/to-tailwind/README.md index 0b7d9dcf..f0558576 100644 --- a/parsers/to-tailwind/README.md +++ b/parsers/to-tailwind/README.md @@ -2,7 +2,7 @@ ## Description -Format design tokens to create a theme compatible with the [TailwindCSS specification](https://tailwindcss.com/docs/theme). +This parser helps you format design tokens to create a theme compatible with the [TailwindCSS specification](https://tailwindcss.com/docs/theme). The theme is also compatible with [WindiCSS](https://windicss.org/). This parser creates a file containing the whole theme. It can then be used in the `tailwind.config.js`. diff --git a/parsers/to-theme-ui/README.md b/parsers/to-theme-ui/README.md index ba2b7210..03ad1c24 100644 --- a/parsers/to-theme-ui/README.md +++ b/parsers/to-theme-ui/README.md @@ -2,7 +2,7 @@ ## Description -Format design tokens to create a theme compatible with the [theme-ui specification](https://theme-ui.com/theme-spec). +This parser helps you format design tokens to create a theme compatible with the [theme-ui specification](https://theme-ui.com/theme-spec). Learn more about how to configure Specify in the API documentation: [https://specifyapp.com/developers](https://specifyapp.com/developers). diff --git a/parsers/to-typescript-definition/README.md b/parsers/to-typescript-definition/README.md index 5cf2a6fa..c9977375 100644 --- a/parsers/to-typescript-definition/README.md +++ b/parsers/to-typescript-definition/README.md @@ -2,7 +2,7 @@ ## Description -Format design tokens to create their corresponding TypeScript types. +This parser helps you format design tokens to create their corresponding TypeScript types. This parser generates TypeScript types corresponding to [Specify Token types](https://docs.specifyapp.com/concepts/token-types). All types respective values match the name of your design tokens returned by Specify. diff --git a/scripts/list-parsers.js b/scripts/list-parsers.js new file mode 100644 index 00000000..67fd3b95 --- /dev/null +++ b/scripts/list-parsers.js @@ -0,0 +1,118 @@ +const fs = require('fs'); +const path = require('path'); + +const directoryPath = path.join(__dirname, '../', 'parsers'); +let parsers = []; +const fileNames = fs.readdirSync(directoryPath); + +const directories = fileNames.filter(fileName => !fileName.includes('.ts')); + +parsers = directories.map(directory => { + const readmeParserPath = path.join(__dirname, '../', 'parsers', directory, 'README.md'); + const parserContent = fs.readFileSync(readmeParserPath, { encoding: 'utf8', flag: 'r' }); + + const parserDescription = parserContent.match(/This parser helps you (.*)/)[1]; + const capitalizedParserDescription = + parserDescription.charAt(0).toUpperCase() + parserDescription.slice(1); + const exampleLink = `https://github.com/Specifyapp/parsers/blob/master/parsers/${directory}/README.md#usage`; + const parserLink = `https://github.com/Specifyapp/parsers/blob/master/parsers/${directory}`; + + return { + title: directory, + description: capitalizedParserDescription, + parserLink, + exampleLink, + }; +}); + +const markdownFullPage = `--- +description: >- + Parsers are functions allowing you to transform design tokens and assets + coming from Specify to fit your needs and company standards. +--- + +# Parsers + +## Why you need parsers + +

Parsers help you transform raw design tokens and assets returned by Specify to match your company standards

+ +By default, without any parsers, Specify will return your design data as raw data: + +* Design tokens are returned in JSON +* Assets are returned as files + +There are high chances you need to transform those design data to fit your needs. Parsers help you do just that. + +## What are parsers? + +Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards. + +

An example output pipeline that pulls colors from Specify, sorts them alphabetically and transforms them as CSS Custom Properties

+ +A parser does the following job: + +1. Receives design data as input +2. Transforms this design data +3. Returns the transformed data + +The data returned by a parser can either be: + +* Design data that can be used by another parser coming next in your transformation pipeline +* A file so it can be used by people, frameworks, or scripts + +{% hint style="info" %} +Parsers are what make Specify powerful and flexible. They help you be in total control of the design data you pull from Specify. +{% endhint %} + +Parsers are ordered and takes specific input to generate specific output. This way, we can easily test the input coming from the previous parser to check if the whole parsers process will work. + +## Categories + +Parsers are classified in 2 categories: technology and utility. + +### Technology + +Technology parsers help you transform your design tokens to specific technologies and formats (CSS Custom properties, SCSS, Tailwind, a Javascript theme object compatible with React Native...) + +Some examples: + +* [to-react-native](https://github.com/Specifyapp/parsers/tree/master/parsers/to-react-native) +* [to-css-custom-properties](https://github.com/Specifyapp/parsers/tree/master/parsers/to-css-custom-properties) +* [to-scss-variables](https://github.com/Specifyapp/parsers/tree/master/parsers/to-scss-variables) +* [to-tailwind](https://github.com/Specifyapp/parsers/tree/master/parsers/to-tailwind) + +### Utility + +Utility parsers take care of "smaller" transformation. Like converting a pixel value to \`rem\` or transforming a string to kebabcase. + +Some examples: + +* [convert-font](https://github.com/Specifyapp/parsers/tree/master/parsers/convert-font) +* [kebabcasify](https://github.com/Specifyapp/parsers/tree/master/parsers/kebabcasify) +* [px-to-rem](https://github.com/Specifyapp/parsers/tree/master/parsers/px-to-rem) + +## All parsers available + +All parsers are open source and available on [the following GitHub repository](https://github.com/Specifyapp/parsers). + +`; + +const markdownHeader = `| Parser | Description | Usage Example | +|---|---|---|`; + +const parsersMarkdown = parsers.reduce((acc, currentParser) => { + const { title, description, exampleLink, parserLink } = currentParser; + if (!acc) { + return `${markdownHeader} +| [${title}](${parserLink}) | ${description} | [Example](${exampleLink}) |`; + } + return `${acc} +| [${title}](${parserLink}) | ${description} | [Example](${exampleLink}) |`; +}, ''); + +const summaryFilePath = path.join(__dirname, '../output/', 'parsers.md'); +fs.writeFileSync(summaryFilePath, markdownFullPage + parsersMarkdown, { + encoding: 'utf8', + flag: 'w', +});