Editorial (#192)

* intro editorial

* components - buttons

* components - accents

* components - branding

* components - containers

* components - elements

* components - inputs

* components - layout

* components - notifications

* components - profile

* foundations - typography

@stellar/design-system-website/docs/get-started/intro.mdx → @stellar/design-system-website/docs/get-started/introduction.mdx

@@ -3,12 +3,12 @@ slug: /
 sidebar_position: 1
 ---
 
-# Intro
+# Introduction
 
 Stellar Design System (SDS) is an opinionated React component library (we hope
-it will grow into a full-featured design system in the future) used in Stellar
-Development Foundation’s Web projects. It's meant to be used internally to keep
-our Web products consistent.
+it will grow into a full-featured design system in the future) used in the Stellar
+Development Foundation’s web projects. It's meant to be used internally to keep
+our web products consistent.
 
 ## Current version
 
@@ -27,15 +27,15 @@ our Web products consistent.
 - Yarn
 - Webpack
 
-## Usage
+## Get started
 
-Install using package manager of your choice.
+Install SDS by using the package manager of your choice.
 
 ```bash npm2yarn
 npm install @stellar/design-system
 ```
 
-Add Google Fonts (`Inter Tight`, `Inter`, and `Roboto Mono`) to `index.html`
+Add Google Fonts (`Inter Tight`, `Inter`, and `Roboto Mono`) to the `index.html`
 file.
 
 ```html
@@ -87,7 +87,7 @@ npm install
 ### Scripts to develop and build locally
 
 - `build:sds` - build Stellar Design System (sds) project only
-- `build:sds-web` - build Stellar Design System Website (sds-web) project only
+- `build:sds-web` - build Stellar Design System website (sds-web) project only
 - `build` - build both projects
 - `start:sds` - start sds project for local development
 - `start:sds-web` - start sds-web project for local development
@@ -101,9 +101,9 @@ You need to run each `start` command in its own window or tab.
 
 ## Developer notes
 
-- Use the Design System components "as is", don’t modify existing ones to fit
+- Use the Stellar Design System components "as is", don’t modify existing ones to fit
   your needs if the component doesn’t allow it.
-- If a component doesn’t exist, it’s OK to create it locally for your project
+- If a component doesn’t exist, it’s okay to create it locally for your project
   (we’ll keep adding more components to SDS as we go).
 - If you are creating a component locally, use only color variables available in
   the SDS palette (in `theme.scss`). This is very important for the light and

@stellar/design-system/src/components/AssetIcon/index.tsx

@@ -21,7 +21,7 @@ export interface AssetIconProps {
 }
 
 /**
- * Asset image displayed in a circle from a URL source. The component accepts multiple sources to show currency pair, for example.
+ * An asset image displayed in a circle from a URL source. The component can accept multiple sources to show a currency pair, for example.
  */
 export const AssetIcon: React.FC<AssetIconProps> = ({
   source,

@stellar/design-system/src/components/Avatar/index.tsx

@@ -8,7 +8,7 @@ export interface AvatarProps {
 }
 
 /**
- * Unique identicon of public Stellar address. [We’re using stellar-identicon-js](https://github.com/Lobstrco/stellar-identicon-js).
+ * A unique identicon of a public Stellar address. [We’re using stellar-identicon-js](https://github.com/Lobstrco/stellar-identicon-js).
  */
 export const Avatar: React.FC<AvatarProps> = ({
   publicAddress,

@stellar/design-system/src/components/Banner/index.tsx

@@ -10,7 +10,7 @@ export interface BannerProps {
 }
 
 /**
- * Use banner to display messages at the top of the page, stretching across the whole width. There are five variants `default`, `primary`, `success`, `error`, and `warning`.
+ * Use `banner` to display messages at the top of the page, stretching across the whole width. There are five variants `default`, `primary`, `success`, `error`, and `warning`.
  */
 export const Banner: React.FC<BannerProps> = ({ variant, children }) => (
   <div className={`Banner Banner--${variant}`}>

@stellar/design-system/src/components/Button/index.tsx

@@ -3,7 +3,7 @@ import { Loader } from "../Loader";
 import "./styles.scss";
 
 /**
- * Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+ * Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes).
  */
 export interface ButtonProps {
   /** Variant of the button */
@@ -39,7 +39,7 @@ interface Props
     React.ButtonHTMLAttributes<HTMLButtonElement> {}
 
 /**
- * `Button` is used to trigger an action that is not opening a link (use {@link Link}
+ * `Button` is used to trigger an action that is not opening a link (to trigger an action that opens a link, use {@link Link}
  * instead).
  */
 export const Button: React.FC<Props> = ({

@stellar/design-system/src/components/ButtonPreset/index.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { Icon } from "../../icons";
 
-/** Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes) */
+/** Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). */
 export interface ButtonPresetProps {
   /** Button preset */
   preset: "copy" | "download";
@@ -35,7 +35,8 @@ const presetDetails = {
 };
 
 /**
- * `ButtonPreset` is similar to the {@button Button} component, and is used to trigger an action. There are two presets `copy` and `download`, and two variants for color: `default` and `highlight`.
+ * `ButtonPreset` is similar to the {@button Button} component, and is used to trigger an action. There are two presets: `copy` and `download` and two variants 
+ * for color: `default` and `highlight`.
  */
 export const ButtonPreset: React.FC<Props> = ({
   altText,

@stellar/design-system/src/components/Card/index.tsx

@@ -14,7 +14,7 @@ export interface CardProps {
 }
 
 /**
- * Container with flexible dimensions for any type of content.
+ * The `card` container has flexible dimensions for any type of content.
  */
 export const Card: React.FC<CardProps> = ({
   children,

@stellar/design-system/src/components/Checkbox/index.tsx

@@ -3,9 +3,9 @@ import { FieldNote } from "../utils/FieldNote";
 import { Icon } from "../../icons";
 import "./styles.scss";
 
-/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes) */
+/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes). */
 export interface CheckboxProps {
-  /** ID of the checkbox should be unique */
+  /** ID of the checkbox (should be unique) */
   id: string;
   // Note: cannot use "size" here because it's input's native property
   /** Size of the checkbox */
@@ -27,7 +27,7 @@ interface Props
 }
 
 /**
- * `Checkbox` component is a form input element, which allows you to select single values for submission. All native HTML `checkbox` input attributes apply.
+ * The `checkbox` component is a form input element that allows you to select single values for submission. All native HTML `checkbox` input attributes apply.
  */
 export const Checkbox: React.FC<Props> = ({
   id,

@stellar/design-system/src/components/CopyText/index.tsx

@@ -30,7 +30,7 @@ export interface CopyTextProps {
 }
 
 /**
- * Use `CopyText` component to copy a string. Done action label can be displayed in a tooltip, by default it will replace component’s label inline. We’re using [react-copy-to-clipboard](https://github.com/nkbt/react-copy-to-clipboard) to handle the copy part.
+ * Use the `CopyText` component to copy a string. Done action label can be displayed in a tooltip, by default it will replace the component’s label inline. We’re using [react-copy-to-clipboard](https://github.com/nkbt/react-copy-to-clipboard) to handle the copy part.
  */
 export const CopyText: React.FC<CopyTextProps> = ({
   textToCopy,

@stellar/design-system/src/components/IconButton/index.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import "./styles.scss";
 
-/** Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes) */
+/** Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). */
 export interface IconButtonProps {
   /** Icon element */
   icon: React.ReactNode;
@@ -22,7 +22,7 @@ interface Props
     React.ButtonHTMLAttributes<HTMLButtonElement> {}
 
 /**
- * `IconButton` is similar to the {@button Button} component, and is used to trigger an action. There are five variants (color is the only difference): `default`, `error`, `success`, `warning`, and `highlight`.
+ * `IconButton` is similar to the {@button Button} component and is used to trigger an action. There are five variants (color is the only difference): `default`, `error`, `success`, `warning`, and `highlight`.
  */
 export const IconButton: React.FC<Props> = ({
   icon,

@stellar/design-system/src/components/Input/index.tsx

@@ -4,7 +4,7 @@ import { Icon } from "../../icons";
 import { FieldNote } from "../utils/FieldNote";
 import "./styles.scss";
 
-/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes) */
+/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes). */
 export interface InputProps {
   /** ID of the input should be unique */
   id: string;
@@ -40,7 +40,7 @@ interface Props
 }
 
 /**
- * `Input` component is a form input element, which inherits all native HTML `input` element attributes.
+ * The `input` component is a form input element that inherits all native HTML `input` element attributes.
  */
 export const Input: React.FC<Props> = ({
   customInput,

@stellar/design-system/src/components/Layout/index.tsx

@@ -14,7 +14,7 @@ interface LayoutComponent {
 }
 
 /**
- * Use `Layout` component’s sub-components, such as `Content`, `Inset`, `Header`, and `Footer`, to build page layouts.
+ * Use the `Layout` component’s sub-components, such as `Content`, `Inset`, `Header`, and `Footer`, to build page layouts.
  */
 export const Layout: LayoutComponent = () => {
   // do nothing
@@ -40,7 +40,7 @@ export interface ContentProps {
 }
 
 /**
- * Page level content of the website (all other content goes in here). It is on the same level as header and footer.
+ * The page level content of the website (all other content goes in here). This content is on the same level as the header and footer.
  */
 export const Content: React.FC<ContentProps> = ({ children }: ContentProps) => (
   <div className="Layout__content">{children}</div>
@@ -83,7 +83,7 @@ const stringToCamelcase = (str: string) =>
     .replace(/\s+/g, "");
 
 /**
- * Header of the website with Stellar logo, project name, and theme switch.
+ * The header of the website with the Stellar logo, project name, and theme switch.
  */
 export const Header: React.FC<HeaderProps> = ({
   projectId,

@stellar/design-system/src/components/Link/index.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import "./styles.scss";
 
 /**
- * Including all valid [anchor element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes)
+ * Including all valid [anchor element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes).
  */
 export interface LinkProps {
   /** Content of the link */
@@ -28,7 +28,7 @@ interface Props
     React.AnchorHTMLAttributes<HTMLAnchorElement> {}
 
 /**
- * `Link` component is a styled HTML anchor (`a`) element. Use `Link` to open links or to navigate to other pages.
+ * The `Link` component is a styled HTML anchor (`a`) element. Use `Link` to open links or to navigate to other pages.
  *
  * `Link` with external `href` (starting with `http(s)` or `//`) will have attributes `rel="noreferrer noopener"` and `target="_blank"` automatically added.
  */

@stellar/design-system/src/components/Loader/index.tsx

@@ -8,7 +8,7 @@ export interface LoaderProps {
 }
 
 /**
- * Loader component color is set in CSS, and the size can also be set in CSS or through the `size` prop.
+ * The loader component color is set in CSS, and the size can also be set in CSS or through the `size` prop.
  */
 export const Loader: React.FC<LoaderProps> = ({ size }: LoaderProps) => {
   const customStyle = {

@stellar/design-system/src/components/Modal/index.tsx

@@ -67,7 +67,7 @@ export interface ModalProps {
 }
 
 /**
- * Modal is a dialog window with an overlay background, which is rendered on top of the rest of the website.
+ * `Modal` is a dialog window with an overlay background that is rendered on top of the rest of the website.
  *
  * Modal sub-components `Modal.Heading`, `Modal.Body`, and `Modal.Footer` help structure the modal content.
  */

@stellar/design-system/src/components/NavButton/index.tsx

@@ -3,7 +3,7 @@ import "./styles.scss";
 
 /** */
 export interface NavButtonProps {
-  /** ID of the component should be unique */
+  /** ID of the component (should be unique) */
   id: string;
   /** Title or label to show on hover */
   title: string;
@@ -18,7 +18,7 @@ export interface NavButtonProps {
 }
 
 /**
- * `NavButton` is used to trigger actions like toggle dark and light mode, close a modal, and toggle side navigation.
+ * `NavButton` triggers actions like toggling dark and light mode, closing a modal, and toggling side navigation.
  */
 export const NavButton: React.FC<NavButtonProps> = ({
   id,

@stellar/design-system/src/components/Notification/index.tsx

@@ -21,7 +21,7 @@ interface Props
 }
 
 /**
- * Use notification to draw user attention. There are five variants `primary`, `secondary`, `success`, `error`, and `warning`.
+ * Use `notification` to draw a user's attention. There are five variants `primary`, `secondary`, `success`, `error`, and `warning`.
  */
 export const Notification: React.FC<Props> = ({
   variant,

@stellar/design-system/src/components/Profile/index.tsx

@@ -24,7 +24,7 @@ export interface ProfileProps {
 }
 
 /**
- * Profile showing avatar with Stellar address.
+ * The `Profile` component shows an avatar with a Stellar address.
  */
 export const Profile: React.FC<ProfileProps> = ({
   publicAddress,

@stellar/design-system/src/components/ProjectLogo/index.tsx

@@ -11,7 +11,7 @@ export interface ProjectLogoProps {
 }
 
 /**
- * `ProjectLogo` with name and link is used in page header.
+ * `ProjectLogo` contains the name of the project and its link and are displayed in the page header.
  */
 export const ProjectLogo: React.FC<ProjectLogoProps> = ({
   title,

@stellar/design-system/src/components/RadioButton/index.tsx

@@ -1,9 +1,9 @@
 import React from "react";
 import "./styles.scss";
 
-/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes) */
+/** Including all valid [input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes). */
 export interface RadioButtonProps {
-  /** ID of the radio button should be unique */
+  /** ID of the radio button (should be unique) */
   id: string;
   /** Label of the radio button */
   label: string | React.ReactNode;
@@ -19,7 +19,7 @@ interface Props
 }
 
 /**
- * `RadioButton` component is a form input element, which allows you to select a single value from a group of options for submission. All native HTML `radio` input attributes apply.
+ * The `RadioButton` component is a form input element that allows you to select a single value from a group of options for submission. All native HTML `radio` input attributes apply.
  */
 export const RadioButton: React.FC<Props> = ({
   id,

@stellar/design-system/src/components/Select/index.tsx

@@ -4,9 +4,9 @@ import { FieldNote } from "../utils/FieldNote";
 import { Icon } from "../../icons";
 import "./styles.scss";
 
-/** Including all valid [select attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attributes) */
+/** Including all valid [select attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attributes). */
 export interface SelectProps {
-  /** ID of the select should be unique */
+  /** ID of the select (should be unique) */
   id: string;
   // Note: cannot use "size" here because it's input's native property
   /** Size of the select */
@@ -39,7 +39,7 @@ interface Props
 }
 
 /**
- * `Select` component is a form `select` element, which inherits all native HTML `select` element attributes.
+ * The `Select` component is a form `select` element that inherits all native HTML `select` element attributes.
  */
 export const Select: React.FC<Props> = ({
   id,

@stellar/design-system/src/components/Table/index.tsx

@@ -40,7 +40,7 @@ export interface TableProps<T> {
 }
 
 /**
- * Display sets of data in a table. Table data can be sorted and with pagination. If any of the table labels have `sortBy` flag enabled, the table becomes sortable.
+ * Display sets of data in a table. Table data can be sorted with pagination. If any of the table labels have the `sortBy` flag enabled, the table becomes sortable.
  */
 export const Table = <T extends Record<string, any>>({
   id = "table",

@stellar/design-system/src/components/Textarea/index.tsx

@@ -5,7 +5,7 @@ import "./styles.scss";
 
 /** Including all valid [textarea attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#attributes) */
 export interface TextareaProps {
-  /** ID of the textarea should be unique */
+  /** ID of the textarea (should be unique) */
   id: string;
   // Note: cannot use "size" here because it's input's native property
   /** Size of the textarea */
@@ -36,7 +36,7 @@ interface Props
 }
 
 /**
- * `Textarea` component is a multi-line text input element, which inherits all native HTML `textarea` element attributes.
+ * The `textarea` component is a multi-line text input element that inherits all native HTML `textarea` element attributes.
  */
 export const Textarea: React.FC<Props> = ({
   id,

@stellar/design-system/src/components/Toggle/index.tsx

@@ -3,7 +3,7 @@ import "./styles.scss";
 
 /** */
 export interface ToggleProps {
-  /** ID of the toggle should be unique */
+  /** ID of the toggle (should be unique) */
   id: string;
   /** If `true` the toggle state is "on" */
   checked: boolean;
@@ -24,7 +24,7 @@ interface Props
 }
 
 /**
- * `Toggle` component is similar to `Checkbox` component, which allows to toggle/switch between on and off states.
+ * The `Toggle` component is similar to `Checkbox` component, which allows you to toggle/switch between on and off states.
  */
 export const Toggle: React.FC<Props> = ({
   id,