hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-uiux-design
hyper-uiux-design
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.ko.md | markdown | 25.6 KB |
| SKILL.md | skill md | 23.0 KB |
| assets/evals/hyper-uiux-design-cases.jsonl | other | 23.1 KB |
| references/html-match.ko.md | markdown | 13.5 KB |
| references/html-match.md | markdown | 12.2 KB |
| references/mockup-brief.ko.md | markdown | 11.6 KB |
| references/mockup-brief.md | markdown | 10.3 KB |
| references/reference-sites.ko.md | markdown | 8.5 KB |
| references/reference-sites.md | markdown | 7.3 KB |
| references/review-checklist.ko.md | markdown | 9.1 KB |
| references/review-checklist.md | markdown | 8.3 KB |
| references/visual-quality-recipe.ko.md | markdown | 22.5 KB |
| references/visual-quality-recipe.md | markdown | 20.9 KB |
| rules/mockup-is-evidence.ko.md | markdown | 9.0 KB |
| rules/mockup-is-evidence.md | markdown | 8.2 KB |
| rules/mockup-workflow.ko.md | markdown | 16.0 KB |
| rules/mockup-workflow.md | markdown | 14.2 KB |
| rules/reference-use.ko.md | markdown | 8.6 KB |
| rules/reference-use.md | markdown | 7.3 KB |
references/html-match.ko.md
View on GitHub# HTML 일치 단계
승인된 시안(또는 사전 승인된 시안) 뒤, 인계 전에 이 문서를 읽습니다. 시안이 HTML 화면 한 장이 되는 방법, "시각적으로 같다"를 판정하는 기준, 어떤 경우 HTML을 다시 고치는지를 정합니다.
시안은 화면의 증거입니다. HTML은 시안 그 자체를 마크업으로 옮긴 화면이고, 사용자가 브라우저에서 직접 엽니다. 이 단계가 필요한 이유는 그림이 제품 표면이 되지 못하기 때문입니다. 그림은 눌리지 않고, 크기를 바꿀 수 없고, 화면 읽기 프로그램이 읽지 못합니다.
## 목차
1. 이 단계의 산출물
2. HTML의 강제 규칙
3. 시안에서 마크업으로
4. "같다"의 판정 기준
5. 불합격 신호
6. 비교 반복
7. 인계 변경 사항
## 1. 이 단계의 산출물
화면 하나당 파일 하나, `.hyper/uiux-design/<slug>/html/<screen>.html`. 한 문서에 화면 전체가 들어갑니다.
| 들어가는 것 | 들어가지 않는 것 |
|---|---|
| 의미 있는 HTML, 화면당 `<main>` 하나 | 시안 이미지, 그 스크린샷, 그것을 옮겨 그린 배경 |
| 모든 CSS를 한 `<style>` 블록에 인라인 | 빌드 단계, 번들러, 프레임워크, npm 설치 |
| 모든 문자열은 실제 텍스트, 모든 아이콘은 인라인 SVG | 이미지로 그린 글자, CDN에서 받는 아이콘 폰트 |
| 스타일시트 맨 위의 토큰 블록(CSS 사용자 속성) | 렌더링 시점에 외부 호스트에서 받는 폰트·자산 |
| 브리프에 적은 고정 논리 뷰포트를 디자인 폭으로 사용 | 화면 전체를 절대 위치로 배치 |
시안 파일은 HTML 옆에 두고 노트에서만 참조합니다. 비교용 증거이고, 페이지 배경도, 실제 텍스트 아래 숨긴 `<img>`도 아닙니다.
## 2. HTML의 강제 규칙
1. **HTML 안에 화면 이미지를 넣지 않습니다.** 시안을 깔고 그 위에 실제 텍스트를 그리면 한 번의 스크린샷에서는 맞아 보이고 나머지 모든 면에서 틀린 페이지가 나옵니다. HTML에 시안이 들어 있으면 그 단계는 실패입니다.
2. **화면 하나당 독립 문서 하나.** 파일을 디스크에서 열면 서버 없이, 네트워크 없이, JavaScript 없이 화면이 그려져야 합니다. JavaScript는 브리프가 이름 붙인 상태(선택된 기간, 펼친 행)에만 쓰고 초기 레이아웃 구성에는 쓰지 않습니다.
3. **글자는 글자입니다.** 모든 문자열은 DOM 텍스트 노드입니다. 차트 축의 일부가 아니면 SVG `<text>`도 아니고, 아이콘에 구워 넣지도 않습니다.
4. **아이콘은 인라인 SVG로, 브리프의 아이콘 규칙대로 그립니다.** `viewBox` 하나, 선 굵기 하나, 역할별 크기 하나, `stroke="currentColor"`. 시안의 글리프가 지어낸 것이고 식별할 수 없으면 기하 도형으로 대체하고, 어떤 아이콘이 대체인지 노트에 적습니다.
5. **토큰 블록이 먼저 옵니다.** 페이지·표면·헤어라인·본문 1차·본문 2차·강조색·강조 틴트·위험색을 CSS 사용자 속성으로 두고, 이어서 활자 스케일·모서리·간격을 둡니다. 스타일시트의 모든 값은 토큰을 읽고, 같은 색이나 크기가 리터럴로 두 번 나오지 않습니다.
6. **레이아웃은 흐름이지 흐름의 그림이 아닙니다.** 플렉스나 그리드에 간격을 명시하고, 좌우 여백 토큰 하나를 모든 곳에 쓰고, 영역 사이 간격도 토큰에서 가져옵니다. 절대 위치는 배지·오버레이·장식 표시로 한정합니다.
7. **반응형은 한 방향으로만.** 브리프의 논리 폭이 디자인 폭입니다. 콘텐츠 열은 그 폭에서 멈추고 넓은 뷰포트에서는 가운데에 놓입니다. 모바일 화면을 데스크톱 레이아웃으로 늘리지 않고, 데스크톱 화면을 폰 열로 접지 않습니다.
8. **구조부터 접근성.** 실제 `<button>`·`<a>`·`<input>`·`<label>` 요소를 쓰고, 아이콘만 있는 컨트롤에는 `aria-label`을 붙이고, 포커스 링을 보이게 하고, 제목 단계를 시각 위계와 맞춥니다. 대비는 토큰에서 나오고 눈대중으로 조정하지 않습니다.
9. **라이브러리 냄새 금지.** 유틸리티 프레임워크 클래스, 기본 컴포넌트 스타일, 토큰에 없는 그림자·그라디언트를 쓰지 않습니다.
## 3. 시안에서 마크업으로
아래 순서대로 합니다. 각 단계는 시안에서 읽어 HTML에 쓰고, 토큰 표는 첫 마크업 줄보다 먼저 씁니다.
1. **토큰 표를 CSS 사용자 속성으로 복사합니다.** 브리프의 값이 계약이고, 이미지에서 잰 값은 계약이 아닙니다.
2. **영역 목록을 DOM 순서로 씁니다.** 위에서 아래로 영역 하나당 블록 요소 하나입니다. 그림에서 추측하지 않고 시안의 영역 목록을 씁니다.
3. **세로 리듬을 브리프의 간격으로 정합니다.** 좌우 여백, 그룹 간격, 행 높이, 영역 간격. 이 네 숫자가 닮은 인상의 대부분을 만듭니다.
4. **활자 스케일을 브리프대로 정합니다.** 가장 큰 요소, 영역 제목, 행 제목, 메타 순서입니다. 다섯 번째 크기를 만들지 않습니다.
5. **모든 문자열을 같은 위치, 같은 강조로 놓습니다.** 문자열은 이미지를 읽어 옮기지 않고 시안의 문구 목록에서 가져옵니다. 그래야 이미지의 틀린 음절이 HTML로 복사되지 않습니다.
6. **아이콘마다 인라인 SVG를 그립니다.** 브리프의 크기와 선 굵기로 그립니다.
7. **주 동작 하나를 마지막에 만듭니다.** 강조색이 꽉 찬 상태로 정확히 한 번만 나오게 하려는 것입니다.
8. **브리프에 없는 것은 지웁니다.** "실감 나게" 하려고 넣은 구분선·배지·캡션은 보너스가 아니라 불일치입니다.
시안의 렌더링된 글자는 문구의 출처가 아닙니다. 출처는 브리프의 문구 목록입니다. 이미지가 틀린 음절을 보이면 HTML은 맞는 음절을 담고, 노트에 그 둘이 의도적으로 다른 자리를 적습니다.
## 4. "같다"의 판정 기준
일치는 픽셀 비교가 아니라 구조와 리듬으로 판정합니다. 그림이 확정할 수 없는 것(정확한 간격, 글꼴 계측, 이미지 내용)은 토큰과 브리프가 확정합니다.
| 밴드 | 비교 대상 | 통과 조건 |
|---|---|---|
| 프레임 | 뷰포트 비율, 좌우 여백, 세이프 에어리어 | 같은 비율, 같은 좌우 여백 토큰, 프레임 가장자리에 닿는 요소 없음 |
| 상단 | 상태 표시줄 또는 내비게이션 바, 제목, 동작 글리프 | 같은 항목이 같은 순서, 동작은 최대 하나, 제목은 브리프 크기 |
| 히어로 | 가장 큰 요소와 그 캡션·델타·배지 | 같은 요소가 가장 크고, 브리프의 크기 비율을 지키고, 같은 캡션 줄 수 |
| 콘텐츠 그룹 | 그룹 헤더, 행 수, 행 구조 | 첫 뷰포트의 그룹 수·행 수가 같고, 행마다 같은 부품이 같은 순서(아이콘 타일, 두 줄 텍스트, 끝 값) |
| 리듬 | 그룹 간 간격, 행 높이, 정렬 선 | 모든 간격이 자기 토큰과 일치, 두 텍스트 열은 왼쪽 선 하나, 숫자 열은 오른쪽 선 하나를 공유 |
| 활자 | 네 단계 스케일, 굵기 | 여분 크기 없음, 가장 큰 요소와 본문의 비율이 브리프와 일치 |
| 색 | 강조색 개수, 표면 채움, 헤어라인 | 꽉 찬 강조색 하나, 그룹당 틴트 표면 최대 하나, 헤어라인은 브리프가 둔 곳만 |
| 하단 | 탭 바 또는 고정 동작, 선택 상태 | 같은 항목, 같은 활성 항목, 활성 상태는 모양과 색으로 함께 표시 |
| 콘텐츠 | 모든 문자열·금액·건수·날짜 | 모든 문자열이 있고 철자가 맞고, 숫자 합이 여전히 맞음 |
밴드 하나라도 실패하면 화면을 다시 고칩니다. 여덟 밴드를 통과하고 리듬에서 실패하면 불합격입니다. 리듬이 같은 화면으로 읽히게 만드는 요소이기 때문입니다.
## 5. 불합격 신호
눈으로 보기에 가까워도 아래 중 하나면 불합격입니다.
| 신호 | 실패인 이유 |
|---|---|
| 페이지에 시안 이미지나 그 일부가 있음 | 레이아웃이 마크업이 아니라 그림이고, 그림 아래는 아무것도 실제가 아님 |
| 간격 값 하나를 모든 곳에 씀(예: 전부 16px) | 시안의 묶음이 사라짐. 생성된 페이지의 가장 흔한 표식 |
| 토큰에 없는 그라디언트·글로우·그림자·블러 | 브리프에 없고, 기계가 만든 장식으로 읽힘 |
| 모든 영역이 가운데 정렬이거나 모든 카드가 같은 무게 | 위계 없음. 시선이 처음 멈출 곳이 없음 |
| 세 요소 이상에서 브리프와 다른 글자 크기 | 스케일을 읽지 않고 눈대중한 것 |
| 역할 안에서 선 굵기나 크기가 섞인 아이콘 | 아이콘 세트 하나가 핵심인데 조립한 것으로 읽힘 |
| 아이콘 자리에 이모지 | 아이콘이 아니고 플랫폼마다 다르게 렌더링됨 |
| 자리표시자 문자열, `Lorem`, `Item`, `00,000`, 콘텐츠 자리의 빈 상자 | 시안의 콘텐츠 규칙을 산출물에서 어긴 것 |
| 일러스트나 사진 자리에 둥근 사각형 | 자산이 필요하다고 말해야 함. 회색 블록을 그리지 않음 |
| 꽉 찬 강조색이 둘 이상이거나 주 동작이 아닌 요소의 강조색 | 색 규율이 설계된 화면의 가장 싼 신호 |
| 글자를 담는 컨테이너의 고정 픽셀 높이 | 다른 글꼴에서 넘치거나 잘림. `min-height`와 여백을 씀 |
| 요청하지 않은 모션·캐러셀·애니메이션 | 범위 밖이고, 깨진 정적 상태를 가림 |
| 정지 상태에서 페이지 스크롤바가 생기거나 시안에 없는 하단 잘림 | 뷰포트 계산이 틀린 것 |
## 6. 비교 반복
1. **렌더링하고 캡처합니다.** 브리프의 논리 뷰포트로 브라우저에서 HTML을 열고, 시안의 원본 크기와 같은 배율로 스크린샷을 찍습니다. 두 파일 경로를 기록합니다.
2. **§4의 밴드 순서대로 비교하고 차이 목록을 씁니다.** `밴드 — 무엇이 다른가 — 고칠 토큰 또는 브리프 값` 한 줄씩, 묶지 않습니다.
3. **목록에 순위를 매깁니다.** 리듬과 콘텐츠, 그다음 위계, 그다음 색, 그다음 아이콘 디테일. 가장 높은 항목 하나만 고칩니다.
4. **그림이 아니라 HTML을 고칩니다.** 토큰이나 규칙을 바꾸고, 이미지에서 잰 값에 맞추려고 값을 밀지 않습니다.
5. **다시 렌더링하고 다시 비교합니다.** 최대 세 번 반복합니다.
6. **멈춥니다.** 차이 목록이 비었거나 상한에 닿았을 때입니다. 상한에서 멈추면 차이 목록이 가장 짧은 시도를 남기고, 남은 차이를 전부 노트에 적습니다. 간격 차이로 상한에 닿은 화면은 일치가 아니라 그 차이로 보고합니다.
반복마다 기록합니다. 회차 번호, 고치기 전후의 차이 개수, 바꾼 것 하나. 한 번에 세 가지를 바꾼 회차는 비교로 치지 않습니다.
## 7. 인계 변경 사항
이제 인계는 산출물 두 개를 담고 어느 쪽이 무엇인지 밝힙니다.
| 부분 | 내용 |
|---|---|
| 시안 이미지 | 레이아웃과 밀도의 증거일 뿐. 넣지도, 따라 그리지도, 출시하지도 않음 |
| HTML | 화면 그 자체. 파일 하나, 디스크에서 열림. 실제 구현의 출발점 |
| HTML이 아닌 것 | 운영 코드가 아님: 데이터 계층 없음, 라우팅 없음, 브리프가 이름 붙인 것 외의 상태 없음, 빌드 통합 없음 |
| 토큰 블록 | CSS 사용자 속성에서 그대로 뽑아낸 값. 프로젝트 자체 테마의 계약 |
| 남은 차이 | 상한 이후에도 실패하는 밴드 전부와 그것을 닫을 토큰 |
| 아이콘 목록 | 브리프가 이름 붙인 글리프와 기하 대체 중 무엇인지 |
구현자는 토큰과 HTML을 참조 구현으로 받습니다. 그림과 HTML이 어긋나면 토큰이 이깁니다.
## Sources
> Checked 2026-11-15.
| Claim | Source |
|---|---|
| HTML 단계, 화면당 독립 파일 하나, 시안 이미지 삽입 금지, 실제 텍스트와 인라인 SVG, 토큰 블록, 비교 상한 | user instruction, 2026-11-15 (approved mockup becomes HTML that matches it) |
| 영역 목록을 DOM 순서로, 네 가지 리듬 숫자, 네 단계 활자 스케일, 주 동작 하나 | 이 패키지의 브리프 규칙을 마크업용으로 다시 쓴 것 |
| 일치 판정이 점검하는 좌우 여백·그룹 간격·카드 묶음·행 구조·활자 비율 범위 | 2026-11-15에 읽은 공개 화면 목록에서 이 패키지가 뽑아낸 합성이며, 측정된 플랫폼 요구가 아닌 기본값. `.hyper/uiux-design/html-2026-11-15/ref-log.md` 참조 |
| 토큰에서 계산한 텍스트 대비, 보이는 포커스, 색만으로 전달하지 않는 상태 | <https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html>, <https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html> |
| 간격 값 미분화, 장식적 그라디언트 같은 생성 페이지 표식 | 이 패키지가 `.hyper/uiux-design/html-2026-11-15/`에 기록한 비교 회차에서 관찰한 것 |
### 근거 등급
강제 규칙, 밴드 목록, 불합격 신호, 세 번 상한은 `LOCAL`입니다. 제작 기본값(좌우 여백, 행 구조, 활자 비율)은 공개 앱 여러 개에서 공통으로 보이는 것을 이 패키지가 합성한 값이고, 공개된 표준이 아닙니다. WCAG 기준은 `PRIMARY`입니다.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |