atomsystem 0.1.26 → 0.1.28

package/README.md

@@ -1,7 +1,55 @@
-This is Atom Design System
+# AtomSystem Design Token
 
-with tokenStudio,
-with Figma,
-with Storybook,
+AtomSystem은 **디자인 토큰(Design Tokens)**을 중심으로 UI 컴포넌트와 문서를 관리하는 현대적인 디자인 시스템 프레임워크입니다. `tokens.json`을 단일 진실 공급원(Single Source of Truth)으로 하여 CSS 변수와 TypeScript 타입을 자동으로 생성하고, 이를 기반으로 React 컴포넌트와 MDX 가이드를 구축합니다.
 
-https://system.atomground.com
+## ✨ 핵심 가치
+
+- **Token-Driven Design**: 모든 스타일 값(색상, 간격, 타이포그래피 등)은 토큰으로 관리되어 디자인과 코드 간의 일관성을 유지합니다.
+- **Automated Workflow**: Style Dictionary를 통해 토큰 변경 시 즉시 CSS 및 TS 파일이 업데이트됩니다.
+- **Component-First Documentation**: 컴포넌트 생성과 동시에 MDX 문서가 연동되어 실시간 라이브러리 가이드를 제공합니다.
+- **Multi-Theme Support**: 테마별 토큰 분리 관리를 통해 화이트/다크 모드 및 커스텀 테마를 손쉽게 지원합니다.
+
+## 🛠 기술 스택
+
+- **Core**: Next.js 15, React 18, TypeScript
+- **Styling**: Tailwind CSS 4, CSS Modules
+- **Design Token**: Style Dictionary 4, Tokens Studio
+- **Animation**: GSAP, @gsap/react
+- **Documentation**: MDX
+
+## 📂 프로젝트 구조
+
+- `/tokens`: 디자인 토큰의 원천 데이터 (`tokens.json`)
+- `/build`: 빌드된 토큰 결과물 (CSS Variables, TS Objects)
+- `/app/templates`: 디자인 시스템의 핵심 React 컴포넌트
+- `/css`: 각 컴포넌트의 스타일 시트
+- `/markdown`: 컴포넌트 가이드 및 예시를 담은 MDX 파일
+- `/cli`: 디자인 시스템 관리를 위한 CLI 도구
+
+## 🚀 시작하기
+
+### 1. 의존성 설치
+```bash
+npm install
+```
+
+### 2. 토큰 빌드 및 개발 서버 실행
+`npm run dev`는 토큰을 먼저 빌드한 후 Next.js 개발 서버를 실행합니다.
+```bash
+npm run dev
+```
+
+### 3. 토큰만 빌드하기
+```bash
+npm run token-build
+```
+
+## 🔄 워크플로우
+
+1.  **토큰 정의**: `tokens/tokens.json`에서 새로운 스타일 값이나 컴포넌트 토큰을 정의합니다.
+2.  **토큰 빌드**: `npm run token-build`를 통해 `build/` 경로의 자산들을 업데이트합니다.
+3.  **컴포넌트 구현**: `app/templates/`에서 빌드된 TS 타입을 참조하여 컴포넌트를 작성합니다.
+4.  **문서화**: `markdown/`에서 MDX를 작성하여 컴포넌트 사용법을 기록합니다.
+
+---
+© 2026 [AtomGround](https://system.atomground.com). All rights reserved.

package/app/templates/Badge/Badge.tsx

@@ -2,18 +2,16 @@ export const Badge = ({
   children,
   color,
   type,
-  className,
 }: {
   children: React.ReactNode;
   color: "primary" | "secondary" | "warning" | "danger";
   type?: "default" | "tint";
-  className?: string;
 }) => {
   switch (type) {
     case "tint":
       return (
         <span
-          className={`text-sm px-1.5 rounded ${color === "primary" ? "bg-primary/20 !text-primary" : color === "secondary" ? "bg-secondary/20 !text-secondary" : color === "warning" ? "bg-warning/20 !text-warning" : color === "danger" ? "bg-danger/20 !text-danger" : null} ${className}`}
+          className={`badge-tint ${color}`}
         >
           {children}
         </span>
@@ -21,7 +19,7 @@ export const Badge = ({
     default:
       return (
         <span
-          className={`text-sm px-1.5 rounded ${color === "primary" ? "bg-primary !text-white" : color === "secondary" ? "bg-secondary !text-white" : color === "warning" ? "bg-warning !text-white" : color === "danger" ? "bg-danger !text-white" : null} ${className}`}
+          className={`badge ${color}`}
         >
           {children}
         </span>

package/app/templates/Button/Button.tsx

@@ -9,36 +9,14 @@ export const Button = ({
   onClick,
 }: {
   children: React.ReactNode;
-  type: "primary" | "secondary" | "success" | "danger" | "gray";
+  type: "primary" | "secondary" | "success" | "warning" | "danger" | "gray";
   style?: React.CSSProperties;
   disabled?: boolean;
   onClick?: () => void;
 }) => {
   return (
     <button
-      className={clsx(
-        "px-4 py-2 rounded-common text-white transition-all cursor-pointer rounded-[var(--global-rounded)]",
-        {
-          "bg-[var(--button-main-primary-standard)] hover:bg-[var(--button-main-primary-hover)] active:bg-[var(--button-main-primary-active)] standard:bg-[var(--buttion-main-primary-standard)]/20":
-            type == "primary",
-        },
-        {
-          "bg-[var(--button-main-secondary-standard)] hover:bg-[var(--button-main-secondary-hover)] active:bg-[var(--button-main-secondary-active)] standard:bg-[var(--buttion-main-secondary-standard)]/20 ":
-            type == "secondary",
-        },
-        {
-          "bg-[var(--button-main-success-standard)] hover:bg-[var(--button-main-success-hover)] active:bg-[var(--button-main-success-active)] standard:bg-[var(--buttion-main-success-standard)]/20":
-            type == "success",
-        },
-        {
-          "bg-[var(--button-main-danger-standard)] hover:bg-[var(--button-main-danger-hover)] active:bg-[var(--button-main-danger-active)] standard:bg-[var(--buttion-main-danger-standard)]/20":
-            type == "danger",
-        },
-        {
-          "bg-[var(--button-main-gray-standard)] hover:bg-[var(--button-main-gray-hover)] active:bg-[var(--button-main-gray-active)] standard:bg-[var(--buttion-main-gray-standard)]/20":
-            type == "gray",
-        }
-      )}
+      className={clsx("btn", type)}
       style={style}
       disabled={disabled}
       onClick={onClick}

package/app/templates/Card/Card.tsx

@@ -2,7 +2,6 @@ import React from "react";
 
 export const Card = ({
   children,
-  type = "standard",
   className = "",
   overflow = "overflow-auto",
 }: {
@@ -11,17 +10,9 @@ export const Card = ({
   type?: "standard" | "group";
   overflow?: "overflow-auto" | "overflow-hidden" | "overflow-none";
 }) => {
-  // CardHeader와 CardContent의 존재 여부 확인
-  const hasCardContent = React.Children.toArray(children).some(
-    (child) =>
-      React.isValidElement(child) &&
-      (child.type === CardHeader ||
-        child.type === CardContent ||
-        child.type === CardFooter)
-  );
   return (
     <div
-      className={`${type == "standard" ? "bg-[var(--background-card)] border-[var(--color-border)]" : type == "group" ? "bg-[var(--background-wrapper)] border-none" : ""} ${!hasCardContent ? "p-4" : ""} rounded  border ${className} ${overflow === "overflow-auto" ? `overflow-auto` : overflow === "overflow-hidden" ? "overflow-hidden" : overflow === "overflow-none" ? "" : ""}`}
+      className={`card ${className} ${overflow}`}
     >
       {children}
     </div>
@@ -35,7 +26,7 @@ export const CardHeader = ({
   children: React.ReactNode;
   noMargin?: boolean;
 }) => {
-  return <div className={`${noMargin ? "p-0" : "p-4"}`}>{children}</div>;
+  return <div className={`card-header ${noMargin ? "no-margin" : ""}`}>{children}</div>;
 };
 
 export const CardContent = ({
@@ -45,7 +36,7 @@ export const CardContent = ({
   children: React.ReactNode;
   noMargin?: boolean;
 }) => {
-  return <div className={`${noMargin ? "p-0" : "p-4"}`}>{children}</div>;
+  return <div className={`card-content ${noMargin ? "no-margin" : ""}`}>{children}</div>;
 };
 
 export const CardFooter = ({
@@ -55,5 +46,5 @@ export const CardFooter = ({
   children: React.ReactNode;
   noMargin?: boolean;
 }) => {
-  return <div className={`${noMargin ? "p-0" : "p-4"}`}>{children}</div>;
+  return <div className={`card-footer ${noMargin ? "no-margin" : ""}`}>{children}</div>;
 };

package/app/templates/CodeBlock/CodeBlock.tsx

@@ -12,10 +12,16 @@ const CodeBlock = ({
 }) => {
   const codeRef = useRef<HTMLElement | null>(null);
   const [copied, setCopied] = useState(false);
+  const [isHeightCheck, setHeightCheck] = useState(false);
+  const [isOpen, setIsOpen] = useState(false);
 
   useEffect(() => {
     if (codeRef.current) {
       hljs.highlightElement(codeRef.current); // 코드 블록 하이라이트
+
+      if (codeRef.current.offsetHeight >= 300) {
+        setHeightCheck(true);
+      }
     }
   }, [children]);
 
@@ -33,7 +39,7 @@ const CodeBlock = ({
 
   return (
     <div className="relative">
-      <pre>
+      <pre className={`${isOpen ? "max-h-fit" : "max-h-60"}  overflow-hidden`}>
         <code ref={codeRef} className={language}>
           {children}
         </code>
@@ -41,10 +47,20 @@ const CodeBlock = ({
 
       <button
         onClick={handleCopy}
-        className="absolute top-2 right-2 bg-white text-black text-xs px-2 py-1 rounded hover:bg-gray-200"
+        className="absolute top-2 right-2 bg-[var(--color-bg-card)] hover:bg-[var(--color-bg-wrapper)] text-[var(--text-standard)] text-xs px-2 py-1 rounded cursor-pointer "
       >
         {copied ? "Copied!" : "Copy"}
       </button>
+
+      {isHeightCheck ? (
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          className="
+         w-full cursor-pointer hover:bg-[var(--color-bg-wrapper)] text-center py-2 px-8"
+        >
+          {isOpen ? "Close" : "Open"}
+        </button>
+      ) : null}
     </div>
   );
 };

package/app/templates/Collapse/Collapse.tsx

@@ -35,20 +35,20 @@ export const Collapse = ({
   return (
     <>
       {collapses.map((collapse, idx) => (
-        <div key={idx}>
-          <label className="flex justify-between cursor-pointer p-4 border-t border-[var(--color-border)]">
+        <div key={idx} className="collapse-item">
+          <label className="collapse-header">
             {collapse.title}
             <button
               onClick={() => toggleContent(idx)}
-              className={`material-symbols-outlined cursor-pointer transition-all duration-300 ${
-                isActive(idx) ? "rotate-90" : "rotate-0"
+              className={`material-symbols-outlined collapse-icon ${
+                isActive(idx) ? "open" : "closed"
               }`}
             >
               keyboard_arrow_right
             </button>
           </label>
           {isActive(idx) && (
-            <div className="p-4 bg-[var(--background-wrapper)] border-rounded">
+            <div className="collapse-content">
               {collapse.content}
             </div>
           )}
@@ -91,20 +91,20 @@ export const NodeCollapse = ({
   return (
     <>
       {collapses.map((collapse, idx) => (
-        <div key={idx}>
-          <label className="flex justify-between cursor-pointer p-4 border-t border-[var(--color-border)]">
+        <div key={idx} className="collapse-item">
+          <label className="collapse-header">
             {collapse.title}
             <button
               onClick={() => toggleContent(idx)}
-              className={`material-symbols-outlined cursor-pointer transition-all duration-300 ${
-                isActive(idx) ? "rotate-90" : "rotate-0"
+              className={`material-symbols-outlined collapse-icon ${
+                isActive(idx) ? "open" : "closed"
               }`}
             >
               keyboard_arrow_right
             </button>
           </label>
           {isActive(idx) && (
-            <div className="p-4 bg-[var(--background-wrapper)] border-rounded">
+            <div className="collapse-content">
               {collapse.content}
             </div>
           )}

package/app/templates/{Input/Input.tsx → Form/Form.tsx}

@@ -1,12 +1,31 @@
 "use client";
 import clsx from "clsx";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 
+export const Label = ({
+    label,
+    required,
+}: {
+    label: string;
+    required?: boolean;
+}) => {
+    return (
+        <p className={"mb-1 text-text-standard"}>  
+            <span
+                className={clsx("", {
+                    "after:content-['*'] after:ml-1 after:text-danger": required,
+                })}
+            >
+                {label}
+            </span>
+        </p>
+    );
+};
+
 export const Input = ({
   type = "text",
   placeholder = "값을 입력해주세요",
-  label,
   readOnly,
   disabled,
   required,
@@ -14,53 +33,27 @@ export const Input = ({
   type?: string;
   className?: string;
   placeholder?: string;
-  label?: string;
   readOnly?: boolean;
   disabled?: boolean;
   required?: boolean;
 }) => {
   return (
-    <>
-      {label ? (
-        <p className={clsx("mb-1 text-text-standard", {})}>
-          <span
-            className={clsx("", {
-              "after:content-['*'] after:ml-1 after:text-danger": required,
-            })}
-          >
-            {label}
-          </span>
-        </p>
-      ) : null}
       <input
+        className="input"
         type={type}
-        className="border rounded focus:outline-none focus:ring-0 bg-[var(--input-background-standard)] disabled:bg-[var(--input-background-disabled)] disabled:cursor-not-allowed border-[var(--input-border-standard)] focus:border-[var(--input-border-focus)] w-full"
-        style={{
-          color: "var(--input-text-standard)",
-          paddingLeft: "var(--spacing-global-x)",
-          paddingRight: "var(--spacing-global-x)",
-          paddingTop: "var(--spacing-global-y)",
-          paddingBottom: "var(--spacing-global-y)",
-          borderRadius: "var(--input-rounded)",
-        }}
         placeholder={placeholder}
         readOnly={readOnly}
         disabled={disabled}
         required={required}
       />
-    </>
   );
 };
 
 export const Select = ({
   options,
-  label,
-  required,
   disabled,
 }: {
   options: string[];
-  label?: string;
-  required?: boolean;
   disabled?: boolean;
 }) => {
   const [filterValue, setFilterValue] = useState("");
@@ -76,16 +69,41 @@ export const Select = ({
     option.toLowerCase().includes(filterValue.toLowerCase())
   );
 
-  useEffect(() => {
-    if (isOpen && inputRef.current) {
+  useLayoutEffect(() => {
+    if (isOpen && inputRef.current && dropdownRef.current) {
       const rect = inputRef.current.getBoundingClientRect();
-      setMenuPosition({
-        top: rect.bottom + window.scrollY,
-        left: rect.left,
-        width: rect.width,
+      const dropdownRect = dropdownRef.current.getBoundingClientRect();
+
+      if (Math.abs(menuPosition.width - rect.width) > 0.5) {
+        setMenuPosition({
+          top: rect.bottom + window.scrollY,
+          left: rect.left,
+          width: rect.width,
+        });
+        return;
+      }
+
+      let top = rect.bottom + window.scrollY;
+
+      if (rect.bottom + dropdownRect.height > window.innerHeight) {
+        top = rect.top + window.scrollY - dropdownRect.height;
+      }
+
+      setMenuPosition((prev) => {
+        if (
+          Math.abs(prev.top - top) < 0.5 &&
+          Math.abs(prev.left - rect.left) < 0.5
+        ) {
+          return prev;
+        }
+        return {
+          top,
+          left: rect.left,
+          width: rect.width,
+        };
       });
     }
-  }, [isOpen]);
+  }, [isOpen, filterValue, menuPosition.width]);
 
   useEffect(() => {
     // 마우스 벗어난 영역 클릭 시 드롭다운 닫기
@@ -105,17 +123,6 @@ export const Select = ({
 
   return (
     <div className="relative">
-      {label ? (
-        <p className={clsx("mb-1 text-text-standard", {})}>
-          <span
-            className={clsx("", {
-              "after:content-['*'] after:ml-1 after:text-danger": required,
-            })}
-          >
-            {label}
-          </span>
-        </p>
-      ) : null}
       <label className="relative w-fit hidden md:block">
         <input
           ref={inputRef}
@@ -126,15 +133,7 @@ export const Select = ({
             setFilterValue(e.target.value);
           }}
           onFocus={() => setIsOpen(true)}
-          className={clsx(
-            "transition-all bg-[var(--input-background-standard)] border px-4 py-2 border-[var(--color-border)] text-[var(--text-standard)] rounded-[var(--input-rounded)]",
-            { "placeholder:text[var(--input-text-placeholder)]": true },
-            { "focus:border-[var(--input-border-focus)]": true },
-            {
-              "disabled:bg-[var(--input-background-disabled)] disabled:cursor-not-allowed":
-                disabled,
-            }
-          )}
+          className="select hidden sm:block"
           disabled={disabled}
         />
         <div
@@ -150,7 +149,7 @@ export const Select = ({
         createPortal(
           <ul
             ref={dropdownRef}
-            className="absolute w-full border rounded bg-[var(--input-background-standard)] border-[var(--input-border-standard)] shadow-md mt-1"
+            className="absolute w-full select-menu"
             style={{
               top: menuPosition.top,
               left: menuPosition.left,
@@ -161,7 +160,7 @@ export const Select = ({
               filteredOptions.map((option, index) => (
                 <li
                   key={index}
-                  className="px-4 py-2 text-[var(--text-standard)] hover:bg-primary/10 cursor-pointer"
+                  className="select-menu-item"
                   onClick={() => {
                     setFilterValue(option);
                     setIsOpen(false);
@@ -171,19 +170,13 @@ export const Select = ({
                 </li>
               ))
             ) : (
-              <li className="px-4 py-2 text-gray-500">No results</li>
+              <li className="select-menu-item">No results</li>
             )}
           </ul>,
           document.body
         )}
       <select
-        className={clsx(
-          " block transition-all bg-[(--input-background-standard)] border px-4 py-2 border-[var(--color-border)] text-[var(--text-standard)] rounded-input-rounded",
-          { "placeholder:text-input-text-placeholder": true },
-          { "focus:border-[var(--input-border-focus)]": true },
-          { "disabled:bg-[var(--input-background-disabled)]": true },
-          { "md:hidden": true }
-        )}
+        className="select block sm:hidden"
       >
         {options.map((option, index) => {
           return (
@@ -204,6 +197,7 @@ export const Radio = ({
   className,
   onChange,
   defaultChecked,
+  checked,
 }: {
   name: string;
   value: string;
@@ -211,15 +205,16 @@ export const Radio = ({
   className?: string;
   onChange?: () => void;
   defaultChecked?: boolean;
+  checked?: boolean;
 }) => {
   return (
     <>
       {label ? <p>{label}</p> : null}
-      <label className="flex items-center gap-2">
+      <label className="flex items-center gap-1">
         <input
           type="radio"
           className={clsx(
-            "relative appearance-none peer w-5 h-5 bg-[var(--input-background-standard)] border border-[var(--color-border)] rounded-full",
+            "relative appearance-none radio rounded-full ",
             {
               "checked:bg-primary after:w-2.5 after:h-2.5 after:bg-[var(--input-background-standard)] after:content-[''] after:absolute after:rounded-full after:left-1 after:top-1":
                 true,
@@ -231,6 +226,7 @@ export const Radio = ({
           name={name}
           onChange={onChange}
           defaultChecked={defaultChecked}
+          checked={checked}
         />
         <span>{value}</span>
       </label>
@@ -240,15 +236,12 @@ export const Radio = ({
 
 export const Checkbox = ({
   text,
-  label,
-  className,
   onChange,
   disabled,
   required,
   defaultChecked,
 }: {
   text?: string;
-  label?: string;
   className?: string;
   onChange?: () => void;
   disabled?: boolean;
@@ -257,30 +250,16 @@ export const Checkbox = ({
 }) => {
   return (
     <>
-      {label ? <p>{label}</p> : null}
-      <label className="relative flex flex-nowrap items-center gap-1">
+      <label className="checkbox gap-1.5">
         <input
           type="checkbox"
-          className={clsx(
-            "relative appearance-none peer min-w-5 min-h-5 bg-[var(--input-background-standard)] border border-[var(--color-border)] rounded-common",
-            { "checked:bg-primary": true },
-            { "focus:border-[var(--input-border-focus)]": true },
-            {
-              "disabled:bg-[var(--input-background-disabled)] disabled:cursor-not-allowed":
-                true,
-            },
-            {
-              "after:content-['*'] after:text-danger after:absolute after:-right-1 after:-top-2":
-                required,
-            },
-            className
-          )}
+          className="appearance-none hidden"
           onChange={onChange}
           disabled={disabled}
           required={required}
           defaultChecked={defaultChecked}
         />
-        <span className="absolute left-0.5 top-1 invisible  peer-checked:visible fill-[var(--input-background-standard)] ">
+        <span>
           <svg
             xmlns="http://www.w3.org/2000/svg"
             className="h-4 w-4"
@@ -297,8 +276,8 @@ export const Checkbox = ({
         {text ? (
           <span
             className={clsx(
-              "text-[var(--text-standard)] text-nowrap select-none",
-              { "!text-[var(--input-text-disabled)]": disabled }
+              "text-text-standard text-nowrap select-none",
+              { "!text-text-disabled": disabled }
             )}
           >
             {text}

package/app/templates/Modal/Modal.tsx

@@ -29,11 +29,11 @@ export const ModalContent = ({
       isOpen={isOpen}
       onRequestClose={onRequestClose}
       shouldCloseOnEsc={true}
-      overlayClassName="fixed inset-0 bg-black/40 flex justify-center items-center z-50"
-      className={`bg-[var(--modal-background)] p-0 rounded shadow-md w-full flex flex-col ${size === "normal" ? "max-w-md" : size === "middle" ? "max-w-xl" : size === "large" ? "max-w-5xl" : size === "xl" ? "max-w-6xl" : size === "full" ? "max-w-screen" : size === "full-screen" ? "w-screen h-screen" : null}`}
+      overlayClassName="modal-overlay"
+      className={`modal modal-${size}`}
     >
       <ModalTitle onRequestClose={onRequestClose} title={modalTitle} />
-      <div className="p-4 w-full h-full">{children}</div>
+      <div className="modal-content">{children}</div>
       <ModalFooter modalFooter={modalFooter} />
     </ReactModal>
   );
@@ -50,11 +50,11 @@ type ModalTitleProps = {
 
 export const ModalTitle = ({ title, onRequestClose }: ModalTitleProps) => {
   return (
-    <div className="flex justify-between py-3 px-4">
-      <h6>{title}</h6>
+    <div className="modal-header">
+      <h6 className="modal-title">{title}</h6>
       <button
         onClick={onRequestClose}
-        className="material-symbols-outlined cursor-pointer"
+        className="material-symbols-outlined modal-close"
       >
         close
       </button>
@@ -67,5 +67,5 @@ export const ModalFooter = ({
 }: {
   modalFooter: React.ReactNode;
 }) => {
-  return <div className="flex justify-end py-3 px-4">{modalFooter}</div>;
+  return <div className="modal-footer">{modalFooter}</div>;
 };