개발자 가이드

테마 패키지 만들기

테마 패키지는 레이아웃과 여러 모듈 스킨을 한 벌로 묶어 배포·적용하는 Zittme의 방식입니다. 사용자는 테마 하나를 설치·적용하면 레이아웃과 게시판·회원 등 각 모듈 스킨이 서로 어울리는 한 세트로 바뀝니다.

테마는 새로운 종류의 자료가 아닙니다. 이미 있는 레이아웃·스킨을 묶는 포장입니다. 구성요소 각각은 평소처럼 만들면 됩니다.

1. 폴더 구조: 전부 자기 폴더 안에

테마는 themes/{테마이름}/ 안에 모든 구성요소를 담습니다. 내부 구조는 원래 경로를 그대로 흉내 냅니다.

themes/heritage/
├── theme.xml                              ← 테마 정보와 구성 목록
├── assets/                                ← (선택) 구성요소가 공유하는 CSS 등
├── layouts/
│   └── heritage_default/                  ← 일반 레이아웃과 완전히 같은 구조
│       ├── layout.html
│       ├── conf/info.xml
│       ├── css/  js/
└── modules/
    ├── board/skins/heritage_default/      ← 일반 게시판 스킨과 같은 구조
    └── member/skins/heritage_default/

이렇게 하는 이유는 충돌이 없기 때문입니다. 테마의 게시판 스킨과 다른 자료의 게시판 스킨이 이름이 같아도, 서로 다른 폴더에 있으므로 덮어쓰지 않습니다. 테마를 지우면 폴더 하나만 지워집니다.

2. theme.xml

<?xml version="1.0" encoding="UTF-8"?>
<theme schema="1.0">
	<title xml:lang="ko">헤리티지</title>
	<description xml:lang="ko">레이아웃·게시판·회원 스킨이 한 벌로 맞춰진 테마입니다.</description>
	<version>1.0.0</version>
	<date>2026-08-04</date>
	<author email_address="you@example.com" link="https://example.com">제작자</author>
	<license>GPLv2</license>

	<components>
		<component type="layout" name="heritage_default" />
		<component type="module-skin" target="board" name="heritage_default" />
		<component type="module-skin" target="member" name="heritage_default" />
	</components>

	<apply>
		<layout name="heritage_default" />
		<skin module="board" name="heritage_default" />
		<skin module="member" name="heritage_default" />
	</apply>
</theme>

components: 이 테마 폴더 안에 무엇이 들어 있는지 선언합니다. type 은 layout 또는 module-skin(이때 target 으로 모듈 지정).
apply: "테마 적용"을 눌렀을 때 무엇을 어디에 입힐지 정합니다. 적용 전에 바뀔 목록을 사용자에게 보여주고 확인을 받습니다.

없는 모듈은 건너뜁니다

테마가 커머스 스킨을 포함해도, 커머스 모듈이 설치되지 않은 사이트에서는 그 항목만 조용히 건너뜁니다. 부가 모듈용 스킨을 세트에 넣어도 안전합니다.

반응형 테마

테마를 반응형으로 선언하려면 구성요소 스킨·레이아웃이 모두 <responsive>true</responsive> 표시를 갖고 있어야 합니다. 하나라도 빠지면 검증에서 거부됩니다. (반응형 뷰와 반응형 표시 참고)

3. 구성요소는 평소처럼 만든다

테마 안의 레이아웃·스킨은 문법도 규약도 일반 자료와 완전히 같습니다. 위치만 테마 폴더 안일 뿐입니다.

레이아웃: layout.html + conf/info.xml (extra_vars, 메뉴 선언, 반복 필드 포함)
스킨: 해당 모듈의 기본 스킨과 같은 템플릿 파일 구성

공유 자산: 테마 전체가 같은 색·글꼴 체계를 쓰게 하려면 themes/{이름}/assets/ 에 공통 CSS를 두고 각 구성요소에서 상대 경로로 불러옵니다. 색을 CSS 변수로 모아 두면 테마 전체의 색을 한 곳에서 바꿀 수 있습니다.

/* themes/heritage/assets/heritage.css */
:root {
	--hr-brand: #6c5ce0;
	--hr-ink: #10151f;
	...
}

/* 게시판 스킨 css 에서 */
@import url("../../../../../assets/heritage.css");

4. 설치와 적용 동작

설치는 전부 검증한 뒤에 전부 푸는 방식입니다. 구성요소 하나라도 문제가 있으면 아무것도 설치되지 않습니다.
적용 범위는 선택한 사이트 안으로 한정됩니다.
적용 전에 무엇이 바뀌는지 목록을 보여주고 확인을 받습니다.

5. 제작 체크리스트

theme.xml 의 components 와 실제 폴더 내용이 일치하는가
각 구성요소가 단독으로도 정상 동작하는가 (테마는 포장일 뿐이므로)
반응형 선언 시 모든 구성요소에 <responsive>true</responsive> 가 있는가
템플릿 v2를 쓴다면 여러 줄 {{-- --}} 주석을 쓰지 않았는가: 한 줄 주석만 제거되므로 여러 줄 주석은 서버 오류를 냅니다. 여러 줄 설명은 HTML 주석으로 쓰세요.
레이아웃 CSS에 html, body 배경을 선언했는가: 최상위 div에만 배경을 칠하면 다크 모드에서 화면 가장자리에 흰 띠가 남습니다.