mobilereality/mdma/vendor

A2UI Generation

What This Skill Does

• Generate or refactor A2UI updateComponents and updateDataModel
• Output a unified Python transformation entry in DTO Component mode
• Iterate on existing files rather than rewriting everything from scratch each round
• Gate quality through design review and validation scripts

Execution Boundary

• Do not proactively search, read, borrow from, or imitate historical examples, old artifacts, sample pages, sample JSON, sample HTML, or screenshot outputs in the repository unless the user explicitly requests it
• By default, rely only on the user's current input, currently attached files, and this skill's own documentation
• If the user provides a DTO, do not hard-code business facts

First Principle: User Requirements First

• Global first principle: User requirements first
• When a feature explicitly requested by the user conflicts with a skill default rule, prioritize the user requirement
• Do not "pretend to comply with the skill"; explicitly record the conflict and apply a targeted exemption during the validation phase
• Exemptions are scoped only to items the user explicitly requested — never use them as an excuse to disable validation globally
• Choose an appropriate layout style based on the user's requirements and intent; using the same layout style and color scheme across multiple queries is forbidden

Query / Search Term Scenario Detection

Before entering mode selection, determine whether the user input is an information summary card scenario:

Trigger conditions: The user provides a natural language search query, place name, person name, event name, or concept word (e.g., "Snow in the Forbidden City", "West Lake", "Su Dongpo") and asks for an information card.

⚠️ CRITICAL WARNING — English model content inflation risk: When generating cards for query/search-term inputs in English, there is a strong model tendency to produce article-style content with long paragraphs, full narrative sections, and detail-page structures. This is always wrong for summary cards. Treat every word below as a hard constraint, not a suggestion.

Mandatory card shape for this scenario (non-negotiable):

• Structure locked to: Title → Core attributes (1–3) → Brief summary (≤ 2 lines) → Tag group → Optional CTA
• Main sections ≤ 3
• Body text ≤ 2 paragraphs; each paragraph ≤ 3 lines
• FORBIDDEN: Dynamic List child templates (i.e., children.componentId-driven template rows such as tips_item_template) — this is a detail-page structure, not a summary card
• FORBIDDEN: Full-width hero image (aspect-ratio: 16/9 + width: 100%) — this is a page header, not a card element
• FORBIDDEN: Expanding the card into an article or content detail page (multiple long body paragraphs + full lists)
• Total card height must not exceed 2/3 of screen height

Canonical layout patterns (choose one; do not invent new structures):

• Horizontal summary card: small thumbnail on the left + title / core metrics / tags / CTA on the right (suitable for POIs, attractions, products)
• Vertical summary card: title section at top + core metrics row (2–3 numeric metrics side by side) + one-line summary + tags + CTA (suitable for events, people, concepts)

Pre-generation self-check (mandatory before writing any JSON):

• [ ] Main sections ≤ 3?
• [ ] No dynamic List sub-templates?
• [ ] No full-width hero image?
• [ ] Body paragraphs ≤ 2, each ≤ 3 lines?
• [ ] Total height within 2/3 screen?

If any item fails → converge first or escalate to page explicitly. Never bypass.

Mode Selection

Before starting, determine:

1. Does the user want a component/card or a full page?
2. Has the user provided a DTO?

Default to generating a component / card for the user, unless the user explicitly says they want a full page.

Then enter exactly one of the following three modes:

Mode 1: DTO Component

Applicable when:

• The user has provided a DTO
• The user wants a component / card

Deliverables:

1. Python transformer code
2. updateComponents JSON
3. updateDataModel JSON

Unified entry function:

def build_component_payload_from_dto(dto: dict) -> tuple[dict, dict]:
    ...

Mode 2: Non-DTO Component

Applicable when:

• The user has not provided a DTO
• The user wants a component / card

Deliverables:

1. updateComponents JSON
2. updateDataModel JSON

Mandatory order (must not be reversed):

1. Output UI layout (updateComponents) first
2. Output data (updateDataModel) second

Mode 3: Non-DTO Page

Applicable when:

• The user has not provided a DTO
• The user wants a full page

Deliverables:

1. updateComponents JSON
2. updateDataModel JSON

Mandatory order (must not be reversed):

1. Output UI layout (updateComponents) first
2. Output data (updateDataModel) second

Supplementary rules:

• Only the three modes above are defined by default
• If the user provides a DTO but explicitly wants a full page, do not silently apply one of these modes; ask first whether to design the page as DTO-driven

Read Only What You Need

Do not read all sub-documents by default. Load only what the current task requires:

Additional notes:

• Load `reference/component-catalog.md` when you need to verify atomic components, charts, fields, allowed values, or style whitelists
• Load `reference/data-binding.md` when you need to verify path binding, template binding, or relative path rules
• Load `reference/component-design.md` when you need to verify component height budgets, card content budgets, or multi-column text budgets
• Load `reference/page-design.md` when you need to verify full-page structure, layout composition, or page-level sectioning

• Load `reference/spacing-elevation.md` when you need spacing scale, shadow elevation, or border radius guidance
• Load `reference/expressiveness-toolkit.md` when you need to add visual richness: inline color, color blocks, icons, opacity, pseudo-gradients
• Load `reference/design-review.md` when performing model-level design review after script validation passes

Output Persistence

Final artifacts should be written to files by default, and the user should be told the paths explicitly.

Priority order:

1. If the user specifies a directory or filename, save according to that
2. If the user provides an existing artifact directory, prefer saving near that context
3. Otherwise choose a clear, sensible, easy-to-find location

Default file naming:

• *_components.json
• *_datamodel.json
• *_transformer.py or *_vo.py

Non-DTO mode write order (mandatory):

1. Generate and save *_components.json first
2. Generate and save *_datamodel.json second

To save tokens:

• Write the first draft to disk immediately after generation
• If the user continues modifying, iterate on the existing file by default
• Each round of changes should edit the file and work from a diff — do not repaste the entire JSON in the conversation

Workflow

1. Read user input; confirm mode, data source, interaction requirements, and visual constraints
2. Load only the sub-documents the current task truly needs
3. Before formal output, explicitly list the layout rationale: at minimum describe the main sections, visual focal point, information rhythm, key horizontal relationships, and the role of images
4. Based on that layout rationale, draft an internal first version, then perform at least 1 explicit design improvement before proceeding to formal output
5. Output the first draft formally and write it to disk immediately (non-DTO mode: components before datamodel, mandatory)
6. Run `scripts/validate_a2ui.py` immediately; if it fails, fix the file directly and re-run until it passes
7. Only after the script passes for the first time, perform design quality review following `reference/design-review.md`; apply improvements directly to the on-disk file
8. After design review improvements, perform a dedicated "protected content abnormal wrapping" check on all horizontal layouts — prioritize checking whether short phrases, CTAs, ratings, times, and prices are being squeezed and broken by narrow fixed widths
9. If the model review modifies files, re-run the validation script; deliver only after it passes again
10. At delivery, clearly state the output file paths; if placeholder links were used, explicitly remind the user to replace them

When a "user explicitly required item conflicts with a rule":

• Use overrides.json to exempt only the conflicting checks at minimum scope
• Exempt only the relevant check; do not disable other validations as collateral

Non-Negotiables

Only truly irreplaceable business invariants that scripts cannot fully substitute are listed here: