Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(docs): add guidelines to components with new docs #645

Merged
merged 1 commit into from
Oct 27, 2021
Merged

feat(docs): add guidelines to components with new docs #645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 24 additions & 20 deletions packages/docs/components/GuidelinesTable/GuidelinesTable.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,39 @@ import { GuidelinesTableProps } from './types';
export const GuidelinesTable: React.FC<GuidelinesTableProps> = ({ recommended, discouraged }) => {
return (
<>
<StatefulTable
columns={[{ header: 'Do', hash: 'do', render: ({ recommend }) => recommend }]}
items={recommended.map((rule) => ({
recommend: (
<Flex alignItems="center">
<FlexItem flexGrow={0} marginRight="large">
<CheckCircleIcon color="success" />
</FlexItem>
<FlexItem>{rule}</FlexItem>
</Flex>
),
}))}
/>

<Box marginTop="xLarge">
{recommended.length > 0 && (
<StatefulTable
columns={[{ header: `Don't`, hash: 'dont', render: ({ discourage }) => discourage }]}
items={discouraged.map((rule) => ({
discourage: (
columns={[{ header: 'Do', hash: 'do', render: ({ recommend }) => recommend }]}
items={recommended.map((rule) => ({
recommend: (
<Flex alignItems="center">
<FlexItem flexGrow={0} marginRight="large">
<ErrorIcon color="danger" />
<CheckCircleIcon color="success" />
</FlexItem>
<FlexItem>{rule}</FlexItem>
</Flex>
),
}))}
/>
</Box>
)}

{discouraged.length > 0 && (
<Box marginTop="xLarge">
<StatefulTable
columns={[{ header: `Don't`, hash: 'dont', render: ({ discourage }) => discourage }]}
items={discouraged.map((rule) => ({
discourage: (
<Flex alignItems="center">
<FlexItem flexGrow={0} marginRight="large">
<ErrorIcon color="danger" />
</FlexItem>
<FlexItem>{rule}</FlexItem>
</Flex>
),
}))}
/>
</Box>
)}
</>
);
};
23 changes: 19 additions & 4 deletions packages/docs/pages/badge.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { Badge, Grid, H1, Panel, Text } from '@bigcommerce/big-design';
import React from 'react';

import { Code, CodePreview, ContentRoutingTabs, List } from '../components';
import { GuidelinesTable } from '../components/GuidelinesTable';
import { BadgePropTable, MarginPropTable } from '../PropTables';

const BadgePage = () => {
Expand All @@ -10,15 +11,18 @@ const BadgePage = () => {
<H1>Badge</H1>

<Panel header="Overview" headerId="overview">
<Text>Badges are labels that indicate the status of an object on the page.</Text>
<Text>
<Code primary>Badge</Code>s are labels that indicate the status of an object on the page.
</Text>
<Text bold>When to use it:</Text>
<List>
<List.Item>
Use badges to indicate the connection status of a 3rd party integration (e.g. payment method, a channel
connection).
Use <Code primary>Badge</Code>s to indicate the connection status of a 3rd party integration (e.g. payment
method, a channel connection).
</List.Item>
<List.Item>
You can also use badges to call attention to new features (e.g. “new”) or recommended integrations.
You can also use <Code primary>Badge</Code>s to call attention to new features (e.g. “new”) or recommended
integrations.
</List.Item>
</List>
</Panel>
Expand Down Expand Up @@ -70,6 +74,17 @@ const BadgePage = () => {
<Panel header="Props" headerId="props">
<BadgePropTable inheritedProps={<MarginPropTable collapsible />} renderPanel={false} />
</Panel>

<Panel header="Do's and Don'ts" headerId="guidelines">
<GuidelinesTable
recommended={['Use the right colour for the right situation (e.g. red when something is broken / wrong).']}
discouraged={[
<>
Don’t apply multiple <Code primary>Badge</Code>s to the same object.
</>,
]}
/>
</Panel>
</>
);
};
Expand Down
27 changes: 21 additions & 6 deletions packages/docs/pages/box.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { Box, Flex, H1, Panel, Text } from '@bigcommerce/big-design';
import React from 'react';
import styled from 'styled-components';

import { CodePreview, ContentRoutingTabs } from '../components';
import { Code, CodePreview, ContentRoutingTabs, GuidelinesTable } from '../components';
import { BoxPropTable, DisplayPropTable, MarginPropTable, PaddingPropTable } from '../PropTables';

const BoxPage = () => {
Expand All @@ -12,8 +12,9 @@ const BoxPage = () => {

<Panel header="Overview" headerId="overview">
<Text>
Box is a base component that is used to create other components. Using different values for properties like
border, border radius, and drop shadow, it can be turned into form field, button, panel, etc.
<Code primary>Box</Code> is a base component that is used to create other components. Using different values
for properties like border, border radius, and drop shadow, it can be turned into form field, button, panel,
etc.
</Text>
</Panel>

Expand Down Expand Up @@ -43,7 +44,9 @@ const BoxPage = () => {
title: 'Shadows',
render: () => (
<>
<Text>Box also supports multiple shadows, here is an example of how they look like:</Text>
<Text>
<Code primary>Box</Code> also supports multiple shadows, here is an example of how they look like:
</Text>

<CodePreview>
{/* jsx-to-string:start */}
Expand All @@ -66,8 +69,9 @@ const BoxPage = () => {
render: () => (
<>
<Text>
Box is extendable, here is an example on how to create an Avatar component extending from Box with a
couple of extra styles:
<Code primary>Box</Code> is extendable, here is an example on how to create an{' '}
<Code primary>Avatar</Code> component extending from <Code primary>Box</Code> with a couple of extra
styles:
</Text>

<CodePreview>
Expand Down Expand Up @@ -106,6 +110,17 @@ const BoxPage = () => {
renderPanel={false}
/>
</Panel>

<Panel header="Do's and Don'ts" headerId="guidelines">
<GuidelinesTable
recommended={[
'Apply 4px corner radius for all rectangular standalone components.',
'Apply raised drop shadow style to make the content on the grey background of the page stand out (panels).',
'Apply floating drop shadow style for elements that appear on top of the content of the page (pop-overs, alerts, drop menus, etc.).',
]}
discouraged={['Use any other corner radius values.']}
/>
</Panel>
</>
);
};
Expand Down
18 changes: 17 additions & 1 deletion packages/docs/pages/button-group.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { Box, ButtonGroup, H1, Panel, Text } from '@bigcommerce/big-design';
import { CheckIcon, InfoIcon } from '@bigcommerce/big-design-icons';
import React from 'react';

import { Code, CodePreview, ContentRoutingTabs, List } from '../components';
import { Code, CodePreview, ContentRoutingTabs, GuidelinesTable, List } from '../components';
import { ButtonGroupPropTable } from '../PropTables';

const ButtonGroupPage = () => {
Expand Down Expand Up @@ -108,6 +108,22 @@ const ButtonGroupPage = () => {
<Panel header="Props" headerId="props">
<ButtonGroupPropTable renderPanel={false} />
</Panel>

<Panel header="Do's and Don'ts" headerId="guidelines">
<GuidelinesTable
recommended={[
'Hide secondary actions or actions that doesn’t fit the container under ellipsis.',
'Hide destructive actions under ellipsis.',
'Keep all the controls in the same outlined style.',
'Show only actions that are available for the entity.',
]}
discouraged={[
'Move some controls to the second row.',
'Stylize some of the actions in the group differently (disabled, primary, destructive, etc.)',
'Use icons or text + icon for actions (except for ellipsis).',
]}
/>
</Panel>
</>
);
};
Expand Down
40 changes: 31 additions & 9 deletions packages/docs/pages/checkbox.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { Checkbox, Form, FormGroup, H1, Panel, Text } from '@bigcommerce/big-design';
import React, { useState } from 'react';

import { Code, CodePreview, ContentRoutingTabs, List } from '../components';
import { Code, CodePreview, ContentRoutingTabs, GuidelinesTable, List } from '../components';
import { CheckboxDescriptionLinkPropTable, CheckboxDescriptionPropTable, CheckboxPropTable } from '../PropTables';

const CheckboxPage = () => {
Expand All @@ -10,10 +10,14 @@ const CheckboxPage = () => {
<H1>Checkbox</H1>

<Panel header="Overview" headerId="overview">
<Text>Checkboxes let users toggle settings on and off within a form.</Text>
<Text>
<Code primary>Checkbox</Code>es let users toggle settings on and off within a form.
</Text>
<Text bold>When to use it:</Text>
<List>
<List.Item>Use checkboxes when users can make toggle one or more items in a form.</List.Item>
<List.Item>
Use <Code primary>Checkbox</Code>es when users can make toggle one or more items in a form.
</List.Item>
</List>
</Panel>

Expand All @@ -27,8 +31,8 @@ const CheckboxPage = () => {
render: () => (
<>
<Text>
Checkboxes are a stylized <Code>input[type="checkbox"]</Code> with controllable checked/unchecked
states.
<Code primary>Checkbox</Code>es are a stylized <Code>input[type="checkbox"]</Code> with controllable
checked/unchecked states.
</Text>

<CodePreview>
Expand Down Expand Up @@ -61,8 +65,8 @@ const CheckboxPage = () => {
render: () => (
<>
<Text>
Checkboxes support <Code primary>isIndeterminate</Code> passed as a prop to show a combined state of
partially selected checkboxes.
<Code primary>Checkbox</Code>es support <Code primary>isIndeterminate</Code> passed as a prop to
show a combined state of partially selected checkboxes.
</Text>

<CodePreview>
Expand All @@ -83,8 +87,8 @@ const CheckboxPage = () => {
render: () => (
<>
<Text>
Checkboxes support <Code primary>description</Code> passed as a prop, which contains a text and an
optional link.
<Code primary>Checkbox</Code>es support <Code primary>description</Code> passed as a prop, which
contains a text and an optional link.
</Text>

<CodePreview>
Expand Down Expand Up @@ -153,6 +157,24 @@ const CheckboxPage = () => {
]}
/>
</Panel>

<Panel header="Do's and Don'ts" headerId="guidelines">
<GuidelinesTable
recommended={[
<>
Use <Code primary>Checkbox</Code>es to turn on and off settings within a form.
</>,
<>
Group related <Code primary>Checkbox</Code>es under input label (h4).
</>,
]}
discouraged={[
<>
Apply changes made with the <Code primary>Checkbox</Code> right away without additional save action.
</>,
]}
/>
</Panel>
</>
);
};
Expand Down
32 changes: 29 additions & 3 deletions packages/docs/pages/collapse.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { Collapse, H1, Panel, Text } from '@bigcommerce/big-design';
import React, { useState } from 'react';

import { CodePreview, List } from '../components';
import { Code, CodePreview, GuidelinesTable, List } from '../components';
import { CollapsePropTable } from '../PropTables';

const CollapsePage = () => {
Expand All @@ -10,11 +10,14 @@ const CollapsePage = () => {
<H1>Collapse</H1>

<Panel header="Overview" headerId="overview">
<Text>The collapse component can hide/reveal content within a panel.</Text>
<Text>
The <Code primary>Collapse</Code> component can hide/reveal content within a panel.
</Text>
<Text bold>When to use it:</Text>
<List>
<List.Item>
Use collapse to reduce clutter, hiding non-essential information or options on a panel or modal.
Use <Code primary>Collapse</Code> to reduce clutter, hiding non-essential information or options on a panel
or modal.
</List.Item>
</List>
</Panel>
Expand Down Expand Up @@ -47,6 +50,29 @@ const CollapsePage = () => {
<Panel header="Props" headerId="props">
<CollapsePropTable renderPanel={false} />
</Panel>

<Panel header="Do's and Don'ts" headerId="guidelines">
<GuidelinesTable
recommended={[
'Users should be able tell what’s beneath the collapse button without having to open it - make sure the label is specific and helpful!',
'Collapse buttons should read like actions, and start with the word “Show”.',
'Collapsed content should be lower priority information that users don’t always need to see.',
'Left align directly under the content that is collapsed.',
'Position the collapsible content immediately after the collapse button.',
'Chevron arrow should flip vertically when component is toggled, to indicate the state of showing/hiding the content.',
]}
discouraged={[
<>
Do not use <Code primary>Collapse</Code> to hide elements necessary to complete a form - only
optional/extra content.
</>,
<>
Do not move <Code primary>Collapse</Code> component after click; instead, show the new content directly
below the component and let the component remain stationary.
</>,
]}
/>
</Panel>
</>
);
};
Expand Down
Loading