# Component Review Rules

This document records the review rules extracted from the first canonical components. It is the working baseline for later components and helps keep Figma review decisions consistent across the system.

## Goal

The goal is not to chase perfect screenshots too early. The goal is to:

1. keep Figma naming and variant semantics aligned with code
2. keep page information architecture consistent
3. keep token usage stable and explainable
4. reduce repeated review mistakes when scaling to more components

## Review Strategy

Use this order instead of reviewing everything at the very end:

1. Build the canonical wrapper and documentation page
2. Review a small set of representative components deeply
3. Extract reusable rules from those components
4. Apply the rules to the remaining components
5. Do a final full-system review pass

The first representative set is:

1. `CheckBox`
2. `Radio`
3. `Input`
4. `Select`

## Naming Rules

1. Keep the code component name as the primary display name.
2. Add a Chinese explanation after the code name.
3. Do not replace the code name with a translated-only name.
4. Keep page names, sidebar labels, and pager labels consistent.

Examples:

- `CheckBox 复选框`
- `Radio 单选框`
- `Input 输入框`
- `Select 选择框`
- `DateTime 日期时间选择`

## Documentation Structure Rules

1. Use one component per page.
2. Keep the left navigation as a shared shell.
3. Load different page files for different components.
4. Put shared page title and summary in the shell, not repeated inside each page.
5. Add previous/next navigation at the bottom of each page.

## Page Organization Rules

### Generic rule

Within a component page, organize content by the component's real feature groups first, then by state.

### Input

Use these sections:

- `Basic Input 基础输入`
- `Feature Input 功能输入`

Within each section, show states from top to bottom:

- `Default 默认态`
- `Error 错误态`
- `Disable 禁用态`
- `Hover 悬停态`
- `Click 点击态`

Compare `InputBoxLine` and `InputBoxFilled` side by side in the same state.

### Select

Keep `Select` focused on base select behavior:

- `Single Select 基础单选`
- `Multi Select 多选`

Move date/time selection out of `Select`.

Within each section, show states from top to bottom:

- `Default 默认态`
- `Error 错误态`
- `Disable 禁用态`
- `Hover 悬停态`
- `Click 点击态`
- `Editable 可编辑态`

Compare line/filled side by side in the same state.

### DateTime

Use a separate page for date/time related selection:

- `Time Picker 时间选择`
- `Date Picker 日期选择`

Within each section, show states from top to bottom:

- `Default 默认态`
- `Error 错误态`
- `Disable 禁用态`
- `Hover 悬停态`
- `Click 点击态`

Do not render a state section if there is no real Figma-supported variant for that section.

### CheckBox

Use this order:

1. basic states
2. disabled states
3. interactive example

### Radio

Use this order:

1. basic states
2. disabled states
3. interactive example

### Switch

Use this order:

1. basic states
2. disabled and loading states
3. interactive example

## Token Rules

1. Prefer Figma variable semantics over color guessing.
2. If a color is known from design review, use the exact value or the confirmed token alias.
3. Do not silently replace a semantic token with a nearby-looking token.
4. Keep derived rules traceable when they are inferred from layered fills or combined effects.
5. If a state has no reliable token interpretation yet, raise it instead of inventing one.

## Visual Review Rules

1. Distinguish between exported data values and visual rendering.
2. If Figma says `1px` but browser rendering looks thinner or thicker, explicitly note whether the decision is:
   - data-faithful
   - visual-faithful
3. Prefer visual-faithful adjustments only after the design intent is confirmed.
4. When a state is uncertain, do not silently normalize it into a nearby state.

## Missing-State Rules

1. Do not show empty placeholder cards for unsupported states.
2. If a feature group does not have a state in Figma, remove that state section from the documentation page.
3. Empty UI blocks are treated as documentation bugs.

## Interaction Rules

1. Interactive examples are for behavior verification only.
2. Interactive examples should be separated from static review sections.
3. Select-like controls must behave like custom selects:
   - trigger opens overlay below the field
   - selecting an item writes the value back
   - overlay does not stretch the demo card height

## What To Ask During Review

When checking a component, ask in this order:

1. Is the component on the correct page?
2. Is the page name consistent with the code component name?
3. Is the component grouped by the right feature category?
4. Are the state sections shown in the right order?
5. Are unsupported states hidden?
6. Are line/filled variants compared in the same row or state block?
7. Are token choices confirmed, not guessed?
8. Are there interaction differences from Figma?

## Current Known Rules Proven By Review

Already confirmed by prior review:

- `CheckBox` disabled visual logic must not collapse selected and indeterminate into an empty disabled box
- `Radio` selected-disabled must be handled separately from disabled-off
- `Input` and `Select` pages should compare line/filled together, not split by page
- `DateTime` must be separated from base `Select`
- Unsupported `Editable` states for date/time must not render empty sections

## Next Recommended Review Order

1. `Input`
2. `Select`
3. `DateTime`
4. `CheckBox`
5. `Radio`
6. `Switch`