Fiori 브랜딩 90%는 CSS 금지 — UI Theme Designer #shorts #SAP #Fiori

개요 및 이 글에서 얻어갈 것

SAP Fiori 앱을 회사에 배포하다 보면 반드시 마주치는 요구사항이 있습니다. "우리 회사 CI 컬러로 바꿔주세요", "로고를 헤더에 넣어주세요", "폰트를 사내 표준 Pretendard로 통일해주세요" 같은 브랜딩 요청입니다. 이때 CSS를 직접 오버라이드하기 시작하면 SAPUI5 버전 업그레이드 때마다 스타일이 깨지는 지옥이 시작됩니다. UI Theme Designer는 이런 문제를 원천 차단하기 위한 SAP의 브랜딩 도구입니다. 이 글에서는 Base Theme 위에 Custom Theme을 올리는 원리부터, BTP Cockpit에서 활성화하는 절차, 실제 회사 브랜드 컬러(#1A237E)와 폰트를 Fiori Launchpad에 적용하는 과정, 프로덕션 배포와 유지보수 전략까지 순서대로 다룹니다.

• UI Theme Designer의 존재 이유와 CSS 직접 수정의 위험성 이해
• BTP Cockpit에서 UI Theme Designer 서비스 활성화
• Base Theme, Parameter, Custom Theme 관계 파악
• 회사 CI 컬러/폰트/로고를 파라미터로 적용하는 실전 예제
• Fiori Launchpad와 개별 앱에 테마 배포·바인딩
• SAPUI5 버전 업그레이드 대응 및 유지보수 팁

미리 알아두면 좋은 배경

이 글은 Fiori Launchpad 또는 SAPUI5 앱을 한 번이라도 배포해 본 중급 개발자를 대상으로 합니다. HTML/CSS 기본기, LESS(CSS 전처리기) 개념, SAP BTP Cockpit에서 서비스를 활성화해 본 경험이 있으면 매끄럽게 따라올 수 있습니다. Fiori Launchpad에서 카탈로그와 그룹을 구성해 본 경험, 그리고 관리자 권한(예: PortalAdmin, UIThemeDesigner)이 부여된 사용자 계정이 필요합니다.

환경, 버전, 준비물 정리

이 글의 예제는 SAP BTP Cloud Foundry 환경의 UI Theme Designer 서비스(SaaS 형태)를 기준으로 작성했습니다. 온프레미스 환경(SAP NetWeaver AS ABAP 7.5+, SAP Gateway hub)의 UI Theme Designer도 개념은 동일하지만 배포 경로가 다르므로 각 환경 매뉴얼을 병행 참고해야 합니다.

• SAP BTP Cloud Foundry 서브 계정 (Trial 또는 Enterprise)
• SAPUI5 1.108 이상 (Long-Term Maintenance 버전 권장)
• Base Theme: sap_horizon (2022년 이후 표준), sap_fiori_3, sap_belize 중 하나
• 역할 컬렉션: UIThemeDesigner, Portal_Admin 할당된 사용자
• 브라우저: Chrome/Edge 최신 버전 (Safari는 폰트 미리보기 이슈 간헐 발생)
• 선택: 회사 로고(SVG 권장), 사내 웹폰트 URL 또는 WOFF2 파일

참고: sap_belize와 sap_bluecrystal은 SAPUI5 최신 릴리스에서 점진적으로 deprecation 되고 있으니 신규 프로젝트라면 sap_horizon을 Base로 삼는 것이 일반적으로 권장됩니다.

핵심 개념 정리

UI Theme Designer는 SAPUI5/Fiori 앱의 시각적 스타일을 파라미터 단위로 변경할 수 있게 해주는 웹 기반 디자인 도구입니다. 핵심은 "CSS 파일을 직접 편집하지 않는다"는 원칙입니다. 그 대신 미리 정의된 500개 이상의 Theme Parameter(예: sapBrandColor, sapShellColor, sapFontFamily)의 값을 조정하면, 도구가 내부적으로 LESS를 컴파일해 완성된 CSS 번들을 생성합니다.

이 구조를 페인트 팔레트에 비유하면 이해가 쉽습니다. Base Theme은 미리 채색된 밑그림이고, Custom Theme은 그 위에 덧칠하는 투명 레이어입니다. 여러분은 물감(파라미터 값)만 바꾸고, 실제 붓질(CSS 생성)은 도구가 담당합니다. SAPUI5가 1.110에서 1.120으로 업그레이드되어 밑그림이 바뀌어도, 여러분의 덧칠 레이어(파라미터 값)는 그대로 적용됩니다.

구성 요소를 그림으로 표현하면 다음과 같습니다.

┌─────────────────────────────────────────┐
│  Base Theme (sap_horizon)               │  ← SAP 제공, 건드리지 않음
│    ├── base.less                        │
│    ├── global.less                      │
│    └── library-parameters.json          │
└─────────────────────────────────────────┘
              ▲
              │ 상속
┌─────────────────────────────────────────┐
│  Custom Theme (my_company_theme)        │  ← 우리가 만드는 레이어
│    ├── 변경된 Parameter (JSON)          │
│    ├── Custom CSS (선택적, 최소화)      │
│    └── 리소스 (로고, 폰트)              │
└─────────────────────────────────────────┘
              ▼
       Compiled CSS Bundle
       (library.css, library-RTL.css)

Theme Parameter는 계층적으로 설계되어 있습니다. 최상위에는 브랜드 아이덴티티급 파라미터(sapBrandColor, sapHighlightColor)가 있고, 그 아래로 컨트롤 단위(sapButton_Background, sapList_HeaderBackground)가 상속받는 구조입니다. 상위 파라미터 하나만 바꾸면 수십 개 컨트롤이 일관되게 변합니다. 이 상속 트리를 이해하지 못하고 하위 파라미터를 하나씩 바꾸다 보면 유지보수 부담이 기하급수적으로 늘어납니다.

또한 Quick Mode(간이 편집)와 Expert Mode(전체 파라미터)라는 두 편집 모드가 있는데, 브랜딩 초기에는 Quick Mode의 6~8개 핵심 파라미터만으로 80% 이상의 시각적 변화를 얻을 수 있습니다.

1단계 실전 예제: 기본 Custom Theme 만들기

먼저 BTP Cockpit에서 UI Theme Designer 서비스를 활성화합니다. Subaccount → Service Marketplace → "UI Theme Designer" 검색 → Create Instance/Subscription 순으로 진행합니다. Subscription이 완료되면 좌측 메뉴 Instances and Subscriptions에서 애플리케이션 링크가 활성화됩니다.

도구에 진입한 후 New Theme을 클릭하면 Base Theme 선택 창이 뜹니다. 여기서 sap_horizon을 선택하고 이름을 zcompany_horizon으로 지정합니다(사내 표준 접두어 z 권장). 이제 Quick 탭에서 다음 값을 입력해 봅니다.

{
  "themeId": "zcompany_horizon",
  "baseTheme": "sap_horizon",
  "quickParameters": {
    "sapBrandColor": "#1A237E",
    "sapHighlightColor": "#1A237E",
    "sapShellColor": "#0D1442",
    "sapTitleColor": "#0D1442",
    "sapFontFamily": "'Pretendard', 'Noto Sans KR', Arial, sans-serif"
  }
}

우측 프리뷰 패널에서 Fiori Launchpad 샘플이 실시간으로 색상을 반영합니다. 상단 Save를 누르면 서브계정 전용 저장소에 Custom Theme이 저장됩니다. 이 시점에는 아직 어떤 앱에도 적용되지 않은 상태입니다.

2단계 실전 예제: 로고·폰트·상세 파라미터를 반영한 실무 시나리오

실무에서는 색상만 바꾸는 걸로 끝나지 않습니다. 헤더에 회사 로고를 넣고, 사내 웹폰트를 로드하고, 특정 컨트롤(예: 승인 버튼)의 강조 색을 별도로 지정해야 합니다. Expert 탭으로 이동해 다음 파라미터를 추가로 조정합니다.

/* zcompany_horizon custom.less (도구가 자동 생성, 개념 이해용) */

/* 1. 웹폰트 로드 - Manifest의 CSS Import 영역에 추가 */
@import url('https://cdn.company.co.kr/fonts/pretendard/pretendard.css');

/* 2. 브랜드 파라미터 재정의 */
@sapBrandColor: #1A237E;
@sapHighlightColor: #1A237E;
@sapShellColor: #0D1442;
@sapShell_TextColor: #FFFFFF;
@sapShell_InteractiveTextColor: #E8EAF6;

/* 3. 폰트 계열 */
@sapFontFamily: 'Pretendard', 'Noto Sans KR', Arial, sans-serif;
@sapFontHeaderFamily: 'Pretendard', 'Noto Sans KR', Arial, sans-serif;
@sapFontSize: 0.875rem;

/* 4. 버튼 강조색 - Positive Action */
@sapButton_Emphasized_Background: #1A237E;
@sapButton_Emphasized_BorderColor: #1A237E;
@sapButton_Emphasized_TextColor: #FFFFFF;

/* 5. 링크 색상 */
@sapLinkColor: #303F9F;
@sapActiveColor: #283593;

로고는 Resources 탭에서 SVG 파일을 업로드한 뒤 sapUiGlobalLogo 파라미터에 URL을 연결합니다. Fiori Launchpad는 이 파라미터를 자동으로 좌상단 로고 위치에 렌더링합니다.

{
  "resources": [
    {
      "fileName": "company_logo.svg",
      "path": "/UI5/themes/zcompany_horizon/img/company_logo.svg"
    }
  ],
  "parameters": {
    "sapUiGlobalLogo": "url('img/company_logo.svg')"
  }
}

로깅과 검증을 위해 저장 후 반드시 우측 Preview → Fiori Elements List Report와 SAPUI5 Explored 두 시나리오를 모두 확인합니다. 특정 컨트롤(예: SmartTable 헤더)에서 색상이 부자연스러우면 상속 파라미터가 아니라 하위 파라미터가 하드코딩된 경우이므로 Expert 탭에서 개별 조정이 필요합니다. 문제가 반복된다면 window["sap-ui-config"] 로그를 브라우저 콘솔에 출력해 어떤 테마가 로드되었는지 확인합니다.

// 브라우저 콘솔 검증 스니펫
console.log('Applied theme:', sap.ui.getCore().getConfiguration().getTheme());
console.log('Theme root:', sap.ui.getCore().getConfiguration().getThemeRoot());

// 특정 파라미터 실제 적용값 확인
sap.ui.require(["sap/ui/core/theming/Parameters"], function(Parameters) {
    const brand = Parameters.get({
        name: "sapBrandColor",
        callback: (value) => console.log("sapBrandColor resolved:", value)
    });
    console.log("sapBrandColor sync:", brand);
});

3단계 실전 예제: 프로덕션 배포와 Launchpad 바인딩

테마가 완성되면 Publish 버튼으로 서브계정 전역에 공개합니다. 그다음 두 가지 방식으로 적용할 수 있습니다.

방식 A는 Fiori Launchpad 전체에 기본 테마로 지정하는 것입니다. BTP Cockpit → Portal Service → Site Directory → 대상 사이트 → Site Settings → Themes 영역에서 zcompany_horizon을 Default로 지정합니다. 이후 접속하는 모든 사용자는 별도 설정 없이 새 테마를 보게 됩니다.

방식 B는 개별 SAPUI5 앱의 manifest.json에서 명시적으로 지정하는 방법으로, 앱 배포 파이프라인 단위 통제가 필요할 때 사용합니다.

{
  "sap.ui5": {
    "dependencies": {
      "minUI5Version": "1.120.0"
    },
    "theme": "zcompany_horizon",
    "resourceRoots": {
      "zcompany.theme": "/comsapuitheming.runtime/themeroot/v1/zcompany_horizon/"
    }
  }
}

프로덕션 반영 전에는 반드시 아래 체크리스트를 통과시킵니다.

• 주요 페이지 5종(Launchpad Home, List Report, Object Page, Analytical, Fact Sheet) 스크린샷 캡처 후 디자인팀 승인
• 대비비 검사: sapContent_ForegroundColor vs sapContent_ForegroundTextColor의 WCAG AA 4.5:1 이상 확인
• RTL(아랍어 등) 지원 필요 시 preview에서 Direction을 RTL로 전환해 검증
• 모바일(Fiori Client, 반응형 브라우저) 프리뷰 확인
• 성능: 컴파일된 library.css 번들 크기가 200KB를 넘지 않는지 (넘으면 Custom CSS 남용 의심)

배포 자동화는 다음과 같이 CI/CD 파이프라인의 사후 단계에 넣을 수 있습니다.

stages:
  - build
  - deploy-app
  - verify-theme

verify-theme:
  stage: verify-theme
  script:
    - curl -s -H "Authorization: Bearer $BTP_TOKEN" \
        "$THEME_DESIGNER_HOST/api/themes/zcompany_horizon" \
        | jq '.state' | grep -q "PUBLISHED"
    - echo "Theme published check OK"
  only:
    - main

실무에서 자주 부딪히는 문제와 해결책

Custom Theme 적용 후 흔히 발생하는 이슈를 세 가지로 정리합니다.

Q1. 테마를 지정했는데 브라우저에는 여전히 sap_horizon으로 보입니다.

브라우저 캐시와 SAPUI5 CDN 캐시가 원인인 경우가 대부분입니다. 강제 새로고침(Ctrl+Shift+R)과 함께 URL 파라미터 ?sap-ui-theme=zcompany_horizon을 붙여 테스트합니다. 그래도 안 되면 Launchpad Site의 Theme 설정에 Publish가 반영되지 않은 상태입니다. Site Directory에서 Publish를 다시 눌러야 사용자 세션에 반영됩니다.

Q2. SAPUI5 버전을 1.108에서 1.120으로 올리자 특정 컨트롤 색상이 깨졌습니다.

Base Theme의 파라미터가 릴리스 노트에서 리네이밍/deprecation 된 경우입니다. UI Theme Designer는 rebuild 시 경고를 표시하므로, 업그레이드 후 반드시 도구에서 테마를 열고 Rebuild Against Latest Base Theme을 실행합니다. 하위 파라미터 대신 상위 파라미터 위주로 튜닝했다면 이 리스크가 크게 줄어듭니다.

Q3. 사내 웹폰트가 로컬에서는 보이는데 배포 환경에서 로드되지 않습니다.

CDN의 CORS 헤더 문제이거나 CSP(Content Security Policy)의 font-src가 사내 도메인을 허용하지 않은 경우입니다. BTP Portal Service의 CSP 설정에 폰트 도메인을 추가하거나, 폰트 파일을 UI Theme Designer의 Resources로 직접 업로드해 same-origin으로 배포하는 방법이 안정적입니다.

그 밖에 자주 놓치는 지점을 정리하면, Custom CSS 탭은 되도록 비워두는 것이 좋습니다. 여기에 규칙을 넣기 시작하면 파라미터 상속 트리 밖의 하드코딩이 되어 결국 CSS 오버라이드와 같은 유지보수 부담이 돌아옵니다. 정말 필요하다면 특정 클래스(.myCompanyBadge) 한정으로만 사용하고, 표준 컨트롤 selector(.sapMBtn)에 직접 규칙을 걸지 않는 원칙을 지켜야 합니다.

이어서 살펴보면 좋은 주제

UI Theme Designer만으로도 브랜딩의 대부분을 해결할 수 있지만, 더 나아가려면 다음 주제를 이어서 탐색해 보길 권장합니다. 첫째, Fiori Launchpad Site Manager로 Space/Page 단위 커스터마이징과 결합하면 조직별 서로 다른 룩앤필을 하나의 서브계정에서 운영할 수 있습니다. 둘째, SAPUI5 Custom Control을 만들고 여기에도 Theme Parameter를 노출시키면 자사 컴포넌트까지 일관된 브랜딩을 유지할 수 있습니다. 셋째, SAP Build Work Zone(구 Launchpad Service)의 이미지·아이콘 커스터마이징 옵션과 결합해 시각 아이덴티티를 완결시킬 수 있습니다. 마지막으로 Accessibility(WCAG 2.1 AA) 관점에서 색상 대비를 자동 검증하는 파이프라인을 구축하면 브랜딩과 접근성을 동시에 만족시킬 수 있습니다.

더 읽어볼 자료

• SAP Help Portal - UI Theme Designer 공식 가이드
• SAP Help Portal - UI Theme Designer Product Page
• SAP Help Portal - Fiori Launchpad 테마 설정
• SAPUI5 Demo Kit - Theming: Custom Themes
• SAP Fiori Design Guidelines - Horizon
• SAP Community - Fiori 카테고리 Q&A
• SAP Blogs - UI Theme Designer 태그 아카이브