From 32ce8e6be3e13e5667b45670a9da97d584fb7e1d Mon Sep 17 00:00:00 2001 From: AlexanderBelokon Date: Thu, 10 Sep 2026 21:26:39 +0300 Subject: [PATCH 01/11] Switch over to UnoCSS as a base --- .eslintrc.json | 32 + .gitignore | 2 + CHANGELOG.md | 10 + MIGRATION_GUIDES.md | 31 + README.md | 30 +- babel.config.json | 7 +- batfish.config.js | 40 - docs/.vitepress/config.mjs | 94 + docs/.vitepress/documentation-layout.js | 235 + docs/.vitepress/hljs-github-theme.js | 110 + docs/.vitepress/html-example-markup.js | 9 + docs/.vitepress/theme/Catalog.vue | 83 + docs/.vitepress/theme/ColorGrid.vue | 23 + docs/.vitepress/theme/ExamplesIndex.vue | 21 + docs/.vitepress/theme/HtmlExample.vue | 69 + docs/.vitepress/theme/IconGrid.vue | 20 + docs/.vitepress/theme/Layout.vue | 180 + docs/.vitepress/theme/LayoutScales.vue | 122 + docs/.vitepress/theme/Logo.vue | 9 + docs/.vitepress/theme/catalog/Bleeds.vue | 27 + docs/.vitepress/theme/catalog/Buttons.vue | 76 + docs/.vitepress/theme/catalog/Checkboxes.vue | 37 + docs/.vitepress/theme/catalog/Flexbox.vue | 111 + docs/.vitepress/theme/catalog/Grids.vue | 93 + docs/.vitepress/theme/catalog/Inputs.vue | 65 + docs/.vitepress/theme/catalog/Links.vue | 47 + docs/.vitepress/theme/catalog/Lists.vue | 157 + docs/.vitepress/theme/catalog/Pills.vue | 47 + docs/.vitepress/theme/catalog/Radios.vue | 29 + docs/.vitepress/theme/catalog/Ranges.vue | 55 + docs/.vitepress/theme/catalog/Selects.vue | 79 + docs/.vitepress/theme/catalog/Switches.vue | 41 + docs/.vitepress/theme/catalog/Tables.vue | 190 + docs/.vitepress/theme/catalog/Textareas.vue | 36 + docs/.vitepress/theme/catalog/Toggles.vue | 119 + docs/.vitepress/theme/catalog/Triangles.vue | 34 + docs/.vitepress/theme/catalog/Typography.vue | 119 + docs/.vitepress/theme/data.js | 43 + docs/.vitepress/theme/docs.css | 29 + docs/.vitepress/theme/index.js | 11 + docs/.vitepress/theme/site-nav.js | 144 + docs/catalog.md | 9 + docs/documentation/animations.md | 39 + docs/documentation/buttons.md | 108 + docs/documentation/colors.md | 37 + docs/documentation/forms.md | 427 + docs/documentation/icons.md | 21 + docs/documentation/index.md | 16 + docs/documentation/layout.md | 808 + docs/documentation/links.md | 38 + docs/documentation/miscellaneous.md | 131 + docs/documentation/tables.md | 85 + docs/documentation/theming.md | 175 + docs/documentation/triangles.md | 25 + docs/documentation/typography.md | 385 + docs/examples/badges.md | 37 + docs/examples/equal-height-columns.md | 31 + docs/examples/index.md | 9 + docs/examples/inputs.md | 32 + .../legends.js => docs/examples/legends.md | 46 +- .../modal.js => docs/examples/modal.md | 25 +- .../examples/navigation.md | 49 +- docs/examples/progress-bars.md | 26 + .../examples/sidebar-apps.md | 37 +- docs/examples/spinner.md | 12 + docs/examples/tooltips.md | 42 + docs/icons.md | 9 + docs/index.md | 248 + docs/layout-scales.md | 9 + {site => docs/public}/img/baseline-grid.svg | 0 {site => docs/public}/img/box-model.svg | 0 {site => docs/public}/img/custom-icons.svg | 0 {site => docs/public}/img/defaults.svg | 0 {site => docs/public}/img/focus.svg | 0 {site => docs/public}/img/is-active.svg | 0 {site => docs/public}/img/media-queries.svg | 0 {site => docs/public}/img/modifier.svg | 0 {site => docs/public}/img/spacedog800.jpg | Bin {site => docs/public}/img/specificity.svg | 0 examples/jit/assembly.css | 34 + examples/jit/build.mjs | 63 + examples/jit/index.html | 53 + index.js | 6 +- nodemon.json | 11 - package-lock.json | 27139 ++++-------- package.json | 49 +- scripts/build-color-variants.js | 637 - scripts/build-css.js | 213 - scripts/build-icon-json.js | 38 - scripts/build-layout-scales.js | 641 - scripts/build-media-variants.js | 195 - scripts/build-navigation-json.js | 253 - scripts/check-size.js | 29 - scripts/clean-svgs.js | 82 - scripts/deploy.js | 36 - scripts/order-sections.js | 43 - scripts/watch-assembly-assets.js | 21 - site/.eslintrc.json | 16 - site/application_wrapper.js | 11 - site/catalog/bleeds.js | 36 - site/catalog/buttons.js | 88 - site/catalog/checkboxes.js | 60 - site/catalog/flexbox.js | 123 - site/catalog/grids.js | 114 - site/catalog/inputs.js | 97 - site/catalog/links.js | 60 - site/catalog/lists.js | 171 - site/catalog/pills.js | 69 - site/catalog/radios.js | 62 - site/catalog/ranges.js | 73 - site/catalog/selects.js | 103 - site/catalog/switches.js | 72 - site/catalog/tables.js | 208 - site/catalog/textareas.js | 65 - site/catalog/toggles.js | 125 - site/catalog/triangles.js | 60 - site/catalog/typography.js | 149 - site/css/hljs.css | 90 - site/entry.js | 138 - site/heading.js | 59 - site/html_example.js | 34 - site/html_template.js | 22 - site/js/copy.js | 10 - site/logo.js | 23 - site/navigation.js | 118 - site/page.js | 46 - site/pages/catalog.js | 91 - site/pages/documentation.js | 41 - site/pages/examples/badges.js | 53 - site/pages/examples/equal-height-columns.js | 49 - site/pages/examples/index.js | 35 - site/pages/examples/inputs.js | 43 - site/pages/examples/progress-bars.js | 41 - site/pages/examples/spinner.js | 23 - site/pages/examples/tooltips.js | 53 - site/pages/favicon.ico | Bin 15086 -> 0 bytes site/pages/icons.js | 40 - site/pages/index.js | 436 - site/pages/layout-scales.js | 107 - src/animations.css | 97 - src/build-css.js | 170 + {scripts => src}/build-js.js | 2 +- {scripts => src}/build-svg-loader.js | 2 +- {scripts => src}/build-user-assets.js | 0 src/buttons.css | 231 - src/check-size.js | 30 + src/clean-svgs.js | 73 + src/color-variants.css | 3893 -- src/colors.css | 13 - src/deploy.js | 35 + src/focus.css | 38 - src/fonts.css | 42 - src/forms.css | 1012 - src/generate-uno.mjs | 20 + src/icons.css | 29 - src/layout-scales.css | 7748 ---- src/layout.css | 573 - src/links.css | 52 - src/md4-shim.js | 23 - src/miscellaneous.css | 289 - src/preset.js | 87 + src/preset/base.js | 2415 ++ src/preset/color-utils.js | 168 + src/preset/colors.js | 225 + src/preset/emit.js | 32 + src/preset/escape.js | 14 + src/preset/layout-scales.js | 214 + src/preset/media-classes.js | 151 + src/preset/utilities.js | 712 + src/preset/variants.js | 17 + src/reset.css | 124 - src/scales.json | 14 + src/tables.css | 154 - src/theming.css | 262 - {scripts => src}/timelog.js | 0 src/triangles.css | 92 - src/typography.css | 732 - .../build-color-variants.jest.js.snap | 8749 ---- test/__snapshots__/build-css.jest.js.snap | 35421 ++++------------ test/__snapshots__/build-js.jest.js.snap | 4 +- .../build-layout-scales.jest.js.snap | 7749 ---- .../build-media-variants.jest.js.snap | 824 - test/build-color-variants.jest.js | 40 - test/build-css.jest.js | 125 +- test/build-js.jest.js | 2 +- test/build-layout-scales.jest.js | 9 - test/build-media-variants.jest.js | 11 - test/build-user-assets.jest.js | 10 +- test/examples-jit.jest.js | 80 + test/generate-jit.mjs | 19 + test/preset.jest.js | 65 + 191 files changed, 26946 insertions(+), 84436 deletions(-) delete mode 100644 batfish.config.js create mode 100644 docs/.vitepress/config.mjs create mode 100644 docs/.vitepress/documentation-layout.js create mode 100644 docs/.vitepress/hljs-github-theme.js create mode 100644 docs/.vitepress/html-example-markup.js create mode 100644 docs/.vitepress/theme/Catalog.vue create mode 100644 docs/.vitepress/theme/ColorGrid.vue create mode 100644 docs/.vitepress/theme/ExamplesIndex.vue create mode 100644 docs/.vitepress/theme/HtmlExample.vue create mode 100644 docs/.vitepress/theme/IconGrid.vue create mode 100644 docs/.vitepress/theme/Layout.vue create mode 100644 docs/.vitepress/theme/LayoutScales.vue create mode 100644 docs/.vitepress/theme/Logo.vue create mode 100644 docs/.vitepress/theme/catalog/Bleeds.vue create mode 100644 docs/.vitepress/theme/catalog/Buttons.vue create mode 100644 docs/.vitepress/theme/catalog/Checkboxes.vue create mode 100644 docs/.vitepress/theme/catalog/Flexbox.vue create mode 100644 docs/.vitepress/theme/catalog/Grids.vue create mode 100644 docs/.vitepress/theme/catalog/Inputs.vue create mode 100644 docs/.vitepress/theme/catalog/Links.vue create mode 100644 docs/.vitepress/theme/catalog/Lists.vue create mode 100644 docs/.vitepress/theme/catalog/Pills.vue create mode 100644 docs/.vitepress/theme/catalog/Radios.vue create mode 100644 docs/.vitepress/theme/catalog/Ranges.vue create mode 100644 docs/.vitepress/theme/catalog/Selects.vue create mode 100644 docs/.vitepress/theme/catalog/Switches.vue create mode 100644 docs/.vitepress/theme/catalog/Tables.vue create mode 100644 docs/.vitepress/theme/catalog/Textareas.vue create mode 100644 docs/.vitepress/theme/catalog/Toggles.vue create mode 100644 docs/.vitepress/theme/catalog/Triangles.vue create mode 100644 docs/.vitepress/theme/catalog/Typography.vue create mode 100644 docs/.vitepress/theme/data.js create mode 100644 docs/.vitepress/theme/docs.css create mode 100644 docs/.vitepress/theme/index.js create mode 100644 docs/.vitepress/theme/site-nav.js create mode 100644 docs/catalog.md create mode 100644 docs/documentation/animations.md create mode 100644 docs/documentation/buttons.md create mode 100644 docs/documentation/colors.md create mode 100644 docs/documentation/forms.md create mode 100644 docs/documentation/icons.md create mode 100644 docs/documentation/index.md create mode 100644 docs/documentation/layout.md create mode 100644 docs/documentation/links.md create mode 100644 docs/documentation/miscellaneous.md create mode 100644 docs/documentation/tables.md create mode 100644 docs/documentation/theming.md create mode 100644 docs/documentation/triangles.md create mode 100644 docs/documentation/typography.md create mode 100644 docs/examples/badges.md create mode 100644 docs/examples/equal-height-columns.md create mode 100644 docs/examples/index.md create mode 100644 docs/examples/inputs.md rename site/pages/examples/legends.js => docs/examples/legends.md (67%) rename site/pages/examples/modal.js => docs/examples/modal.md (55%) rename site/pages/examples/navigation.js => docs/examples/navigation.md (60%) create mode 100644 docs/examples/progress-bars.md rename site/pages/examples/sidebar-apps.js => docs/examples/sidebar-apps.md (69%) create mode 100644 docs/examples/spinner.md create mode 100644 docs/examples/tooltips.md create mode 100644 docs/icons.md create mode 100644 docs/index.md create mode 100644 docs/layout-scales.md rename {site => docs/public}/img/baseline-grid.svg (100%) rename {site => docs/public}/img/box-model.svg (100%) rename {site => docs/public}/img/custom-icons.svg (100%) rename {site => docs/public}/img/defaults.svg (100%) rename {site => docs/public}/img/focus.svg (100%) rename {site => docs/public}/img/is-active.svg (100%) rename {site => docs/public}/img/media-queries.svg (100%) rename {site => docs/public}/img/modifier.svg (100%) rename {site => docs/public}/img/spacedog800.jpg (100%) rename {site => docs/public}/img/specificity.svg (100%) create mode 100644 examples/jit/assembly.css create mode 100644 examples/jit/build.mjs create mode 100644 examples/jit/index.html delete mode 100644 nodemon.json delete mode 100644 scripts/build-color-variants.js delete mode 100755 scripts/build-css.js delete mode 100644 scripts/build-icon-json.js delete mode 100644 scripts/build-layout-scales.js delete mode 100644 scripts/build-media-variants.js delete mode 100644 scripts/build-navigation-json.js delete mode 100644 scripts/check-size.js delete mode 100644 scripts/clean-svgs.js delete mode 100644 scripts/deploy.js delete mode 100644 scripts/order-sections.js delete mode 100644 scripts/watch-assembly-assets.js delete mode 100644 site/.eslintrc.json delete mode 100644 site/application_wrapper.js delete mode 100644 site/catalog/bleeds.js delete mode 100644 site/catalog/buttons.js delete mode 100644 site/catalog/checkboxes.js delete mode 100644 site/catalog/flexbox.js delete mode 100644 site/catalog/grids.js delete mode 100644 site/catalog/inputs.js delete mode 100644 site/catalog/links.js delete mode 100644 site/catalog/lists.js delete mode 100644 site/catalog/pills.js delete mode 100644 site/catalog/radios.js delete mode 100644 site/catalog/ranges.js delete mode 100644 site/catalog/selects.js delete mode 100644 site/catalog/switches.js delete mode 100644 site/catalog/tables.js delete mode 100644 site/catalog/textareas.js delete mode 100644 site/catalog/toggles.js delete mode 100644 site/catalog/triangles.js delete mode 100644 site/catalog/typography.js delete mode 100644 site/css/hljs.css delete mode 100644 site/entry.js delete mode 100644 site/heading.js delete mode 100644 site/html_example.js delete mode 100644 site/html_template.js delete mode 100644 site/js/copy.js delete mode 100644 site/logo.js delete mode 100644 site/navigation.js delete mode 100644 site/page.js delete mode 100644 site/pages/catalog.js delete mode 100644 site/pages/documentation.js delete mode 100644 site/pages/examples/badges.js delete mode 100644 site/pages/examples/equal-height-columns.js delete mode 100644 site/pages/examples/index.js delete mode 100644 site/pages/examples/inputs.js delete mode 100644 site/pages/examples/progress-bars.js delete mode 100644 site/pages/examples/spinner.js delete mode 100644 site/pages/examples/tooltips.js delete mode 100644 site/pages/favicon.ico delete mode 100644 site/pages/icons.js delete mode 100644 site/pages/index.js delete mode 100644 site/pages/layout-scales.js delete mode 100644 src/animations.css create mode 100755 src/build-css.js rename {scripts => src}/build-js.js (97%) rename {scripts => src}/build-svg-loader.js (98%) rename {scripts => src}/build-user-assets.js (100%) delete mode 100644 src/buttons.css create mode 100644 src/check-size.js create mode 100644 src/clean-svgs.js delete mode 100644 src/color-variants.css delete mode 100644 src/colors.css create mode 100644 src/deploy.js delete mode 100644 src/focus.css delete mode 100644 src/fonts.css delete mode 100644 src/forms.css create mode 100644 src/generate-uno.mjs delete mode 100644 src/icons.css delete mode 100644 src/layout-scales.css delete mode 100644 src/layout.css delete mode 100644 src/links.css delete mode 100644 src/md4-shim.js delete mode 100644 src/miscellaneous.css create mode 100644 src/preset.js create mode 100644 src/preset/base.js create mode 100644 src/preset/color-utils.js create mode 100644 src/preset/colors.js create mode 100644 src/preset/emit.js create mode 100644 src/preset/escape.js create mode 100644 src/preset/layout-scales.js create mode 100644 src/preset/media-classes.js create mode 100644 src/preset/utilities.js create mode 100644 src/preset/variants.js delete mode 100644 src/reset.css delete mode 100644 src/tables.css delete mode 100644 src/theming.css rename {scripts => src}/timelog.js (100%) delete mode 100644 src/triangles.css delete mode 100644 src/typography.css delete mode 100644 test/__snapshots__/build-color-variants.jest.js.snap delete mode 100644 test/__snapshots__/build-layout-scales.jest.js.snap delete mode 100644 test/__snapshots__/build-media-variants.jest.js.snap delete mode 100644 test/build-color-variants.jest.js delete mode 100644 test/build-layout-scales.jest.js delete mode 100644 test/build-media-variants.jest.js create mode 100644 test/examples-jit.jest.js create mode 100644 test/generate-jit.mjs create mode 100644 test/preset.jest.js diff --git a/.eslintrc.json b/.eslintrc.json index a173f42d..5f67ffa1 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -2,5 +2,37 @@ "extends": [ "@mapbox/eslint-config-mapbox", "prettier" + ], + "ignorePatterns": [ + "docs/.vitepress/**", + "_site" + ], + "overrides": [ + { + "files": ["*.mjs"], + "parserOptions": { + "ecmaVersion": 2022, + "sourceType": "module" + }, + "rules": { + "node/no-unsupported-features/es-syntax": "off" + } + }, + { + "files": [ + "src/deploy.js", + "src/clean-svgs.js", + "src/check-size.js" + ], + "env": { + "node": true + }, + "parserOptions": { + "sourceType": "script" + }, + "rules": { + "strict": "off" + } + } ] } diff --git a/.gitignore b/.gitignore index 0b9a3081..28176e6d 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,6 @@ dist _tmp_assembly _batfish* _site +docs/.vitepress/cache +docs/.vitepress/dist .DS_Store \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a7e0ea0..05669222 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 2.0.0 + +- [breaking] Rebuild Assembly's CSS pipeline on [UnoCSS](https://unocss.dev/). Class names and `buildUserAssets` stay compatible; the generated stylesheet's formatting, comments, and source maps may differ. Node.js 18+ is required. +- [add] Export `presetAssembly()` for on-demand UnoCSS builds that keep Assembly class names. Pass `{ safelist: true }` only when you want the full prebuilt utility set. +- [add] `gap{size}`, `gapx{size}`, and `gapy{size}` on the padding scale, with `*-mm` / `*-ml` / `*-mxl` variants. Use with `flex` or `gridbox`; do not combine with `grid--gut*` or percentage `w-*` columns on `grid`. +- [add] CSS Grid via `gridbox` / `inline-gridbox`, `gridbox--cols{n}` / `gridbox--rows{n}` (1–12), child spans, auto-flow, and alignment. The existing `grid` / `col` 12-column flex system is unchanged. +- [add] `examples/jit` — a sample app that generates only the utilities used in its markup (no reset or component preflight). +- [add] `aspect-{ratio}` / `aspect-auto`, `object-{contain,cover,fill,none,scale-down}`, `flex--space-around-main` / `flex--space-evenly-main`, `gridbox--space-around` / `gridbox--space-evenly`, and transform utilities (`rotate{deg}`, `scale{percent}`, `translate-x{n}` / `translate-y{n}`). +- [internal] Assembly utilities are UnoCSS rules in `src/preset/`. Reset and component CSS live in `src/preset/base.js`. The package build is `src/build-*.js`. The documentation site is VitePress under `docs/`. + ## 1.16.0 - [add] `ai` icon diff --git a/MIGRATION_GUIDES.md b/MIGRATION_GUIDES.md index 2bf11555..0e15dc6d 100644 --- a/MIGRATION_GUIDES.md +++ b/MIGRATION_GUIDES.md @@ -1,5 +1,36 @@ # Migration Guides +## 2.0.0 + +Version 2.0.0 rebuilds Assembly with [UnoCSS](https://unocss.dev/) while keeping the existing class names and `buildUserAssets` API. + +You do not need to change class names in markup. Continue to use `assembly.css` / `assembly.js`, or keep calling `Assembly.buildUserAssets`. + +What can change: + +- The contents of `assembly.css` are generated by UnoCSS, so whitespace, comments, rule order, and source maps may differ from 1.x. Selectors and declarations for public classes stay the same. +- Layout-scale media variants (`px12-mm`, `w-1/2-ml`, and so on) now use the same custom media queries you pass to `buildUserAssets`, instead of the hardcoded default breakpoints. +- `@mapbox/assembly` now depends on `@unocss/core` (used when creating custom builds) and requires Node.js 18+. + +New: you can use Assembly as an UnoCSS preset for on-demand CSS: + +```js +import { defineConfig } from 'unocss'; +import { presetAssembly } from '@mapbox/assembly'; + +export default defineConfig({ + presets: [presetAssembly()] +}); +``` + +`presetAssembly()` tree-shakes utilities from your source. The prebuilt `assembly.css` uses `presetAssembly({ safelist: true })`. Reset, forms, buttons, and other component CSS are preflight and always included. + +New layout utilities, additive with 1.x class names: + +- `gap12` / `gapx12` / `gapy12` (padding scale) for flex and CSS Grid spacing. +- `gridbox` for CSS Grid. Keep `grid` / `col` / `grid--gut*` for the 12-column flex system. +- `aspect-16/9`, `object-cover`, `flex--space-evenly-main`, `rotate90`, `scale50`, `translate-x12`. + ## 1.0.0+ Version 1.0.0 of Assembly introduces breaking changes – learn how to resolve them with this handy guide. diff --git a/README.md b/README.md index 1849ad43..468123ef 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,23 @@ Assembly exposes a JS module for creating custom builds. Why might you want to c - You want to append extra stylesheets that also use Assembly's variables and media queries. - You want to reduce file-size by picking and choosing the color variants you need. +### presetAssembly([options]) + +Returns an [UnoCSS preset](https://unocss.dev/guide/presets) that generates Assembly class names on demand. Utilities, media variants, and color modifiers are tree-shaken from your source. Reset, form, and other component CSS is included as preflight. + +```js +import { defineConfig } from 'unocss'; +import { presetAssembly } from '@mapbox/assembly'; + +export default defineConfig({ + presets: [presetAssembly()] +}); +``` + +The prebuilt `assembly.css` is generated with `presetAssembly({ safelist: true })` so every class is present. Do not pass `safelist: true` in an app that wants on-demand CSS. + +`options.variables`, `options.colorVariants`, and `options.files` match the `buildUserAssets` options of the same names. + ### buildUserAssets(outdir[, options]) Returns a Promise that resolves when all assets have been written to `outdir`. @@ -125,30 +142,27 @@ Assembly strives for flat, single rule declarations and avoids overrides wheneve ### Media query class variants -Media query class variants (e.g. `block-mm` as a variant of `block`) are automatically generated and added to the CSS build with `scripts/build-media-variants.js`. If you want to generate media variants for a new class, or change which classes get media variants, you'll need to modify the lists in that file. +Media query class variants (e.g. `block-mm` as a variant of `block`) are generated by the Assembly UnoCSS preset (`src/preset/variants.js`). The prebuilt stylesheet includes `-mm`, `-ml`, and `-mxl` variants for the classes listed in `src/preset/media-classes.js` plus every layout-scale utility. If you use `presetAssembly()` on demand, those suffixes work for any matching utility. ## Development ### Tools +- [UnoCSS](https://unocss.dev/) generates Assembly utilities from `presetAssembly()` (`src/preset/utilities.js`, layout scales, color rules, media-query variants, and `src/preset/base.js` for reset/forms). - [PostCSS](http://postcss.org/) for processing CSS. PostCSS parses CSS and runs it through plugins, and these are the plugins we're using: - [Autoprefixer](https://autoprefixer.github.io/) automatically adds vendor prefixes. - [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties) allows us to use variables for values, with the [CSS custom properties syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). - [postcss-custom-media](https://github.com/postcss/postcss-custom-media) allows us to use variables for media queries, with the [CSS custom media queries syntax](https://www.w3.org/TR/2016/WD-mediaqueries-4-20160126/#custom-mq). - - [concat-with-sourcemaps](https://github.com/floridoo/concat-with-sourcemaps) allows us to split our CSS into multiple stylesheets. -- [stylelint](http://stylelint.io/) lints our CSS. -- SVGs +- [PostCSS](http://postcss.org/) for processing CSS. PostCSS parses CSS and runs it through plugins, and these are the plugins we're using: - [svgstore](https://github.com/svgstore/svgstore) compiles our SVGs into a SVG "sprite" of sorts, allowing us to use [the latest and greatest SVG-based icon system](https://css-tricks.com/svg-sprites-use-better-icon-fonts/). -- Documentation - - [documentation-css](https://github.com/documentationjs/documentation-css) parses annotation comments in the CSS, outputting objects that can be used to build documentation. -- [Batfish](https://github.com/mapbox/batfish) powers the website. +- [VitePress](https://vitepress.dev/) powers the website. ### Install and start ```bash npm ci # Installs your `node_modules` -npm start # Builds everything, starts a dev server, rebuilds & reloads on changes +npm run dev # Builds CSS/JS, starts the VitePress docs server npm run build:js # Build SVGs and other JS ``` diff --git a/babel.config.json b/babel.config.json index 0960c012..1320b9a3 100644 --- a/babel.config.json +++ b/babel.config.json @@ -1,6 +1,3 @@ { - "presets": [ - "@babel/preset-env", - "@babel/preset-react" - ] -} \ No newline at end of file + "presets": ["@babel/preset-env"] +} diff --git a/batfish.config.js b/batfish.config.js deleted file mode 100644 index 33b0ae9b..00000000 --- a/batfish.config.js +++ /dev/null @@ -1,40 +0,0 @@ -'use strict'; - -require('./src/md4-shim'); - -const path = require('path'); -// eslint-disable-next-line -const navigationStructure = require('./_tmp_assembly/navigation.json'); - -module.exports = () => { - return { - siteBasePath: '/assembly/', - siteOrigin: 'https://labs.mapbox.com', - outputDirectory: path.join(__dirname, '_site'), - stylesheets: [ - path.join(__dirname, './site/css/hljs.css'), - path.join(__dirname, './dist/assembly.css') - ], - dataSelectors: { - examplesSubNavigationList: () => { - return navigationStructure.navigationList.find( - routeConfig => routeConfig.name === 'Examples' - ).items; - }, - documentationData: () => { - return navigationStructure.navigationList.find( - routeConfig => routeConfig.name === 'Documentation' - ).props.documentationData; - } - }, - fileLoaderExtensions: extensions => extensions.concat(['svg']), - pagesDirectory: path.join(__dirname, './site/pages'), - webpackStaticIgnore: [/copy\.js$/], - vendorModules: ['highlight.js'], - applicationWrapperPath: path.join( - __dirname, - './site/application_wrapper.js' - ), - staticHtmlInlineDeferCss: false - }; -}; diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs new file mode 100644 index 00000000..2d4d8da8 --- /dev/null +++ b/docs/.vitepress/config.mjs @@ -0,0 +1,94 @@ +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; +import { defineConfig } from 'vitepress'; + +import { documentationLayout } from './documentation-layout.js'; +import { htmlExampleMarkup } from './html-example-markup.js'; +import hljsGithub from './hljs-github-theme.js'; + +const configDir = path.dirname(fileURLToPath(import.meta.url)); +const distJs = path.resolve(configDir, '../../dist/assembly.js'); + +function assemblyJsPlugin() { + return { + name: 'assembly-js', + configureServer(server) { + server.middlewares.use((req, res, next) => { + const url = (req.url || '').split('?')[0]; + if (url !== '/assembly.js' && url !== '/assembly/assembly.js') { + next(); + return; + } + if (!fs.existsSync(distJs)) { + next(); + return; + } + res.setHeader('Content-Type', 'application/javascript'); + fs.createReadStream(distJs).pipe(res); + }); + }, + closeBundle() { + const outDir = path.resolve(configDir, '../../_site'); + if (fs.existsSync(distJs) && fs.existsSync(outDir)) { + fs.copyFileSync(distJs, path.join(outDir, 'assembly.js')); + } + } + }; +} + +function colorUtilsEsm() { + return { + name: 'color-utils-esm', + transform(code, id) { + const file = id.split('?')[0].replace(/\\/g, '/'); + if (!file.endsWith('/src/preset/color-utils.js')) return null; + return code.replace( + /module\.exports = \{([^}]+)\};?\s*$/, + 'export {$1};' + ); + } + }; +} + +function exampleFence(md) { + const defaultFence = md.renderer.rules.fence; + md.renderer.rules.fence = (tokens, idx, options, env, slf) => { + const token = tokens[idx]; + if (token.info.trim() === 'example') { + return `${htmlExampleMarkup(options.highlight, token.content)}\n`; + } + return `
${defaultFence(tokens, idx, options, env, slf)}
\n`; + }; +} + +export default defineConfig({ + title: 'Assembly.css', + description: + 'A CSS framework that makes the hard parts of building anything on the web easy.', + base: '/assembly/', + outDir: '../_site', + cleanUrls: true, + appearance: false, + vite: { + plugins: [assemblyJsPlugin(), colorUtilsEsm()], + server: { + fs: { + allow: ['..'] + } + } + }, + markdown: { + theme: { + light: hljsGithub, + dark: hljsGithub + }, + anchor: { + permalink: false + }, + config(md) { + exampleFence(md); + documentationLayout(md); + } + } +}); diff --git a/docs/.vitepress/documentation-layout.js b/docs/.vitepress/documentation-layout.js new file mode 100644 index 00000000..3691ebfc --- /dev/null +++ b/docs/.vitepress/documentation-layout.js @@ -0,0 +1,235 @@ +import { htmlExampleMarkup } from './html-example-markup.js'; + +function isDocPage(env) { + const file = env?.relativePath || ''; + return file.startsWith('documentation/') && file !== 'documentation/index.md'; +} + +function headingCloseIndex(tokens, openIndex) { + return tokens.findIndex( + (token, index) => index > openIndex && token.type === 'heading_close' + ); +} + +function nextHeadingOpen(tokens, fromIndex) { + return tokens.findIndex( + (token, index) => index >= fromIndex && token.type === 'heading_open' + ); +} + +function headingText(tokens, openIndex) { + const inline = tokens[openIndex + 1]; + return inline && inline.type === 'inline' ? inline.content : ''; +} + +function htmlToken(state, content) { + const token = new state.Token('html_block', '', 0); + token.content = content; + return token; +} + +function tokenText(token) { + if (token.content) return token.content; + if (!token.children) return ''; + return token.children.map(child => child.content || '').join(''); +} + +function isTxtMonoToken(token) { + return /class=["']txt-mono["']/.test(tokenText(token)); +} + +function dropTxtMono(tokens) { + return tokens.filter((token, index) => { + if (isTxtMonoToken(token)) return false; + if ( + token.type === 'paragraph_open' && + tokens[index + 1] && + isTxtMonoToken(tokens[index + 1]) + ) { + return false; + } + if ( + token.type === 'paragraph_close' && + tokens[index - 1] && + isTxtMonoToken(tokens[index - 1]) + ) { + return false; + } + return true; + }); +} + +function hasVisibleText(tokens) { + return tokens.some(token => { + if (token.type === 'fence') return false; + return tokenText(token).trim().length > 0; + }); +} + +function selectorsFromMono(tokens) { + return tokens.flatMap(token => { + if (!isTxtMonoToken(token)) return []; + return [...tokenText(token).matchAll(/`([^`]+)`/g)].map(match => + match[1].trim() + ); + }); +} + +function classesFromExample(content) { + return [...content.matchAll(/class=['"]([^'"]+)['"]/g)].flatMap(match => + match[1].split(/\s+/).filter(Boolean) + ); +} + +function isDemoChrome(name) { + return /^(border(?:--[\w-]+)?|inline-block|block|relative|absolute|top|right|bottom|left|mt\d+|mb\d+|mr\d+|ml\d+|h\d+|w\d+)$/.test( + name + ); +} + +function unique(values) { + return values.filter((value, index) => values.indexOf(value) === index); +} + +function selectorsFromExample(content, file) { + const classes = unique(classesFromExample(content)); + const kept = file.includes('typography.md') + ? classes.filter(name => + /^(txt-|align-|pre$|pre--|prose|unprose)/.test(name) + ) + : classes.filter(name => !isDemoChrome(name)); + return (kept.length > 0 ? kept : classes).map(name => `.${name}`); +} + +function exampleContent(tokens) { + const fence = tokens.find( + token => token.type === 'fence' && token.info.trim() === 'example' + ); + return fence ? fence.content : ''; +} + +function entrySelectors(inner, file) { + const fromMono = unique(selectorsFromMono(inner)); + if (fromMono.length > 0) return fromMono; + const example = exampleContent(inner); + if (!example) return []; + return selectorsFromExample(example, file); +} + +function escapeAttr(value) { + return value + .replace(/&/g, '&') + .replace(/"/g, '"') + .replace(/ 1 + ? 'mr3 py3 color-blue-deep round bg-blue-faint mb3 inline-block txt-s px3' + : 'mr3 py3 color-blue-deep round bg-blue-faint mb3 inline-block px6'; + return selectors + .map(selector => { + const id = selector.trim().replace(/\s+/g, '-').replace(/\./g, ''); + const label = escapeAttr(selector.replace(/\\/g, '')); + return `${label}`; + }) + .join(''); +} + +function wrapH3Entry(state, openIndex, md) { + const tokens = state.tokens; + const closeIndex = headingCloseIndex(tokens, openIndex); + const title = headingText(tokens, openIndex); + const nextOpen = nextHeadingOpen(tokens, closeIndex + 1); + const end = nextOpen === -1 ? tokens.length : nextOpen; + const inner = tokens.slice(closeIndex + 1, end); + const selectors = entrySelectors(inner, state.env?.relativePath || ''); + const fenceAt = inner.findIndex( + token => token.type === 'fence' && token.info.trim() === 'example' + ); + const desc = dropTxtMono(fenceAt === -1 ? inner : inner.slice(0, fenceAt)); + const rest = fenceAt === -1 ? [] : inner.slice(fenceAt); + const description = hasVisibleText(desc) + ? desc + : [htmlToken(state, `

${escapeAttr(title)}

\n`)]; + const descHtml = md.renderer.render(description, md.options, state.env); + const exampleHtml = rest + .filter(token => token.type === 'fence' && token.info.trim() === 'example') + .map( + token => + htmlExampleMarkup(md.options.highlight, token.content) + ) + .join('\n'); + tokens.splice( + openIndex, + end - openIndex, + htmlToken( + state, + `
+
+
+
${pillsHtml(selectors)}
+
+
+
${descHtml}
+${exampleHtml} +
+
+
\n` + ) + ); +} + +function wrapIntro(state, openIndex) { + const tokens = state.tokens; + const closeIndex = headingCloseIndex(tokens, openIndex); + const nextOpen = nextHeadingOpen(tokens, closeIndex + 1); + const end = nextOpen === -1 ? tokens.length : nextOpen; + const inner = tokens.slice(closeIndex + 1, end); + if (!hasVisibleText(inner)) return; + tokens.splice( + closeIndex + 1, + end - (closeIndex + 1), + htmlToken(state, '
\n'), + ...inner, + htmlToken(state, '
\n') + ); +} + +function wrapAllH3(state, md) { + const start = state.tokens.findIndex( + token => token.type === 'heading_open' && token.tag === 'h3' + ); + if (start === -1) return; + wrapH3Entry(state, start, md); + wrapAllH3(state, md); +} + +function headingOpens(tokens, tag) { + return tokens + .map((token, index) => + token.type === 'heading_open' && token.tag === tag ? index : -1 + ) + .filter(index => index >= 0); +} + +function styleHeadings(tokens) { + tokens.forEach(token => { + if (token.type !== 'heading_open') return; + if (token.tag === 'h1') token.attrJoin('class', 'txt-h2 txt-bold mb18 pt24'); + if (token.tag === 'h2') token.attrJoin('class', 'txt-l txt-bold pt12 mt12'); + }); +} + +export function documentationLayout(md) { + md.core.ruler.push('documentation_layout', state => { + if (!isDocPage(state.env)) return; + styleHeadings(state.tokens); + headingOpens(state.tokens, 'h2') + .reverse() + .forEach(index => wrapIntro(state, index)); + headingOpens(state.tokens, 'h1').forEach(index => wrapIntro(state, index)); + wrapAllH3(state, md); + }); +} diff --git a/docs/.vitepress/hljs-github-theme.js b/docs/.vitepress/hljs-github-theme.js new file mode 100644 index 00000000..6a5a733c --- /dev/null +++ b/docs/.vitepress/hljs-github-theme.js @@ -0,0 +1,110 @@ +/** highlight.js GitHub theme, as a Shiki theme for VitePress. */ +export default { + name: 'hljs-github', + type: 'light', + colors: { + 'editor.background': '#ffffff', + 'editor.foreground': '#333333' + }, + settings: [ + { + scope: ['comment', 'punctuation.definition.comment', 'string.comment'], + settings: { foreground: '#999988', fontStyle: 'italic' } + }, + { + scope: [ + 'keyword', + 'storage', + 'storage.type', + 'storage.modifier' + ], + settings: { foreground: '#333333', fontStyle: 'bold' } + }, + { + scope: [ + 'constant.numeric', + 'constant.language', + 'variable', + 'variable.other' + ], + settings: { foreground: '#008080' } + }, + { + scope: [ + 'string', + 'string.quoted', + 'punctuation.definition.string', + 'string punctuation.section.embedded source' + ], + settings: { foreground: '#DD1144' } + }, + { + scope: ['entity.name.tag', 'punctuation.definition.tag'], + settings: { foreground: '#000080' } + }, + { + scope: ['entity', 'entity.name'], + settings: { foreground: '#000080' } + }, + { + scope: ['entity.other.attribute-name'], + settings: { foreground: '#008080' } + }, + { + scope: ['support', 'support.constant', 'support.variable'], + settings: { foreground: '#0086B3' } + }, + { + scope: ['constant', 'entity.name.constant'], + settings: { foreground: '#008080' } + } + ], + tokenColors: [ + { + scope: ['comment', 'punctuation.definition.comment', 'string.comment'], + settings: { foreground: '#999988', fontStyle: 'italic' } + }, + { + scope: ['keyword', 'storage', 'storage.type', 'storage.modifier'], + settings: { foreground: '#333333', fontStyle: 'bold' } + }, + { + scope: [ + 'constant.numeric', + 'constant.language', + 'variable', + 'variable.other' + ], + settings: { foreground: '#008080' } + }, + { + scope: [ + 'string', + 'string.quoted', + 'punctuation.definition.string', + 'string punctuation.section.embedded source' + ], + settings: { foreground: '#DD1144' } + }, + { + scope: ['entity.name.tag', 'punctuation.definition.tag'], + settings: { foreground: '#000080' } + }, + { + scope: ['entity', 'entity.name'], + settings: { foreground: '#000080' } + }, + { + scope: ['entity.other.attribute-name'], + settings: { foreground: '#008080' } + }, + { + scope: ['support', 'support.constant', 'support.variable'], + settings: { foreground: '#0086B3' } + }, + { + scope: ['constant', 'entity.name.constant'], + settings: { foreground: '#008080' } + } + ] +}; diff --git a/docs/.vitepress/html-example-markup.js b/docs/.vitepress/html-example-markup.js new file mode 100644 index 00000000..add60b1e --- /dev/null +++ b/docs/.vitepress/html-example-markup.js @@ -0,0 +1,9 @@ +export function htmlExampleMarkup(highlight, content) { + const source = content.replace(/\n$/, ''); + const highlighted = + typeof highlight === 'function' ? highlight(source, 'html', '') : ''; + const highlightedAttr = highlighted + ? ` highlighted="${encodeURIComponent(highlighted)}"` + : ''; + return ``; +} diff --git a/docs/.vitepress/theme/Catalog.vue b/docs/.vitepress/theme/Catalog.vue new file mode 100644 index 00000000..8c7cbaf8 --- /dev/null +++ b/docs/.vitepress/theme/Catalog.vue @@ -0,0 +1,83 @@ + + + diff --git a/docs/.vitepress/theme/ColorGrid.vue b/docs/.vitepress/theme/ColorGrid.vue new file mode 100644 index 00000000..9875d392 --- /dev/null +++ b/docs/.vitepress/theme/ColorGrid.vue @@ -0,0 +1,23 @@ + + + diff --git a/docs/.vitepress/theme/ExamplesIndex.vue b/docs/.vitepress/theme/ExamplesIndex.vue new file mode 100644 index 00000000..359e7aaf --- /dev/null +++ b/docs/.vitepress/theme/ExamplesIndex.vue @@ -0,0 +1,21 @@ + + + diff --git a/docs/.vitepress/theme/HtmlExample.vue b/docs/.vitepress/theme/HtmlExample.vue new file mode 100644 index 00000000..29b49616 --- /dev/null +++ b/docs/.vitepress/theme/HtmlExample.vue @@ -0,0 +1,69 @@ + + + diff --git a/docs/.vitepress/theme/IconGrid.vue b/docs/.vitepress/theme/IconGrid.vue new file mode 100644 index 00000000..c6c0a64a --- /dev/null +++ b/docs/.vitepress/theme/IconGrid.vue @@ -0,0 +1,20 @@ + + + diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue new file mode 100644 index 00000000..6fd08aaf --- /dev/null +++ b/docs/.vitepress/theme/Layout.vue @@ -0,0 +1,180 @@ + + + diff --git a/docs/.vitepress/theme/LayoutScales.vue b/docs/.vitepress/theme/LayoutScales.vue new file mode 100644 index 00000000..bcbbd346 --- /dev/null +++ b/docs/.vitepress/theme/LayoutScales.vue @@ -0,0 +1,122 @@ + + + diff --git a/docs/.vitepress/theme/Logo.vue b/docs/.vitepress/theme/Logo.vue new file mode 100644 index 00000000..01e180db --- /dev/null +++ b/docs/.vitepress/theme/Logo.vue @@ -0,0 +1,9 @@ + diff --git a/docs/.vitepress/theme/catalog/Bleeds.vue b/docs/.vitepress/theme/catalog/Bleeds.vue new file mode 100644 index 00000000..ce1203f5 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Bleeds.vue @@ -0,0 +1,27 @@ + diff --git a/docs/.vitepress/theme/catalog/Buttons.vue b/docs/.vitepress/theme/catalog/Buttons.vue new file mode 100644 index 00000000..b33db582 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Buttons.vue @@ -0,0 +1,76 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Checkboxes.vue b/docs/.vitepress/theme/catalog/Checkboxes.vue new file mode 100644 index 00000000..4fe96093 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Checkboxes.vue @@ -0,0 +1,37 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Flexbox.vue b/docs/.vitepress/theme/catalog/Flexbox.vue new file mode 100644 index 00000000..ee14593b --- /dev/null +++ b/docs/.vitepress/theme/catalog/Flexbox.vue @@ -0,0 +1,111 @@ + diff --git a/docs/.vitepress/theme/catalog/Grids.vue b/docs/.vitepress/theme/catalog/Grids.vue new file mode 100644 index 00000000..fcc2ac7f --- /dev/null +++ b/docs/.vitepress/theme/catalog/Grids.vue @@ -0,0 +1,93 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Inputs.vue b/docs/.vitepress/theme/catalog/Inputs.vue new file mode 100644 index 00000000..3f7f65f5 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Inputs.vue @@ -0,0 +1,65 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Links.vue b/docs/.vitepress/theme/catalog/Links.vue new file mode 100644 index 00000000..59a54dc1 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Links.vue @@ -0,0 +1,47 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Lists.vue b/docs/.vitepress/theme/catalog/Lists.vue new file mode 100644 index 00000000..7c973e4e --- /dev/null +++ b/docs/.vitepress/theme/catalog/Lists.vue @@ -0,0 +1,157 @@ + diff --git a/docs/.vitepress/theme/catalog/Pills.vue b/docs/.vitepress/theme/catalog/Pills.vue new file mode 100644 index 00000000..c3c7107a --- /dev/null +++ b/docs/.vitepress/theme/catalog/Pills.vue @@ -0,0 +1,47 @@ + diff --git a/docs/.vitepress/theme/catalog/Radios.vue b/docs/.vitepress/theme/catalog/Radios.vue new file mode 100644 index 00000000..ef108f34 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Radios.vue @@ -0,0 +1,29 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Ranges.vue b/docs/.vitepress/theme/catalog/Ranges.vue new file mode 100644 index 00000000..00b780c8 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Ranges.vue @@ -0,0 +1,55 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Selects.vue b/docs/.vitepress/theme/catalog/Selects.vue new file mode 100644 index 00000000..0164685e --- /dev/null +++ b/docs/.vitepress/theme/catalog/Selects.vue @@ -0,0 +1,79 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Switches.vue b/docs/.vitepress/theme/catalog/Switches.vue new file mode 100644 index 00000000..4a29d01d --- /dev/null +++ b/docs/.vitepress/theme/catalog/Switches.vue @@ -0,0 +1,41 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Tables.vue b/docs/.vitepress/theme/catalog/Tables.vue new file mode 100644 index 00000000..dd5e3ff8 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Tables.vue @@ -0,0 +1,190 @@ + diff --git a/docs/.vitepress/theme/catalog/Textareas.vue b/docs/.vitepress/theme/catalog/Textareas.vue new file mode 100644 index 00000000..5386f3ef --- /dev/null +++ b/docs/.vitepress/theme/catalog/Textareas.vue @@ -0,0 +1,36 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Toggles.vue b/docs/.vitepress/theme/catalog/Toggles.vue new file mode 100644 index 00000000..36074fbe --- /dev/null +++ b/docs/.vitepress/theme/catalog/Toggles.vue @@ -0,0 +1,119 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Triangles.vue b/docs/.vitepress/theme/catalog/Triangles.vue new file mode 100644 index 00000000..efb0b3a4 --- /dev/null +++ b/docs/.vitepress/theme/catalog/Triangles.vue @@ -0,0 +1,34 @@ + + + diff --git a/docs/.vitepress/theme/catalog/Typography.vue b/docs/.vitepress/theme/catalog/Typography.vue new file mode 100644 index 00000000..6c6c255e --- /dev/null +++ b/docs/.vitepress/theme/catalog/Typography.vue @@ -0,0 +1,119 @@ + + + diff --git a/docs/.vitepress/theme/data.js b/docs/.vitepress/theme/data.js new file mode 100644 index 00000000..bfec2840 --- /dev/null +++ b/docs/.vitepress/theme/data.js @@ -0,0 +1,43 @@ +import { + ALL_COLORS, + isNotAccessibleExceptBg, + isNotAccessibleForButtons, + isNotAccessibleForForms +} from '../../../src/preset/color-utils.js'; +import scales from '../../../src/scales.json'; + +function colorNames(kind) { + if (kind === 'color') { + return ALL_COLORS.filter(color => !isNotAccessibleExceptBg(color)).concat([ + 'text' + ]); + } + return ALL_COLORS.slice(); +} + +function scaleToken(value) { + if (Array.isArray(value)) { + return String(value[0]).replace(/\\/g, ''); + } + return String(value).replace(/\\/g, ''); +} + +function buttonColors() { + return ALL_COLORS.filter(color => !isNotAccessibleForButtons(color)); +} + +function formColors() { + return ALL_COLORS.filter(color => !isNotAccessibleForForms(color)); +} + +export { + ALL_COLORS, + scales, + colorNames, + scaleToken, + buttonColors, + formColors, + isNotAccessibleForButtons, + isNotAccessibleForForms, + isNotAccessibleExceptBg +}; diff --git a/docs/.vitepress/theme/docs.css b/docs/.vitepress/theme/docs.css new file mode 100644 index 00000000..f7195f62 --- /dev/null +++ b/docs/.vitepress/theme/docs.css @@ -0,0 +1,29 @@ +.header-anchor { + display: none; +} + +div[class^='language-'] > button.copy, +div[class^='language-'] > span.lang { + display: none; +} + +.pre [class^='language-'] { + background: transparent; + padding: 0; + margin: 0; +} + +.pre .shiki, +.pre .shiki code { + background: transparent; + padding: 0; + margin: 0; + overflow: visible; + font-size: inherit; + line-height: inherit; + white-space: inherit; +} + +.shiki span { + color: var(--shiki-light); +} diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js new file mode 100644 index 00000000..8fb3c729 --- /dev/null +++ b/docs/.vitepress/theme/index.js @@ -0,0 +1,11 @@ +import Layout from './Layout.vue'; +import HtmlExample from './HtmlExample.vue'; +import '../../../dist/assembly.css'; +import './docs.css'; + +export default { + Layout, + enhanceApp({ app }) { + app.component('HtmlExample', HtmlExample); + } +}; diff --git a/docs/.vitepress/theme/site-nav.js b/docs/.vitepress/theme/site-nav.js new file mode 100644 index 00000000..f093b6a6 --- /dev/null +++ b/docs/.vitepress/theme/site-nav.js @@ -0,0 +1,144 @@ +const exampleLinks = [ + { name: 'Badges', href: '/examples/badges' }, + { name: 'Inputs', href: '/examples/inputs' }, + { name: 'Legends', href: '/examples/legends' }, + { name: 'Modal', href: '/examples/modal' }, + { name: 'Navigation', href: '/examples/navigation' }, + { name: 'Progress bars', href: '/examples/progress-bars' }, + { name: 'Sidebar apps', href: '/examples/sidebar-apps' }, + { name: 'Equal-height columns', href: '/examples/equal-height-columns' }, + { name: 'Tooltips', href: '/examples/tooltips' }, + { name: 'Spinner', href: '/examples/spinner' } +]; + +const catalogLinks = [ + { name: 'Typography', id: 'Typography' }, + { name: 'Grids', id: 'Grids' }, + { name: 'Flexbox', id: 'Flexbox' }, + { name: 'Bleeds', id: 'Bleeds' }, + { name: 'Tables', id: 'Tables' }, + { name: 'Lists', id: 'Lists' }, + { name: 'Links', id: 'Links' }, + { name: 'Buttons', id: 'Buttons' }, + { name: 'Pills', id: 'Pills' }, + { name: 'Inputs', id: 'Inputs' }, + { name: 'Textareas', id: 'Textareas' }, + { name: 'Selects', id: 'Selects' }, + { name: 'Ranges', id: 'Ranges' }, + { name: 'Toggles', id: 'Toggles' }, + { name: 'Switches', id: 'Switches' }, + { name: 'Checkboxes', id: 'Checkboxes' }, + { name: 'Radios', id: 'Radios' }, + { name: 'Triangles', id: 'Triangles' } +]; + +function headingItems(href, names) { + return names.map(name => ({ + name, + href: `${href}#${name.toLowerCase().replace(/&/g, '').replace(/\s+/g, '-').replace(/-+/g, '-')}` + })); +} + +const nav = [ + { + name: 'Home', + href: '/', + items: [ + { name: 'Getting started', href: '/#getting-started' }, + { name: 'Philosophy', href: '/#philosophy' }, + { name: 'Overview', href: '/#overview' }, + { name: 'Javascript API', href: '/#javascript-api' } + ] + }, + { + name: 'Documentation', + href: '/documentation/', + isDoc: true, + items: [ + { + name: 'Typography', + href: '/documentation/typography', + items: headingItems('/documentation/typography', [ + 'Type basics', + 'Type utils', + 'Prose' + ]) + }, + { + name: 'Layout', + href: '/documentation/layout', + items: headingItems('/documentation/layout', [ + 'Grid', + 'Display', + 'Positioning', + 'Margins', + 'Padding', + 'Gap', + 'Sizing', + 'Flexbox', + 'Gridbox', + 'Aspect ratio', + 'Object fit', + 'Transforms', + 'Layout utils' + ]) + }, + { + name: 'Theming', + href: '/documentation/theming', + items: headingItems('/documentation/theming', [ + 'Borders', + 'Border radius', + 'Shadows', + 'Cursors', + 'Opacity' + ]) + }, + { + name: 'Colors', + href: '/documentation/colors', + items: headingItems('/documentation/colors', [ + 'Text colors', + 'Background colors' + ]) + }, + { name: 'Icons', href: '/documentation/icons' }, + { name: 'Buttons', href: '/documentation/buttons' }, + { name: 'Links', href: '/documentation/links' }, + { + name: 'Forms', + href: '/documentation/forms', + items: headingItems('/documentation/forms', [ + 'Inputs & textareas', + 'Selects', + 'Ranges', + 'Checkboxes', + 'Radio buttons', + 'Switches', + 'Toggle group' + ]) + }, + { name: 'Tables', href: '/documentation/tables' }, + { name: 'Animations', href: '/documentation/animations' }, + { name: 'Triangles', href: '/documentation/triangles' }, + { name: 'Miscellaneous', href: '/documentation/miscellaneous' } + ] + }, + { + name: 'Examples', + href: '/examples/', + items: exampleLinks + }, + { name: 'Icons', href: '/icons' }, + { + name: 'Catalog', + href: '/catalog', + items: catalogLinks.map(section => ({ + name: section.name, + href: `/catalog#${section.id}` + })) + }, + { name: 'Layout Scales', href: '/layout-scales' } +]; + +export { nav, catalogLinks, exampleLinks }; diff --git a/docs/catalog.md b/docs/catalog.md new file mode 100644 index 00000000..716086d8 --- /dev/null +++ b/docs/catalog.md @@ -0,0 +1,9 @@ +--- +title: Catalog +--- + + + + diff --git a/docs/documentation/animations.md b/docs/documentation/animations.md new file mode 100644 index 00000000..33a89912 --- /dev/null +++ b/docs/documentation/animations.md @@ -0,0 +1,39 @@ +# Animations + +Animations and animation modifiers. + +## Transition and reaction animations. By default, these run once for 1.5 seconds + +Transition and reaction animations. By default, these run once for 1.5 seconds. + +```example +
+
+
+
+
+
+``` + +## Animation duration modifiers + +Animation duration modifiers. +Change animation duration with an `animation--speed-{seconds}` modifier. +Add a 1 second delay with `animation--delay`. + +```example +
+
+
+
+
+
+``` + +## Repeat an animation infinitely with a `animation--infinite` modifier + +Repeat an animation infinitely with a `animation--infinite` modifier. + +```example +
+``` diff --git a/docs/documentation/buttons.md b/docs/documentation/buttons.md new file mode 100644 index 00000000..8df97749 --- /dev/null +++ b/docs/documentation/buttons.md @@ -0,0 +1,108 @@ +# Buttons + +Although the `btn` class will apply button styling to any element, you should typically apply it to the ` + + + +
+ +
+``` + +## Modify a button so its text and borders are colored and its background transparent + +Modify a button so its text and borders are colored and its background transparent. +The border color and text color will always match. +To change the text and border color, use a `btn--{color}` modifier (`*-deep` colors are not available). + +```example + + + +
+ +
+``` + +## Make a button small + +Make a button small. + +```example + +``` + +## Apply a darker active state to buttons by adding the `is-active` class + +

`.btn.is-active` `.btn--stroke.is-active`

+ +Apply a darker active state to buttons by adding the `is-active` class. + +```example + + + + +``` + +## When a button has the `disabled` attribute, it will be styled accordingly + +

`.btn:disabled`

+ +When a button has the `disabled` attribute, it will be styled accordingly. + +```example + +``` + +## Create pill button groups + +Create pill button groups. +Pill groups must be wrapped in a `inline-flex` container. +Every button in a pill group must have +- a `btn` class +- any `btn--*` modifiers you want (e.g. `btn--stroke`) +- a `btn--pill` *or* `btn--pill-stroke` modifier. Use the `btn--pill-stroke` modifier if the buttons in the pill group are mostly stroke buttons (though active buttons can be non-stroke, if you like that) +- a `btn--pill-*` modifier specifying its position (e.g. `btn--pill-hc`) + +For *horizontal* pills, use +- `inline-flex` on the container +- `btn btn--pill(-stroke) btn--pill-hc` (center) +- `btn btn--pill(-stroke) btn--pill-hl` (left) +- `btn btn--pill(-stroke) btn--pill-hr` (right) + +For *vertical* pills, use +- `inline-flex flex--column` on the container +- `btn btn--pill(-stroke) btn--pill-vc` (center) +- `btn btn--pill(-stroke) btn--pill-vt` (top) +- `btn btn--pill(-stroke) btn--pill-vb` (bottom) + +Pill buttons can be modified and themed in the same ways as regular buttons. + +```example +
+ + + +
+
+ + + +
+``` diff --git a/docs/documentation/colors.md b/docs/documentation/colors.md new file mode 100644 index 00000000..3dd20590 --- /dev/null +++ b/docs/documentation/colors.md @@ -0,0 +1,37 @@ + + +# Colors + +Background and text colors. Colors include dark, light, and faint variations. +Be sure to maintain a readable color contrast between background and text. +Only use `-faint` text colors on dark backgrounds. + +## Text colors + +Apply a text color with `color-{name}`. + + + +### Hover and active + +```example +
color-red-on-hover
+
color-red-on-active (not active)
+
color-red-on-active (active)
+``` + +## Background colors + +Apply a background color with `bg-{name}`. + + + +### Hover and active + +```example +
bg-darken25-on-hover
+
bg-darken25-on-active (not active)
+
bg-darken25-on-active (active)
+``` diff --git a/docs/documentation/forms.md b/docs/documentation/forms.md new file mode 100644 index 00000000..9c430653 --- /dev/null +++ b/docs/documentation/forms.md @@ -0,0 +1,427 @@ +# Forms + +Styles for HTML5 input and textarea elements. All form elements fit into Assembly's `6px` baseline grid. + +## Inputs & textareas + +The `input` class styles input types `text`, `password`, `email`, +`datetime`, `search`, `tel`, `url`, and `number`. The `textarea` class styles the ` + +``` + +### Make a textarea extra small + +Make a textarea extra small. + +```example + +``` + +### When `input` and `textarea` elements have a `disabled` attribute, they will be styled accordingly + +

`.input:disabled` `.textarea:disabled` `.select--stroke:disabled`

+ +When `input` and `textarea` elements have a `disabled` attribute, they will be styled accordingly. + +```example + + +``` + +### When `input` and `textarea` elements have a `readonly` attribute, they will be styled accordingly + +

`.input[readonly]` `.textarea[readonly]`

+ +When `input` and `textarea` elements have a `readonly` attribute, they will be styled accordingly. + +```example + + +``` + +## Selects + +The select component styles the `` element with the `select` class. +- A `
` with the `select-arrow` class. + +### Style a select component + +Style a select component. +Set the text and arrow color by adding a `select--{color}` modifier to the `select` element (`*-dark` colors are not available). + +```example +
+ +
+
+
+ +
+
+``` + +### Make a select component small + +

`.select--s + .select-arrow`

+ +Make a select component small. + +```example +
+ +
+
+``` + +### Modify a select component so that it has a border + +

`.select--stroke .select--s`

+ +Modify a select component so that it has a border. +Set the border and arrow color by adding a `select--{color}` modifier to the `select` element along with the `select--stroke` modifier (`*-dark` colors are not available). +Note that the `select--stroke` modifier changes how the color modifier is interpreted. + +```example +
+ +
+
+
+ +
+
+``` + +### When the `select` element has the `disabled` attribute, the component will be styled accordingly + +

`.select:disabled`

+ +When the `select` element has the `disabled` attribute, the component will be styled accordingly. + +```example +
+ +
+
+
+ +
+
+``` + +## Ranges + +The `range` class styles the `` element. The markup must fit the following pattern: +- A wrapping `
` with the `range` class. +- An `` element. + +### Style a range element + +

`.range > input`

+ +Style a range element. + +The best way to vertically align range elements with other items on the same row is to wrap the row in a `flex flex--center-cross` container. +For more details, read about the [flexbox classes](/documentation/layout#flexbox). + +```example +
+ +
+``` + +### Make a range element small + +

`.range--s`

+ +Make a range element small. + +```example +
+ +
+``` + +### When a range element has the `disabled` attribute, it will be styled accordingly + +

`.range:disabled`

+ +```example +
+ +
+``` + +## Checkboxes + +The checkbox component styles the `` element. The markup must fit the following pattern: +- A wrapping `
` with the class `checkbox` + containing an `` with the chosen icon (usually `#icon-check`). + +### Style a checkbox with a label + +Style a checkbox with a label. Change the color of the checkbox with a `checkbox--{color}` modifier (`*-dark` colors are not available). +Adjust the line height of the checkbox to match a label with small text with the `checkbox--s-label` modifier. + +```example +
+ +
+ More cats + + +``` + +### When a checkbox has the `disabled` attribute, it will be styled accordingly + +

`input:disabled + .checkbox`

+ +When a checkbox has the `disabled` attribute, it will be styled accordingly. + +```example + + +``` + +## Radio buttons + +The radio component styles the `` element. The markup must fit the following pattern: +- A wrapping `
` with the class `radio`. + +### Style a radio button + +

`.radio`

+ +Style a radio button. Change the color of the radio button with a `radio--{color}` modifier (`*-dark` colors are not available). +Adjust the line height of the radio button to match a label with small text with the `radio--s-label` modifier. + +```example + + +``` + +### When a radio button has the `disabled` attribute, it will be styled accordingly + +

`input:disabled + .radio`

+ +When a radio button has the `disabled` attribute, it will be styled accordingly. + +```example + + +``` + +## Switches + +The switch component styles the `` element. The markup must fit the following pattern: +- A wrapping `
` with the class `switch`. + +### Style a switch + +

`.switch`

+ +Style a switch. +Change the color of the dot when inactive, the border when inactive, +and the background when active with a `switch--{color}` modifier (`*-dark` colors are not available). +Change the color of the dot when active with a `switch--dot-{color}` modifier. Adjust the line height of the switch to match a label with small text with the `switch--s-label` modifier. + +```example + + +``` + +### Make a switch control large + +

`.switch--l`

+ +Make a switch control large. + +```example + +``` + +### When a switch has the `disabled` attribute, it will be styled accordingly + +

`input:disabled + .switch`

+ +When a switch has the `disabled` attribute, it will be styled accordingly. + +```example + + +``` + +## Toggle group + +The toggle group component styles a set of `` elements. The markup must fit the following pattern: +- A wrapping `
` around all your radio options with the class `toggle-group`. +- For each radio option, a wrapping `
` with the class `toggle`. + +### Style a toggle group + +Style a toggle group. +Change the inactive toggle text color and the active toggle background color with a `toggle--{color}` modifier (`*-dark` colors are not available). +Change the active label color with a `toggle--active-{color}` modifier (`*-dark` colors are not available). +Change the border radiuses of toggle groups inside small text with `toggle-group--s` on the `toggle-container` element. + +```example +
+ + +
+``` + +### Make a toggle small + +Make a toggle small. + +```example +
+ + +
+``` + +### When a toggle group input has the `disabled` attribute, it will be styled accordingly + +

`input:disabled + .toggle`

+ +When a toggle group input has the `disabled` attribute, it will be styled accordingly. + +```example +
+ + +
+``` diff --git a/docs/documentation/icons.md b/docs/documentation/icons.md new file mode 100644 index 00000000..3d81b131 --- /dev/null +++ b/docs/documentation/icons.md @@ -0,0 +1,21 @@ +# Icons + +Assembly uses an SVG icon sprite. To load the sprite, you must must include [`assembly.js`](https://labs.mapbox.com/assembly/) on your page. + +**Please read [the Icons page](/assembly/icons) to learn more about the available icons and the [Javascript API section of the home page](/assembly#js-api) to learn how to use them.** + +## The `icon` class must be appled to an `` element + +The `icon` class must be appled to an `` element. +Inside the ``, insert a `` element whose `xlink:href` attribute +points to an icon loaded by `assembly.js`. All icons are referenced +by the string `#icon-{name}`. By default, icons inherit size from their calculated text size. +Change the size of icons by applying `w{size}` and `h{size}` classes to the svg. + +Be aware that *icons are block-level*. + +To see a list of all available icons, visit [the icons page](/assembly/icons). + +```example + +``` diff --git a/docs/documentation/index.md b/docs/documentation/index.md new file mode 100644 index 00000000..f7fabcfd --- /dev/null +++ b/docs/documentation/index.md @@ -0,0 +1,16 @@ +# Documentation + +Assembly's class reference. + +- [Typography](/documentation/typography) +- [Layout](/documentation/layout) +- [Theming](/documentation/theming) +- [Colors](/documentation/colors) +- [Icons](/documentation/icons) +- [Buttons](/documentation/buttons) +- [Links](/documentation/links) +- [Forms](/documentation/forms) +- [Tables](/documentation/tables) +- [Animations](/documentation/animations) +- [Triangles](/documentation/triangles) +- [Miscellaneous](/documentation/miscellaneous) diff --git a/docs/documentation/layout.md b/docs/documentation/layout.md new file mode 100644 index 00000000..f3f47a96 --- /dev/null +++ b/docs/documentation/layout.md @@ -0,0 +1,808 @@ +# Layout + +Define the size, shape, and content flow of your markup. + +## Grid + +Assembly uses a 12-column flexible grid with optional gutters. +`grid` is flexbox (`display: flex`). For CSS Grid, use [`gridbox`](#gridbox). + +### Grids require at minimum two elements: A parent with the class `grid` and a child with the class `col` + +Grids require at minimum two elements: A parent with the class `grid` and a child with the class `col`. To define the width of `col` in a grid, add a width class, `col--auto`, or both. The `grid` class includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +To avoid unexpected side-effects, do not add margin left or right to `grid` and do not add padding left or right to `col`. + +```example +
+
one
+
two
+
three
+
+``` + +### Apply to a `col` element to override a `col--{size}` rule and take on default `col`, occupying equal space with other `col` siblings + +Apply to a `col` element to override a `col--{size}` rule and take on default `col`, occupying equal space with other `col` siblings. +This class is designed to be used with `*-mm`, `*-ml`, and `*-mxl` variations +to target screen sizes. + +```example +
+
w-1/4 col--auto-ml
+
w-3/4 col--auto-ml
+
+``` + +### Apply column gutters to all columns in a grid by adding a `grid--gut{size}` modifier to the `grid` element + +Apply column gutters to all columns in a grid by adding a `grid--gut{size}` modifier to the `grid` element. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
+
+
w-1/6
+
+
+
w-1/3
+
+
+
w-1/2
+
+
+``` + +## Display + +Control the display style of elements. + +### Set an element's `display` property value. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes + +Set an element's `display` property value. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
inline
+
block
+
inline-block
+
none
+``` + +## Positioning + +Classes for basic positioning. For flexbox positioning rules, see the documentation for [flexbox](#flexbox) utilities. + +### Set an element's `position` property value. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes + +Set an element's `position` property value. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
+
absolute
+
relative
+
static
+
static
+ +
+``` + +### Pin a positioned element against a side of its container + +Pin a positioned element against a side of its container. Positioning classes can be combined to stretch elements across the top, bottom, left, or right sides of their container. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
+
right
+
bottom
+
left
+
top left right
+
+``` + +### Override default stacking order by setting an element's `z-index` property value + +Override default stacking order by setting an element's `z-index` property value. Whenever possible, rely on built-in stacking order and avoid using these classes. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
+
z5
+
z1
+
z-neg1
+
+``` + +## Margins + +All margin classes fit the following pattern: `m`. +And all margin class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +### Set `auto` margins on left and right + +Set `auto` margins on left and right. This pattern is useful for horizontally centering block elements or aligning block elements to the start or end of their container. + +```example +
mx-auto
+
ml-auto
+
mr-auto
+``` + +### Apply margin on the top and bottom + +Apply margin on the top and bottom. + +```example +
my24
+``` + +### Apply margin on the left and right + +Apply margin on the left and right. + +```example +
mx24
+``` + +### Apply margin on the top + +Apply margin on the top. + +```example +
mt24
+``` + +### Apply margin on the right + +Apply margin on the right. + +```example +
mr24
+``` + +### Apply percentage-based margin on the right. When using with `col`, add a width class, `col--auto`, or both to define the size of the element + +Apply percentage-based margin on the right. When using with `col`, add a width class, `col--auto`, or both to define the size of the element. + +```example +
+
mr-1/2
+
+``` + +### Apply margin on the bottom + +Apply margin on the bottom. + +The negative margin classes, mb-neg, can be useful for certain design patterns like underline tabs. + +```example +
mb24
+``` + +### Apply margin on the left + +Apply margin on the left. + +```example +
ml24
+``` + +### Apply percentage-based margin on the left. When using with `col`, add a width class, `col--auto`, or both to define the size of the element + +Apply percentage-based margin on the left. When using with `col`, add a width class, `col--auto`, or both to define the size of the element. + +```example +
+
ml-1/2
+
+``` + +## Padding + +All padding classes fit the following pattern: `m`. +And all padding class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +### Apply padding on the top and bottom + +Apply padding on the top and bottom. + +```example +
py24
+``` + +### Apply padding on the left and right + +Apply padding on the left and right. + +```example +
px24
+``` + +### Apply padding on the top + +Apply padding on the top. + +```example +
pt24
+``` + +### Apply padding on the right + +Apply padding on the right. + +```example +
pr24
+``` + +### Apply padding on the bottom + +Apply padding on the bottom. + +```example +
pb24
+``` + +### Apply padding on the left + +Apply padding on the left. + +```example +
pl24
+``` + +## Gap + +Gap utilities fit `gap{size}`, `gapx{size}`, and `gapy{size}` on the padding scale. +Class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. +Use with `flex`, `inline-flex`, or `gridbox`. Do not combine with `grid--gut*` or percentage `w-*` columns on `grid`. + +### Apply `gap` on both axes. Use with `flex`, `inline-flex`, or `gridbox` + +Apply `gap` on both axes. Use with `flex`, `inline-flex`, or `gridbox`. +Do not combine with `grid--gut*` or percentage `w-*` columns on `grid`. + +```example +
+
a
+
b
+
c
+
+``` + +### Apply `column-gap` (horizontal gap) + +Apply `column-gap` (horizontal gap). + +```example +
+
a
+
b
+
+``` + +### Apply `row-gap` (vertical gap) + +Apply `row-gap` (vertical gap). + +```example +
+
a
+
b
+
+``` + +## Sizing + +All sizing classes fit the following pattern: `` or `-full` for `100%`. +And all sizing class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +### Set an element's width + +Set an element's width. + +In addition to numeric values, there are `w-full` and `w-auto` classes. + +```example +
w60
+``` + +### Set a percentage-based width + +Set a percentage-based width. + +```example +
+
w-1/2
+
w-1/4
+
w-1/4
+
+``` + +### Set an element's maximum width + +Set an element's maximum width. + +In addition to numeric values, there are `wmax-full` and `wmax-none` classes. + +```example +
wmax6
+``` + +### Set an element's minimum width + +Set an element's minimum width. + +In addition to numeric values, there is the `wmin-full` class. + +```example +
wmin60
+``` + +### Set an element's height + +Set an element's height. + +In addition to numeric values, there are `h-full` and `h-auto` classes. + +```example +
h24
+``` + +### Set an element's maximum height + +Set an element's maximum height. + +In addition to numeric values, there are `hmax-full` and `hmax-none` classes. + +```example +
hmax12
+``` + +### Set an element's minimum height + +Set an element's minimum height. + +In addition to numeric values, there is the `hmin-full` class. + +```example +
hmin60
+``` + +### Set a viewport-based height + +Set a viewport-based height. + +```example +
h-viewport-1/3
+``` + +### Set a viewport-based max width + +Set a viewport-based max width. + +```example +
hmax-viewport-1/3
+``` + +## Flexbox + +Flexbox utilities. All class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +Usage must fit the following pattern: +- `flex` or `inline-flex` must be on a parent container in order to use `flex--*` modifiers, while `flex-child-*` rules control children of a `flex` or `inline-flex` element. +- By default, the `main` axis is horizontal and the `cross` axis is vertical. The axes can be inverted with the use of `flex--column`. +- To learn about how the flexbox system works, check out ["A Complete Guide to Flexbox"](https://css-tricks.com/snippets/css/a-guide-to-flexbox). + +### Establish an element as a flex parent + +Establish an element as a flex parent. +These classes allow the use of `flex--*` modifiers, and `flex-child-*` classes on children. + +```example +
flex
+
inline-flex
+``` + +### Set the direction of the main axis to top-to-bottom (default is left-to-right) + +Set the direction of the main axis to top-to-bottom (default is left-to-right). + +```example +
+ 1 + 2 + 3 +
+``` + +### Set the direction of the main axis to bottom-to-top (default is left-to-right) + +Set the direction of the main axis to bottom-to-top (default is left-to-right). + +```example +
+ 1 + 2 + 3 +
+``` + +### Set the direction of the main axis to left-to-right (the default value of `flex`) + +```example +
+ 1 + 2 + 3 +
+``` + +### Set the direction of the main axis to right-to-left (default is left-to-right) + +Set the direction of the main axis to right-to-left (default is left-to-right). + +```example +
+ 1 + 2 + 3 +
+``` + +### Center an element's children on the main axis + +Center an element's children on the main axis. + +```example +
+
child
+
+``` + +### Center an element's children on the cross axis + +Center an element's children on the cross axis. + +```example +
+
child
+
+``` + +### Align an element's children to the start of the cross axis + +Align an element's children to the start of the cross axis. + +```example +
+
child
+
child
+
+``` + +### Align an element's children to the start of the main axis + +Align an element's children to the start of the main axis. + +```example +
+
child
+
+``` + +### Align an element's children to the end of the cross axis + +Align an element's children to the end of the cross axis. + +```example +
+
child
+
child
+
+``` + +### Align an element's children to the end of the main axis + +Align an element's children to the end of the main axis. + +```example +
+
child
+
+``` + +### Allow children to wrap. By default, they are all forced onto one line + +Allow children to wrap. By default, they are all forced onto one line. + +```example +
+
child
+
child
+
+``` + +### Stretch children to fill the parent container along the cross axis + +Stretch children to fill the parent container along the cross axis. + +```example +
+
child
+
+``` + +### Evenly distribute children across the line, so first child is at the start + +Evenly distribute children across the line, so first child is at the start +and last child is at the end. + +```example +
+
child
+
child
+
+``` + +### Distribute children with equal space around each item on the main axis + +Distribute children with equal space around each item on the main axis. + +```example +
+
child
+
child
+
+``` + +### Distribute children with equal space between and around items on the main axis + +Distribute children with equal space between and around items on the main axis. + +```example +
+
child
+
child
+
+``` + +### Make a child grow to fill whatever space is available in the main axis of the parent container + +Make a child grow to fill whatever space is available in the main axis of the parent container. +This is useful when you have one or more elements of +fixed width, and another element that should take up the remaining space in the row. + +Typically, you will also want to apply the `flex-child-no-shrink` class to the element in the row with a fixed width. + +```example +
+
child
+
child
+
+``` + +### Prevent a child from shrinking below its width value + +Prevent a child from shrinking below its width value. + +By default, flex children (even with specified widths) will shrink as needed to accommodate sibling elements. +This class prevents that default shrinkage, forcing siblings to accommodate the parent's width. + +```example +
+
child
+
child
+
child
+
+``` + +## Gridbox + +CSS Grid utilities. All class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +`gridbox` does not replace [`grid`](#grid). Keep using `grid` / `col` / `grid--gut*` for the 12-column flex system. + +Usage: +- Put `gridbox` or `inline-gridbox` on the parent. +- Set columns with `gridbox--cols{n}` (1–12). Use `gap{size}` for spacing. +- Span children with `gridbox-child-col{n}` and `gridbox-child-row{n}`. + +### Establish an element as a CSS Grid parent + +Establish an element as a CSS Grid parent. + +```example +
+
1
+
2
+
3
+
+``` + +### Set `grid-auto-flow`. `gridbox--row` is the CSS default; use it to override a column flow + +Set `grid-auto-flow`. `gridbox--row` is the CSS default; use it to override a column flow. + +```example +
+
1
+
2
+
3
+
+``` + +### Align items inside their grid areas with `place-items` + +Align items inside their grid areas with `place-items`. + +```example +
+
center
+
center
+
+``` + +### Distribute extra space between grid tracks + +Distribute extra space between grid tracks. + +```example +
+
1
+
2
+
3
+
+``` + +### Set the number of equal columns on a `gridbox` + +Set the number of equal columns on a `gridbox`. + +```example +
+
1
+
2
+
3
+
+``` + +### Set the number of equal rows on a `gridbox` + +Set the number of equal rows on a `gridbox`. + +```example +
+
1
+
2
+
3
+
4
+
+``` + +### Span columns on a `gridbox` child + +Span columns on a `gridbox` child. + +```example +
+
span 2
+
1
+
1
+
+``` + +### Span rows on a `gridbox` child + +Span rows on a `gridbox` child. + +```example +
+
span 2 rows
+
1
+
1
+
+``` + +## Aspect ratio + +Aspect-ratio classes fit `aspect-{ratio}` (`aspect-1/1`, `aspect-16/9`, `aspect-auto`). +Class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +### Set `aspect-ratio`. `aspect-auto` resets it + +Set `aspect-ratio`. `aspect-auto` resets it. + +```example +
aspect-16/9
+``` + +## Object fit + +Set `object-fit` on replaced elements such as `img` and `video`. +Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
object-cover
+``` + +## Transforms + +Transform utilities use the individual `rotate`, `scale`, and `translate` properties so they compose. +Rotate and scale classes fit `rotate{deg}` / `scale{percent}`; translate classes fit `translate-x{n}` / `translate-y{n}` on the margin scale. +Class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +### Rotate an element. Combines with `scale*` and `translate-*` + +Rotate an element. Combines with `scale*` and `translate-*`. + +```example +
+``` + +### Scale an element. `scale100` is `1`. Combines with `rotate*` and `translate-*` + +Scale an element. `scale100` is `1`. Combines with `rotate*` and `translate-*`. + +```example +
+``` + +### Translate on the x axis. Uses the margin scale, including negatives + +Translate on the x axis. Uses the margin scale, including negatives. + +```example +
+``` + +### Translate on the y axis. Uses the margin scale, including negatives + +Translate on the y axis. Uses the margin scale, including negatives. + +```example +
+``` + +## Layout utils + +Extra layout utilities. + +### Bleed utilities. Bleed classes allow an element inside a centered container to escape the container and meet the edge of the screen + +Bleed utilities. Bleed classes allow an element inside a centered container to escape the container and meet the edge of the screen. +When using the bleed classes, consider adding the `.overflow-hidden` class on a parent element to prevent horizontal overflow. + +*Warning*: Bleeding elements will never bleed out to more than 50% of the viewport width. +So you should not make an element bleed to one side unless it's already on that half of +the screen. + +*Warning*: In Firefox, children with negative margins have different layout effects than in other browsers. +The bleed classes should only be used if the parent's width is stable, either because it is set or because other children determine it. + +Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. +These screen-size variants are best suited to *adding* the bleed, not *removing* it. +Be aware of the effects of the `unbleed` class: it resets `margin-left`, `margin-right`, +and `flex-child-grow`. + +```example +
+
+
Right bleed
+
+
+``` + +### Float utilities. Class set (except `clearfix`) includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes + +Float utilities. Class set (except `clearfix`) includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
+
left
+
+
with .clearfix
+
right
+
without .clearfix
+
unfloat
+``` diff --git a/docs/documentation/links.md b/docs/documentation/links.md new file mode 100644 index 00000000..e82a8b0f --- /dev/null +++ b/docs/documentation/links.md @@ -0,0 +1,38 @@ +# Links + +Create clickable, hoverable, focusable, colored text. +These classes are often used for actual `` elements with `href` attributes, +but might prove useful for ` + +``` diff --git a/docs/documentation/miscellaneous.md b/docs/documentation/miscellaneous.md new file mode 100644 index 00000000..cb7db12b --- /dev/null +++ b/docs/documentation/miscellaneous.md @@ -0,0 +1,131 @@ +# Miscellaneous + +Extra rules that come in handy. + +## Style scrollbars. Only works in Webkit-based browsers (Safari and Chrome) + +

`.scroll-styled`

+ +Style scrollbars. Only works in Webkit-based browsers (Safari and Chrome). +On dark backgrounds, add the `scroll-styled--dark` modifier. + +**Use in combination with `overflow-auto`.** + +```example +
+
+``` + +## Style a loading spinner + +Style a loading spinner. +On dark backgrounds, add the `loading--dark` modifier. +For a smaller spinner, add the `loading--s` modifier. +Use `color-*` classes to apply a custom color to the spinner handle. + +```example +
+
+
+
+
+
+
+
+``` + +## Disable touch and click events on an element and its children + +Disable touch and click events on an element and +its children. Be aware that this rule does not disable keyboard events, +so a user can still tab to an element and press Return to trigger +its click event. + +```example +
You can't click this
+``` + +## Enable touch and click events on an element and its children + +Enable touch and click events on an element and +its children. Use to re-enable such events inside a parent with the `events-none` class. + +```example +
You can click this.
+``` + +## Disable text selection on an element and its children + +Disable text selection on an element and its children. Use only in cases where accidental text selection causes user frustration. + +```example +
You can't select this.
+``` + +## Enable text selection on an element and its children + +Enable text selection on an element and its children. +Use to re-enable selection inside a parent with the `unselectable` class. + +```example +
You can select this.
+``` + +## Apply a subtle animated transition when changing CSS properties on an element + +Apply a subtle animated transition when changing CSS properties on an element. See MDN's [list of CSS animated properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animated_properties) for every property effected by this class. + +```example +
Hover over me
+``` + +## Disable an animated transition on elements like [`btn`](/documentation/buttons) that have default transitions + +Disable an animated transition on elements like [`btn`](/documentation/buttons) that have default transitions. + +```example +
transition-none
+``` + +## Always show scrollbars + +Always show scrollbars. + +```example +
Curabitur blandit tempus porttitor. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Maecenas faucibus mollis interdum. Donec ullamcorper nulla non metus auctor fringilla. Nullam id dolor id nibh ultricies vehicula ut id elit.
+``` + +## Display scrollbars if content flows beyond the edge of the element + +Display scrollbars if content flows beyond the edge of the element. + +```example +
Curabitur blandit tempus porttitor. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Maecenas faucibus mollis interdum. Donec ullamcorper nulla non metus auctor fringilla. Nullam id dolor id nibh ultricies vehicula ut id elit.
+``` + +## Hide content if it extends beyond the edge of the containing element + +Hide content if it extends beyond the edge of the containing element. + +```example +
Curabitur blandit tempus porttitor. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Maecenas faucibus mollis interdum. Donec ullamcorper nulla non metus auctor fringilla. Nullam id dolor id nibh ultricies vehicula ut id elit.
+``` + +## Hide an element *visually*, but keep it available to screen readers + +Hide an element *visually*, but keep it available to screen readers. + +```example +
You cannot see this with your eyes.
+
There is a sentence above this that you cannot see.
+``` + +## Apply display none when rendering page for print + +

`.none-print`

+ +Apply display none when rendering page for print. + +```example +
`.table`

+ +Apply standard table styling. + +```example + + + + + + + + + + + + + + + + + +
Malesuada Tristique CommodoNibh Commodo
itemitem
itemitem
+``` + +## Invert a table's colors so it is legible against a dark background + +Invert a table's colors so it is legible against a dark background. + +```example +
+ + + + + + + + + + + + + + + + + +
Malesuada Tristique CommodoNibh Commodo
itemitem
itemitem
+
+``` + +## Any columns whose widths are *not* specified (by their top cells) will be equally distributed across the available space + +Any columns whose widths are *not* specified (by their top cells) will be equally distributed across the available space. + +```example + + + + + + + + + + + + + + + + + + + + +
Malesuada Tristique CommodoNibh CommodoFusce
FusceCurabitur blandit tempus porttitor.Aenean Adipiscing
Donec ullamcorper nulla non metus auctor fringilla. Maecenas faucibus mollis interdum.Maecenas sed diam eget risus varius blandit sit amet non magna. Nullam quis risus eget urna mollis ornare vel eu leo.Cras Inceptos Purus
+``` diff --git a/docs/documentation/theming.md b/docs/documentation/theming.md new file mode 100644 index 00000000..89361de0 --- /dev/null +++ b/docs/documentation/theming.md @@ -0,0 +1,175 @@ +# Theming + +Decorate elements with borders, shadows, opacity adjustments, and more. + +## Borders + +Add borders to an element. + +### Add a `1px` border that is the same color as the element's text. Target sides with `*-t`, `*-r`, `*-b`, and `*-l` + +Add a `1px` border that is the same color as the element's text. Target sides with `*-t`, `*-r`, `*-b`, and `*-l`. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
border
+
border-b
+``` + +### Make a border zero pixels wide. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes + +Make a border zero pixels wide. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes. + +```example +
border-r--0
+``` + +### Make a border two pixels wide + +Make a border two pixels wide. + +```example +
border--2
+``` + +### Make a border dashed instead of solid + +Make a border dashed instead of solid. + +```example +
border--dash
+``` + +### Apply a [color](/documentation/colors) to a border + +Apply a [color](/documentation/colors) to a border. + +```example +
border--red
+``` + +### Apply a border color on hover and active states + +Apply a border color on hover and active states. + +```example +
border--red-on-hover
+
border--red-on-active (not active)
+
border--red-on-active (active)
+``` + +## Border radius + +Adjust the curve of an element's corners. All border classes include `*-mm`, +`*-ml`, and `*-mxl` variations to target screen sizes. + +### Round the corners of elements. Target sides with `*-t`, `*-r`, `*-b`, `*-l` + +Round the corners of elements. Target sides with `*-t`, `*-r`, `*-b`, `*-l`. +Target corners with `*-tl`, `*-tr`, `*-bl`, `*-br`. + +```example +
round
+
round-tr
+``` + +### Like `round`, but with twice the border radius + +Like `round`, but with twice the border radius. + +```example +
round-bold
+
round-tr-bold
+``` + +### Like `round`, but with fully round corners + +Like `round`, but with fully round corners. + +```example +
round-full
+
round-tr-full
+``` + +### Unround the corners of elements. Target sides with `*-t`, `*-r`, `*-b`, `*-l`. Target corners with `*-tl`, `*-tr`, `*-bl`, `*-br` + +Unround the corners of elements. Target sides with `*-t`, `*-r`, `*-b`, `*-l`. Target corners with `*-tl`, `*-tr`, `*-bl`, `*-br`. + +```example + +``` + +## Shadows + +Apply outer shadows that add emphasis to elements or structure to layouts. Class naming follows the pattern `shadow-`. + +### Apply a box shadow + +Apply a box shadow. + +```example +
shadow-darken25
+``` + +### Apply a larger box shadow + +Apply a larger box shadow. + +```example +
shadow-darken25-bold
+``` + +### Apply a box shadow on hover and active states + +Apply a box shadow on hover and active states. + +```example +
shadow-darken25-on-hover
+
shadow-darken25-on-active (not active)
+
shadow-darken25-on-active (active)
+``` + +## Cursors + +Set the style of the cursor when hovering over an element. + +### Set the `cursor` property value of an element + +Set the `cursor` property value of an element. + +```example +
cursor-pointer
+
cursor-crosshair
+
cursor-move
+
cursor-notallowed
+
cursor-grab
+
cursor-grabbing
+
cursor-col-resize
+
cursor-row-resize
+``` + +## Opacity + +Dim elements, or hide them from the document flow without removing them. + +### Apply an opacity + +Apply an opacity. + +```example +
opacity25
+
opacity50
+
opacity100
+``` + +### Apply an opacity on hover and active states + +Apply an opacity on hover and active states. + +`.opacity100-on-focus` is also available to make an otherwise transparent element opaque on focus. + +```example +
opacity25-on-hover
+
opacity25-on-active (inactive)
+
opacity25-on-active (active)
+ +``` diff --git a/docs/documentation/triangles.md b/docs/documentation/triangles.md new file mode 100644 index 00000000..08d79218 --- /dev/null +++ b/docs/documentation/triangles.md @@ -0,0 +1,25 @@ +# Triangles + +Create general-purpose triangle-shaped elements. Great for dialog boxes and tooltips. + +## Style simple small triangles + +Style simple small triangles. + +```example +
+
+
+
+``` + +## Style large triangles + +Style large triangles. + +```example + + + + +``` diff --git a/docs/documentation/typography.md b/docs/documentation/typography.md new file mode 100644 index 00000000..873e8f2b --- /dev/null +++ b/docs/documentation/typography.md @@ -0,0 +1,385 @@ +# Typography + +Font styles, sizes, and utilities. + +There are two ways to style text with Assembly: by applying utility classes to every element, +or by creating [`prose`](#prose) sections. All typographic styles can be applied individually with classes that have a +`.txt-` prefix. Alternatively, [`prose`](#prose) sections can be used to apply sensible default styling for all the semantic elements they contain. + +## Type basics + +Classes for font size and line height, lists, block quotes, code blocks, and more. + +### Style text like a keyboard button + +

`.txt-kbd`

+ +Style text like a keyboard button. + +```example +You entered Flamingo. +``` + +### Style subscript text: small and below the standard line + +

`.txt-sub`

+ +Style subscript text: small and below the standard line. + +```example +The chemical formula of water is H2O. +``` + +### Style a code block + +

`.pre`

+ +Style a code block. + +```example +
+for each
+  do this
+end
+
+``` + +### Style text as inline code + +

`.txt-code`

+ +Style text as inline code. + +```example +Make sure you git checkout the repository. +``` + +### Classes for the headline text scale. Line heights are 1.3333 times font size or less + +Classes for the headline text scale. Line heights are 1.3333 times font size or less. +All text size classes include `-mm`, `-ml`, and `-mxl` variations to target screen sizes. + +```example +
Malesuada Pharetra Ridiculus
+
Malesuada Pharetra Ridiculus
+
Malesuada Pharetra Ridiculus
+
Malesuada Pharetra Ridiculus
+
Malesuada Pharetra Ridiculus
+``` + +### Classes for the body text scale. Line heights are 1.5 times font size or more + +Classes for the body text scale. Line heights are 1.5 times font size or more. +All text size classes include `-mm`, `-ml`, and `-mxl` variations to target screen sizes. + +```example +
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+
Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
+``` + +### Style an abbreviation or acronym + +

`.txt-abbr`

+ +Style an abbreviation or acronym. + +```example +How do you feel about CSS? +``` + +### Style a line separating two blocks of text + +

`.txt-hr`

+ +Style a line separating two blocks of text. + +```example +
+``` + +### Style an unordered list. Works with any element type if the list items use the `txt-li` class, but you should almost always use it with a `
    ` element + +

    `.txt-ul`

    + +```example +
    +
    one
    +
    two
    +
    three
    +
    +``` + +### Style an ordered list. This does *not* work (in Firefox) without semantic elements `
      ` and `
    1. `, so use those + +

      `.txt-ol`

      + +```example +
        +
      1. one
        2. +
      2. two
        3. +
      3. three
        4. +
      +``` + +### Style a block quotation + +

      `.txt-blockquote`

      + +Style a block quotation. + +```example +
      Donec sed odio dui. Integer posuere erat a ante venenatis dapibus posuere velit aliquet. Donec ullamcorper nulla non metus auctor fringilla.
      +``` + +### Style superscript text: small and above the standard line + +

      `.txt-sup`

      + +Style superscript text: small and above the standard line. + +```example +Planet earth is seven years old. citation needed +``` + +## Type utils + +Single-purpose classes for styling text. + +### Apply Assembly's monospaced font stack + +Apply Assembly's monospaced font stack. + +```example +
      txt-mono
      +``` + +### Apply a bold font weight + +Apply a bold font weight. + +```example +
      txt-bold
      +``` + +### Apply a light font weight + +Apply a light font weight. + +```example +
      txt-light
      +``` + +### Apply a normal font weight + +Apply a normal font weight. + +```example +
      txt-normal
      +``` + +### Italicize text + +Italicize text. + +```example +
      em
      +``` + +### Capitalize all letters in an element + +Capitalize all letters in an element. + +```example +
      UpPeRcAsE
      +``` + +### Lowercase all letters in an element + +Lowercase all letters in an element. + +```example +
      LoWeRcAsE
      +``` + +### Capitalize all words in an element + +Capitalize all words in an element. + +```example +
      all words are capitalized
      +``` + +### Capitalize the first letter in an element + +

      `.txt-capitalize-first`

      + +Capitalize the first letter in an element. + +```example +
      first word only is capitalized
      +``` + +### Underline text + +Underline text. + +```example +
      txt-underline
      +``` + +### Underline text on hover + +

      `.txt-underline-on-hover`

      + +Underline text on hover. + +```example +txt-underline-on-hover +``` + +### Strikethrough text + +

      `.txt-strike`

      + +Strikethrough text. + +```example +
      txt-strike
      +``` + +### Prevent text from wrapping + +Prevent text from wrapping. + +```example +
      + This text is too long for its container +
      +``` + +### Allow words to break across lines + +Allow words to break across lines. + +```example +
      + Thiswordistoolongforitscontainer +
      +``` + +### Truncate text to a single line contained within the width + +Truncate text to a single line contained within the width +of its container, ending with an ellipsis if it overflows. + +```example +
      + This text is too long for its container +
      +``` + +### Apply extra space between letters + +Apply extra space between letters. + +```example +
      spaced out
      +
      way spaced out
      +``` + +### Apply text shadows + +Apply text shadows. + +```example +
      ghost world
      +
      ghost world
      +
      ghost world
      +
      ghost world
      +
      ghost world
      +
      ghost world
      +``` + +### Control the horizontal alignment of an element's inline children + +Control the horizontal alignment of an element's inline children. + +```example +
      .align-l
      +
      .align-r
      +
      .align-center
      +``` + +### Control the vertical alignment of an inline or table-cell element + +Control the vertical alignment of an inline or table-cell element. + +```example +
      + + align-t +
      +
      + + align-middle +
      +
      + + align-b +
      +``` + +## Prose + +Conveniently style large blocks of semantic markup. +`prose` is designed to only be used when content is generated by a markdown processor and you don't have control over each element's class list. + +### Apply appropriate styles based on semantic markup. Supported elements are: + +

      `.prose`

      + +Apply appropriate styles based on semantic markup. Supported elements are: +`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `table`, `small`, `ul`, `ol`, `a`, `abbr`, `hr`, `blockquote`, `kbd`, `sub`, `sup`, `code`, `pre`, `del`, `s`, `img`, and `video`. + +```example +
      +

      Tortor Porta

      + Aenean lacinia bibendum nulla sed consectetur. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam quis risus eget urna mollis ornare vel eu leo. +
      +

      Cras justo odio, dapibus ac facilisis[note] in, egestas eget quam. Lorem ipsum dolor sit amet, consectetur adipiscing elit. H20 electrolitis.

      +
      +``` + +### Remove prose styling. Useful when you need to display, for example, a custom form inside an otherwise consistently-styled document + +

      `.unprose`

      + +Remove prose styling. Useful when you need to display, for example, a custom form inside an otherwise consistently-styled document. + +**Apply this class directly to the element you want to unstyle.** It does not work on containers, only on the elements themselves. + +```example +
      +

      felis euismod semper

      + Click me +

      Morbi leo risus

      + Click me +
      +``` + +### Invert the coloring of textual content inside `prose` sections, so it is legible against dark backgrounds + +Invert the coloring of textual content inside `prose` sections, so it is legible against dark backgrounds. + +```example +
      +

      Tortor Porta

      + Aenean lacinia bibendum nulla sed consectetur. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam quis risus eget urna mollis ornare vel eu leo. +
      +

      Cras justo odio, dapibus ac facilisis[note] in, egestas eget quam. Lorem ipsum dolor sit amet, consectetur adipiscing elit. H20 electrolitis.

      +
      +``` diff --git a/docs/examples/badges.md b/docs/examples/badges.md new file mode 100644 index 00000000..c422a0aa --- /dev/null +++ b/docs/examples/badges.md @@ -0,0 +1,37 @@ +

      Badges

      + +

      Badges

      + +```example +
      + screamin dealz +
      +``` + +```example +
      + + Did you know? +
      +``` + +```example +
      + Heads up! + +
      +``` + +```example +
      +
      + This +
      + +
      + is that +
      +
      +``` diff --git a/docs/examples/equal-height-columns.md b/docs/examples/equal-height-columns.md new file mode 100644 index 00000000..d5d9269f --- /dev/null +++ b/docs/examples/equal-height-columns.md @@ -0,0 +1,31 @@ +

      Equal-height columns

      + +

      Equal-height columns

      + +
      + +This effect is easy, of course, if you can fix the height of the columns. Often, though, that's not what you want. If you want columns to have equal heights *based on the column with the tallest content*, you need some flexbox powers. + +The key here is to add `flex--stretch-cross` to the `grid`, and add `h-full` to the *child* of the `col` element, which is the one with the background color. + +
      + +```example +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +``` diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 00000000..e56f52b0 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,9 @@ +--- +title: Examples +--- + + + + diff --git a/docs/examples/inputs.md b/docs/examples/inputs.md new file mode 100644 index 00000000..128c85e6 --- /dev/null +++ b/docs/examples/inputs.md @@ -0,0 +1,32 @@ +

      Inputs

      + +

      Input with button

      + +```example +
      + + +
      +``` + +

      Input with icon

      + +```example +
      +
      + +
      + +
      +``` + +

      Input with spinner

      + +```example +
      +
      + +
      + +
      +``` diff --git a/site/pages/examples/legends.js b/docs/examples/legends.md similarity index 67% rename from site/pages/examples/legends.js rename to docs/examples/legends.md index f25e4ff8..46882599 100644 --- a/site/pages/examples/legends.js +++ b/docs/examples/legends.md @@ -1,8 +1,9 @@ -import React from 'react'; -import { HtmlExample } from '../../html_example'; -import { Page } from '../../page'; +

      Legends

      -const basicLegend = `
      +

      Legend with bars

      + +```example +
      Title description
      @@ -18,9 +19,11 @@ const basicLegend = `
      Low
      High
      -
      `; +
      +``` -const basicLegendTwo = `
      +```example +
      Title description
      @@ -34,9 +37,13 @@ const basicLegendTwo = `
      50
      75
      -
      `; +
      +``` + +

      Legend with varying radius

      -const radiusLegend = `
      +```example +
      Title description
      @@ -62,24 +69,5 @@ const radiusLegend = `
      18
      24
      -
      `; - -export default class ExampleLegends extends React.Component { - render() { - return ( - -

      - Legend with bars -

      -
      - -
      - -

      - Legend with varying radius -

      - -       - ); - } -} +
      +``` diff --git a/site/pages/examples/modal.js b/docs/examples/modal.md similarity index 55% rename from site/pages/examples/modal.js rename to docs/examples/modal.md index 4cc0500b..21fa6161 100644 --- a/site/pages/examples/modal.js +++ b/docs/examples/modal.md @@ -1,8 +1,9 @@ -import React from 'react'; -import { HtmlExample } from '../../html_example'; -import { Page } from '../../page'; +

      Modal

      -const tiles = `
      +

      Modal component

      + +```example +
      @@ -18,17 +19,5 @@ const tiles = `
      -
      `; - -export default class ExampleModal extends React.Component { - render() { - return ( - -

      - Modal component -

      - -       - ); - } -} +
      +``` diff --git a/site/pages/examples/navigation.js b/docs/examples/navigation.md similarity index 60% rename from site/pages/examples/navigation.js rename to docs/examples/navigation.md index 5d947117..f9d32b7b 100644 --- a/site/pages/examples/navigation.js +++ b/docs/examples/navigation.md @@ -1,8 +1,9 @@ -import React from 'react'; -import { HtmlExample } from '../../html_example'; -import { Page } from '../../page'; +

      Navigation

      -const menuNavigation = `