{"id":13493834,"url":"https://github.com/typographist/postcss","last_synced_at":"2025-03-28T13:31:08.543Z","repository":{"id":55824123,"uuid":"102346708","full_name":"typographist/postcss","owner":"typographist","description":null,"archived":true,"fork":false,"pushed_at":"2020-12-11T18:41:08.000Z","size":2842,"stargazers_count":59,"open_issues_count":11,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-31T08:37:31.001Z","etag":null,"topics":["css","design","frontend","javascript","mg901","modular","modular-scale","modularscale","modularscale-postcss","musical-scales","postcss","postcss-plugin","postcss-toolkit","ratio","scale","typo","typographist","typography","vertical-rhythm","web-typography"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typographist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-04T09:56:57.000Z","updated_at":"2023-01-28T10:31:42.000Z","dependencies_parsed_at":"2022-08-15T07:30:36.013Z","dependency_job_id":null,"html_url":"https://github.com/typographist/postcss","commit_stats":null,"previous_names":["typography-gang/typographist"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typographist%2Fpostcss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typographist%2Fpostcss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typographist%2Fpostcss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typographist%2Fpostcss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typographist","download_url":"https://codeload.github.com/typographist/postcss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246037255,"owners_count":20713385,"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","frontend","javascript","mg901","modular","modular-scale","modularscale","modularscale-postcss","musical-scales","postcss","postcss-plugin","postcss-toolkit","ratio","scale","typo","typographist","typography","vertical-rhythm","web-typography"],"created_at":"2024-07-31T19:01:19.256Z","updated_at":"2025-03-28T13:31:08.236Z","avatar_url":"https://github.com/typographist.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch3\u003e\u003ca href=\"https://maxinakenty.github.io/\" target=\"_blank\" title=\"Demo\"\u003eDemo\u003c/a\u003e\u003c/h3\u003e\n\n# Typographist\n\n## Documentation\n\n- [Introduction](#introduction)\n- [Getting Started](#getting-started)\n\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n    - [base](#base)\n    - [line-height](#line-height)\n    - [ratio](#ratio)\n    - [breakpoint](#breakpoint)\n    - [typographist with webpack](#typographist-with-webpack)\n    - [typographist with gulp](#typographist-with-gulp)\n\n  CSS\n\n  - [PostCSS syntax hightlight](#postcss-syntax-hightlight)\n  - [Syntax peculiarity](#syntax-peculiarity)\n  - [Root font size](#root-font-size)\n  - [Base font size](#base-font-size)\n  - [Breakpoints](#breakpoints)\n  - [Step unit](#step-unit)\n  - [T-step function](#t-step-function)\n  - [Nesting](#nesting)\n\n## Introduction\n\n### What is a Typographist?\n\nThe Typographist is a mobile first progressive toolkit for web designers and developers that allows you to build interfaces with responsive graphics. Having absorbed the best qualities of \u003ca href=\"https://github.com/jakegiltsoff/sassline\" target=\"_blank\" title=\"Sassline\"\u003eSassline\u003c/a\u003e and \u003ca href=\"https://github.com/matejlatin/Gutenberg\" target=\"_blank\" title=\"Gutenberg\"\u003eGutenberg\u003c/a\u003e, it significantly simplifies the process of improving typography on the web.\nThe framework's objective is to provide developers with the most simple, powerful and flexible tool that will take over all the routine work in the form of complex calculations. The Typographist builds a basic grid to establish the correct vertical rhythm on the basis of rem, and also establishes macro-tipography, which allows paying special attention to micro-tipographic details. Also the toolkit is perfectly combined with css grid layout.\n\n### Base type \\* line-height = leading\n\nThe correct vertical rhythm leads to a constant distance between the elements, which helps to clarify the structure and order of the contents and to associate it with other elements. The ultimate goal of the program is to draw the reader's attention to the text and improve the readability in general.\n\n### Root font-size = ½ leading\n\nTypographist works by setting the root font-size as half the line-height of the standard paragraph text. The height of the baseline grid is then effectively set at 2, with increments at each 1rem. This makes it a pleasant and easy tool for creating harmony of content in your layout and typography. This is based off a technique for setting text in print documents.\n\n## Getting Started\n\n### Installation\n\nTo install the stable version:\n\n**yarn**\n\n```\nyarn add postcss @typographist/postcss -D\n```\n\n**npm**\n\n```\nnpm i postcss  @typographist/postcss\n```\n\n### Configuration\n\n1.  Connect Typographist\n\nrequireJs\n\n```js\nconst { typographist, ratios } = require('@typographist/postcss');\n```\n\nes6 modules\n\n```js\nimport { typographist, ratios } from ' @typographist/postcss';\n```\n\n#### Base\n\n2.  Set font size for standard paragraph text. For example, I set 16px, but you can choose one that you like. Feel free to constantly experiment.\n    Base is set for each breakpoint.\n\n```js\ntypographist({\n  base: '16px',\n});\n```\n\n#### Line-height\n\n3.  Set the line-height. For example, I set 1.4. It is not necessary to specify at each breakpoint. Each next breakpoint inherits the value of line-height from the previous breakpoint.\n\n```js\ntypographist({\n  base: '16px',\n  lineHeight: 1.4,\n});\n```\n\n#### Ratio\n\n4.  Set the ratio. To do this, we use Tim Brown's \u003ca href=\"http://www.modularscale.com/\" target=\"_blank\" title=\"Modular Scale\"\u003eModular Scale\u003c/a\u003e. For example, I set a ratio equal to the minor second (~1.067) \u003ca href=\"http://www.modularscale.com/?16\u0026px\u00261.067\" target=\"_blank\" title=\"Let's see what happened\"\u003eLet's see what happened\u003c/a\u003e. It is not necessary to specify at each breakpoint. Each next breakpoint inherits the value of line-height from the previous breakpoint.\n\n```js\ntypographist({\n  base: '16px',\n  lineHeight: 1.4,\n  ratio: ratios.MINOR_SECOND,\n});\n```\n\n##### Ratios\n\n| function         |  ratio  | decimal value |\n| ---------------- | :-----: | :-----------: |\n| AUGMENTED_FOURTH |  1:√2   |    1.41421    |\n| DOUBLE_OCTAVE    |   1:4   |       4       |\n| GOLDEN_SECTION   | 1:1.618 |   1.618034    |\n| MAJOR_ELEVENTH   |   3:8   |  2.666666667  |\n| MAJOR_SECOND     |   8:9   |     1.125     |\n| MAJOR_SEVENTH    |  8:15   |     1.875     |\n| MAJOR_SIXTH      |   3:5   |  1.666666667  |\n| MAJOR_TENTH      |   2:5   |      2.5      |\n| MAJOR_THIRD      |   4:5   |     1.25      |\n| MAJOR_TWELFTH    |   1:3   |       3       |\n| MINOR_SECOND     |  15:16  |  1.066666667  |\n| MINOR_SEVENTH    |  9:16   |  1.777777778  |\n| MINOR_THIRD      |   5:6   |      1.2      |\n| OCTAVE           |   1:2   |       2       |\n| PERFECT_FIFTH    |   2:3   |      1.5      |\n| PERFECT_FOURTH   |   3:4   |  1.333333333  |\n| PHI              | 1:1.618 |   1.618034    |\n\n#### Breakpoint\n\n5.  Set the breakpoint name and breakpoint value.\n\n```js\ntypographist({\n  base: '16px',\n  lineHeight: 1.4,\n  ratio: ratios.MINOR_SECOND,\n  tablet: {\n    breakpoint: '768px',\n  },\n});\n```\n\nYou are free to choose any breakpoint name, and you can specify just how many breakpoints you need. If you are used to naming breakpoints as in bootstrap, nothing prevents you from using the usual names.\n\n```js\ntypographist({\n  base: '16px',\n  lineHeight: 1.4,\n  ratio: ratios.MINOR_SECOND,\n  sm: {\n    // your code\n  },\n  md: {\n    // your code\n  },\n  lg: {\n    // your code\n  },\n  xl: {\n    // you code\n  },\n});\n```\n\n6.  Let's set base, line-height, and ratio for each breakpoint. For the tablet, I set the ratio to a \u003ca href=\"http://www.modularscale.com/?17\u0026px\u00261.125\" target=\"_blank\" title=\"major second\"\u003emajor second\u003c/a\u003e = 1.125. For the desktop it will be equal to the \u003ca href=\"http://www.modularscale.com/?18\u0026px\u00261.2\" target=\"_blank\" title=\"minor third\"\u003eminor third\u003c/a\u003e = 1.2.\n\n```js\ntypographist({\n  base: '16px',\n  lineHeight: 1.4,\n  ratio: ratios.MINOR_SECOND,\n  tablet: {\n    breakpoint: '768px',\n    base: '17px',\n    ratio: ratios.MAJOR_SECOND,\n  },\n  desktop: {\n    breakpoint: '992px',\n    base: '18px',\n    ratio: ratios.MINOR_THIRD,\n  },\n  lgDesktop: {\n    breakpoint: '1200px',\n    base: '20px',\n  },\n}),\n```\n\nYou probably noticed that I did not set a ratio for a breakpoint named lgDesktop. It's all right. As mentioned earlier, this value will be inherited from the previous breakpoint.\n\nI hope it was not difficult for you. The idea of such a simple configuration I borrowed from \u003ca href=\"https://github.com/scottkellum\" target=\"_blank\" title=\"Skott Kellum\"\u003eSkott Kellum\u003c/a\u003e and his remarkable project \u003ca href=\"https://github.com/modularscale/modularscale-sass\" target=\"_blank\" title=\"modularscale-sass\"\u003emodularscale-sass\u003c/a\u003e. Well? Fasten your seat belts. This is where the fun begins.)\n\n#### Typographist with Webpack\n\nYou need to create a `postcss.config.js` or `.postcssrc.js`\n\n```js\nconst { typographist, ratios } = require('typographist');\n\nmodule.exports = () =\u003e ({\n  plugins: [\n    typographist({\n      base: '16px',\n      lineHeight: 1.4,\n      ratio: ratios.MINOR_SECOND,\n      tablet: {\n        breakpoint: '768px',\n        base: '17px',\n        ratio: ratios.MAJOR_SECOND,\n      },\n      desktop: {\n        breakpoint: '992px',\n        base: '18px',\n        ratio: ratios.MINOR_THIRD,\n      },\n      lgDesktop: {\n        breakpoint: '1200px',\n        base: '20px',\n      },\n    }),\n  ],\n});\n```\n\n#### Typographist with Gulp\n\n```js\nconst gulp = require('gulp');\nconst gulpIf = require('gulp-if');\nconst postcss = require('gulp-postcss');\nconst sourcemaps = require('gulp-sourcemaps');\nconst rename = require('gulp-rename');\nconst cssnano = require('gulp-cssnano');\nconst notify = require('gulp-notify');\nconst combine = require('stream-combiner2').obj;\nconst { typographist, ratios } = require('typographist');\n\nconst processors = [\n  typographist({\n    base: '16px',\n    lineHeight: 1.4,\n    ratio: ratios.MINOR_SECOND,\n    tablet: {\n      breakpoint: '768px',\n      base: '17px',\n      ratio: ratios.MAJOR_SECOND,\n    },\n    desktop: {\n      breakpoint: '992px',\n      base: '18px',\n      ratio: ratios.MINOR_THIRD,\n    },\n    lgDesktop: {\n      breakpoint: '1200px',\n      base: '20px',\n    },\n  }),\n];\n\nconst IS_DEVELOPMENT =\n  !process.env.NODE_ENV || process.env.NODE_ENV === 'development';\n\ngulp.task('styles', () =\u003e\n  combine(\n    gulp.src('./entryDir/entry.css'),\n    gulpIf(IS_DEVELOPMENT, sourcemaps.init()),\n    postcss(processors),\n    gulpIf(IS_DEVELOPMENT, sourcemaps.write()),\n    gulpIf(!IS_DEVELOPMENT, combine(cssnano())),\n    rename('main.css'),\n    gulp.dest('./outputDir/'),\n  ).on('error', notify.onError()),\n);\n```\n\n## CSS\n\n### Postcss syntax hightlight\n\nIf you use vscode as the code editor. To avoid conflicts with the linter and to correctly postcss syntax highlighting, install the plugin \u003ca href=\"https://marketplace.visualstudio.com/items?itemName=ricard.PostCSS#review-details\" target=\"_blank\"\u003ePostCSS syntax\u003c/a\u003e.\n\n### Root font size\n\nInput\nSet the root font-size.\n\n```css\n:root {\n  @root;\n}\n```\n\nOutput\n\n```css\n:root {\n  --tablet: 768px;\n  --desktop: 992px;\n  --lg-desktop: 1200px;\n  font-size: 68.75%;\n}\n@media screen and (min-width: 48em) {\n  :root {\n    font-size: 75%;\n  }\n}\n@media screen and (min-width: 62em) {\n  :root {\n    font-size: 81.25%;\n  }\n}\n@media screen and (min-width: 75em) {\n  :root {\n    font-size: 87.5%;\n  }\n}\n```\n\nUsing the @ root directive, we calculated the size of the root font for each breakpoint. Also now we have the opportunity to link our css and javascript to native css variables. The value of each breakpoint is converted to em.\n\nInput\n\n```css\n:root {\n  @root (fluid);\n}\n```\n\nOutput\n\n```css\n:root {\n  --tablet: 768px;\n  --desktop: 992px;\n  --lg-desktop: 1200px;\n  font-size: 68.75%;\n}\n@media screen and (min-width: 48em) {\n  :root {\n    font-size: calc(68.75% + 2 * ((100vw - 48em) / 224));\n  }\n}\n@media screen and (min-width: 62em) {\n  :root {\n    font-size: calc(81.25% + 1 * ((100vw - 62em) / 208));\n  }\n}\n@media screen and (min-width: 75em) {\n  :root {\n    font-size: 87.5%;\n  }\n}\n```\n\nNow our font and layout have become elastic. It is possible to have precise control over responsive typography. Using calc() and viewport units you can create fluid type that scales perfectly between specific pixel values, within a specific viewport range.\nThis was made possible by \u003ca href=\"https://github.com/MadeByMike\" target=\"_blank\" title=\"Mike Riethmuller\"\u003eMike Riethmuller\u003c/a\u003e and his formula.\n\n### Base font size\n\nInput\n\n```css\nbody {\n  @base;\n}\n```\n\nOutput\n\n```css\nbody {\n  font-size: 1.4545454545454546rem;\n  line-height: 2rem;\n}\n@media screen and (min-width: 48em) {\n  body {\n    font-size: 1.4166666666666667rem;\n  }\n}\n@media screen and (min-width: 62em) {\n  body {\n    font-size: 1.3846153846153846rem;\n  }\n}\n@media screen and (min-width: 75em) {\n  body {\n    font-size: 1.4285714285714286rem;\n  }\n}\n```\n\nThe @ t-base directive sets the size of the base font to rem for each breakpoint, and also sets line-height: 2rem.\n\n### Breakpoints\n\n#### @up\n\n@up takes as parameters the names of breakpoints, values in pixels or ems.\n\nInput\n\n```css\n.your-class {\n  @up (desktop) {\n    /* your code */\n  }\n}\n```\n\nOutput\n\n```css\n@media screen and (min-width: 62em) {\n  .your-class {\n    /* your code */\n  }\n}\n```\n\n#### @down\n\n@down takes as parameters the names of breakpoints, values in pixels or ems.\nInput\n\n```css\n.your-class {\n  @down (desktop) {\n    /* your code */\n  }\n}\n```\n\nOutput\n\n```css\n@media screen and (max-width: 74.99875em) {\n  .your-class {\n    /* your code */\n  }\n}\n```\n\n#### @only\n\n@only takes as parameters parameters only the names of breakpoints.\n\nInput\n\n```css\n.your-class {\n  @only (desktop) {\n    /* your code */\n}\n```\n\nOutput\n\n```css\n@media screen and (min-width: 62em) and (max-width: 74.99875em) {\n  .test {\n    /* your code */\n  }\n}\n```\n\n#### @between\n\n@between takes as parameters the names of breakpoints, values in pixels or ems.\n\nInput\n\n```css\n.your-class @between(tablet, desktop) {\n  /* your code */\n}\n```\n\nOutput\n\n```css\n@media screen and (min-width: 48em) and (max-width: 74.99875em) {\n  .your-class {\n    /* your code */\n  }\n}\n```\n\n### Step unit\n\nSet the font size from the position in the modular scale.\n\n  \u003cimg src=\"/img/msunit.jpg\" alt=\"position in modular scale\"\u003e\n\nTo convert step to rem, use directives @up, @down, or @only.\n\ninput\n\n```css\nh1 {\n  font-size: 6step;\n\n  @-above (tablet) {\n    font-size: 6step;\n  }\n\n  @up (desktop) {\n    font-size: 6step;\n  }\n\n  @up (lg-desktop) {\n    font-size: 6step;\n  }\n}\n```\n\nOutput\n\n```css\nh1 {\n  font-size: 2.1818181818181817rem;\n}\n@media screen and (min-width: 48em) {\n  h1 {\n    font-size: 2.8333333333333335rem;\n  }\n}\n@media screen and (min-width: 62em) {\n  h1 {\n    font-size: 4.153846153846154rem;\n  }\n}\n@media screen and (min-width: 75em) {\n  h1 {\n    font-size: 4.285714285714286rem;\n  }\n}\n```\n\nStep unit is converted to rem.\n\nThis approach is useful if you want to dramatically increase the font size on any of the breakpoints, but in most cases it is too cumbersome and we force you to duplicate the code every time. For this I have something better for you!\n\n### step function\n\nWith step function we do the same much faster and more gracefully.\n\nInput\n\n```css\nh1 {\n  font-size: step(6);\n}\n```\n\nOutput\n\n```css\nh1 {\n  font-size: 2.1818181818181817rem;\n}\n@media screen and (min-width: 48em) {\n  h1 {\n    font-size: 2.8333333333333335rem;\n  }\n}\n@media screen and (min-width: 62em) {\n  h1 {\n    font-size: 4.153846153846154rem;\n  }\n}\n@media screen and (min-width: 75em) {\n  h1 {\n    font-size: 4.285714285714286rem;\n  }\n}\n```\n\n### Nesting\n\nInheritance the name of the parent class. Do this as you are used to in sass, less and stylus.\n\nInput\n\n```css\n.your-class {\n  border: 1px solid gray;\n\n  \u0026__inner {\n    padding: 1rem;\n  }\n\n  \u0026__inner_active {\n    background-color: rebeccapurple;\n  }\n\n  \u0026:hover {\n    border: 1px solid black;\n  }\n}\n```\n\nOutput\n\n```css\n.your-class {\n  border: 1px solid gray;\n}\n.your-class__inner {\n  padding: 1rem;\n}\n.your-class__inner_active {\n  background-color: rebeccapurple;\n}\n.your-class:hover {\n  border: 1px solid black;\n}\n```\n\nMIT License\n\nCopyright (c) 2018 Maxim Alyoshin\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypographist%2Fpostcss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypographist%2Fpostcss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypographist%2Fpostcss/lists"}