Tailwind CSS and Capsize
15 |
16 |
24 |
17 |
20 |
21 |
23 | 
3 |
2 |
3 |
Capsized Text
13 | ``` 14 | 15 | # Table of Contents 16 | 17 | - [Installation](#installation) 18 | - [Usage](#usage) 19 | - [Trim by default](#trim-by-default) 20 | - [Default line-height](#default-line-height) 21 | - [Define a default font-family](#define-a-default-font-family) 22 | - [Usage with @apply](#usage-with--apply) 23 | - [Root font-size](#root-font-size) 24 | - [Limitation and Customization](#limitation-and-customization) 25 | - [Behind the scenes](#behind-the-scenes) 26 | - [This port vs original Capsize](#this-port-vs-original-capsize) 27 | - [cap-height (since v0.4.0)](#cap-height--since-v040-) 28 | - [Default values](#default-values) 29 | - [line-gap (since v0.4.0)](#line-gap--since-v040-) 30 | - [Default values](#default-values-1) 31 | 32 | ## Installation 33 | 34 | Install the plugin from npm: 35 | 36 | ```sh 37 | # Using npm 38 | npm install @themosaad/tailwindcss-capsize 39 | ``` 40 | 41 | Then add the plugin to your `tailwind.config.js` file: 42 | 43 | ```js 44 | // tailwind.config.js 45 | module.exports = { 46 | theme: { 47 | fontFamily: { 48 | // define your custom font 49 | sans: ['Inter var', 'sans-serif'], 50 | }, 51 | capsize: { 52 | fontMetrics: { 53 | // define font metrics for your custom font from Capsize's website 54 | sans: { 55 | capHeight: 2048, 56 | ascent: 2728, 57 | descent: -680, 58 | lineGap: 0, 59 | unitsPerEm: 2816, 60 | }, 61 | }, 62 | // define the utility class for trimming (leave empty to trim all text nodes) 63 | className: 'capsize', 64 | }, 65 | }, 66 | plugins: [require('@themosaad/tailwindcss-capsize')], 67 | } 68 | ``` 69 | 70 | ## Usage 71 | 72 | Now you can use the `capsize` class to trim any text: 73 | 74 | ```html 75 |Capsized Text
76 | ``` 77 | 78 | ### Trim by default 79 | 80 | if you prefer to trim text nodes by default, don't define a class name. This will move the trimming css to the font-size classes: 81 | 82 | ```js 83 | // tailwind.config.js 84 | module.exports = { 85 | theme: { 86 | capsize: { 87 | fontMetrics: { 88 | // ... 89 | }, 90 | // className: 'capsize', 91 | }, 92 | }, 93 | plugins: [require('@themosaad/tailwindcss-capsize')], 94 | } 95 | ``` 96 | 97 | this way, you can use: 98 | 99 | ```html 100 |Capsized Text
101 | ``` 102 | 103 | ### Default line-height 104 | 105 | The root `line-height` is set to `1.5` by default. Which you can alter via: 106 | 107 | ```js 108 | // tailwind.config.js 109 | module.exports = { 110 | theme: { 111 | capsize: { 112 | rootLineHeightUnitless: 1.2, 113 | }, 114 | } 115 | ``` 116 | 117 | Therefore, if that's the line-height you want for a capsized element, you can ditch the leading class: 118 | 119 | ```html 120 |Capsized Text
121 | ``` 122 | 123 | If you want better default line-height per font-size, you can enable the [defaultLineHeights experimental feature](https://github.com/tailwindlabs/tailwindcss/blob/v1.8.5/src/flagged/defaultLineHeights.js). Which will become the default in Tailwindcss v2. 124 | 125 | ```js 126 | // tailwind.config.js 127 | module.exports = { 128 | experimental: { 129 | defaultLineHeights: true, 130 | }, 131 | } 132 | ``` 133 | 134 | ### Define a default font-family 135 | 136 | In most cases, you'll have a default font-family that's used accross the website by default. 137 | 138 | If you added the `font-sans` class to the body or a parent element, you can use 139 | 140 | ```html 141 |Capsized Text
142 | ``` 143 | 144 | ### Usage with @apply 145 | 146 | Since the plugin outputs pseudo-elements, you'll need to use the experimental applyComplexClasses feature: 147 | 148 | ```js 149 | // tailwind.config.js 150 | module.exports = { 151 | experimental: { 152 | applyComplexClasses: true, 153 | }, 154 | } 155 | ``` 156 | 157 | Which will allow you to use: 158 | 159 | ```css 160 | p { 161 | @apply capsize font-sans text-xl leading-7; 162 | } 163 | ``` 164 | 165 | ### Root font-size 166 | 167 | The plugin outputs the following inside the `@tailwind/base`: 168 | 169 | ```css 170 | html { 171 | font-size: 16px; 172 | --root-font-size-px: 16; 173 | } 174 | ``` 175 | 176 | So overriding it from you css might mess up the trimming calculations. 177 | 178 | To change the default root font-size: 179 | 180 | ```js 181 | // tailwind.config.js 182 | module.exports = { 183 | theme: { 184 | capsize: { 185 | rootFontSizePx: { 186 | default: 16, 187 | }, 188 | }, 189 | }, 190 | } 191 | ``` 192 | 193 | You can also change the rootFontSize for each screen: 194 | 195 | ```js 196 | // tailwind.config.js 197 | module.exports = { 198 | theme: { 199 | capsize: { 200 | rootFontSizePx: { 201 | default: 16, 202 | sm: 18, 203 | lg: 20, 204 | }, 205 | }, 206 | }, 207 | } 208 | ``` 209 | 210 | ## Limitation and Customization 211 | 212 | - Accepts `rem` and `px` for fontSize. 213 | - Accepts `rem`, `px`, and `unitless` for lineHeight. 214 | - Doesn't trim text on IE11 as it uses css variables for the trimming calculations. (will work on a JS polyfill or an average pre-calculation for all project fonts) 215 | - ~~Adds `padding: 0.05px 0` to capsized element which will override your padding utility classes.~~ No longer the case from v0.3.0. 216 | 217 | ## Behind the scenes 218 | 219 | The plugin adds the following to typography-related utility classes: 220 | 221 | To font-family classes, it adds css variables with font metrics: 222 | 223 | ```css 224 | .font-sans { 225 | font-family: Inter var, system-ui; 226 | --cap-height-scale: 0.7272; 227 | --descent-scale: 0.2414; 228 | --ascent-scale: 0.96875; 229 | --line-gap-scale: 0; 230 | --line-height-scale: 1.2102; 231 | } 232 | ``` 233 | 234 | To font-size classes, it adds css variables for calculating the font-size in pixels: 235 | 236 | ```css 237 | .text-6xl { 238 | font-size: 4rem; 239 | --font-size-rem: 4; 240 | --font-size-px: calc(var(--font-size-rem) * var(--root-font-size-px)); 241 | } 242 | ``` 243 | 244 | To line-height classes, it adds css variables for calculating the line-height in pixels: 245 | 246 | ```css 247 | .leading-tight { 248 | line-height: 1.25; 249 | --line-height-unitless: 1.25; 250 | --line-height-px: calc(var(--line-height-unitless) * var(--font-size-px)); 251 | } 252 | ``` 253 | 254 | To the capsized element's pseduo selectors, it adds the trimming calculation: 255 | 256 | ```css 257 | .capsize::before { 258 | content: ''; 259 | display: table; 260 | --line-height-normal: calc(var(--line-height-scale) * var(--font-size-px)); 261 | --specified-line-height-offset-double: calc(var(--line-height-normal) - var(--line-height-px)); 262 | --specified-line-height-offset: calc(var(--specified-line-height-offset-double) / 2); 263 | --specified-line-height-offset-to-scale: calc( 264 | var(--specified-line-height-offset) / var(--font-size-px) 265 | ); 266 | --line-gap-scale-half: calc(var(--line-gap-scale) / 2); 267 | --leading-trim-top: calc( 268 | var(--ascent-scale) - var(--cap-height-scale) + var(--line-gap-scale-half) - var(--specified-line-height-offset-to-scale) 269 | ); 270 | margin-bottom: calc(-1em * var(--leading-trim-top)); 271 | } 272 | 273 | .capsize::after { 274 | content: ''; 275 | display: table; 276 | --line-height-normal: calc(var(--line-height-scale) * var(--font-size-px)); 277 | --specified-line-height-offset-double: calc(var(--line-height-normal) - var(--line-height-px)); 278 | --specified-line-height-offset: calc(var(--specified-line-height-offset-double) / 2); 279 | --specified-line-height-offset-to-scale: calc( 280 | var(--specified-line-height-offset) / var(--font-size-px) 281 | ); 282 | --prevent-collapse-to-scale: calc(var(--prevent-collapse) / var(--font-size-px)); 283 | --line-gap-scale-half: calc(var(--line-gap-scale) / 2); 284 | --leading-trim-bottom: calc( 285 | var(--descent-scale) + var(--line-gap-scale-half) - var(--specified-line-height-offset-to-scale) 286 | ); 287 | margin-top: calc(-1em * var(--leading-trim-bottom)); 288 | } 289 | ``` 290 | 291 | ## This port vs original Capsize 292 | 293 | Aside from implementing the calculations via CSS variables to allow the usage of utility classes as illustrated above, I use a different method to prevent margin collapse that's not yet used in the original Capsize package (capsize@1.1.0 at the time). 294 | 295 | Capsize currently adds a `0.05` top and bottom padding to the capsized element to prevent margin collapse. 296 | 297 | From v0.3.0, I implemented a new way to prevent the collapsing based on @michaeltaranto's findings in [this issue](https://github.com/seek-oss/capsize/issues/26#issuecomment-686796155) that's not yet implemented in their Capsize. 298 | 299 | Now, you can use padding classes on the capsized element: 300 | 301 | ```html 302 | 303 | Capsized Link with Padding 304 | 305 | ``` 306 | 307 | If you encountered any crossbrowser issue with the new prevent collapse implementation, you can reverse back to the original implementation with padding: 308 | 309 | ```js 310 | // tailwind.config.js 311 | module.exports = { 312 | theme: { 313 | capsize: { 314 | keepPadding: true, 315 | }, 316 | }, 317 | } 318 | ``` 319 | 320 | ## cap-height (since v0.4.0) 321 | 322 | Instead of setting the `font-size`, you can use `cap-height` to declare the height of a the capital letters, and it'll automatically set the `font-size` based on the `fontMetrics`. 323 | 324 | This comes in handy when you have an icon next to the test and you want to visually balance their height. 325 | 326 | ```html 327 |Capsized Text that's 1rem in height
328 | ``` 329 | 330 | ### Default values 331 | 332 | Default values are cut from the `extendedSpacingScale` feature flag. Found it unuseful to inclue the very small and very large values. 333 | 334 | You can override the default values via: 335 | 336 | ```js 337 | module.exports = { 338 | theme: { 339 | // ... 340 | capHeight: { 341 | 2: '0.5rem', 342 | 2.5: '0.625rem', 343 | 3: '0.75rem', 344 | 3.5: '0.875rem', 345 | 4: '1rem', 346 | 5: '1.25rem', 347 | 6: '1.5rem', 348 | 7: '1.75rem', 349 | 8: '2rem', 350 | 9: '2.25rem', 351 | 10: '2.5rem', 352 | 11: '2.75rem', 353 | 12: '3rem', 354 | 13: '3.25rem', 355 | 14: '3.5rem', 356 | 15: '3.75rem', 357 | }, 358 | }, 359 | } 360 | ``` 361 | 362 | ## line-gap (since v0.4.0) 363 | 364 | `line-gap` goes hand in hand with `cap-height` to have predectible height. 365 | 366 | If the following example wrapped to 2 lines. The total height of the element would be 3rem. 367 | 368 | ```html 369 |370 | Capsized Text that's 1rem in height and has a 1rem line-gap 371 |
372 | ``` 373 | 374 | ### Default values 375 | 376 | `line-gap` has the same default values as `cap-height` which you can override via: 377 | 378 | ```js 379 | module.exports = { 380 | theme: { 381 | // ... 382 | lineGap: { 383 | 2: '0.5rem', 384 | 2.5: '0.625rem', 385 | 3: '0.75rem', 386 | 3.5: '0.875rem', 387 | 4: '1rem', 388 | 5: '1.25rem', 389 | 6: '1.5rem', 390 | 7: '1.75rem', 391 | 8: '2rem', 392 | 9: '2.25rem', 393 | 10: '2.5rem', 394 | 11: '2.75rem', 395 | 12: '3rem', 396 | 13: '3.25rem', 397 | 14: '3.5rem', 398 | 15: '3.75rem', 399 | }, 400 | }, 401 | } 402 | ``` 403 | 404 | You can also set default `line-gap` values for each `cap-height` similar to the [defaultLineHeights experimental feature](https://github.com/tailwindlabs/tailwindcss/blob/v1.8.5/src/flagged/defaultLineHeights.js) via: 405 | 406 | ```js 407 | module.exports = { 408 | theme: { 409 | // ... 410 | capHeight: { 411 | 2: ['0.5rem', { lineGap: '0.5rem' }], 412 | 3: ['0.75rem', { lineGap: '0.625rem' }], 413 | // ... 414 | }, 415 | }, 416 | } 417 | ``` 418 | -------------------------------------------------------------------------------- /demo/components/GithubLink.js: -------------------------------------------------------------------------------- 1 | export default function GithubLink() { 2 | return ( 3 |{`text-${fontSize}`}
29 |{`text-${fontSize} leading-none`}
32 |{`text-${fontSize} leading-tight`}
35 |{`text-${fontSize} leading-relaxed`}
38 |{`cap-height-${capHeight}`}
53 |{`cap-height-${capHeight} line-gap-0`}
56 |{`cap-height-${capHeight} line-gap-8`}
59 |{`cap-height-${capHeight} line-gap-10`}
62 |