@adobe-commerce/elsie 1.0.0-alpha04071347

package/src/docs/Design/designBlocks.jsx

@@ -0,0 +1,87 @@
+import { Source } from '@storybook/blocks';
+
+export const Block = ({ style, children }) => (
+  // Renders content in a block that has a light background
+  <div
+    style={{
+      background: 'var(--color-neutral-50)',
+      color: 'black',
+      display: 'grid',
+      gridGap: 'var(--spacing-sm)',
+      padding: 'var(--spacing-sm)',
+      ...style,
+    }}
+  >
+    {children}
+  </div>
+);
+
+export const DesignSwatchGroup = ({
+  property,
+  prefix,
+  tokens,
+  swatchStyles,
+  groupStyles,
+  children,
+}) => {
+  // Renders a group of token swatches
+  const group = prefix
+    ? tokens.filter((entry) => entry.startsWith(prefix))
+    : tokens;
+  return group.map((entry) => {
+    const styleOverride = {};
+    styleOverride[property] = `var(${entry})`;
+    return (
+      <div
+        key={entry}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          font: 'var(--type-body-1-strong-font)',
+          letterSpacing: 'var(--type-body-1-strong-spacing)',
+          margin: 'var(--spacing-xxsmall)',
+          ...groupStyles,
+        }}
+      >
+        <DesignSwatch style={{ ...swatchStyles, ...styleOverride }}>
+          {children}
+        </DesignSwatch>
+        <pre style={{ marginLeft: 'var(--spacing-small)' }}>var({entry});</pre>
+      </div>
+    );
+  });
+};
+
+export const DesignSwatch = ({ style, children, ...restProps }) => {
+  // Renders a token swatch
+  return (
+    <div
+      style={{
+        width: '3rem',
+        height: '3rem',
+        background: 'var(--color-informational-200)',
+        border: '1px solid var(--color-neutral-400)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const TokenDefinitions = ({ tokenData }) => {
+  const tokenDefinitions = tokenData.map((token) => {
+    const { name, value, comment } = token;
+    return `${name}: ${value}; ${comment ? `/* ${comment} */` : ''}`;
+  });
+  return (
+    <Source
+      language="css"
+      code={`.dropin-design {\n  ${tokenDefinitions.join('\n  ')}
+}`}
+    />
+  );
+};

package/src/docs/Design/getTokenData.ts

@@ -0,0 +1,28 @@
+export interface TokenData {
+  name: string;
+  value: string;
+  comment?: string;
+}
+
+export const getTokenData = (data: any) => {
+  const results: TokenData[] = [];
+
+  walk(results, '-', data);
+
+  return results;
+};
+
+const walk = (results: TokenData[], currentName: string, data: any) => {
+  if (data.value) {
+    results.push({
+      name: currentName,
+      value: data.value,
+      comment: data.comment || null,
+    });
+    return;
+  }
+
+  Object.entries(data).forEach((entry) => {
+    walk(results, `${currentName}-${entry[0]}`, entry[1]);
+  });
+};

package/src/docs/Design/grid.mdx

@@ -0,0 +1,365 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Block, DesignSwatchGroup, TokenDefinitions } from './designBlocks.jsx';
+import gridData from '@adobe-commerce/storefront-design/base/grid/grid.json';
+import { getTokenData } from './getTokenData';
+import { OptionsTable } from '@adobe-commerce/elsie/config/storybook/components/OptionsTable';
+
+export const tokenData = getTokenData(gridData);
+export const tokenNames = tokenData.map((token) => token.name);
+
+<Meta title="Design/Grid System" />
+<Unstyled>
+
+export const SampleColumn = () => {
+  return (
+    <div
+      style={{
+        background: `var(--color-informational-200)`,
+        padding:`200px 0`,
+      }}
+    ></div>
+  );
+};
+export const SampleGrid = ({ prefix, columnNumber }) => {
+  return (
+    <div>
+        <TokenDefinitions
+          tokenData={tokenData.filter((data) => data.name.startsWith(prefix))}
+        />
+        <Block
+            style={{
+                display: `grid`,
+                gridTemplateColumns: `repeat(var(${prefix}-columns), 1fr)`,
+                gridColumnGap: `var(${prefix}-gutters)`,
+                margin: `0 var(${prefix}-margins)`,
+            }}
+        >
+
+        {Array.from(Array(parseInt(columnNumber)).keys()).map((i) => (
+            <SampleColumn key={i} />
+        )) }
+
+        </Block>
+    </div>
+
+    );
+
+};
+
+# Grid System
+
+The grid system is based on a **12-column responsive grid**, meaning that the number of columns can change depending on the screen width. Let's look first at the breakpoints and tokens we defined for our grid system. Then we'll look at how to use them in your drop-ins.
+
+## Grid Breakpoints
+
+Breakpoints are the specific widths (in pixels) that define how the drop-in grid changes when displayed on different screen widths. These changes include the number of columns, column widths, column gaps, and grid margins.
+
+These are the breakpoints we defined for the drop-in grid:
+
+<OptionsTable
+  options={[
+    ['Name', 'Breakpoint (code)', 'Description', 'Devices'],
+    ['Small (default)', 'n/a', 'Screens up to 767px', 'Phones'],
+    [
+      'Medium',
+      'min-width: 768px',
+      'Screens that are 768px or larger',
+      'Tablets portrait',
+    ],
+    [
+      'Large',
+      'min-width: 1024px',
+      'Screens that are 1024px or larger',
+      'Tablets landscape',
+    ],
+    [
+      'XLarge',
+      'min-width: 1366px',
+      'Screens that are 1366px or larger',
+      'Desktops, laptops',
+    ],
+    [
+      'XXLarge',
+      'min-width: 1920px',
+      'Screens that are 1920px or larger',
+      'Desktops, laptops',
+    ],
+  ]}
+/>
+
+## Grid tokens
+
+The drop-in grid system provides **five sets of grid tokens** (CSS variables) to lay out your components: `--grid-[1-5]-columns`, `--grid-[1-5]-gutters`, and `--grid-[1-5]-margins`. Each set of tokens can provide a different number of columns, column widths, column-gutter widths, or grid margins. These token sets, values, suggested breakpoints, and the CSS properties they are applied to, are listed below.
+
+<OptionsTable
+  compact
+  options={[
+    [
+      'Breakpoint',
+      'Grid token (code)',
+      'Value 100px (code)',
+      'CSS property (code)',
+    ],
+    [
+      'Small (default) screens',
+      'var(--grid-1-columns)',
+      '4',
+      'grid-template-columns',
+    ],
+    ['Small (default)', 'var(--grid-1-gutters)', '16px', 'grid-column-gap'],
+    ['Small (default)', 'var(--grid-1-margins)', '0', 'margin'],
+    [],
+    ['Medium screens', 'var(--grid-2-columns)', '12', 'grid-template-columns'],
+    ['Medium', 'var(--grid-2-gutters)', '16px', 'grid-column-gap'],
+    ['Medium', 'var(--grid-2-margins)', '0', 'margin'],
+    [],
+    ['Large screens', 'var(--grid-3-columns)', '12', 'grid-template-columns'],
+    ['Large', 'var(--grid-3-gutters)', '24px', 'grid-column-gap'],
+    ['Large', 'var(--grid-3-margins)', '0', 'margin'],
+    [],
+    ['XLarge screens', 'var(--grid-4-columns)', '12', 'grid-template-columns'],
+    ['XLarge', 'var(--grid-4-gutters)', '24px', 'grid-column-gap'],
+    ['XLarge', 'var(--grid-4-margins)', '0', 'margin'],
+    [],
+    ['XXLarge screens', 'var(--grid-5-columns)', '12', 'grid-template-columns'],
+    ['XXLarge', 'var(--grid-5-gutters)', '24px', 'grid-column-gap'],
+    ['XXLarge', 'var(--grid-5-margins)', '0', 'margin'],
+  ]}
+  compact={true}
+/>
+
+## How to use the grid system
+
+To use the grid system in your drop-ins, you need to:
+
+- Define your **grid-container** CSS class(es) using the drop-in grid token sets.
+- Define your **grid-item** CSS classes to specify the columns and spans for your drop-in components.
+
+You can name your grid-container and grid-item classes whatever you want. For these examples, we will use `grid-container-[size]` and `grid-item-a`, `grid-item-b`, and so on.
+
+The grid-container class defines the grid itself, and the grid-item classes define where and how to put your components on the grid. The following example shows a simple usage of these classes:
+
+```html
+<div class="grid-container-small">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+</div>
+```
+
+## Define a grid container
+
+The first step is to define your `grid-container` classes. Use the grid token sets to define values for grid-column CSS properties as shown here:
+
+```css
+.grid-container-small {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-1-columns), 1fr);
+  grid-column-gap: var(--grid-1-gutters);
+  margin: 0 var(--grid-1-margins);
+}
+```
+
+**CSS properties**
+
+As shown in the previous example, every grid container needs the following CSS properties:
+
+- `display: grid` — Creates a grid layout.
+- `grid-template-columns:` — Defines the number and width of columns in the grid.
+- `grid-column-gap:` — Defines the space between columns.
+- `margin:` — Defines the space between the grid container and the edge of the screen.
+
+## Define grid items
+
+Grid item CSS classes define where (which column) and how (columns span) you want to put the components that make up your drop-in UI. To create grid-item classes, add a `grid-item-x` class to the UI components within your drop-in. You can then use the `grid-column` CSS property to define which column a component starts in and the number of columns it spans.
+
+In this example, the `grid-item-a` class starts at column 1 and spans 5 columns:
+
+```css
+.grid-item-a {
+  grid-column: 1 / span 5;
+}
+```
+
+## Example grids
+
+The following examples show which grid token sets we recommend when using the defined breakpoints.
+
+### Small (default) layouts (up to 767px)
+
+For this breakpoint, we recommend the `grid-1` token set:
+
+<SampleGrid prefix="--grid-1" columnNumber="4" />
+
+**CSS classes**
+
+```css
+.grid-container-small {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-1-columns), 1fr);
+  grid-column-gap: var(--grid-1-gutters);
+  margin: 0 var(--grid-1-margins);
+}
+.grid-item-a {
+  grid-column: 1 / span 4;
+}
+.grid-item-b {
+  grid-column: 3 / span 2;
+}
+```
+
+**HTML additions**
+
+```html
+<div class="grid-container-small">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+</div>
+```
+
+### Medium layouts (768px and wider)
+
+For this breakpoint, we recommend the `grid-2` token set:
+
+<SampleGrid prefix="--grid-2" columnNumber="12" />
+
+**CSS classes**
+
+```css
+.grid-container-medium {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-2-columns), 1fr);
+  grid-column-gap: var(--grid-2-gutters);
+  margin: 0 var(--grid-2-margins);
+}
+.grid-item-a {
+  grid-column: 1 / span 4;
+}
+.grid-item-b {
+  grid-column: 5 / span 4;
+}
+.grid-item-c {
+  grid-column: 9 / span 4;
+}
+```
+
+**HTML additions**
+
+```html
+<div class="grid-container-medium">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+  <div class="grid-item-c">Item C</div>
+</div>
+```
+
+### Large layouts (1024px and wider)
+
+For this breakpoint, we recommend the `grid-3` token set:
+
+<SampleGrid prefix="--grid-3" columnNumber="12" />
+
+**CSS classes**
+
+```css
+.grid-container-large {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-3-columns), 1fr);
+  grid-column-gap: var(--grid-3-gutters);
+  margin: 0 var(--grid-3-margins);
+}
+.grid-item-a {
+  grid-column: 1 / span 12;
+}
+.grid-item-b {
+  grid-column: 1 / span 6;
+}
+.grid-item-c {
+  grid-column: 7 / span 6;
+}
+```
+
+**HTML additions**
+
+```html
+<div class="grid-container-large">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+  <div class="grid-item-c">Item C</div>
+</div>
+```
+
+### XLarge layouts (1366px and wider)
+
+For this breakpoint, we recommend the `grid-4` token set:
+
+<SampleGrid prefix="--grid-4" columnNumber="12" />
+
+**CSS classes**
+
+```css
+.grid-container-x-large {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-4-columns), 1fr);
+  grid-column-gap: var(--grid-4-gutters);
+  margin: 0 var(--grid-4-margins);
+}
+.grid-item-a {
+  grid-column: 1 / span 5;
+}
+.grid-item-b {
+  grid-column: 6 / span 7;
+}
+.grid-item-c {
+  grid-column: 1 / span 12;
+}
+```
+
+**HTML additions**
+
+```html
+<div class="grid-container-x-large">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+  <div class="grid-item-c">Item C</div>
+</div>
+```
+
+### XXLarge layouts (1920px and wider)
+
+For this breakpoint, we recommend the `grid-5` token set:
+
+<SampleGrid prefix="--grid-5" columnNumber="12" />
+
+**NOTE:** The `grid-3`, `grid-4`, and `grid-5`token sets are the same. We provide these tokens to make it easier to customize this token set for different layouts or breakpoints.
+
+**CSS classes**
+
+```css
+.grid-container-xx-large {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-5-columns), 1fr);
+  grid-column-gap: var(--grid-5-gutters);
+  margin: 0 var(--grid-5-margins);
+}
+.grid-item-a {
+  grid-column: 1 / span 5;
+}
+.grid-item-b {
+  grid-column: 6 / span 7;
+}
+.grid-item-c {
+  grid-column: 1 / span 12;
+}
+```
+
+**HTML additions**
+
+```html
+<div class="grid-container-xx-large">
+  <div class="grid-item-a">Item A</div>
+  <div class="grid-item-b">Item B</div>
+  <div class="grid-item-c">Item C</div>
+</div>
+```
+
+</Unstyled>

package/src/docs/Design/overview.mdx

@@ -0,0 +1,69 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Flex } from '@adobe-commerce/elsie/config/storybook/components/Flex';
+import { Panel } from '@adobe-commerce/elsie/config/storybook/components/Panel';
+
+import colors from '@adobe-commerce/elsie/src/docs/assets/Colors.png';
+import spacing from '@adobe-commerce/elsie/src/docs/assets/Spacing.png';
+import typography from '@adobe-commerce/elsie/src/docs/assets/Typography.png';
+import shapeStyles from '@adobe-commerce/elsie/src/docs/assets/ShapeStyles.png';
+
+<Meta title="Design/Overview" />
+<Unstyled>
+
+# Drop-in Design Tokens
+
+All of our drop-ins are built with our design tokens baked-in so that you can quickly change their visual appearance to match your brand.
+
+## What are design tokens?
+
+Design tokens are CSS variables with default values. Our design tokens provide a standard set of CSS properties and default values for colors, typography, spacing, shapes, and layouts. We use them in all of our component CSS classes to avoid hard-coded values that cannot be easily changed. With this strategy, you can restyle our drop-ins to match your brand simply by changing the default values.
+
+<Flex itemsPerAxis={2}>
+<Panel header footer>
+<img src={colors} alt="Colors"/>
+### Colors
+Create meaningful experiences while also expressing hierarchy, state, and brand identity.
+
+[Read more](/docs/design-colors--overview)
+</Panel>
+
+<Panel header footer>
+<img src={typography} alt="Typography" />
+### Typography
+Set your typography scale to present your content as clearly and efficiently as possible.
+
+[Read more](/docs/design-typography--overview)
+</Panel>
+
+<Panel header footer>
+<img src={spacing} alt="Spacing" />
+### Spacing
+Create harmonious arrangements with consistent visual balance and predictable rhythm.
+
+[Read more](/docs/design-spacing--overview)
+</Panel>
+
+<Panel header footer>
+<img src={shapeStyles} alt="Shape styles" />
+### Shape styles
+Grab user attention by using shadows or other visual cues, such as strokes, border-radius, and size.
+
+[Read more](/docs/design-shape-styles--overview)
+</Panel>
+</Flex>
+
+## How to use design tokens
+
+To apply design tokens on your project, make use of the UIProvider, which grants components access to the design tokens as CSS variables. Simply specify the desired design token using the var() CSS function to apply its corresponding value.
+
+```css
+.myComponent {
+  background-color: var(--color-brand-500);
+}
+```
+
+## How to add new design tokens
+
+You can always add new design tokens to the existing categories (color, spacing, etc.) or create new categories to fit your needs. Just follow the simple patterns and conventions we use in our existing design tokens and you can add as many new tokens for your drop-in as you want.
+
+</Unstyled>

package/src/docs/Design/shapes.mdx

@@ -0,0 +1,100 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+import { Block, DesignSwatchGroup, TokenDefinitions } from './designBlocks.jsx';
+
+import shapesData from '@adobe-commerce/storefront-design/base/shapes/shapes.json';
+import { getTokenData } from './getTokenData';
+
+import { Icon } from '@adobe-commerce/elsie/src/components';
+import { Placeholder } from '@adobe-commerce/elsie/src/icons';
+
+export const tokenData = getTokenData(shapesData);
+export const tokenNames = tokenData.map((token) => token.name);
+
+<Meta title="Design/Shape styles" />
+<Unstyled>
+
+# Shapes
+
+Grab user attention by using shadows or other visual cues, such as strokes, surface fills, or opacities.
+These can serve a number of purposes from aesthetics to functionality.
+Use them to provide visual hierarchy or to focus a user's attention on a specific group.
+
+## Border
+
+### Radius
+
+export const shapeBorderRadiusPrefix = '--shape-border-radius';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(shapeBorderRadiusPrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="borderRadius"
+    prefix={shapeBorderRadiusPrefix}
+    tokens={tokenNames}
+  />
+</Block>
+
+### Width
+
+export const shapeBorderWidthPrefix = '--shape-border-width';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(shapeBorderWidthPrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="borderWidth"
+    prefix={shapeBorderWidthPrefix}
+    tokens={tokenNames}
+  />
+</Block>
+
+## Drop Shadows
+
+export const shapeShadowPrefix = '--shape-shadow';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(shapeShadowPrefix)
+  )}
+/>
+
+<Block style={{ background: 'var(--color-neutral-50)' }}>
+  <DesignSwatchGroup
+    property="boxShadow"
+    prefix="--shape-shadow"
+    tokens={tokenNames}
+    swatchStyles={{ border: 'none', background: 'var(--color-neutral-50)' }}
+  />
+</Block>
+
+## Icon Stroke Widths
+
+export const shapeIconStrokePrefix = '--shape-icon-stroke-';
+
+<TokenDefinitions
+  tokenData={tokenData.filter((data) =>
+    data.name.startsWith(shapeIconStrokePrefix)
+  )}
+/>
+
+<Block>
+  <DesignSwatchGroup
+    property="strokeWidth"
+    prefix={shapeIconStrokePrefix}
+    tokens={tokenNames}
+  >
+    <Icon source={Placeholder} size={32} />
+  </DesignSwatchGroup>
+</Block>
+
+</Unstyled>

package/src/docs/Design/spacing.mdx

@@ -0,0 +1,22 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+import { Block, DesignSwatchGroup, TokenDefinitions } from './designBlocks.jsx';
+import spacingData from '@adobe-commerce/storefront-design/base/spacing/spacing.json';
+import { getTokenData } from './getTokenData';
+
+export const tokenData = getTokenData(spacingData);
+export const tokenNames = tokenData.map((token) => token.name);
+
+<Meta title="Design/Spacing" />
+<Unstyled>
+
+# Spacing
+
+Use an incremental system to create harmonious arrangements with consistent visual balance and predictable rhythm to make the user interface easier for users to scan and identify relevant groups.
+
+<TokenDefinitions tokenData={tokenData} />
+
+<Block>
+  <DesignSwatchGroup property="width" tokens={tokenNames} />
+</Block>
+
+</Unstyled>