@jobber/design 0.27.9 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/design",
-  "version": "0.27.9",
+  "version": "0.28.0",
   "description": "Design foundation for the Jobber Atlantis Design System",
   "license": "MIT",
   "main": "dist/index.js",
@@ -9,37 +9,44 @@
     "dist/*",
     "*.css",
     "foundation.*",
-    "icons/*"
+    "icons/*",
+    "src/*",
+    "foundation_config/*",
+    "tsconfig.json",
+    "*.js"
   ],
   "scripts": {
     "build": "npm run build:css && npm run build:css:icons && npm run build:colors && npm run build:cssTypes && npm run build:foundation && npm run build:iconCssStyle && npm run build:rollup",
     "build:rollup": "rollup --config",
-    "build:css": "postcss src/foundation.css --output foundation.css --use postcss-import",
+    "build:css": "postcss src/foundation.css --config foundation_config --output foundation.css",
     "build:css:icons": "postcss src/icons/*.css --dir icons/ --use postcss-import",
     "build:ts": "tsc --project .",
     "build:cssTypes": "tcm src/icons",
     "build:colors": "node buildColors.js",
     "build:foundation": "node buildFoundation.js && node jobberStyle.js && npm run build:foundationTypes && npm run build:addTypeLinterExceptions && npm run build:addFoundationLinterExceptions && npm run build:removeTempFiles",
-    "build:foundationTypes": "tsc --declaration --emitDeclarationOnly --allowJs foundation.js --outDir .",
+    "build:foundationTypes": "tsc --declaration --emitDeclarationOnly --allowJs foundation.js --outDir . --skipLibCheck",
     "build:addTypeLinterExceptions": "(printf '/* tslint:disable */\n/* eslint-disable */\n/* This file is automatically generated and should not be edited. */\n'; cat foundation.d.ts) > foundation.d.ts.temp",
     "build:addFoundationLinterExceptions": "(printf '/* tslint:disable */\n/* eslint-disable */\n/* This file is automatically generated and should not be edited. */\n'; cat foundation.js) > foundation.js.temp",
     "build:removeTempFiles": "rm -f src/foundation.js && mv foundation.d.ts.temp foundation.d.ts && mv foundation.js.temp foundation.js",
     "build:iconCssStyle": "node buildIconStyles.js && npm run build:iconCssStyleTypes",
-    "build:iconCssStyleTypes": "tsc --declaration --emitDeclarationOnly --allowJs src/icons/iconStyles.ts --outDir ./src/icons",
-    "clean": "rm -rf dist/* icons/* colors.js foundation.css iconStyles.* tsconfig.tsbuildinfo",
-    "prepare": "npm run clean; npm run build",
+    "build:iconCssStyleTypes": "tsc --declaration --emitDeclarationOnly --allowJs src/icons/iconStyles.ts --outDir ./src/icons --skipLibCheck",
+    "clean": "rm -rf dist/* icons/* colors.js foundation.* iconStyles.* tsconfig.tsbuildinfo ./src/icons/iconStyles.*",
+    "prepare": "npm run clean && npm run build",
+    "postinstall": "npm run prepare",
     "ci:typescript-compile": "npm run build:ts"
   },
-  "dependencies": {
-    "classnames": "^2.2.6"
+  "optionalDependencies": {
+    "@jobber/fonts": "^1.0.0"
   },
-  "devDependencies": {
+  "dependencies": {
     "@types/classnames": "^2.2.10",
     "autoprefixer": "^9.5.1",
+    "classnames": "^2.2.6",
     "css-to-react-native-transform": "^2.0.0",
     "postcss": "^7.0.36",
     "postcss-calc": "7.0.2",
     "postcss-cli": "^6.1.2",
+    "postcss-copy": "^7.1.0",
     "postcss-custom-properties": "^8.0.10",
     "postcss-import": "^12.0.1",
     "postcss-preset-env": "^6.6.0",
@@ -54,5 +61,5 @@
     "typed-css-modules": "^0.7.0",
     "typescript": "^3.8.3"
   },
-  "gitHead": "f504df8432313e62043d66f3f1ea617c43600b2c"
+  "gitHead": "3221cfb57c036d3cc651cb0eba3dd642554dc02b"
 }

package/rollup.config.js

@@ -0,0 +1,41 @@
+/* eslint-disable import/no-default-export */
+import multiInput from "rollup-plugin-multi-input";
+import typescript from "rollup-plugin-typescript2";
+import postcss from "rollup-plugin-postcss";
+import commonjs from "rollup-plugin-commonjs";
+import copy from "rollup-plugin-copy";
+
+export default {
+  input: `src/index.ts`,
+  plugins: [
+    multiInput(),
+    typescript({
+      declarationDir: "dist",
+    }),
+    postcss({
+      modules: { generateScopedName: "[hash:base64]" },
+      plugins: [
+        require("postcss-import"),
+        require("autoprefixer"),
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        require("postcss-preset-env")({
+          stage: 1,
+          preserve: true,
+        }),
+      ],
+    }),
+    commonjs({
+      ignore: [],
+    }),
+    copy({
+      targets: [{ src: "src/icons/*.css.d.ts", dest: "dist/icons" }],
+    }),
+  ],
+  output: [
+    {
+      dir: "dist",
+      format: "cjs",
+    },
+  ],
+  external: ["react", "classnames", "@jobber/fonts"],
+};

package/src/Borders.mdx

@@ -0,0 +1,65 @@
+---
+name: Borders
+menu: Design
+route: /borders
+---
+
+# Borders and Dividers
+
+You may find that a visual indicator is helpful to segment elements in an
+interface. We have elements to help you do so in a consistent way across
+platforms: borders and dividers.
+
+## Borders
+
+### Border Widths
+
+To add a border to an element, use the border-width variables in the component's
+styling to ensure consistent border thickness throughout Jobber.
+
+Border style should be `solid` unless a specific use case calls for some other
+format, such as indicating a dropzone on the
+[`InputFile` component](https://atlantis.getjobber.com/components/input-file).
+
+export function Example({ of: size }) {
+  const style = {
+    width: "100%",
+    height: "var(--space-miniscule)",
+    borderBottomStyle: "solid",
+    borderBottomWidth: `var(--border-${size})`,
+    borderBottomColor: "var(--color-grey--lighter)",
+  };
+  return <div style={style} />;
+}
+
+| Width               | Visual                    |
+| :------------------ | :------------------------ |
+| `--border-base`     | <Example of="base" />     |
+| `--border-thick`    | <Example of="thick" />    |
+| `--border-thicker`  | <Example of="thicker" />  |
+| `--border-thickest` | <Example of="thickest" /> |
+
+The `base` border width should be used for most use cases (see
+[`Card`](https://atlantis.getjobber.com/components/card) and
+[`List` items](https://atlantis.getjobber.com/components/list) for in-context
+examples). You may want to consider thicker borders when the border conveys a
+closing of already-divided sections, such as a
+[`Table` footer](https://atlantis.getjobber.com/components/table).
+
+### Border Colors
+
+Borders should use `--color-border)` for most use cases.
+[`List` sections](https://atlantis.getjobber.com/components/list#sectioned-list-items),
+[`Table` headers](https://atlantis.getjobber.com/components/table) and other
+scenarios where other bordered content is being further subsectioned should use
+`--color-border--section)`.
+
+For accessibility reasons, ensure that color usage is not the only way to
+[convey meaning](https://webaim.org/articles/contrast/#sc141) in an interface.
+
+## Dividers
+
+The [`Divider` component](https://atlantis.getjobber.com/components/divider)
+will help you segment sections of content without writing additional styling.
+This component will render a horizontal rule that takes up the full available
+width.

package/src/Colors.mdx

@@ -0,0 +1,295 @@
+---
+name: Colors
+menu: Design
+route: /colors
+---
+
+import { ColorSwatches } from "@jobber/docx";
+import { ColorSwatches as Swatch } from "@jobber/docz-tools";
+
+import colors from "../colors";
+
+# Colors
+
+Color can provide a visual cue for users to navigate and understand an
+interface.
+
+Atlantis is built with a
+[semantic layer](https://dev.to/ynab/a-semantic-color-system-the-theory-hk7)
+overtop of a base palette. Use the semantic color values defined in the usage
+guidelines whenever possible to ensure you are using colors for their intended
+purpose.
+
+## Accessibility
+
+Color should never be the single means of conveying information in an interface.
+Use labels, iconography, or hints for assistive technology alongside color to
+ensure your content can be understood by everyone.
+
+## Usage guidelines
+
+### Typography
+
+Typographic elements in Jobber should use consistent colors to ensure
+readability.
+
+#### Heading
+
+<Swatch colors={[`--color-heading`]} />
+
+Headings have a bold, high-contrast color to cement their hierarchy.
+
+#### Text
+
+<Swatch colors={[`--color-text`, "--color-text--secondary"]} />
+
+A slightly softer color is used for body text for greater readability.
+
+Text that is relevant but less important ("secondary") can be lower-contrast to
+suggest its’ reduced importance. This color should only be used when there is
+more important text content already present.
+
+##### Text--Reverse
+
+<Swatch
+  colors={[`--color-text--reverse`, "--color-text--reverse--secondary"]}
+/>
+
+When used against a [reversed surface](#surface--reverse), reversed text should
+be used to maintain readability.
+
+Reverse text also has a secondary value following the same rules outlined for
+standard secondary text.
+
+### Interactions
+
+Use these colors in buttons and form controls to communicate the presence and
+meaning of interaction. In cases such as [Buttons](/components/button) where the
+interactive color is functioning as a background color or the text color, the
+alternative color should be `--color-white`\*.
+
+_\*This is a known contrast issue in the case of Interactive/White, as we have
+currently tied our interactive color to our brand color._
+
+#### Interactive
+
+<Swatch colors={[`--color-interactive`, "--color-interactive--hover"]} />
+
+The default color used for interactive elements.
+
+##### Interactive--Subtle
+
+<Swatch
+  colors={[`--color-interactive--subtle`, "--color-interactive--subtle--hover"]}
+/>
+
+Use for interactive elements that should be less visually pronounced, such as an
+icon action in main navigation, or buttons to dismiss or cancel a workflow.
+
+#### Destructive
+
+<Swatch colors={[`--color-destructive`, "--color-destructive--hover"]} />
+
+Use to signify that an interaction will destroy something in the users’ account
+or workflow.
+
+#### Disabled
+
+<Swatch colors={[`--color-disabled`, "--color-disabled--secondary"]} />
+
+Use to signify that an interactive element is disabled.
+
+Use `secondary` when a disabled element needs more than one color to be readable
+in a disabled state; for example, a button's background and label colors must be
+different.
+
+#### Focus
+
+<div
+  style="width:100%;
+  height:var(--space-extravagant);
+  background-color:var(--color-surface);
+  box-shadow:var(--shadow-focus);"
+></div>
+
+`--color-focus`
+
+Used by the `--shadow-focus` property to indicate that an element has received
+focus. Avoid using `--color-focus` directly on UI elements.
+
+### Status
+
+Use these colors in labels, icons, filters, alerts, and other elements where
+color can add meaning to the state of the system or an item in the system.
+
+All status colors have a main color, a surface color, and an on-surface color.
+The on-surface color should be used for an element when it sits inside of an
+element with the status' surface color to maintain a cohesive tone and ensure
+sufficient color contrast.
+
+#### Critical
+
+<Swatch
+  colors={[
+    "--color-critical",
+    "--color-critical--surface",
+    "--color-critical--onSurface",
+  ]}
+/>
+
+Action required; user must see this status to be unblocked.
+
+#### Warning
+
+<Swatch
+  colors={[
+    "--color-warning",
+    "--color-warning--surface",
+    "--color-warning--onSurface",
+  ]}
+/>
+
+Action _may_ be required as a consequence of current state.
+
+#### Success
+
+<Swatch
+  colors={[
+    "--color-success",
+    "--color-success--surface",
+    "--color-success--onSurface",
+  ]}
+/>
+
+No action required; an action has completed successfully.
+
+#### Informative
+
+<Swatch
+  colors={[
+    "--color-informative",
+    "--color-informative--surface",
+    "--color-informative--onSurface",
+  ]}
+/>
+
+No action required; but helpful to know about.
+
+#### Inactive
+
+<Swatch
+  colors={[
+    "--color-inactive",
+    "--color-inactive--surface",
+    "--color-inactive--onSurface",
+  ]}
+/>
+
+No action required; not part of an active workflow.
+
+### Surfaces
+
+Surfaces are the background-colors of almost every element in Jobber. Overlays
+act as supplementary surfaces that mask areas of the interface to adjust visual
+focus.
+
+#### Surface
+
+<Swatch
+  colors={[
+    "--color-surface",
+    "--color-surface--hover",
+    "--color-surface--active",
+  ]}
+/>
+
+Most elements in Jobber have a light surface to indicate their nearness to the
+user; if interactive, they have a hover color and an active color to indicate
+state.
+
+#### Surface--Background
+
+<Swatch colors={["--color-surface--background"]} />
+
+A slightly darker surface gives a receded appearance relative to main surfaces.
+
+#### Surface--Reverse
+
+<Swatch colors={["--color-surface--reverse"]} />
+
+Use a reversed surface when a strong contrast is needed with the rest of the
+application.
+
+#### Overlay
+
+<Swatch colors={["--color-overlay"]} />
+
+Use to mask an area of the interface to promote focus to a foreground action,
+such as a [Modal](/components/modal)’s appearance. Overlay includes built-in
+opacity values.
+
+#### Overlay--Dimmed
+
+<Swatch colors={["--color-overlay--dimmed"]} />
+
+A transparent version of [Surface](#surface), this masks an area of the
+interface to indicate inactivity (i.e. waiting for updates). Overlay--Dimmed
+includes built-in opacity values.
+
+### Borders
+
+Defining the edges of elements on the same elevation plane, border colors are
+the subtle maintainers of layout structure. Learn more about borders in our
+[Borders guide.](/borders)
+
+#### Border
+
+<div
+  style="width:100%;
+  height:var(--space-extravagant);
+  background-color:var(--color-surface);
+  border: var(--border-base) solid var(--color-border)"
+></div>
+
+`--color-border`
+
+Most borders should use `--color-border` for subtle definition.
+
+#### Border--Section
+
+<div
+  style="width:100%;
+  height:var(--space-extravagant);
+  background-color:var(--color-surface);
+  border: var(--border-base) solid var(--color-border--section)"
+></div>
+
+`--color-border--section`
+
+Use `--color-border--section` where other bordered content is being further
+sectioned, such as table headers or list sections.
+
+### Brand
+
+Use these colors to represent the Jobber brand visual language.
+
+#### Brand
+
+<Swatch colors={["--color-brand"]} />
+
+The primary color associated with our brand, from website to ads to product; AKA
+“Jobber Green”.
+
+#### Brand--Highlight
+
+<Swatch colors={["--color-brand--highlight"]} />
+
+Use to highlight an element in a way that aligns with our website. Use with
+caution, it’s _bright!_
+
+<br />
+<br />
+
+## Swatch list
+
+<ColorSwatches colors={colors.customProperties} />

package/src/Elevations.mdx

@@ -0,0 +1,107 @@
+---
+name: Elevation
+menu: Design
+route: /elevation
+---
+
+# Elevation
+
+> Elevation is the relative distance between two surfaces along the z-axis.
+> –[Material Design](https://material.io/design/environment/elevation.html)
+
+In Atlantis, our web components use elevation to specify position on the z-axis,
+with shadows separately responsible for conveying that depth. Our mobile
+components combine these two concepts in keeping with Android and iOS patterns.
+
+Generally speaking, the "higher" an element sits in the z-axis, the broader its'
+shadow should spread, to reflect diffusion in the distance between the element
+and the ground. As an element gets nearer to the ground, or "lower", the
+shadow's spread should reduce and the shadow may appear darker.
+
+We also include a _slight_ y-axis offset of elevation shadows to imply that the
+light source is coming from an angle slightly over the head of a user looking
+directly into the screen.
+
+### Low
+
+<Example of="low" />
+
+A low element may have a slight elevation, but is not necessarily something that
+will glide across the surface. A basic card on mobile that is not tappable would
+be represented as having a "low" elevation.
+
+### Base
+
+<Example of="base" />
+
+This shadow should be used for most instances of shadows to convey that an
+element is floating overtop related elements, such as in
+[Menu](/components/menu) or [Popover](/components/popover). An element with a
+base elevation is likely interactive, and this level can indicate and invite the
+use of gesture controls in a mobile app.
+
+### High
+
+<Example of="high" />
+
+High elements should be elements that float overtop the entire interface,
+typically with a fixed position. The "high" elevation indicates that the element
+has broken the plane of the view. A good example for web would be
+[Toast](/components/toast).
+
+## Web
+
+export function Value({ of: type }) {
+  const styles = getComputedStyle(document.documentElement);
+  const getValue = styles.getPropertyValue(`--elevation-${type}`);
+  return <React.Fragment>{getValue}</React.Fragment>;
+}
+
+### Z-index elevation
+
+The following table lists Atlantis components that have a z-index specified.
+
+These values can be referenced when you are building a view so that you can
+ensure the elements you are using do not unintentionally overlap, if you end up
+using z-index on non-Atlantis components.
+
+| Component        | Value                  |
+| :--------------- | :--------------------- |
+| Form field label | <Value of="base" />    |
+| Menu             | <Value of="menu" />    |
+| Modal            | <Value of="modal" />   |
+| Tooltip          | <Value of="tooltip" /> |
+| Toast            | <Value of="toast" />   |
+
+export function Example({ of: shadow }) {
+  const style = {
+    width: "100%",
+    height: "var(--space-largest)",
+    backgroundColor: "var(--color-white)",
+    boxShadow: `var(--shadow-${shadow})`,
+  };
+  return <div style={style} />;
+}
+
+export function Elevation({ of: shadow }) {
+  const element = document.createElement("div");
+  element.style.boxShadow = `var(--shadow-${shadow})`;
+  document.body.appendChild(element);
+}
+
+### Shadow elevation
+
+These are the box-shadows rendered to signify elevation on given UI elements;
+they map to our low/base/high pattern.
+
+| Name            | Visual                |
+| :-------------- | :-------------------- |
+| `--shadow-low`  | <Example of="low" />  |
+| `--shadow-base` | <Example of="base" /> |
+| `--shadow-high` | <Example of="high" /> |
+
+## Mobile
+
+For mobile designs, the concept of elevation applies to both shadows and
+hierarchy of the element along the z-index. Android accepts a single "elevation"
+value, while iOS accepts more granular shadow values similar to CSS.

package/src/Radii.mdx

@@ -0,0 +1,40 @@
+---
+name: Radius
+menu: Design
+route: /border-radius
+---
+
+# Border Radius
+
+We favour a subtle rounding of corners wherever possible as a nod to the blunt
+visual style of our marketing properties to afford a smoother transition from
+the signup flow into the product. To achieve this appearance, use
+`--radius-base`.
+
+This base radius can be found in almost all of our components that have a
+defined "edge": [Button](/components/button), [Card](/components/Card),
+[InputText](/components/input-text), and [Menu](/components/menu) are all
+examples of this in practice.
+
+Larger rounded corners should be used sparingly, but are available for cases
+where the user may expect a smoother corner, such as
+[ProgressBar](/components/progress-bar). `--radius-circle` can be used for
+circular elements like [Radio](/components/radio-group) options or the "pip" in
+[Switch](/components/switch).
+
+export function Example({ of: radius }) {
+  const style = {
+    width: "var(--space-large)",
+    height: "var(--space-large)",
+    backgroundColor: "var(--color-indigo)",
+    borderRadius: `var(--radius-${radius})`,
+  };
+  return <div style={style} />;
+}
+
+| Radius            | Visual                  |
+| :---------------- | :---------------------- |
+| `--radius-base`   | <Example of="base" />   |
+| `--radius-large`  | <Example of="large" />  |
+| `--radius-larger` | <Example of="larger" /> |
+| `--radius-circle` | <Example of="circle" /> |

package/src/ResponsiveBreakpoints.mdx

@@ -0,0 +1,48 @@
+---
+name: Breakpoints
+menu: Design
+route: /breakpoints
+---
+
+import { Button } from "@jobber/components/Button";
+
+# Responsive Breakpoints
+
+**To make most components responsive, you will want to use the
+[useResizeObserver hook](/hooks/use-resize-observer) so that the component can
+be responsive based on its container.**
+
+However, there are times the component will not care about its container and
+want to be responsive based on the browser size. For this you will want to use a
+breakpoint in the CSS.
+
+**Note** Components should be styled mobile first, meaning that it should be
+styled for small screens and then scaled up. This means that the `--handhelds`
+breakpoint should be rarely considered.
+
+**Note** Media queries can be nested inside selectors. This will help with
+clarity when reading.
+
+| Breakpoint         | Width       |
+| :----------------- | :---------- |
+| `--handhelds`      | `< 640px`   |
+| `--medium-screens` | `>= 640px`  |
+| `--wide-screens`   | `>= 1024px` |
+
+## Usage
+
+```css
+.foo {
+  ...;
+  /** small screens first **/
+  padding: var(--space-base);
+
+  @media (--medium-screens) {
+    padding: var(--space-large);
+  }
+
+  @media (--wide-screens) {
+    padding: var(--space-extravagant);
+  }
+}
+```