Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs tidy up #68

Merged
merged 1 commit into from
Jun 4, 2024
Merged

Docs tidy up #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/Theming.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,21 @@ import * as ThemingStories from './recipes/Theming.stories.ts'

# Theming

Diamond UI supports component theming, but does not provide any production ready themes out of the box.
Diamond UI supports component theming but provides no production-ready themes out of the box.

All themes are based around a core set of variables.
All themes are based on a core set of variables.

<Source code={theme} language='css' />

These can be overridden by setting the `:root` CSS variables to create a base theme, as well as creating theme classes which can wrap components or groups of components.
These can be overridden by setting the `:root` CSS variables to create a base theme and creating theme classes that can wrap components or groups of components.

This setup allows consuming apps to create an infinite number of themes to apply to components, as well as allowing those themes to be applied at different levels within a page or app, rather than requiring them to be global.
This setup allows consuming apps to create an infinite number of themes to apply to components and apply those themes at different levels within a page or app, rather than requiring them to be global.

## Examples

Diamond UI optionally includes an example set of 3 basic themes: light, medium and dark. The theme tokens are set on the `:root` and then applied to the base theme via classes, such as `.diamond-theme-dark`.

Components that support theming will apply the base theme tokens, such as setting background to `--diamond-theme-background`.
Components that support theming will apply the base theme tokens, such as setting the background to `--diamond-theme-background`.

<Source code={themes} language='css' />

Expand All @@ -33,6 +33,6 @@ Here is an example of 3 cards wrapped in the demo theme classes, which then appl

## Recommended themes

In most projects we recommend a base set of themes for light, medium and dark.
In most projects, we recommend a base set of themes for light, medium and dark.

We would also recommend creating some state based themes for states such as info, success, warning and error.
14 changes: 7 additions & 7 deletions docs/WhyWeDontUseSass.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,31 @@ import { Meta } from '@storybook/blocks';

Diamond UI doesn't use Sass. It's written in pure CSS (with a tiny sprinkle of PostCSS to clean up the imports) and outputs pure CSS.

Sass has been the default CSS preprocessor for a long time and it felt like the leap to not using it is worth acknowledging and explaining why.
Sass has been the default CSS preprocessor for a long time and the leap to not using it is worth acknowledging and explaining why.

## What do we get from Sass?

Our favourite parts of Sass are variables, imports, mixins, functions (especially colour manipulation), loops and variable maps. With the recent improvements in modern CSS techniques and browser support coming to fruition, we can replicate most of these in pure CSS.

### Variables
CSS variables (custom properties) are _awesome_. Whilst Sass variables are pre-compiled into hardcoded static values, CSS variables are evaluated at runtime, opening up a wide range of new and interesting techniques for application.
CSS variables (custom properties) are awesome. Whilst Sass variables are pre-compiled into hardcoded static values, CSS variables are evaluated at runtime, opening up a wide range of new and interesting techniques for application.

### Imports
We've used standard `@import` syntax from CSS and, during the production build, used PostCSS import and importGlob to inline all the base CSS. This method gives the same effect as using Sass imports.

### Functions
CSS now has a wide array of functions that can be used to achieve what we would previously have used Sass functions for. `color-mix` and `calc` seem to cover the majority of simple UI manipulations we need in Diamond.
CSS now has a wide array of functions that can be used to achieve what we would have used Sass functions for. `color-mix` and `calc` seems to cover most of the simple UI manipulations we need in Diamond.

### Loops
We use loops in Sass primarily to generate swathes of grid column CSS or lots of modifiers on a component around a single prop, like alignment. The upcoming ability to use `attr` as a value, or within a `calc` will likely bypass the need for these loops so we have decided to temporarily write them out manually until they can be upgraded.
We use loops in Sass primarily to generate swathes of grid column CSS or many modifiers on a component around a single prop, like alignment. The upcoming ability to use `attr` as a value, or within a `calc` will likely bypass the need for these loops so we have decided to temporarily write them out manually until they can be upgraded.

### CSS modules
The nessessity for CSS module scoping has been bypassed with the use of Shadow DOM. We have also used BEM for a number of years, which negates the need to involve Javascript in CSS scope.
The necessity for CSS module scoping has been bypassed with Shadow DOM. We have also used BEM for several years, which negates the need to involve JavaScript in CSS scope.

### Mixins and variable maps
These last two do not currently have an equivalent in native CSS, but it feels like, with the new techniques available using CSS variables and the soon to be available `attr` values and container style queries, they are not as nessessary in modern CSS development. We almost had native CSS misings with the `@apply` functionality, but this has been abandoned. In rare cases, we can use Lit's shared styles to share CSS across components.
These last two do not currently have an equivalent in native CSS. Still, it feels like, with the new techniques available using CSS variables and the soon-to-be-available `attr` values and container style queries, they are not as necessary in modern CSS development. We almost had native CSS mixins with the `@apply` functionality, but this has been abandoned. In rare cases, we can use Lit's shared styles to share CSS across components.

## Embracing the native web
These Diamond UI components are part of a conscious move by the team to embrace the native web. We're _tired_ of upgrading frameworks and dependencies and the less we can get away with, the better. Many people don't use Sass and we don't want to force another dependency and longer build times on them, however small they are.
These Diamond UI components are part of a conscious move by the team to embrace the native web. We're tired of upgrading frameworks and dependencies and the less we can get away with, the better. Many people don't use Sass and we want to avoid forcing another dependency and longer build times on them, however small they are.

The CSS in Diamond will stay native for as long as possible.
Loading