diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000000..906ccb0871 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,199 @@ +# How to contribute + +So you want to contribute to Circuit UI? That's awesome. Here are a few +things that can help you make it a reality. + +## Code of conduct + +We expect all participants to read and adhere to our [code of conduct](/CODE_OF_CONDUCT.md). + +## Semantic versioning + +Circuit UI follows semantic versioning. In short, this means we use patch versions +for bugfixes, minor versions for new features, and major versions for +breaking changes. Our [release process](#Releases) is automated using [semantic-release](https://github.com/semantic-release/semantic-release) +which adheres to the [conventional commit message format](https://www.conventionalcommits.org). + +As a result, our changelog is pretty tidy. You can [read our changelog on GitHub](https://github.com/sumup/circuit-ui/releases). + +## Bugs + +We use the [GitHub issues](https://github.com/sumup/circuit-ui/issues) to track +all our bugs and feature requests. + +When [submitting a new issue](https://github.com/sumup/circuit-ui/issues/new), +please check that it hasn't already been raised by someone else. We've provided +a template for new issues which will help you structure your issue to ensure it +can be picked up and actioned easily. + +Please provide as much information possible detailing what you're currently +experiencing and what you'd expect to experience. + +## Proposing a change + +![Component pattern addition](/component-addition-flowchart.png) + +### Creating or changing a component + +Our process for introducing changes to Circuit UI largely follow the Vanilla +design system process published by Canonical. + +#### Creating new components + +- You should favor using existing components rather than creating new ones. +- You should favor adapting existing components rather than creating new ones. +- You must contribute new components through the design system (rather than + coding them directly in the application) if the component is likely to be + used in more than one project. +- You should create an issue in the Circuit UI GitHub repo with the proposed + components using the appropriate issue type, _before_ implementing the + component. +- You should _not_ contribute components that are highly specific to the + use-case of a single application. If possibly, generalize it! + +#### Adapting an existing component + +- You may open a pull request with your proposed changes without opening an + issue in Circuit UI, so long as those changes could be classified as + minor. + +#### Workflow + +- Either a designer or a developer must open the issue in Circuit UI to propose + a new component or changes to an existing component. +- New components must be reviewed by two designers and two developers from + different teams. +- We should strive to decide whether we adopt a new component, if it's needed + for a feature, within one week of opening the issue. +- We should strive to decide whether we accept changes to an existing + component within one week of opening the issue. + +### Technical changes or improvements + +- You should open an issue in Circuit UI with your proposed change using the + "Suggest tech improvement" issue type. + +## Your first pull request + +## Development workflow + +We develop our components in Storybook. To start running Storybook on your +local machine, run: + +``` +yarn storybook +``` + +To run unit tests in watch mode, run: + +``` +yarn test:unit:watch +``` + +As for linting and formatting, you can configure your editor to automatically +lint and format your code on save. For this purpose, we're using Prettier +and ESLint. + +If you need to do it manually, you can run: + +``` +yarn unit:lint-js +yarn fix +``` + +### Local testing + +While making changes to Circuit UI, you might want to test them in your +application. You can do so by [linking the two projects](https://yarnpkg.com/lang/en/docs/cli/link/) +locally. + +Inside the Circuit UI project folder, run: + +``` +yarn link +``` + +Then, in your application project folder, run: + +``` +yarn link @sumup/circuit-ui +``` + +### Deprecation process + +The purpose of deprecating a component or a feature is to warn people that +it should not be used anymore, and that support will be removed in the future. +You can either offer a preferred solution, or it may be that the feature is +no longer needed. + +1. **Communicate intent to deprecate.** Please open an issue in the repo with + issue type "Deprecation", and share this issue with webchapter@sumup.com and + productdesign@sumup.com. Go through the product repos and find instances of + the component in use, and proactively communicate with the teams responsible + for those features. Give your reasoning about _why_ you believe the feature + should be deprecated, and discuss the impact on the teams that rely on + that feature today. +2. **Decide on a timeline.** Based on the feedback you receive, come up with + a timeline, including the people who are affected by the change. Generally + speaking, 3-6 months is ample time. Document the planned date of removal + in the original deprecation issue. +3. **Add a notice to the docs and to the code.** Introduce the deprecation + warning in a minor release. Change the status badge on the component page + to "Deprecated" and add a `console.warn(`ComponentName is deprecated and will be removed in version X.0.0`)` + to the `render()` function of the component, or generally on the first + run of an instance of a component or feature. +4. **Wait for the deadline.** You may still need to fix critical bugs during the + deprecation period, but we should try and offer alternatives where possible. +5. **Communicate it one more time!** Give one last warning to people involved + that the deadline is imminent. +6. **Delete it.** Create a PR deleting the deprecated functionality, which should + signal a major version bump. + +In some cases, you can also introduce a completely new version of the component +alongside the old, especially in cases where teams need longer to migrate +to the new component. For example, changing the SideNav component. + +## Releases + +We have a couple of special branches that are automatically released whenever +you merge code into them. + +- `beta` — This is a branch you can use to test your changes integrated with + other branches before it is ready to be PR'd to `canary`. It is also useful + if you need to deploy the changes somewhere to test them. `beta` is a + throw-away branch that can be recreated from `canary` at any time. +- `canary` - The step before `master`. This is where we prepare a group of + changes for the next release. Code on `canary` should be tested and stable. + Usually, `canary` is a couple of commits ahead of `master`. +- `master` - A merge to `master` will release a new version of the library. + Code on `master` is stable and production-tested. +- `next` - This branch is used to develop the next major version in parallel. + It is the only branch that can contain breaking changes. + +When you merge into one of these release branches, `semantic-release` runs in +CI and automatically: + +- pushes a new version to the respective release channel on NPM (`beta`, + `canary`, `latest` or `next`) +- updates the release notes on GitHub based on the commit messages since the + previous release +- and posts comments on any PRs and issues that are included in the release. + +To install the most recent version from a release channel, run: + +``` +yarn add @sumup/circuit-ui@ +``` + + +### Troubleshooting + +- **The release failed.** This can happen if you merge multiple times to a + release branch in short succession. The first CI job will fail because the + branch on GitHub is ahead of the branch that was checked out in CI. + `semantic-release` will open an issue to alert you of the failure. You can + simply wait for the last CI job to finish. It should succeed and will + automatically close the issue. +- **My commit doesn't show in the release notes.** Make sure that your commit + message follows the [conventional commit format](https://www.conventionalcommits.org). + Otherwise, `semantic-release` can't understand your commit and will omit it. diff --git a/.github/ISSUE_TEMPLATE/suggest-tech-improvement.md b/.github/ISSUE_TEMPLATE/suggest-tech-improvement.md new file mode 100644 index 0000000000..171ba1bbae --- /dev/null +++ b/.github/ISSUE_TEMPLATE/suggest-tech-improvement.md @@ -0,0 +1,18 @@ +--- +name: Suggest tech improvement +about: Suggest an improvement to the technology and tools behind Circuit UI +--- + +## Suggested technology + +- What technology do you suggest we start using? +- What technology (if any) would it replace? +- What problem does it solve? + +## Alternatives + +What are the alternatives you've explored? Why choose one over the other? + +## Potential downsides + +Do you see any downsides to this technology? \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..5481cef558 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +Addresses #ticket-number. + +## Purpose + +_Describe what you are trying to accomplish_ + +## Approach and changes + +_Describe how you solved the problem_ + +## Definition of done + +* [ ] Development completed +* [ ] Reviewers assigned +* [ ] Unit and integration tests +* [ ] Meets minimum browser support +* [ ] Meets accessibility requirements diff --git a/.github/component-addition-flowchart.png b/.github/component-addition-flowchart.png new file mode 100644 index 0000000000..159e611312 Binary files /dev/null and b/.github/component-addition-flowchart.png differ diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000000..e132a2b16a --- /dev/null +++ b/docs/404.html @@ -0,0 +1,9 @@ + + + + + + + diff --git a/docs/content/changelog.mdx b/docs/content/changelog.mdx deleted file mode 100644 index b8bf16b6f4..0000000000 --- a/docs/content/changelog.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -name: Changelog -route: /changelog ---- - -# Changelog - -Check out Github for the latest [Circuit UI changelog](https://github.com/sumup/circuit-ui/releases). diff --git a/docs/content/component-status/components/Statuses.js b/docs/content/component-status/components/Statuses.js deleted file mode 100644 index 1422aac369..0000000000 --- a/docs/content/component-status/components/Statuses.js +++ /dev/null @@ -1,22 +0,0 @@ -import React from 'react'; -import Badge from '../../../../src/components/Badge'; - -const Stable = () => ( - - Stable - -); - -const Deprecated = () => ( - - Deprecated - -); - -const InReview = () => ( - - In review - -); - -export { Stable, InReview, Deprecated }; diff --git a/docs/content/component-status/index.mdx b/docs/content/component-status/index.mdx deleted file mode 100644 index 42d50bd649..0000000000 --- a/docs/content/component-status/index.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -name: Component Status -route: /component-status ---- - -import { Deprecated, InReview, Stable } from './components/Statuses'; - -# Component Status - - - Component's name and API are considered stable. No foreseen breaking changes. - -
- - - Component is being reviewed as to its name, API, or whether it should be exposed in the UI library. - -
- - - Component will be removed in the next major version. - -## Components - -| Component | Added | Status | -| ------------------ | ----------------- | ------------- | -| Badge | development-0.0.1 | | -| Blockquote | development-0.0.2 | | -| Button | development-0.0.1 | | -| Calendar | development-0.0.1 | | -| Card | development-0.0.1 | | -| Checkbox | development-0.0.1 | | -| Heading | development-0.0.1 | | -| Hr | development-0.0.1 | | -| Image | development-0.0.1 | | -| InlineNotification | development-0.0.1 | | -| List | development-0.0.1 | | -| Markdown | development-0.0.1 | | -| Message | development-0.0.1 | | -| Modal | development-0.0.1 | | -| Picture | development-0.0.1 | | -| ProgressBar | development-0.0.1 | | -| Select | development-0.0.1 | | -| Selector | development-0.0.1 | | -| Subheading | development-0.0.1 | | -| Table | development-0.0.1 | | -| Tag | development-0.0.1 | | -| Text | development-0.0.1 | | -| TextArea | development-0.0.1 | | -| Toggle | development-0.0.1 | | -| Tooltip | development-0.0.1 | | - -## Grid - -| Component | Added | Status | -| --------- | ----------------- | --------- | -| Col | development-0.0.1 | | -| Grid | development-0.0.1 | | -| Row | development-0.0.1 | | - -## Patterns - -| Component | Added | Status | -| ----------------- | ----------------- | ----------- | -| AutoCompleteInput | development-0.0.1 | | -| AutoCompleteTags | development-0.0.1 | | -| CreditCardDetails | development-0.0.1 | | -| CurrencyInput | development-0.0.1 | | -| SearchInput | development-0.0.1 | | -| SvgButton | development-0.0.1 | | - -## Utilities - -| Component | Added | Status | -| ------------------ | ----------------- | ----------- | -| CardSchemes | development-0.0.1 | | -| CloseButton | development-0.0.1 | | -| Hamburger | development-0.0.1 | | -| InfoIcon | development-0.0.1 | | -| InlineElements | development-0.0.1 | | -| MaskedInput | development-0.0.1 | | -| NotificationBanner | development-0.0.1 | | -| NotificationList | development-0.0.1 | | -| PaymentMethodIcon | development-0.0.1 | | -| Popover | development-0.0.1 | | -| RestrictedInput | development-0.0.1 | | -| Spacing | development-0.0.1 | | -| Spinner | development-0.0.1 | | diff --git a/docs/content/components/DocButton.js b/docs/content/components/DocButton.js deleted file mode 100644 index 7b47b9e3cb..0000000000 --- a/docs/content/components/DocButton.js +++ /dev/null @@ -1,12 +0,0 @@ -import React from 'react'; -import { ThemeProvider } from 'emotion-theming'; -import OriginalButton from '../../../src/components/Button/Button'; -import { theme as themes } from '../../../src'; - -const DocButton = () => ( - - Button - -); - -export default DocButton; diff --git a/docs/content/components/badge.mdx b/docs/content/components/badge.mdx index 05851e4157..566a9899dd 100644 --- a/docs/content/components/badge.mdx +++ b/docs/content/components/badge.mdx @@ -4,30 +4,38 @@ route: /components/badge menu: Components --- -import { Playground } from 'docz'; +import { Playground, Props } from 'docz'; import { Fragment } from 'react'; import Badge from '../../../src/components/Badge/Badge'; +import Status from '../../utils/Statuses'; # Badge + + +Badges are non-actionable elements in the UI, used to indicate status of an object. + Badge -## Props - -(Cannot be rendered because it's a styled component) + ## Best practices -- Only use one badge at a time. +- Use our colour patterns so that merchants can learn and identify status on a + glance. +- Create a clear label with a short, scannable text. +- Position a badge so that it is obvious what content the status is related to. ## Usage guidelines -- Use to indicate statuses of a process, for instance, "Pending payment" or - "Successful transaction". -- Only use semantic badges in cases where their colors can be mapped to a - meaning. +- **Do** use badges to indicate the status of data rows in a table. +- **Do** use badges to bring attention to a specific area on the screen (like a + new feature). +- **Do not** use badges to indicate default statuses (e.g. in the Transaction + History, a transaction should only include a status if it's anything other + than default; failed, refunded, paid out, etc.) ## Component variations diff --git a/docs/content/components/blockquote.mdx b/docs/content/components/blockquote.mdx index f3d6126b77..fb9d2e1596 100644 --- a/docs/content/components/blockquote.mdx +++ b/docs/content/components/blockquote.mdx @@ -5,34 +5,45 @@ menu: Components --- import { Playground, Props } from 'docz'; - import { Fragment } from 'react'; import Blockquote from '../../../src/components/Blockquote/Blockquote'; +import Status from '../../utils/Statuses'; # Blockquote + + +Blockquotes are a way of styling specific text with indention, normally used for demonstrating and highlighting textual information that comes from an external source. + -
Blockquote
+
The ability to accept credit card payments that are EMV-compliant is essentially an insurance policy against fraud and an impressively economical one at that. +
 -## Props - -## Best practices +## When to use it + +For highlighting pieces of textual information, usually quotes, that aren't from SumUp directly. +For instance, we should use a blockquote to highlight a quote from a merchant that was interviewed on a blog post regarding product development. ## Usage guidelines -## Component variations +- **Do** use blockquotes for citing quotes from merchants, partners or other external sources +- **Do not** place an image within a blockquote, they should contain only text. -### Sizes blockquotes +## Component variations -The blockquotes come in a number of colors based on their semantic meaning. +You can customize the size of the blockquote using the `size` property. +We reccomend always sticking to mega in most cases, since it fits well with the Circuit's default body text size. -
Blockquote
-
Blockquote
-
Blockquote
+
Kilo - The ability to accept credit card payments that are EMV-compliant is essentially an insurance policy against fraud and an impressively economical one at that. +
+
Mega - The ability to accept credit card payments that are EMV-compliant is essentially an insurance policy against fraud and an impressively economical one at that. +
+
Giga - The ability to accept credit card payments that are EMV-compliant is essentially an insurance policy against fraud and an impressively economical one at that. +
 diff --git a/docs/content/components/button.js b/docs/content/components/button.js new file mode 100644 index 0000000000..ac914350a1 --- /dev/null +++ b/docs/content/components/button.js @@ -0,0 +1,62 @@ +/** + * Copyright 2019, SumUp Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import React, { useState } from 'react'; +import PropTypes from 'prop-types'; +import LoadingButton from '../../../src/components/LoadingButton'; + +const LoadingButtonWithState = ({ exitAnimation, children }) => { + // get loading button status animation or set as default + const variation = exitAnimation || 'DEFAULT'; + + const [loading, setLoading] = useState({ + DEFAULT: false, + SUCCESS: false, + ERROR: false + }); + + const handleClick = () => { + // trigger loading state + setLoading({ + ...loading, + [variation]: true + }); + // reset loading + window.setTimeout(() => { + setLoading({ + ...loading, + [variation]: false + }); + }, 1000); + }; + + return ( + handleClick()} + exitAnimation={exitAnimation && LoadingButton[exitAnimation]} + > + {children} + + ); +}; + +LoadingButtonWithState.propTypes = { + exitAnimation: PropTypes.oneOf(['SUCCESS', 'ERROR']), + children: PropTypes.string +}; + +export default LoadingButtonWithState; diff --git a/docs/content/components/button.mdx b/docs/content/components/button.mdx index 58620f5332..16897a9d71 100644 --- a/docs/content/components/button.mdx +++ b/docs/content/components/button.mdx @@ -7,99 +7,152 @@ menu: Components import { Playground, Props } from 'docz'; import { Fragment } from 'react'; -import Button from '../../../src/components/Button/Button'; +import Button from '../../../src/components/Button'; +import LoadingButtonWithState from './button'; +import ButtonGroup from '../../../src/components/ButtonGroup'; +import LoadingButtonComponent from '../../../src/components/LoadingButton'; +import Status from '../../utils/Statuses'; # Button + + +A button allows us to highlight actions in the product and make them easily +perceived and achievable through just one click. + - + -## Props - -## Best practices +## When to use it -- Be clearly and accurately labeled. -- Lead with strong actionable words. -- Use established button colors appropriately. -- Prioritize the most important actions. +Use buttons when merchants need to either navigate through a product or perform a specific task. ## Usage guidelines -### Components in a group - -- The primary action belongs on the right. +- **Do** always label a button in a clear and understandable way +- **Do** always think about the priority of the action to be taken when choosing a type of button +- **Do** position buttons in a predictable and coherent way throughout the product. +- **Do** combine different button types if you have more than one button in a specific screen +- **Do** use a loading state to provide feedback for our merchant when the action revolves around saving or + inputting information, especially when it could take some seconds. -### Content guidelines +## Content guidelines -- Start with a verb. +- **Do** always start the label with an actionable verb accompanied by a noun to provide enough context (example: "Confirm order"). + The only exceptions are the following common actions: "Save"; "Cancel"; and "Close". +- **Do** keep the label to a maximum of 3 words +- **Do not** capitalize all words of the label, just the first word or brand/product words (such as Apple Pay, for example) ## Component variations -### Default buttons +### Primary button -The default button can be used as a primary button if it's being displayed -on a dark background. +Used to highlight the most important action in a certain page. In most cases, there should be only one primary button visible +at a time. - + -### Primary buttons +### Default button -A button should be primary if it's the primary action that a user should take -on the page. In most cases, there should be only one primary button visible -at a time. +Used to highlight secondary actions to be takes, specially when there's already a primary action on the page. - + ### Secondary buttons -A secondary button offers an alternative action to the primary button. -Usually the secondary button signals actions such as "Cancel". +Only use secondary buttons when paired to a primary button, placed in the left side of it. They are used to +signal opposite actions from the primary button, such as "Cancel order". - + ### Flat buttons -A secondary button offers an alternative action to the primary button. -Usually the secondary button signals actions such as "Cancel". +Used only in the marketing website when you need to position an action over a dark background. It has a +primary and secondary version. - ### Plain buttons -Plain buttons are meant to look like links. Whether they render with an -`` tag or a ` ### Sized buttons +The button component also supports three different sizes: Mega, the best suitable for most cases; Kilo, used +when there is sizing constraints in the button position; and Giga, used for extreme cases when there's little +or no constraint on the button's placement. + + + + + + + + + + + + + - - - + + +## Button group + +Used when our merchant has two opposites actions to be taken in a certain step of a flow. It is generally used aligned to the right, +with a primary button for the expected action and a secondary button on its left. + + + + + + + + + + +## Loading button + +When the button's action is inputting/saving information or it takes more than 3 seconds to take the merchant +to the next step/page, you can indicate a loading state with `LoadingButton`, as well as visually notify +the merchant of success or an error after loading. You should only use it on primary buttons. + + + + {/* A live implementation example can be found on Storybook */} + Load + + Load success + + + Load error + + + + + diff --git a/docs/content/components/calendar.js b/docs/content/components/calendar.js new file mode 100644 index 0000000000..2cf2e51424 --- /dev/null +++ b/docs/content/components/calendar.js @@ -0,0 +1,60 @@ +/** + * Copyright 2019, SumUp Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import React from 'react'; +import { withStateHandlers } from 'recompose'; +import { RangePicker, SingleDayPicker } from '../../../src/components/Calendar'; + +const enhanceRangePicker = withStateHandlers( + { startDate: null, endDate: null, focusedInput: null }, + { + onDatesChange: () => ({ startDate, endDate }) => ({ startDate, endDate }), + onFocusChange: () => focusedInput => ({ focusedInput }) + } +); + +export const EnhancedRangePicker = enhanceRangePicker( + ({ startDate, endDate, focusedInput, onDatesChange, onFocusChange }) => ( + + ) +); + +const enhanceSingleDayPicker = withStateHandlers( + { date: null, focused: null }, + { + onDateChange: () => date => ({ date }), + onFocusChange: () => ({ focused }) => ({ focused }) + } +); + +export const EnhancedSingleDayPicker = enhanceSingleDayPicker( + ({ date, onDateChange, focused, onFocusChange }) => ( + + ) +); diff --git a/docs/content/components/calendar.mdx b/docs/content/components/calendar.mdx new file mode 100644 index 0000000000..8338f224b2 --- /dev/null +++ b/docs/content/components/calendar.mdx @@ -0,0 +1,90 @@ +--- +name: Calendar +route: /components/calendar +menu: Components +--- + +import { Playground } from 'docz'; +import { Fragment } from 'react'; + +import { + EnhancedRangePicker as RangePicker, + EnhancedSingleDayPicker as SingleDayPicker +} from './calendar'; +import CalendarTag from '../../../src/components/CalendarTag'; +import CalendarTagTwoStep from '../../../src/components/CalendarTagTwoStep'; +import Status from '../../utils/Statuses'; +import Text from '../../../src/components/Text'; + +# Calendar + + Likely to be renamed + +A calendar contains a view with actionable buttons in order to pick a range of dates +and time frames for a specific task. + + + + + +## When to use it + +Calendars are used when we need our merchants to pick a specific time period in order to complete a task +or filter a subset of dated items (such as the transaction history, for example). + +## Usage guidelines + +- **Do** suggest frequently used selections, such as "Today", "Last month", and others. +- **Do** use the proper component variation depending on how you need the data input +- **Do not** use it when requiring dates very far from the present, such as a birth date. + +## Component variations + +### Range Picker + + + +Used when the merchant needs to have clear visibility of selected start and end dates after the selection, +for instance when a merchant needs to pick a time period within a form. + + + + + +### Single Day Picker + + + +Used when you the merchant only needs to select a single specific date. + + + + + +### Calendar Tag + + + +Used for cases where the merchant needs to select dates within the same month and that selection affects the data displayed. + + + { + console.log(e); + }} + /> + + +### Calendar Tag Two Step + + + +Used for cases where the merchant needs to select dates that could be outside the same month and that selection affects the data displayed. + + + { + console.log(e); + }} + /> + diff --git a/docs/content/components/card-schemes.mdx b/docs/content/components/card-schemes.mdx new file mode 100644 index 0000000000..1b9f0f2194 --- /dev/null +++ b/docs/content/components/card-schemes.mdx @@ -0,0 +1,46 @@ +--- +name: Card Schemes +route: /components/card-schemes +menu: Components +--- + +import { Playground, Props } from 'docz'; +import { Fragment } from 'react'; +import CardSchemes from '../../../src/components/CardSchemes'; +import Text from '../../../src/components/Text'; +import Status from '../../utils/Statuses'; + +# Card Schemes + + Likely to be moved to the icon library + +Card Schemes provides a quick way to pull all accepted card schemes icons from SumUp. + + + + + +## When to use it + +Card scheme icons are used to indicate the accepted card schemes, such as in a credit card input form or in the marketing +website to promote accepted schemes. + +## Usage guidelines + +- **Do** always check which schemes are accepted in each market, they usually vary from country to country +- **Do** use to provide context beforehand when our merchant is completing a credit card payment + + + +## Usage in code + +It can be used in forms with the `CardNumberInput` component. Different sizes are also supported. + + + + \ No newline at end of file diff --git a/docs/content/components/card.mdx b/docs/content/components/card.mdx index f37d80641d..9537a114e2 100644 --- a/docs/content/components/card.mdx +++ b/docs/content/components/card.mdx @@ -4,34 +4,57 @@ route: /components/card menu: Components --- -import { Playground } from 'docz'; +import { Playground, Props } from 'docz'; import { Fragment } from 'react'; import Card from '../../../src/components/Card/Card'; +import { CardHeader } from '../../../src/components/Card'; +import ListView from '../../../src/components/ListView'; +import Text from '../../../src/components/Text'; +import Status from '../../utils/Statuses'; +import Heading from '../../../src/components/Heading/Heading'; # Card + + +Cards are one of the most important elements that give structure for the content we are showing for our +merchants. They group related information and make our product easy to scan and understand. + - Card + + + + Send us a message + + + + If you didn't solve your problem using our resource center, please send us + a message below and we will answer as soon as possible + + -## Props - -(Cannot be rendered because it's a styled component) + -## Best practices +## When to use it -- Use different shadows. +You should use cards whenever you need to present related information in an easy and scannable way for our merchant. ## Usage guidelines -- Every card should be a logical combination of its contents. +- **Do** always write a heading for your card that expresses clearly what to expect from it +- **Do** order the information on the card according to priority for our merchants +- **Do** place primary buttons on the bottom of the card, especially the main call to action for the next step +- **Do not** place more than one primary button on a card +- **Do not** fill the card with a lot of content. If the card requires too much scrolling, consider breaking it into multiple sections with different cards +- **Do not** place a card ## Component variations -### Spacings +### Card spacings Cards come in two spacing variations, mega and giga. Giga -is the default spacing. +is the default and should be used for most cases. @@ -43,6 +66,9 @@ is the default spacing. ### Shadows +A card has three possible different shadows ranging from low intensity (single) to maximum (triple). For most cases, +the single shadow is recommended. + Card with single shadow @@ -53,3 +79,22 @@ is the default spacing.
+ +## List of cards + + Likely to be renamed + +You can create a list of cards using `ListView`. You should use it when showing the same type of information within +each card and clicking on it opens contextual information about it. One example is the transaction history, where +each transaction is a card shown on a list and clicking in any one of them shows more information on that particular +transaction. + + + + First card + Second card + Third card + + + + diff --git a/docs/content/components/date-picker.mdx b/docs/content/components/date-picker.mdx deleted file mode 100644 index 0c6a0412bf..0000000000 --- a/docs/content/components/date-picker.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Date picker -route: /components/date-picker -menu: Components ---- - -import { Playground } from 'docz'; - -import { Fragment } from 'react'; -import RangePicker from '../../../src/components/Calendar/RangePicker'; - -# Blockquote - - - -## Best practices - -## Usage guidelines - -## Component variations diff --git a/docs/content/components/forms.mdx b/docs/content/components/forms.mdx index b9971c6aa3..2aa1318015 100644 --- a/docs/content/components/forms.mdx +++ b/docs/content/components/forms.mdx @@ -5,18 +5,26 @@ menu: Components --- import { Fragment } from 'react'; -import { Playground } from 'docz'; +import { Playground, Props } from 'docz'; +import Text from '../../../src/components/Text'; import Input from '../../../src/components/Input/Input'; import Label from '../../../src/components/Label/Label'; import Checkbox from '../../../src/components/Checkbox/Checkbox'; import RadioButton from '../../../src/components/RadioButton/RadioButton'; import Select from '../../../src/components/Select/Select'; import TextArea from '../../../src/components/TextArea/TextArea'; +import SearchInput from '../../../src/components/SearchInput'; +import AutoCompleteInput from '../../../src/components/AutoCompleteInput'; +import CurrencyInput from '../../../src/components/CurrencyInput'; +import AutoCompleteTags from '../../../src/components/AutoCompleteTags'; +import Status from '../../utils/Statuses'; # Forms ## Text Field + + A text field is an input field for inserting short text and numbers. It has multiple functions and supports multiple character types/formats. @@ -27,6 +35,8 @@ multiple functions and supports multiple character types/formats. + + ### When to use it When you need short textual information from the user such as email address, @@ -121,6 +131,8 @@ Always provide a placeholder for text input fields. ## Label + + A label is a short text that explains what information is needed in the text field. Having a clear and straightforward label not only helps the user to know what is the purpose of the input but also helps directly with making forms @@ -130,6 +142,8 @@ more accessible. + + ### When to use it Always provide a label for text input fields. @@ -145,6 +159,8 @@ Always provide a label for text input fields. ## Checkbox + + The primary goal of checkboxes is to provide a way for the user to make a range of selections. The users can select from zero, one, or multiple options. In other words, each checkbox is independent of all other checkboxes in the list, and checking one box doesn’t uncheck the others. @@ -160,6 +176,8 @@ of all other checkboxes in the list, and checking one box doesn’t uncheck the + + ### When to use it Use it to ask the users questions with one or multiple alternatives. You could also use it as a way to toggle @@ -224,6 +242,8 @@ an option or agree to certain terms & conditions. ## Radio button + + A radio button is a quick way to extract a single coded answer from our users by presenting multiple possibilities and allowing only one option to be chosen. @@ -244,6 +264,8 @@ possibilities and allowing only one option to be chosen. + + ### When to use it Use a radio button when the user has to choose only one option based on a pre-defined list of mutually @@ -291,6 +313,8 @@ An example being the expiration date for a users credit card. /> + + ### When to use it Best used when there are 4 or more defined options to choose from (e.g. Months).If there are less than 4 options, @@ -308,12 +332,16 @@ consider using the radio button component. ## Textarea + + It is a type of input that allow mutiple lines of text.