Merge pull request #49 from pepabo/attach-sassdoc

adapter-functionにSassDocを添付します

packages/adapter/functions/color/_background.scss

@@ -9,6 +9,12 @@ $background-color-tokens: map.get(
   background
 );
 
+/// 汎用的に使えるbackground colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-background-color($name: light, $type: well)
+///   // ”f7f8fa”
 @function get-background-color($name: light, $type: base) {
   $base-tokens: map.get($background-color-tokens, base);
   $brand-colors: brand, accent;
@@ -51,6 +57,12 @@ $background-color-tokens: map.get(
   }
 }
 
+/// モーダルなオーバーレイなどで使うscrimのbackground colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-scrim-background-color()
+///   // ”rgba(0, 0, 0, 0.32)”
 @function get-scrim-background-color() {
   @return map.get($background-color-tokens, scrim);
 }

packages/adapter/functions/color/_border.scss

@@ -14,6 +14,12 @@ $border-color-tokens: map.get(
   border
 );
 
+/// 汎用的に使えるborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-border-color($brightness: light, $name: high_emphasis)
+///   // ”rgba(57, 60, 65, 0.3)”
 @function get-border-color($brightness: light, $name: high_emphasis) {
   $tokens: map.get($border-color-tokens, base);
   $available-brightnesses: helpers.get-brightnesses();
@@ -43,10 +49,22 @@ $border-color-tokens: map.get(
   @return map.get($brightness-tokens, $name);
 }
 
+/// avatarのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-avatar-border-color()
+///   // ”rgba(0, 0, 0, 0)”
 @function get-avatar-border-color() {
   @return map.get($border-color-tokens, avatar);
 }
 
+/// buttonのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-button-border-color($appearance: flat, $color: neutral, $state: enabled)
+///   // ”transparent”
 @function get-button-border-color(
   $appearance: flat,
   $color: neutral,
@@ -104,6 +122,12 @@ $border-color-tokens: map.get(
   }
 }
 
+/// checkboxのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-checkbox-border-color($states: (enabled))
+///   //”rgba(57, 60, 65, 0.2)”
 @function get-checkbox-border-color($states: (enabled)) {
   $available-states: helpers.get-states();
 
@@ -124,6 +148,12 @@ $border-color-tokens: map.get(
 }
 
 /// @deprecated この関数は非推奨です
+/// focus ringのcolorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-focus-ring-color($color: neutral)
+///   //”#9297a1”
 @function get-focus-ring-color($color: neutral) {
   $available-colors: list.join(
     helpers.get-semantic-intentions(),
@@ -182,10 +212,22 @@ $border-color-tokens: map.get(
   }
 }
 
+/// interactive-listのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-interactive-list-border-color()
+///   // ”rgba(57, 60, 65, 0.2)”
 @function get-interactive-list-border-color() {
   @return map.get($border-color-tokens, interactive-list);
 }
 
+/// interactive-tableのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-interactive-table-border-color($element: header)
+///   // “rgba(57, 60, 65, 0.3)”
 @function get-interactive-table-border-color($element: header) {
   $tokens: map.get($border-color-tokens, interactive-table);
   $available-elements: header, data;
@@ -200,6 +242,12 @@ $border-color-tokens: map.get(
   @return map.get($tokens, $element);
 }
 
+/// radioのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-radio-border-color($states: (enabled))
+///   // ”rgba(57, 60, 65, 0.2)”
 @function get-radio-border-color($states: (enabled)) {
   $available-states: helpers.get-states();
 
@@ -219,10 +267,22 @@ $border-color-tokens: map.get(
   }
 }
 
+/// side-navigationのborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-side-navigation-border-color()
+///   // ”rgba(57, 60, 65, 0.2)”
 @function get-side-navigation-border-color() {
   @return map.get($border-color-tokens, side-navigation);
 }
 
+/// textfieldとselectで共通するfield部分のborder colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-field-border-color(neutral, enabled)
+///   // ”#afb3ba”
 @function get-field-border-color($color: neutral, $state: enabled) {
   $tokens: map.get($border-color-tokens, field);
   $color-tokens: map.get($tokens, $color);

packages/adapter/functions/color/_button.scss

@@ -9,6 +9,12 @@ $button-color-tokens: map.get(
   button
 );
 
+/// buttonのbackground colorを取得します。注意事項あり
+///
+/// @group color
+/// @example
+///   functions.get-button-color(neutral)
+///   // “#585c63”
 @function get-button-color($color: neutral) {
   $tokens: map.get($button-color-tokens, base);
   $available-colors: helpers.get-button-colors();

packages/adapter/functions/color/_implication.scss

@@ -9,6 +9,12 @@ $implication-color-tokens: map.get(
   implication
 );
 
+/// implication colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-implication-color(interactive, 600)
+///   // ”#1f7acc”
 @function get-implication-color($name: interactive, $level: 1000) {
   $available-implications: helpers.get-implications();
 

packages/adapter/functions/color/_overlay.scss

@@ -9,6 +9,12 @@ $overlay-color-tokens: map.get(
   overlay
 );
 
+/// checkbox, radioなどinteractiveな要素にhoverやfocusしたときのoverlay colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-background-overlay-color(light, enabled)
+///   // “rgba(0, 0, 0, 0)”
 @function get-background-overlay-color($brightness: light, $state: enabled) {
   $tokens: map.get($overlay-color-tokens, background);
   $available-brightnesses: helpers.get-brightnesses();
@@ -33,6 +39,12 @@ $overlay-color-tokens: map.get(
   @return map.get($brightness-tokens, $state);
 }
 
+/// 画像にhoverやfocusしたときのoverlay colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-image-overlay-color(enabled)
+///   // “rgba(0, 0, 0, 0)”
 @function get-image-overlay-color($state: enabled) {
   $tokens: map.get($overlay-color-tokens, image);
   $available-states: helpers.get-states();

packages/adapter/functions/color/_primitive.scss

@@ -9,6 +9,12 @@ $primitive-color-tokens: map.get(
   primitive
 );
 
+/// 汎用的に使えるprimitive colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-primitive-color($name: blue, $level: 600)
+///   // “#1f7acc”
 @function get-primitive-color($name, $level: 1000) {
   $primitive-color-name: map.get($primitive-color-tokens, "#{$name}");
 

packages/adapter/functions/color/_semantic.scss

@@ -9,6 +9,12 @@ $semantic-color-tokens: map.get(
   semantic
 );
 
+/// 意味が付与されたsemantic colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-semantic-color(informative, 600)
+///   // “#1f7acc”
 @function get-semantic-color($intention: neutral, $level: 1000) {
   $available-semantics: helpers.get-semantic-intentions();
 

packages/adapter/functions/color/_surface.scss

@@ -13,6 +13,13 @@ $surface-color-tokens: map.get(
   surface
 );
 
+/// 汎用的に使えるsurface colorを取得します。
+/// ページやビューなど最下層でbackground colorを持つ要素の上に乗った、形のあるオブジェクト表面の色がsurface colorです。
+///
+/// @group color
+/// @example
+///   functions.get-surface-color(light, secondary)
+///   // “#f7f8fa”
 @function get-surface-color($brightness: light, $priority: primary) {
   $tokens: map.get($surface-color-tokens, base);
   $available-brightnesses: helpers.get-brightnesses();
@@ -37,10 +44,22 @@ $surface-color-tokens: map.get(
   @return map.get($brightness-tokens, $priority);
 }
 
+/// avatarのsurface colorを取得します。
+///
+/// @group color
+/// @example
+///   functions.get-avatar-surface-color()
+///   // “#f7f8fa”
 @function get-avatar-surface-color() {
   @return map.get($surface-color-tokens, avatar);
 }
 
+/// bottom-navigationのsurface colorを取得します。
+///
+/// @group color
+/// @example
+///   function get-bottom-navigation-surface-color(filled)
+///   // “#1f7acc”
 @function get-bottom-navigation-surface-color($appearance: white) {
   $tokens: map.get($surface-color-tokens, bottom-navigation);
   $available-appearances: helpers.get-bottom-navigation-appearances();
@@ -55,6 +74,12 @@ $surface-color-tokens: map.get(
   @return map.get($tokens, $appearance);
 }
 
+/// solidなappearanceのbuttonのグラデーションを構成するscrimのcolorを取得します。
+///
+/// @group color
+/// @example
+///   function.get-solid-button-scrim-color(start)
+///   // “rgba(255, 255, 255, 0.25)”
 @function get-solid-button-scrim-color($position: start) {
   $tokens: map.get(map.get(map.get($surface-color-tokens, button), solid), scrim);
   $available-positions: start, end;
@@ -69,6 +94,12 @@ $surface-color-tokens: map.get(
   @return map.get($tokens, $position);
 }
 
+/// buttonのsurface colorを取得します。
+///
+/// @group color
+/// @example
+///   function.get-button-surface-color($appearance: flat, $brightness: light, $color: neutral, $state: enabled)
+///   // “#585c63”
 @function get-button-surface-color(
   $appearance: flat,
   $brightness: light,
@@ -156,6 +187,13 @@ $surface-color-tokens: map.get(
   }
 }
 
+/// 最終的なbutton表面の色を定義したbackground-imageのグラデーションを取得します。
+/// 内部でget-button-surface-color()を使っています。
+///
+/// @group color
+/// @example
+///   function.get-button-surface-image($appearance: flat, $brightness: light, $color: neutral, $own-brightness: light, $state: enabled)
+///   // “linear-gradient(rgba(0, 0, 0, 0), rgba(0, 0, 0, 0)), linear-gradient(#585c63, #585c63)”
 @function get-button-surface-image(
   $appearance: flat,
   $brightness: light,
@@ -243,6 +281,12 @@ $surface-color-tokens: map.get(
   }
 }
 
+/// checkboxのsurfaceのcolorを取得します。
+///
+/// @group color
+/// @example
+///   function.get-checkbox-surface-color(enabled)
+///   // “#ffffff”
 @function get-checkbox-surface-color($states: (enabled)) {
   $tokens: map.get($surface-color-tokens, checkbox);
   $available-states: helpers.get-states();
@@ -263,6 +307,12 @@ $surface-color-tokens: map.get(
   }
 }
 
+/// ヘッダーの背景色を取得します
+///
+/// @group color
+/// @example
+///   functions.get-header-surface-color($appearance: filled)
+///   // #1f7acc
 @function get-header-surface-color($appearance: white) {
   $header-tokens: map.get($surface-color-tokens, header);
   $available-appearances: helpers.get-header-appearances();
@@ -277,12 +327,24 @@ $surface-color-tokens: map.get(
   @return map.get($header-tokens, #{$appearance});
 }
 
+/// プログレスインジケーターの全体を表すtrack（溝）部分のカラーを取得します
+///
+/// @group color
+/// @example
+///   functions.get-progress-indicator-track-surface-color()
+///   // #e5f3ff
 @function get-progress-indicator-track-surface-color() {
   $tokens: map.get($surface-color-tokens, progress-indicator);
 
   @return map.get($tokens, track);
 }
 
+/// プログレスインジケーターの進捗を表すindicator部分のカラーを取得します
+///
+/// @group color
+/// @example
+///   functions.get-progress-indicator-indicator-surface-color()
+///   // #3e93de
 @function get-progress-indicator-indicator-surface-color() {
   $tokens: map.get($surface-color-tokens, progress-indicator);
 
@@ -293,10 +355,25 @@ $surface-color-tokens: map.get(
   @return get-surface-color($brightness: light, $priority: primary);
 }
 
+/// スケルトン背景の背景色を取得します
+///
+/// @group color
+/// @example
+///   functions.get-skeleton-surface-color()
+///   // rgba(0, 0, 0, 0.2)
 @function get-skeleton-surface-color() {
   @return map.get($surface-color-tokens, skeleton);
 }
 
+/// フィールド要素の背景色を取得します
+///
+/// @group color
+/// @example
+///   functions.get-field-surface-color(
+///     $color: neutral,
+///     $state: enabled
+///   )
+///   // #f7f8fa
 @function get-field-surface-color($color: neutral, $state: enabled) {
   $tokens: map.get($surface-color-tokens, field);
   $color-tokens: map.get($tokens, $color);