# snowdog/module-alpaca-components

> Components of the Alpaca theme for Magento 2

`composer require snowdog/module-alpaca-components`

Canonical URL: https://packagento.com/snowdog/module-alpaca-components

## At a glance

- **Vendor**: snowdog (https://packagento.com/snowdog.md)
- **Latest version**: 1.6.0 — released 2020-09-29
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/snowdog/module-alpaca-components and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require snowdog/module-alpaca-components:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Components of the Alpaca theme for Magento 2

## README

[![Greenkeeper badge](https://badges.greenkeeper.io/SnowdogApps/magento2-alpaca-components.svg)](https://greenkeeper.io/)
![Browser Status](https://badges.herokuapp.com/browsers?googlechrome=63,64,65,66,67&firefox=58,59&safari=11&iphone=11.2&android=64&iexplore=11&microsoftedge=16)

### Introduction
Components library of Alpaca [design system](https://www.uxpin.com/studio/blog/design-systems-vs-pattern-libraries-vs-style-guides-whats-difference/) 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](http://fractal.build/guide).

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:
   ```json
   ["../../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:
```scss
$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](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

### [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 (autoprefixer@9.6.0, globby@9.2.0, fs-extra@8.0.1, stylelint-config-standard@8.3.0, stylelint@10.1.0)
- 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

_(Changelog truncated for .md surface. Full history on https://packagento.com/snowdog/module-alpaca-components.)_

## Recent Versions

| Version | Released |
|---|---|
| 1.6.0 | 2020-09-29 |
| 1.5.1 | 2020-06-15 |
| 1.5.0 | 2020-05-25 |
| 1.4.0 | 2019-10-15 |
| 1.3.2 | 2019-10-15 |
| 1.3.1 | 2019-04-30 |
| 1.3.0 | 2019-04-17 |
| 1.2.0 | 2019-03-04 |
| 1.1.0 | 2019-01-07 |
| 1.0.1 | 2018-10-18 |

Showing 10 of 30 versions. Full release history on https://packagento.com/snowdog/module-alpaca-components.

## Quality

Latest release (1.6.0) passes the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Pass | 0 |  |
| PHPMD | Pass | 0 |  |
| Cpd | N/A | 0 | package ships no PHP source — cpd skipped (no files for copy-paste detection) |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Error | Error | – | – |
| 2.4.8 | – | Error | Error | – |
| 2.4.9 | – | – | Error | Error |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["snowdog/module-alpaca-components"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

snowdog is a Magento 2 vendor on Packagento. See https://packagento.com/snowdog.md for their full catalogue.