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.
This components liblary is built on top of Fractal.js.
Magento 2 experience isn't required to work with this code.
Demo / Preview
https://alpaca-components.now.sh/
Installation
- Install dependencies using
yarn - Run
gulp devto start Fractal.js development server - Run
gulpif 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.
- Copy-paste
package.json,gulpfile.js,.eslintignore,.eslintrc,.sass-lint.yml,.stylelintrc,.gitignorefiles to the new project - Create
modules.jsonfile with an array of paths to parent components libraries.
In most cases it will look like this:["../../snowdog/module-alpaca-components"] - Customize or add new files following the same structure as in Alpaca components library
- Run
gulp dev
Directory structure
componentsdirectory is what you are going to import into the Magento 2 theme.docsandpublicare 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:
- Globals
- Contains code that other components can use in any place, for example, typography, icons or SASS variables.
- Elements
- Smallest UI parts, for example, buttons
- Element can't depend on other elements
- Element shouldn't have any layout
- Modules
- More complex UI parts like search form or header
- Takes elements or modules and combine them together adding layout and context
- 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.
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-listorcollapsible-list
- Bad:
- Avoid using
box,block,item,info,text,cms, especialy combined together, for exampleinfo-box - Avoid naming two components in similar way i.e.
cms-subcategoriesandcms-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.
Same as in BEM, you are not allowed to build construction like $button__icon__padding, it should be $button__icon-padding.
Variables related to the pseudo-classes and pseudo-selectors should be treated as a BEM elements $button__color-hover.
Also, BEM modificators are allowed in variables $button__padding--secondary, you can even stack them like this $button__padding--secondary--dark.
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.
Examples of proper variables names:
$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.
If on some view there is no a11y message, please go to the component config and comment out preview: '@docs-only-styles'