Asharyu-design-token

디자인 토큰

Install

1.npm

npm i asharyu-design-token

2.yarn

yarn add asharyu-design-token

Usage

1. css

import 'normalize.css';
import 'asharyu-design-token/index.css';

2.js(ts)

import Token from 'asharyu-design-token';

Concept

asharyu는 동양 철학인 음양오행설을 현대적인 인터페이스 가이드라인에 투영한 디자인 시스템입니다. 디자인 감각에만 의존하지 않고, 요소 간의 상생(相生)과 상극(相剋) 관계를 통해 논리적이고 의미론적인(Semantic) UI 구성을 지향합니다.

• 음양 (Yin-Yang): 명암의 대비를 통해 라이트/다크 테마의 질서와 반전을 정의합니다.
• 오행 (Five Elements): 목(Action), 화(Danger), 토(Surface), 금(Border), 수(Info)의 기운으로 기능적 위계를 구분합니다.
• 필치와 검의 예리함: 수묵의 번짐(Bleed)과 날카로운 필압(Stroke Weight)을 인터랙션과 스타일의 핵심 요소로 삼습니다.

오행의 기능적 역할 (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에서 사용

/* 예: 버튼 호버 시 상생 흐름 애니메이션 적용 */
.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)에서 사용

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

모든 토큰은 --asharyu- 접두사를 가지며, **Raw(원형)**와 Semantic(의미) 계층으로 나뉩니다.

1. Naming Convention (Sword's Edge)

모든 키값은 CamelCase에서 Kebab-case로 자동 변환되어 생성됩니다. 예: yinText (JS) -> --asharyu-color-semantic-yin-text (CSS)

2. Semantic Layers

테마 전환 시 시맨틱 토큰의 값은 자동으로 상응하는 음/양의 값으로 교체됩니다.

:root {
  /* 🎨 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;
}

License

This project is licensed under the Apache 2.0 License.