Skip to main content

Introduction

Hashi's components are designed to be primitive, and small. The components should provide the most basic of needs in a project like buttons, cards, form fields, wallets, and... profiles? Really? Jokes aside, these are part of Dev Protocol's identity, hence, it uses the provided design tokens.

These components can also be subcomponents of a larger, more project-specific components that solve its own design problems.

Instantiation​

Instantiating a component is as easy as calling the component's use() mixin.

@use 'node_modules/@devprotocol/hashi';
@use 'node_modules/@devprotocol/hashi/hs-component';

@include hashi.init() {
  @include hs-component.use();
}

Modification (HTML)​

The components must be modifiable using class names. In comparison to the modification API in the previous version, v1's implementation is more of a class name focused API.

We tried to put a more "human-feel" to the class names. We're using what we call a "base-description" pattern in terms of naming classes. BEM does provide a good way of doing this, however we generally found this very verbose and takes up a lot of character space. Hence, we tried to deviate from BEM's variance pattern to our own.

<!-- v0.x -->
<button class="hs-button hs-button--outlined is-danger">
    <span class="hs-button__label hs-button__label--bold">Button</span>
</button>

<!-- v1.x -->
<button class="hs-button is-outlined is-danger">
    <span class="hs-button__label is-bold">Button</span>
</button>

By making the class API like this, it's more readable and concise. As you can see, the only thing we retained from BEM is the element part of it. We truly believe this API style will make the class names API more consistent, readable, and developer-friendly.

Aren't there specificity issues?​

To solve specificity issues, these modification classes are created with the base class as the key.

.hs-button {
  // base styles...
  
  &.is-outlined {
    // outlined styles...
  }
}

This lets us use the same class names for every component while not clashing in with other modifiers.

Modification (SCSS)​

// Theming > Theme Variables

Extension (SCSS)​

Extension is a useful feature that lets you create component variants. An example usage is like so:

@use 'node_modules/@devprotocol/hashi/hs-component';

@include hs-component.extend('class-name') {
  @include hs-component.color(($preset));
  @include hs-component.shape(($preset));
  @include hs-component.typography(($preset));
}

Each preset is a map containing the properties and values present in the composition API.

Multiple selection​

The extension API allows you to do multiple selection. Meaning you can create sub-variants of variants. A good example of this is extending an already present button variant like is-outlined, and creating a color variant for it.

You can do multiple selection by separating variants using a period (.).

@use 'node_modules/@devprotocol/hashi/hs-button';

@include hs-button.extend('filled.blue-ink') {
  @include hs-button.color((
    ink: #0000ff,
  ));
}

Composition​

Hashi lets you create custom components to solve your project's design problems. From layouts, to coloring, to adding radii, to changing the font size, Hashi will cover it all for you.

Simple composition (utilities)​

By using utility classes, you can create layouts of components, add color, and modify the shapes and sizes of a component easily. This is generally recommended for components that are not complex in nature.

Advanced composition (composition API)​

This is for components that are complex in structure, and requires more attention, care, and effort to building. We expose a handful of composition APIs to help you in building these complex components. You are required to write SCSS.