From 0dc3a66d58f9c7b0aa798f5499de5fdfd8f485cc Mon Sep 17 00:00:00 2001 From: Stuart Hendren Date: Fri, 23 Jul 2021 17:13:14 +0000 Subject: [PATCH] feat: rewrite of design system This comit completes initil development of the new design system implemented with Stritches and Radix BREAKING CHANGE: Fully redesigned. While many of the old components are still present the API for all components has changed. See documentation. fix #194 --- src/docs/colours.stories.mdx | 12 +- src/docs/examples/Overview.stories.tsx | 24 ++-- src/docs/examples/form.stories.tsx | 8 +- src/docs/examples/inbox.stories.tsx | 21 +-- src/docs/examples/website.stories.tsx | 4 +- src/docs/gettingStarted.stories.mdx | 120 +++++++++++++++--- src/docs/introduction.stories.mdx | 29 ++--- src/docs/overview.stories.mdx | 15 --- src/docs/util/Colors.tsx | 9 +- .../{util.stories.mdx => util.oldstories.mdx} | 0 10 files changed, 150 insertions(+), 92 deletions(-) delete mode 100644 src/docs/overview.stories.mdx rename src/docs/util/{util.stories.mdx => util.oldstories.mdx} (100%) diff --git a/src/docs/colours.stories.mdx b/src/docs/colours.stories.mdx index 7dd1217d..7142fa65 100644 --- a/src/docs/colours.stories.mdx +++ b/src/docs/colours.stories.mdx @@ -16,7 +16,7 @@ import { SemanticColors, Swatch, Colors, Surfaces } from './util' ### Light - + + + @@ -89,7 +89,7 @@ These are themed and rand from 1-12, with 9 being the pure color from which the ### Dark - + @@ -107,13 +107,13 @@ We use the brand colours within our main color sets differently for light and da themes. <> - + - + diff --git a/src/docs/examples/Overview.stories.tsx b/src/docs/examples/Overview.stories.tsx index 2c8573c7..0e9da90d 100644 --- a/src/docs/examples/Overview.stories.tsx +++ b/src/docs/examples/Overview.stories.tsx @@ -1,28 +1,20 @@ -import React from 'react' -import * as C from '../../index' import { - mdiDelete, + mdiAbTesting, mdiAlarm, mdiCart, + mdiChat, + mdiClipboardAccount, + mdiDelete, mdiEmail, + mdiEmailEdit, mdiFolder, - mdiAbTesting, - mdiClipboardAccount, - mdiFace, mdiInbox, - mdiEmailEdit, - mdiAccountCircle, - mdiHeartOutline, - mdiHeart, - mdiBookmarkOutline, - mdiBookmark, - mdiShareVariant, + mdiPlay, mdiSkipNext, mdiSkipPrevious, - mdiPlay, - mdiChat, } from '@mdi/js' -import commmitImage from '../../public/images/Avatar1-YellowTrans-32px.png' +import React from 'react' +import * as C from '../../index' export default { title: 'Examples/Overview', diff --git a/src/docs/examples/form.stories.tsx b/src/docs/examples/form.stories.tsx index 58a1ffed..55f5d979 100644 --- a/src/docs/examples/form.stories.tsx +++ b/src/docs/examples/form.stories.tsx @@ -7,6 +7,7 @@ import { CardBody, CardHeading, Checkbox, + CheckedState, Column, Flex, Input, @@ -16,7 +17,6 @@ import { Select, SelectItem, Text, - CheckedState, } from '../../components' import { listOfCountries } from '../util/data' @@ -79,9 +79,9 @@ export const Form = () => { label="Country" onValueChange={(value) => setCountry(value)} > - {listOfCountries.map((country) => ( - - {country.title} + {listOfCountries.map((c) => ( + + {c.title} ))} diff --git a/src/docs/examples/inbox.stories.tsx b/src/docs/examples/inbox.stories.tsx index 7bd4f71a..474ea05a 100644 --- a/src/docs/examples/inbox.stories.tsx +++ b/src/docs/examples/inbox.stories.tsx @@ -1,39 +1,28 @@ -import { - mdiDelete, - mdiEmail, - mdiFastForward, - mdiReply, - mdiReplyAll, -} from '@mdi/js' +import { mdiDelete, mdiFastForward, mdiReply, mdiReplyAll } from '@mdi/js' import React from 'react' import { AppBar, - AppBarHeading, AppBarActions, + AppBarHeading, Avatar, Box, Card, CardBody, - Heading, + darkTheme, IconButton, + lightTheme, List, ListItem, ListItemIcon, ListItemText, + Paragraph, Row, Svg, - Text, - Paragraph, ThemeProvider, - lightTheme, - darkTheme, ThemeSwitch, } from '../../' import { randomColor } from '../util' -const Email: React.FC> = (props) => ( - -) const Delete: React.FC> = (props) => ( ) diff --git a/src/docs/examples/website.stories.tsx b/src/docs/examples/website.stories.tsx index d564c303..86647944 100644 --- a/src/docs/examples/website.stories.tsx +++ b/src/docs/examples/website.stories.tsx @@ -9,21 +9,19 @@ import { Box, Card, CardBody, - CardHeading, Column, - Paragraph, Container, Divider, Flex, Heading, Link, + Paragraph, Row, Spinner, Svg, Text, ThemeProvider, ThemeSwitch, - useThemeController, } from '../../' const Email: React.FC> = (props) => ( diff --git a/src/docs/gettingStarted.stories.mdx b/src/docs/gettingStarted.stories.mdx index aae7de82..23772f8b 100644 --- a/src/docs/gettingStarted.stories.mdx +++ b/src/docs/gettingStarted.stories.mdx @@ -1,5 +1,7 @@ import { Meta } from '@storybook/addon-docs/blocks' import { version } from '../../package.json' +import { mdiImage } from '@mdi/js' +import { Svg, Text } from '../' @@ -10,7 +12,7 @@ Install the design system and dependencies in your application -npm add @committed/components@5.0.0-beta +npm add @committed/components@5.x.x Optionally, add the default fonts. This is done separately to keep down bundle size if they are not required. @@ -29,21 +31,19 @@ import React from 'react' import { ThemeProvider } from '@committed/components' import AppRoot from './AppRoot' -// If fonts used import in single place in your app. +// If fonts used, import once in your app e.g. // import '@fontsource/inter/300.css' // import '@fontsource/inter/400.css' // import '@fontsource/inter/700.css' -// import '@fontsource/dosis' - -class App extends React.Component { - render() { - return ( - - - - ) - } -} +// import '@fontsource/dosis/300.css' +// import '@fontsource/dosis/400.css' +// import '@fontsource/dosis/700.css' + +const App = () => ( + + + +) ``` ## Primitive UI Components @@ -52,7 +52,7 @@ Import and use the design system UI components in your application. ```jsx import React from 'react' -import { Box, Typography } from '@committed/components' +import { Box, Text } from '@committed/components' const AppRoot = (props) => ( @@ -63,6 +63,96 @@ const AppRoot = (props) => ( ## Icons +Import the icon paths from `@mdi/js` and use in `Svg` or `IconButton` components. + +For example, we suggest you create semantic icon components for use in your application. +This will make it easier to understand the usage of the icon and simpler to update and maintain. + + + +```jsx +import { mdiImage } from '@mdi/js' +import React, { ComponentProps, FC } from 'react' +import type { CSS } from ''@committed/components' +import { Svg } from '@committed/components' + +type IconType = FC> + +export const Picture: IconType = (props) => ( + +) +``` + +## Styling + +To style an individual component when used all (on screen) components support a `css` prop to allow for positioning and further styling of the component. +By design, components control their internal spacing and positioning but not the external. + +For example: + + + Example + + +```jsx +import { Text } from "@committed/components + +export StyledAndPositionedText = () => ( + + Example + +) +``` + +The `css` prop accepts all standard CSS in object form and, as this example shows, +there are theme tokens available for use, prefixes by the `$` symbol. + +For App specific components the `styled` function can be used. + +```jsx +import { styled, Text } from "@committed/components + +export StyledAndPositionedText = styled(Text, { + color: '$error', + padding: '$3', + border: 'solid 1px', + borderColor: '$text', + m: '$3', +}) ``` -TODO + +For the available theme tokens, see [Theme Config](/docs/components-themeprovider--default#theme-config) and +for more information of the use of the `css` prop and `styled` function see [Stitches Docs](https://stitches.dev/docs/styling). + +## Polymorphic components using `as` + +Most components support the base html component being changed using the `as` prop. +This can be used to set the appropriate semantic html tags. + +For example: + +``` + +My article + ``` + +This would create an `article` element in the html rather than this components standard `div` +but would still support the `css` props and other styles already applied to the component. +This makes for a cleaner html, that is semantically correct and reduced unnecessary elements. diff --git a/src/docs/introduction.stories.mdx b/src/docs/introduction.stories.mdx index 6bea616f..d0f94b83 100644 --- a/src/docs/introduction.stories.mdx +++ b/src/docs/introduction.stories.mdx @@ -8,32 +8,31 @@ import { version } from '../../package.json' -v5.0.0-beta +v5.x.x This is Committed's design system. It serves as a resource to help define a common visual language for Committed applications. This is a living system, and will be updated as we continue to improve and evolve our design system. +It's intended for Committed use but feel free to use it or the `src` in your own projects. + ## Getting Started Here are a few helpful links for getting started with Committed Components: -- [Getting Started](/components/?path=/docs/design-system-getting-started--page) Install and setup Components for your React app. -- [Design Principles](/components/?path=/docs/design-system-design-principles--page) Learn about the principles for the design. -- [Overview](/components/?path=/docs/design-system-overview) Get an overview of the main components in the system. -- [Status](/components/?path=/docs/design-system-status--page) See the status of different components. +- [Getting Started](/docs/design-system-getting-started--page) Install and setup Components for your React app. +- [Design Principles](/docs/design-system-design-principles--page) Learn about the principles for the design. +- [Overview](/docs/examples-overview--overview) Get an overview of the main components in the system. +- [Status](/docs/design-system-status--page) See the status of different components. - [Code](https://github.com/commitd/components) See the source code on GitHub. -## Motivation - -Design systems enable teams to build better products faster by making design reusable—reusability makes scale possible. -This is the heart and primary value of design systems. A design system is a collection of reusable components, guided by -clear standards, that can be assembled together to build any number of applications. +## Technologies -Regardless of the technologies and tools chosen, we aim to follow these guiding principles: +This design system is build with: -- **It’s consistent**. The way components are built and managed follows a predictable pattern. -- **It’s reusable**. The components are built so they can be reused in many contexts, but not all. -- **It’s accessible**. Applications built with Components are usable by as many people as possible, no matter how they access the web. -- **It’s robust**. No matter the product or platform, it should perform with minimal bugs. +- [Stitches](https://stitches.dev/) - for styling +- [Radix Primitives](https://www.radix-ui.com/docs/primitives/overview/introduction) - for accessible unstyled base components +- [Radix Colors](https://www.radix-ui.com/colors) - For accessible color scales +- [Material Design Icons](https://materialdesignicons.com/) - For iconography +- [Storybook](https://storybook.js.org/) - For documentation diff --git a/src/docs/overview.stories.mdx b/src/docs/overview.stories.mdx deleted file mode 100644 index 04cbb197..00000000 --- a/src/docs/overview.stories.mdx +++ /dev/null @@ -1,15 +0,0 @@ -import { Meta, Story, Preview } from '@storybook/addon-docs/blocks' -import { ThemeProvider } from '../' -//import { Background, Overview } from './util' - - - -# Overview - -A general overview of the components and how they look together. - - - - {/* */} - - diff --git a/src/docs/util/Colors.tsx b/src/docs/util/Colors.tsx index 25eb5849..2e1fcdf7 100644 --- a/src/docs/util/Colors.tsx +++ b/src/docs/util/Colors.tsx @@ -13,14 +13,19 @@ export interface ColorsProps { const resolveColor = (theme: any, name: string): string => { try { + if (name.startsWith('$')) { + return resolveColor(theme, name.substring(1)) + } const value = theme.colors[name].value as string if (value.startsWith('$')) { return resolveColor(theme, value.substring(8)) + } else if (value.startsWith('var')) { + return resolveColor(theme, value.substring(13, value.length - 1)) } else { return value } } catch (e) { - console.warn(`Missing color reference $${name}`) + console.warn(`Missing color reference ${name}`) console.log({ theme }) } return 'red' @@ -74,7 +79,7 @@ export const Color = ({ const key = `${name}${weight}` const colorKey = `$colors$${key}` const rawValue = theme.colors[key].value - const rawColor = resolveColor(theme, key) + const rawColor = resolveColor(theme, `$${key}`) const col = parseColor(rawColor) return ( diff --git a/src/docs/util/util.stories.mdx b/src/docs/util/util.oldstories.mdx similarity index 100% rename from src/docs/util/util.stories.mdx rename to src/docs/util/util.oldstories.mdx