85 lines
10 KiB
Markdown
85 lines
10 KiB
Markdown
# Guard CSS Intent·동적 Token 검증 개선
|
|
|
|
RESULT: PARTIAL — 요청한 Guard·문서 구현과 필수 검증 PASS. T01 사용자 디자인 의도 및 미실행 Theme/동적 상태는 NOT VERIFIED.
|
|
|
|
TARGET: `D:\디자인시스템\hmdesign`
|
|
|
|
BASE_SHA: `512cd280554b385dbfa7606ea8a7e557ccf7b197`
|
|
|
|
최종 commit/push SHA·작업 시간은 이 보고서를 포함한 커밋을 만든 뒤 로컬 `_local/css-intent-20261010/FINAL_REPORT.md`에 기록한다. 자기 커밋 SHA를 동일 커밋 파일 안에 넣지 않는다. 실험 source·측정 JSON/PNG·기존 실패 증거는 GitHub에 추가 전송하지 않는다.
|
|
|
|
## 개선 결과와 판정 범위
|
|
|
|
| 항목 | 결과 |
|
|
|---|---|
|
|
| CSS_INTENT | STATIC/RUNTIME/DESIGN_INTENT/FINAL 분리. 명확한 Component HEX/RGB/HSL·spacing/radius override는 STYLE-001 FAIL. 일반 콘텐츠 CSS·Token override·중요도/승인 의도는 별도 inventory/NOT VERIFIED |
|
|
| DYNAMIC_TOKEN | 최대 32개 유한 후보 전체 선언 검사. const/conditional/concatenation/template, shadowing, fallback, Props/style spread/className 미해석 위치를 구분. 실제 Runtime 미정의 Token은 computed fallback 일치에도 FAIL |
|
|
| STATIC_ANALYSIS | 공개 import/CSS entry·Production graph·PARTIAL·Storybook 격리 보존. non-HM host 변수 미확인과 명확한 HM 미정의를 구분. 명백히 잘못된 var() TOKEN-003 FAIL |
|
|
| RUNTIME_EVIDENCE | source/contract + site/file/rule/Component/DOM/property/state/browser/viewport 대응, 실제 값 비교. 원본 issues 보존, 중복 측정 PASS가 FAIL을 가리지 않음 |
|
|
| DESIGN_INTENT | 자동 승인 기능 없음. 문서 recipe·해시·유효 행 검토도 NOT VERIFIED. 새 Theme 편집 방식이나 CSS override 허용 없음 |
|
|
| MEDIUM_T01 | 기존 원본 화면만 사용. Theme/Status import와 연결 Token 정적 PASS. 4폭×4상태의 기존 종류 CSS 64건 + 3개 Badge override custom property 48건 = 112/112 PASS. 세 위치 STATIC PASS/RUNTIME PASS/DESIGN_INTENT NOT VERIFIED/FINAL NOT VERIFIED |
|
|
|
|
T01의 기존 `REUSE-003`는 `src/index.css:15`의 `[data-slot="badge"]` 규칙이다. 세 기존 Badge Token에 상태 변수·공식 background/border recipe를 연결한다. 연결 선언 존재와 브라우저 적용값은 검증할 수 있으나, 사용자가 요청한 화면 의미 및 예외 override 승인 여부는 이 근거만으로 확정할 수 없다. 기존 raw/static/combined NOT VERIFIED를 삭제하지 않았다. 새 결합의 raw/static도 NOT VERIFIED이며 전체 Runtime만 PASS다. 구체적인 CSS 검토 결과는 정적 PASS·위치별 Runtime PASS·디자인 의도 NOT VERIFIED로 구분한다.
|
|
|
|
`styleVerification.runtimeStatus`는 검토가 필요한 override/동적 위치에 대응하는 명명된 측정의 결과다. inventory의 모든 일반 레이아웃 선언, 모든 상태와 Theme 전환을 검증했다는 뜻이 아니다. `styleEvidence.checks`의 나머지 Runtime NOT VERIFIED를 전체 PASS로 바꾸지 않는다.
|
|
|
|
## 수정 파일과 영향
|
|
|
|
| 파일 | 원인 / 변경 내용 | 영향 |
|
|
|---|---|---|
|
|
| scripts/ai-generation-guard.mjs | 스타일 inventory·동적 위치·선언 출처/행·새 분석기 contract hash 연결 | 기존 소비 graph/Navigation/Storybook 범위 유지 |
|
|
| scripts/guard-theme-analysis.mjs | 동적 문자열·Props와 var fallback 검사의 한계 | 유한 후보/미해석 위치/외부 변수/잘못된 참조를 구분 |
|
|
| scripts/guard-style-analysis.mjs | 선언 존재와 디자인 의도가 기존 REUSE-003 하나에 묶임 | 명확한 위반·일반 CSS·Global/scoped·Token override 분리 |
|
|
| scripts/guard-style-evidence.mjs | 측정 PASS가 특정 source site에 대응하지 않음 | 실제 DOM/Component/rule/state/browser와 위치별 네 판정 연결 |
|
|
| scripts/guard-evidence.mjs | 상태 이름·문서 행·충돌/위반 처리 보강 필요 | 원본 보존, 임의 supplied PASS 대신 계산, FAIL 우선 |
|
|
| scripts/ai-generation-guard.test.mjs | 회귀 coverage 확대 | 기존 63개 본문 보존 + 12개 신규 |
|
|
| scripts/guard-evidence.test.mjs | Runtime false PASS 방지 | 기존 11개 본문 보존 + 9개 신규 |
|
|
| AGENTS.md / docs/guidelines/ai-screen-contract.md | AI 화면의 Token/override 보고 계약 명확화 | 기존 Theme 편집 권한·Runtime 공개 계약 확대 없음 |
|
|
| docs/guidelines/ai-generation-guard.md | 세 영역·동적 후보·위치별 JSON/실행 명령·한계 설명 | 과거 테스트 수와 기존 증거는 역사 기록으로 보존 |
|
|
| docs/components/badge.md / docs/patterns/dashboard-layout.md | 기존 상태 recipe와 승인 의도의 구분 | Component·Pattern API/디자인 예제 자체는 미변경 |
|
|
| 이 보고서 | 실제 검증 범위와 잔여 한계 기록 | 저장소 보고 근거 |
|
|
|
|
## 검증
|
|
|
|
| 검사 | 결과 / 근거 |
|
|
|---|---|
|
|
| GUARD_EXISTING | EXECUTED PASS — 기존 63개 본문 보존, 최종 suite에서 통과 |
|
|
| GUARD_NEW | EXECUTED PASS — 12개 추가, 현재 Guard 75/75 |
|
|
| CSS_INTENT_TEST | EXECUTED PASS — Component HEX/RGB/HSL/numeric spacing/radius/utility, Token override, Global/general CSS, literal 동적 분기, graph 밖/Storybook 범위 |
|
|
| DYNAMIC_TOKEN_TEST | EXECUTED PASS — 유한 후보·미정의 분기·fallback·shadowed/destructured binding·외부 Props/style/class·Runtime 미정의 참조 |
|
|
| RUNTIME_EVIDENCE_TEST | EXECUTED PASS — 기존 11 + 신규 9 = 20/20. stale/hash·scope·불가능한 문서 행·site/selector/Component/browser/state·중복 이름과 static 충돌 검사 |
|
|
| REQUIREMENTS_LINK | EXECUTED PASS — 기존 연결 검사 5/5 |
|
|
| 통합 테스트 | EXECUTED 100/100 PASS, `_local/css-intent-20261010/tests-release-final.log` |
|
|
| MEDIUM_T01 | EXECUTED 112/112 CSS 측정 + 20개 필터 동작 + 4 viewport PASS. Dashboard 48px/960px 유지. FINAL NOT VERIFIED |
|
|
| TYPECHECK | EXECUTED PASS — npm run typecheck, Theme defaults 71/73 일치 및 packages build hook 포함 |
|
|
| BUILD | EXECUTED PASS — npm run build --ignore-scripts. 이미 성공한 Theme/package hook 중복 생략. 기존 500kB chunk 경고는 별도 보존 |
|
|
| DOC_CONSISTENCY | EXECUTED — 변경된 로컬 링크/anchor·실행 명령·결과 필드·원칙을 변경 범위에서 점검 |
|
|
| RELATED_STORY | 관련 Badge/Dashboard/Runtime Theme/Designer source 설명 확인. 이번 Guard의 Production 하드코드 FAIL은 Storybook에 강제하지 않음. 설명 충돌 없음, Story source/ID 수정 0. 전체 렌더 NOT VERIFIED |
|
|
|
|
초기 기존 suite 1건은 반복 Token 목록으로 JSON이 spawnSync 출력 버퍼를 초과한 도구 오류였다. 동적 위치가 있는 entry에만 선언 목록을 출력해 같은 검사 재실행 PASS, 최종 100개 전체 PASS다. 초기 T01 추가 32건은 기대 source `var()` 문자열과 computed 치환 값의 비교 형식 오류였다. 해당 실패 JSON/로그를 보존하고 실패 32건만 재측정했으며 당시 통과 80건은 재사용했다. 최종 source-selector/Component 연결 및 하드코드 분기 규칙 변경으로 contract fingerprint가 달라진 뒤에는 이전 해시를 이식하지 않고 최종 112건을 새 계약에서 다시 측정했다. 이는 동일 조건 중복 검사가 아니라 최종 계약 증거 생성이다.
|
|
|
|
## 중복 검증·보존
|
|
|
|
- EXECUTED: 변경 Guard/증거/요구사항 연결 100개, T01 새 계약 CSS112와 동작/네 폭, Typecheck/Build 1회, 문서 영향 범위·Git diff 점검.
|
|
- REUSED PASS: 미변경 T01 source fingerprint와 기존 dist·공개 Theme/Component/Pattern/Story source 보존 근거. 중간 실패 보정 시 유효한 CSS80건 재사용. 이전 frozen f78cc206 공통80/80은 당시 결과로만 인용하며 현재 HEAD 전체 인증으로 확대하지 않음.
|
|
- NOT VERIFIED: 사용자 CSS intent, 실행하지 않은 Theme/상태/외부 입력, 전체 Story별 Runtime, 실제 스크린리더·touch·backend·CSS 전 문법/cycle.
|
|
- SKIPPED — 중복 검사: 전체 292 Story 렌더, 전체 Component 테스트, 기존 정상 화면 재생성, 별도 의존성 설치, 이미 성공한 prebuild package/Theme 재실행.
|
|
|
|
Git diff에서 `src/`, `packages/`, `themes/`, `.storybook/` 변경 0. Foundation·Typography·Spacing·Radius·Button/Tabs/Table·Green LNB 8%·목차 LNB 8%·D-01/D-02·퍼블리셔 확정 요구·공개 API/Theme Token/Designer 기능과 Theme 적용·전환 구현은 미변경이다. 실험 경로는 읽기 전용으로 사용했으며 T01 기존 guard/runtime/combined 3개 원본 SHA-256은 작업 전후 같다. 신규 로컬 실패도 revision1 및 별도 로그로 보존한다. `preservation.json`이 근거다.
|
|
|
|
## 오탐·미탐과 잔여 검토
|
|
|
|
FALSE_POSITIVE: 이번 정상 fixture 회귀 범위에서 발견되지 않음. 일반 HTML/layout·documented Token override·Storybook을 일괄 FAIL로 바꾸지 않았다. 임의 CSS 전체 무오탐 인증은 아니다.
|
|
|
|
FALSE_NEGATIVE: 이번 위반 fixture 범위에서 발견되지 않음. 기존 CSS entry/Navigation/Token/공개 API FAIL 보존. 유한/미확정 분기의 명확한 하드코드와 Runtime fallback 미정의 참조를 추가 탐지한다.
|
|
|
|
REMAINING_LIMITATIONS: named color·일반 utility class·%, calc와 외부 CSS/selector cascade·변수 cycle·opaque wrapper/객체 style·모든 Theme/상태/외부 입력은 전수 인증하지 않는다. Token 선언 PASS는 실제 적용을 뜻하지 않는다. Runtime 자료는 제출 증거이며 독립 실행 인증이 아니다. 사용자 CSS 승인 기능과 Theme 편집 기능은 만들지 않았다. Theme 기능 자체의 결함/개선 필요성은 이번 검사에서 확정하지 않았으며 추가로 발견되면 별도 이슈로 검토한다.
|
|
|
|
## 외부 호출과 Git 정책
|
|
|
|
APPROVED_SESSIONS: 12 / USED_SESSIONS: 10 / REMAINING_SESSIONS: 2 — 사용자 제공 기존 실험 장부 유지. 이번 유지보수의 외부 AI 생성 세션·신규 모델·Claude·하위 에이전트·신규 화면 실험 호출 0. 현재 대화 자체를 외부 실험 장부에 추가하지 않았다.
|
|
|
|
GitHub origin은 `https://github.com/shkim25027/HMDesignSystemTest.git` 그대로다. 시작 main/local/remote SHA는 모두 BASE_SHA와 같고 기존 미커밋 작업은 없었다. 관련 Guard/테스트/MD만 stage·diff 검토 후 일반 main commit/push하며 결과는 최종 로컬 보고서에 기록한다. force/reset/clean/이력 삭제/연결 변경/ZIP 배포 없음.
|
|
|
|
공식 Gitea: NOT ACCESSED / NOT MODIFIED. 월요일 이전·GitHub 연결 해제는 별도 작업으로 유지한다.
|