From 626cda3c8ed5b24b963b665de5cc361c87156865 Mon Sep 17 00:00:00 2001 From: Alexander Schwarzmann Date: Wed, 31 Jul 2024 16:20:37 +0200 Subject: [PATCH] chore(storybook): docs about UI kit ver 0.6.0 --- app/storybook/.storybook/preview.tsx | 2 + .../documentation/ui-kit/theming/Color.mdx | 244 ++++++++++++++++++ .../documentation/ui-kit/theming/Cursors.mdx | 62 +++++ .../documentation/ui-kit/theming/DarkMode.mdx | 24 ++ .../documentation/ui-kit/theming/Overview.mdx | 60 +++++ .../documentation/ui-kit/theming/Radius.mdx | 55 ++++ .../documentation/ui-kit/theming/Shadows.mdx | 37 +++ .../documentation/ui-kit/theming/Spacing.mdx | 61 +++++ .../ui-kit/theming/Typography.mdx | 21 ++ .../TimeSeries/TimeSeries.stories.tsx | 83 ++++++ .../Typography/Typography.stories.tsx | 16 ++ 11 files changed, 665 insertions(+) create mode 100644 app/storybook/documentation/ui-kit/theming/Color.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Cursors.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/DarkMode.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Overview.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Radius.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Shadows.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Spacing.mdx create mode 100644 app/storybook/documentation/ui-kit/theming/Typography.mdx diff --git a/app/storybook/.storybook/preview.tsx b/app/storybook/.storybook/preview.tsx index 31859dd5..359498bd 100644 --- a/app/storybook/.storybook/preview.tsx +++ b/app/storybook/.storybook/preview.tsx @@ -84,6 +84,8 @@ const preview: Preview = { order: [ 'Getting started', ['Overview', 'Installation', 'Authentication', 'Usage', 'Querying Metrics', 'FAQ', 'Migration guide'], + 'Theming', + ['Overview', 'Color', 'Dark mode', 'Typography', 'Spacing', 'Radius', 'Shadows', 'Cursors'], 'Customization', ['Theming', 'Components'], 'Components', diff --git a/app/storybook/documentation/ui-kit/theming/Color.mdx b/app/storybook/documentation/ui-kit/theming/Color.mdx new file mode 100644 index 00000000..9f45e036 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Color.mdx @@ -0,0 +1,244 @@ +import { Meta, Source, Story } from '@storybook/blocks' +import LinkTo from '@storybook/addon-links/react' +import { prettier } from '../../../src/utils' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import { accentColors, grayColors, colors } from '../../../../../packages/ui-kit/src/themes' +import * as ThemeProviderStories from '../../../../../packages/ui-kit/src/components/ThemeProvider/ThemeProvider.stories' + +export const ColorsPallete = ({ colorsGroup }) => ( +
+ {colorsGroup.map((color) => ( +
+
+

+ {color.charAt(0).toUpperCase() + color.slice(1)} +

+
+ ))} +
+) + +export const ColorAnatomy = ({ color }) => ( +
+ {Object.keys(colors[color]).map((key, index) => ( +
+
+
+
+
+
{index + 1}
+
+ ))} +
+) + + + +# Color + +Understanding the color system and its application in your theme. + +Propel Themes come with a number of color scales, each with its own light, dark, and alpha variants. Under the hood, the +color system is powered by [Radix Colors](https://www.radix-ui.com/colors). + +## Accents + +Accent color is the most dominant color in your theme. It is used for primary buttons, links and other interactive +elements. `accentColor` is specified directly on the`ThemeProvider` component: + + + ", + metric: { + count: { + dataPool: { name: "TacoSoft Demo Data" } + }, + } + timeRange: { relative: RelativeTimeRange.LastNDays, n: 90 }, + granularity: "DAY", + }} + /> + + ); + } + +`} /> + +### Available accent colors + +There is a range of accent colors to choose from: + + + +### Accent scale anatomy + +Each accent is a 12-step scale that includes a solid and a transparent variant of each color. + +For example, here's the `indigo` color scale: + + + +### Accent scale tokens + +Accent color tokens can be accessed using CSS variables. You can use these tokens to style your custom components, +ensuring they are accessible and consistent with the rest of your theme. + + + +## Grays + +You can also choose between a pure gray or a number of tinted grays. Your accent color will be automatically paired with +a gray shade that compliments it. However, you can also specify a custom `grayColor` directly on the `ThemeProvider` +component: + + + ", + metric: { + count: { + dataPool: { name: "TacoSoft Demo Data" } + }, + } + timeRange: { relative: RelativeTimeRange.LastNDays, n: 90 }, + granularity: "DAY", + }} + /> + + ); + } + +`} /> + +### Available gray colors + +There is 6 grays to choose from. The difference may seem subtle, but it is impactful especially on pages with a lot of +text or in dense UIs. + + color !== 'auto')} /> + +### Gray scale anatomy + +Grays are based on the same 12-step color scale that includes a solid and a transparent variant of each color. For +example, here's the `slate` color scale: + + + +### Gray scale tokens + +Gray color tokens can be accessed using CSS variables. You can use these tokens to style your custom components, +ensuring they are accessible and consistent with the rest of your theme. + + diff --git a/app/storybook/documentation/ui-kit/theming/Cursors.mdx b/app/storybook/documentation/ui-kit/theming/Cursors.mdx new file mode 100644 index 00000000..67bdd727 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Cursors.mdx @@ -0,0 +1,62 @@ +import { Meta, Source } from '@storybook/blocks' + + + +# Cursors + +Customizing cursors used for interactive elements. + +## Default cursors + +By default, interactive elements that don't link to another page use the regular arrow cursor. This also matches the +browser defaults. However, disabled elements use an explicit disabled cursor. + +## Cursor tokens + +Cursor settings can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring +they are accessible and consistent with the rest of your theme. + + + +## Customization + +It's common to use a pointer cursor for interactive elements. Propel Themes cursors can be customized by overriding the +corresponding CSS variables of the token system. + +Here's an example of how you can customize the cursor tokens to set `cursor: pointer` for most interactive elements in +the theme: + + diff --git a/app/storybook/documentation/ui-kit/theming/DarkMode.mdx b/app/storybook/documentation/ui-kit/theming/DarkMode.mdx new file mode 100644 index 00000000..c46d69c2 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/DarkMode.mdx @@ -0,0 +1,24 @@ +import { Meta, Story } from '@storybook/blocks' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import * as TimeSeriesStories from '../../../../../packages/ui-kit/src/components/TimeSeries/TimeSeries.stories' + + + +# Dark mode + +Using appearance to manage and integrate dark mode. + +## Overview + +Light and dark modes are supported out of the box, allowing you to easily switch appearance without additional design or +styling. + +### Basic usage + +By default, the root `ThemeProvider` appearance is `light`. + + + +To set a different appearance pass it via the `appearance` prop. This will force the theme to use the specified setting. + + diff --git a/app/storybook/documentation/ui-kit/theming/Overview.mdx b/app/storybook/documentation/ui-kit/theming/Overview.mdx new file mode 100644 index 00000000..8ba2666c --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Overview.mdx @@ -0,0 +1,60 @@ +import { Meta, Source, Story } from '@storybook/blocks' +import LinkTo from '@storybook/addon-links/react' +import { prettier } from '../../../src/utils' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import * as ThemeProviderStories from '../../../../../packages/ui-kit/src/components/ThemeProvider/ThemeProvider.stories' +import * as TimeSeriesStories from '../../../../../packages/ui-kit/src/components/TimeSeries/TimeSeries.stories' + + + +# Anatomy + +The ThemeProvider component defines the overall visual look +of your application. It can be customized by passing a minimal set of configuration options. + + + +A well-tuned set of defaults is provided to get you started, but don't be afraid to play with all of the available +options to find the right visual style for your application. + +## Tokens + +Tokens provide direct access to theme values and give you the flexibility to build and customize your own themed +components. + +For all available theme tokens see the +[source code](https://github.com/propeldata/ui-kit/tree/main/packages/ui-kit/src/themes/tokens), or read more about each +type of token in the relevant theme pages. + +## Start now + +Get started with UI Kit today through some of these useful resources: + +- + Color + + - understand the color system and its application in your theme. +- + Drak mode + + -  learn how to switch between light and dark mode. +- + Typography + + - learn how to use and customize the typographic elements of your theme. +- + Spacing + + - explore the spacing scale and the available scaling options. +- + Radius + + - choose the radius setting in your theme that fits your style. +- + Shadows + + - use elevation, depth and shadows effectively and customize their properties. +- + Cursors + + - customizing cursors used for interactive elements. diff --git a/app/storybook/documentation/ui-kit/theming/Radius.mdx b/app/storybook/documentation/ui-kit/theming/Radius.mdx new file mode 100644 index 00000000..963a74b3 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Radius.mdx @@ -0,0 +1,55 @@ +import { Meta, Source } from '@storybook/blocks' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import * as TimeSeriesStories from '../../../../../packages/ui-kit/src/components/TimeSeries/TimeSeries.stories' + + + +# Radius + +Choosing the right radius setting in your theme. + +## Theme setting + +Theme `radius` setting manages the radius factor applied to the components: + + + +## Radius scale + +Radius values used in the components are derived from a 6-step scale. + +While you can't use a specific step on a particular component directly—the `radius` prop is used to set just the radius +factor—you can use the radius scale to style your own components. + +Radius tokens are accessed using CSS variables. You can use these tokens to style your custom components, ensuring they +are consistent with the rest of your theme. + + diff --git a/app/storybook/documentation/ui-kit/theming/Shadows.mdx b/app/storybook/documentation/ui-kit/theming/Shadows.mdx new file mode 100644 index 00000000..699b1896 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Shadows.mdx @@ -0,0 +1,37 @@ +import { Meta, Source } from '@storybook/blocks' + + + +# Shadows + +Understanding the shadow styles used in your theme. + +Shadows used in the components are derived from a 6-step scale. Refer to the +[source code](https://github.com/propeldata/ui-kit/blob/main/packages/ui-kit/src/themes/tokens/_shadow.scss) for the +actual values used to achieve these shadows. + +### Shadow tokens + +Shadow tokens can be accessed using CSS variables. You can use these tokens to style your custom components, ensuring +they are consistent with the rest of your theme. + + diff --git a/app/storybook/documentation/ui-kit/theming/Spacing.mdx b/app/storybook/documentation/ui-kit/theming/Spacing.mdx new file mode 100644 index 00000000..1764e71c --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Spacing.mdx @@ -0,0 +1,61 @@ +import { Meta, Source } from '@storybook/blocks' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import * as TimeSeriesStories from '../../../../../packages/ui-kit/src/components/TimeSeries/TimeSeries.stories' + + + +# Spacing + +Overview of the space scale and scaling options. + +## Space scale + +Spacing values are derived from a 9-step scale, which is used for props such as margin and padding. These props accept +numeric strings from `"1"` to `"9"`, which correspond to the steps in the scale below. + +### Space scale tokens + +Space scale tokens can also be accessed using CSS variables. You can use these tokens to style your custom components, +ensuring they are consistent with the rest of your theme. + + + +## Scaling + +Values that affect layout (spacing, font size, line height) scale relatively to each other based on the `scaling` value +defined in your Theme. This setting allows you to scale the UI density uniformly across your entire application. + + + +### Scaling factor + +The scaling factor token can be accessed using the `--propel-scaling` CSS variable. If you need to use different scaling +factors in your app, you can use this token in your custom styles, ensuring they are consistent with the rest of your +theme. + + diff --git a/app/storybook/documentation/ui-kit/theming/Typography.mdx b/app/storybook/documentation/ui-kit/theming/Typography.mdx new file mode 100644 index 00000000..9ff90e69 --- /dev/null +++ b/app/storybook/documentation/ui-kit/theming/Typography.mdx @@ -0,0 +1,21 @@ +import { Meta } from '@storybook/blocks' +import LinkTo from '@storybook/addon-links/react' +import { SourceCode } from '../../../.storybook/blocks/SourceCode' +import * as TypographyStories from '../../../../../packages/ui-kit/src/components/Typography/Typography.stories' + + + +# Typography + +Guidance for using and tuning typography. + +## Base component + +Use Typography component to render text. This component +has `size` prop and map to the underlying type system to ensure consistent typography throughout your app. + +It can render text using various semantic HTML elements (e.g., `h1`, `p`, `span`) while maintaining consistent styling. +It adapts its underlying DOM element based on the context or props, ensuring proper document structure and +accessibility. + + diff --git a/packages/ui-kit/src/components/TimeSeries/TimeSeries.stories.tsx b/packages/ui-kit/src/components/TimeSeries/TimeSeries.stories.tsx index cbf7a46f..124f68ea 100644 --- a/packages/ui-kit/src/components/TimeSeries/TimeSeries.stories.tsx +++ b/packages/ui-kit/src/components/TimeSeries/TimeSeries.stories.tsx @@ -5,6 +5,7 @@ import axiosInstance from '../../../../../app/storybook/src/axios' import { RelativeTimeRange, TimeSeriesGranularity } from '../../graphql' import { quotedStringRegex, storybookCodeTemplate, useStorybookAccessToken } from '../../helpers' import { TimeSeries as TimeSeriesSource, TimeSeriesComponent } from './TimeSeries' +import { ThemeProvider } from '../ThemeProvider' import { TimeSeriesQueryProps } from './TimeSeries.types' const meta: Meta = { @@ -320,3 +321,85 @@ export const ErrorStory: Story = { }, render: (args) => } + +export const WithThemeProviderStory: Story = { + name: 'With ThemeProvider', + tags: ['hidden'], + args: { + query: connectedParams + }, + parameters: { + imports: 'ThemeProvider, TimeSeries, RelativeTimeRange' + }, + render: (args) => ( + + + + ) +} + +export const LightThemeStory: Story = { + name: 'With Light theme', + tags: ['hidden'], + args: { + query: connectedParams, + card: true + }, + parameters: { + imports: 'ThemeProvider, TimeSeries, RelativeTimeRange' + }, + render: (args) => ( + + + + ) +} + +export const DrakThemeStory: Story = { + name: 'With Drak theme', + tags: ['hidden'], + args: { + query: connectedParams, + card: true + }, + parameters: { + imports: 'ThemeProvider, TimeSeries, RelativeTimeRange' + }, + render: (args) => ( + + + + ) +} + +export const ScalingStory: Story = { + name: 'Scaling', + tags: ['hidden'], + args: { + query: connectedParams + }, + parameters: { + imports: 'ThemeProvider, TimeSeries, RelativeTimeRange' + }, + render: (args) => ( + + + + ) +} + +export const RadiusStory: Story = { + name: 'Radius', + tags: ['hidden'], + args: { + query: connectedParams + }, + parameters: { + imports: 'ThemeProvider, TimeSeries, RelativeTimeRange' + }, + render: (args) => ( + + + + ) +} diff --git a/packages/ui-kit/src/components/Typography/Typography.stories.tsx b/packages/ui-kit/src/components/Typography/Typography.stories.tsx index f2cc4ac2..57747ab7 100644 --- a/packages/ui-kit/src/components/Typography/Typography.stories.tsx +++ b/packages/ui-kit/src/components/Typography/Typography.stories.tsx @@ -41,3 +41,19 @@ export const BigStory: Story = {
) } + +export const MixedWithdStory: Story = { + name: 'Mixed with weight', + tags: ['hidden'], + render: (args) => ( +
+ + Typographic principles + + + The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes + beauty and makes reading easier and more pleasant. + +
+ ) +}