"readme": "<p align=\"center\">\n <sup><em>«On the count of ten you will be in...»</em></sup>\n</p>\n\n\n\n<p align=\"center\">\n <a href=\"https://travis-ci.org/brandocms/europacss\"><img src=\"https://img.shields.io/travis/brandocms/europacss/master.svg\" alt=\"Build Status\"></a>\n <a href=\"https://badge.fury.io/js/%40brandocms%2Feuropacss\"><img src=\"https://badge.fury.io/js/%40brandocms%2Feuropacss.svg\" alt=\"npm version\" height=\"18\"></a>\n</p>\n\n------\n\nEuropaCSS originally began as a collection of SASS mixins and functions that came in\nhandy when working with design agencies that had very specific designs over different\nbreakpoints. These design systems translate pretty well to configurations and allows\nweeding out a lot of the boilerplate involved.\n\n## USAGE WITH POSTCSS\n\nExample `postcss.config.js`:\n\n```js\nmodule.exports = {\n plugins: [\n require('@univers-agency/europacss')({\n // You can specify your config in one of these ways:\n\n // 1. Default: Automatically looks for ./europa.config.js or ./europa.config.cjs\n\n // 2. Path to config file:\n // config: './path/to/europa.config.js',\n\n // 3. Direct configuration object:\n // config: { /* Your europacss config */ },\n\n // 4. PostCSS Preset Env options:\n presetEnv: {\n // browsers: ['> 1%', 'last 2 versions'],\n // features: { /* specific features */ },\n // preserve: false,\n // disable: false // Set to true to disable postcss-preset-env entirely\n }\n }),\n require('postcss-reporter')({ clearReportedMessages: true, throwError: false })\n ]\n}\n```\n\n> Note: You no longer need to include `autoprefixer` or `css-mqgroup` as those are now handled internally by EuropaCSS.\n\n## NOTES\n\n- Remember to keep your `@import` statements at the top of your `.css` file\n- Add\n\n```\n@europa arrows;\n@europa base;\n```\n\n to your main stylesheet\n\n\n## CONFIG\n\n`setMaxForVw`\n\nIf you have a set max size for your largest container, you should enable `setMaxForVw`. This will\nensure that the largest breakpoint of your vw based sizes will be set to a fixed size.\n\nFor instance, if you have:\n```\n{\n setMaxForVw: true,\n theme: {\n container: {\n maxWidth: {\n mobile: '100%',\n tablet: '100%',\n desktop: '1920px'\n }\n },\n typography: {\n sizes: {\n h1: {\n mobile: '18px',\n tablet: '4vw',\n desktop: '4vw'\n }\n }\n }\n }\n}\n```\nwe will replace the desktop key's `4vw` with `1920/100*4` so that the font will not scale\nbeyond the container's maxWidth.\n\n`dpxViewportSize` and `dpxViewportSizes`\n\nWhen working with design pixel units (dpx), you can specify reference viewport widths to convert\ndesign pixels to viewport width units. This is especially useful when working with Figma designs\nthat are created at specific widths for different device sizes.\n\nYou can set a global reference width with `dpxViewportSize`, or specify different reference widths\nfor individual breakpoints and breakpoint collections using `dpxViewportSizes`:\n\n```js\n{\n // Global fallback reference width (used if no specific width is defined)\n dpxViewportSize: 1440, // Default is 1440px if not specified\n\n // Per-breakpoint and per-collection reference viewport widths\n dpxViewportSizes: {\n // Direct breakpoint references\n xs: 375,\n sm: 768,\n\n // Breakpoint collections\n $desktop: 1440,\n $tablet: 768,\n $mobile: 375\n },\n\n theme: {\n typography: {\n sizes: {\n heading: {\n mobile: '25dpx', // Uses 375px reference (from $mobile collection)\n tablet: '35dpx', // Uses 768px reference (from $tablet collection)\n desktop: '45dpx' // Uses 1440px reference (from $desktop collection)\n }\n }\n }\n }\n}\n```\n\nFor example, when using `25dpx` at the `$mobile` reference viewport width of 375px, it will be\nconverted to `6.667vw` (`(25/375)*100`). The same value in the `$desktop` collection would\nuse the 1440px reference, resulting in `1.736vw` (`(25/1440)*100`).\n\nWhen processing dpx units, Europa looks for a reference width in this order:\n1. A direct match in `dpxViewportSizes` for the current breakpoint (e.g., `xs`, `md`, etc.)\n2. A match in `dpxViewportSizes` for a collection that includes the current breakpoint (e.g., `$mobile`, `$desktop`)\n3. The global `dpxViewportSize` value\n4. Default fallback of 1440px\n\nThis makes it easy to maintain the exact sizing from design files while keeping\nthe responsive behavior of viewport units across different device sizes.\n\n\n### Typography\n#### Sizes\n\n`typography`\n `sizes`\n `size_name`\n `breakpoint_name`: `value`\n\n**Examples**\n\nA regular setup:\n\n```\n typography: {\n sizes: {\n base: {\n mobile: '16px'\n }\n }\n }\n```\n\nIf `value` is an object, all properties will be added to the selector, i.e:\n\n```\n typography: {\n sizes: {\n base: {\n mobile: {\n 'font-size': '16px',\n 'line-height': 1.25\n }\n }\n }\n }\n```\n\n\n## AT-RULES\n\ntodo\n\n### `@responsive {breakpointQuery} {block}`\n\n**EXAMPLE**:\n\n```\n@responsive desktop_md {\n display: none;\n}\n\n@responsive <=ipad_portrait {\n color: red;\n}\n```\n\n\n### `@color {fg/bg/stroke/fill/border/border-[top|bottom|left|right]} {colorName/hex}`\n\nTries to get `colorName` from `theme.colors`, otherwise passes the color through\n\n**EXAMPLE**:\n\n```\nh2 {\n @color fg headings.h2;\n @color bg transparent;\n}\n```\n\n\n### `@grid`\n\nSets column gap to your gutter configuration across all breakpoints.\n\n**EXAMPLE**:\n\n```\n.my-grid {\n @grid;\n grid-template-areas: \"a b\"\n \"a c\";\n grid-template-columns: 6fr 6fr;\n\n .a {\n grid-area: a;\n }\n\n .b {\n grid-area: b;\n }\n\n .c {\n grid-area: c;\n }\n}\n```\n\nThis creates a 6 columns wide stacking grid.\n\n\n### `@display [displayType[/flexDirection][/flexWrap]] [breakpointQuery]`\n\nAdd shortcut for responsive display decls.\n\n**EXAMPLE**:\n\n```\narticle {\n @display flex $mobile;\n}\n\narticle {\n @display flex/row/wrap $mobile;\n}\n```\n\n\n### `@order {orderNumber} [breakpointQuery]`\n\nAdd shortcut for responsive order decls.\n\n**EXAMPLE**:\n\n```\narticle {\n @order 1 $mobile;\n}\n```\n\n\n### `@embed-responsive {aspectRatio}\n\n**PARAMS**:\n\n`{aspectRatio}`\n - 16/9\n\n\n### `@space {decl} {sizeQuery} [breakpointQuery]`\n\n**PARAMS**:\n\n`{decl}`\n - `container` (does not accept `sizeQuery`, only `[breakpointQuery]`)\n - `margin-x`, `margin-y`, `padding-x`, `padding-y`\n - `translateX`, `translateY`, `translateZ`, `scale`\n - Any prop that accepts the values you give it.\n\n`{sizeQuery}`\n - `xs` > Gets XS from `theme.spacing` map.\n - `-xs` > Gets negative value of XS from `theme.spacing` map.\n - `2` > Gets `2` times the gutter padding.\n - `1/3` > Calcs a fraction.\n - `3:1/6` > Calcs a 3/6 fraction but with 1 added gutter unit\n - `xs/2` > Gets half of the XS from `theme.spacing` map.\n - `between(20px-50px)` > Scales the value from 20px at the start of breakpoint to 50px at the end of breakpoint.\n - `container` > Gets value from `theme.container.padding` for breakpoint.\n - `-container` > Gets negative value of `theme.container.padding` for breakpoint.\n - `vertical-rhythm(theme.typography.sizes.xl)` > Grabs object for breakpoint and multiplies with default line-height.\n - `vertical-rhythm(theme.typography.sizes.xl, 1.2)` > Grabs object for breakpoint and multiplies with 1.2 as line-height.\n - `calc(100vw - var[container] + var[1])` > Switches out `var[container]` and `var[1]` with correct values for\n container padding and 1 gutter unit per breakpoint.\n - `20dpx` > Design pixel units that scale with viewport width based on the `dpxViewportSize` setting (defaults to 1440px).\n\n**EXAMPLES**:\n\n```postcss\n.block {\n @space margin-y xl/2;\n\n &:first-of-type {\n @space margin-top xl;\n }\n\n &:last-of-type {\n @space margin-bottom: xl;\n }\n}\n\n.overlap {\n /* Use negative named spacing to create overlaps */\n @space margin-top -block;\n}\n\n.powerful-stuff {\n /* move element 4 columns + a gutter size to the left */\n @space translateX calc(var[4:1/12] * -1);\n}\n```\n\nIf you need the set properties to be marked as `!important` you can use `@space!`\n\n```postcss\n @space! margin-left xs;\n```\n\n### `@font {fontFamily} [fsQuery]`\n\nSelects a font family. Can also be passed a font size query.\n\n**PARAMS**:\n\n`{fontFamily}`\n - picks `fontFamily` from `typography.families`\n\n`[fsQuery]`\n - can also be passed. Will then create a `@fontsize` rule with `fsQuery` as params\n\n\n### `@fontsize {fsQuery} [breakpointQuery]`\n\n**PARAMS**:\n\n`{fsQuery}`\n - `lg` > Picks the `lg` key from `theme.typography.sizes` across breakpoints\n - `lg/2.0` > Also sets `line-height` to `2.0`\n - `lg(2.0)/2.0` > Adds a modifier `(2.0)` that gets used as a multiplier in a calc() for the final font-size.\n - `between(18px-22px)` > Responsive font sizing, from 18px to 22px. Needs a breakpoint to function properly.\n - `product.size` > Traverses the keypath `product.size` within `theme.typography.sizes`\n - `20dpx` > Design pixel units that scale with viewport width based on the `dpxViewportSize` setting (defaults to 1440px)\n\n`[breakpointQuery]`\n - `xs` > Only for the `xs` breakpoint\n - `>=md` > Only for larger or equal to `md`\n\n\n### `ease() function`\n\nProvides easing functions as CSS cubic-bezier values. This function can be used in any CSS property that accepts `transition-timing-function` values.\n\n**PARAMS**:\n\n`type`\n - Standard: `ease`, `ease.in`, `ease.out`, `ease.inOut`\n - Sine: `sine.in`, `sine.out`, `sine.inOut`\n - Quad: `quad.in`, `quad.out`, `quad.inOut`\n - Cubic: `cubic.in`, `cubic.out`, `cubic.inOut`\n - Quart: `quart.in`, `quart.out`, `quart.inOut`\n - Quint: `quint.in`, `quint.out`, `quint.inOut`\n - Expo: `expo.in`, `expo.out`, `expo.inOut`\n - Circ: `circ.in`, `circ.out`, `circ.inOut`\n - Back: `back.in`, `back.out`, `back.inOut`\n - Power1-4: `power1.in`, `power1.out`, `power1.inOut` through `power4.in`, `power4.out`, `power4.inOut`\n\n**EXAMPLES**:\n\n```postcss\n.element {\n transition: transform 300ms ease('power3.out');\n}\n\n.another-element {\n transition: opacity 500ms ease('sine.inOut'), transform 800ms ease('back.out');\n}\n```\n\nNote: If an invalid easing name is provided, an error will be thrown during CSS processing.\n\n\n### `@if {value} {block}`\n\nRenders `{block}` if `{value}` is true. Ignores it otherwise.\n\n**PARAMS**:\n\n`{value}`\n - `theme.typography.optimizeLegibility` > Checks value in theme config.\n\n**EXAMPLES**:\n\n```postcss\n@if theme.typography.optimizeLegibility {\n article {\n text-rendering: optimizeLegibility;\n -webkit-font-smoothing: antialiased;\n -moz-osx-font-smoothing: grayscale;\n }\n}\n```\n\n\n### `@column {sizeQuery} [breakpointQuery] `\n\nCreates a flex column inside rule.\n\n**PARAMS**:\n\n`{sizeQuery}`\n - `1/3` > Takes up one third of container, across all breakpoints\n - `3:1/6` > Takes up one third of container, across all breakpoints, with 1 unit of gutter\n - `calc(var[container] + var[6/12])` > 6/12 columns + width of container gutter\n\n`[breakpointQuery]`\n - `xs` > For xs breakpoint only\n - `xs/sm/xl` > For xs, sm and xl breakpoints\n - `<=md` > Less and equal to the md breakpoint\n\n\n**EXAMPLES**:\n\n```postcss\narticle {\n @column 1/3;\n @column 3/3 xs;\n}\n/* Column is 1/3 wide on all devices, except xs, which is 3/3. */\n```\n\n### `@iterate {iterable} block`\n\nIterates through a config object.\n\n**PARAMS**:\n\n`{iterable}`\n - a path in the theme.object, I.E `theme.header.padding.small`\n\n**EXAMPLES**:\n\n```postcss\narticle {\n @iterate theme.header.padding.small {\n @responsive $key {\n padding-top: $value;\n padding-bottom: $value;\n }\n }\n}\n```\n\nThis creates a media query for each key in `theme.header.padding.small`\n\n### `@unpack {object}`\n\nUnpacks a config object.\n\n**PARAMS**:\n\n`{object}`\n - a path in the theme object, I.E `theme.typography.sections.navigation`\n\n**EXAMPLES**:\n\n```postcss\narticle {\n @unpack theme.typography.sections.navigation;\n}\n```\n\nresults in\n\n```css\n @media (min-size: 0) and (max-size: 749px) {\n article {\n font-size: 1.2rem;\n line-height: 1.6;\n }\n }\n\n @media (min-size: 750px) and (max-size: 1039px) {\n article {\n font-size: 1.4rem;\n line-height: 1.5;\n }\n }\n\n /* ... */\n```\n\n\n## POSTCSS PLUGINS IN USE\n\nThis would not be possible without the following great plugins:\n\n - `postcss-extend-rule`\n - `postcss-functions`\n - `postcss-nested`\n - `postcss-preset-env`\n - `postcss-combine-duplicated-selectors`\n - `postcss-nesting`\n",
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments