plan-ui-change

Plan a Blazor UI Change

When asked to build a complex UI feature, plan the component decomposition first, then immediately implement it. A single monolithic page component is almost never the right answer — break the UI into focused, composable components.

Planning Workflow

Step 1 — Map the Visual Regions

Read the request and identify every distinct visual region. Each region that has its own data, behavior, or layout responsibility is a candidate component.

Draw the component tree:

InventoryDashboard          (page — owns data, orchestrates layout)
├── StockSummaryBar         (read-only stats: total items, low-stock count, value)
├── InventoryFilters        (search box, category dropdown, stock-level toggle)
├── InventoryTable          (sortable table of products)
│   └── InventoryRow        (single product row with inline edit/delete)
└── AddProductForm          (slide-out form for new products)

Rules for identifying components:

• Distinct responsibility — a region owns its own state or behavior → separate component
• Repeated structure — items in a list, cards in a grid → extract the item template
• Independent interactivity — a section that handles user input separately from its siblings → separate component
• Size — any section that would exceed ~150 lines of markup on its own → split it

Step 2 — Classify Each Component

For every component in the tree, determine:

A page component that exceeds ~200 lines of combined markup + code is too large. If your estimate puts a single component above that, split further.

Step 3 — Design Data Flow

Identify the state owner for each piece of data, then map how it flows:

Rules:

• Data always flows down through [Parameter]
• Events always flow up through EventCallback<T>
• The page/parent owns the data and passes filtered/transformed views to children
• Children never mutate parameters — they notify the parent via callbacks
• If data must cross more than 2 levels without intermediate components needing it, use a cascading value or a scoped service

Step 4 — Identify Reuse Opportunities

Before creating a new component, check if an existing component in the project can serve the purpose. Look for:

• Existing list-item components that match the structure
• Shared filter/search components already in the project
• Generic components (e.g., DataTable<T>, Pagination) that accept templates

If a component will be used in more than one page, place it in a Shared/ or Components/ folder.

Step 5 — Order the Implementation

Build bottom-up — leaf components first, then parents that compose them:

1. Models/DTOs — define the data shapes
2. Services — data access, business logic (interface + implementation)
3. Leaf components — components with no children (InventoryRow, StockSummaryBar)
4. Container components — components that compose leaves (InventoryTable, InventoryFilters)
5. Page component — wires everything together, registers routes
6. Configuration — DI registration, render mode setup

Each component should be independently compilable. Never reference a component that doesn't exist yet.

Output Format

Present the plan briefly, then immediately proceed to implement — never stop at just the plan or ask for confirmation before writing code. The plan is a thinking tool, not a deliverable.

After outputting the plan, immediately begin implementing the components in the order listed. Do not wait for approval or ask "shall I proceed?" — the plan is a guide for you to follow, not a proposal for the user to approve.

Anti-Patterns to Avoid

Guidelines

• Plan briefly, then implement. Write a concise component table and data flow map, then immediately create the .razor files — never stop at just the plan.
• Prefer many small components over one large one. A component with a single clear purpose is easier to understand, test, and reuse.
• State ownership is the first decision. Before writing fetch logic, decide which component owns the data.
• Build bottom-up. Create leaf components first so parent components can reference them immediately.
• Name components after what they render, not what they do internally: ProductCard not ProductRenderer, OrderFilters not FilterHandler.