Theming

Meerkit의 스타일은 새로운 스타일 시스템이 아닙니다. Tailwind CSS와 shadcn/ui를 쓰던 방식 그대로 두고, 그 위에 Meerkit의 색·모서리·모션 값을 덧붙인 얇은 레이어입니다. 그래서 Tailwind와 shadcn을 아는 사람은 새로 배울 것이 거의 없습니다.

How it fits together

Tailwind CSS v4     @import "tailwindcss" · @theme inline      유틸리티 클래스(bg-primary 등)를 만든다
 └ shadcn/ui        components.json · src/components/ui        컴포넌트 코드. 색은 의미 이름(primary, card…)으로만 쓴다
    └ Meerkit 토큰  src/meerkit/styles/tokens.css              --mk-* 변수. 값의 단일 출처
       └ Meerkit 화면  src/meerkit/**                           shadcn 컴포넌트를 조합해 만든 로그인·관리자 화면

버튼 하나가 색을 얻는 경로는 다음과 같습니다.

<Button>                       className="bg-primary"           ← shadcn 컴포넌트
  → Tailwind                   --color-primary                  ← @theme inline
  → Meerkit 토큰               var(--mk-primary)                ← tokens.css
  → 값                         #2a2c3b

• 컴포넌트는 값을 모르고 의미 이름만 압니다. 그래서 값을 바꿔도 컴포넌트를 고칠 필요가 없습니다.
• 값은 --mk-* 변수 한 곳에만 있습니다. 바꾸고 싶으면 이 변수만 건드리면 됩니다.
• shadcn CLI로 새 컴포넌트를 추가해도 같은 의미 이름을 쓰므로 자동으로 Meerkit 색을 따릅니다.

Choose a theme

프로젝트 루트의 meerkit.config.ts에서 고릅니다. 킷 폴더(src/meerkit)는 건드리지 않습니다.

import { defineMeerkitConfig } from "@/meerkit/define-config";

export default defineMeerkitConfig({
  theme: "meerkit", // "meerkit" | "shadcn"
  motion: true,     // false면 Meerkit 애니메이션을 모두 끈다
});

선택은 루트 <html>의 data-mk-theme 속성으로 반영됩니다. 코드를 지우거나 import를 바꾸지 않아도 됩니다.

Use your own shadcn theme

이미 쓰고 있는 shadcn 테마(globals.css의 --background, --primary 등)를 유지하고 싶다면 theme: "shadcn"으로 바꾸세요. Meerkit 변수가 shadcn 변수를 가리키도록 자동으로 연결됩니다.

Change individual values

기본 스타일에서 일부만 바꾸려면 tokens.css를 고치지 말고, globals.css에서 import 아래에 덮어쓰세요. 그래야 킷을 업데이트해도 내 값이 유지됩니다.

@import "tailwindcss";
@import "../meerkit/styles/tokens.css";

:root {
  --mk-brand: #7c3aed;   /* 포인트 색 */
  --mk-primary: #111827; /* 기본 버튼 */
  --mk-radius: 0.5rem;   /* 모서리 */
}

Tokens

Dark mode

기본 제공은 라이트 테마뿐입니다. 다크 모드를 추가하려면 같은 --mk-* 변수만 다시 정의하면 되고, 컴포넌트는 고치지 않습니다.

:root[data-theme="dark"] {
  --mk-background: #0b0c10;
  --mk-foreground: #f2f3f7;
  --mk-card: #14161c;
  --mk-surface: #1a1d25;
  --mk-muted: #1f222b;
  --mk-accent: #262a34;
  --mk-border: #2a2e39;
  --mk-primary: #f2f3f7;
  --mk-primary-foreground: #0b0c10;
}

Radius

--mk-radius 하나로 모든 모서리가 바뀝니다. 작을수록 각지고 클수록 둥글어집니다.

Fonts

기본 글꼴은 Pretendard(한글·영문), 코드는 시스템 모노스페이스입니다. --font-sans와 app/layout.tsx의 스타일시트를 바꾸면 교체됩니다.

Motion

Meerkit의 움직임은 한 가지 원칙을 따릅니다: 항상 부드럽게. 급하게 멈추거나 튕기지 않고, 빠르게 시작해 천천히 감속하며 멈춥니다.

• 곡선은 --mk-ease 하나만 씁니다 (cubic-bezier(0.22, 1, 0.36, 1)). 닫힐 때만 --mk-ease-in으로 가볍게 빠집니다.
• 나타날 때는 길게(0.5~0.9초), 사라질 때는 짧게(0.3초 안팎) 합니다.
• 움직임은 투명도, 아주 작은 이동, 약한 블러만 씁니다. 선형(linear)이나 바운스는 쓰지 않습니다.

모션 끄기

• meerkit.config.ts에서 motion: false로 설정하면 위 클래스가 모두 꺼집니다.
• 사용자 OS에서 "동작 줄이기"를 켰다면 설정과 관계없이 자동으로 꺼집니다.

내 컴포넌트에 쓰기

<section className="mk-rise" style={{ animationDelay: "200ms" }}>
  ...
</section>

Not using the Meerkit style

Meerkit 스타일이 필요 없다면 두 단계로 정리할 수 있습니다.

1단계: 값만 끄기 (권장)

theme: "shadcn"과 motion: false로 바꾸면 코드는 그대로 두고 내 shadcn 테마만 적용됩니다.

2단계: 코드까지 정리하기

Meerkit 전용 토큰과 클래스를 완전히 없애고 싶다면 아래 순서로 정리합니다. 먼저 사용처를 찾으세요.

grep -rnE "bg-brand|text-brand|border-brand|bg-surface|shadow-soft|mk-" src

1. 위 표대로 클래스를 바꿉니다.
2. globals.css에서 tokens.css import와 mk-* 키프레임을 지웁니다.
3. layout.tsx의 data-mk-theme, data-mk-motion 속성을 지웁니다.
4. 쓰지 않는 화면(welcome/, docs/)은 폴더째 삭제해도 인증 기능에는 영향이 없습니다.

Add a shadcn component

shadcn CLI로 추가한 컴포넌트는 같은 의미 이름을 쓰므로 별도 작업 없이 현재 테마를 따릅니다.

npx shadcn@latest add select