diff --git a/canon-docs/src/app/(docs)/components/button/page.mdx b/canon-docs/src/app/(docs)/components/button/page.mdx
index c35c4888f3..e0b0a89f31 100644
--- a/canon-docs/src/app/(docs)/components/button/page.mdx
+++ b/canon-docs/src/app/(docs)/components/button/page.mdx
@@ -167,9 +167,7 @@ Here's a view when buttons are responsive.
py={4}
open
preview={}
- code={``}
+ code={``}
/>
diff --git a/canon-docs/src/app/(docs)/components/heading/page.mdx b/canon-docs/src/app/(docs)/components/heading/page.mdx
index 4e3b0aa46c..e843e131ce 100644
--- a/canon-docs/src/app/(docs)/components/heading/page.mdx
+++ b/canon-docs/src/app/(docs)/components/heading/page.mdx
@@ -93,5 +93,7 @@ on the screen size.
py={4}
open
preview={}
- code={`Responsive`}
+ code={`
+ Responsive heading
+ `}
/>
diff --git a/canon-docs/src/app/(docs)/components/table/page.mdx b/canon-docs/src/app/(docs)/components/table/page.mdx
index f91505acf6..f169bcd7f9 100644
--- a/canon-docs/src/app/(docs)/components/table/page.mdx
+++ b/canon-docs/src/app/(docs)/components/table/page.mdx
@@ -1 +1 @@
-# Table
+# Table (Coming soon)
diff --git a/canon-docs/src/app/(docs)/components/text/page.mdx b/canon-docs/src/app/(docs)/components/text/page.mdx
index 79f9f96a6b..6d96fc5da3 100644
--- a/canon-docs/src/app/(docs)/components/text/page.mdx
+++ b/canon-docs/src/app/(docs)/components/text/page.mdx
@@ -137,5 +137,7 @@ on the screen size.
}
- code={`Responsive`}
+ code={`
+ Responsive text
+ `}
/>
diff --git a/canon-docs/src/app/(docs)/theme/theming/page.mdx b/canon-docs/src/app/(docs)/theme/theming/page.mdx
index 3a16b533e9..4cb03859f9 100644
--- a/canon-docs/src/app/(docs)/theme/theming/page.mdx
+++ b/canon-docs/src/app/(docs)/theme/theming/page.mdx
@@ -1,67 +1,70 @@
import { CodeBlock } from '@/components/CodeBlock';
import * as Table from '@/components/Table';
import { Chip } from '@/components/Chip';
+import { customTheme } from '@/snippets/_snippets';
# Theming
-Backstage ships with a default theme with a light and dark mode variant. The
-themes are provided as a part of the `@backstage/canon` package, which also
-includes utilities for customizing the default theme, or creating completely
-new themes.
+Canon's theming is built entirely on CSS, without relying on any CSS-in-JS libraries.
+At its core, it provides a solid default theme that is easily customizable using a
+comprehensive set of CSS variables. Additionally, it enables anyone to adapt the design
+to their specific needs. Each component comes with fixed class names, making customization
+even more straightforward.
## Light & Dark modes
-By default we are supporting both light and dark modes. Each user can opt to
-choose what theme they want to use or to use their system decide what theme to
-use. If you want to create your own theme, you will have to set both light and
-dark themes following the instructions below. If you only set one of them, the
-other mode will fallback to the default theme.
+By default, Canon supports both light and dark modes using the `data-theme` attribute.
+The light theme is applied by default if no `data-theme` attribute is specified. To create
+a custom theme, you'll need to define both light and dark modes as outlined below. If
+only one mode is defined, the other will fall back to the default theme.
## How to create your own theme
-To create your own theme, you will have to define the variables below. To do
-that, create a theme.css file and import it in your application. Here's an
-example below on how to set your light and dark mode.
+In our [started guide](/), we ask you to import two css files. The `core.css` file includes
+the default set of variables. We recommend to keep this file in place and add your own theme
+on top of it. `core.css` also include an opinionated reset. If you decided to remove `core.css`
+you will have to provide your own reset css.
-
+Here's an example of how your theme.css file should look like:
-## Colors
+
-We provide a set of generic colours tokens that we use across Canon. By
-changing these colours you can easily change the look and feel of your
-application to match your brand.
+## Available CSS variables
+
+### Core background colors
+
+These colors are used for the background of your application. We are mostly using for now a
+single elevated background for panels. `--canon-bg` should mostly use as the main background
+color of your app.
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-bg
+
+ The background color of your Backstage instance.
+
+
+
+ --canon-bg-elevated
+
+ 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, ...
@@ -75,54 +78,254 @@ application to match your brand.
--canon-bg-accent
- The accent color for the theme.
+ Used mostly for primary interactive components.
- --canon-bg
+ --canon-bg-accent-hover
+
+
+ Used for interactive components when they are hovered.
- The background color for the theme.
- --canon-bg-elevated
+ --canon-bg-accent-focus
+
+
+ Used for interactive components when they are in focus.
- The first surface color for the theme.
- --canon-bg
+ --canon-bg-accent-disabled
+
+
+ Used for interactive components when they are disabled.
- The second surface color for the theme.
- --canon-outline
+ --canon-bg-tint
- The outline color for the theme.
+ Used for secondary interactive components.
- --canon-outline-focus
+ --canon-bg-tint-hover
+
+
+ Used for interactive components when they are hovered.
- The outline focus color for the theme.
- --canon-text-primary
+ --canon-bg-tint-focus
+
+
+ Used for interactive components when they are active.
- The primary text color for the theme.
- --canon-text-secondary
+ --canon-bg-tint-disabled
+
+
+ Used for interactive components when they are disabled.
- The secondary text color for the theme.
-## Typography
+### Status background colors
+
+These backgrounds are intended for non-interactive elements to visually convey a specific state.
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-bg-danger
+
+ Used to show errors informations.
+
+
+
+ --canon-bg-warning
+
+ Used to show warnings informations.
+
+
+
+ --canon-bg-success
+
+ Used to show success informations.
+
+
+
+
+### Foreground colors
+
+Foreground colours are meant to work in pair with a background colours. Typeically this would work
+for icons, texts, shapes, ... Use a matching name to know what foreground color to use. These colors
+are prefixed with `fg` to make it easier to identify.
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-fg-text-primary
+
+
+ It should be used on top of `--canon-bg-app` or `--canon-bg-elevated`.
+
+
+
+
+ --canon-fg-text-secondary
+
+
+ It should be used on top of `--canon-bg-app` or `--canon-bg-elevated`.
+
+
+
+
+ --canon-fg-link
+
+
+ It should be used on top of `--canon-bg-app` or `--canon-bg-elevated`.
+
+
+
+
+ --canon-fg-link-hover
+
+
+ It should be used on top of `--canon-bg-app` or `--canon-bg-elevated`.
+
+
+
+
+ --canon-fg-accent
+
+ It should be used on top of `--canon-bg-accent`.
+
+
+
+ --canon-fg-tint
+
+ It should be used on top of `--canon-bg-tint`.
+
+
+
+ --canon-fg-danger
+
+ It should be used on top of `--canon-bg-danger`.
+
+
+
+ --canon-fg-warning
+
+ It should be used on top of `--canon-bg-warning`.
+
+
+
+ --canon-fg-success
+
+ It should be used on top of `--canon-bg-success`.
+
+
+
+
+### Border colors
+
+These border colors are mostly meant to be used as borders on top of any components with
+low contrast to help as a separator with the different background colors.
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-border
+
+
+ It should be used on top of `--canon-bg-elevated`.
+
+
+
+
+ --canon-border-hover
+
+
+ Used when the component is interactive and hovered.
+
+
+
+
+ --canon-border-focus
+
+
+ Used when the component is interactive and focused.
+
+
+
+
+ --canon-border-tint
+
+ 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.
+
+
+
+ --canon-border-danger
+
+ It should be used on top of `--canon-bg-danger`.
+
+
+
+ --canon-border-warning
+
+ It should be used on top of `--canon-bg-warning`.
+
+
+
+ --canon-border-success
+
+ It should be used on top of `--canon-bg-success`.
+
+
+
+
+## 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
@@ -151,12 +354,9 @@ monospace font that we use for code blocks and tables.
-## Spacing
+## Font weights
-Our default spacing system is made to work in most scenarios. We have 7 scale
-values from `xxs` to `xxl`. We use the values on padding and margin in our
-layout components mostly. If you prefer to use a different spacing system, you
-can do that by changing the values below.
+We have two font weights that we use across Canon. Regular or Bold
@@ -168,53 +368,184 @@ can do that by changing the values below.
- --canon-space-unit
-
-
- The base unit for the spacing system. Default value is `1em`
+ --canon-font-weight-regular
+ The regular font weight for the theme.
- --canon-space-xxs
+ --canon-font-weight-bold
- Default value is `0.25 x space unit`
-
-
-
- --canon-space-xs
-
- Default value is `0.5 x space unit`
-
-
-
- --canon-space-sm
-
- Default value is `0.75 x space unit`
-
-
-
- --canon-space-md
-
- Default value is `1.25 x space unit`
-
-
-
- --canon-space-lg
-
- Default value is `2 x space unit`
-
-
-
- --canon-space-xl
-
- Default value is `3.25 x space unit`
-
-
-
- --canon-space-xxl
-
- Default value is `5.25 x space unit`
+ The bold font weight for the theme.
+
+
+
+
+## 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
+increase or decrease the spacing between your components you can do it simply by updating
+`--canon-space` and it will apply to all spacing values.
+
+`--canon-space` is not used directly in any components but serve as an easy way to
+calculate the other values.
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-space
+
+
+ The base unit for the spacing system. Default value is `0.25rem`.
+
+
+
+
+
+Below is the list of all spacing values you can use in your application. We use these
+tokens for pretty much each spacing properties like padding, margin, gaps, ...
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-space-0_5
+
+ Base unit (`--canon-space`) times 0.5.
+
+
+
+ --canon-space-1
+
+ Base unit (`--canon-space`).
+
+
+
+ --canon-space-1_5
+
+ Base unit (`--canon-space`) times 1.5.
+
+
+
+ --canon-space-2
+
+ Base unit (`--canon-space`) times 2.
+
+
+
+ --canon-space-3
+
+ Base unit (`--canon-space`) times 3.
+
+
+
+ --canon-space-4
+
+ Base unit (`--canon-space`) times 4.
+
+
+
+ --canon-space-5
+
+ Base unit (`--canon-space`) times 5.
+
+
+
+ --canon-space-6
+
+ Base unit (`--canon-space`) times 6.
+
+
+
+ --canon-space-7
+
+ Base unit (`--canon-space`) times 7.
+
+
+
+ --canon-space-8
+
+ Base unit (`--canon-space`) times 8.
+
+
+
+ --canon-space-9
+
+ Base unit (`--canon-space`) times 9.
+
+
+
+ --canon-space-10
+
+ Base unit (`--canon-space`) times 10.
+
+
+
+ --canon-space-11
+
+ Base unit (`--canon-space`) times 11.
+
+
+
+ --canon-space-12
+
+ Base unit (`--canon-space`) times 12.
+
+
+
+ --canon-space-13
+
+ Base unit (`--canon-space`) times 13.
+
+
+
+ --canon-space-14
+
+ Base unit (`--canon-space`) times 14.
+
+
+
+
+### Radius (Work in progress)
+
+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`
+
+
+
+
+ Prop
+ Description
+
+
+
+
+
+ --canon-radius-factor
+
+ By default the value is set to medium `1`.
diff --git a/canon-docs/src/app/globals.css b/canon-docs/src/app/globals.css
index 71f7b8be9c..343f23a38f 100644
--- a/canon-docs/src/app/globals.css
+++ b/canon-docs/src/app/globals.css
@@ -2,7 +2,7 @@ body {
display: flex;
flex-direction: row;
background-color: var(--canon-bg);
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
transition: background-color 0.2s ease-in-out;
--docs-font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
diff --git a/canon-docs/src/app/page.module.css b/canon-docs/src/app/page.module.css
index b0fbed71c1..bc28185d48 100644
--- a/canon-docs/src/app/page.module.css
+++ b/canon-docs/src/app/page.module.css
@@ -17,7 +17,7 @@
}
.page p {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
font-size: 1rem;
line-height: 1.5rem;
margin-top: 0;
diff --git a/canon-docs/src/components/CodeBlock/styles.module.css b/canon-docs/src/components/CodeBlock/styles.module.css
index b5f005f962..966b3ff72b 100644
--- a/canon-docs/src/components/CodeBlock/styles.module.css
+++ b/canon-docs/src/components/CodeBlock/styles.module.css
@@ -18,7 +18,7 @@
border-bottom: 1px solid var(--canon-border);
padding: 12px 20px;
font-size: 0.875rem;
- color: var(--canon-text-secondary);
+ color: var(--canon-fg-text-secondary);
}
.code {
diff --git a/canon-docs/src/components/CustomTheme/styles.module.css b/canon-docs/src/components/CustomTheme/styles.module.css
index fdb2d00fba..ac7d7f36f1 100644
--- a/canon-docs/src/components/CustomTheme/styles.module.css
+++ b/canon-docs/src/components/CustomTheme/styles.module.css
@@ -66,7 +66,7 @@
padding: 0 8px;
color: #fff;
background-color: var(--canon-bg);
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
transition: background-color 0.2s ease-in-out;
border-radius: 0.25rem;
cursor: pointer;
diff --git a/canon-docs/src/components/HeadlessBanners/styles.module.css b/canon-docs/src/components/HeadlessBanners/styles.module.css
index 1353f150bb..4817ab569f 100644
--- a/canon-docs/src/components/HeadlessBanners/styles.module.css
+++ b/canon-docs/src/components/HeadlessBanners/styles.module.css
@@ -10,7 +10,7 @@
}
.icon path {
- fill: var(--canon-text-primary);
+ fill: var(--canon-fg-text-primary);
}
.content {
@@ -37,6 +37,6 @@
border-radius: 100px;
margin-top: var(--canon-space-3);
font-size: var(--canon-font-size-3);
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
gap: var(--canon-space-2);
}
diff --git a/canon-docs/src/components/Sidebar/Sidebar.module.css b/canon-docs/src/components/Sidebar/Sidebar.module.css
index 43f1681812..feb9f8bea3 100644
--- a/canon-docs/src/components/Sidebar/Sidebar.module.css
+++ b/canon-docs/src/components/Sidebar/Sidebar.module.css
@@ -10,7 +10,7 @@
left: 0;
width: 300px;
height: 100vh;
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
background-color: var(--canon-bg-elevated);
border-right: 1px solid var(--canon-border);
padding-left: 20px;
@@ -26,7 +26,7 @@
}
.logo path {
- fill: var(--canon-text-primary);
+ fill: var(--canon-fg-text-primary);
}
.menu {
@@ -75,11 +75,11 @@
font-family: var(--docs-font);
font-size: var(--canon-font-size-3);
font-weight: var(--canon-font-weight-regular);
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
}
.lineStatus {
font-family: var(--docs-font);
font-size: var(--canon-font-size-3);
- color: var(--canon-text-secondary);
+ color: var(--canon-fg-text-secondary);
}
diff --git a/canon-docs/src/components/Table/styles.module.css b/canon-docs/src/components/Table/styles.module.css
index 7ac48709eb..9b67b25025 100644
--- a/canon-docs/src/components/Table/styles.module.css
+++ b/canon-docs/src/components/Table/styles.module.css
@@ -38,7 +38,7 @@
transition: background-color 0.2s ease-in-out;
& p {
- margin: 0;
+ margin: 0 !important;
}
}
diff --git a/canon-docs/src/components/Tabs/parts.tsx b/canon-docs/src/components/Tabs/parts.tsx
index e0ae296136..41dfadf2ea 100644
--- a/canon-docs/src/components/Tabs/parts.tsx
+++ b/canon-docs/src/components/Tabs/parts.tsx
@@ -34,8 +34,8 @@ export const Tab = (props: React.ComponentProps) => (
{...rest}
style={{
color: state.selected
- ? 'var(--canon-text-primary)'
- : 'var(--canon-text-secondary)',
+ ? 'var(--canon-fg-text-primary)'
+ : 'var(--canon-fg-text-secondary)',
}}
>
{children}
diff --git a/canon-docs/src/components/Tabs/styles.module.css b/canon-docs/src/components/Tabs/styles.module.css
index 8d898fd727..137bc7470d 100644
--- a/canon-docs/src/components/Tabs/styles.module.css
+++ b/canon-docs/src/components/Tabs/styles.module.css
@@ -22,6 +22,6 @@
left: var(--active-tab-left);
width: var(--active-tab-width);
height: 1px;
- background-color: var(--canon-text-primary);
+ background-color: var(--canon-fg-text-primary);
transition: all 0.2s ease-in-out;
}
diff --git a/canon-docs/src/components/Toolbar/nav.module.css b/canon-docs/src/components/Toolbar/nav.module.css
index 90730b1403..526d7bf918 100644
--- a/canon-docs/src/components/Toolbar/nav.module.css
+++ b/canon-docs/src/components/Toolbar/nav.module.css
@@ -27,21 +27,21 @@
all: unset;
height: 60px;
font-family: var(--docs-font);
- color: var(--canon-text-secondary);
+ color: var(--canon-fg-text-secondary);
font-size: var(--canon-font-size-3);
font-weight: var(--canon-font-weight-bold);
cursor: pointer;
transition: color 0.2s ease-in-out;
&:hover {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
}
&[data-selected] {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
& p {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
}
}
@@ -60,7 +60,7 @@
}
.tab p {
- color: var(--canon-text-secondary) !important;
+ color: var(--canon-fg-text-secondary) !important;
}
.indicator {
@@ -72,7 +72,7 @@
width: var(--active-tab-width);
height: 1px;
border-radius: 0.25rem;
- background-color: var(--canon-text-primary);
+ background-color: var(--canon-fg-text-primary);
transition-property: translate, width, background-color;
transition-duration: 200ms;
transition-timing-function: ease-in-out;
diff --git a/canon-docs/src/components/Toolbar/theme.module.css b/canon-docs/src/components/Toolbar/theme.module.css
index 564f5be4ca..ac3701541f 100644
--- a/canon-docs/src/components/Toolbar/theme.module.css
+++ b/canon-docs/src/components/Toolbar/theme.module.css
@@ -29,23 +29,23 @@
outline: 0;
background: none;
appearance: none;
- color: var(--canon-text-secondary);
+ color: var(--canon-fg-text-secondary);
user-select: none;
height: 2rem;
flex: 1;
cursor: pointer;
&[data-selected] {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
& p {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
}
}
@media (hover: hover) {
&:hover {
- color: var(--canon-text-primary);
+ color: var(--canon-fg-text-primary);
}
}
@@ -64,7 +64,7 @@
}
.tab p {
- color: var(--canon-text-secondary) !important;
+ color: var(--canon-fg-text-secondary) !important;
}
.indicator {
diff --git a/canon-docs/src/mdx-components.tsx b/canon-docs/src/mdx-components.tsx
index 85df3315c4..182eaa03b4 100644
--- a/canon-docs/src/mdx-components.tsx
+++ b/canon-docs/src/mdx-components.tsx
@@ -62,10 +62,13 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
),
a: ({ children, href }) => (
-
+
{children as ReactNode}
),
+ li: ({ children }) => (
+