# Component Generation Pitfalls

This document summarizes the repeated mistakes found while turning Figma components into canonical code components and docs pages.

It is intended to reduce repeated errors when generating later components.

## 1. Compressing Figma axes too early

The most common mistake is to collapse multiple Figma axes into a smaller boolean API too early.

Examples:

- `CheckBox`
  - Figma: `status = off | on | some`, `enable = yes | no`, `dark theme = on | off`
  - overly compressed code: `checked`, `indeterminate`, `disabled`
- `Radio`
  - Figma: `status = off | on`, `enable = yes | no`, `dark theme = on | off`
  - overly compressed code: `selected`, `disabled`

Why this is a problem:

- variant semantics remain in the wrapper but disappear in the visual layer
- disabled-selected and disabled-off become hard to review independently
- later pixel review turns into patching approximations instead of matching real variants

Rule:

- keep Figma axes explicit as long as possible
- wrappers may adapt them, but the visual layer should still style against explicit variant classes or `data-figma-*` attributes

## 2. Guessing token meaning from close-looking colors

A color match is not the same thing as a semantic match.

Typical failure modes:

- using a nearby gray token because the hex looks similar
- mapping layered fills to a flat token without confirming the design intent
- replacing a confirmed semantic token with a generic fallback token

Rule:

- prefer explicit variable meaning over visual similarity
- if only the hex is known, record it as a temporary visual fact, not a semantic truth
- when the meaning is unclear, raise it instead of silently normalizing it

## 3. Treating disabled states as generic opacity reductions

This caused repeated problems in:

- `CheckBox`
- `Radio`

Typical mistake:

- selected disabled state is reduced with opacity instead of being mapped to its own Figma visual treatment

Rule:

- `disabled-off` and `disabled-selected` must be distinct states
- if Figma preserves a selected glyph in disabled state, keep it
- do not collapse selected disabled controls into empty neutral controls

Additional note:

- in light theme, `disabled-off` controls must not rely on transparent backgrounds when the reference component uses a pale filled base
- otherwise the control can appear visually missing on white backgrounds

## 4. Using browser-native behavior where Figma shows custom interaction

This was most visible in `Select`.

Typical mistakes:

- dropdown expands layout height instead of floating as an overlay
- clicking an option does not write the value back to the trigger
- date/time controls are treated as basic selects

Rule:

- match the interaction model first
- for select-like controls:
  - trigger opens overlay below
  - selection writes back to field value
  - overlay should not stretch the surrounding demo layout

## 5. Organizing docs pages by technical variant instead of feature meaning

Typical mistake:

- one long page with all components mixed together
- separate pages for `line` and `filled` even when the review should compare them side by side
- grouping by component file name instead of by feature category

Rule:

- one component per page
- shared left navigation shell
- inside each page:
  - organize by feature groups first
  - then by states
- compare `line / filled` side by side in the same state whenever the component family requires it

## 6. Showing unsupported states as empty UI blocks

This happened in `DateTime` when the page rendered `Editable` even though Figma did not provide that state for that feature group.

Rule:

- do not render empty placeholder cards
- if a state has no real Figma-backed variant for that feature group, hide the whole subsection

## 7. Translating component names instead of preserving code names

Typical mistake:

- sidebar and page titles use only Chinese labels
- code name disappears, making it harder to connect docs to actual component exports

Rule:

- keep the code component name
- add Chinese explanation after it

Examples:

- `CheckBox 复选框`
- `Radio 单选框`
- `Input 输入框`
- `Select 选择框`

## 8. Treating exported numeric values as the only source of truth

Typical mistake:

- exported data says `1px`, so the browser implementation is forced to `1px` even when the visual result is obviously thinner than Figma

Rule:

- distinguish between:
  - data-faithful values
  - visual-faithful values
- if visual mismatch is confirmed, record the reason and use the visually correct value

Example:

- `CheckBox` border was confirmed visually closer to `1.2px`

## 9. Reviewing too late

If every component is generated first and reviewed only at the end:

- the same mistakes repeat across many components
- fixing them becomes expensive

Rule:

- use a representative subset to establish review rules
- then apply those rules to later components
- do a final system-wide pass after the broader site is assembled

## Recommended Review Template

For each component, ask in this order:

1. Is the page grouping correct?
2. Are line/filled variants compared in the correct place?
3. Are unsupported states hidden?
4. Are Figma axes preserved in the wrapper?
5. Are disabled states modeled explicitly?
6. Is interaction behavior matched before visual fine-tuning?
7. Are token choices confirmed rather than guessed?
8. Which states deserve pixel review first?