lightstair-css 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 박민권
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,122 @@
+<p align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="./preview/icon-dark.svg">
+        <img src="./preview/icon-light.svg" alt="LightStair CSS logo" width="140">
+    </picture>
+</p>
+
+<h1 align="center">LightStair CSS</h1>
+
+<p align="center">
+    <a href="README.ko.md">한국어</a> ·
+    <a href="README.md">English</a>
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+</p>
+
+<p align="center">
+    OKLCH 색상 공간을 기반으로 글자·배경·테두리 색의 밝기 단계를 설정하여 CSS 파일을 생성하는 CLI 도구.
+</p>
+
+<p align="center">
+    <img src="./assets/demo.gif" alt="Demo" width="800">
+</p>
+
+---
+
+## 이 도구가 필요한 이유
+
+CSS에서 특정 색상의 밝기를 여러 단계로 선언해 두고 사용하고 싶을 때가 있습니다. 하지만 똑같은 밝기라도 글자·배경·테두리 색은 서로 다른 밝기 단계로 설정해야 합니다. 또한, 글자·배경·테두리 색의 조합도 맞춰봐야 하고 다크 모드까지 고려해야 합니다. 이 도구는 이러한 과정을 도와줍니다.
+
+## 기능 소개
+
+- OKLCH 색상 공간 기반 설정
+- OKLCH, RGB, HEX 색상 값으로 내보내기
+- 다크 모드 지원
+- 로컬 서버 미리보기 제공
+  - 글자색 × 배경색 × 테두리색 조합 기능
+  - 라이트/다크 테마 같이 보기
+
+## 설치
+
+```bash
+npm install lightstair-css
+```
+
+## CLI
+
+### 도움말
+
+```bash
+lightstair-css --help
+```
+
+### 설정 파일 생성
+
+```bash
+lightstair-css init
+```
+
+실행 위치에 기본 [lightstair-css.yml](./templates/lightstair-css.yml) 설정 파일을 생성합니다. 설정 파일이 이미 존재하면 무시합니다.
+
+### CSS 파일 생성
+
+```bash
+lightstair-css [options]
+```
+
+기본으로 실행 위치에 `lightstair-css.css` 파일을 생성합니다. 실행 위치에 설정 파일이 없는 경우 기본 설정 파일이 자동으로 생성됩니다.
+
+기본 포맷은 `OKLCH`이며 생성된 CSS 변수들의 색상 값은 동적으로 계산하는 코드로 생성됩니다. `--bake [format]` 옵션을 사용하면 계산된 색상 값으로 CSS를 생성할 수 있습니다.
+
+```css
+/* 기본 코드 */
+--tx-1: oklch(clamp(0, var(--tx-init-l) + var(--tx-l-gap) * 0, 1) var(--tx-base-c) var(--tx-base-h));
+
+/* `--bake oklch` 옵션으로 계산된 코드 */
+--tx-1: oklch(0.31 0.01 250);
+
+/* `--bake rgb` 옵션으로 계산된 코드 */
+--tx-1: rgb(44.585 48.788 53.291);
+
+/* `--bake hex` 옵션으로 계산된 코드 */
+--tx-1: #2d3135;
+```
+
+### 미리보기 서버 실행
+
+```bash
+lightstair-css preview [options]
+```
+
+브라우저에서 `http://localhost:[port]`로 접속하면 미리보기 화면을 확인할 수 있습니다. 옵션으로 포트 번호를 명시하지 않으면 임의의 포트로 실행됩니다.
+
+### 명령어 예시
+
+```bash
+# 도움말
+lightstair-css --help
+
+# 기본 설정 파일 생성
+lightstair-css init
+
+# 기본 설정으로 CSS 파일 생성
+lightstair-css
+
+# 설정 파일과 출력 파일 지정
+lightstair-css -c my-config.yml -o dist/my-colors.css
+
+# 계산된 RGB 포맷으로 CSS 파일 생성
+lightstair-css --bake rgb
+
+# 계산된 HEX 포맷으로 CSS 파일 생성 및 출력 파일 지정
+lightstair-css --bake hex -o dist/my-colors.css
+
+# 미리보기 서버 시작
+lightstair-css preview
+
+# 포트 및 설정 파일을 지정하여 미리보기 서버 시작
+lightstair-css preview -p 3000 -c my-config.yml
+```

package/README.md

@@ -0,0 +1,122 @@
+<p align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="./preview/icon-dark.svg">
+        <img src="./preview/icon-light.svg" alt="LightStair CSS logo" width="140">
+    </picture>
+</p>
+
+<h1 align="center">LightStair CSS</h1>
+
+<p align="center">
+    <a href="README.ko.md">한국어</a> ·
+    <a href="README.md">English</a>
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+</p>
+
+<p align="center">
+    A CLI tool that generates CSS files by setting brightness steps for text, background, and border colors based on the OKLCH color space.
+</p>
+
+<p align="center">
+    <img src="./assets/demo.gif" alt="Demo" width="800">
+</p>
+
+---
+
+## Why This Tool
+
+In CSS, you may want to declare and use multiple brightness steps for a given color. However, even for the same perceived brightness, text, background, and border colors require different brightness levels. You also need to match combinations of text, background, and border colors, and account for dark mode. This tool simplifies these processes.
+
+## Features
+
+- Configuration based on the OKLCH color space
+- Export in OKLCH, RGB, and HEX color formats
+- Dark mode support
+- Local server preview
+  - Text × Background × Border color combination preview
+  - Side-by-side light and dark theme views
+
+## Installation
+
+```bash
+npm install lightstair-css
+```
+
+## CLI
+
+### Help
+
+```bash
+lightstair-css --help
+```
+
+### Generate Configuration File
+
+```bash
+lightstair-css init
+```
+
+Creates a default [lightstair-css.yml](./templates/lightstair-css.yml) configuration file in the current directory. Skips if a configuration file already exists.
+
+### Generate CSS File
+
+```bash
+lightstair-css [options]
+```
+
+Generates a `lightstair-css.css` file in the current directory by default. If no configuration file exists, a default one is automatically created.
+
+The default format is `OKLCH`, and the generated CSS variables use dynamically computed color values. Use the `--bake [format]` option to generate CSS with pre-computed color values.
+
+```css
+/* Default code */
+--tx-1: oklch(clamp(0, var(--tx-init-l) + var(--tx-l-gap) * 0, 1) var(--tx-base-c) var(--tx-base-h));
+
+/* Pre-computed code with `--bake oklch` option */
+--tx-1: oklch(0.31 0.01 250);
+
+/* Pre-computed code with `--bake rgb` option */
+--tx-1: rgb(44.585 48.788 53.291);
+
+/* Pre-computed code with `--bake hex` option */
+--tx-1: #2d3135;
+```
+
+### Run Preview Server
+
+```bash
+lightstair-css preview [options]
+```
+
+Open `http://localhost:[port]` in your browser to view the preview. If no port is specified, a random port is used.
+
+### Command Examples
+
+```bash
+# Show help
+lightstair-css --help
+
+# Create default configuration file
+lightstair-css init
+
+# Generate CSS with default settings
+lightstair-css
+
+# Specify configuration and output files
+lightstair-css -c my-config.yml -o dist/my-colors.css
+
+# Generate CSS with pre-computed RGB format
+lightstair-css --bake rgb
+
+# Generate CSS with pre-computed HEX format and specify output file
+lightstair-css --bake hex -o dist/my-colors.css
+
+# Start preview server
+lightstair-css preview
+
+# Start preview server with port and configuration file
+lightstair-css preview -p 3000 -c my-config.yml
+```

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "lightstair-css",
+  "version": "0.2.0",
+  "description": "OKLCH 색상 공간을 기반으로 글자·배경·테두리 색의 밝기 단계를 설정하여 CSS 파일을 생성하는 CLI 도구.",
+  "keywords": [
+    "color",
+    "css",
+    "cli",
+    "theming",
+    "dark-mode",
+    "lightstair"
+  ],
+  "author": "박민권 <ani2life@gmail.com> (https://github.com/ani2life)",
+  "license": "MIT",
+  "homepage": "https://github.com/ani2life/lightstair-css",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ani2life/lightstair-css"
+  },
+  "bugs": {
+    "url": "https://github.com/ani2life/lightstair-css/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "lightstair-css": "./bin/cli.js"
+  },
+  "dependencies": {
+    "@toolsnap/css-minifier-tool": "^1.0.0",
+    "colorjs.io": "^0.6.1",
+    "commander": "^15.0.0",
+    "open": "^11.0.0",
+    "yaml": "^2.9.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "preview/"
+  ]
+}

package/preview/icon-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><circle cx="256" cy="256" r="230" fill="#1e1e1e" stroke="#e0e0e0" stroke-width="24"/><rect width="288" height="48" x="112" y="350" fill="#4a4a4a" rx="16"/><rect width="240" height="48" x="160" y="278" fill="#787878" rx="16"/><rect width="192" height="48" x="208" y="206" fill="#b3b3b3" rx="16"/><rect width="144" height="48" x="256" y="134" fill="#fff" rx="16"/></svg>

package/preview/icon-light.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><circle cx="256" cy="256" r="230" fill="#fff" stroke="#4a4a4a" stroke-width="24"/><rect width="288" height="48" x="112" y="350" fill="#212121" rx="16"/><rect width="240" height="48" x="160" y="278" fill="#424242" rx="16"/><rect width="192" height="48" x="208" y="206" fill="#757575" rx="16"/><rect width="144" height="48" x="256" y="134" fill="#bdbdbd" rx="16"/></svg>

package/preview/index.html

@@ -0,0 +1,449 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>LightStair CSS</title>
+<link href="/css" rel="stylesheet">
+<style>
+:root {
+    color-scheme: light dark;
+
+    --main-tx-color: light-dark(var(--preview-tx-color), var(--dark-preview-tx-color));
+    --main-bg-color: light-dark(var(--preview-bg-color), var(--dark-preview-bg-color));
+}
+
+html {
+    font-size: 16px;
+}
+
+body {
+    color: var(--main-tx-color);
+    background-color: var(--main-bg-color);
+    font-family: ui-monospace, SFMono-Regular, SF Mono, Menlo, Monaco, Consolas, "Liberation Mono", "Course New", monospace;
+    margin: 0;
+    padding: 2rem;
+}
+
+h1 {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    margin: 0 0 2rem 0;
+
+    img {
+        display: block;
+        width: 1.2em;
+        height: 1.2em;
+    }
+}
+
+main {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 2rem;
+
+    .theme-column {
+        display: flex;
+        flex-direction: column;
+        gap: 1.5rem;
+        flex: 1;
+        min-width: 300px;
+        padding: 1.5rem;
+        border-radius: 8px;
+        color: var(--main-tx-color);
+        background-color: var(--main-bg-color);
+
+        box-shadow: 0 2px 12px rgba(0, 0, 0, 0.15);
+        @media (prefers-color-scheme: dark) {
+            box-shadow: 0 2px 12px rgba(255, 255, 255, 0.15);
+        }
+
+        h3 {
+            font-size: 1.5rem;
+            margin: 0;
+        }
+
+        section {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 1rem;
+        }
+
+        hr {
+            border: none;
+            height: 1px;
+            margin: 0 -1.5em;
+            background-color: currentColor;
+            opacity: 0.2;
+        }
+    }
+}
+
+.overview-card {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    width: 100%;
+    border-radius: 8px;
+
+    .overview-card__stairs {
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        gap: 0.5rem;
+
+        /* horizontal dots */
+        &:not(:last-child)::after {
+            content: '';
+            position: absolute;
+            left: 50%;
+            top: 100%;
+            transform: translate(-50%, calc(1rem - 1.5px));
+            width: 3px;
+            height: 3px;
+            background: currentColor;
+            border-radius: 50%;
+            box-shadow:
+                -10px 0 0 0 currentColor,
+                10px 0 0 0 currentColor;
+        }
+
+        .stair {
+            --checkbox-opacity: 0.3;
+
+            display: flex;
+            flex-wrap: wrap;
+            gap: 1em;
+            box-sizing: border-box;
+            font-size: 0.8rem;
+            padding: 0.5rem 1.5rem 0.5rem 2rem;
+            border-radius: 4px;
+            border: 1px solid transparent;
+            position: relative;
+            cursor: pointer;
+
+            /* checkbox background */
+            &::before {
+                opacity: var(--checkbox-opacity);
+
+                content: '';
+                position: absolute;
+                top: 50%;
+                left: 0.5rem;
+                transform: translateY(-50%);
+
+                width: 1rem;
+                height: 1rem;
+
+                background-color: var(--main-tx-color);
+                border-radius: 50%;
+            }
+            /* checkbox mark */
+            &::after {
+                opacity: var(--checkbox-opacity);
+
+                content: '';
+                position: absolute;
+                top: 50%;
+                left: 0.85rem;
+                transform: translateY(-60%) rotate(45deg);
+
+                width: 0.24rem;
+                height: 0.4rem;
+
+                border: solid var(--main-bg-color);
+                border-width: 0 0.1rem 0.1rem 0;
+            }
+
+            &:hover {
+                outline: 1px solid var(--main-tx-color);
+            }
+
+            &:has(> input[type="radio"]:checked) {
+                --checkbox-opacity: 1;
+            }
+
+            input[type="radio"] {
+                position: absolute;
+                width: 0;
+                height: 0;
+                opacity: 0;
+                pointer-events: none;
+            }
+
+            > span {
+                white-space: nowrap;
+
+                &:nth-of-type(2) {
+                    width: 20ch;
+                }
+                &:nth-of-type(3) {
+                    width: 25ch;
+                }
+                &:nth-of-type(4) {
+                    width: 7ch;
+                }
+            }
+        }
+    }
+}
+
+.combo-card {
+    padding: 1rem;
+    border-radius: 8px;
+    font-size: 0.85rem;
+    border-width: 1px;
+    border-style: solid;
+}
+</style>
+</head>
+<body>
+
+<header>
+    <h1>
+        <picture>
+            <source media="(prefers-color-scheme: dark)" srcset="/icon-dark.svg">
+            <img src="/icon-light.svg" alt="">
+        </picture>
+        LightStair CSS
+    </h1>
+</header>
+
+<main>
+    <div class="theme-column light-theme">
+        <h3>☀️ Light Theme</h3>
+        <section id="overview-light"></section>
+        <hr>
+        <section id="combo-light"></section>
+    </div>
+    <div class="theme-column dark-theme">
+        <h3>🌙 Dark Theme</h3>
+        <section id="overview-dark"></section>
+        <hr>
+        <section id="combo-dark"></section>
+    </div>
+</main>
+
+<template id="overview-card">
+    <div class="overview-card">
+        <div class="overview-card__stairs" data-color-type="tx"></div>
+        <div class="overview-card__stairs" data-color-type="bg"></div>
+        <div class="overview-card__stairs" data-color-type="bd"></div>
+    </div>
+</template>
+
+<template id="overview-card-stair">
+    <label class="stair">
+        <input type="radio">
+        <span>color-var</span>
+        <span>oklch(0 0 0)</span>
+        <span>rgb(0 0 0)</span>
+        <span>#000000</span>
+    </label>
+</template>
+
+<template id="combo-card">
+    <div class="combo-card"></div>
+</template>
+
+<script>
+(async function () {
+    try {
+        const [configRes, colorVarsRes] = await Promise.all([
+            fetch('/config'),
+            fetch('/color-vars'),
+        ]);
+
+        if (!configRes.ok) {
+            throw new Error(`Config fetch failed: ${configRes.status}`);
+        }
+        if (!colorVarsRes.ok) {
+            throw new Error(`Color vars fetch failed: ${colorVarsRes.status}`);
+        }
+
+        const config = await configRes.json();
+        const colorVars = await colorVarsRes.json();
+
+        renderOverviewCards(config, colorVars, 'overview-light', false);
+        renderOverviewCards(config, colorVars, 'overview-dark', true);
+        renderComboCards(config, 'combo-light', false);
+        renderComboCards(config, 'combo-dark', true);
+    } catch (err) {
+        console.error('[Preview] Failed to load data:', err.message);
+    }
+
+    function colorVarName(prefix, num) {
+        return `--${prefix}-${num}`;
+    }
+
+    const lastCheckedRadio = new Map();
+
+    function createStairElement(colorType, theme, colorData, styleProp, colorVar) {
+        const radioName = `${colorType}-stair-${theme}`;
+
+        const template = document.getElementById('overview-card-stair');
+        const clone = document.importNode(template.content, true);
+        const label = clone.querySelector('.stair');
+        const radio = clone.querySelector('input[type="radio"]');
+
+        label.dataset.theme = theme;
+        label.dataset.colorType = colorType;
+
+        radio.name = radioName;
+        radio.dataset.theme = theme;
+        radio.dataset.colorType = colorType;
+        radio.dataset.colorVar = colorVar;
+
+        label.style[styleProp] = `var(${colorVar})`;
+        const spans = label.querySelectorAll(':scope > span');
+        spans[0].textContent = colorVar;
+        spans[1].textContent = colorData.oklch;
+        spans[2].textContent = colorData.rgb;
+        spans[3].textContent = colorData.hex;
+
+        radio.addEventListener('click', () => {
+            const groupName = radio.name;
+            const lastRadio = lastCheckedRadio.get(groupName);
+
+            if (lastRadio === radio) {
+                // 마지막 체크 요소가 동일하면 체크 해제
+                radio.checked = false;
+                lastCheckedRadio.delete(groupName);
+            } else {
+                lastCheckedRadio.set(groupName, radio);
+            }
+
+            document.querySelectorAll(`.stair[data-theme="${theme}"]:not([data-color-type="${colorType}"])`).forEach(stair => {
+                stair.style[styleProp] = radio.checked ? label.style[styleProp] : '';
+            });
+
+            filterComboCards();
+        });
+
+        return clone;
+    }
+
+    function filterComboCards() {
+        const filterData = {};
+
+        for (const [groupName, radio] of lastCheckedRadio) {
+            const theme = radio.dataset.theme;
+            const colorType = radio.dataset.colorType;
+            const colorVar = radio.dataset.colorVar;
+
+            if (!filterData[theme]) {
+                filterData[theme] = {};
+            }
+            filterData[theme][colorType] = colorVar;
+        }
+
+        document.querySelectorAll('.combo-card').forEach(card => {
+            let isVisible = true;
+            const cardTheme = card.dataset.theme;
+            const filter = filterData[cardTheme];
+
+            if (filter) {
+                if ('tx' in filter && card.dataset.txColorVar !== filter.tx) {
+                    isVisible = false;
+                }
+                if ('bg' in filter && card.dataset.bgColorVar !== filter.bg) {
+                    isVisible = false;
+                }
+                if ('bd' in filter && card.dataset.bdColorVar !== filter.bd) {
+                    isVisible = false;
+                }
+            }
+
+            card.style.display = isVisible ? '' : 'none';
+        });
+    }
+
+    async function renderOverviewCards(config, colorVars, containerId, isDark = false) {
+        const {
+            tx_l_steps, bg_l_steps, bd_l_steps,
+            tx_prefix, bg_prefix, bd_prefix,
+        } = config;
+
+        const theme = isDark ? 'dark' : 'light';
+
+        const template = document.getElementById('overview-card');
+        const clone = document.importNode(template.content, true);
+        const card = clone.querySelector('.overview-card');
+
+        const configs = [
+            {
+                colorType: 'tx',
+                prefix: tx_prefix,
+                steps: tx_l_steps,
+                styleProp: 'color',
+            },
+            {
+                colorType: 'bg',
+                prefix: bg_prefix,
+                steps: bg_l_steps,
+                styleProp: 'backgroundColor',
+            },
+            {
+                colorType: 'bd',
+                prefix: bd_prefix,
+                steps: bd_l_steps,
+                styleProp: 'borderColor',
+            },
+        ];
+
+        for (const { colorType, prefix, steps, styleProp, container } of configs) {
+            for (let i = 1; i <= steps; i++) {
+                const colorVar = colorVarName(prefix, i);
+                const colorData = colorVars[colorVar][theme];
+                const container = clone.querySelector(`.overview-card__stairs[data-color-type="${colorType}"]`);
+                container.appendChild(
+                    createStairElement(colorType, theme, colorData, styleProp, colorVar)
+                );
+            }
+        }
+
+        document.getElementById(containerId).appendChild(clone);
+    }
+
+    function renderComboCards(config, containerId, isDark = false) {
+        const {
+            tx_l_steps, bg_l_steps, bd_l_steps,
+            tx_prefix, bg_prefix, bd_prefix,
+        } = config;
+
+        const theme = isDark ? 'dark' : 'light';
+
+        const template = document.getElementById('combo-card');
+
+        for (let bg = 1; bg <= bg_l_steps; bg++) {
+            for (let tx = 1; tx <= tx_l_steps; tx++) {
+                for (let bd = 1; bd <= bd_l_steps; bd++) {
+                    const clone = document.importNode(template.content, true);
+                    const card = clone.querySelector('.combo-card');
+
+                    const txVar = colorVarName(tx_prefix, tx);
+                    const bgVar = colorVarName(bg_prefix, bg);
+                    const bdVar = colorVarName(bd_prefix, bd);
+                    card.style.color = `var(${txVar})`;
+                    card.style.backgroundColor = `var(${bgVar})`;
+                    card.style.borderColor = `var(${bdVar})`;
+                    card.innerHTML = `${txVar}<br>${bgVar}<br>${bdVar}<br>`;
+
+                    card.dataset.theme = theme;
+                    card.dataset.txColorVar = txVar;
+                    card.dataset.bgColorVar = bgVar;
+                    card.dataset.bdColorVar = bdVar;
+
+                    document.getElementById(containerId).appendChild(clone);
+                }
+            }
+        }
+    }
+})();
+</script>
+
+</body>
+</html>

package/src/cli.js

@@ -0,0 +1,203 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import http from 'node:http';
+import { Command, Option } from 'commander';
+import { parse } from 'yaml';
+import { beautify } from '@toolsnap/css-minifier-tool';
+import { generateCSS, generateBakedCSS, generateColorVars } from './generator.js';
+
+const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG_FILE = 'lightstair-css.yml';
+const DEFAULT_CONFIG_PATH = resolve(SRC_DIR, '..', 'templates', DEFAULT_CONFIG_FILE);
+
+const program = new Command();
+const configOption = new Option('-c, --config <path>', 'path to configuration file');
+
+function loadConfig(configPath) {
+    const raw = readFileSync(configPath, 'utf-8');
+    const userConfig = parse(raw);
+
+    const defaultRaw = readFileSync(DEFAULT_CONFIG_PATH, 'utf-8');
+    const defaultConfig = parse(defaultRaw);
+
+    const config = Object.assign({}, defaultConfig, userConfig);
+    return config;
+}
+
+function ensureConfigFile(configPath, { suppressIfExists = false } = {}) {
+    const targetPath = resolve(configPath);
+    if (existsSync(targetPath)) {
+        if (!suppressIfExists) console.log(`[OK] Config already exists: ${targetPath}`);
+        return;
+    }
+    copyFileSync(DEFAULT_CONFIG_PATH, targetPath);
+    console.log(`[OK] Created: ${targetPath}`);
+}
+
+function resolveAndEnsureConfigFile(options, { suppressIfExists = true } = {}) {
+    const configPath = options.config === undefined
+        ? resolve(process.cwd(), DEFAULT_CONFIG_FILE)
+        : resolve(options.config);
+
+    if (options.config === undefined) {
+        ensureConfigFile(configPath, { suppressIfExists });
+    }
+
+    return configPath;
+}
+
+function beautifyCss(css) {
+    return beautify(css)
+        // 시작 공백을 제외한 중간 공백을 1개로 치환.
+        .replace(/(?<=\S)[ ]{2,}/g, ' ');
+}
+
+program
+    .name('lightstair-css')
+    .description('LightStair CSS CLI tool for generating color values')
+    .version('0.1.0')
+    .addOption(configOption)
+    .option('-o, --output <path>', 'output CSS file path', 'lightstair-css.css')
+    .option('--bake [format]', 'bake CSS variables into computed values (oklch, rgb, hex)')
+    .action(() => {
+        const options = program.opts();
+        const configPath = resolveAndEnsureConfigFile(options, { suppressIfExists: true });
+
+        const outputPath = resolve(options.output);
+        const bakeFormat = (() => {
+            if (options.bake === undefined) return null;
+            if (options.bake === true) return 'oklch';
+            return options.bake;
+        })();
+
+        try {
+            const config = loadConfig(configPath);
+
+            const rawCss = bakeFormat
+                ? generateBakedCSS(config, bakeFormat)
+                : generateCSS(config);
+
+            const css = beautifyCss(rawCss);
+
+            const outputDir = dirname(outputPath);
+            mkdirSync(outputDir, { recursive: true });
+            writeFileSync(outputPath, css, 'utf-8');
+            console.log(`[OK] Output written to: ${outputPath}`);
+        } catch (err) {
+            console.error(`[Error] Failed to process config: ${configPath}`);
+            console.error(err.message);
+            process.exit(1);
+        }
+    });
+
+program.command('init').description('create a default lightstair-css.yml config file').action(() => {
+    const targetPath = resolve(process.cwd(), DEFAULT_CONFIG_FILE);
+    ensureConfigFile(targetPath, { suppressIfExists: false });
+    process.exit(0);
+});
+
+program
+    .command('preview')
+    .description('run the preview server')
+    .addOption(configOption)
+    .option('-p, --port <number>', 'port number to use (default: random)')
+    .action((options) => {
+        const configPath = resolveAndEnsureConfigFile(options, { suppressIfExists: true });
+
+        const port = options.port !== undefined
+            ? parseInt(options.port, 10)
+            : 0;
+
+        if (port !== 0 && (isNaN(port) || port < 1 || port > 65535)) {
+            console.error('[Error] Invalid port number. Must be 1-65535.');
+            process.exit(1);
+        }
+
+        const server = http.createServer((req, res) => {
+            if (req.url === '/') {
+                const htmlPath = resolve(SRC_DIR, '..', 'preview', 'index.html');
+                const htmlContent = readFileSync(htmlPath, 'utf-8');
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(htmlContent);
+                return;
+            }
+
+            if (req.url === '/css') {
+                try {
+                    const config = loadConfig(configPath);
+                    const css = generateCSS(config, { isPreview: true });
+                    res.writeHead(200, { 'Content-Type': 'text/css; charset=utf-8' });
+                    res.end(css, 'utf-8');
+                } catch (err) {
+                    console.error(`[Error] CSS generation failed: ${configPath}`);
+                    console.error(err.message);
+                    res.writeHead(500);
+                    res.end(`Error: ${err.message}`, 'utf-8');
+                }
+                return;
+            }
+
+            if (req.url === '/config') {
+                try {
+                    const config = loadConfig(configPath);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(JSON.stringify(config), 'utf-8');
+                } catch (err) {
+                    console.error(`[Error] Config load failed: ${configPath}`);
+                    console.error(err.message);
+                    res.writeHead(500);
+                    res.end(`Error: ${err.message}`, 'utf-8');
+                }
+                return;
+            }
+
+            if (req.url === '/color-vars') {
+                try {
+                    const config = loadConfig(configPath);
+                    const colorVars = generateColorVars(config);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(JSON.stringify(colorVars), 'utf-8');
+                } catch (err) {
+                    console.error(`[Error] Variables generation failed: ${configPath}`);
+                    console.error(err.message);
+                    res.writeHead(500);
+                    res.end(`Error: ${err.message}`, 'utf-8');
+                }
+                return;
+            }
+
+            if (req.url.endsWith('.svg') || req.url.endsWith('.ico')) {
+                const filePath = join(SRC_DIR, '..', 'preview', req.url.replace(/^\//, ''));
+                const contentType = req.url.endsWith('.svg')
+                    ? 'image/svg+xml'
+                    : 'image/x-icon';
+                try {
+                    const content = readFileSync(filePath);
+                    res.writeHead(200, { 'Content-Type': contentType });
+                    res.end(content);
+                } catch {
+                    res.writeHead(404);
+                    res.end('Not Found');
+                }
+                return;
+            }
+
+            res.writeHead(404);
+            res.end('Not Found');
+        });
+
+        server.listen(port, () => {
+            const actualPort = server.address().port;
+            console.log(`[OK] Preview server running at http://localhost:${actualPort}`);
+            console.log('Press Ctrl+C to stop the server.');
+        });
+
+        process.on('SIGINT', () => {
+            console.log('\nShutting down preview server...');
+            server.close();
+            process.exit(0);
+        });
+    });
+
+program.parse(process.argv);

package/src/generator.js

@@ -0,0 +1,214 @@
+import Color from 'colorjs.io';
+
+export function generateCSS(config, { isPreview = false } = {}) {
+    const {
+        tx_base_c, tx_base_h,
+        bg_base_c, bg_base_h,
+        bd_base_c, bd_base_h,
+        tx_init_l, bg_init_l, bd_init_l,
+        dark_tx_init_l, dark_bg_init_l, dark_bd_init_l,
+        tx_l_gap, bg_l_gap, bd_l_gap,
+        dark_tx_l_gap, dark_bg_l_gap, dark_bd_l_gap,
+        tx_l_steps, bg_l_steps, bd_l_steps,
+        tx_prefix, bg_prefix, bd_prefix,
+    } = config;
+
+    function generateSteps(prefix, steps) {
+        const initL = `var(--${prefix}-init-l)`;
+        const lGap = `var(--${prefix}-l-gap)`;
+        const baseC = `var(--${prefix}-base-c)`;
+        const baseH = `var(--${prefix}-base-h)`;
+
+        return Array.from({ length: steps }, (_, i) => {
+            const calcL = `clamp(0, ${initL} + ${lGap} * ${i}, 1)`;
+            return `--${prefix}-${i + 1}: oklch(${calcL} ${baseC} ${baseH});`
+        }).join('\n');
+    }
+
+    const txStepsCss = generateSteps(tx_prefix, tx_l_steps);
+    const bgStepsCss = generateSteps(bg_prefix, bg_l_steps);
+    const bdStepsCss = generateSteps(bd_prefix, bd_l_steps);
+
+    const baseCss = `
+        --${tx_prefix}-base-c: ${tx_base_c};
+        --${tx_prefix}-base-h: ${tx_base_h};
+        --${bg_prefix}-base-c: ${bg_base_c};
+        --${bg_prefix}-base-h: ${bg_base_h};
+        --${bd_prefix}-base-c: ${bd_base_c};
+        --${bd_prefix}-base-h: ${bd_base_h};
+    `;
+
+    const lightThemeCss = `
+        --${tx_prefix}-init-l: ${tx_init_l};
+        --${bg_prefix}-init-l: ${bg_init_l};
+        --${bd_prefix}-init-l: ${bd_init_l};
+
+        --${tx_prefix}-l-gap: ${tx_l_gap};
+        --${bg_prefix}-l-gap: ${bg_l_gap};
+        --${bd_prefix}-l-gap: ${bd_l_gap};
+    `;
+
+    const darkThemeCss = `
+        --${tx_prefix}-init-l: ${dark_tx_init_l};
+        --${bg_prefix}-init-l: ${dark_bg_init_l};
+        --${bd_prefix}-init-l: ${dark_bd_init_l};
+
+        --${tx_prefix}-l-gap: ${dark_tx_l_gap};
+        --${bg_prefix}-l-gap: ${dark_bg_l_gap};
+        --${bd_prefix}-l-gap: ${dark_bd_l_gap};
+    `;
+
+    if (isPreview) {
+        const {
+            preview_tx_l, preview_tx_c, preview_tx_h,
+            preview_bg_l, preview_bg_c, preview_bg_h,
+            dark_preview_tx_l, dark_preview_tx_c, dark_preview_tx_h,
+            dark_preview_bg_l, dark_preview_bg_c, dark_preview_bg_h,
+        } = config;
+
+        const previewColorVars = `
+            --preview-tx-color: oklch(${preview_tx_l} ${preview_tx_c} ${preview_tx_h});
+            --preview-bg-color: oklch(${preview_bg_l} ${preview_bg_c} ${preview_bg_h});
+            --dark-preview-tx-color: oklch(${dark_preview_tx_l} ${dark_preview_tx_c} ${dark_preview_tx_h});
+            --dark-preview-bg-color: oklch(${dark_preview_bg_l} ${dark_preview_bg_c} ${dark_preview_bg_h});
+        `;
+
+        return /* css */`
+            :root {
+                ${previewColorVars}
+
+                ${baseCss}
+            }
+
+            .light-theme,
+            .dark-theme {
+                ${txStepsCss}
+                ${bgStepsCss}
+                ${bdStepsCss}
+            }
+
+            .light-theme {
+                color-scheme: light;
+                ${lightThemeCss}
+            }
+
+            .dark-theme {
+                color-scheme: dark;
+                ${darkThemeCss}
+            }
+        `;
+    } else {
+        return /* css */`
+            :root {
+                ${baseCss}
+
+                ${lightThemeCss}
+
+                @media (prefers-color-scheme: dark) {
+                    ${darkThemeCss}
+                }
+
+                ${txStepsCss}
+                ${bgStepsCss}
+                ${bdStepsCss}
+            }
+        `;
+    }
+}
+
+function clamp(min, val, max) {
+    return Math.max(min, Math.min(val, max));
+}
+
+function formatColor(l, c, h) {
+    const color = new Color({ spaceId: 'oklch', coords: [l, c, h] });
+    return {
+        oklch: color.toString({
+            format: 'oklch',
+            coords: ['<number>', '<number>', '<number>']
+        }),
+        rgb: color.toString({
+            format: 'rgb',
+            coords: ['<number>[0, 255]', '<number>[0, 255]', '<number>[0, 255]']
+        }),
+        hex: color.toString({ format: 'hex' }),
+    };
+}
+
+export function generateBakedCSS(config, format) {
+    const {
+        tx_base_c, tx_base_h,
+        bg_base_c, bg_base_h,
+        bd_base_c, bd_base_h,
+        tx_init_l, bg_init_l, bd_init_l,
+        dark_tx_init_l, dark_bg_init_l, dark_bd_init_l,
+        tx_l_gap, bg_l_gap, bd_l_gap,
+        dark_tx_l_gap, dark_bg_l_gap, dark_bd_l_gap,
+        tx_l_steps, bg_l_steps, bd_l_steps,
+        tx_prefix, bg_prefix, bd_prefix,
+    } = config;
+
+    function generateSteps(prefix, initL, gap, steps, c, h, format) {
+        return Array.from({ length: steps }, (_, i) => {
+            const l = clamp(0, initL + gap * i, 1);
+            return `--${prefix}-${i + 1}: ${formatColor(l, c, h)[format]};`;
+        }).join('\n');
+    }
+
+    const txSteps = generateSteps(tx_prefix, tx_init_l, tx_l_gap, tx_l_steps, tx_base_c, tx_base_h, format);
+    const bgSteps = generateSteps(bg_prefix, bg_init_l, bg_l_gap, bg_l_steps, bg_base_c, bg_base_h, format);
+    const bdSteps = generateSteps(bd_prefix, bd_init_l, bd_l_gap, bd_l_steps, bd_base_c, bd_base_h, format);
+
+    const txStepsDark = generateSteps(tx_prefix, dark_tx_init_l, dark_tx_l_gap, tx_l_steps, tx_base_c, tx_base_h, format);
+    const bgStepsDark = generateSteps(bg_prefix, dark_bg_init_l, dark_bg_l_gap, bg_l_steps, bg_base_c, bg_base_h, format);
+    const bdStepsDark = generateSteps(bd_prefix, dark_bd_init_l, dark_bd_l_gap, bd_l_steps, bd_base_c, bd_base_h, format);
+
+    return /* css */`
+        :root {
+            ${txSteps}
+            ${bgSteps}
+            ${bdSteps}
+
+            @media (prefers-color-scheme: dark) {
+                ${txStepsDark}
+                ${bgStepsDark}
+                ${bdStepsDark}
+            }
+        }
+    `;
+}
+
+export function generateColorVars(config) {
+    const {
+        tx_base_c, tx_base_h,
+        bg_base_c, bg_base_h,
+        bd_base_c, bd_base_h,
+        tx_init_l, bg_init_l, bd_init_l,
+        dark_tx_init_l, dark_bg_init_l, dark_bd_init_l,
+        tx_l_gap, bg_l_gap, bd_l_gap,
+        dark_tx_l_gap, dark_bg_l_gap, dark_bd_l_gap,
+        tx_l_steps, bg_l_steps, bd_l_steps,
+        tx_prefix, bg_prefix, bd_prefix,
+    } = config;
+
+    const result = {};
+
+    function addSteps(prefix, lightInitL, lightGap, darkInitL, darkGap, steps, c, h) {
+        for (let i = 0; i < steps; i++) {
+            const key = `--${prefix}-${i + 1}`;
+            const lightL = clamp(0, lightInitL + lightGap * i, 1);
+            const darkL = clamp(0, darkInitL + darkGap * i, 1);
+
+            result[key] = {
+                light: formatColor(lightL, c, h),
+                dark: formatColor(darkL, c, h),
+            };
+        }
+    }
+
+    addSteps(tx_prefix, tx_init_l, tx_l_gap, dark_tx_init_l, dark_tx_l_gap, tx_l_steps, tx_base_c, tx_base_h);
+    addSteps(bg_prefix, bg_init_l, bg_l_gap, dark_bg_init_l, dark_bg_l_gap, bg_l_steps, bg_base_c, bg_base_h);
+    addSteps(bd_prefix, bd_init_l, bd_l_gap, dark_bd_init_l, dark_bd_l_gap, bd_l_steps, bd_base_c, bd_base_h);
+
+    return result;
+}

package/templates/lightstair-css.yml

@@ -0,0 +1,57 @@
+# ================================================
+# L, C, H 값은 OKLCH 색상 공간을 기준으로 합니다.
+# - L (Lightness, 명도): 0 ~ 1
+# - C (Chroma, 채도): 0 ~ 약 0.4
+# - H (Hue, 색상): 0 ~ 360 (각도, deg 단위)
+# ================================================
+
+tx_base_c: 0.01 # 기본 글자 채도
+tx_base_h: 250 # 기본 글자 색상
+
+bg_base_c: 0.01 # 기본 배경 채도
+bg_base_h: 250 # 기본 배경 색상
+
+bd_base_c: 0.01 # 기본 테두리 채도
+bd_base_h: 250 # 기본 테두리 색상
+
+tx_init_l: 0.31 # 초기 글자 밝기
+bg_init_l: 0.96 # 초기 배경 밝기
+bd_init_l: 0.88 # 초기 테두리 밝기
+
+dark_tx_init_l: 0.85 # 다크모드 초기 글자 밝기
+dark_bg_init_l: 0.22 # 다크모드 초기 배경 밝기
+dark_bd_init_l: 0.38 # 다크모드 초기 테두리 밝기
+
+tx_l_gap: 0.09 # 글자 밝기 간격
+bg_l_gap: -0.04 # 배경 밝기 간격
+bd_l_gap: -0.08 # 테두리 밝기 간격
+
+dark_tx_l_gap: -0.09 # 다크모드 글자 밝기 간격
+dark_bg_l_gap: 0.04 # 다크모드 배경 밝기 간격
+dark_bd_l_gap: 0.10 # 다크모드 테두리 밝기 간격
+
+tx_l_steps: 4 # 글자 밝기 단계
+bg_l_steps: 4 # 배경 밝기 단계
+bd_l_steps: 4 # 테두리 밝기 단계
+
+tx_prefix: tx # 글자색 CSS 변수 접두어
+bg_prefix: bg # 배경색 CSS 변수 접두어
+bd_prefix: bd # 테두리색 CSS 변수 접두어
+
+# ================================================
+# 미리보기 페이지의 글자색과 배경색
+# ================================================
+
+preview_tx_l: 0.22 # 미리보기 글자 밝기
+preview_tx_c: 0 # 미리보기 글자 채도
+preview_tx_h: 0 # 미리보기 글자 색상
+preview_bg_l: 1 # 미리보기 배경 밝기
+preview_bg_c: 0 # 미리보기 배경 채도
+preview_bg_h: 0 # 미리보기 배경 색상
+
+dark_preview_tx_l: 0.94 # 다크모드 미리보기 글자 밝기
+dark_preview_tx_c: 0 # 다크모드 미리보기 글자 채도
+dark_preview_tx_h: 0 # 다크모드 미리보기 글자 색상
+dark_preview_bg_l: 0.18 # 다크모드 미리보기 배경 밝기
+dark_preview_bg_c: 0 # 다크모드 미리보기 배경 채도
+dark_preview_bg_h: 0 # 다크모드 미리보기 배경 색상