snowdog/module-alpaca-ui-components

Components of the Alpaca theme for Magento 2

, _(*1)

⚠️ This project is deprecated. Please use Alpaca 2.0 instead.

Introduction

Components library of Alpaca design system created to speed up the process of working with design on Magento 2 stores, by creating each UI element, module, and view in a simplified, front-end developer friendly, environment., _(*2)

This components liblary is built on top of Fractal.js., _(*3)

Magento 2 experience isn't required to work with this code., _(*4)

Demo / Preview

https://alpaca-components.now.sh/, _(*5)

Installation

• Install dependencies using yarn
• Run gulp dev to start Fractal.js development server
• Run gulp if you want to generate static files (for example to deploy them)

How to create a components library on top of Alpaca

It's necessary only to work outside the Magento. 1. Copy-paste package.json, gulpfile.js, .eslintignore, .eslintrc, .sass-lint.yml, .stylelintrc, .gitignore files to the new project 2. Create modules.json file with an array of paths to parent components libraries. In most cases it will look like this: json ["../../snowdog/module-alpaca-components"] 3. Customize or add new files following the same structure as in Alpaca components library 4. Run gulp dev, _(*6)

Directory structure

• components directory is what you are going to import into the Magento 2 theme.
• docs and public are just for the local environment purposes, you will find there sample images, testing libs, utility styles etc.

Core concepts

Components architecture

Components are divided into 4 groups: 1. Globals - Contains code that other components can use in any place, for example, typography, icons or SASS variables. 2. Elements - Smallest UI parts, for example, buttons - Element can't depend on other elements - Element shouldn't have any layout 3. Modules - More complex UI parts like search form or header - Takes elements or modules and combine them together adding layout and context 4. Views - Takes elements or modules and combine them together adding final layout and context - You should be able to show it to client/PM as a preview of ready to use store - You shouldn't create any new UI elements, everything needs to be reusable., _(*7)

Naming

• Group name needs to be plural
• Component name needs to be singular
• Component name shouldn't be related to any project or place in the layout
  • Bad: filters
  • Good: dropdown-list or collapsible-list
• Avoid using box, block, item, info, text, cms, especialy combined together, for example info-box
• Avoid naming two components in similar way i.e. cms-subcategories and cms-subcategory

Colors

• By default alpaca components uses up to 7 step grayscale

SASS Variables naming

Follow BEM-like naming convention i.e. when you component name is button and you are creating a variable for a padding it should be $button__padding., _(*8)

Same as in BEM, you are not allowed to build construction like $button__icon__padding, it should be $button__icon-padding., _(*9)

Variables related to the pseudo-classes and pseudo-selectors should be treated as a BEM elements $button__color-hover., _(*10)

Also, BEM modificators are allowed in variables $button__padding--secondary, you can even stack them like this $button__padding--secondary--dark., _(*11)

To target variable to specific breakpoint adding \@breakpoint at the end of the variable name $button__padding\@medium. Always use small, medium, large etc. to describe the breakpoint., _(*12)

Examples of proper variables names:, _(*13)

$swatch__option-border
$swatch__option-border-color-hover

$swatch__option-image-height\@large

$swatch__option-size--small
$swatch__option-image-width--small
$swatch__option-image-width--small\@large

Accessibility

You can run gulp a11y to run dev server with accessibility tests enabled., _(*14)

If on some view there is no a11y message, please go to the component config and comment out preview: '@docs-only-styles', _(*15)