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 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:

   ["../../snowdog/module-alpaca-components"]
   

3. Customize or add new files following the same structure as in Alpaca components library
4. Run gulp dev

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.

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.

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'

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog
and this project adheres to Semantic Versioning.

[Unreleased]

[1.6.0] - 29.09.2020

Added

• focus-visible styles

Fixed

• spacing between dashboard items sections in 2 column layout without overriding templates
• typo in login page styles

[1.5.1] - 15.06.2020

Added

• Node 12.x support
• Build tools dependecies update

[1.5.0] - 26.05.2020

Fixed

• Rendering attributes in select and image elements

Changed

• Password strength and datepicker styles

[1.4.0] - 15.10.2019

Added

• Focus & Keyboard support for mega-menu
• Skip nav element

Changed

• Change modal attribute to kebab case and fix modal overflow
• Switching to Gulp 4
• Update node modules ([email protected], [email protected], [email protected], [email protected], [email protected])
• Load dropdown-list globally and change dropdown selector

Fixed

• Rating focus style
• Hide side-menu content from keyboard navigation
• Fixed typo for variable in Sass catalog grid

[1.3.2] - 15.07.2019

Fixed

• CI issues after moval of rsync from docker image

Changed

• Frontools removed from dependecies
• CI Frontools config update

[1.3.1] - 30.04.2019

Added

• Missing mega-menu item classes

Changed

• Remove lazyload from logo image

Fixed

• Missing icons
• Lazyload in catalog

[1.3.0] - 17.04.2019

Added

• Focus state for components

Changed

• Dashboard My Orders page - a11y updates
• Refactor divider component
• Update preview grid

Fixed

• Quantity icons config
• Catalog grid item styles for images with different sizes

[1.2.0] - 04.03.2019

Added

• Support for escape key in dropdown script
• B2B Quickorder view
• reCAPTCHA styles

Changed

• Refactor filters and accessibility improvements
• Checkbox styles
• Variables Scope and variable inheritance
• Price styles for configurable products

Fixed

• Related products styles in product view

[1.1.0] - 07.01.2019

Added

• email-to-friend view
• confirmation-link view
• price--between element variant
• bundle-option module
• product-view--bundle view variant
• product-view--grouped view variant
• Support for B2B module
• Grid based on flexboxgrid2

Fixed

• Review alignment
• Alignment for buttons
• Alignment for quick search input (Safari issue)
• Input text on safari browsers

Changed

• Refactor dropdown list and nested list
• Update dependencies to work with node lts v10.15.0
• Deployment moved from Heroku to Now

Removed

• Wrong z-index from rating stars
• Grid styles and references in modules and views

[1.0.1] - 18.10.2018

Changed

• Circle CI tests setup

[1.0.0] - 15.10.2018

Added

• Better docs

[0.10.2] - 11.10.2018

Added

• Styles for 2 column layouts

Changed

• Refactor rating & review on product page, a11y

Removed

• Useless table element sass extends

Fixed

• z-index value for mega menu

[0.10.1] - 26.09.2018

Fixed

• Catalog grid on IE

[0.10.0] - 18.09.2018

Added

• Class for hiding column name in menu
• Category block styles in catalog view

Changed

• Rating stars
• Error styles
• Catalog structure

Fixed

• Qty validation error styles

[0.9.1] - 06.09.2018

Changed

• Yarn lock file

[0.9.0] - 05.09.2018

Added

• Question mark icon

Changed

• Sidebar blocks heading

Fixed

• Review module and review details view

[0.8.0] - 22.08.2018

Added

• Compare view
• Loader element
• Hover effect to header buttons
• Accessibility for swatches and toolbar
• Swatch color variant
• README files for elements with accessibility information
• Sidebar block module for compare, wishlist and recent orders
• Margin to notification
• Modifier to swatch option for white color
• Quicksearch module

Changed

• Product page styles
• Gallery loader styles
• Swatch refactored
• Page title and breadcrumbs styles
• Catalog grid item adjustments
• Global & Elements accessibility improvements (svg, typography, cookies, messages, pager, price, tabs, table, rating, dropdown-list-medium)
• Link refactored
• Moved wishlist component from modules to dashboard views
• Catalog items improvements
• 4 columns grid to fix sidebar size in my account

Removed

• sidebar-nav-list module
• mix-blend-mode from product images

[0.7.3] - 09.07.2018

Fixed

• CSS Lint errors

[0.7.2] - 07.05.2018

Fixed

• Yarn lock file

Changed

• Swatches styles
• Catalog item styles
• Filters media query size

[0.6.0] - 30.03.2018

Added

• New list variant
• Global focus style
• Catalog list item module
• Catalog grid item module
• Catalog grid view
• Catalog list view
• Filters module.
• Modal module
• Working js for Quantity-update
• Sticky footer
• Minicart
• Forgot password view

Changed

• Product view adjustements
• Links color and styles
• Brief-info styles
• Review start refactor
• Rating - use svg icons as css background with svg-uri for encoding uri
• Footer component design
• Global variables
• List module styles
• Newsletter module design
• Refactored swatch element
• Update label hidden style
• Refactored file-upload component - removed dependecy on button styles, JS code made more roboust
• Update accessibility features in file-upload component
• Login page, removed tabs and set two columns
• Aria-label values
• Registration view
• Simplify filters
• Remove unnecessary code from config
• Update toolbar styles
• Mega menu module to fit Snowdog Menu Module
• Side menu module to fit Snowdog Menu Module

Removed

• Old catalog product modules and catalog views

[0.5.0] - 20.11.2017

Added

• Slide module
• Arrow-right icon
• Home page view
• Variant for list - with components as content
• Accessibility tests

Changed

• Pager element styling that fits design
• Adjustements in slider module
• Swatcher update

[0.4.1] - 13.11.2017

Fixed

• Typo - double semicolon

[0.4.0] - 13.11.2017

Added

• Quantity-updater module
• Minus icon
• Icon component
• Dropdown list component for side menu
• Link modifier with custom border on hover

Changed

• Dropdown list component
• Footer module changed
• Update form elements style and structure (accessibility): checkbox/radio button, select, input, textarea
• Tab styling
• Cookie message styling
• Update icon list and change to alph order
• Update icons list to display with icon components
• Name of dropdown-menu element to mega-menu
• Mega menu styling

[0.3.0] - 06.11.2017

Added

• Spacer global variables

Changed

• Variables in password strength element
• Popup component
• Table styles
• Newsletter module

[0.2.0] - 28.10.2017

Added

• Banner images
• marketing bar element
• docs-styles-only preview layout
• User account dashbord elemenets, modules and views
• Project description

Changed

• Refactor banner styles
• Optimize new banner images
• Simplify banner template
• Button styling that fits alpaca design.
• Badges styling that fits alpaca design (default, new, discount).
• Breadcrumbs styling that fits alpaca design.
• Header styling that fits alpaca design.
• Styles used only for previews (i.e. buttons)
• Button icon variables to BEM
• CHANGELOG releases date format to european

[0.1.2] - 10.10.2017

Changed

• update README, correct typo

Added

• CHANGELOG.md

[0.1.1] - 09.10.2017

Changed

• Project name to module-alpaca-components

[0.1.0] - 09.10.2017

Added

• Initial release (internal purpouses only)