asharyu-design-token 1.0.3 → 2.0.4

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a original work of authorship. For the purposes of this
+      License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022 yoonjonglyu(ISA)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -21,6 +21,7 @@ yarn add asharyu-design-token
 1. css
 
 ```js
+import 'normalize.css';
 import 'asharyu-design-token/index.css';
 ```
 
@@ -32,66 +33,100 @@ import Token from 'asharyu-design-token';
 
 ## Concept
 
-![음야오행 색상도](./wuxingcolor.png);
+**asharyu**는 동양 철학인 음양오행설을 현대적인 인터페이스 가이드라인에 투영한 디자인 시스템입니다. 디자인 감각에만 의존하지 않고, 요소 간의 상생(相生)과 상극(相剋) 관계를 통해 논리적이고 의미론적인(Semantic) UI 구성을 지향합니다.
 
-철학적인 요소를 결합해서 CSS 디자인 시스템을 HTML 처럼 시맨틱하게 할 수 없을까? 라는 발상으로 컨셉을 잡고 시작한 프로젝트입니다. 음양오행설을 베이스로 삼고 어레인지해서 컨셉을 잡습니다.  
-오행 정색과 간색의 기본색을 정의하고 기본 베이스로 삼았습니다. 음양을 상징하는 흑백(동,서)의 경우 1단계씩 나머지 3정색은 2단계 또 간색은 1단계씩 색상의 단계를 정의하여서 0,1,2,3,4(0의 경우 무시) 5단계로 색상을 정의하였습니다.  
-오행 정색과 간색의 경우 색상에 대한 정의가 제각각인 점이 있어서 편의적으로 규정한 부분이 있습니다. 실제 철학적인 색상과 100% 일치하지 않습니다.  
-음양을 기반으로한 심플한 스타일의 디자인 테마와 오행을 기반으로 각 5원소와 그 5원소간의 상극 과정에서 도출되는 간색의 위계와 조화를 통해서 이론적으로 색의 조합과 그 색을 통한 문서의 철학적인(직관) 표현을 유도하는 것이 기본 컨셉입니다.
+- **음양 (Yin-Yang):** 명암의 대비를 통해 라이트/다크 테마의 질서와 반전을 정의합니다.
+- **오행 (Five Elements):** 목(Action), 화(Danger), 토(Surface), 금(Border), 수(Info)의 기운으로 기능적 위계를 구분합니다.
+- **필치와 검의 예리함:** 수묵의 번짐(Bleed)과 날카로운 필압(Stroke Weight)을 인터랙션과 스타일의 핵심 요소로 삼습니다.
 
-심플한 스타일의 음양 테마와 화려하면서도 정갈한 오행의 시맨틱한 디자인을 표현하는 것을 디자인 시스템의 컨셉으로 삼았습니다.  
-해당 프로젝트는 디자인 감각에 의존하지 않아도 되는 시맨틱 CSS를 추구합니다.
+### 오행의 기능적 역할 (Functional Roles)
 
+| 오행 (Element) | 시맨틱 역할 | 주요 용도 | 기운의 성질 |
+| :--- | :--- | :--- | :--- |
+| **목 (Wood)** | `Action` | 주 버튼(Primary), 시작, 긍정 상태 | 솟구치는 시작 |
+| **화 (Fire)** | `Danger` | 경고, 오류, 삭제, 중요 알림 | 확산되는 경고 |
+| **토 (Earth)** | `Surface` | 카드, 컨테이너 배경, 머무르는 공간 | 머무르는 안정 |
+| **금 (Metal)** | `Border` | 보조 버튼(Confirm), 경계선, 결단 | 응축된 결단 |
+| **수 (Water)** | `Info` | 정보 전달, 네비게이션, 탐색 | 흐르는 정보 |
+
+이러한 시맨틱 정의를 통해 개발자와 디자이너는 색상 선택 시 주관적인 감각 대신 시스템의 논리(상생/상극)에 따라 의사결정을 내릴 수 있습니다.
+
+### 상생과 상극의 인터랙션 (Interaction Guide)
+
+디자인 시스템의 동적인 기운(Motion)은 오행의 순환 논리인 상생과 상극에 기반합니다.
+
+| 분류 (Category) | 기운 (Ki-Un) | 인터랙션 성격 | 권장 사용 사례 |
+| :--- | :--- | :--- | :--- |
+| **상생 (Sangsaeng)** | `Gentle` | 부드럽고 유연한 연결 | 긍정적인 여정, 일반적인 상태 변화, 페이지 전환 |
+| **상극 (Sanggeuk)** | `Sharp / Spread` | 예리한 대비와 제어 | 경고, 오류, 중요 알림, 삭제 시의 긴장감 표현 |
+
+- **상생 Flow (`flow.sangSaeng`):** 물이 나무를 자라게 하듯 자연스러운 흐름을 표현할 때 사용하며, 사용자 경험의 연속성을 확보합니다.
+- **상극 Feedback (`feedback.sangGeuk...`):** 화기가 금속을 녹이듯 강한 시각적 제어가 필요할 때 사용합니다. 예리한 필압의 결단(`decisive`) 혹은 충돌하여 널리 퍼지는 경고(`spread`)로 구분됩니다.
+
+이러한 인터랙션 원칙은 단순한 애니메이션을 넘어, 인터페이스 내의 기운의 흐름과 긴장을 조절하는 핵심 장치입니다.
+
+### 인터랙션 토큰 사용 예제 (Usage Examples)
+
+**1. 순수 CSS에서 사용**
+
+```css
+/* 예: 버튼 호버 시 상생 흐름 애니메이션 적용 */
+.my-button {
+  transition: var(--asharyu-interaction-flow-sang-saeng);
+  /* 다른 스타일 */
+}
+
+/* 예: 경고 메시지 등장 시 상극 확산 애니메이션 적용 */
+.alert-message {
+  animation: fade-in-spread 0.8s var(--asharyu-interaction-feedback-sang-geuk-spread);
+  /* 다른 스타일 */
+}
+
+@keyframes fade-in-spread {
+  from { opacity: 0; transform: scale(0.9); }
+  to { opacity: 1; transform: scale(1); }
+}
+```
+
+**2. Emotion (React)에서 사용**
+
+```tsx
+import styled from '@emotion/styled';
+import { tokens } from 'asharyu-design-token'; // JS 브릿지 토큰 임포트
+
+const AnimatedButton = styled.button`
+  transition: ${tokens.interaction.flow.sangSaeng};
+  background-color: ${tokens.color.semantic.action.primary};
+  color: ${tokens.color.semantic.background};
+  /* 다른 스타일 */
+`;
+```
 ## Token Structure
 
-core 토큰 구성요소 `label`, `scale`, `type`, `category`는 4가지.
+모든 토큰은 `--asharyu-` 접두사를 가지며, **Raw(원형)**와 **Semantic(의미)** 계층으로 나뉩니다.
 
-`$red-1`: `label-scale`;  
-`$color-red-1`: `type-label-scale`;  
-`$light-color-red-1`:`category-type-label-scale`;
+### 1. Naming Convention (Sword's Edge)
+모든 키값은 CamelCase에서 Kebab-case로 자동 변환되어 생성됩니다.
+예: `yinText` (JS) -> `--asharyu-color-semantic-yin-text` (CSS)
 
-기본이 되는 value schema와 sementic layer가 존재한다.  
-토큰은 css와 js(타입스크립트 지원) 두가지 구조로 구성 되어있다.
-css의 경우 [CSS var](https://developer.mozilla.org/ko/docs/Web/CSS/var)로 제공된다.
+### 2. Semantic Layers
+테마 전환 시 시맨틱 토큰의 값은 자동으로 상응하는 음/양의 값으로 교체됩니다.
 
 ```css
 :root {
-  --color-yinyang-yin: #000000;
-  --color-yinyang-yin-1: #111111;
-  --color-yinyang-yin-2: #222222;
-  --color-yinyang-yin-3: #333333;
-  --color-yinyang-yin-4: #444444;
-  --color-yinyang-yang: #ffffff;
-  --color-yinyang-yang-1: #eeeeee;
-  --color-yinyang-yang-2: #dddddd;
-  --color-yinyang-yang-3: #cccccc;
-  --color-yinyang-yang-4: #bbbbbb;
-  --color-fiveelements-wood: #0000ff;
-  --color-fiveelements-wood-1: #0000dd;
-  --color-fiveelements-wood-2: #0000bb;
-  --color-fiveelements-wood-3: #000099;
-  --color-fiveelements-wood-4: #000077;
-  --color-fiveelements-fire: #ff0000;
-  --color-fiveelements-fire-1: #dd0000;
-  --color-fiveelements-fire-2: #bb0000;
-  --color-fiveelements-fire-3: #990000;
-  --color-fiveelements-fire-4: #770000;
-  --color-fiveelements-earth: #ffff00;
-  --color-fiveelements-earth-1: #dddd00;
-  --color-fiveelements-earth-2: #bbbb00;
-  --color-fiveelements-earth-3: #999900;
-  --color-fiveelements-earth-4: #777700;
-  --color-fiveelements-metal: #ffffff;
-  --color-fiveelements-metal-1: #eeeeee;
-  --color-fiveelements-metal-2: #dddddd;
-  --color-fiveelements-metal-3: #cccccc;
-  --color-fiveelements-metal-4: #bbbbbb;
-  --color-fiveelements-water: #000000;
-  --color-fiveelements-water-1: #111111;
-  --color-fiveelements-water-2: #222222;
-  --color-fiveelements-water-3: #333333;
-  --color-fiveelements-water-4: #444444;
-  ......
+  /* 🎨 Color: Raw & Semantic */
+  --asharyu-color-raw-wood-2: #7BA2BE;
+  --asharyu-color-semantic-action-primary: var(--asharyu-color-raw-wood-2);
+  --asharyu-color-semantic-background: #fdfaf4;
+  --asharyu-color-semantic-text: #0c0c0c;
+
+  /* ✍️ Typography */
+  --asharyu-font-semantic-h1: 4.25rem;
+  --asharyu-font-semantic-body1: 1rem;
+
+  /* 🌬️ Motion & Stroke */
+  --asharyu-motion-duration-bleed: 0.8s;
+  --asharyu-stroke-weight-heavy: 3px;
 }
 ```