diff --git a/canon-docs/public/css-classname-structure.png b/canon-docs/public/css-classname-structure.png new file mode 100644 index 0000000000..df9894ff2b Binary files /dev/null and b/canon-docs/public/css-classname-structure.png differ diff --git a/canon-docs/src/app/(docs)/theme/theming/page.mdx b/canon-docs/src/app/(docs)/theme/theming/page.mdx index e3fc42da44..665755c268 100644 --- a/canon-docs/src/app/(docs)/theme/theming/page.mdx +++ b/canon-docs/src/app/(docs)/theme/theming/page.mdx @@ -29,8 +29,100 @@ Here's an example of how your theme.css file should look like: +## CSS class name structure + +All Canon components come with a set of CSS classes that you can use to style them. To make it +easier to identify the class name you can use, we use a specific structure for the class names. + + + +Every component has a unique prefix `.canon-` followed by the component name. Component props +are represented using the `data-` attribute. That way, class names are easily identifiable. + ## Available CSS variables +### Base colors + +These colors are used for special purposes like ring, scrollbar, ... + + + + + Prop + Description + + + + + + --canon-black + + + Pure black color. This one should be the same in light and dark themes. + + + + + --canon-white + + + Pure white color. This one should be the same in light and dark themes. + + + + + --canon-gray-1 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-2 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-3 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-4 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-5 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-6 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-7 + + You can use these mostly for backgrounds colors. + + + + --canon-gray-8 + + You can use these mostly for backgrounds colors. + + + + ### Core background colors These colors are used for the background of your application. We are mostly using for now a @@ -57,98 +149,60 @@ color of your app. Use for any panels or elevated surfaces. - - - -### Component background colors - -These colors are meants for interactive components like buttons, callout avatar, chips, ... -We have two main level of background you can customise. The accent one is mostly used as a primary option -for interactive components. The tint one is used for secondary components like callouts, avatars, ... - - - - - Prop - Description - - - - --canon-bg-accent + --canon-bg-surface-2 - Used mostly for primary interactive components. + Use for any panels or elevated surfaces. - --canon-bg-accent-hover - - - Used for interactive components when they are hovered. + --canon-bg-solid + Used for solid background colors. - --canon-bg-accent-focus - - - Used for interactive components when they are in focus. + --canon-bg-solid-hover + Used for solid background colors when hovered. - --canon-bg-accent-disabled + --canon-bg-solid-pressed + Used for solid background colors when pressed. + + - Used for interactive components when they are disabled. + --canon-bg-solid-disabled + Used for solid background colors when disabled. --canon-bg-tint - Used for secondary interactive components. + Used for tint background colors. --canon-bg-tint-hover - - Used for interactive components when they are hovered. - + Used for tint background colors when hovered. --canon-bg-tint-focus - - Used for interactive components when they are active. - + Used for tint background colors when active. --canon-bg-tint-disabled - - Used for interactive components when they are disabled. - + Used for tint background colors when disabled. - - - -### Status background colors - -These backgrounds are intended for non-interactive elements to visually convey a specific state. - - - - - Prop - Description - - - --canon-bg-danger @@ -189,7 +243,7 @@ are prefixed with `fg` to make it easier to identify. --canon-fg-primary - It should be used on top of `--canon-bg-app` or `--canon-bg-surface-1`. + It should be used on top of main background surfaces. @@ -197,7 +251,7 @@ are prefixed with `fg` to make it easier to identify. --canon-fg-secondary - It should be used on top of `--canon-bg-app` or `--canon-bg-surface-1`. + It should be used on top of main background surfaces. @@ -205,7 +259,7 @@ are prefixed with `fg` to make it easier to identify. --canon-fg-link - It should be used on top of `--canon-bg-app` or `--canon-bg-surface-1`. + It should be used on top of main background surfaces. @@ -213,38 +267,64 @@ are prefixed with `fg` to make it easier to identify. --canon-fg-link-hover - It should be used on top of `--canon-bg-app` or `--canon-bg-surface-1`. + It should be used on top of main background surfaces. - --canon-fg-accent + --canon-fg-disabled + + + It should be used on top of main background surfaces. + + + + + --canon-fg-solid + + + It should be used on top of solid background colors. - It should be used on top of `--canon-bg-accent`. --canon-fg-tint - It should be used on top of `--canon-bg-tint`. + + It should be used on top of tint background colors. + + + + + --canon-fg-tint-disabled + + + It should be used on top of tint background colors when disabled. + --canon-fg-danger - It should be used on top of `--canon-bg-danger`. + + It should be used on top of danger background colors. + --canon-fg-warning - It should be used on top of `--canon-bg-warning`. + + It should be used on top of warning background colors. + --canon-fg-success - It should be used on top of `--canon-bg-success`. + + It should be used on top of success background colors. + @@ -288,21 +368,9 @@ low contrast to help as a separator with the different background colors. - --canon-border-tint + --canon-border-disabled - It should be used on top of `--canon-bg-tint`. - - - - --canon-border-tint-hover - - Used when the component is hovered. - - - - --canon-border-tint-focus - - Used when the component is in focus. + Used when the component is disabled. @@ -325,7 +393,40 @@ low contrast to help as a separator with the different background colors. -## Font families +### Special colors + +These colors are used for special purposes like ring, scrollbar, ... + + + + + Prop + Description + + + + + + --canon-ring + + The color of the ring. + + + + --canon-scrollbar + + The color of the scrollbar. + + + + --canon-scrollbar-thumb + + The color of the scrollbar thumb. + + + + +### Font families We have two fonts that we use across Canon. The first one is the sans-serif font that we use for the body of the application. The second one is the @@ -354,9 +455,9 @@ monospace font that we use for code blocks and tables. -## Font weights +### Font weights -We have two font weights that we use across Canon. Regular or Bold +We have two font weights that we use across Canon. Regular or Bold. @@ -381,7 +482,7 @@ We have two font weights that we use across Canon. Regular or Bold -## Spacing +### Spacing We built a spacing system based on a single value `--canon-space`. This value is used to calculate the spacing for all the components. By default if you would like to @@ -520,18 +621,9 @@ tokens for pretty much each spacing properties like padding, margin, gaps, ... -### Radius (Work in progress) +### Radius -Our radius system is a little bit different from spacing as we use a factor to calculate the radius values. -Under the hood different components uses different radius values. For example, button can be set to have full radius -while a checkbox will have to remain a square. - -Here are the different radius factor we recommend to use - -- None: `0` -- Small: `0.75` -- Medium: `1` -- Large: `1.5` +We use a radius system to make sure that the components have a consistent look and feel. @@ -543,9 +635,59 @@ Here are the different radius factor we recommend to use - --canon-radius-factor + --canon-radius-1 + + + The radius of the component. Default value is `0.125rem`. + + + + + --canon-radius-2 + + + The radius of the component. Default value is `0.25rem`. + + + + + --canon-radius-3 + + + The radius of the component. Default value is `0.5rem`. + + + + + --canon-radius-4 + + + The radius of the component. Default value is `0.75rem`. + + + + + --canon-radius-5 + + + The radius of the component. Default value is `1rem`. + + + + + --canon-radius-6 + + + The radius of the component. Default value is `1.25rem`. + + + + + --canon-radius-full + + + The radius of the component. Default value is `9999px`. - By default the value is set to medium `1`.