AI가 잘 쓸 수 있는 디자인 시스템을 만들고, AI가 만든 컴포넌트 확인하기

## 무엇이든 바꾸기 전에 컴포넌트와 문서를 맡은 패키지 찾기 디자인 시스템을 시각적 조각의 모음이 아니라 공유 제품 계약으로 취급하세요. 무엇이든 변경하기 전에 컴포넌트, 문서, 예제, 미리보기 화면, 테스트 하네스, 마이그레이션 유틸리티를 각각 소유하는 패키지를 파악하세요. 사용 가능한 API와 규칙은 저장소의 현재 브랜치를 기준으로 판단하세요. 일반적인 웹 플랫폼 지식, 다른 브랜치 또는 더 최신 라이브러리 릴리스만으로 지원 여부를 추론하지 마세요. 작업이 도구 체인을 명시적으로 변경하지 않는 한 설정된 패키지 관리자, 런타임, 모듈 형식, 테스트 실행기를 유지하세요. ## 시작 전에 현재 브랜치의 문서와 컴포넌트 목록 읽기 컴포넌트 작업 전에 다음을 수행하세요. 1. 대상에 적용되는 저장소 및 패키지 지침을 읽으세요. 2. 로컬 명령줄 도움말을 확인하고 사용 가능한 문서 주제를 나열하세요. 3. 디자인 원칙, 토큰, 테마 규칙, 컴포넌트 목록을 불러오세요. 4. 작업이 하나의 기본 요소가 아니라 레이아웃에 관한 것이라면 페이지 템플릿을 확인하세요. 5. 대상 컴포넌트의 현재 API, 변형, 구조, 예제, 제약 조건을 읽으세요. 생성된 문서와 지원되는 API는 브랜치마다 다를 수 있으므로 이 준비 과정을 모든 브랜치에서 반복하세요. 디자인 시스템 의존성을 업그레이드한 뒤에는 관련 없는 수동 변경을 하기 전에 저장소의 마이그레이션 유틸리티를 실행하세요. ## 파일 머리의 설명과 컴포넌트 문서를 함께 고치기 서로 보완하는 두 문서 계층을 유지하세요. 각 소스 파일 헤더에는 입력, 출력, 아키텍처상 위치에 관한 간결한 메타데이터를 넣고, 상세한 속성, 기능, 예제, 접근성 참고 사항, 조합 지침은 컴포넌트가 소유하는 문서 파일에 유지하세요. 구현이 변경되면 두 계층을 모두 업데이트하고 서로 연결된 파일을 식별하는 동기화 마커를 따르세요. 렌더러가 실제로 지원하는 문서 형식을 사용하세요. 예를 들어 언어 태그가 있는 코드 펜스가 활성 자동 문서 분석기를 깨뜨린다면 언어 태그가 없는 예제 펜스를 사용하세요. 유효한 소스 구문이 유효한 문서를 만든다고 가정하지 말고 렌더링 결과를 확인하세요. ## 스타일 도구가 실제로 지원하는 CSS 기능을 기록하기 스타일 엔진 버전과 at-rules, 의사 클래스, 의사 요소, 복합 선택자, 값, 애니메이션, 변수, 테마, 동적 값, 조건부 선택자에 대한 검증된 지원 범위를 기록하세요. 지원되는 구문과 컴파일은 되지만 잘못되거나 사용할 수 없는 CSS를 생성하는 구문을 구분하세요. 매트릭스가 지원을 확인한 경우 CSS 네이티브 해결책을 우선하세요. 일반적인 후보에는 미디어·기능·컨테이너 쿼리, 시작 스타일, 스코프, 상호작용 및 구조 의사 클래스, 생성 콘텐츠 의사 요소, 최신 색상 및 크기 함수, 전환, 키프레임이 있습니다. 이전 기능 표에 해당 기능이 없었다는 이유만으로 JavaScript 우회 방법을 만들지 마세요. ## 호버와 포커스 효과를 그 컴포넌트 안에서만 적용하기 스타일 엔진이 지원하는 조건부 선택자 메커니즘을 통해 상위, 하위, 형제 요소의 상태를 표현하세요. 이 메커니즘에 마커가 필요하면 실제 상위 요소에 마커를 적용하고 그 정의를 소유 컴포넌트 가까이에 두세요. 폼 컨트롤과 기타 중첩된 상호작용 요소에는 컴포넌트 범위의 마커를 사용하세요. 바깥쪽 팝오버, 패널 또는 컨테이너의 hover나 포커스 상태가 컨트롤로 새어 들어갈 수 있다면 전역 기본 마커를 절대 사용하지 마세요. 의사 클래스만으로 구성된 상위 조건 같은 선택자 계약을 지키고, 지원되지 않는 CSS 중첩을 흉내 내지 마세요. 터치 장치가 고정된 상호작용 상태를 물려받지 않도록 hover 전용 효과를 hover 기능 미디어 쿼리로 보호하세요. 키보드 포커스와 비활성화 상태 동작은 hover와 독립적으로 보존하세요. ## 배치와 애니메이션은 JavaScript 대신 CSS로 만들기 지원되는 경우 grid, 간격을 둔 flexbox, 종횡비, 오버플로 제어, 스크롤바 속성을 직접 사용하세요. 컴포넌트 반응형 동작에는 관찰자로 요소를 측정하는 방식보다 컨테이너 쿼리를 우선하고, 줄무늬 표현에는 인덱스 기반 JavaScript보다 구조 의사 클래스를 사용하세요. 진입 전환은 상태와 애니메이션 프레임 조율을 조합하는 대신 starting-style 지원으로 구현하세요. 순서가 있는 CSS fallback은 수동 런타임 감지 대신 스타일 엔진의 fallback 추상화로 표현하세요. 특수 위치 지정 지원은 생성된 CSS가 지원 브라우저 집합에서 검증된 경우에만 사용하세요. ## 링크와 테마를 바꿔 끼울 수 있게 해서 컴포넌트를 복사하지 않게 하기 런타임 의존 값은 인라인 스타일 대신 타입이 지정된 스타일 함수를 통해 전달하세요. 조건부 스타일은 임의의 클래스 이름을 전환하지 말고 시스템의 스타일 속성 메커니즘으로 조합하세요. 테마 변수와 테마 생성은 컴파일러가 요구하는 파일 유형에 유지하고, 검증에 도움이 되는 경우 타입이 지정된 변수나 컴파일 타임 상수를 사용하세요. 앵커 요소를 하드코딩하지 말고 주입 가능한 링크 추상화를 통해 내비게이션을 렌더링하세요. 그러면 사용자가 컴포넌트를 포크하지 않고도 자신의 라우터를 제공할 수 있습니다. 패키지된 컴포넌트의 이식성을 유지하도록 저장소의 에셋, 글꼴, 공개 경로, 테마 제공자 계약을 따르세요. ## 긴 대화 후반까지 포함해 AI가 컴포넌트를 제대로 만드는지 테스트하기 에이전트 지침이 모델의 유효한 컴포넌트 코드 생성을 돕는지 측정하세요. 빠른 피드백을 위해 전체 프롬프트 모음이나 층화 표본을 실행하세요. 각 프롬프트에는 작업을 읽고, 문서화된 시스템으로 컴포넌트를 생성하며, 우회 수단을 스스로 식별하고, 코드와 평가 메타데이터를 모두 저장하는 격리된 작업자를 사용하세요. 채우기, 주의 분산, 복구 턴이 포함된 10턴 대화에서 문맥 유지력을 측정하는 성능 저하 모드를 추가하세요. 0, 6, 8, 10턴과 같은 대표 지점을 조사한 뒤 마지막 턴만 보고하지 말고 각 프롬프트의 궤적을 비교하세요. 테스트 프롬프트, 생성 결과, 스크린샷을 안정적인 반복 식별자에 연결하세요. 독립적인 프롬프트는 병렬화하되 작업자들이 변경 가능한 결과 파일을 공유하게 하지 마세요. ## 테스트 결과를 모두 남기고, AI가 디자인 시스템을 우회한 곳 찾기 각 사례를 재현하고 비교할 수 있도록 반복 및 프롬프트 식별자, 타임스탬프, 모델, 페르소나, 프롬프트 범주, 궤적 깊이, 프롬프트, 생성 응답, 성공 판정, 사용된 컴포넌트, 감지된 우회 수단을 포함한 충분한 구조화 메타데이터를 저장하세요. 집계하기 전에 미리보기 페이지를 만들고 스크린샷을 캡처하세요. 기능적 성공 여부와 함께 원시 요소, 인라인 스타일, 하드코딩된 내비게이션, 지원되지 않는 선택자, 중복된 기본 요소 또는 지원되는 CSS 대신 사용한 JavaScript 우회 방법을 통해 출력이 디자인 시스템을 우회했는지도 평가하세요. 모델의 자체 평가는 증거가 아니라 하나의 신호로 취급하세요. 기계적 검사, 미리보기 증거, 표본 기반 사람 검토를 결합하세요. 반복되는 실패 양상을 찾은 뒤에만 집계 결과를 사용해 문서나 API를 개선하세요. ## 바꾼 뒤에 작은 확인을 돌리고, 통과한 것을 보고하기 컴포넌트를 수정하기 전에 현재 문서를 살펴보고 요구 사항을 설정, 조합, 새 변형 또는 심층 사용자 지정을 위한 명시적 소스 분리 중 무엇으로 해결하는 것이 가장 적합한지 판단하세요. 공개 계약을 보존하고 확립된 확장 지점이 있는데도 병렬 기본 요소를 만들지 마세요. 변경 후에는 동기화된 문서를 업데이트하고 관련 범위에서 가장 작은 단위 테스트, 타입 및 lint 검사, 스타일 기능 스캔, 컴포넌트 미리보기를 실행하세요. 변경이 공유 계약을 가로지를 때만 전체 모음으로 확장하세요. 핵심 패키지 버전이 변경되었다면 문서화된 마이그레이션 단계를 실행하고 diff를 검토하세요. 변경된 동작, 업데이트한 문서, 통과한 검사, 발견한 지원되지 않는 기능, 실행할 수 없었던 검증을 보고하세요.