oui-kit

# oui-stylus > CSS Framework written in Stylus Goals: - [ ] Good CSS resets - [ ] Support for dark mode - [ ] Styleguide for naming properties and CSS variables - [ ] Great defaults - [ ] Concise --- ## Naming conventions In general the **semantic meaning** is prefered over visual aspects. ### Components CSS for Vue components start with `oui-` like `oui-modal`. ### Modifiers Modifiers start with an underscore like `_active`. The idea behind this is, that you can more easily use these in Vue class bindings like `:class="{ _active }"`, because they don't conflict with JS variable names, like `-active` would do. I also want to avoid uppercase letters, and therefore modifiers like `isActive` or `hasValue` (see Bulma). Modifiers should only be defined together with other class names, like `&._active`. For widgets with inner structure this might look like this: ```html <div class="oui-list"> <div class="oui-list-item" :class="{ _active }"> ... </div> </div> ``` ### CSS variables ```css :root { /* Neutral colors */ --n0-50: #f5f6f6; --n0-100: #e6e7e7; --n0-200: #d0d1d1; --n0-300: #aeb0b2; --n0-400: #7d8082; --n0-500: #6b6e6f; --n0-600: #5b5d5f; --n0-700: #4e4f50; --n0-800: #444546; --n0-900: #3c3d3d; --n0-950: #252527; /* Brand / primary colors */ --p1-50: #f3f7fc; --p1-100: #e7eff7; --p1-200: #c9dbee; --p1-300: #9abedf; --p1-400: #639ccd; --p1-500: #4385be; --p1-600: #2e659b; --p1-700: #27527d; --p1-800: #234569; --p1-900: #223c58; --p1-950: #17273a; } ``` ```css :root { /** Common text and panel colors */ --fg: var(--n0-950, black); --bg: var(--n0-50, white); --s2-fg: var(--n0-800); --s2-bg: var(--n0-200); --t3-fg: var(--n0-700); --t3-bg: var(--n0-300); /* Hyperlinks */ --link-fg: var(--p1-800); --link-fg-hover: var(--p1-700); --link-fg-active: var(--p1-600); } /* Dark mode via class, because user might want to choose */ .dark { --fg: var(--n0-50, white); --bg: var(--n0-950, black); } ``` `--name-(level)-style-state` `--link-fg-hover` `--input-border-focus` `--s2-bg` - Level (Basics) - `n0` (neutral, usually gray) - `p1` (primary) - `s2` (secondary, usually lighter) - `t3` (ternary, usually even more lighter) - Style - `fg` is **foreground color**, corresponds to `color` - `bg` is **background**, corresponds to `background` - `border` - `shadow` - `outline` - `radius` - State - `active` - `disabled` - `focus` - `hover` Do not use words like `color`. ## Colors We work with color palettes like in Tailwind where `500` is the actual color. These tools might help to find good values for you particular color: - [tailwindcss](https://tailwindcss.com/docs/customizing-colors) pick a good one here - [tailwindshades](https://www.tailwindshades.com/) - [ui colors](https://uicolors.app/create) - [tints.dev](https://www.tints.dev/) --- For websites and web apps there is no way around CSS. It is versatile and powerful, but in some places it is also cumbersome. CSS frameworks make things easier, but sometimes they are already too much. Then there are also utility first CSS frameworks like [Tailwind](https://tailwindcss.com/), which put the [whole design back into HTML](https://tailwindcss.com/docs/utility-first). Tailwind indeed offers maximum flexibility with attractive results. But it ignores the semantic structure of HTML. Especially if different themes are to be used, the classic approach to separate content and visual design is better. To get the best of both worlds, I have written Stylus mix ins inspired by Tailwind using the incredibly powerful yet elegant [Stylus CSS preprocessor](https://stylus-lang.com/), which should make the code clearer. ## Units We introduce the special unit `rex` (a mix of `rem` and `px`). `1rem` is usually equivalent to `16px`, but it can vary between different environments. Still it is easier for most developers think in `px`. To get the best of both worlds and a UI that scales correctly for the environment you can now use `rex(value)` to have the pseudo pixel size being translated to `rem` values. The shortcuts for `padding` and `margin` automatically convert pure numbers without any specified unit to `rex`. Such that in the following example we would get horizontal margins if `0.5rem`: ```stylus .demo m-x 8 ``` It should always be thought in steps of 8 to get a harmonious picture. Further, shortcuts like `p()` or `m-y()` or `p-r()` or the long versions like `padding-y` are available. In case you would like to write your own function using `rex` with multiple values, there is a function for that: ```stylus fancy-border() border rexArgs(arguments) .test fancy-border 1 solid -gray-500 // Will result in: // border: 0.0625rem solid #71717a; ``` ## Predefined Values and Colors Predefined values are prefixed by `-`. This convention should help to better see the difference of a mix in and a value. Such values are e.g. colors. These have been adopted from Tailwind and can be used beautifully as follows: ```stylus .success color -green-900 background -green-100 ``` You can see the [full list of colors at Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference). ## Breakpoints / Responsiveness Stylus already offers a flexible '@media' support, so it can also be placed within a class or mix in. The breakpoints are defined as variables. Example: ```stylus container() m-x(32) @media -lg margin-left auto margin-right auto max-width 960px ``` The full list is: ```stylus -sm = '(min-width: 640px)' -md = '(min-width: 768px)' -lg = '(min-width: 1024px)' -xl = '(min-width: 1280px)' ``` ## Dark Mode If the design should respond to systems that prefer dark mode, you can simply to so by defining the alternatives with `@media -dark`: ```stylus body color -gray-900 @media -dark color white background -gray-800 ``` But you could also set a class named `dark` to the `html` element programmatically and respond to that: ```stylus body color -gray-900 .dark & color white background -gray-800 ``` Learn more about [this setup at Tailwind](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually). ## Reset The included reset canonizes all elements so that they are used purely semantically and can be visually overloaded later. The box model is predefined with 'box-sizing: border-box'. In the own CSS definition you should then only set the desired font. However, _twindy_ generally does not add styles on its own, so we have to call the following mix in at the beginning of the CSS file: ```stylus oui-reset() ``` ## Text Similar to the reset, there are also predefined styles for continuous text passages, which can be used optionally. For example, for elements within the `.text` class: ```stylus .text oui-text() ``` ## Shortcuts To make the code look more like CSS you can use the `tw` expander for functionalities, that have none or default arguments (aliases `use`, `do`, `apply` or `twindy`). The previous example could be written this way too: ```stylus article use text ``` But it is also possible to add multiple calls like shown in the following sections. ## Stack Layout A strong abstraction for the layout, especially for web apps, is provided by stacks. A container can define a vertical `stack-y()` or horizontal `stack-x()`. The child elements are then arranged accordingly. If an element should consume the remaining space it can be marked with `grow()`. If it should be vertically scrollable, this can be done with `vscroll()`. If contained content should be placed vertically and horizontally centered, this can be defined with `center()`. In general, the layout is created using a flex box, so all the usual CSS properties will work. Example: ```stylus .app use stack-x .sidebar use stack-y .content use stack-item-grow stack-item-scroll ``` ## Blocks You can of course name and set your CSS selectors as you like, but I personally would not recommend going nuts by naming elements the [BEM](https://en.bem.info/) way or nest to hard. If you avoid global definitions for repeating elements like 'h1' or classes with common names like '.title' you can do everything you need in the scope of a well-defined block, without having side effects. This [article from Cube CSS](https://piccalil.li/cube-css/block/) describes the methodology quite well. ## Positioning But also from the old stylus framework [nib](https://github.com/stylus/nib) I took some things over, like the shortcuts for positioning elements: ```stylus .header absolute top left width 100% ``` ## File Size Due to its design _twindy_ is already very economical with definitions. But there is of course more to it: 1. use [Purge CSS](https://purgecss.com/) to remove unused styles 2. apply a CSS minifier, such as [clean-css](https://github.com/jakubpawlowicz/clean-css) --- ## Layout Shortcuts - `-x` and `-y` set stacked layout using `display:flex` with the respective direction. - `-grow` lets such stack items consume the availble space. `-fix` is the counter part but usually implicit. - `-center` to position the content vertically and horizontally in the middle of the element. - `-scroll` enables vertical scrolling inside the element. - `-gap` leaves space between contained elements. The space is `var(--space-s, px(8))` - `-sep` gives the element the gap with, usefull to have explicit space. - `-dots` will set `text-overflow: ellipsis` correctly to show dots on text overflow. --- ## Inspiring 3rd Party Work - The elegant and powerful [Stylus](https://stylus-lang.com/) - The awesome [TailwindCSS](https://tailwindcss.com/) - The classic Stylus CSS framework [nib](https://github.com/stylus/nib)