Better Stylekit

See usage

Better Stylekit example website

Installation

npm install better-stylekit

Contributing

Browser support

Stylekit components (CSS and JS) should work in following browsers:

• Chrome 58 or newer
• Safari 11 (Desktop), 11 and 10 for iOS (revisit in two months)
• Firefox 57 and newer
• Edge 16 and newer

CSS

• Use SUIT CSS naming conventions for CSS classes and component variables
• Use Bourbon mixins

JavaScript

• Assume ES6 environment
• Assume DOM4 environment
• Polyfill when in doubt
• Prefer leaving library integrations to the user rather than vendoring/bundling them

Components

• Make sure each component has at least one customizable data-qa attribute
  • Put the qa attribute on the form element (<select>, <input>, etc.) directly, if the component is simple
  • For complex components with multiple inputs, put the qa attribute on the parent and add non-customizable qa attributes for the child inputs. For example, if there is a two-choice toggle component, add a customizable qa attribute to the main parent element, and qa attributes like "choice-1", "choice-2" to the proper inputs.
• Always include a type for <button> tags
• Always include a role attribute where it makes sense
• Sass mixins shared across different components should be in a shared file
• Set sensitive to add the bsk-Field--sensitive class so the field is obscured in FullStory: {{bsk-field sensitive=true ...}}

Usage

Using the stylekit as an artifact

1. npm install the stylekit.
2. Add stylekit/dist/*.css, stylekit/dist/*.js, and stylekit/fonts/* to your build pipeline.
3. Add stylekit-web.css or stylekit-web.min.css to your page as a stylesheet.
4. Add stylekit-web.js or stylekit-web.min.js to your page as a script.
5. Make sure the stylekit fonts are accessible under fonts/ in your CSS directory.

You can use the stylekit JS via the global BetterStylekit object.

Using the stylekit as a library

Ember

npm install ember-better-stylekit

See the ember-better-stylekit README for more details.

Components

| Component | HTML + CSS | JS | Ember | React | |----------- |------------- |---- |------- |------- | | Button | ✔ |✌ | ✔ | | | Card | ✔ |✌ | ✔ | | | CardList | ✔ | | ✔ | | | Dropdown | ✔ |✌ | ✔ | | | RadioList | ✔ |✌ | ✔ | | | Checkbox | ✔ |✌ | ✔ | | | Field | ✔ | | ✔ | | | FieldSet | ✔ |✔ | ✔ | | | Range | ✔ | | ✔ | | | Toggle | ✔ |✌ | ✔ | | | Tabs | ✔ | | | | | Modal | | | | |

✌ = not necessary

Development

• BSK refers to your local /stylekit
• ESK refers to your local /stylekit/ember-better-stylekit
• Better Stylekit refers to the published NPM package

IMPORTANT: CSS changes made in BSK do not automatically update the styles of ESK. ESK uses Better Stylekit for it's styling. In order to have BSK css changes propagate without having to publish to NPM check the Building CSS Changes section below.

Using BSK or ESK in Mortgage

• In order to access BSK and ESK in /mortgage/frontend, you will need to add symlinks:
  • to set up: run make add-bsk-esk-to-mortgage-symlinks in BSK
  • to teardown: run make rm-bsk-esk-to-mortgage-symlinks in BSK
• The above commands will create symlinks to BSK and ESK in /mortgage/frontend/node_modules.

Building CSS changes

• You will need to create a symlink in /stylekit/ember-better-stylekit/node_modules/better-stylekit that points to your local stylekit/src:

  • to set up: run make add-bsk-to-esk-css-symlink in BSK
  • to teardown: run make rm-bsk-to-esk-css-symlink in BSK

• Stylekit CSS changes should be picked up when you run npm run build in BSK

• If you prefer a watcher, use npm start in BSK

Test

• There are visual tests for components. The visual tests work this way:
  1. build the project, which creates previews of components
  2. use puppeteer to open the preview html and take a screenshot
  3. Use node-resemble-js to report any differences between the screenshot and a baseline screenshot
  4. A diff screenshot will be generated if necessary to highlight issues
• Since screenshots are os/browser dependent, the visual test will only pass in the docker environment
• To run the visual tests invoke make test in the root of stylekit
• When you add a new component, add a baseline screenshot and enable the component within the visual test
• When you change a component, update the baseline screenshot
• To add or update a baseline screenshot:
  1. run make component=yourComponentName generate-baseline for example: make component=dropdown generate-baseline
  2. when that command is finished, you should see a new baseline screenshot in stylekit/src/test/visual/baseline-screenshot that you can check in

Release

Automated

• Patch release: make release
• Minor release (rare): make release-minor

Manual

• Commit all relevant changes
• Run npm version patch or npm version minor depending on type of release
• Run npm install to ensure latest bundled deps are included
• Run npm run build so the new version is baked in
• Commit changes as the new version commit
• Login with npm login using the better account (ask someone to share it with you via LastPass)
• Run npm publish

Roadmap

• Ability to add a message to a field
• Generic field set support
• Error state with clearable ability
• Document Field API
• Grid and form component
• Add /index.js and other root-level files to simplify library integration
• React/Preact library integration
• Consider Lerna for monorepo management
• Ember/Preact component generation from one source of truth