Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-uiux-design

hyper-uiux-design

Verified

Use this skill when the user asks to design an app or web screen and wants both a picture of it and the screen as HTML before real code - a login, onboarding, dashboard, or checkout screen, or a short flow of screens, for mobile, tablet, or web, in light or dark. It reads public UI references (UIBowl, Mobbin public pages) for patterns, settles tokens, has hyper-imagegen render one mockup image per screen, then builds one standalone HTML file per screen that matches that mockup, checks the match with a browser screenshot, and saves both with handoff notes under `.hyper/uiux-design/[slug]/`. Do not use it for one image that is not a product screen, a visual-direction brief or audit, production frontend or native code, or a requirements document.

rules/mockup-workflow.ko.md

View on GitHub
# 시안 워크플로

토큰을 정하거나 브리프를 쓰기 전에 이 규칙을 읽습니다. 범위 확정부터 승인까지의 작업 순서, 누가 이미지를 렌더링하는지, 화면 하나를 몇 번까지 재생성할 수 있는지, 메모 파일에 무엇을 담는지를 정합니다.

## Contents

1. 범위와 모드
2. 토큰 먼저
3. 패턴에서 브리프로
4. 생성
5. 검토
6. 재생성 상한
7. 화면 세트와 테마
8. 승인과 인계
9. 메모 파일

## 1. 범위와 모드

무엇보다 먼저 요청과 프로젝트에서 네 가지를 확정합니다.

| 항목 | 값 | 밝히지 않았을 때 기본값 |
|---|---|---|
| 화면 | 이름이 나온 화면이나 흐름의 단계 | 요청에 화면이 없으면 질문 |
| 플랫폼 | `mobile`, `tablet`, `web` | 프로젝트의 플랫폼. 프로젝트에서 알 수 없으면 질문 |
| 테마 | `light`, `dark`, `both` | 프로젝트의 기본 테마, 없으면 `light` |
| 모드 | `screen`, `set`, `revise` | 화면 하나는 `screen`, 두 개에서 여섯 개는 `set` |

세트는 한 번 실행에 화면 여섯 개까지입니다. 더 큰 흐름은 나눕니다. 첫 실행은 흐름을 이끄는 화면 여섯 개를 다루고, 메모에 나머지를 아직 그리지 않았다고 나열합니다.

## 2. 토큰 먼저

토큰이 있기 전에는 브리프를 쓰지 않습니다.

1. 프로젝트에서 디자인 문서와 토큰 출처를 찾습니다. `DESIGN.md`, 테마 파일, CSS 사용자 정의 속성, Tailwind나 디자인 토큰 설정, 네이티브 테마 파일이 해당합니다. 찾으면 해당하는 값을 옮기고 어느 파일에서 왔는지 기록합니다.
2. 아무것도 없으면 [../references/mockup-brief.ko.md](../references/mockup-brief.ko.md) §4의 최소 토큰 세트인 색, 글꼴, 모서리, 간격을 정합니다. 메모에 `provisional`로 표시하고, 시안의 일관성을 지키려고 만든 값이며 사용자가 바꿀 수 있다고 적습니다.
3. 쓰기 전에 토큰 세트의 모든 글자와 배경 쌍의 대비를 계산합니다([mockup-is-evidence.ko.md](mockup-is-evidence.ko.md) §4). 실패한 쌍은 브리프가 아니라 토큰에서 고칩니다.
4. 테마가 `both`면 두 토큰 열을 이때 모두 정합니다.

최소 토큰은 일관성을 위한 바닥입니다. 브랜드 정체성, 분위기, 온전한 시각 방향은 더 큰 결정이므로 여기서 지어내지 않습니다. 사용자가 그것을 원하면 별도 산출물이라고 말하고, 사용자가 동의할 때만 임시 세트로 계속합니다.

## 3. 패턴에서 브리프로

1. 출처 기록에서 패턴 요약을 씁니다([reference-use.ko.md](reference-use.ko.md) §5). 구조, 위계, 간격, 컴포넌트, 흐름입니다.
2. 화면마다 위에서 아래로 영역, 주 동작 하나, 컴포넌트를 정하고 각 선택이 어느 패턴 서술을 따르는지 적습니다.
3. [../references/visual-quality-recipe.ko.md](../references/visual-quality-recipe.ko.md) §5에서 화면 유형을 고르고 그 영역 순서에서 시작합니다. 기대 요소 수(§7)를 적어 두어 브리프가 요소 부족으로 돌아오지 않게 합니다.
4. 브리프를 쓰기 전에 완성 콘텐츠를 먼저 씁니다. 헤드라인 숫자, 모든 행의 이름·건수·금액·비중, 날짜, 이름, 섹션 개수입니다. 앞뒤를 맞춥니다. 요소마다 한 줄씩 배정해 전부 씁니다.
5. [../references/mockup-brief.ko.md](../references/mockup-brief.ko.md) §3의 뼈대로 브리프를 씁니다. 브리프에는 토큰 값, 콘텐츠가 인라인으로 들어간 영역 목록, 모든 문자열, 캔버스를 싣습니다. 제품 이름, 레퍼런스 URL, 모델 이름은 싣지 않습니다.
6. 호출 전에 콘텐츠 규칙을 점검합니다. 브리프를 열어 화면의 어떤 자리도 막대, 블록, 라벨 없는 도형에 맡겨지지 않았는지 확인합니다. 브리프에 살아남은 막대는 이미지에도 살아남습니다([../references/visual-quality-recipe.ko.md](../references/visual-quality-recipe.ko.md) §2).
7. 호출하기 전에 이미지가 통과해야 할 점검을 [../references/review-checklist.ko.md](../references/review-checklist.ko.md)에서 골라 적습니다.

## 4. 생성

모든 이미지는 hyper-imagegen이 만들고, 브리프 하나에 이미지 하나입니다.

없다고 판단하기 전에 이미지 도구를 아래 순서로 찾고, 어느 단계에서 찾았는지 기록합니다.

1. 이 세션에 이미 노출된 런타임 도구.
2. 이 런타임에 설정된 MCP 서버. 로컬에서 도는 이미지 서버도 포함합니다. 설정은 됐지만 세션에 노출되지 않은 서버도 런타임이 닿을 수 있으면 쓸 도구입니다.
3. 두 단계 뒤에만 대체 경로로 가고, 메모에 어느 대체 경로를 썼는지 적습니다.

"이미지 도구가 없다"고 결론 내고 코드로 렌더링했지만 같은 기기에서 이미지 서버가 응답하고 있던 세션이, 이 순서가 막으려는 실패입니다.

2단계가 어떤 모습인지는 런타임 사실 두 가지가 정하고, 둘 다 가정하지 않고 확인합니다.

- **세션이 시작된 뒤에 켠 서버는 이 세션의 도구 목록에 없습니다.** 라이브러리와 세션의 도구 목록은 다른 것입니다. 런타임에 서버를 켜도 실행 중인 세션에 그 도구가 소급해서 생기지 않습니다. 아무것도 단정하기 전에 런타임의 MCP 관리자가 제공하는 명령으로 서버 목록을 다시 확인하고, 세션에 노출된 도구도 다시 확인합니다.
- **그래도 런타임 자체의 MCP 엔드포인트는 닿습니다.** 런타임의 MCP 서버들을 앞에 두는 게이트웨이 프로세스가 세션 라우팅도 맡는다면, 그 엔드포인트로 JSON-RPC를 보내면 같은 서버가 뜨고 같은 도구가 돕니다. API 키 스크립트가 아니라, 같은 서버를 런타임이 이미 가진 같은 자격 증명으로 한 계층 아래에서 부르는 것입니다. 어느 엔드포인트가 응답했고 무엇이 돌아왔는지 기록합니다.

절대 안 되는 것은 이미지 단계를 직접 쓴 렌더링 경로로 대체하는 것입니다. 엔드포인트가 거부하면 종료 상태는 스킬이 정한 그 값이고, 무엇이 왜 거부했는지 메모에 적습니다.

- 브리프를 요청으로 넘기고, 캔버스는 프롬프트 글 안이 아니라 이미지 스킬의 구조화된 캔버스 값으로 넘깁니다.
- 모델 이름을 대거나 고르지 않습니다. 이미지 스킬의 기본값과 그 자체 호출 상한, 종료 상태를 그대로 따릅니다.
- 브리프마다 이미지 스킬이 보고한 내용을 기록합니다. 종료 상태, 호출 횟수, 저장 경로나 반환 산출물 기록, 다이제스트가 있으면 다이제스트입니다.
- 반환된 픽셀 크기를 기록하고 요청 비율과 비교합니다. 다르면 메모에 한 줄을 씁니다. 요청한 비율, 돌아온 크기, 그리고 프레임은 예시이고 브리프의 논리 프레임이 계약이라는 점입니다. 비율을 억지로 맞추려고 이미지를 자르거나 크기를 바꾸지 않습니다.
- 이미지 도구가 없어서 `prompt_saved`나 `blocked`로 끝난 것은 이 스킬의 실패가 아닙니다. 브리프를 메모에 남기고 `briefs_saved`로 끝냅니다. 스스로 API 키, 유료 엔드포인트, 다른 도구로 바꾸지 않습니다.
- 반환된 이미지에 글자를 편집하지 않고 이미지를 합성하지 않습니다. 잘못된 이미지에는 수정한 브리프로 답합니다.

## 5. 검토

반환된 이미지는 사용자에게 후보로 보이기 전에 [../references/review-checklist.ko.md](../references/review-checklist.ko.md)로 검토합니다. 검토는 브리프 충실도, 가독성, 생성 이미지 티, 접근성, 세트 일관성, 레퍼런스 독립성을 다룹니다. 항목마다 `pass`, `fail`, `not checkable in an image` 중 하나를 [mockup-is-evidence.ko.md](mockup-is-evidence.ko.md) §1의 라벨과 함께 기록합니다.

`fail`인 항목이 없을 때 이미지는 후보입니다. 이미지에서 확인할 수 없는 항목은 통과가 아니라 인계 요구사항이 됩니다.

## 6. 재생성 상한

- 화면·테마당 브리프는 최대 세 개입니다. 첫 브리프와 수정 두 번입니다.
- 수정은 한 가지만 바꾸고, 무엇을 바꿨는지 밝히고, 모든 불변 요소를 다시 적습니다. 적지 않은 불변 요소는 흔들리기 때문입니다.
- 전달 뒤에 사용자가 요청한 변경은 자체 상한을 가진 `revise` 실행으로 시작합니다.
- 서로 독립적인 결함이 둘 있는 화면도 브리프당 한 가지 변경입니다. [../references/review-checklist.ko.md](../references/review-checklist.ko.md) §9의 검토 순서로 결함 순위를 매겨 가장 앞선 것을 먼저 고칩니다. 두 번째 결함은 상한 안에서 브리프를 받지 못할 수 있고, 그것은 정상입니다.
- 세 번째 브리프 뒤에는 실패 항목이 가장 적은 시도를 남기고 남은 `fail`을 id와 메모와 함께 전부 나열합니다. 남은 실패가 사용자의 취향 문제뿐이면 `awaiting_approval`로 끝냅니다. 시도와 실패 항목 목록을 함께 보여 줍니다. 영역 누락이나 상한 때문에 고치지 못한 읽을 수 없는 위계처럼 남은 실패가 구조적일 때만 `blocked`로 끝냅니다.
- 메모에는 채택한 시도가 아직 실패하는 점검을 명확히 적습니다. 상한에 닿은 화면에 틀린 음절이 둘 있으면 둘이라고 적고 통과라고 적지 않습니다.
- 완벽한 이미지를 좇아 반복하지 않습니다. 레이아웃과 위계와 밀도를 보여 주는 시안은 제 몫을 다한 것입니다.

## 7. 화면 세트와 테마

- 불변 요소 블록을 한 번 쓰고 세트의 모든 브리프에 글자 그대로 반복합니다. 토큰 값, 글자 처리, 컴포넌트 모양, 아이콘 스타일, 시스템 바 처리, 캔버스가 들어갑니다.
- 공통 컴포넌트가 가장 많이 나오는 기준 화면을 먼저 생성합니다. 검토하고, 사용자가 자리에 있으면 보여 줍니다. 나머지는 기준 화면이 후보가 된 뒤에만 생성합니다.
- 화면에 필요한 것만 바꿉니다. 영역, 문자열, 주 동작입니다.
- 다크 버전은 별도 브리프와 이미지입니다. 토큰 열만 바꾸고 다른 것은 바꾸지 않으며, 라이트 기준 화면이 후보가 된 뒤에 생성합니다.
- 세트가 완성되면 체크리스트의 일관성 항목을 모든 이미지에 함께 적용합니다.

## 8. 승인과 인계

- 후보를 검토 표와 함께 보여 주고 승인이나 변경 한 가지를 요청합니다. 승인은 사용자의 몫입니다.
- 사용자가 미리 승인했으면 후보를 승인된 것으로 봅니다. 승인이 미리 주어졌다고 기록하고 그 요청을 인용합니다.
- 답이 없으면 `awaiting_approval`로 끝냅니다. 구현을 시작하지 않습니다.
- 승인되면 인계 섹션을 쓰고([mockup-is-evidence.ko.md](mockup-is-evidence.ko.md) §5) `approved`로 끝냅니다. 구현은 메모를 넘겨받는 별도 작업이고, 이 스킬은 인터페이스 코드를 쓰지 않습니다.

## 9. HTML 단계

시안이 승인되었고(또는 미리 승인되었고) 사용자가 여는 산출물이 HTML일 때입니다. 규칙, 일치 밴드, 불합격 신호는 [../references/html-match.ko.md](../references/html-match.ko.md)가 소유하고, 이 절은 순서와 인계를 소유합니다.

1. **첫 HTML 줄 전에 일치 참조를 읽습니다.**
2. **그림이 아니라 브리프로 만듭니다.** 토큰 표, 영역 목록, 문구 목록은 이미 쓰였고 이미 합의됐습니다. HTML은 그것을 복사합니다. 그림에서 잰 값은 출처이고 복사하는 순간 화면이 자기 계약에서 벗어납니다.
3. **화면당 파일 하나**, `.hyper/uiux-design/<slug>/html/<screen>.html`에 두고 디스크에서 엽니다. 시안은 옆에 두되 절대 넣지 않고, 배경도, 숨은 이미지도 아닙니다.
4. **실제 텍스트, 인라인 SVG 아이콘, 토큰 블록 먼저.** 렌더링 시점에 폰트, 아이콘, 이미지를 받아 오지 않습니다.
5. **브라우저에서 비교합니다.** 브리프의 논리 뷰포트로 열고, 시안의 원본 배율로 스크린샷을 찍고, 참조의 밴드 순서대로 비교합니다. 무엇이든 바꾸기 전에 차이 목록을 쓰고, 가장 높은 항목 하나만 고칩니다.
6. **최대 세 번 반복합니다.** 회차마다 번호, 고치기 전후 차이 개수, 바꾼 것 하나를 기록합니다.
7. **멈춥니다.** 차이 목록이 비었거나 상한에 닿았을 때입니다. 차이 목록이 가장 짧은 시도를 남기고 남은 차이를 전부 적고, 간격 차이가 남은 화면은 일치가 아니라 그 차이로 보고합니다.
8. **산출물 두 개를 넘깁니다.** 토큰 블록을 프로젝트 테마 계약으로, 아이콘 목록과 남은 차이를 함께 넘깁니다.

HTML 단계는 운영 구현이 되지 않습니다. 데이터 계층도, 라우팅도, 브리프가 이름 붙인 것 외의 상태도, 빌드 통합도 없습니다. 구현자는 토큰과 HTML을 참조로 받고 그다음부터는 구현자 몫입니다.

스크린샷을 찍을 브라우저가 런타임에 없으면 HTML을 쓰고 비교를 건너뛰며, 일치 점검을 건너뛴 사실과 이유를 기록하고 그 화면을 일치했다고 보고하지 않습니다.

## 10. 메모 파일

`.hyper/uiux-design/<slug>/mockup-notes.md`를 한국어로, 다음 순서로 씁니다.

1. 결과 요약 한 줄과 종료 상태.
2. 범위: 화면, 플랫폼, 테마, 모드.
3. 토큰과 그 출처(파일을 밝힌 `project` 또는 `provisional`), 계산한 대비.
4. 출처 기록과 저작권 안내. 사이트 약관을 읽지 못했으면 표준 문구를 씁니다: `약관 본문 확인 실패(이유), 공개 목록 범위만 사용`.
5. 패턴 요약과 각 패턴의 근거 강도.
6. 화면·테마마다: 브리프, 이미지 경로나 반환 산출물 기록, 이미지 스킬의 종료 상태와 호출 횟수, 돌아온 픽셀 크기와 옆에 적은 요청 비율, 검토 표, 시도 횟수, 화면이 보여 주는 모든 문자열을 센 `정확 n/m`.
7. 화면마다: HTML 경로, 아홉 밴드 전부의 일치 표, 회차별 차이 목록, 회차 수.
8. 승인 기록.
9. 인계. 토큰 블록, 아이콘 목록, 남은 차이를 포함합니다.
10. 가정과 하지 않은 것.

파일은 정확히 `Result:` 한 줄로 끝납니다. 이미지는 이미지 스킬이 둔 자리에 그대로 두고, 메모는 링크만 걸며 그 옆에 타사 화면을 복사해 두지 않습니다.

메모의 검토 표는 체크리스트 항목마다 한 행을 갖고, 절을 줄여 요약하지 않습니다. 열세 항목을 여섯 행으로 접은 표는 검토가 아니고, 콘텐츠 자리에 있는 막대를 숨깁니다.

## Sources

> Checked 2026-11-15.

| Claim | Source |
|---|---|
| 레퍼런스 조사부터 인계까지의 순서, 코드보다 시안 먼저, `DESIGN.md`나 최소 세트로 토큰 먼저, 한 화면과 화면 세트, 세 플랫폼, 라이트와 다크, 명시한 재생성 상한, 이미지 스킬과 그 기본 모델 | user instruction, 2026-11-15 (new skill request) |
| 이미지당 브리프 하나, 구조화된 값으로 넘기는 캔버스, 시리즈의 모든 브리프에 반복하는 공통 불변 요소, 한 가지만 바꾸는 수정, 렌더링된 글자 덧대기 금지, 요청 없이 API 키 경로로 바꾸지 않기 | this package's image-generation skill contract, restated for screens |
| HTML 단계 순서, 화면당 독립 파일, 그림이 아니라 브리프로 만들기, 브라우저 비교, 세 회차 상한 | user instruction, 2026-11-15; 규칙과 밴드는 [../references/html-match.ko.md](../references/html-match.ko.md) |

### Evidence grade

`LOCAL`: 세트의 화면 여섯 개 크기, 브리프 세 개 상한, 기준 화면 먼저라는 순서, HTML 비교 순서, 메모 구성은 이 패키지가 고른 절차이고 외부 측정값이 없습니다.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall