@uinamic/colors

v0.2.4

Published

a year ago

CSS color token generator centered on HSL lightness (HSL 기반 명도 중심 CSS 색상 토큰 생성기)

0High
0Medium
0Low

color colors color-token design-token palette theme theme-builder hsl hsl-color css css-variables style design-system cli npx uinamic

@uinamic/colors 🎨 (0.2 version)

[!NOTE] CSS color token generator centered on HSL lightness (HSL 기반 명도 중심 색상 스펙트럼 자동 생성기)

ⅰ English

✨ Features
Generates a 9-step asymmetrical spectrum based on central lightness (100~900)
Built-in brightness correction algorithm for detecting extreme zones
1:4 distribution-based color calculation considering perceptual balance
Supports :root CSS variables, SCSS, and JSON formats
Zero-dependency, fast execution, available via CLI and API
🖐 Spectrum Structure
generateColorTokens() generates a 9-step asymmetrical lightness spectrum based on a central lightness value (centerL).
Larger changes near the center, smaller steps towards the edges.
Smooth drop towards low lightness, wider spread towards high lightness.
limit option restricts the allowable lightness range.
Example: If limit is 20, tokens are generated within 20%~80% of the full 0~100 lightness range.

ⅱ Korean

✨ 주요 특징
중심 명도(L)를 기준으로 9단계 비대칭 스펙트럼 생성 (100~900)
극단 영역 자동 감지 및 밝기 보정 알고리즘 탑재
perceptual 균형을 고려한 1:4 분포 기반 색상 계산
:root 내 CSS 변수 혹은 SCSS/JSON 포맷 지원
zero-dependency, 빠른 실행, CLI 및 API 모두 사용 가능
🖐 스펙트럼 구조
generateColorTokens()는 중심 명도값(centerL)을 기준으로 비대칭적인 9단계 명도 분할을 생성합니다.
중심과 가까워지면 명도 변화가 큰 것이 특징.
거리가 멀어지면서 명도 변화량이 작아진다.
낮은 방향은 수직적으로 낮아지고, 높은 방향은 넓게 확장됩니다.
limit 옵션은 중심 명도 기준으로 명도 범위를 제한합니다.
예시: limit 값이 20일 경우, 0~100 범위 내에서 20%~80% 구간에서만 토큰이 생성됩니다.

📦 Installation (설치)

npm install -D @uinamic/colors
# or
pnpm add -D @uinamic/colors

📖 Example (centerL = 50)

※ generateColorTokens automatically adjusts results within a 0~100 lightness range.

[5, 16, 27, 38, (50), 62, 73, 84, 95]
[  ↑   ↑   ↑   ↑     ↑   ↑   ↑   ↑]
[ 11  11  11  12     12  11  11  11] ← Step intervals

(50) is the central lightness.
Gradual division near the center with smart bias adjustments.
If centerL is below 20 or above 80:
- limit is fixed to 3.
- lowRange = centerL - 3
- highRange = lowRange * 4

🧪 Example (pink)

pink: [340, 100, 88] → [52, 58, 64, 70, 76, 82, 88, 94, 97]

📂 Options

| Option | Description | | ------ | ------------------------------------------------------ | | format | Output format ('css', 'scss', 'json') (default: 'css') | | prefix | Variable prefix (default: '--color-') | | name | Output file name (default: 'uinamic-color') | | path | Output directory (default: './theme') | | limit | Lightness range limit (e.g., 20 means 20%~80%) |

🛠️ Usage

🧹 1. Run directly via terminal (npx)

npx @uinamic/colors
npx @uinamic/colors --name color
npx @uinamic/colors --format css
npx @uinamic/colors --format scss
npx @uinamic/colors --prefix theme
npx @uinamic/colors --path ./palette
npx @uinamic/colors --limit 20

# Composite options example
npx @uinamic/colors --path ./palette --name palette --format scss --prefix font-color --limit 20

🧹 2. Use with a custom color map

import { generateColorTokens } from '@uinamic/colors'

const myColorMap = {
    mint: [160, 100, 50],
    coral: [16, 100, 60],
}

const css = generateColorTokens(myColorMap)

// Run node generate-color-css.js

🌈 Custom Colormap & Advanced Options

const scss = generateColorTokens(
    {
        mint: [160, 100, 50],
    },
    {
        format: 'scss',
        prefix: 'theme',
        name: 'color',
        path: './custom',
        limit: 8,
    }
)

Example Output

$theme-mint-100: hsl(160, 100%, 8%);
$theme-mint-200: hsl(160, 100%, 18%);
...
$theme-mint-900: hsl(160, 100%, 92%);

💡 Default Provided Colors

{
  red: [0, 100, 50],
  blue: [240, 100, 50],
  yellow: [60, 100, 50],
  orange: [39, 100, 50],
  green: [120, 100, 40],
  purple: [270, 100, 60],
  pink: [340, 100, 88],
  teal: [180, 100, 45],
  gray: [0, 0, 50],
  darkgray: [0, 0, 30],
  lightgray: [0, 0, 70],
  coral: [16, 100, 65],
  mint: [160, 100, 50],
  cyan: [190, 100, 60],
  violet: [290, 76, 72],
  indigo: [225, 100, 45],
  amber: [45, 100, 50],
}

💡 CSS Variable Example

:root {
  --color-black: hsl(0, 0%, 0%);
  --color-white: hsl(0, 0%, 100%);
  --color-red-100: hsl(0, 100%, 5%);
  ...
  --color-blue-900: hsl(240, 100%, 95%);
}

💡 Future Plan (v0.3)

Add offset option to adjust spectrum baseline.

generateColorTokens(
    {
        mint: [160, 100, 50],
    },
    {
        format: 'css',
        offset: 2,
    }
)

Example Output:

--color-mint-100: hsl(160, 100%, 7%);
--color-mint-200: hsl(160, 100%, 12%);
--color-mint-300: hsl(160, 100%, 18%);
--color-mint-400: hsl(160, 100%, 25%);
--color-mint-500: hsl(160, 100%, 32%);
--color-mint-600: hsl(160, 100%, 42%);
--color-mint-700: hsl(160, 100%, 50%); /* center */
--color-mint-800: hsl(160, 100%, 59%);
--color-mint-900: hsl(160, 100%, 69%);

📖 예시 centerL = 50

※ generateColorTokens는 항상 명도 0~100 범위 내에서 결과를 자동 조정합니다.

[5, 16, 27, 38, (50), 62, 73, 84, 95]
[  ↑   ↑   ↑   ↑     ↑   ↑   ↑   ↑]
[ 11  11  11  12     12  11  11  11] ← 명도 간격

(50)은 중심 명도값입니다.
가까운 가까운 분할이지만, 중심부(값 12)를 기점으로 약간의 비율 조정이 있습니다.
smartBias + delta 가용치를 적용하여 감각적인 스텝플러버스트를 생성합니다.
입력값이 20 이하 또는 80 이상인 경우:
- limit 값은 3으로 고정합니다.
- lowRange = centerL - 3
- highRange = lowRange * 4
- 전체 명도 구조는 0~100 범위를 사용합니다.

🧪 예시 (pink)

pink: [340, 100, 88] → [52, 58, 64, 70, 76, 82, 88, 94, 97]

📂 옵션 설명

| 옵션 | 설명 | | ------ | ---------------------------------------------------- | | format | 출력 포맷 ('css', 'scss', 'json') 선택 (기본: 'css') | | prefix | CSS 변수 전치키 지정 (기본: '--color-') | | name | 생성할 파일명 (기본: 'uinamic-color') | | path | 파일 저장 경로 (기본: './theme') | | limit | 명도 허용 범위 설정 (ex: 20 → 20%~80%) |

🛠️ 사용법

🧽 1. 터미널에서 바로 실행 (npx)

npx @uinamic/colors
npx @uinamic/colors --name color
npx @uinamic/colors --format css
npx @uinamic/colors --format scss
npx @uinamic/colors --prefix theme
npx @uinamic/colors --path ./palette
npx @uinamic/colors --limit 20

# 복합 옵션 예시
npx @uinamic/colors --path ./palette --name palette --format scss --prefix font-color --limit 20

🧽 2. 사용자 정의 색상맵 사용

import { generateColorTokens } from '@uinamic/colors'

const myColorMap = {
    mint: [160, 100, 50],
    coral: [16, 100, 60],
}

const css = generateColorTokens(myColorMap)

// node generate-color-css.js 실행

🎨 커스텀 컬러맵 & 옵션 사용법

const scss = generateColorTokens(
    {
        mint: [160, 100, 50],
    },
    {
        format: 'scss',
        prefix: 'theme',
        name: 'color',
        path: './custom',
        limit: 8,
    }
)

// node color-css.js

출력 결과 (예시)

$theme-mint-100: hsl(160, 100%, 8%);
$theme-mint-200: hsl(160, 100%, 18%);
...
$theme-mint-900: hsl(160, 100%, 92%);

💡 기본 제공 색상맵

{
  red: [0, 100, 50],
  blue: [240, 100, 50],
  yellow: [60, 100, 50],
  orange: [39, 100, 50],
  green: [120, 100, 40],
  purple: [270, 100, 60],
  pink: [340, 100, 88],
  teal: [180, 100, 45],
  gray: [0, 0, 50],
  darkgray: [0, 0, 30],
  lightgray: [0, 0, 70],
  coral: [16, 100, 65],
  mint: [160, 100, 50],
  cyan: [190, 100, 60],
  violet: [290, 76, 72],
  indigo: [225, 100, 45],
  amber: [45, 100, 50],
}

💡 CSS 변수 형식 예시

:root {
  --color-black: hsl(0, 0%, 0%);
  --color-white: hsl(0, 0%, 100%);
  --color-red-100: hsl(0, 100%, 5%);
  ...
  --color-blue-900: hsl(240, 100%, 95%);
}

💡 향후 계획 (v0.3)

offset 옵션 추가
- 스펙트럼의 기본 위치 조정 가능

generateColorTokens(
    {
        mint: [160, 100, 50],
    },
    {
        format: 'css',
        offset: 2,
    }
)

결과

--color-mint-100: hsl(160, 100%, 7%);
--color-mint-200: hsl(160, 100%, 12%);
--color-mint-300: hsl(160, 100%, 18%);
--color-mint-400: hsl(160, 100%, 25%);
--color-mint-500: hsl(160, 100%, 32%);
--color-mint-600: hsl(160, 100%, 42%);
--color-mint-700: hsl(160, 100%, 50%); /* 중심 */
--color-mint-800: hsl(160, 100%, 59%);
--color-mint-900: hsl(160, 100%, 69%);