maliang (马良) —— 디자인 시스템 스킬
스크립트 호출 규칙:
python3 scripts/…의 상대 경로는 이 스킬의 설치 디렉터리를 기준으로 합니다(CWD 가정). 사용자 프로젝트에서 실행할 때는 항상{SKILL_DIR}절대 경로로 호출합니다(예:python3 {SKILL_DIR}/scripts/ui-graph.py …).--target/--framework-file등의 입력 매개변수는 명시적으로 사용자 프로젝트 경로를 가리켜야 하며, 스킬 자체의examples/를 분석 대상으로 삼는 것을 금지합니다.
열세 개의 하위 명령어가 UIUX 전체 수명주기(연구→정의→설계→구현→검증→전달→반복, 전체 그림은 references/meta/lifecycle.md 참조)를 다룹니다: design-md(DESIGN.md 생성, 도메인 탐색 및 의사 결정 원장 포함)→ redesign(기존 UI 개선)→ explore(방향이 정해지지 않았을 때 여러 방안 발산-비교-수렴)→ draw-md(페이지 수준 UI 마크다운)· component(단일 컴포넌트 brief)→ preview(미리보기 검증)→ critique(사용성 평가)→ draw-harmony/draw-flutter/draw-element(프레임워크 코드)→ ui-graph(UI 관계 관리)· ip(IP 캐릭터)/ip-handbook(IP 비주얼 매뉴얼).
- design-md(상류)— prose-first 형식의 DESIGN.md(YAML 토큰 + Markdown 디자인 근거, Google Labs agent-first 형식)를 생성합니다. "생성, 적용, 검증, 내보내기" 네 가지 액션을 지원합니다. "디자인 시스템이 무엇이고, 왜"라는 질문을 해결합니다.
- redesign(상류 우회)— 기존 UI를 개선하며, 10차원 감사(SEO 및 추적, 산출물 일관성 포함) + 규칙 유지를 수행합니다. Refresh / Restructure / Rebuild / Deslop 네 가지 모드를 지원합니다. "기존 디자인을 어떻게 개선할 것인가"를 해결합니다.
- draw-md(중류)— DESIGN.md에서 페이지 수준 하드 토큰 UI 마크다운(레이아웃 섹션 + 컴포넌트 매개변수 테이블, 색상/글꼴/간격 모두 토큰 참조, RGBA + HEX)을 생성합니다. "각 페이지/컴포넌트를 구체적으로 어떻게 구현할지"를 해결합니다.
- preview(검증)— Element Plus 프레임워크를 사용하여 draw-md 산출물을 실시간으로 미리보기 검증하며, iOS/Android 기기 케이스를 지원합니다. "효과가 올바른지"를 해결합니다.
- critique(검증·심층 평가)— Nielsen 10 휴리스틱 0-4점 평가 + persona 워크스루 + 인지 부하 체크리스트를 통해 평가 스냅샷/추세/백로그를 생성합니다. "사용하기 좋은지"를 해결합니다. UI 규정 준수/a11y 체크리스트는
references/meta/web-interface-guidelines.md를 읽습니다. 제품 UI 제작 규율과 엄격한 심사/슬롭 제거 심층 프로세스는references/interface-design/를 참조하세요(원래 독립 스킬에서 통합됨). - draw-harmony(하류)— draw-md 논리 UI를 HarmonyOS(ArkTS) 프레임워크 구현으로 변환합니다. "HarmonyOS 코드를 어떻게 작성할지"를 해결합니다.
- draw-flutter(하류)— draw-md 논리 UI를 Flutter 프레임워크 구현으로 변환합니다. "Flutter 코드를 어떻게 작성할지"를 해결합니다.
- draw-element(하류)— draw-md 논리 UI를 Element Plus 프레임워크 구현으로 변환합니다. "Element Plus 코드를 어떻게 작성할지"를 해결합니다.
- ui-graph(관계 관리)— ui-markdown/에서 ui-relationships.json(계층 + 이동) + ui-hash-state.json(해시 기준선) + ui-implementation-map.json(논리 UI ↔ 구현 매핑)을 생성합니다. "페이지 관계를 어떻게 관리하고, 변경 사항을 어떻게 추적하며, 구현 격차는 어디에 있는지"를 해결합니다.
- ip(IP 캐릭터)— DESIGN.md 톤을 기반으로 프롬프트를 구성하고, 우선 text_to_image API를 호출하여 이미지를 생성하며, 실패 시 구조화된 프롬프트 문서를 출력합니다. "프로젝트 IP 캐릭터를 어떻게 생성할지"를 해결합니다.
- ip-handbook(IP 비주얼 매뉴얼)— 8개 모듈로 사양(삼면도/동작 확장/이모티콘 팩/글꼴/색상/레이아웃/주변 기기/일반 요구사항)을 생성하며, 2K HD 3:4 비율입니다. "IP 비주얼 시스템을 어떻게落地할지"를 해결합니다.
하위 명령어 라우팅
🔴 체크포인트: DESIGN.md가 없으면 draw-md / draw-* 하류 하위 명령어로 직접 진입하는 것을 엄격히 금지합니다. 먼저 design-md를 통해 디자인 시스템을 구축해야 합니다. 그렇지 않으면 생성된 UI 마크다운과 프레임워크 코드가 참조할 토큰이 없습니다.
| 사용자 의도 | 하위 명령어 | 전체 프로세스 |
|---|---|---|
| DESIGN.md 생성 / 생성(코드/스크린샷/인터뷰에서) | design-md | references/commands/design-md.md |
| DESIGN.md를 프런트엔드 코드에 적용 | design-md | references/commands/design-md.md |
| DESIGN.md 린트 / diff / 내보내기 / 검증 | design-md | references/commands/design-md.md |
| 🔷 기존 UI 개선 / 재설계(Refresh/Restructure/Rebuild/Deslop AI취향제거) | redesign | references/commands/redesign.md |
| 🔷 방향성 미세 조정(bolder 더 대담하게 / quieter 더 조용하게 / distill 더 정제되게, 비주얼 월드 유지, redesign 경량 문서 선행) | redesign | references/commands/redesign.md |
| 🔷 단일 컴포넌트 brief(버튼 만들기 / 단일 입력 상자 / toast 등 단일 요소, 8가지 상태 하드 게이트) | component | references/commands/component.md |
| 페이지 수준 UI 마크다운 생성(토큰 테이블 + 페이지 사양) | draw-md | references/commands/draw-md.md |
| 페이지 간 재사용 컴포넌트(네비게이션 바 / dock) 사양화 | draw-md | references/commands/draw-md.md |
| 🔷 방향이 정해지지 않음, 먼저 여러 방안 비교 후 확정(레이아웃/밀도/페르소나/상호작용 모델 진정한 차이, 기본 3개 최대 5개) | explore | references/commands/explore.md |
| 🔴 UI 마크다운 효과 미리보기(기기 케이스 + Element) | preview | references/commands/preview.md |
| 🔷 사용성 평가 / 점수 부여(Nielsen+persona 워크스루+인지 부하) | critique | references/commands/critique.md |
| 🔴 UI 마크다운을 HarmonyOS(ArkTS) 코드로 변환 | draw-harmony | references/commands/draw-harmony.md |
| 🔴 UI 마크다운을 Flutter(Dart) 코드로 변환 | draw-flutter | references/commands/draw-flutter.md |
| 🔴 UI 마크다운을 Element Plus(Vue 3) 코드로 변환 | draw-element | references/commands/draw-element.md |
| 🔷 UI 관계도 생성 / 조회(계층 + 이동 + 해시 + 구현 매핑) | ui-graph | references/commands/ui-graph.md |
| 🔷 생성되지 않은 이동 대상 / 비정상 이동 / 구현되지 않은 페이지 / 사양↔코드 의미적 표류(기능 누락/하드코딩 값/아키텍처 이탈) 조회 | ui-graph | references/commands/ui-graph.md |
| 🔷 DESIGN.md 기반 IP 캐릭터 생성(API 우선, fallback 프롬프트) | ip | references/commands/ip.md |
| 🔷 IP 비주얼 매뉴얼 생성(삼면도/동작/이모티콘/글꼴/색상/레이아웃/주변 기기) | ip-handbook | references/commands/ip-handbook.md |
🔴 표시된 행은 draw-md 산출물이 존재하는지 먼저 확인해야 합니다. preview/draw-*에 UI 마크다운 입력이 없으면 하위 명령어 프로세스 내에서 fallback하여 사용자를 draw-md로 안내해야 합니다. 사용자가 대상 프레임워크를 지정하지 않은 경우, draw-*는 먼저 사용자 프로젝트의 기존 프론트엔드 스택을 확인합니다(있음 → 해당 스택을 따르고 가정을 설명함; 없음 →
framework/INDEX.md「프레임워크 선택 가이드」에 따라 시나리오별로 추천하고, 사용자 확인 후 진행). 🔷 표시된 행은 새로운 기능에 속합니다. critique는 먼저 preview 산출물 또는 접근 가능한 페이지가 필요합니다. ui-graph는 먼저 draw-md 산출물이 필요합니다. ip/ip-handbook은 먼저 DESIGN.md가 필요합니다.
하위 명령어로 진입한 후, 해당 프로세스 문서를 따라 실행합니다. 체크포인트, 경계 상황, 전달 확인 체크리스트는 각 하위 명령어 문서에 있습니다. 이 라우터는 프로세스 본문을 포함하지 않습니다.
작업 규모 분류(경량 / 전체)
| 등급 | 판단 기준 | 프로세스 |
|---|---|---|
| 경량 | 프로젝트에 이미 DESIGN.md가 있고, 변경 범위 = 단일 컴포넌트(component 하위 명령어) 또는 단일 페이지 부분 조정 | design-md와 전체 페이지 체크리스트 프로세스를 다시 거치지 않음: draw-md로 대상 페이지만 직접 변경(단일 컴포넌트는 component 사용) + preview로 해당 페이지/컴포넌트를 샘플링 검사 |
| 전체 | 새 프로젝트 / 새 페이지 유형 / 다중 페이지 변경 / 방향 미정(먼저 explore) / DESIGN.md 없음 | 전체 링크 design-md → draw-md → preview → draw-* |
경량이 게이트 면제는 아닙니다. 다음 삭제할 수 없는 항목은 모든 등급에서 완전히 실행해야 합니다:
- a11y 검사 — aria-label, 터치 대상 ≥44px, 대비,
prefers-*환경 설정(CRITICAL 등급,references/meta/rules-priority.md충돌 판결 규칙 4 참조, 타협 불가); - preview 하드 게이트 — validate-draw-md 검사와 preview 평가 disposition은 정상적으로 수행됩니다. 경량의 "샘플링 검사"는 변경된 페이지에 대해서만 수행하는 것을 의미하며, 건너뛰거나 임계값을 낮추는 것이 아닙니다. 유일한 예외: 사용자가 미리보기가 필요하지 않다고 명시적으로 말한 경우
preview.md「건너뛰기 조건(명시적 opt-out)」에 따라 렌더링 및 평가를 건너뛰고, validate 검사는 계속 실행하며, 전달 설명에 DEGRADED 배너를 표시합니다. - draw-md 하드 제약 조건(토큰 참조 / 다크 모드 참조 / 애니메이션 ≤400ms)은 변경된 페이지별로 하나씩 확인합니다(
references/commands/draw-md.md제약 조건 요약 참조).
DESIGN.md가 없는 상태에서의 경량 요청은 "실패 모드 및 fallback" 첫 번째 줄에 따라 처리합니다: 먼저 design-md를 수행하도록 안내하며, 등급 분류에 예외를 제공하지 않습니다.
무인 상태 및 체크포인트 저하
판단 기준: 사용자가 "당신이 정해 / 직접 해"라고 명시적으로 말하거나, 세션이 무인 상태(사용자 부재, 응답 없음)인 경우, 체크포인트는 개별적으로 차단하지 않습니다. "누락된 정보가 핵심 방향을 바꾸고 추론할 수 없는" 경우에만 한 번에 집중적으로 질문합니다. 되돌릴 수 있는 세부 사항은 스스로 결정하고 가정을 설명합니다.
| 체크포인트 유형 | 무인 상태 기본 동작 |
|---|---|
| 방향 / 제안 확인(design-md 0b/0c, explore 방향 목록) | 증거와 권장 사항에 따라 직접 진행합니다. explore는 여전히 3가지 방향을 구체화하고, 세 장의 첫 화면을 480px로 축소하여 나란히 표시하며 선택 이유를 명시합니다. 작업이 명확히 하나의 방향만을 요구하는 경우 질문하지 않고 비교 페이지를 만들지 않습니다. |
| 추출 / 목록 확인(토큰 추출, 페이지 목록) | 현장 증거에 따라 값을 가져오고 신뢰도를 표시합니다(✅/⚠️/❓, 작성 방법은 design-md "추출 경로 신뢰도 표시" 참조). 목록은 기본 규칙에 따라 생성됩니다. |
| 전달 전 확인(preview / critique 조치 확인) | 게이트 및 증거 결과에 따라 진행하며, 전달 설명 첫 줄에 저하 배너를 표시합니다. preview 건너뛰기는 자발적 선택에 속하지 않습니다. 사용자가 명시적으로 preview.md「건너뛰기 조건(명시적 opt-out)」에 따라 허용하는 경우에만 가능하며, 무인 상태에서는 항상 정상 실행합니다. |
| 자료 / API 유형 확인(ip 등) | API를 사용할 수 없으면 기존 fallback을 따릅니다. 산출물은 새 경로에 기록하며 덮어쓰지 않습니다. |
표시 규율: 전달 설명 첫 줄에 ⚠️ DEGRADED: unattended（<이유>）를 표시합니다(critique/preview의 기존 DEGRADED 형식을 따르며, 두 번째 패턴을 도입하지 않음). 자발적 결정과 이유는 하나씩 디자인 설명에 기록합니다. 그림을 볼 수 없을 때는 "실제 시각적 효과를 확인하지 않음"이라고 명시하고, 시각적 점수를 부여하지 않습니다. 실행 가능한 환경이 없으면 상호 작용이 통과되었다고 말하지 않습니다. 사용자가 돌아오면 의견에 따라 수정하며, 수정은 의사 결정 재작성을 따릅니다.
약한 런타임 및 교차 에이전트 저하
이전 섹션과 상호 보완적입니다: 무인 상태 표는 사용자 부재 축을 관리하고, 이 표는 실행 능력 축(하위 에이전트 없음 / 비주류 모델 / 작은 컨텍스트 런타임)을 관리합니다.
긴박 정도에 따라 단계적으로 저하되며, 저하는 프로세스를 희생하지만 하드 제약 조건(a11y 검사, 토큰 참조, G01–G46 CRITICAL 게이트, 실제 자산 프로토콜 면제 불가)은 희생하지 않습니다:
- explore 다중 방향 병렬 실행 → 직렬 실행: 각 방향 시작 전에 DESIGN.md 계약과 자신의 방향 카드만 읽고, 이미 수행된 방향은 참조하지 않습니다.
- 여전히 긴박함 → 주 방향 1개 전체 사양 + 나머지 방향은 가벼운 카드(방향 카드 7개 칸 + 첫 화면 골격만 작성), 비교 페이지는 방향 카드를 나란히 배치하는 것으로 저하됩니다.
- references는 현재 하위 명령어의 "메타 문서 로드 타이밍" 필독 열만 읽고, 전체를 읽지 않습니다.
- draw-md 대량 페이지는 먼저 P0 페이지를 제출하고(default-pages 참조), 나머지 페이지는 방향 확인 후 배치로 처리합니다.
- 체크포인트 질문은 산출물 내의 가정 목록으로 대체합니다(gate 파일과 체크포인트 저하 의미는 이전 섹션과 동일하며, 둘 다 공유함).
버전 확인
이 섹션에서는 사용자가 maliang 스킬에 새 버전이 있는지 알 수 있게 합니다. 결정적 로직(스로틀 판단 / 버전 비교 / 기록)은 scripts/version-check.py에 있으며, 상태 파일은 기본적으로 ~/.maliang/version-check입니다(--state로 변경 가능). 에이전트는 명령어와 git ls-remote만 실행합니다.
이 스킬을 사용할 때 먼저 python3 {SKILL_DIR}/scripts/version-check.py due를 실행합니다. 출력이 skip:*이면 이 섹션을 건너뜁니다. 출력이 due이면:
git -C {SKILL_DIR} ls-remote --tags --refs --sort=-v:refname origin 'v*'를 실행하고, 첫 번째 태그 줄을python3 {SKILL_DIR}/scripts/version-check.py compare <tag>에 전달합니다(--current는 기본적으로 이 저장소의 SKILL.md frontmatter를 읽음).compare출력이same이면(태그가 vX.Y.Z 형식과 일치하지 않는 경우를 포함하여 태그가 없는 것으로 처리) 언급할 필요가 없습니다. 출력이newer이면 먼저 사용자의 작업을 완료하고, 마지막에 사용자에게 "maliang에 새 버전 vX.Y.Z가 있습니다. 업데이트는 https://github.com/Kirky-X/maliang/releases 를 참조하세요. 필요시git -C {SKILL_DIR} pull --ff-only를 실행하세요. 더 이상 알림을 받지 않으려면python3 {SKILL_DIR}/scripts/version-check.py record off를 실행하세요."라고 알려줍니다.- 조회 결과와 관계없이 실제 결과로 마무리합니다:
python3 {SKILL_DIR}/scripts/version-check.py record ok(조회 성공) 또는record failed(네트워크 끊김/샌드박스 네트워크 차단, 7일 후 재시도).
업데이트 여부는 사용자가 결정하며, 자동으로 업데이트를 실행하거나 파일을 다운로드하지 않습니다.
메타 문서 로드 타이밍(단계 × 필독)
규범 계층 references/meta/는 한 번에 모두 읽을 필요가 없습니다. 현재 단계에 따라 로드하며, 계획 작업은 실행 단계 문서를 로드하지 않습니다:
| 단계(하위 명령어) | 작업 전 필독 | 필요 시 참조 |
|---|---|---|
| design-md(시스템 생성) | product-reasoning.md, philosophy.md(Phase 1 prose 전 필독), principles.md, ux-laws.md(법칙 계층 "왜") | token-provenance.md(Phase 0d 의사 결정 테이블 + 토큰 출처), dials.md, spec-schema.md, analytics-events.md(추적 이벤트 테이블), content-guide.md, templates/README.md(선택 4단계), data-floor.md(데이터 유형 제품 Phase 0a 필수 통과: 바인딩 테이블+콜드 스타트 대사), workbench-structures.md(11가지 구조 판단) |
| redesign(개선) | ai-tells.md, rules-priority.md | dials.md, accessibility.md, surface-modes.md, ux-rules.md |
| explore(방향 미정 다중 방안 비교) | dials.md, surface-modes.md, token.md | ai-tells.md(면제 총칙), ux-rules.md, workbench-structures.md(데이터 유형 인터페이스 발산 전 주/하위 구조 판단); 작업 시작 전 python3 {SKILL_DIR}/scripts/style-ledger.py check(프로젝트 간 외관 원장, 중복 배경색/글꼴 패밀리를 능동적으로 회피, 차단하지 않음) |
| draw-md(페이지 사양 생성) | token.md, ai-tells.md | surface-modes.md, visual-assets.md, copy-strategy.md(Persuade 페이지 카피 전략), templates/INDEX.md, ux-rules.md, llm-behavior.md(긴 산출물 잘림 방지), performance.md, alignment.md(정렬 축/동일 행 높이, G44/G45), workbench-structures.md(단계 2.7 구조 판단), data-floor.md(단계 2.7 데이터 베이스 바인딩 테이블), app-screen-floor.md(Operate/Data 모드 데이터 스크린 플로어); 작업 시작 전 python3 {SKILL_DIR}/scripts/style-ledger.py check(프로젝트 간 외관 원장, 차단하지 않음) |
| preview(검증 전달) | numbered-gates.md(번호 게이트 G01–G46, 전달 여부 결정 계층), ai-tells.md(면제 총칙), performance.md | token-provenance.md(A 그룹 출처 판단 흔적 남기기), ux-rules.md, accessibility.md, content-guide.md, hardening.md(프로덕션 강화) |
| critique(사용성 심층 평가) | surface-modes.md, principles.md | accessibility.md, ux-rules.md, day-two-blacklist.md(네 번째 질문·정의 수준 audit) |
| draw-harmony/flutter/element | performance.md, accessibility.md, polish-craft.md(미세 조각 기술, 대부분 항목 web-only) | token.md(명명 역채움), ux-rules.md |
| ip / ip-handbook | product-reasoning.md | content-guide.md |
메타 규칙:
rules-priority.md와philosophy.md는 전 단계 판결 계층이며, 충돌 시 각 단계 문서보다 우선합니다.lifecycle.md는 전체 수명주기 전체 그림입니다(7단계 × 매체 × 체크포인트).theory-router.md는 이론 판단 보조 계층(자동 단계 판단 + 단계×이론 모델 패키지 + 트리거 조건 + 복합 규칙)이며, 모든 단계에서 이론 모델 추론/귀인/설득이 필요할 때 필요 시 로드합니다. 상세 계층design-theory-models.md는 앵커 포인트로만 조회하고 전체를 읽지 않습니다.llm-behavior.md는 산출물이 2화면을 초과하는 긴 문서에서 필독입니다.
일반 사항
- 어느 것을 사용할지 확실하지 않습니까? 먼저
design-md를 사용하세요. DESIGN.md가 없으면 안정적인draw-md하드 토큰을 생성할 수 없으며, 프레임워크 적응도 불가능합니다. - 전체 프로세스 링크(각 단계의 산출물 = 다음 단계의 입력):
design-md(→.maliang/DESIGN.md) →draw-md(→.maliang/ui-markdown/.md) →preview(→.maliang/preview/preview_.html) →critique(→평가 스냅샷) →draw-harmony/draw-flutter/draw-element(→프레임워크 코드); 반복은redesign/ui-graph를 통해 decisions 원장으로 환류됩니다. - 차원 규범(색상 / 글꼴 / 이미지 / 간격 / 모서리 / 선 / 레이아웃 / 정렬 / 표고)은
references/dimensions/아래에 있습니다(색상 팔레트 라이브러리 color-palettes, 참조 디자인 시스템 design-systems, 리퀴드 글라스 레시피 glass-effect/glass-advanced, 텍스처 예산 texture(페이지당 하나의 텍스처 패밀리/투명도 토큰화), 표면 표고 elevation, 정렬 축/동일 행 높이/볼록 관계 alignment, H5 모바일 전용 페이지 컨테이너 계약 h5-frame). 디자인 원칙은references/meta/principles.md에 있으며, 열세 개의 하위 명령어가 공유하는 참조로, 이 라우터에서 반복하지 않습니다. 데스크톱 페이지를 모바일로 가져갈 때의 여섯 가지 기계적 오류는references/meta/mobile-floor.md를 참조하세요. - 템플릿 벽은
references/templates/에 있습니다: 14가지 디자인 언어(리퀴드 글라스/M3 Expressive/Fluent 2/Bento/스위스 편집/OLED 다크/데이터 대시보드 등) + 전체 페이지 모드(편집 분할/심층 갤러리/Dashboard 스타일 세트/모바일 5가지 유형/스크롤 이미지 스트립/AI 워크벤치) + 랜딩 페이지 편곡 + 성격 방향 카드; 선택은 README 4단계 라우팅 + variation-engine 7축 조합 + 빌드 간 구성 기억(build-log + CSS 스탬프, ≥5축 동일 시 재선택). - 전달물 골격 템플릿은
template/에 있습니다: DESIGN.md 골격 / ui-markdown 페이지 골격 / IP 프롬프트 계약 / A11y 실제 측정 기록, 복사하여 채우기용. 골격의 유일한 정규 형식은 각 파일에 있으며, 채우기 방법과 검증 규칙은 해당 하위 명령어 문서에 있습니다. 템플릿 벽과의 분업(선택 참조 vs 기록 시작점)은template/README.md를 참조하세요. - 용어 라이브러리는 [
ref
…
[번역을 위해 잘림]