diff --git a/microsite-canon/app/components/[slug]/page.tsx b/microsite-canon/app/components/[slug]/page.tsx index 4a2c1990e7..53d2030504 100644 --- a/microsite-canon/app/components/[slug]/page.tsx +++ b/microsite-canon/app/components/[slug]/page.tsx @@ -1,4 +1,4 @@ -import { components } from '@/data'; +import { components } from '@/utils/data'; import { notFound } from 'next/navigation'; import fs from 'fs'; import path from 'path'; diff --git a/microsite-canon/app/core-concepts/[slug]/page.tsx b/microsite-canon/app/core-concepts/[slug]/page.tsx index ae67382267..35be6dc2c9 100644 --- a/microsite-canon/app/core-concepts/[slug]/page.tsx +++ b/microsite-canon/app/core-concepts/[slug]/page.tsx @@ -1,4 +1,4 @@ -import { coreConcepts } from '@/data'; +import { coreConcepts } from '@/utils/data'; import { notFound } from 'next/navigation'; import fs from 'fs'; import path from 'path'; diff --git a/microsite-canon/components/Sidebar/index.tsx b/microsite-canon/components/Sidebar/index.tsx index 74aef01982..6cd58a26be 100644 --- a/microsite-canon/components/Sidebar/index.tsx +++ b/microsite-canon/components/Sidebar/index.tsx @@ -2,7 +2,7 @@ import styles from './Sidebar.module.css'; import Image from 'next/image'; import { TabsVersion, TabsTheme, TabsPages } from '../Tabs'; import Link from 'next/link'; -import { components, coreConcepts } from '@/data'; +import { components, coreConcepts } from '@/utils/data'; export const Sidebar = () => { return ( diff --git a/microsite-canon/content/checkbox.mdx b/microsite-canon/content/checkbox.mdx new file mode 100644 index 0000000000..f71faeca9c --- /dev/null +++ b/microsite-canon/content/checkbox.mdx @@ -0,0 +1,62 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; + +# Checkbox + +A checkbox component that can be used to trigger actions. + + + + +`} /> + +## API reference + + void", + responsive: false, + }, + disabled: { + type: 'boolean', + responsive: false, + }, + required: { + type: 'boolean', + responsive: false, + }, + name: { + type: 'string', + responsive: false, + }, + value: { + type: 'string', + responsive: false, + }, + className: { + type: 'string', + responsive: false, + }, + style: { + type: 'CSSProperties', + responsive: false, + }, + }} +/> diff --git a/microsite-canon/content/container.mdx b/microsite-canon/content/container.mdx new file mode 100644 index 0000000000..03abe77525 --- /dev/null +++ b/microsite-canon/content/container.mdx @@ -0,0 +1,85 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { spacePropsList } from '../utils/spaceProps'; + +# Container + +The container component let you use our default max-width and center the +content on the page. + +Hello World! +`} /> + +## API reference + + + +## Examples + +### Simple + +A simple example of how to use the Container component. + + + Hello World + Hello World + Hello World +`} +/> + +### Responsive padding & margin + +The Container component also supports responsive values, making it easy to +create responsive designs. + + + Hello World + Hello World + Hello World +`} +/> diff --git a/microsite-canon/content/grid.mdx b/microsite-canon/content/grid.mdx new file mode 100644 index 0000000000..10b7f2e96e --- /dev/null +++ b/microsite-canon/content/grid.mdx @@ -0,0 +1,177 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { spacePropsList } from '../utils/spaceProps'; + +# Grid + +A layout component that helps to create simple column-based layouts as well as +more complex ones. + + + Hello World + +`} /> + +## API reference + +### Grid + +This is the grid container component. It will help to define the number of +columns that will be used in the grid. You can also define the gap between the +columns. All values are responsive. + + + +The grid component also accepts all the spacing props from the Box component. + + + +### Grid.Item + +If you need more control over the columns, you can use the grid item +component. This will give you access to `rowSpan`, `colSpan`, `start` and +`end`. All values are responsive. This component is optional, you can use any +elements directly if you prefer. + + + +## Examples + +### Simple grid + +A simple grid with 3 columns and a gap of md. + + + Hello World + Hello World + Hello World + +`} +/> + +### Complex grid + +You can also use the grid item to create more complex layouts. In this example +the first column will span 1 column and the second column will span 2 columns. + + + + Hello World + + + Hello World + + +`} +/> + +### Mixing rows and columns + +The grid item component also supports the `rowSpan` prop, which allows you to +span multiple rows within the grid layout. In this example, the first item +will span 2 rows to achieve a dynamic and flexible grid structure. + + + + Hello World + + + Hello World + + + Hello World + + +`} +/> + +### Responsive grid + +The grid component also supports responsive values, making it easy to create +responsive designs. + + + + Hello World + + + Hello World + + +`} +/> + +### Start and End + +The start and end props can be used to position the item in the grid. + + + + Hello World + + +`} +/> diff --git a/microsite-canon/content/heading.mdx b/microsite-canon/content/heading.mdx new file mode 100644 index 0000000000..61b13c0d2f --- /dev/null +++ b/microsite-canon/content/heading.mdx @@ -0,0 +1,66 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; + +# Heading + +Headings are used to structure the content of your page. + + + +Hello World! +`} /> + +## API reference + + + +## Examples + +### All variants + +The `Heading` component has a `variant` prop that can be used to change the +appearance of the heading. + + + + + Display + Title 1 + Title 2 + Title 3 + Title 4 +`} +/> + +### Responsive + +You can also use the `variant` prop to change the appearance of the text based +on the screen size. + +Responsive`} +/> diff --git a/microsite-canon/content/icon.mdx b/microsite-canon/content/icon.mdx new file mode 100644 index 0000000000..ad4b1aa2fc --- /dev/null +++ b/microsite-canon/content/icon.mdx @@ -0,0 +1,39 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { icons } from '@backstage/canon'; + +# Icon + +Icons are used to represent an action or a state. + + + + +`} /> + +## API reference + + diff --git a/microsite-canon/content/inline.mdx b/microsite-canon/content/inline.mdx new file mode 100644 index 0000000000..ef078e8b27 --- /dev/null +++ b/microsite-canon/content/inline.mdx @@ -0,0 +1,104 @@ +import { Story } from '../components/Story'; +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { spacePropsList } from '../utils/spaceProps'; + +# Inline + +The Inline component is used to create a horizontal layout of elements. By +default it uses flex and flexWrap to make sure that your content always flows +responsively. + + + Hello World + Hello World + Hello World + +`} /> + +## API reference + + + +The grid component also accepts all the spacing props from the Box component. + + + +## Examples + +### Simple + +A simple example of how to use the Inline component. + + + Hello World + Hello World + Hello World +`} +/> + +### Responsive + +The Inline component also supports responsive values, making it easy to create +responsive designs. + + + Hello World + Hello World + Hello World +`} +/> + +### Align + +The Inline component also supports responsive alignment, making it easy to +create responsive designs. + + + Hello World + Hello World + Hello World +`} +/> + +### Align vertically + +The Inline component also supports responsive vertical alignment, making it +easy to create responsive designs. + + + Hello World + Hello World + Hello World +`} +/> diff --git a/microsite-canon/content/responsive.mdx b/microsite-canon/content/responsive.mdx new file mode 100644 index 0000000000..cdbd82533c --- /dev/null +++ b/microsite-canon/content/responsive.mdx @@ -0,0 +1,123 @@ +import * as Table from '@/components/Table'; +import { Chip } from '@/components/Chip'; +import { CodeBlock } from '@/components/CodeBlock'; + +# Responsive + +Canon is built on a responsive design system, meaning that the components are +designed to adapt to different screen sizes. By default we offer a set of +breakpoints that you can use to create responsive components. + +## Breakpoints + + + + + Breakpoint prefix + Minimum width + CSS + + + + + + xs + + + 0px + + + {`{ ... }`} + + + + + sm + + + 640px + + + {`@media (min-width: 640px) { ... }`} + + + + + md + + + 768px + + + {`@media (min-width: 768px) { ... }`} + + + + + lg + + + 1024px + + + {`@media (min-width: 1024px) { ... }`} + + + + + xl + + + 1280px + + + {`@media (min-width: 1280px) { ... }`} + + + + + 2xl + + + 1536px + + + {`@media (min-width: 1536px) { ... }`} + + + + + +## Responsive components + +Canon components are designed to be responsive, meaning that they will adapt +to different screen sizes. Not every component is responsive, but the ones +that are will have a prop to control the responsive behavior. + +The behaviour is the same for each component. For each prop, instead of adding +the value, you add an object with the value and the breakpoint prefix. + +Button + +// Responsive value + +`} /> + +## How to update breakpoints + +The set of keys are not to be changed, but you can update the minimum width of +each breakpoint in the theme provider. + +`} +/> diff --git a/microsite-canon/content/stack.mdx b/microsite-canon/content/stack.mdx new file mode 100644 index 0000000000..57059f7468 --- /dev/null +++ b/microsite-canon/content/stack.mdx @@ -0,0 +1,102 @@ +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { spacePropsList } from '../utils/spaceProps'; + +# Stack + +This is the stack container component. It will help to define the number of +columns that will be used in the grid. You can also define the gap between the +columns. All values are responsive. + + + Hello World + Hello World + Hello World + +`} /> + +## API reference + + + +The grid component also accepts all the spacing props from the Box component. + + + +## Common questions + +### Can I stack horizontally? + +The Stack component only allows for stacking elements vertically. If you want +to create a column layout, please use the Grid component. + + + Hello World + Hello World + Hello World + +`} +/> + +## Examples + +### Simple + +A simple example of how to use the Stack component. + + + Hello World + Hello World + Hello World +`} +/> + +### Responsive + +The Stack component also supports responsive values, making it easy to create +responsive designs. + + + Hello World + Hello World + Hello World +`} +/> + +### Align + +The Stack component also supports responsive alignment, making it easy to +create responsive designs. + + + Hello World + Hello World + Hello World +`} +/> diff --git a/microsite-canon/content/table.mdx b/microsite-canon/content/table.mdx new file mode 100644 index 0000000000..f91505acf6 --- /dev/null +++ b/microsite-canon/content/table.mdx @@ -0,0 +1 @@ +# Table diff --git a/microsite-canon/content/text.mdx b/microsite-canon/content/text.mdx new file mode 100644 index 0000000000..7c1579f523 --- /dev/null +++ b/microsite-canon/content/text.mdx @@ -0,0 +1,78 @@ +import { CodeBlock } from '../components/CodeBlock'; +import { PropsTable } from '../components/PropsTable'; +import { Story } from '../components/Story'; + +# Text + +The `Text` component is used to display content on your page. + + + +Hello World!`} /> + +## API reference + + + +## Examples + +### All variants + +The `Text` component has a `variant` prop that can be used to change the +appearance of the text. + + + Subtitle Lorem ipsum dolor sit amet consectetur... + Body Lorem ipsum dolor sit amet consectetur... + Caption Lorem ipsum dolor sit amet consectetur... + Label Lorem ipsum dolor sit amet consectetur... +`} +/> + +### All weights + +The `Text` component has a `weight` prop that can be used to change the +appearance of the text. + + + Regular Lorem ipsum dolor sit amet consectetur... + Bold Lorem ipsum dolor sit amet consectetur... +`} +/> + +### Responsive + +You can also use the `variant` prop to change the appearance of the text based +on the screen size. + +Responsive`} +/> diff --git a/microsite-canon/content/theming.mdx b/microsite-canon/content/theming.mdx new file mode 100644 index 0000000000..7f46ca4fb6 --- /dev/null +++ b/microsite-canon/content/theming.mdx @@ -0,0 +1,220 @@ +import { CodeBlock } from '@/components/CodeBlock'; +import * as Table from '@/components/Table'; +import { Chip } from '@/components/Chip'; + +# 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. + +## 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. + +## 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. + + + +## 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. + + + + + Prop + Description + + + + + + --canon-accent + + The accent color for the theme. + + + + --canon-bg + + The background color for the theme. + + + + --canon-surface-1 + + The first surface color for the theme. + + + + --canon-surface-2 + + The second surface color for the theme. + + + + --canon-outline + + The outline color for the theme. + + + + --canon-outline-focus + + The outline focus color for the theme. + + + + --canon-text-primary + + The primary text color for the theme. + + + + --canon-text-secondary + + The secondary text color for the theme. + + + + +## Typography + +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 +monospace font that we use for code blocks and tables. + + + + + Prop + Description + + + + + + --canon-font-regular + + The sans-serif font for the theme. + + + + --canon-font-mono + + The monospace font for the theme. + + + + +## Spacing + +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. + +{' '} + + + + Prop + Description + + + + + + --canon-space-unit + + + The base unit for the spacing system. Default value is `1em` + + + + + --canon-space-xxs + + 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` + + + diff --git a/microsite-canon/content/typography.mdx b/microsite-canon/content/typography.mdx new file mode 100644 index 0000000000..f353c2b3e9 --- /dev/null +++ b/microsite-canon/content/typography.mdx @@ -0,0 +1,28 @@ +import { Story } from '@/components/Story'; + +# Typography + +Canon offers a suite of typography components designed to seamlessly align +with the rest of your Backstage instance. While you can customize their +appearance to match your brand, the underlying API remains consistent and +unchanged. Each component is built on a responsive structure, allowing you to +define different typography values for various breakpoints. + +## Headings + +Headings are used to structure the content of your page. They are used to +create a hierarchy of information and to make the content more readable. The +best way to use add these headings to your page is to import the [Heading +component](?path=/docs/components-heading--docs). + + + +## Text + +Canon provides four distinct text variants, each offering different font sizes +carefully designed to cover the majority of use cases. These variants are +versatile and can be paired with regular and bold of font weights. You can use +the [Text component](?path=/docs/components-text--docs) to add text to your +page. + + diff --git a/microsite-canon/data.ts b/microsite-canon/data.ts deleted file mode 100644 index 251bee98eb..0000000000 --- a/microsite-canon/data.ts +++ /dev/null @@ -1,29 +0,0 @@ -export const coreConcepts = [ - { - title: 'Iconography', - slug: 'iconography', - }, - { - title: 'Layout', - slug: 'layout', - }, - { - title: 'Responsive', - slug: 'responsive', - }, - { - title: 'Theming', - slug: 'theming', - }, -]; - -export const components = [ - { - title: 'Box', - slug: 'box', - }, - { - title: 'Button', - slug: 'button', - }, -]; diff --git a/microsite-canon/utils/data.ts b/microsite-canon/utils/data.ts new file mode 100644 index 0000000000..12dbb1432c --- /dev/null +++ b/microsite-canon/utils/data.ts @@ -0,0 +1,69 @@ +export const coreConcepts = [ + { + title: 'Iconography', + slug: 'iconography', + }, + { + title: 'Layout', + slug: 'layout', + }, + { + title: 'Responsive', + slug: 'responsive', + }, + { + title: 'Theming', + slug: 'theming', + }, + { + title: 'Typography', + slug: 'typography', + }, +]; + +export const components = [ + { + title: 'Box', + slug: 'box', + }, + { + title: 'Button', + slug: 'button', + }, + { + title: 'Checkbox', + slug: 'checkbox', + }, + { + title: 'Container', + slug: 'container', + }, + { + title: 'Grid', + slug: 'grid', + }, + { + title: 'Heading', + slug: 'heading', + }, + { + title: 'Icon', + slug: 'icon', + }, + { + title: 'Inline', + slug: 'inline', + }, + { + title: 'Stack', + slug: 'stack', + }, + { + title: 'Table', + slug: 'table', + }, + { + title: 'Text', + slug: 'text', + }, +]; diff --git a/packages/canon/report.api.md b/packages/canon/report.api.md index f2e88fd367..170072687b 100644 --- a/packages/canon/report.api.md +++ b/packages/canon/report.api.md @@ -439,7 +439,7 @@ export { Text_2 as Text }; // @public (undocumented) export interface TextProps { // (undocumented) - children: React.ReactNode; + children: ReactNode; // (undocumented) variant?: | 'subtitle'