hiui-design

HiUI Typical Pages Skill

Positioning

This skill is the standard generation protocol and delivery governance control plane for HiUI React page engineering.page-task-plan.v1 remains the only top-level execution entry;generationRecipe is its internal forward generation sub-protocol; the delivery completion state is still determined by preflight-report.v1、hiui-page-governance-report.v1、acceptanceProfile and finalReportContract . The main narrative is \"generate correctly according to the recipe first, then confirm through acceptance\", not \"generate a version first, then correct deviations through acceptance\".

Standard typical page hits page-component + slot-fill , by default take minimal-doc fast path: prioritize consuming planner, scaffold, and slot contract, and no longer manually expand long governance documents; only complex pages, drifting pages, and formal acceptance scenarios escalate to the full rule chain.

legacy-host-compatible The main path is unified as project-certified carrier first -> page-component semantics -> explicit fallback. When the host undertaking fact holds, it should prioritize consuming the project-certified carrier or already-certified page components,managed-translation is retained only as an explicit fallback.runtime-bridged-page-component is merely a bridging semantic name in legacy for page-component , and does not introduce a parallel generation family; when hitting header , only carrier certification, page contract, and preflight can jointly prove that PageHeader stretch、extra right-docked and 60px rhythm owner do not drift, and only then does the main chain hold.

When communicating externally, separate the two things clearly: the legacy host main tree cannot be treated as generic @hiui-design/typical-page-shells directly mounted runtime, but that does not mean a legacy project cannot go through the ordinary typical page component main chain. As long as the planner has given page-component + runtime bridge + slot fill, it must be executed along that main chain, and \"cannot ad hoc direct shell import\" must not be misread as \"can only reference/fallback\".

Core Object Model

• page-task-plan.v1 is the only execution plan and fact exit; AI does not manually assemble mode、pageType、pageUnits、startFrom、requiredDocs、requiredActions or the key command chain.
• generationRecipe is introduced as an incremental sub-object of page-task-plan.v1 , and does not separately create a parallel top-level contract.
• generationRecipe only describes assembly order, asset mapping, slot boundaries, prohibited actions, and lightweight consistency checks; it does not repeatedly store facts that can be derived from pageComponent、baseMoldId, registry, or existing contracts.
• targetDeliverySemantics and currentExecutionState must be output in layers: the former answers \"once the plan holds, which managed delivery main chain should be followed to land it\", and the latter answers \"what is allowed to be executed at the current step\". When legacy is blocked, the former can still retain page-component + runtime bridge + slot fill target semantics, but the latter must expose only ResolveBlockingFacts。
• editableSlots、lockedRegions、pageComponent、baseMoldId should prioritize \"reference or derivation\", and not copy into the planner.
• runtimeBridgeProfile exists only as an additional resolution object for the legacy page-component path; it describes the runtime bridging strategy through rules/runtime-bridged-component-matrix.json , and does not redefine pageComponent、baseMoldId、lockedRegions or business slot facts.
• Project-level host pack、project-scoped page carrier and its certification results belong to runtime / asset facts, and by default are referenced by the plan through fields such as facts、assetResolution、pageComponent ; do not flatten and copy these facts into every page contract again.
• Carrier-critical layout facts, especially header 's stretch owner, actions docking, and vertical rhythm owner, are machine facts jointly consumed by contract + certification + preflight; they must not degrade into soft suggestions that exist only in explanatory documents.
• acceptanceProfile、preflight-report.v1、hiui-page-governance-report.v1、finalReportContract Continue to retain; do not downgrade or remove.
• requiredDocs is the default sole source for supplementary reading; its minimal structure is fixed as path、readMode、reason. Read readMode=required，reference / conditional only supplement reading when the corresponding scenario is matched.requiredActions is the default sole execution source; when there are no structured actions, prioritize using the compatible command fields, and do not extend the gate on your own.

Object model and field tiering:docs/generation/explainers/core-object-model.md

Standard Generation Protocol

Standard Generation Protocol only answers 4 questions:

• What skeleton to start from.
• What is the assembly order of key regions.
• Which areas allow business filling.
• What to do after each key step is completed inlineChecks。

generationRecipe.required includes at least by default:

• startingPoint
• assemblyOrder
• requiredAssets
• forbiddenMoves

generationRecipe.optional can be gradually completed by page type and complexity:

• slotFillPolicy
• regionOwnership
• inlineChecks

The first batch of recipes covers only high-frequency page types:

• table-page
• analytics-page
• edit/detail-page

Standard generation protocol supplementary reading:docs/generation/explainers/standard-generation-protocol.md

Guardrails

• This skill only handles HiUI React page engineering tasks; requirement refinement, end-to-end process orchestration, Figma writing / design draft generation, and general React refactoring must be handed off to the corresponding skill or ordinary code process.
• Page generation, rewriting, major changes, page type migration, and legacy system / screenshot translation must first obtain page-task-plan.v1; when there is no machine plan, conclusions, command chains, or completion states must not be manually assembled.
• blockingIssues / blockingReasons When non-empty, it must fail closed and only supplement facts; it must not generate pages, write contracts, run preflight, or output a completion state.
• Asset addition, completion, and updates can only go through the shipped public contract;add-asset / update-asset must be dry-run; write / force / asset type that are not shipped must not be executed.
• Without explicit authorization from the machine plan or an explicit request from the maintainer, deploy, upload, publish, sync, global sync, Feishu / bitable backend writes, release archive generation, or historical output overwrites must not be executed.
• For actions involving external services, backend agents, launch agents, daemons, or user configuration writes, the target scope, authorization source, and side effect boundary must all be verified before execution; if any condition is missing, execution must be refused.
• preflight failed, hard profile governance failed, source snapshot missing / low confidence,acceptance contract When provenance is missing, the final response must be blocked / failed.
• The open source version must not collect usage data and must follow PRIVACY.md present not_applicable、skipped or unavailable。

Generation Gates

• Pre-generation gates: project root, machine plan, capability profile, mode lock, pre-plan facts.
• Generation protocol gates: page-component availability, route ownership, slot boundaries, shell / adapter proof, analytics contract, business content boundaries, controlled extensions.
• legacy-host-compatible The hard gate truth for ordinary typical pages is uniformly consolidated into rules/legacy-host-hard-gates.json: the baseline is fixed as 4 hard gates, and when header is matched, header-layout-proof conditional gates are additionally added, so current common typical pages usually end up with 5 effective hard gates.styleBoundary、portalBoundary、runtimeSmoke is still triggered by risk; but header 's stretch / right-dock / rhythm owner is no longer just a styling suggestion, and the main path must be blocked when structured proof is missing.
• legacy-host-compatible Under this, if the planner has proven page-component ready and runtimeAdapterProof.status=available, the default execution semantics are page-component + runtime bridge + slot fill. Without the prerequisite of a legacy main tree direct shell import, only ad hoc standard-shell mount can be prevented; it cannot serve as a reason to arbitrarily downgrade to a compatible hand-assembled page, a reference default translation page, or a free fallback.
• The first two gatekeeping layers are part of "how to generate correctly" and are no longer mixed with the delivery-blocking tone.
• required level generationRecipe When a field is missing, do not assume or manually fill it in; it can only be blocked, or execute the fallback explicitly given by the plan.
• startingPoint cannot be parsed,requiredAssets unavailable, or assemblyOrder incomplete, it is not allowed to freely fall back to writing by hand on a blank page.
• Only when the plan explicitly gives managed-fallback、host-archetype or reference-or-scaffold as a legal fallback is degraded generation allowed.
• optional A missing field does not automatically block, but it must not be filled in falsely; when missing, execute according to the page-type default policy or existing rules.

Generation gatekeeping details:docs/generation/explainers/generation-gates.md

Delivery Gates

• preflight-report.v1 and hiui-page-governance-report.v1 continue to be the core judgment objects of the delivery confirmation layer.
• acceptanceProfile determines the acceptance scope;formal acceptance is the acceptance level, not the generation pipeline.
• finalReportContract continues to be retained for complete reporting and downstream compatibility.
• The delivery gate only handles "whether completion may be declared" and no longer dominates the generation narrative.
• If a certain type of issue is repeatedly exposed at the DeliveryConfirmation stage, it must be fed back first to generationRecipe or generation gates, rather than continuously appending new acceptance descriptions.

Delivery gatekeeping details:docs/generation/explainers/delivery-gates.md

Runtime Protocol

• The only source of truth for the runtime protocol is rules/runtime-contract.md; the only source of truth for the managed page governance protocol is rules/page-governance.md。
• rules/runtime-bridged-component-matrix.json is the only source of truth for legacy page-component bridging semantics; it only declares the bridge profile, runtime shell source, and thin bridge layer responsibilities, and does not duplicate mold / slot / ownership facts.
• rules/legacy-host-hard-gates.json is the only machine source of truth for legacy ordinary typical page hard gatekeeping orchestration;SKILL.md, the generation gatekeeping description, and the planner only reference it, and no longer each hand-write the number of gates.
• Basic project facts (mode, capabilities, route ownership, i18n, governance availability) and basic asset facts (certified page component, mold, adapter catalog) should be consumed internally by the plan and exposed through fields such as facts、assetResolution、projectMode、targetPage.routeOwnership .
• For an already integrated project, the .local-context/hiui-design/outputs/project-integration-state.json written during the integration stage belongs to a project-level runtime input fact.PlanTask It should preferentially reuse it and project-mode.json, and directly enter page planning; only when that state is missing, corrupted, or conflicts with current facts should it fall back to host profile / mode detection diagnosis.
• project-integration-state.json.integrationReady=true It holds only when, during the integration stage, it has already been verified that the project-certified carriers' componentSource、componentShell and componentSupportSources can both resolve to real project source code; if either is missing, integration must remain integrationReady=false, and the page generation stage may only expose the blocking reason, and must not defer the missing carrier issue until the business page implementation stage before it is discovered.
• For legacy-host-compatible，integrationReady=true , the definition itself includes that the project-level required rollout has been completed: by default, first cover table-basic、table-stat、tree-table、tree-split、drawer-form、 drawer-detail、full-page-edit、full-page-detail these carrier-first-required page types;feedback-status and data-visualization may be added later as a deferred batch. When a project-certified carrier for the required batch is missing, the integration state must explicitly output requiredLegacyPageTypes、deferredLegacyPageTypes、certifiedLegacyPageTypes、 missingRequiredLegacyPageTypes and legacyRolloutCoverageStatus=blocked, and treat the current project as legacy integration incomplete, rather than "already integrated but rollout to be added later at the page stage".
• integrationReady By default, only answer "whether the project has completed hiui-design integration" and "whether the legacy host bridge already has project-level acceptance facts." For legacy, this completion state already includes required carrier batch ready;rules-only / host-integration Whether the standard typical page components are available belongs to the asset facts and page-type support facts consumed by the planner, and should not be collapsed into a general project integration failure.
• project-scoped host pack / carrier facts also belong to runtime input facts. For legacy projects, they should preferably be authenticated once during the project integration / capabilities stage, and then reused by the page generation stage, rather than repeatedly explaining the host boundary on every page.
• The Agent explicitly reads capabilities, mode lock, authentication files, or catalog only when the plan is missing / conflicting / troubleshooting / maintenance.
• host-qualification-facts.v1 It is only a runtime input facts contract, not an execution plan; it only carries the legacy host boundary, bridge / adapter facts, and provenance.
• typical-page:runtime-smoke It only records "browser-level evidence on the current source snapshot" and is not responsible for declaring the page complete; preflight / doctor It only aligns that evidence with the current source snapshot and identifies whether it is stale; only typical-page:finalize-page can flip the delivery status to finalized。

Task Lifecycle

The documentation narrative layer is unified as:

LocateProjectRoot -> PlanTask -> ResolveBlockingFacts -> BuildGenerationRecipe -> GenerateByRecipe -> InlineConformanceChecks -> DeliveryConfirmation -> OutputDeliverySummary

• PlanTask: by default, first consume project-level integration facts, then supplement capabilities / route / asset-resolution; do not treat "confirm the repository structure / confirm whether hiui-design has been integrated" as a visible prerequisite step for every page task. By default, the planner must also split generation-time and delivery-time actions into generationInputs、inlineChecks、deliveryChecks, to avoid moving the heavy acceptance criteria forward into generation guidance.
• PlanTask The output layer must simultaneously expose targetDeliverySemantics and currentExecutionState: the former describes the target delivery main chain, and the latter describes the currently allowed actions, blocking phase, and blocker priority.requiredCommands、requiredActions and canStartImplementation must be consistent with currentExecutionState , and a blocked plan must no longer appear externally as if page generation can begin directly.
• PlanTask One of the primary responsibilities for ordinary legacy typical pages is to clearly expose both "prohibit ad hoc direct attachment of the legacy main tree to the standard shell" and "allow the page-component + runtime bridge + slot fill main chain"; the failure of direct shell import must not be expressed as a fallback that general page-components are unavailable.
• If project-level integration facts already exist but integrationReady=false，PlanTask must fail closed, directly echo the integration blocking reason; do not attempt to treat page generation, initial scaffold, or page-level preflight as a remediation path for integration / legacy bridge completeness. Page-type-level page-component whether assets are ready continues to be determined independently by the planner's assetResolution / projectTypicalPageSupport , rather than being rewritten as general integration debt.
• When integrationReady=false the reason comes from incomplete legacy required rollout,PlanTask by default should place bootstrap-target-project at the head of the ResolveBlockingFacts queue; this indicates that the current project's legacy integration / bootstrap has not yet been completed, rather than "an already integrated project adding a rollout step during the page stage." If a route ownership blocker is also hit, then append the route repair action after it, and do not skip the project-level carrier rollout to enter page implementation directly.
• BuildGenerationRecipe: convert generationStrategy into a standard assembly protocol.
• GenerateByRecipe: generation behavior must follow assemblyOrder、requiredAssets、forbiddenMoves; freely inventing page shells, region owners, or slot order is not allowed.
• InlineConformanceChecks: a lightweight consistency check after key assembly steps, without moving heavy acceptance forward.
• DeliveryConfirmation: terminal confirmation layer, internally continues to inherit WriteContract、Preflight、PreviewReady、FormalAcceptance、RuntimeGovernance. The open-source edition does not handle usage telemetry / stats closeout; the final reply only closes out page delivery and quality verification status.
• This is a narrative rename, not an immediate external interface rename; public scripts, report objects, and fields retain at least one migration cycle alias.

The detailed lifecycle still uses rules/page-task-lifecycle.md as the single source of truth.

First Turn Output

The first-round reply for page tasks defaults to showing generation information first, rather than laying out acceptance fields first. Default priority fields:

• generationStrategy
• generationRecipe
• generationInputs
• inlineChecks
• primaryGenerationAsset
• assemblyOrder
• requiredAssets
• extensionPolicy
• requiredActions

Expand for complex or strict scenarios:

• deliveryChecks
• acceptanceLevel
• acceptanceProfile
• finalReportContract

If non-typical-overlay or single-page-compositeis hit, the first round must also directly expose layoutStrategy、layoutArchetype、nonTypicalScope、mandatoryComponents、compositionGuardrails、strategyEvidence and ownershipPlan; these are generation input facts, not check notes added after delivery.

If non-standard prototype screenshots, legacy system screenshots / URLs / source code are hit, in the first round output according to docs/generation/ai-kickoff-template.md Output kickoffType=pre-plan-facts, explaining only visual-translation-brief.v1 and the necessary host-qualification-facts.v1 status.

Truth Index

• Machine plan entry, success signals, and failure signals:scripts/README.md
• Fast-path execution entry and supplementary reading order:rules/QUICK-START.md
• Public CLI contract:scripts/public-cli-contracts.json
• Runtime protocol:rules/runtime-contract.md
• Page task lifecycle:rules/page-task-lifecycle.md
• Failure recovery matrix:rules/failure-matrix.md
• Generation constraints:rules/generation-rules.md
• Data visualization primary/secondary/style machine policy:rules/chart-semantic-policy.json、rules/data-visualization-layout-policy.json
• Page component and mold registry:rules/page-component-registry.json、rules/page-mold-registry.json
• runtime bridge profiles：rules/runtime-bridged-component-matrix.json
• legacy hard gates：rules/legacy-host-hard-gates.json
• runtime delivery policy:rules/runtime-delivery-policy.json
• adapter registry:rules/adapter-registry.json
• contract constraints and summary:rules/contract-regions.md
• Page governance and source snapshot / acceptance contract:rules/page-governance.md
• Acceptance checklist:rules/validation-checklist.md
• Forward verification and success metrics:docs/validation/generation-recipe-forward-tests.md
• Page component policy and certification:docs/generation/page-level-components.md、docs/generation/component-certification.md
• explainers (explanation layer, not source of truth):docs/generation/explainers/README.md
• Page header geometry and host baseline:docs/generation/figma-reference.md
• Legacy host translation:docs/generation/legacy-host-compatibility.md
• Visual / legacy system pre-plan facts:docs/generation/visual-to-hiui-translation.md
• Atypical pages:docs/generation/non-typical-pages.md
• Charts and data visualization:docs/generation/figma-page-rules.md、docs/generation/figma-pages/data-visualization.md
• usage stats：PRIVACY.md

In the default read-only plan, requiredDocs; first consume readMode=required, then supplementarily read reason items according to reference / conditional hit status. Do not traverse the entire package of docs/、rules/、templates/、manifests/。

Final Report

• The final reply defaults to outputting a lightweight delivery summary based on deliverySummaryProfile .
• For complex / high-risk scenarios, strict acceptance, legacy migration, truly atypical cases, complex data visualization,preflight / smoke failures, then enter finalReportContract / final-page-report.v1。
• final-page-report.v1 should preferentially reuse existing facts from the managed page contract / workflow to determine whether the page has been generated, whether it is stale, and whether formal finalize has ever been completed; do not require the upper layer to repeatedly manually fill in the same set of statuses.
• The default reading order of the final report is: how the page was generated -> which primary assets and slots were used -> which areas inherit / which areas are business-filled -> current delivery confirmation status.
• Status fields must be fully retained, but no longer occupy the center of primary reading.
• If unable to run typical-page:render-final-report, it must still present page status, preflight status, formal acceptance status, usage stats status, executed actions, changed files, verification commands, and remaining risks.