hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-frontend
hyper-frontend
VerifiedUse this skill when the user wants web frontend code built, fixed, matched to a visual reference, or checked in a rendered browser - a component, page, layout, form, animation, or responsive or state bug in HTML, CSS, JavaScript, React, Vue, Svelte, or Astro - where the job is how the interface is built to hold real content, keep one shape in every state, move safely, and be proven in a real browser. It builds inside the project's existing look, reads a concrete reference as a contract, and saves a report under `.hyper/frontend/[slug]/`. Do not use it for choosing or auditing the visual direction, project structure or tooling, native app UI, or reading a blocked page.
| File | Kind | Size |
|---|---|---|
| SKILL.ko.md | markdown | 16.2 KB |
| SKILL.md | skill md | 14.2 KB |
| assets/evals/hyper-frontend-cases.jsonl | other | 11.6 KB |
| references/reference-fidelity.ko.md | markdown | 4.5 KB |
| references/reference-fidelity.md | markdown | 3.9 KB |
| rules/layout-and-states.ko.md | markdown | 7.5 KB |
| rules/layout-and-states.md | markdown | 6.2 KB |
| rules/motion-and-interaction.ko.md | markdown | 5.2 KB |
| rules/motion-and-interaction.md | markdown | 4.5 KB |
| rules/rendered-verification.ko.md | markdown | 6.2 KB |
| rules/rendered-verification.md | markdown | 5.4 KB |
rules/layout-and-states.ko.md
View on GitHub# 레이아웃과 상태
마크업이나 스타일을 쓰거나 바꾸기 전에 이 규칙을 읽습니다. 인터페이스가 실제 콘텐츠를 담도록, 그리고 모든 상태에서 한 가지 모양을 유지하도록 짓는 방법을 정합니다. 색, 타입, 분위기는 정하지 않으며 프로젝트의 디자인 언어를 따릅니다.
## Contents
1. 스크롤 소유권
2. 조용히 실패하는 두 가지 계약
3. 반응형
4. 콘텐츠 스트레스
5. 상태 안정 컨트롤
6. 상태 매트릭스
## 1. 스크롤 소유권
레이아웃 스타일을 쓰기 전에 다음 세 가지 답을 보고서나 변경 설명에 적습니다.
- 이 영역에서 세로 스크롤을 소유하는 요소가 하나 무엇인지.
- 고정으로 남는 영역(헤더, 사이드바, 툴바, 푸터)이 무엇인지.
- 스크롤 컨테이너의 높이가 어디에서 제한되는지.
규칙은 다음과 같습니다.
- 영역마다 스크롤 컨테이너는 하나만 둡니다. 추가한 컨테이너에는 각각 이름 붙은 역할이 있어야 합니다. 역할 없는 중첩 스크롤바는 다음 제스처가 무엇을 움직일지 알 수 없게 만듭니다.
- 전체 높이 셸은 모바일 브라우저 크롬을 무시하는 `100vh` 대신 동적 뷰포트 단위(`100dvh`)로 제한합니다.
- 한 영역 안에서 문서 스크롤(`position: sticky`)과 자체 스크롤을 소유하는 셸 영역을 이유 없이 섞지 않습니다.
## 2. 조용히 실패하는 두 가지 계약
둘 다 실제 콘텐츠가 들어오기 전까지는 올바르게 보입니다.
**고정 셸 안의 스크롤 본문.** 그리드나 플렉스 자식은 기본값이 `min-height: auto`라서 콘텐츠보다 작게 줄지 않습니다. 그래서 본문이 스크롤되는 대신 푸터를 밀어냅니다. 스크롤하는 자식에 `min-height: 0`과 `overflow: auto`를 주고 셸의 높이를 제한합니다.
```css
.shell { display: grid; grid-template-rows: auto minmax(0, 1fr) auto; height: 100dvh; }
.shell__body { min-height: 0; overflow: auto; }
```
**미디어 쿼리 없이 적응하는 그리드.** 단순한 `minmax(16rem, 1fr)`는 12rem 컨테이너에서도 16rem 트랙을 강제합니다. 하한을 `min()`으로 제한해 트랙이 줄어들 수 있게 합니다.
```css
.grid { display: grid; gap: var(--gap); grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr)); }
```
## 3. 반응형
- 컴포넌트가 무엇에 반응하는지 먼저 묻습니다. 메인 열에서는 넓고 레일에서는 좁은 카드는 자기 너비에 반응하므로 컨테이너 쿼리를 씁니다. 페이지 프레임이 바뀔 때(사이드바 접힘, 열 감소)만 뷰포트 쿼리입니다.
- 브레이크포인트보다 고유 적응(줄바꿈하는 플렉스, 위의 그리드, `clamp()`)을 우선합니다. 브레이크포인트는 기기 이름이 아니라 전환하는 레이아웃 상태로 이름 붙입니다.
- 제품이 오른쪽에서 왼쪽으로 쓰는 글을 지원하면 논리 속성(`margin-inline`, `inset-inline-start`)을 써서 레이아웃이 대칭으로 뒤집히게 합니다.
- 한국어 등 CJK 글은 기본적으로 단어 안에서도 줄이 바뀝니다. 프로젝트 글이 한국어면 문단 컨테이너에 `word-break: keep-all`과 `overflow-wrap: anywhere`를 쓰고, 렌더된 줄바꿈을 확인합니다.
## 4. 콘텐츠 스트레스
모든 영역이 정상 경로의 목업이 아니라 실제 또는 현실적인 콘텐츠로 이 목록을 견디기 전에는 레이아웃이 끝난 것이 아닙니다.
| 스트레스 | 찾을 실패 |
|---|---|
| 비어 있음(행, 아바타, 값 없음) | 깨진 프레임, 무너진 영역, 홀로 남은 제목 |
| 긴 라벨(12자 자리에 40자 이름) | 넘침, 아무도 고르지 않은 잘림 |
| 긴 문단 | 읽기 좋은 길이를 한참 넘는 줄 길이 |
| 끊기지 않는 문자열(URL이나 토큰) | 가로 스크롤. `overflow-wrap: anywhere`와 플렉스 자식의 `min-width: 0`이 필요합니다 |
| 320 CSS px 너비 | 주요 콘텐츠의 가로 스크롤(WCAG 1.4.10). 본질적으로 2차원인 콘텐츠는 예외입니다 |
| 사용자 텍스트 간격 재정의 | 고정 높이 상자에서 글이 잘림(WCAG 1.4.12) |
| 많은 항목(수백 행) | 레이아웃 비용이나 입력을 멈추게 하는 가상화 없는 목록 |
## 5. 상태 안정 컨트롤
컨트롤은 모든 상태에서 상자를 하나로 유지합니다. 상태가 바뀌어도 너비, 높이, 패딩은 변하지 않습니다.
- 가장 긴 라벨의 자리를 그 라벨이 나타나기 전에 확보합니다. 가장 긴 상태 라벨 크기로 슬롯을 잡거나, 라벨을 바꾸지 말고 숨긴 라벨 위에 스피너를 겹칩니다.
- 나중에 도착하는 콘텐츠의 자리를 확보합니다. 고유 크기나 종횡비를 가진 이미지, 로드된 콘텐츠와 같은 크기의 스켈레톤, 검증 메시지 한 줄이 해당합니다. 누적 레이아웃 이동을 낮게 유지하는 방법이기도 합니다.
- 바뀌거나 정렬되는 숫자는 표 형식 숫자(tabular numerals)를 써서 자릿수가 이웃을 밀지 않게 합니다.
- 호버, 포커스, 활성 상태는 기하가 아니라 칠(색, 아웃라인, 그림자)을 바꿉니다. 포커스 링은 `outline`이나 그림자를 쓰고, 상자 크기를 바꾸는 테두리를 쓰지 않습니다.
## 6. 상태 매트릭스
컴포넌트나 화면을 완성했다고 말하기 전에 가능한 모든 상태를 나열하고 각각의 모양과 동작을 정의합니다.
- 컴포넌트: 기본, 호버, focus-visible, 활성, 비활성, 로딩, 오류, 성공, 선택됨.
- 데이터 기반 화면: 로딩, 비어 있음, 다시 시도 경로가 있는 오류, 부분 로드, 오래됨, 긴 콘텐츠가 있는 정상 경로.
- 폼: 초기, 수정됨, 검증 중, 레이아웃을 움직이지 않는 메시지가 붙은 무효, 제출 중, 제출됨. 제출에 실패해도 사용자가 입력한 값을 유지합니다.
제품에는 있지만 매트릭스에 없는 상태는 발견 사항입니다. 의도적으로 뺀 상태는 이유와 함께 기록합니다.
## Sources
> Checked 2026-11-09.
| Claim | Source |
|---|---|
| 플렉스·그리드 항목은 `min-height`를 주지 않으면 콘텐츠보다 작게 줄지 않음 | <https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/min-height> |
| 긴 문자열은 `overflow-wrap: anywhere`로 줄바꿈함 | <https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow-wrap> |
| 컴포넌트가 컨테이너 너비에 반응할 수 있음 | <https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries> |
| 320 CSS px에서 2차원 스크롤 없이 콘텐츠가 재배치됨 | <https://www.w3.org/WAI/WCAG22/Understanding/reflow.html> |
| 늦게 오는 콘텐츠의 자리를 확보하면 누적 레이아웃 이동이 낮게 유지됨 | <https://web.dev/articles/optimize-cls> |
| 텍스트 간격 재정의가 콘텐츠를 자르면 안 됨(1.4.12) | <https://www.w3.org/TR/WCAG22/> |
| 소유권 이름 붙이기, 스트레스 목록, 상태 매트릭스, 상태 안정 컨트롤 규칙 | `dbc-hbin/omp-ulw@74df40f frontend` layout and build-floor guidance (mechanism reference, re-authored) |
### Evidence grade
소유권 질문, 스트레스 목록, 상태 매트릭스는 이 패키지가 고른 체크리스트이므로 `LOCAL`입니다. CSS와 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: 471k | 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: 471k | 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: 471k | 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 |