# 팀 디자인 규칙과 화면 동작 보존

npm 0.12.0부터 지원합니다. npm 0.11.0에는 포함되지 않았습니다.

## 팀 규칙

`examples/team-ui/rules.json`을 프로젝트에 복사하고 `files`와 import 경로를 실제 프로젝트에 맞게 수정합니다.

```sh
oscode frontend team-ui import rules.json --yes
oscode frontend team-ui check
```

대화에서는 `/team-ui import rules.json`, `/team-ui check`를 사용합니다. 등록은 기존 쓰기 승인과 BUILD 권한을 따릅니다. 검사는 모델 호출 없이 실행됩니다. 실패·미검증은 CLI 종료 코드 2입니다.

- `require-import`: 지정 모듈의 정적 import가 필요합니다.
- `forbid-import`: 지정 모듈의 정적 import를 금지합니다.
- `forbid-text`: 소스에 지정 문자열이 있으면 파일·첫 번째 줄 위치를 표시합니다.

규칙은 `.oscode/team-design-rules.json`에 저장됩니다. 명시적으로 지정한 파일만 검사하며 glob은 지원하지 않습니다. 최대 100개 규칙, 규칙당 100개 파일, 파일당 300,000자입니다. 없는 파일·읽기 오류·스크립트 파싱 오류는 통과가 아닌 `incomplete`입니다.

React/Angular의 JS·TS와 Vue/Svelte의 script import를 분석합니다. import 존재는 해당 컴포넌트의 실제 렌더링·provider·props 정확성을 증명하지 않습니다. 동적 import/require는 검사하지 않습니다. `forbid-text`는 주석을 포함한 정확한 문자열 검색이며 CSS 의미 분석이 아닙니다. 자동 코드 수정은 하지 않습니다.

등록된 규칙은 `/workflow run` 결과와 `/evidence`에도 포함됩니다. `/workflow build`는 AI 실행 전 규칙을 보관하고 원래 규칙으로 검증합니다. 실행 중 규칙이 바뀌면 `stale`로 처리합니다. 요구사항별 화면 검사 결과와 팀 규칙 결과는 따로 표시합니다.

## 상태 보존 시나리오

`examples/team-ui/preserve.json`의 선택자를 실제 화면에 맞게 수정합니다.

```sh
oscode ui check http://localhost:3000 --scenario preserve.json --allow-shell
```

기존 `/states run`, `/states fix`, `/workflow` 시나리오에도 같은 단계를 사용할 수 있습니다.

- `remember`: 지정 요소의 상태를 실행 중 메모리에 저장합니다. `name`은 고유해야 합니다.
- `preserved`: 저장한 이름의 상태와 현재 요소를 비교합니다. DOM이 교체되어도 선택자로 다시 찾습니다.
- `properties`: `value`(input/textarea/select), `checked`(checkbox/radio), `selected`(select 선택 값 배열), `focused`(포커스 여부), `scroll`(요소의 좌우·상하 위치).

각 선택자는 정확히 한 요소와 일치해야 합니다. 입력값·선택·포커스는 정확히 비교하고 스크롤은 2px 오차를 허용합니다. 비밀번호·파일 입력의 value는 지원하지 않습니다. 비동기 작업은 예제처럼 완료 표시 검사를 넣은 후 `preserved`를 실행하세요. 자동 재시도로 순간 회귀를 감추지 않습니다.

상태는 같은 시나리오의 작업 전후를 비교하며, 브라우저 종료 후 남지 않습니다. 수정 전후 코드는 동일 시나리오를 재실행해 검증합니다. 기억한 값은 결과 JSON에 넣지 않지만 기존 브라우저 trace·스크린샷에는 화면 데이터가 포함될 수 있습니다. 가상화 그리드의 내부 선택 모델·iframe·모든 사용자 동작을 자동 추론하지 않습니다. 앱이 DOM에 노출하는 선택 상태에 맞게 검사해야 합니다.