hirokaji/jp-ui-contracts/japanese-ui-contract-review

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 ``

1. Identify the active profile and validation targets.
2. Create or modify the UI without weakening explicit contract rules.
3. Inspect the actual application states named by the contract. Use the closest fixtures as reproducible references; fixture success does not validate the application.
4. When this repository's browser harness is available, run rendered validation:

``bash npm install npx playwright install chromium npm run test:rendered ``

1. 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.
2. 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.
3. Attribute each WARN or FAIL to exactly one primary bucket:

• missing contract rule
• weak profile default
• missing fixture
• validator gap
• implementation bug

1. Fix the owning layer. Do not hide a contract problem with a one-off local style override unless the override is explicitly justified.
2. Re-run static and rendered validation as applicable.
3. 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:

## 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:

python validators/contract.py validate DESIGN.md

Export a machine-readable projection for another agent or CI step:

python validators/contract.py export DESIGN.md -o design-contract.json

Strict repository check:

python validators/contract.py validate --strict templates/*/DESIGN.md

Run the browser gates:

npm run test:rendered

See docs/v0.3-release-gate.md for the release-level acceptance conditions.