@preply/ds-docs 7.1.0 → 8.0.0

package/pages/30.guides/60.components/index.mdx

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Introduction" />
+
+# Developing custom components with DS primitives
+
+The DS provides lower level primitives for building custom components that you can use
+if existing DS components are not enough to implement complex or unique designs.
+Using these primitives ensures that your new custom components will still be
+compatible with our visual design language and continue receiving updates as the
+Design System evolves.
+
+However, you should always prefer using the existing components to just using
+these lower level primitives.
+
+Furthermore, if you believe your component can be a good addition for the Design System:
+
+- Read the [contribution guide](/story/contributing--page)
+- Reach out to [#design-system-public](https://preply.slack.com/archives/C024EAEHP6V)
+- Use Less.js instead of StyledComponents.
+- Become familiar with the DS [internal guidelines and conventions](https://preply.atlassian.net/wiki/spaces/DS/pages/2778300873/Guidelines) and the step by step [runbooks](https://preply.atlassian.net/wiki/spaces/DS/pages/3250815332/Runbooks).
+
+Check the guidelines below for some generic strategies to minimize the need for custom CSS.
+
+The following guides provide further information on how to use the lower level primitives according to your stack:
+
+- [Less.js](/story/guides-custom-components-less-js-intro--page)
+- [StyledComponents](/story/guides-custom-components-styledcomponents-intro--page)

package/pages/30.guides/60.components/less/breakpoints.mdx

@@ -0,0 +1,43 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Less.js/Breakpoints" />
+
+# Less.js: Breakpoints
+
+**Note:** Storybook renders this page inside of an `iframe`! The width taken into account by the media query is that of the `iframe` and not the full viewport window. Hide Storybook's navigation sidebar (or pop out this page) to preview the media query against the full browser width.
+
+---
+
+Import the `breakpoints.less` file from the `@preply/ds-web-core` package and use the breakpoint name as a mixin:
+
+```css
+@import '@preply/ds-web-core/dist/generated/breakpoints.less';
+
+.container {
+    display: flex;
+    flex-direction: column;
+
+    @media @medium-l {
+        flex-direction: row;
+    }
+}
+```
+
+Alternatively you can use the `@breakpoints` variable to access the pixel values directly.
+
+We recommend using only `min-width` media queries in order to structure your code with a "mobile first" approach.
+
+Check out this [small article (3 min read)](https://medium.com/swlh/use-min-width-not-max-width-in-your-css-e6898fcf6a78) for a quick explanation why.
+
+```css
+@import '@preply/ds-web-core/dist/generated/breakpoints.less';
+
+.container {
+    display: flex;
+    flex-direction: column;
+
+    @media (min-width: @breakpoints[medium-l]) {
+        flex-direction: row;
+    }
+}
+```

package/pages/30.guides/60.components/less/hover.mdx

@@ -0,0 +1,19 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Less.js/Hover" />
+
+# Less.js: Hover
+
+Import `hover.less` from `@preply/ds-web-core` and use the `onHover` mixin to show hover only for **Desktops with mouse**:
+
+```css
+@import '@preply/ds-web-core/dist/generated/hover.less';
+
+.some-css-class {
+    background: lightblue;
+
+    .onHover({
+        background: lightpink;
+    });
+}
+```

package/pages/30.guides/60.components/less/tokens.mdx

@@ -0,0 +1,24 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Less.js/Tokens" />
+
+# Less.js: Tokens
+
+You can import the tokens directly from `@preply/ds-web-core`:
+
+```css
+@import '@preply/ds-web-core/dist/generated/tokens.less';
+
+.MyComponent {
+    color: @action-variant-primary-color;
+    background-color: @action-variant-primary-bgColor;
+    border-radius: @action-base-borderRadius;
+}
+```
+
+This file declares one `@variable` per token, that simply points to the CSS var `var(--12345)`.
+
+Note that the actual value depends on the parent [ThemeProvider](/story/api-ds-web-core-providers-themeprovider--page) and [ColorSchemeProvider](/story/api-ds-web-core-providers-colorschemeprovider--page).
+
+Use the [Token Explorer](/story/guides-token-explorer--page) to search tokens by name, id, or value
+(make sure you have the correct theme selected).

package/pages/30.guides/60.components/scss/breakpoints.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/SCSS/Breakpoints" />
+
+# SCSS: Breakpoints
+
+**Note:** Storybook renders this page inside of an `iframe`! The width taken into account by the media query is that of the `iframe` and not the full viewport window. Hide Storybook's navigation sidebar (or pop out this page) to preview the media query against the full browser width.
+
+---
+
+<details style={{ marginBlock: '24px' }}>
+    <summary>🚧 SCSS Support is experimental 🚧</summary>
+
+SCSS support was introduced due to the lack of support for LESS in the Next.js app router.
+
+Please avoid using it for other purposes, as the API may change or be removed in the future.
+
+</details>
+
+Import `breakpoints.less` from `@preply/ds-web-core` and use the breakpoint mixin:
+
+```css
+@use '@preply/ds-web-core/dist/generated/breakpoints' as *;
+
+.container {
+    display: flex;
+    flex-direction: column;
+
+    @include medium-l {
+        flex-direction: row;
+    }
+}
+```
+
+Alternatively you can use the `$breakpoints` map to access the pixel values directly:
+
+```css
+@use '@preply/ds-web-core/dist/generated/breakpoints' as *;
+
+.some-css-class {
+    display: flex;
+    flex-direction: column;
+
+    @media (min-width: map-get($breakpoints, medium-l)) {
+        flex-direction: row;
+    }
+}
+```
+
+We recommend using only `min-width` media queries in order to structure your code with a "mobile first" approach.
+
+Check out this [small article (3 min read)](https://medium.com/swlh/use-min-width-not-max-width-in-your-css-e6898fcf6a78) for a quick explanation why.

package/pages/30.guides/60.components/scss/hover.mdx

@@ -0,0 +1,30 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Scss/Hover" />
+
+# SCSS: Hover
+
+<details style={{ marginBlock: '24px' }}>
+    <summary>🚧 SCSS Support is experimental 🚧</summary>
+
+SCSS support was introduced due to the lack of support for LESS in the Next.js app router.
+
+Please avoid using it for other purposes, as the API may change or be removed in the future.
+
+</details>
+
+Import `hover.scss` from `@preply/ds-web-core` and use the `onHover` mixin to show hover only for **Desktops with mouse**:
+
+```css
+@use '@preply/ds-web-core/dist/generated/tokens' as *;
+@use '@preply/ds-web-core/dist/generated/hover' as *;
+
+.MyComponent {
+    background: lightblue;
+    padding: $spacing-16;
+
+    @include onHover {
+        background: lightpink;
+    }
+}
+```

package/pages/30.guides/60.components/scss/migrating-from-less.mdx

@@ -0,0 +1,55 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/Scss/Migrating from LESS" />
+
+# Migrating from LESS
+
+## Imports
+
+Update imports to use `@use` at-rule and remove .less extension:
+
+```css
+- @import '~@preply/ds-web-core/dist/generated/tokens.less';
++ @use '@preply/ds-web-core/dist/generated/tokens' as *;
+```
+
+## Tokens
+
+Update token variables to use `$` prefix:
+
+```css
+.MyComponent {
+    - color: @color-text-primary;
+    + color: $color-text-primary;
+}
+```
+
+## Mixins
+
+Update mixins to use `@include` at-rule:
+
+#### Breakpoints
+
+```css
+.MyComponent {
+    - @media @medium-l {
+    + @include medium-l {
+          display: flex;
+    }
+}
+```
+
+#### Hover
+
+```css
+.MyComponent {
+    - transition: opacity @motion-components-interaction;
+    - .onHover({
+    -     opacity: 1;
+    - });
+    + transition: opacity $motion-components-interaction;
+    + @include onHover {
+    +     opacity: 1;
+    + }
+}
+```

package/pages/30.guides/60.components/scss/tokens.mdx

@@ -0,0 +1,33 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/SCSS/Tokens" />
+
+# SCSS: Tokens
+
+<details style={{ marginBlock: '24px' }}>
+    <summary>🚧 SCSS Support is experimental 🚧</summary>
+
+SCSS support was introduced due to the lack of support for LESS in the Next.js app router.
+
+Please avoid using it for other purposes, as the API may change or be removed in the future.
+
+</details>
+
+You can import the tokens directly from `@preply/ds-web-core`:
+
+```css
+@use '@preply/ds-web-core/dist/generated/tokens' as *;
+
+.MyComponent {
+    color: $action-variant-primary-color;
+    background-color: $action-variant-primary-bgColor;
+    border-radius: $action-base-borderRadius;
+}
+```
+
+This file declares one `$variable` per token, that simply points to the CSS var `var(--12345)`.
+
+Note that the actual value depends on the parent [ThemeProvider](/story/api-ds-web-core-providers-themeprovider--page) and [ColorSchemeProvider](/story/api-ds-web-core-providers-colorschemeprovider--page).
+
+Use the [Token Explorer](/story/guides-token-explorer--page) to search tokens by name, id, or value
+(make sure you have the correct theme selected).

package/pages/30.guides/60.components/styled-components/breakpoints.mdx

@@ -0,0 +1,45 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/StyledComponents/Breakpoints" />
+
+# StyledComponents: Breakpoints
+
+**Note:** Storybook renders this page inside of an `iframe`! The width taken into account by the media query is that of the `iframe` and not the full viewport window. Hide Storybook's navigation sidebar (or pop out this page) to preview the media query against the full browser width.
+
+---
+
+Import `minWidth` from `@preply/ds-web-core` and use it as a 'mixin':
+
+```ts
+import styled from 'styled-components';
+import { minWidth } from '@preply/ds-web-core';
+
+export const MyComponent = styled.div`
+    display: flex;
+    flex-direction: column;
+
+    ${minWidth('medium-l')} {
+        flex-direction: row;
+    }
+`;
+```
+
+Alternatively you can assemble the media query by importing the `BREAKPOINT` variable from `@preply/ds-core`:
+
+```ts
+import styled from 'styled-components';
+import { BREAKPOINT } from '@preply/ds-core';
+
+export const MyComponent = styled.div`
+    display: flex;
+    flex-direction: column;
+
+    @media (min-width: ${BREAKPOINT['medium-l']}px) {
+        flex-direction: row;
+    }
+`;
+```
+
+We recommend using only `min-width` media queries in order to structure your code with a "mobile first" approach.
+
+Check out this [small article (3 min read)](https://medium.com/swlh/use-min-width-not-max-width-in-your-css-e6898fcf6a78) for a quick explanation why.

package/pages/30.guides/60.components/styled-components/hover.mdx

@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/StyledComponents/Hover" />
+
+# StyledComponents: Hover
+
+Import `onHover(content: string)` from `@preply/ds-web-core` and use the mixin to show hover only for **Desktops with mouse**:
+
+```ts
+import styled from 'styled-components';
+import { onHover } from '@preply/ds-web-core';
+
+export const MyComponent = styled.div`
+    background: lightblue;
+
+    ${onHover(`
+        background: lightpink;
+    `)}
+`;
+```

package/pages/30.guides/60.components/styled-components/intro.mdx

@@ -0,0 +1,49 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/StyledComponents/Intro" />
+
+# Developing custom components with StyledComponents
+
+Make sure you read [Guide: Developing custom components with DS primitives](/story/guides-custom-components-introduction--page)
+
+## Guidelines
+
+**Do:** Use `minWidth` responsive mixin ([Read more](/story/guides-custom-components-styledcomponents-responsive--page)).
+
+```tsx
+import { minWidth } from '@preply/ds-web-core';
+
+export const MyStyledComponentWithBreakpoints = styled.div`
+    ${minWidth('medium-l')} {
+        ...
+    }
+`;
+```
+
+**Do:** Use token variables via `getTokenVar()` ([Read more](/story/guides-custom-components-styledcomponents-tokens--page)).
+
+If you're working with a designer you can see [references to tokens](/story/quickstart-for-engineers--page#reading-figma-files)
+in their Figma files. Use the [Token Explorer](/story/guides-token-explorer--page) to search tokens
+by name, id, or value (make sure you have the correct theme selected).
+
+```css
+@import '@preply/ds-web-core/dist/generated/tokens.less';
+```
+
+**Don't**: Use `max-width` breakpoints
+
+```css
+@media (max-width: @breakpoints[medium-l]) {
+    /* ... */
+}
+```
+
+**Don't**: Use `@preply/ui` breakpoints or variables.
+
+```css
+border-radius: @border-radius-m;
+
+@media (min-width: @responsive-mobile-normal) {
+    /* ... */
+}
+```

package/pages/30.guides/60.components/styled-components/tokens.mdx

@@ -0,0 +1,22 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Custom Components/StyledComponents/Tokens" />
+
+# StyledComponents: Tokens
+
+The [getTokenVar](/docs/utilities-gettokenvar--docs) utility gives you access to design tokens:
+
+```tsx
+import styled from 'styled-components';
+import { action, root } from '@preply/ds-core';
+import { getTokenVar as t } from '@preply/ds-web-core';
+
+export const MyComponent = styled.div`
+    padding: ${t(root.space[padding])};
+    color: ${t(action.variant.primary.color)};
+    background-color: ${t(action.variant.primary.bgColor)};
+    border-radius: ${t(action.base.borderRadius)};
+`;
+```
+
+This function actually returns the CSS variable for a token—eg. `var(--12345)`.

package/pages/30.guides/70.assets/00.favicons.guide.mdx

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Assets/Favicons" />
+
+# Favicons
+
+The optimised assets are available under **preply.com** in the formats required by modern and legacy browsers, as well as Android and iOS devices.
+
+Refer to [How to Favicon in 2022: Six files that fit most needs](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) for a detailed breakdown of the formats.
+
+## Variants
+
+Pick the approriate snippet and add it to the `<head>` section of your application.
+
+### Preply logo
+
+<img src="https://static.preply.com/ds/icons/favicon.svg" alt="Preply logo icon" />
+
+```html
+<!-- Preply Favicons /story/guides-assets-favicons--page -->
+<link rel="icon" href="https://static.preply.com/ds/icons/rebrand-23-v0/favicon.ico" sizes="any" />
+<link
+    rel="icon"
+    href="https://static.preply.com/ds/icons/rebrand-23-v0/favicon.svg"
+    type="image/svg+xml"
+/>
+<link
+    rel="apple-touch-icon"
+    href="https://static.preply.com/ds/icons/rebrand-23-v0/icon-180.pngg"
+/>
+<link rel="manifest" href="https://static.preply.com/ds/icons/rebrand-23-v0/web.manifest.json" />
+```

package/pages/30.guides/70.assets/10.fonts.guide.mdx

@@ -0,0 +1,59 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Assets/Fonts" />
+
+# Fonts
+
+The optimised assets are available under **preply.com** in the formats required by modern and legacy browsers.
+
+Refer to [Create new universal brand fonts](https://preply.atlassian.net/l/cp/0sQoEgGa) for a detailed breakdown of the formats, optimisations and technical decisions.
+
+You should only follow these instructions if Preply Design System is NOT installed (and can not be installed), in the application.
+
+In all other cases follow the [Installation Guides](/story/guides-installation-applications--page).
+
+## Tokyo UI (reBrand) fonts
+
+The Tokyo UI fonts are applied only for descendants of elements with the `data-preply-brand="tokyo"` attribute.
+
+```html
+<div data-preply-ds-theme="tokyo-ui">
+    <!-- All the children use the new fonts -->
+</div>
+```
+
+[DES-1108](https://preply.atlassian.net/browse/DES-1108) will fix this.
+
+## Using the assets
+
+First, in the `index.html` file, as close as possible to the start of the `<head>` tag, add:
+
+```html
+<!-- Preply Fonts /story/guides-assets-fonts--page -->
+<link rel="preconnect" href="https://static.preply.com" />
+<link rel="preload" href="https://static.preply.com/ds/global.css" as="style" />
+<link
+    rel="preload"
+    href="https://static.preply.com/ds/fonts/en/PreplyInter.var.woff2"
+    as="font"
+    type="font/woff2"
+    crossorigin
+/>
+<link rel="stylesheet" href="https://static.preply.com/ds/global.css" />
+```
+
+This will make `PreplyInter` available for browsers but not yet apply it to everything on the page. Only text created withing Design System's components will use `PreplyInter` typeface.
+
+Add the following styles as well, also at the top of your cascade, to apply our brand to all the text on the page.
+
+```css
+* {
+    font-family: 'PreplyInter', sans-serif;
+}
+
+@supports (font-variation-settings: normal) {
+    * {
+        font-family: 'PreplyInterV', sans-serif;
+    }
+}
+```

package/pages/30.guides/70.assets/11.languageFont.explorer.stories.tsx

@@ -0,0 +1,15 @@
+import { Meta, StoryFn } from '@storybook/react-vite';
+import React from 'react';
+import { FontForLanguages } from './components/FontForLanguages';
+
+const meta: Meta<typeof FontForLanguages> = {
+    title: 'Guides/Assets/FontForLanguages',
+    component: FontForLanguages,
+    tags: ['!autodocs', '!a11y-test'],
+};
+
+export default meta;
+
+export const LanguageFontExplorer: StoryFn<typeof FontForLanguages> = () => {
+    return <FontForLanguages />;
+};

package/pages/30.guides/70.assets/30.icons.explorer.mdx

@@ -0,0 +1,30 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+import { IconSearch } from './components/IconSearch';
+import { IconSearchResults } from './components/IconSearchResults';
+import { IconSearchProvider } from './components/IconsSearchContext/IconSearchProvider';
+
+<Meta title="Guides/Assets/Icon Explorer" />
+
+# Icon Explorer
+
+**Do not see the icon you are looking for?**
+
+Reach out to us in <a href="https://preply.slack.com/archives/C024EAEHP6V">#design-system-public</a> with:
+
+- a bit of context
+- an icon draft (screenshot or Figma link)
+- the icon name suggested
+
+And we will drive you through the process!
+
+## Usage
+
+These SVGs allow recolouring via `<Icon color="..." />`, see [Icon](/story/components-content-icon-docs--page) docs for detailed information.
+
+## Search icons
+
+<IconSearchProvider>
+    <IconSearch />
+    <IconSearchResults />
+</IconSearchProvider>

package/pages/30.guides/70.assets/40.illustrations.explorer.mdx

@@ -0,0 +1,12 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+import { IllustrationsList } from './components/IllustrationsList';
+
+<Meta title="Guides/Assets/Illustration Explorer" />
+
+# Illustration Explorer
+
+Don't see the illustration you're looking for? You can follow [this guide](https://preply.atlassian.net/wiki/spaces/PDS/pages/4332584962/Hosting+new+illustration) to upload it yourself, it's super easy! Or reach out to us in
+[#design-system-public](https://preply.slack.com/archives/C024EAEHP6V).
+
+<IllustrationsList />