For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/theming.md (or send Accept: text/markdown).

제품 테마

마케팅 브랜드 테마를 변경하지 않고 키트의 제품 크롬을 당신의 SaaS에 맞게 개인화하세요.

이 가이드에 대해 질문하기

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. VS Code에서 로그인된 제품 화면용 apps/web/app/app-theme.css를 열고 컬러 팩을 추가하려면 apps/web/src/theme/catalog.ts를 엽니다. 제품 색상에 대해 apps/web/app/theme.css를 편집하지 마십시오. 마케팅 브랜드를 통제합니다.

2. 저장소 루트에서 corepack pnpm --filter @supastack/web dev를 실행한 다음 http://localhost:3000/settings/appearance.를 방문합니다.

3. 로컬 지점에서 토큰을 변경하고 미리보기를 새로 고칩니다. 예상: 홈페이지가 선택한 마케팅 테마를 유지하는 동안 대시보드 컨트롤이 업데이트됩니다.

마케팅 브랜드와 제품 테마는 별도 파일입니다. 대시보드, 인증, 설정, 결제, 채팅, 조직 크롬에는 apps/web/app/app-theme.css를 편집하세요. 색상 팩은 apps/web/src/theme/catalog.ts에 추가하세요. 밀도, 반경, 폰트, 레이아웃 축은 apps/web/src/theme/presets.ts와 app-theme.css의 대응하는 html[data-*] 규칙에서 확장하세요. 마케팅 아이덴티티는 apps/web/app/theme.css를 편집하는 대신 apps/web/src/theme/marketing-theme.ts(MARKETING_THEME_MODE: locked | inherit | 팩 id)에서 선택하세요 — .marketing-theme:not(.app-theme):not([data-theme]):not([data-marketing-theme="inherit"])를 통한 잠금이 기본적으로 supastack 홈의 Obsidian 브랜드를 유지합니다.

런타임에 설정 → 모양 → ThemePicker는 색상, 밀도, 모서리 반경, 글꼴, 레이아웃을 브라우저 쿠키와 localStorage에 저장하여 theme-boot.ts가 첫 페인트 전에 모든 축을 복원하도록 하고, 로그인한 사용자의 전체 모양 번들을 user_appearance(GET/PUT /api/account/appearance)를 통해 브라우저 간에 동기화합니다. 같은 페이지에 키트 UI 갤러리가 마운트되어 팩과 프리셋이 버튼, 입력란, 카드, 배지, 대화상자를 실시간으로 업데이트합니다. 자세한 디자인 설명과 복사 예시 코드는 docs/design/kit-product-theme.md 및 docs/design/kit-ui-gallery.md에 있습니다.

/* Edit product chrome here — not theme.css */
.app-theme {
  --radius-card: 14px;
  background: var(--page);
  color: var(--text);
}
.app-theme .button-primary {
  background: var(--accent);
  color: var(--accent-ink);
}

/* catalog.ts — append a ThemeDefinition with every THEME_TOKEN_NAMES entry */
{
  id: "coral",
  name: "Coral",
  colorScheme: "light",
  tokens: { "--page": "#fff7f4", "--accent": "#e06b4f" /* …full token set… */ }
}

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

corepack pnpm --filter @supastack/web dev

# In a second terminal, after changing a theme token:
corepack pnpm test -- apps/web/src/theme/contrast.test.ts

구현 워크플로

팩을 추가할 때 contrast.test.ts를 녹색으로 유지하세요. 프리셋 id를 추가할 때 presets.ts와 app-theme.css의 html[data-density|data-radius|data-font|data-layout] 리매핑을 업데이트해 ThemePicker와 anti-FOUC 부팅이 일치하게 하세요.

마케팅 화면을 위해 marketing/brand-geometry.ts의 공유 4타일 브랜드 지오메트리를 보존하세요. 헤더 마크는 투명하게 유지되고, 파비콘과 앱 아이콘 자산은 둥근 검은 배경을 유지합니다. MARKETING_THEME_MODE가 "locked"(키트 기본값)인 동안 순수 마케팅 페이지는 Obsidian을 유지합니다. 제품은 다른 팩을 고정하거나 방문자의 선택을 상속할 수 있습니다.

검증 및 문제 해결

색상 변경이 마케팅 홈페이지에 영향을 미치는 경우 app-theme.css를 편집했는지 확인하고 apps/web/src/theme/marketing-theme.ts.를 검토하세요. 텍스트를 읽기 어려워지면 이전 값을 복원하고 루트에서 corepack pnpm test -- apps/web/src/theme/contrast.test.ts를 실행한 후 다시 시도하세요.

키트 테마 토큰이나 팩을 수정한 후 /settings/appearance의 ThemePicker가 키트 UI 갤러리와 /dashboard, /auth, /billing, /chat, 조직 셸을 업데이트하는지 검증하세요. /가 Obsidian 마케팅 잠금을 유지하는지 확인하세요(MARKETING_THEME_MODE가 다르게 말하지 않는 한). 테마 단위 계약(catalog, presets, contrast, theme-ownership, kit-ui-gallery)과 가능한 경우 Playwright application-theme을 실행하세요. 키보드 포커스, 대비, 320px, 모션 감소를 확인하세요.