WIZ Design System

WIZ Design System의 Flutter 구현은 wiz_ui 패키지입니다. 웹(@wds/ui-web)과 같은 토큰 SSOT를 wiz_tokens.dart로 생성해 흐르고, WizTheme와 Wiz* 컴포넌트를 제공합니다.

⚠️ wiz_ui는 pub.dev에 배포되지 않습니다 (publish_to: none). Dart 사설 pub 레지스트리도 없습니다. 현실적인 소비 수단은 git 의존입니다 — 앱의 pubspec.yaml에서 사내 GitLab 저장소의 flutter/wiz_ui 경로를 직접 참조합니다.

이 저장소는 회사 전용 비공개 레포입니다(공개 GitHub 아님). 설치하려면 사내망 접근과 git 자격증명이 필요합니다 — 아래 인증 참고.

1. 사전 준비#

Flutter SDK >=3.32.0, Dart SDK ^3.5.0 (패키지 environment 제약).
사내망(또는 VPN)에서 GitLab(175.126.123.151:8000)에 접근 가능한 상태.
브랜드 폰트(Pretendard, OFL)는 패키지에 동봉되어 별도 폰트 설정이 필요 없습니다.

2. git 의존 추가#

앱의 pubspec.yaml에 아래를 넣습니다. ref는 릴리스 태그로 고정하는 것을 권장합니다(아래 버전 고정 참고).

dependencies:
  wiz_ui:
    git:
      url: http://175.126.123.151:8000/wiz-infra/wiz-wds.git
      path: flutter/wiz_ui
      ref: wiz_ui-v0.6.0   # 안정성 위해 릴리스 태그 고정 (main 직소비 금지)

path는 모노레포 안에서 패키지가 위치한 하위 경로(flutter/wiz_ui)입니다. 저장소 루트가 아니라 이 경로를 가리켜야 합니다.

그다음 의존을 해석합니다.

flutter pub get

⚠️ main을 직접 소비하지 마세요. ref: main은 항상 최신 커밋을 가져와 재현 불가능한 빌드가 됩니다 — 어느 날 빌드가 조용히 깨질 수 있습니다. 반드시 태그로 고정하세요.

3. 버전 고정 (릴리스 태그)#

git ref에 릴리스 태그를 써야 앱이 안정 버전에 고정됩니다. 현재 게시된 태그:

wiz_ui-v0.6.0 (최신)
wiz_ui-v0.5.0

태그 명명 규칙은 wiz_ui-v<버전> 입니다(패키지 version과 1:1). 업그레이드할 땐 ref 값을 새 태그로 바꾼 뒤 flutter pub get을 다시 실행합니다. 무엇이 바뀌었는지는 체인지로그에서 확인하세요.

🔖 태그가 없으면 고정할 수 없습니다. 새 버전을 릴리스할 때 통합자가 wiz_ui-v<버전> 태그를 달아야 소비처가 그 버전에 안정적으로 고정됩니다. 커밋 SHA로도 고정 가능하지만(ref: a1b2c3d), 가독성을 위해 태그를 권장합니다.

4. import + 앱을 WDS 테마로 감싸기#

배럴 하나만 import하면 WizTheme·Wiz* 컴포넌트·토큰이 모두 들어옵니다.

import 'package:flutter/material.dart';
import 'package:wiz_ui/wiz_ui.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My WDS App',
      theme: WizTheme.light(),       // 라이트 테마
      darkTheme: WizTheme.dark(),    // 다크 테마
      themeMode: ThemeMode.system,   // OS 설정 따름 (또는 light/dark)
      home: const HomePage(),
    );
  }
}

색·간격 등 토큰은 WizTheme.of(context)로 읽고, 컴포넌트는 웹과 같은 계약(variant=enum, 크기=WizSize.sm/md/lg, 비활성화=onPressed: null)을 따릅니다.

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final c = WizTheme.of(context).colors; // WizColorScheme — c.primary, c.text …
    return Scaffold(
      backgroundColor: c.bg,
      body: Center(
        child: WizButton(
          variant: WizButtonVariant.primary,
          onPressed: () {},
          child: const Text('시작하기'),
        ),
      ),
    );
  }
}

✅ 잘 됐는지 확인: 버튼이 브랜드 색(WDS primary) 으로 보이고, 글자가 Pretendard(둥근 고딕)면 테마 · 토큰 · 동봉 폰트가 모두 적용된 것입니다.

인증 (비공개 레포)#

비공개 GitLab 레포라 flutter pub get이 git 자격증명을 요구합니다. 미리 인증을 설정해 두세요.

토큰 임베드 (간편). Personal Access Token(read_repository 범위)을 URL에 포함합니다. 단, pubspec.lock/pubspec.yaml에 토큰이 노출되니 커밋 금지입니다.
```
url: http://oauth2:<읽기토큰>@175.126.123.151:8000/wiz-infra/wiz-wds.git
```
git credential helper (권장). macOS는 osxkeychain, Linux/CI는 store/환경변수로 자격증명을 관리하면 pubspec.yaml에는 토큰을 두지 않아도 됩니다.
CI/CD. 토큰을 pubspec.yaml에 하드코딩하지 말고 CI 시크릿/환경변수로 주입합니다. 예: 파이프라인에서 git config로 URL 치환(insteadOf)을 걸어 인증된 URL로 매핑.
```
git config --global url."http://oauth2:${WDS_GIT_TOKEN}@175.126.123.151:8000/".insteadOf "http://175.126.123.151:8000/"
flutter pub get
```

🔑 토큰이 만료/순환되면 flutter pub get이 인증 오류로 실패합니다. 관리자에게 최신 read_repository 토큰을 받아 자격증명을 갱신하세요.

문제 해결#

인증 실패 / 403 — git 자격증명(토큰)이 없거나 만료됨. read_repository 토큰을 받아 credential helper 또는 URL에 반영.
연결 안 됨 / 타임아웃 — 사내망(VPN) 확인. 레포는 사내에서만 접근됩니다(HTTP 8000, HTTPS 아님).
패키지 못 찾음 — path: flutter/wiz_ui가 맞는지 확인(저장소 루트가 아니라 하위 경로).
재현 불가능한 빌드 / 갑자기 깨짐 — ref: main 사용 중. 릴리스 태그로 고정.
SDK 버전 충돌 — Flutter >=3.32.0 · Dart ^3.5.0 필요. flutter --version으로 확인 후 업그레이드.

컴포넌트 매핑 · ref 계약 · 테스트 게이트 등 자세한 소비 규칙은 개발자 리소스와 저장소 docs/FLUTTER_GUIDE.md가 정본입니다.