japanese-ui-contract-review ยท diff
git:20260914.2343039 to git:20261103.ff96b46
8 added, 7 removed. Audit C to C.
# Japanese UI Contract Review
Use this skill when an AI agent is asked to create, revise, or review a Japanese web interface governed by `DESIGN.md`.
## Goal
Keep UI generation inside the selected Japanese UI contract, then return observed failures to the owning contract layer instead of patching screenshots ad hoc.
## Inputs
Required:
- project `DESIGN.md`
- target UI code or rendered preview
Recommended:
- closest profile under `templates/`
- relevant CSS recipes under `recipes/`
- relevant fixture under `fixtures/`
- CI or local rendered-validation Evidence when available
## Workflow
1. Read `DESIGN.md` before proposing visual changes.
2. Run static validation:
```bash
python validators/contract.py validate DESIGN.md
```
3. Identify the active profile and validation targets.
4. Create or modify the UI without weakening explicit contract rules.
- 5. Test the output against the closest fixtures. At minimum, check any fixture named by the contract's validation targets.
+ 5. Inspect the actual application states named by the contract. Use the closest fixtures as reproducible references; fixture success does not validate the application.
6. When this repository's browser harness is available, run rendered validation:
```bash
npm install
npx playwright install chromium
npm run test:rendered
```
- 7. Review the rendered result using `validators/scorecard.md` and classify findings as PASS / WARN / FAIL.
- 8. Attribute each WARN or FAIL to exactly one primary bucket:
+ 7. Check the actual local application with `npm run check:ui -- --url <local-url>`. This checks document horizontal overflow only. For explicit element measurements, adapt the opt-in helper described in `examples/notification-settings/README.md`; keep its table in DESIGN.md.
+ 8. Review the rendered result using `validators/scorecard.md` and `docs/conditional-visual-review.md`. Separate MUST failures from contextual recommendations. Unknown required checks remain WARN with acceptance pending. Do not ban colors, gradients or emoji without task-specific evidence.
+ 9. Attribute each WARN or FAIL to exactly one primary bucket:
- missing contract rule
- weak profile default
- missing fixture
- validator gap
- implementation bug
- 9. Fix the owning layer. Do not hide a contract problem with a one-off local style override unless the override is explicitly justified.
- 10. Re-run static and rendered validation as applicable.
- 11. Report Evidence and residual manual checks.
+ 10. Fix the owning layer. Do not hide a contract problem with a one-off local style override unless the override is explicitly justified.
+ 11. Re-run static and rendered validation as applicable.
+ 12. Report Evidence and residual manual checks.
## Evidence priority
Prefer Evidence that another reviewer can inspect or reproduce:
1. failing or passing browser gate with exact fixture and viewport
2. geometry or overflow measurement
3. DOM / accessibility assertion
4. screenshot of the rendered fixture
5. human visual observation with explicit PASS / WARN / FAIL rationale
A screenshot alone is not sufficient when the relevant condition can be measured directly.
## Output
Return a compact review record containing:
```md
## Contract review
- Profile:
- Static validation: PASS / WARN / FAIL
- Rendered validation: PASS / WARN / FAIL / NOT RUN
- Visual review: PASS / WARN / FAIL
- Fixtures checked:
- Viewports checked:
## Findings
- Finding:
- Attribution:
- Evidence:
- Change made:
## Residual risk
- Remaining manual checks:
- Unsupported browsers / surfaces:
```
## Guardrails
- Do not globally introduce `word-break: break-all`.
- Do not optimize Japanese body typography from Latin-first defaults without checking long Japanese text.
- Keep paragraph, table, and form density separate.
- Treat screenshots as Evidence, not as the contract itself.
- Prefer measurable browser checks over visual assertion when the property is measurable.
- Do not silently weaken a validation target to make a result pass.
- When Evidence is insufficient, leave the result as WARN and state the missing check.
- Do not treat Chromium-only success as proof of Firefox or WebKit compatibility.
## Useful commands
Validate a contract:
```bash
python validators/contract.py validate DESIGN.md
```
Export a machine-readable projection for another agent or CI step:
```bash
python validators/contract.py export DESIGN.md -o design-contract.json
```
Strict repository check:
```bash
python validators/contract.py validate --strict templates/*/DESIGN.md
```
Run the browser gates:
```bash
npm run test:rendered
```
- See `docs/v0.2-release-gate.md` for the release-level acceptance conditions.
+ See `docs/v0.3-release-gate.md` for the release-level acceptance conditions.