@hidoo/styleunit

The unit oriented CSS framework implemented in Sass.

Demo

• Style Guide (Generated by kss-node)

Installation

npm install @hidoo/styleunit

Usage

@use 'node_modules/@hidoo/styleunit/src/index.scss';

Use with NodePackageImporter

@use 'pkg:@hidoo/styleunit';

Use with @hidoo/sass-importer

@use '@hidoo/styleunit';

Use with configured settings

// Use this package with the configured settings
@use 'node_modules/@hidoo/styleunit/src/index.scss' with (
  $prefix: 'u'
);

// Initialize manually
@use 'node_modules/@hidoo/styleunit/src/bootstrap';

Usage only with the necessary units

// Use this package with the configured settings
@use 'node_modules/@hidoo/styleunit/src/settings' with (
  $prefix: 'u'
);

// Use all of text unit
@use 'node_modules/@hidoo/styleunit/src/unit/text';

// Use part of button unit
@use 'node_modules/@hidoo/styleunit/src/unit/button/core';
@use 'node_modules/@hidoo/styleunit/src/unit/button/inline';

// Initialize manually
@use 'node_modules/@hidoo/styleunit/src/bootstrap';

Plugins

• spritesheet

API

@mixin apply-aspect-ratio

apply aspect ratio settings

Parameters

Name	Type	Description	Default
$width	Number	width	16
$height	Number	height	9

Examples

scss inputs

.selector {
  @include mixin.box-apply-aspect-ratio($width: 16, $height: 9);
}

css outputs

.selector::before {
  content: '';
  display: block;
  width: 100%;
  height: 0;
  padding-top: 56.25%;
}

@mixin apply-clearfix

apply clearfix

Examples

scss inputs

.selector {
  @include mixin.box-apply-clearfix();
}

css outputs

.selector::before,
.selector::after {
  content: '';
  display: table;
}
.selector::after {
  clear: both;
}

@function foreground

return foreground color

Parameters

Name	Type	Description	Default
$background-color	Color	background-color	-
$options	Map	options	()
$options.threshold	Number	threshold	60%
$options.color-mappings	Map	color mappings	-
$options.color-mappings.dark	Map	dark color	settings.$color-scheme.black
$options.color-mappings.light	Map	light color	settings.$color-scheme.white

Returns

Color foreground color

Examples

scss inputs

.selector {
  content: function.color-foreground(#000);
}

css outputs

.selector {
  content: #fff;
}

$themes

Default builtin theme

Type

Map

Properties

Name	Type	Description	Default
light	Map	values of light theme	(...)
dark	Map	values of dark theme	(...)

$palette

Color palette

Type

Map

Properties

Name	Type	Description	Default
black	List	█	(0, 0, 0)
dark-moon	List	█	(20, 23, 26)
night-sky	List	█	(38, 44, 51)
black-olive	List	█	(63, 63, 63)
dim-gray	List	█	(107, 107, 109)
nocturnal	List	█	(119, 124, 130)
gateway-gray	List	█	(159, 159, 161)
stone	List	█	(195, 195, 197)
olympus-white	List	█	(213, 215, 217)
mercury	List	█	(235, 236, 237)
snow-flake	List	█	(237, 237, 240)
ghost-white	List	█	(249, 249, 250)
white	List	█	(255, 255, 255)
summer-sky	List	█	(55, 165, 228)
sky-blue	List	█	(122, 195, 237)

$mappings

Color mappings

Type

Map

Properties

Name	Type	Description	Default
a	String	type a	black
b	String	type b	dark-moon
c	String	type c	night-sky
d	String	type d	black-olive
e	String	type e	dim-gray
f	String	type f	nocturnal
g	String	type g	gateway-gray
h	String	type h	stone
i	String	type i	olympus-white
j	String	type j	mercury
k	String	type k	snow-flake
l	String	type l	ghost-white
m	String	type m	white
n	String	type n	summer-sky
o	String	type o	sky-blue
foreground	String	type foreground	black
background	String	type background	white
link	String	type link	summer-sky
focus	String	type focus	sky-blue

$family

Default font family.

Name	Description
system-ui	Use system ui font as a primary font family in macOS.
-apple-system	Use "San Francisco" as a secondary font family in macOS.
BlinkMacSystemFont	Use "San Francisco" as a primary font family in chrome on macOS.
Helvetica Neue	Use as a fallback font family in macOS.
Arial	Use as a primary font family in Windows.
Hiragino Sans	Use as a primary japanese font family in macOS.
Hiragino Kaku Gothic ProN	Use as a fallback of Hiragino Sans in macOS.
Noto Sans JP	Use as a primary japanese font family in Windows.
BIZ UDPGothic	Use as a secondary japanese font family in Windows.
Meiryo	Use as a fallback japanese font family in Windows.

Type

List

$family-monospace

Default monospace font family.

Name	Description
Consolas	Use as a primary monospace font family in Windows. (Use it if installed in macOS)
Monaco	Use as a primary monospace font family in macOS.
Menlo	Use as a secondary monospace font family in macOS.
Courier	Use as a secondary monospace font family in Windows.

Type

List

$family-presets

Default font family presets

Type

Map

Properties

Name	Type	Description	Default
sans-serif	String	Sans-serif font family	$family
monospace	String	Monospace font family	$family-monospace

$size

Default font size. (default: 14px)

Type

Number

$base-size

Default base font size. (default: 16px) this use if $enable-relative-size is true

Type

Number

$size-presets

Default font size presets

Type

Map

Properties

Name	Type	Description	Default
xsmall	Number	Lorem ipsum dolor sit amet. (= 10px)	0.625
small	Number	Lorem ipsum dolor sit amet. (= 12px)	0.75
medium	Number	sLorem ipsum dolor sit amet. (= 14px)	0.875
large	Number	Lorem ipsum dolor sit amet. (= 16px)	1
xlarge	Number	Lorem ipsum dolor sit amet. (= 18px)	1.125
2xlarge	Number	Lorem ipsum dolor sit amet. (= 20px)	1.25
3xlarge	Number	Lorem ipsum dolor sit amet. (= 22px)	1.375
4xlarge	Number	Lorem ipsum dolor sit amet. (= 24px)	1.5

$weight

Default font weight. (default: 400)

Type

Number

$weight-presets

Font weight presets

Type

Map

Properties

Name	Type	Description	Default
thin	Number	Lorem ipsum dolor sit amet. (= 100)	100
extra-light	Number	Lorem ipsum dolor sit amet. (= 200)	200
light	Number	Lorem ipsum dolor sit amet. (= 300)	300
regular	Number	Lorem ipsum dolor sit amet. (= 400)	400
medium	Number	Lorem ipsum dolor sit amet. (= 500)	500
semi-bold	Number	Lorem ipsum dolor sit amet. (= 600)	600
bold	Number	Lorem ipsum dolor sit amet. (= 700)	700
extra-bold	Number	Lorem ipsum dolor sit amet. (= 800)	800
black	Number	Lorem ipsum dolor sit amet. (= 900)	900

$variant

Default font variant (default: (common-ligatures proportional-width emoji))

Type

List

$smoothing

Default font smoothing (webkit: antialiased, moz-osx: grayscale)

Type

Map

Properties

Name	Type	Description	Default
webkit	Number	For browsers macOS	antialiased
moz-osx	Number	For firefox on macOS	grayscale

$enable-relative-size

enable relative font size specify. override base size settings of font (default: true)

Type

Boolean

$applying-units

Default list of units that applying font

Type

List

$pkg

Package name. (default: "su")

Type

String

Examples

scss inputs

$pkg: 's';

css outputs

:root {
  --s-breakpoint-mobile: 667px;
}

$prefix

Default prefix of unit class name. (default: "unit")

Type

String

Examples

scss inputs

$prefix: 'u';

css outputs

.u-icon {
  /* settings */
}

$breakpoints

Default breakpoints.

Type

Map

Properties

Name	Type	Description	Default
desktop	Number	Breakpoint width for desktop.	1024px
mobile	Number	Breakpoint width for mobile.	667px
sm	String	Breakpoint name when mobile viewport.	"only screen and (width < $mobile)"
not-sm	String	Breakpoint name when not mobile viewport.	"only screen and ($mobile <= width)"

$line-height

Default line-height (default: 1.5)

Type

Number

$hyphens

Default hyphens (default: auto)

Type

String

$letter-spacing

Default letter-spacing (default: 0.04em)

Type

Number

$text-size-adjust

Default text-size-adjust (default: 100%)

Type

Number

$word-break

Default word-break (default: normal)

Type

String

$word-wrap

Default word-wrap (default: break-word)

Type

String

$line-break

Default line-break (default: strict)

Type

String

$overflow-wrap

Default line-break (default: strict)

Type

String

$message-on-image-error

Default message on image error (default: Failed to load image.)

Type

String

$verbose

out warnings verbosely or not

Type

Boolean

$prefix

Default prefix for utility class name. (default: "util")

Type

String

Examples

scss inputs

$util-prefix: 'h';

css outputs

.h--width-0 {
  /* settings */
}

$width

Default width list.

Type

List

$height

Default height list.

Type

List

$margin

Default margin list

Type

List

$padding

Default padding list

Type

List

$position

Default position list

Type

List

$directions

Default direction list

Type

List

$z-index

Default z-index list

Type

List

css// prettier-ignore

$_default-selectors: (":disabled",) !default;

/// Utility for `:has` pseudo classes with `:disabled` /// @param

Default selectors

css// prettier-ignore

$_default-selectors: (":hover", ":focus") !default;

/// Utility for `:has` pseudo classes with `:hover` and `:focus` /// @param

Default selectors

css// prettier-ignore

$_default-selectors: (":checked",) !default;

/// Utility for `:has` pseudo classes with `:checked` /// @param

Default selectors

css// prettier-ignore

$_default-selectors: (":disabled",) !default;

/// Utility for pseudo classes like `:disabled` /// @param

Default selectors

Properties

Name	Type	Description	Default
not	Boolean	Deny selectors whether or not	false

Properties

Name	Type	Description	Default
not	Boolean	Deny selectors whether or not	false

@mixin by-breakpoints

Utility to generate selectors by breakpoints.

Parameters

Name	Type	Description	Default
$breakpoints	Map	Breakpoints.	()
$options	Map	options	()
$options.ignores	List	Breakpoint names to ignore.	()
$options.target	String	Target selector string to replacement.	""

Examples

scss inputs

$breakpoint: (
  'sm': '(width <= 640px)',
  'md': '(width <= 768px)',
  ...
);

.selector {
  @include mixin.by-breakpoints() {
    font-size: 16px;
  }
}

css outputs

.selector {
  font-size: 16px;
}
@media (width <= 640px) {
  .sm\:selector {
    font-size: 16px;
  }
}
@media (width <= 768px) {
  .md\:selector {
    font-size: 16px;
  }
}
...

@mixin has-disabled

Utility for :has pseudo classes with :disabled

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$options	Map	options	()

Examples

scss inputs

.selector {
  @include mixin.has-disabled() {
    font-size: 16px;
  }
}

css outputs

.selector:has(:disabled, .is-disabled) {
  font-size: 16px;
}

@mixin has-focus

Utility for :has pseudo classes with :hover and :focus

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$options	Map	options	()

Examples

scss inputs

.selector {
  @include mixin.has-focus() {
    font-size: 16px;
  }
}

css outputs

.selector:has(:hover, :focus, .is-focus) {
  font-size: 16px;
}

@mixin has-selected

Utility for :has pseudo classes with :checked

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$options	Map	options	()

Examples

scss inputs

.selector {
  @include mixin.has-selected() {
    font-size: 16px;
  }
}

css outputs

.selector:has(:checked, .is-selected) {
  font-size: 16px;
}

@mixin has

The utility mixin for :has pseudo classes.

Parameters

Name	Type	Description	Default
$selectors	List	list of selectors	()
$options	Map	options	()

Examples

scss inputs

.selector {
  @include mixin.has((':hover', ':focus')) {
    font-size: 16px;
  }
}

css outputs

.selector:has(:hover, :focus) {
  font-size: 16px;
}

@mixin media

The media query helper.

Parameters

Name	Type	Description	Default
$query	String	Breakpoint name or media query string	-
$options	Map	Options	()
$options.eval-query	String	Eval query as template whether or not	false
$options.breakpoints	Map	Breakpoints.	null

Examples

scss inputs

$breakpoint: (
  'sm': '(width <= 640px)',
  ...
);

.selector {
  @include mixin.media($query: 'sm') {
    font-size: 16px;
  }
}

css outputs

@media (width <= 640px) {
  .selector {
    font-size: 16px;
  }
}

@mixin on-active

Utility for pseudo classes like .is-active

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-active() {
    font-size: 16px;
  }
}

css outputs

.selector:where(.is-active) {
  font-size: 16px;
}

@mixin on-current

Utility for pseudo classes like .is-current

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-current() {
    font-size: 16px;
  }
}

css outputs

.selector:where(.is-current) {
  font-size: 16px;
}

@mixin on-deactive

Utility for pseudo classes like :not(is-active)

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-deactive() {
    font-size: 16px;
  }
}

css outputs

.selector::where(not(.is-active)) {
  font-size: 16px;
}

@mixin on-disabled

Utility for pseudo classes like :disabled

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-disabled() {
    font-size: 16px;
  }
}

css outputs

.selector:where(:disabled, .is-disabled) {
  font-size: 16px;
}

@mixin on-focus

Utility for pseudo classes like :hover and :focus

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-focus() {
    font-size: 16px;
  }
}

css outputs

.selector:where(:hover, :focus, .is-focus) {
  font-size: 16px;
}

@mixin on-link

Utility for pseudo classes like :link and :visited

Parameters

Name	Type	Description	Default
$additional-selectors	List	list of additional selectors	()
$capturing-selectors	List	capturing parent selectors	()

Examples

scss inputs

.selector {
  @include mixin.on-link() {
    font-size: 16px;
  }
}

css outputs

.selector:where(:link) {
  font-size: 16px;
}

@mixin on-placeholder

wrappper of :placeholder-shown

Examples

scss inputs

.selector {
  @include mixin.on-placeholder() {
    font-size: 16px;
  }
}

css outputs

.selector::-webkit-input-placeholder {
  font-size: 16px;
}
.selector::-moz-placeholder {
  font-size: 16px;
}
.selector:-ms-input-placeholder {
  font-size: 16px;
}
.selector:placeholder-shown {
  font-size: 16px;
}

@mixin on-print

The wrapper of @media print

Examples

scss inputs

.selector {
  @include mixin.on-print() {
    font-size: 16px;
  }
}

css outputs

@media print {
  .selector.is-active {
    font-size: 16px;
  }
}

@mixin on

Utility for pseudo classes

Parameters

Name	Type	Description	Default
$selectors	List	list of selectors	()
$capturing-selectors	List	capturing parent selectors	()
$options	Map	options	()

Examples

scss inputs

.selector {
  @include mixin.on((':hover', ':focus')) {
    font-size: 16px;
  }
}

css outputs

.selector:where(:hover, :focus) {
  font-size: 16px;
}

@function size

return real font-size

Parameters

Name	Type	Description	Default
$value	String, Number	value of font-size (one of "xsmall", "small", "medium", "large", "xlarge", "2xlarge", "3xlarge", "4xlarge" or number)	-
$options	Map	options	()
$options.monospace	Boolean	font-family is monospace or not	false
$options.relative-size	Boolean	convert to rem value or not	false

Returns

Number real font-size

Examples

scss inputs

.selector {
  font-size: function.font-size($value: 'medium');
}

css outputs

.selector {
  font-size: 14px;
}

@function concat-as-string

concatenate list as string

Parameters

Name	Type	Description	Default
$list	List	list	-
$separator	String	separator	","

Returns

String concatenated list

Examples

scss inputs

.selector {
  content: function.list-concat-as-string(('hoge', 'fuga', 'piyo'), ':');
}

css outputs

.selector {
  content: hoge:fuga:piyo;
}

@function map

map list

Parameters

Name	Type	Description	Default
$list	List	list	-
$callback	Function	function called each items	-

Returns

List mapped list

Examples

scss inputs

.selector {
  content: function.list-map(
    ('hoge', 'fuga', 'pi', 'yo'),
    meta.get-function('length', $module: 'string')
  );
}

css outputs

.selector {
  content: 4 4 2 2;
}

@function px-to-rem

convert px to rem

Parameters

Name	Type	Description	Default
$size	Number	font size	-
$base-size	Number	base font size	settings.$font-base-size

Returns

Number rem value

Examples

scss inputs

.selector {
  font-size: function.math-px-to-rem(14px, 16px);
}

css outputs

.selector {
  font-size: 0.875rem;
}

@function remove-unit

return number without unit

Parameters

Name	Type	Description	Default
$number	Number	number with unit	-

Returns

Number number without unit

Examples

scss inputs

$pure-number: function.math-remove-unit(14px); // -> 14

@function is-empty

value is empty or not

Parameters

Name	Type	Description	Default
$value	String, Number, List, Map	test value	-

Returns

Boolean value is empty or not

Examples

scss inputs

$result: function.meta-is-empty(''); // -> true

@mixin apply-flexible-size

apply flexible size to pict

Parameters

Name	Type	Description	Default
$width	Number	width	16
$height	Number	height	9
$options	Map	height	-
$options.use-object-fit	Boolean	use object-fit	false

Examples

scss inputs

.selector {
  @include mixin.pict-apply-flexible-size($width: 16, $height: 9);
}

css outputs

.selector::before {
  content: '';
  display: block;
  width: 100%;
  height: 0;
  padding-top: 56.25%;
}
.selector > .unit-pict__src {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  width: auto;
  max-width: 100%;
  height: auto;
  max-height: 100%;
  margin: auto;
}

@mixin define

define placeholder class.

Parameters

Name	Type	Description	Default
$name	String	name of placeholder class	-

Examples

scss inputs

.selector {
  $name: unique-id();

  @include mixin.placeholder-define($name: $name) {
    font-size: 16px;
  }

  &__child-1 {
    @extend %#{$name};
  }

  &__child-2 {
    @extend %#{$name};
  }
}

css outputs

.selector__child-1,
.selector__child-2 {
  font-size: 16px;
}

$spritesheets

data store of sprite sheets

Type

List, Map

Examples

scss inputs

// format of spritesheets
$spritesheets: (
  // each by types of spritesheet
  (
      'icon-image': (
        'image': 'path/to/sprite/icon-image.png',
        'items': (
          // output each by items
          'logo': (
              'width': 10px,
              'height': 10px,
              'total-width': 30px,
              'total-height': 30px,
              'offset-x': -10px,
              'offset-y': -10px
            ),
          ...
        )
      )
    ),
  ...
);

@function get-sheet-by-type

get sheet by type from values of spritesheets

Parameters

Name	Type	Description	Default
$type	String	type of spritesheet	-
$spritesheets	Map	data of spritesheets	()

Returns

Map, Null

@function normalize

normalize values of spritesheet

Parameters

Name	Type	Description	Default
$values	Map, List	values of spritesheet	()

Returns

Map, Null

@mixin define

Define spritesheet

Parameters

Name	Type	Description	Default
$type	String	type of spritesheet	-
$name	String	name of spritesheet item	-
$options	Map	options	()
$options.use2x	Boolean	use 2x image or (one of true, false or breakpoint name)	false
$options.as-mask	Boolean	use as mask image or not	false
$options.responsive	Boolean	responsive or not	false
$options.toggle	Boolean	toggle or not	false
$options.capturing-selectors	List	capturing parent selectors	("a", "button")

Examples

scss inputs

// use spritesheet plugin with configuration
@use 'path/to/node_modules/unit/src/plugin/spritesheet' with (
  $spritesheets: (
    'icon-image': (
      'image': 'path/to/sprite/icon-image.png',
      'items': (
        'logo': (
          'width': 10px,
          'height': 10px,
          'total-width': 30px,
          'total-height': 30px,
          'offset-x': -10px,
          'offset-y': -10px
        )
      )
    )
  )
);

// use this mixin
.selector {
  @include spritesheet.define($type: 'icon-image', $name: 'logo');
}

css outputs

.selector-logo {
  --background-image: url(path/to/sprite/icon-image.png);
  background-image: var(--background-image);
}
.selector-logo {
  --overflow: hidden;
  --color: transparent;
  --text-indent: -100%;
}
.selector-logo {
  --width: 10px;
  width: var(--width);
  --height: 10px;
  height: var(--height);
  --background-position: -10px -10px;
  background-position: var(--background-position);
  --background-size: 30px 30px;
  background-size: var(--background-size);
}

@mixin define-item

Define item

Parameters

Name	Type	Description	Default
$name	String	name of spritesheet item	-
$items	Map	spritesheet items	()
$options	Map	options	()

@mixin define-responsive-item

Define responsive item

Parameters

Name	Type	Description	Default
$name	String	name of spritesheet item	-
$items	Map	spritesheet items	()
$options	Map	options	()

@mixin define-responsive-toggle-item

Define responsive toggle item

Parameters

Name	Type	Description	Default
$name	String	name of spritesheet item	-
$items	Map	spritesheet items	()
$options	Map	options	()

@mixin define-toggle-item

Define toggle item

Parameters

Name	Type	Description	Default
$name	String	name of spritesheet item	-
$items	Map	spritesheet items	()
$options	Map	options	()

@mixin set-properties

set properties

Parameters

Name	Type	Description	Default
$values	Map	values of item	()
$options	Map	options	()

@function inverse

return inverse selector

Parameters

Name	Type	Description	Default
$selector	String	selector	-

Examples

scss inputs

.selector {
  content: function.selector-inverse('.hoge');
}

css outputs

.selector {
  content: ':not(.hoge)';
}

@function encode-url

return url encoded string

Parameters

Name	Type	Description	Default
$string	String	string	-

Returns

String url encoded string

Examples

scss inputs

.selector {
  content: function.string-encode-url(
    '<svg xmlns="http://www.w3.org/2000/svg"></svg>'
  );
}

css outputs

.selector {
  content: <svg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22><%2Fsvg>;
}

@function replace

replace string

Parameters

Name	Type	Description	Default
$string	String	string	-
$search	String	substring to replace	-
$replace	String	replacement string	""
$options	Map	options	()

Returns

String replaced string

Examples

scss inputs

.selector {
  content: function.string-replace('hogefugapiyohogefugapiyo', 'fuga', 'FUGA');
}

css outputs

.selector {
  content: hogeFUGApiyohogeFUGApiyo;
}

@function sprintf

sprintf

Parameters

Name	Type	Description	Default
$format	String	format	-
$args	List	arguments	-

Returns

String formatted string

Examples

scss inputs

.selector {
  content: function.string-sprintf(
    '%s is small capital of %s.',
    'fuga',
    'FUGA'
  );
}

css outputs

.selector {
  content: fuga is small capital of FUGA.;
}

@mixin apply-line-truncate

apply multi line truncate

Parameters

Name	Type	Description	Default
$line	Number	line length	2

Examples

scss inputs

.selector {
  @include mixin.text-apply-line-truncate($line: 3);
}

css outputs

.selector {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 3;
}

@function reserve

reserve z-index value each by types

Parameters

Name	Type	Description	Default
$type	String	content type name	-
$index	Number	index number	-
$options	Map	options	-
$options.debug	Boolean	debug flag	false

Returns

Number z-index value

Examples

scss inputs

.selector {
  content: function.z-index-reserve('floating', 100);
}

css outputs

.selector {
  content: 2000100;
}

Test

$ pnpm test

License

MIT