Admin React Interfaces

When this skill applies

Use this skill when building administrative React interfaces for VTEX Admin experiences.

Settings pages
Moderation tools
Internal dashboards
Operational forms and tables

Do not use this skill for:

storefront components
render-runtime blocks
route authorization design
backend service structure

Decision rules

Use VTEX official design systems for admin interfaces.
Prefer
```
vtex.styleguide
```
as the default choice for VTEX IO admin apps published to customers.
Accept
```
@vtex/shoreline
```
as an official VTEX design system, especially in internal back-office contexts.
Prefer core Styleguide layout patterns such as
```
Layout
```
,
```
PageHeader
```
, and
```
PageBlock
```
for page composition.
Prefer Styleguide building blocks for common admin needs:
```
Table
```
,
```
Input
```
,
```
Dropdown
```
,
```
Toggle
```
,
```
Tabs
```
,
```
Modal
```
,
```
Spinner
```
, and
```
Alert
```
.
Keep admin screens focused on operational clarity rather than storefront styling concerns.
Prefer explicit loading, empty, and error states for data-heavy admin pages.
Use button loading states and toast-based feedback for async actions so users can tell when a mutation starts, succeeds, or fails.
Prefer internationalized messages over hardcoded admin copy so labels and feedback can stay consistent across stores and locales.
Use tables, forms, filters, and feedback patterns that align with VTEX Admin conventions.
Prefer official design system components over custom clickable
```
div
```
or
```
span
```
patterns so focus behavior, keyboard navigation, and accessibility attributes remain correct by default.
For large lists and tables, prefer pagination and server-side filtering over loading everything into the browser and filtering in memory.
For search and filtering, prefer the search and filter patterns offered by the official design systems instead of inventing custom control behavior.
Keep labels, messages, and action copy in a single language per app and avoid mixing tones or languages on the same screen.
In forms, keep actions consistent: use a primary save action, an optional secondary cancel action when appropriate, and explicit feedback after submit.

Hard constraints

Constraint: Admin UIs must use VTEX design systems

Admin panel components MUST use VTEX official design systems.

Why this matters

VTEX Admin has a consistent design language. VTEX official design systems preserve that consistency, while generic third-party UI libraries create inconsistent visuals, styling conflicts, and review problems.

Detection

If you see Material UI, Chakra, Ant Design, or another generic third-party UI system in an admin app, STOP and replace it with VTEX design system patterns. Do not flag

@vtex/shoreline

as third-party.

Correct

tsx

import { Layout, PageHeader, PageBlock, Table } from 'vtex.styleguide'

tsx

import { Button, Table, EmptyState } from '@vtex/shoreline'

Wrong

tsx

import { DataGrid } from '@material-ui/data-grid'

Constraint: Admin screens must expose loading, empty, and error states

Operational interfaces MUST make data state visible to the user.

Why this matters

Admin users need reliable operational feedback. Silent blank screens are harder to support and diagnose than explicit states.

Detection

If a page loads remote data but renders nothing meaningful on loading, empty, or error cases, STOP and add explicit UI states.

Correct

tsx

if (loading) {
  return (
    <PageBlock>
      <Spinner />
    </PageBlock>
  )
}

if (error) {
  return (
    <PageBlock>
      <Alert type="error">Failed to load data. Please try again.</Alert>
    </PageBlock>
  )
}

Wrong

tsx

return <Table items={data?.items ?? []} />

Constraint: Admin actions must provide explicit user feedback

Mutations in admin screens MUST report success, failure, or pending state clearly.

Why this matters

Operational actions affect real store configuration and data. Users need immediate feedback to avoid repeated or ambiguous actions.

Detection

If a button triggers a write action with no feedback on result, STOP and add explicit feedback.

Correct

tsx

<Button isLoading={saving}>Save</Button>
showToast({ message: 'Settings saved successfully' })

Wrong

tsx

<Button onClick={save}>Save</Button>

Constraint: Data-heavy admin screens must stay bounded and navigable

Lists, tables, and search-heavy admin screens MUST use bounded rendering patterns such as pagination and should prefer server-side filtering when the API supports it.

Why this matters

Admin pages often deal with operational datasets that grow over time. Rendering too many rows at once or filtering only in memory creates poor performance and brittle UX.

Detection

If a page renders very large collections without pagination, or loads the full dataset into the browser just to filter locally, STOP and add bounded navigation or server-side filtering.

Correct

tsx

<Table items={items} />
<Pagination currentItemFrom={1} currentItemTo={10} totalItems={120} />

Wrong

tsx

const filtered = allItems.filter(matchesSearch)
return <Table items={filtered} />

Constraint: Interactive controls must use accessible semantics

Admin interactions MUST use accessible controls and should prefer official design system components instead of custom clickable non-semantic elements.

Why this matters

Keyboard navigation, focus handling, and screen-reader behavior are part of baseline admin usability. Non-semantic clickable elements make accessibility regressions much more likely.

Detection

If you see clickable

div

span

elements being used as primary controls where a button, link, or design system component should be used, STOP and replace them.

Correct

tsx

<Button variation="primary">Save</Button>

Wrong

tsx

<div onClick={save}>Save</div>

Admin builder structure

Admin pages in VTEX IO are exposed through the Admin builder:

Use the
```
admin/
```
folder to declare navigation and routes.
Use
```
admin/navigation.json
```
to define sections, subsections, and Admin navigation paths.
Use
```
admin/routes.json
```
to map each Admin path to a React component implemented under
```
react/
```
.
Use the
```
react/
```
folder to implement the page components used by Admin routes.

Practical rules:

Each entry in
```
admin/routes.json
```
should point to a real component in
```
react/
```
.
The route
```
path
```
should stay aligned with the navigation structure declared in
```
admin/navigation.json
```
.
Page components should use VTEX Admin layout patterns such as
```
Layout
```
,
```
PageHeader
```
, and
```
PageBlock
```
, or official Shoreline equivalents in internal contexts.

Example: navigation.json structure

admin/navigation.json

json

[
  {
    "section": "storeSettings",
    "subSection": "storeFront",
    "subSectionItems": [
      {
        "labelId": "admin/my-settings.navigation.title",
        "path": "/admin/app/my-settings"
      }
    ]
  }
]

Main fields:

```
section
```
/
```
subSection
```
: define where the link appears in the Admin navigation tree.

subSectionItems[].path

: should match the

path

declared in

admin/routes.json

```
titleId
```
/
```
labelId
```
: message IDs used to internationalize navigation labels.
```
adminVersion
```
: optional and only needed for compatibility between legacy and newer Admin experiences. Do not use it in the default example for new apps.

Example: tying Admin builder to a React page

admin/routes.json

json

{
  "admin.app.my-settings": {
    "component": "MySettingsPage",
    "path": "/admin/app/my-settings"
  }
}

react/MySettingsPage.tsx

tsx

import React from 'react'
import { Layout, PageHeader, PageBlock } from 'vtex.styleguide'

const MySettingsPage: React.FC = () => (
  <Layout pageHeader={<PageHeader title="My settings" />}>
    <PageBlock>
      {/* Page content goes here */}
    </PageBlock>
  </Layout>
)

export default MySettingsPage

Preferred pattern

Use VTEX design systems to keep operational state explicit and optimize for clarity over ornamental UI. Use

PageHeader

and

PageBlock

with Styleguide where appropriate, or equivalent official Shoreline patterns in internal contexts. Use

Spinner

Alert

EmptyState

for data states and

showToast

plus button loading states for async feedback. Use paginated tables for large datasets, prefer server-side filtering when possible, and keep form actions consistent with primary save and optional cancel behavior.

Common failure modes

Using third-party UI libraries in admin apps.
Omitting loading, empty, or error states.
Triggering mutations without visible feedback.
Rendering large tables without pagination or filtering everything only in memory.
Building clickable controls with non-semantic elements instead of accessible buttons or links.
Mixing languages or inconsistent copy style on the same admin screen.

Review checklist

Does the screen use VTEX official design systems (Styleguide or Shoreline), not generic UI libs?
Does the page use
```
PageHeader
```
and
```
PageBlock
```
layout patterns where appropriate (or Shoreline equivalents)?
Are loading, empty, and error states explicit?
Are large tables or lists paginated and filtered in a scalable way?
Are write actions safe and visible?
Are interactive controls using accessible semantics instead of clickable non-semantic elements?
Are labels and feedback messages internationalized instead of hardcoded?
Is the app using one consistent language and tone for labels and actions?
Does the UI look and behave like a VTEX Admin tool?

Reference

Admin apps - Admin builder context
Shoreline repository - Official VTEX Shoreline design system repository
Shoreline docs - Shoreline component and design system documentation

vtex-io-admin-react

NPX Install

SKILL.md Content

Admin React Interfaces

When this skill applies

Decision rules

Hard constraints

Constraint: Admin UIs must use VTEX design systems

Constraint: Admin screens must expose loading, empty, and error states

Constraint: Admin actions must provide explicit user feedback

Constraint: Data-heavy admin screens must stay bounded and navigable

Constraint: Interactive controls must use accessible semantics

Admin builder structure

Example: navigation.json structure

Example: tying Admin builder to a React page

Preferred pattern

Common failure modes

Review checklist

Reference