Ahmed8881/ahmed-ui-craft

Ahmed UI Craft

언어 모델은 웹의 통계적 평균을 향해 표류합니다: Inter 폰트, 보라색 그라데이션, 동일한 세 개의 둥근 카드, 기능당 이모지 하나. 그런 출력은 한눈에 알아볼 수 있으며 누구도 결정을 내리지 않았다는 사실을 사용자에게 알립니다. 이 스킬은 결정을 내리고, 토큰으로 기록하며, 무엇이든 전달하기 전에 확인하도록 강제합니다.

워크플로우를 순서대로 따르세요. 각 단계는 건너뛰면 평범한 UI가 되는 방식으로 존재합니다.

0단계 - 디자인하기 전에 프로젝트를 읽으세요

만들기 전에 먼저 살펴보세요. 다음 순서로 확인하세요.

1. 프레임워크: package.json (next, react, vue, svelte, astro) 또는 일반 .html.
2. 스타일링: tailwind.config.* 또는 @import "tailwindcss" / @theme (Tailwind v4), *.module.css, styled-components, 또는 일반 CSS.
3. 기존 토큰: --color-, --space-, @theme, theme.extend를 grep으로 검색.
4. 컴포넌트 라이브러리: components/ui/ + components.json (shadcn/ui), @mui/material, Radix, Headless UI, Vuetify.

이유: 프로젝트의 기존 토큰과 라이브러리를 무시하는 아름다운 컴포넌트는 개선이 아니라 퇴보입니다. 프로젝트에 이미 디자인 시스템이 있다면 그 안에서 작업하세요: 토큰을 확장하고, 프리미티브를 리스타일링하세요 (shadcn/ui의 경우 globals.css의 CSS 변수와 컴포넌트 파일을 편집하고, 래핑하지 마세요). 확장할 시스템이 없을 때만 assets/tokens.css를 가져오세요.

아무것도 없다면 기본값은: assets/tokens.css의 의미론적 HTML + CSS 사용자 정의 속성이며, Tailwind가 있으면 Tailwind에 매핑합니다.

1단계 - 디자인 사고 (코드 작성 전)

머릿속이나 답변에 네 가지 짧은 줄을 작성하세요.

• 목적: 이 화면은 어떤 작업을 수행합니까? (예: "팀 리드를 설득하여 평가판을 시작하게 함")
• 대상: 누가, 어떤 기기에서, 어떤 기분으로 보고 있습니까? (예: "운영 엔지니어, 데스크톱, 빠르게 스캔")
• 톤: 형용사 세 개. (예: "정확함, 차분함, 조밀함")
• 차별화 요소: 탭을 닫은 후 누군가가 기억할 한 가지.

차별화 요소는 구체적이고 눈에 띄어야 하며, "깔끔하고 현대적인"이 아니어야 합니다. 좋은 예: "가격이 가장자리까지 닿는 거대하고 좁은 숫자로 설정됨"; "모든 카드에는 헤어라인 규칙과 사양서와 같은 모노 인덱스 번호가 있음"; "히어로 제목은 오프화이트 종이 질감 위에 세리프 이탤릭체로 설정됨".

이유: 차별화 요소를 명명할 수 없다면 출력은 평균이 될 것입니다. 모델을 끌어당기는 것이 없을 때 모델이 생성하는 것이 평균이기 때문입니다.

사용자가 브랜드, 스크린샷 또는 기존 사이트를 제공한 경우 톤은 그로부터 비롯됩니다. 기존 브랜드에 새로운 방향을 강요하지 마십시오.

2단계 - 하나의 미학적 방향에 전념

하나의 방향을 선택하고 모든 곳에 적용하십시오: 서체, 색상, 반경, 그림자, 모션, 이미지 및 카피 리듬. 혼합된 방향은 우유부단함으로 읽힙니다.

방향	서체	색상	모양과 깊이	모션
편집적	세리프 디스플레이, 휴머니스트 바디	종이 오프화이트, 잉크, 하나의 강한 포인트	헤어라인 규칙, 거의 제로 반경, 그림자 없음	느린 페이드, 스크롤 시 없음
브루탈리스트	두꺼운 그로테스크 또는 모노, 거대한 크기	원색 검정/흰색 + 하나의 강한 색상	0 반경, 두꺼운 테두리, 하드 오프셋 그림자	즉각적, 스냅
소프트 / 오거나닉	둥글거나 부드러운 세리프 디스플레이	따뜻한 색조의 중성색, 음소거된 흙빛 포인트	컨테이너에만 큰 반경, 확산 그림자	탄력적, 부드러움
산업적 / 기술적	좁거나 그로테스크 + 모노	어두운 중성색, 신호 포인트(앰버, 라임, 시안)	작은 반경, 1px 테두리, 눈에 보이는 그리드 선	빠름, 선형적
럭셔리	고대비 세리프, 넓은 트래킹 대문자	거의 검정, 크림, 메탈릭 또는 깊은 보석 포인트	넉넉한 여백, 얇은 테두리	느림, 긴 이징
플레이풀	덩어리진 디스플레이, 친근한 산세리프	의도적으로 충돌하는 두 개의 채도 높은 색상	스티커 모양, 오프셋 그림자	바운스 오버슈트

각 행에는 assets/directions/에 준비된 프리셋(글꼴, 대비 확인된 라이트 및 다크 팔레트, 반경, 그림자, 모션)과 references/directions.md에 있는 시그니처 동작 목록이 있습니다. tokens.css 다음에 프리셋을 로드하고, 시그니처 동작 중 두 개 이상을 사용하고, 색조를 브랜드 쪽으로 이동하십시오. 스위스 미니멀은 일곱 번째 프리셋입니다.

선택 규칙:

• 1단계에서 도출해야 하며, 습관에서 도출해서는 안 됩니다. SRE용 대시보드는 "럭셔리"가 아닙니다.
• 답변에 그 이름을 명시하십시오 ("방향: 산업적 / 기술적") 그래야 사용자가 조기에 방향을 바꿀 수 있습니다.
• 사용자가 밋밋한 것 ("간단하고 깔끔하게")을 요청한다면, 그래도 선택하십시오: "스위스 미니멀"은 하나의 방향입니다 (엄격한 그리드, 하나의 그로테스크, 검정 + 하나의 색상, 장식 없음).

3단계 - 먼저 토큰 정의

단일 컴포넌트를 작성하기 전에 다음에 대한 토큰을 정의하십시오: 색상, 서체, 간격, 반경, 그림자, 모션, z-index. assets/tokens.css에서 시작하십시오: 이름을 유지하고 값을 바꾸십시오.

시작 값 (Fraunces + Instrument Sans, 종이 중성색, 버밀리온 악센트)은 자리 표시자일 뿐 스타일이 아닙니다. 컴포넌트를 작성하기 전에 적어도 글꼴 쌍 (references/typography.md에서 방향과 일치하는 것으로), 포인트 색조 및 중성색이 색조를 띠는 방향을 변경하십시오. 이유: 테스트에서 변경되지 않은 시작 토큰으로 인해 관련 없는 제품의 로그인 양식과 가격 페이지가 동일하게 보였습니다. 이것은 새로운 기본값이며, 이 스킬이 존재하는 이유입니다. 방향이 정말로 빨간색-주황색 액센트가 있는 따뜻한 편집 스타일인 경우에만 유지하십시오.

새롭고 접근 가능한 팔레트를 만드는 가장 빠른 방법: 생성한 다음 2번 블록의 색상 토큰 위에 붙여넣습니다.

node scripts/palette.mjs --hue 250 --accent 130 --dark-first   # 슬레이트 중성색, 라임 악센트

--hue는 중성색의 색조를 지정합니다 (브랜드 색조 사용), --accent는 악센트 색조입니다. 모든 텍스트/배경 쌍은 인쇄 전에 라이트 및 다크에서 WCAG AA를 통과하도록 해결됩니다.

다크 퍼스트 방향 (모니터링 대시보드, 개발자 도구, 럭셔리 나이트 테마)의 경우 :root { color-scheme: dark; }를 설정하여 다크를 기본값으로 하고 라이트를 옵트인으로 만듭니다.

이유: 토큰은 방향을 강제 가능하게 만듭니다. 컴포넌트에 하드코딩된 #6366f1 또는 13px는 고립되어 내려진 결정이며, 그러한 결정이 20개 있으면 UI가 표류합니다. 토큰을 사용하면 다크 모드, 테마 지정 및 추후 리스타일이 하나의 파일 변경으로 가능합니다.

규칙:

• 두 계층: 원시 팔레트 (--ink-900, --clay-500) 및 의미론적 토큰 (--color-text, --color-accent, --color-surface). 컴포넌트는 의미론적 토큰만 사용합니다.
• 컴포넌트에 매직 넘버 없음. 모든 색상, 크기, 간격, 반경, 그림자, 지속 시간 및 z-index는 토큰에서 가져옵니다. 예외: 0, 1px 헤어라인, 100% 및 1fr.
• 다크 모드: 모든 의미론적 색상은 light-dark(LIGHT, DARK)이므로 두 테마가 하나의 선언에 공존하며 컴포넌트는 절대 변경되지 않습니다. references/color-and-theming.md를 참조하세요.

Tailwind: 토큰을 테마로 만들어 bg-surface, text-text-muted, font-display 및 rounded-md가 존재하고 bg-indigo-500는 존재하지 않도록 하십시오.

• v4: assets/tokens.css의 두 번째 블록은 이미 Tailwind의 네임스페이스 (--color-*, --font-*, --text-*, --radius-*, --shadow-*, --ease-*)를 사용합니다. 해당 블록의 :root를 @theme로 변경하고 첫 줄로 --color-*: initial;을 추가하여 기본 팔레트를 삭제하십시오. 블록 3 (color-scheme)은 일반 CSS로 유지하십시오. 유틸리티는 var(--color-*)를 참조하므로 테마별로 light-dark()를 해결합니다. @theme inline { --color-x: var(--color-x) }를 작성하지 마십시오. 자신의 이름을 참조하는 변수는 순환되어 아무것도 해결되지 않습니다.
• v3: tailwind.config에서 theme.colors (extend 아님)를 { surface: "var(--color-surface)", ... }로 설정하고 같은 방식으로 fontFamily, borderRadius, boxShadow를 확장하십시오.

4단계 - 모든 상태와 함께 모바일 우선으로 구축

360px 뷰포트에 대한 기본 스타일을 작성한 다음 min-width 미디어 또는 컨테이너 쿼리를 추가하십시오. 이유: 공간을 추가하는 것이 제거하는 것보다 쉽고, 대부분의 레이아웃 버그 (가로 스크롤, 부서진 테이블)는 작은 너비에서만 나타납니다.

모든 대화형 요소는 모든 상태와 함께 제공됩니다. 누락된 상태는 UI가 미완성된 느낌을 주는 가장 일반적인 이유입니다.

상태	표시해야 할 것
default	휴식 중인 디자인
hover	미묘한 변경 (색상 또는 그림자), @media (hover: hover) 아래에서만
focus-visible	명확하게 보이는 링, 절대 제거하지 않음
active	눌림 피드백 (더 어둡게 또는 translateY(1px))
disabled	더 낮은 대비 + cursor: not-allowed 및 실제 disabled 속성
loading	스피너 또는 스켈레톤, aria-busy="true", 너비가 튀지 않음
error	필드 근처의 메시지 텍스트, 빨간색 테두리만 있는 것이 아님
empty	실제 메시지 및 다음 작업, 빈 상자 절대 안 됨

먼저 의미론적 HTML을 사용하십시오: 작업에는 <button>, 탐색에는 <a href>, 모든 입력에는 <label for>, 모달에는 <dialog>, 표 형식 데이터에는 <table>, 랜드마크 (<header> <nav> <main> <footer>). HTML에 기본 동등 요소가 없는 경우에만 ARIA를 추가하십시오. 이유: 기본 요소는 키보드 동작과 스크린 리더 의미론을 무료로 제공합니다. ARIA는 그런 다음 구현해야 하는 약속입니다.

실제 카피를 작성하십시오. 자리 표시자 텍스트 ("Lorem ipsum", "기능 1", "홍길동")는 레이아웃 문제를 숨기고 결과를 템플릿처럼 보이게 만듭니다. 1단계의 목적에 맞는 구체적이고 그럴듯한 콘텐츠를 사용하십시오.

5단계 - 전달하기 전에 감사

scripts/audit.md를 실행하십시오: bash scripts/audit.sh <변경된 파일> (패턴 검사 및 토큰 대비), 그런 다음 Playwright를 사용할 수 있거나 사용자가 설치에 동의하면 node scripts/browser-check.mjs <페이지>를 실행하고 저장된 스크린샷을 살펴보십시오. 실패한 것을 수정하십시오. 주석에 작성된 비율은 주장일 뿐 측정값이 아닙니다. 계산하십시오. 알려진 실패가 있는 상태에서 작업이 완료된 것으로 보고하지 마십시오. 무언가를 고칠 수 없는 경우(예: 대비에 실패한 브랜드 색상), 명시적으로 말하십시오.

멀티 에이전트 모드 (하위 에이전트 도구를 사용할 수 있는 경우)

메인 에이전트는 항상 0-4단계를 직접 수행합니다. 사고와 구축은 동일한 컨텍스트가 필요하며, 분할하면 0단계에서 찾은 내용이 손실됩니다. 다음 두 지점에서만 하위 에이전트를 사용하십시오.

1. 방향 제안 (2단계, 개방형 브리핑에만 해당). 브랜드, 스크린샷 또는 기존 디자인 시스템이 없는 경우 2-3개의 하위 에이전트를 병렬로 실행하십시오. 각각에 1단계 라인을 제공하고 표에서 다른 방향을 할당하십시오. 각각에게 먼저 references/directions.md 및 references/typography.md의 해당 섹션을 읽도록 지시하고, 다른 에이전트의 방향을 알려주어 피하도록 하십시오. 각각은 다음만 반환합니다: 방향, 글꼴 쌍, 악센트 + 중성 색조, 차별화 요소, 두 개의 시그니처 동작. 다른 에이전트의 글꼴 쌍, 악센트 색조 또는 차별화 요소를 재사용하거나 tokens.css 시작 값을 유지하는 제안은 거부하십시오. 하나를 선택하고 (또는 사용자에게 옵션을 보여주고) 혼자서 계속하십시오. 이유: 하나의 에이전트는 평균에 수렴합니다. 강제된 다른 시작점은 그렇지 않습니다. 브랜드가 이미 방향을 설정한 경우 이 단계를 건너뛰십시오.

2. 독립적인 검토 (5단계, 항상 새 페이지 또는 화면의 경우). 자체 감사가 통과한 후 코드를 작성하지 않은 새로운 하위 에이전트 하나를 시작하십시오. 변경된 파일, 1단계 라인 및 선택한 방향을 제공하고 다음을 요청하십시오: references/anti-patterns.md 읽기, scripts/audit.sh 실행 및 UI가 평범해 보이거나, 상태를 놓치거나, 방향을 위반하는 모든 위치를 나열하십시오. 각 발견 사항을 차단기 / 주요 / 사소로 순위를 매기고 편집하지 않습니다. 모든 차단기와 주요 항목을 수정하고, scripts/audit.sh를 다시 실행하고, 수정되지 않은 사소한 항목을 답변에 나열하십시오. 한 번의 검토 패스, 루프 없음. 이유: 빌더는 화면에 있는 것이 아니라 만들려고 했던 것으로 결과를 판단합니다.

하위 에이전트 도구가 없음: 두 패스를 모두 직접 순서대로 수행하십시오. 검토를 위해 다른 사람이 작성한 것처럼 파일을 다시 읽으십시오.

품질 규칙 (및 이유)

타이포그래피

• 디스플레이 텍스트에 Inter, Roboto, Arial, Helvetica 또는 system-ui를 기본값으로 사용하지 마십시오. 또한 새로운 AI 기본값인 Poppins, Montserrat, Space Grotesk, DM Sans도 피하십시오. 이유: 이들은 모든 생성된 페이지에서 사용되므로 "생성됨"을 암시합니다.
• 디스플레이 얼굴과 구조적으로 대비되는 바디 얼굴 (세리프 + 산세리프, 좁은 + 넓은, 그로테스크 + 모노)을 쌍으로 연결하십시오. 최대 두 개의 패밀리와 선택적 모노 하나.
• 유체 크기 (clamp())가 있는 모듈식 스케일을 사용하고 가장 큰 제목을 본문 텍스트보다 극적으로 크게 만드십시오. 소심한 계층 구조 (16px 위의 32px)는 미완성으로 보입니다.
• 본문 텍스트: 최소 16px, 줄 높이 1.5-1.7, 측정 60-75ch. 조밀한 대시보드는 메타데이터 및 테이블 셀에 12-14px를 사용할 수 있지만 단락 또는 입력에는 사용하지 마십시오.

색상

• 하나의 지배적인 색상이 브랜드를 전달하고, 하나의 선명한 악센트는 기본 작업 및 주요 데이터를 위해 예약됩니다. 중성색이 대부분의 작업을 수행합니다. 대략 60/30/10. 이유: 균등하게 분포된 5가지 색상 팔레트에는 초점이 없으므로 아무것도 중요하게 읽히지 않습니다.
• 순수한 회색을 사용하는 대신 중성색을 브랜드 색조 쪽으로 착색하십시오.
• 브랜드가 실제로 보라색이 아닌 이상 보라색에서 파란색 또는 보라색에서 흰색으로의 그라데이션은 사용하지 마십시오.
• 텍스트 대비 최소 4.5:1 (24px+ 또는 18.66px+ 굵은 텍스트의 경우 3:1, UI 구성 요소 경계 및 포커스 링의 경우도 3:1).

레이아웃 및 모양

• 동일한 3개 또는 4개 카드 그리드를 피하십시오. 크기와 강조를 다양하게 하십시오: 두 개의 열에 걸친 하나의 주요 항목, 큰 시각 자료 옆의 목록, 비대칭 분할.
• 반경은 방향을 따르며 수준별로 일관됩니다. 모든 것에 rounded-2xl을 두지 마십시오. 작은 컨트롤은 작은 반경 또는 반경 없음을 얻습니다.
• 320px에서 가로 스크롤이 없어야 합니다. flex/grid 자식에는 min-width: 0, 긴 문자열에는 overflow-wrap: anywhere, 넓은 테이블에는 스크롤 컨테이너를 사용하십시오.
• 터치 대상은 최소 44x44px (패딩 포함)입니다.

아이콘 및 이미지

• 아이콘으로 이모지를 사용하지 마십시오. 하나의 아이콘 세트 (Lucide, Phosphor, Heroicons, Tabler)를 하나의 선 너비로 사용하거나 인라인 SVG를 사용하십시오. 이유: 이모지는 OS마다 다르게 렌더링되고, 토큰으로 색상을 지정할 수 없으며, 스크린 리더에서 "로켓"으로 알립니다.
• 장식용 아이콘은 aria-hidden="true"를 얻습니다. 아이콘 전용 버튼은 aria-label을 얻습니다.

모션

• transform 및 opacity (그리고 filter는 드물게)만 애니메이션화하십시오. 이유: 다른 속성은 모든 프레임에서 레이아웃 또는 페인트를 트리거하고 저가형 전화기에서 버벅거립니다.
• 토큰의 지속 시간: UI 피드백의 경우 120-200ms, 요소 진입의 경우 250-400ms.
• prefers-reduced-motion을 존중하십시오: 움직임을 제거하고 페이드를 짧게 또는 즉각적으로 유지하십시오.

액세서빌리티

• 모든 대화형 요소는 키보드로 도달 및 작동 가능해야 합니다.
• 시맨틱 HTML을 먼저 사용하십시오. ARIA는 HTML에 동등한 요소가 없을 때만 추가합니다.
• 상태를 놓치지 마십시오 (위의 표 참조).
• 이미지와 아이콘에 대한 대체 텍스트.
• 의미 있는 색상 정보를 전달하는 데만 색상에 의존하지 마십시오 (예: 빨간색 테두리 + 오류 텍스트).

복사

• AI 디자인에서 흔히 볼 수 있는 "혁신적인", "강력한", "차세대"를 피하십시오.
• 특정 제품 또는 페이지에 맞게 조정된 구체적이고 그럴듯한 콘텐츠를 사용하십시오.
• "Lorem ipsum", "기능 1" 또는 "홍길동"과 같은 자리 표시자 텍스트는 레이아웃 문제를 숨깁니다. 피드백을 제공하는 실제 콘텐츠를 작성하십시오.

스크립트 참조

• scripts/palette.mjs: 대비가 해결된 색상 팔레트를 생성합니다.
• scripts/audit.sh: 프로젝트 파일에서 일반적인 패턴 및 대비 문제를 확인합니다.
• scripts/browser-check.mjs: 브라우저에서 페이지를 열고 시각적 검사를 위해 스크린샷을 저장합니다.
• assets/tokens.css: 기본 색상, 서체, 간격 및 기타 디자인 토큰.
• assets/directions/: 다양한 방향에 대한 사전 구성된 스타일 프리셋.
• references/: 서체, 방향, 색상 및 안티 패턴에 대한 추가 정보.

최종 참고 사항

이 워크플로우는 설계 사고, 의도적인 방향 선택, 체계적인 토큰화, 우수한 엔지니어링 및 철저한 검토를 강조합니다. 각 단계를 따르면 AI가 생성했지만 인간이 디자인한 듯한 UI를 만드는 데 도움이 됩니다. 단계를 건너뛰거나 기본값을 수락하면 결국 다른 AI UI와 똑같이 보이게 됩니다.