Office Web Ui System

Office Web UI System

Overview

Use this skill to build or evolve dashboard-style management interfaces with office-style structure, strong visual hierarchy, and reusable composition while keeping the result portable across frameworks and component libraries.

Activate this skill only for admin dashboards, internal dashboards, back-office consoles, reporting systems, customer/user management systems, CRM/ERP-style management pages, or similarly operational products where users repeatedly scan, filter, compare, edit, approve, or manage records.

Do not activate this skill for general UI/UX polish, marketing pages, landing pages, portfolios, brand sites, editorial sites, ecommerce product pages, games, consumer app screens, or one-off visual redesigns unless the user explicitly says the work is for an admin, dashboard, internal tool, back-office, or management system.

This skill is written as the source of truth in SKILL.md so it can be reused across AI tools that support skills, prompt packs, or custom instructions. Tool-specific metadata should stay in adapter files only and must not change the core workflow.

Prioritize two outcomes at the same time:

• deliver a clear, high-density, professional interface
• make important UI regions easy for humans and AI agents to identify by name

This skill is not only for shells and navigation. Use it when the management product needs a polished:

• admin dashboard or reporting page
• customer, user, order, content, ticket, or account management page
• CRUD/list page inside an admin or back-office system
• workspace/detail page for operational records
• form or wizard page for internal workflows
• stat card system tied to operational metrics
• filter/search/action region for managing records
• table-heavy admin page with stronger UI states

When the user asks for a page to feel "beautiful", "modern", "premium", or "like a real web app", first confirm the task is an admin/dashboard/management surface before applying this skill. Do not turn unrelated UI work into generic dashboard boilerplate.

Default expectation:

• choose a page archetype
• choose a visual weight
• define a clear hierarchy for title, summary, actions, filters, and main data
• use only a few intentional visual ideas instead of decorating every surface
• preserve usable width and dark-mode readability

Workflow

1. Inspect before designing

Inspect the real project first:

• identify the framework, CSS strategy, and component library
• identify whether the app already has a shell pattern for topbar, sidebar, cards, panels, tables, filters, and page headers
• preserve the existing visual language when it is coherent

Read these references as needed:

• references/visual-language.md
• references/navigation-and-panels.md
• references/page-type-playbook.md
• references/framework-adaptation.md

2. Choose the page archetype before styling

Before choosing gradients, cards, or hero treatments, classify the page into one of these archetypes:

• dashboard/report
• CRUD/list
• workspace/detail
• form/wizard

This decision is mandatory. The page archetype controls density, action placement, and how expressive the page should be.

Read:

• references/page-type-playbook.md

3. Choose the visual weight

Decide whether the page should be:

• restrained
• balanced
• expressive

Use this to control how much gradient, glass, overlap, and decorative depth the page gets.

Rules:

• prefer restrained surfaces on table-heavy CRUD pages
• use expressive hero or glass treatment only when it clarifies hierarchy
• do not overuse hero sections on pages where the table or form is the real focus

Read:

• references/visual-language.md

4. Add semantic locator structure early

Before deeper UI changes, add or normalize semantic classes on important regions.

Read references/locator-class-contract.md and apply these rules:

• important UI regions must have readable semantic classes
• do not rely on Tailwind-only class strings as the only way to identify a major region
• keep semantic classes stable and specific enough that a user can point to the correct area

Use utility classes freely for low-level styling, but pair them with semantic wrappers for:

• page containers
• shells
• sidebars and topbars
• flyouts
• panels and docks
• toolbar and filter rows
• table wrappers
• action bars

5. Compose the shell and page regions

After the archetype and visual weight are chosen, compose the page in this order: 1. shell or page root 2. page title and context 3. actions, filters, and summary regions 4. primary data surface 5. optional support surfaces such as side panels or utility docks

Use portable recipes for the recurring pieces:

• page hero or header band
• stats card grid
• summary strip
• action cluster
• filter bar
• search input
• table wrapper
• mobile record cards
• empty, loading, and error states
• utility side panels or inspector panels

Read:

• references/component-recipes.md

Before implementing, be able to state:

• what the page is for in one sentence
• which region should dominate the screen
• which 2 or 3 components are carrying the page's visual identity
• which regions must remain restrained so the page stays usable

6. Build with office-web-app defaults

When the project does not already define a better pattern, use these defaults:

• topbar as a transparent shell with readable pill surfaces
• desktop navigation with expanded sidebar or icon rail + flyout
• a page header that explains context before controls
• stats and summaries grouped near the page title, not scattered randomly
• floating panels and docks that do not steal content width unless the UX requires it
• large interaction targets for dense admin workflows
• clear hover, focus, active, loading, and empty states
• strong dark-mode readability, not color inversion for its own sake

Read:

• references/visual-language.md
• references/navigation-and-panels.md
• references/component-recipes.md

7. Stay behavior-first, not library-first

Describe and implement UI in terms of behavior and structure first.

Do not overfit patterns to PrimeVue or any single library. Library-specific handling belongs in adaptation details only.

Read references/framework-adaptation.md when:

• the project uses PrimeVue
• the project uses a different component library
• scoped CSS or third-party internals make dark mode or overrides brittle

8. Verify the page reads like a product, not a wireframe

Before handoff, check:

• the page has one obvious focal region
• stat cards, filters, and table surfaces belong to one coherent family
• the page does not look like interchangeable SaaS boilerplate
• the decorative treatment stops before it hurts density or readability

9. Verify density, dark mode, and locator clarity

Run the bundled scanner before asking the user where a UI element lives:

python3 scripts/scan_ui_locators.py /path/to/repo

Useful modes:

python3 scripts/scan_ui_locators.py /path/to/repo --match layout-sidebar
python3 scripts/scan_ui_locators.py /path/to/repo --prefix quote-create-page__
python3 scripts/scan_ui_locators.py /path/to/repo --json

Use the scanner to:

• map semantic classes to files and line numbers
• detect ambiguous major-region classes
• confirm that a proposed class name is discoverable and specific enough

Also verify:

• the chosen visual weight still fits the page archetype
• table-heavy pages keep usable width
• empty and loading states feel designed, not placeholder-only
• dark mode readability is preserved on the true rendered nodes

Rules

• Preserve an existing good design language instead of forcing one visual language everywhere.
• Choose the page archetype before styling.
• Choose the visual weight before adding expressive treatments.
• Prefer semantic wrappers for important regions even in utility-first codebases.
• Keep major interactive regions identifiable by class name.
• Use modifiers like --collapsed, --active, --open, --rail for state, not entirely different base names.
• Favor layout patterns that maximize usable width for table-heavy admin work.
• Prefer restrained surfaces on CRUD and other dense table pages unless stronger expression clearly improves hierarchy.
• Use hero sections, overlap cards, and glass surfaces deliberately, not by default.
• Use a small number of strong visual ideas per page instead of many weak decorative effects.
• Make the page feel product-specific through hierarchy, grouping, and summary design before adding more color or motion.
• Keep hover/focus targets generous on dense interfaces.
• Treat dark mode as a first-class state during design and verification.
• Keep examples portable; adapt primitives to the host stack instead of cloning one framework's exact API.

References

• references/visual-language.md
• references/navigation-and-panels.md
• references/page-type-playbook.md
• references/component-recipes.md
• references/locator-class-contract.md
• references/framework-adaptation.md

Resources

scripts/

• scripts/scan_ui_locators.py: scan semantic UI locator classes, report files and line numbers, and warn when major-region classes are ambiguous.

Component Recipes

Use this reference after choosing the page archetype. These recipes describe portable UI patterns, not library-specific APIs.

Recipe selection rule

• Pick the smallest set of recipes that produces a clear page.
• A good office page usually has:
• one title/context region
• one summary region if needed
• one controls region
• one dominant working surface
• If every recipe appears on the same page, the page is probably overdesigned.

Page hero / header band

Purpose

Give the page a clear title region with context, status, and top-level actions.

Required regions

• title and subtitle or status context
• optional icon or product marker
• action cluster

Visual treatment

• restrained pages use a compact header band or elevated title region
• expressive pages may use gradient, glass, blur, or layered backgrounds
• keep readability higher than decoration
• the hero should establish the page story in under one screenful

Interaction states

• actions must have obvious hover and focus states
• badges or status pills must remain readable in both themes

When to use

• use on dashboards, reports, and important module entry pages
• use a compact version on CRUD and form pages

When to avoid

• avoid a large hero on pages where the table or form is the only real focus

Semantic locator examples

• inventory-report-page__hero
• customers-page__header

Stats card grid

Purpose

Show a small set of high-signal metrics in a scannable block.

Required regions

• grid wrapper
• repeated stat cards
• label, value, and optional trend or caption

Visual treatment

• cards may use subtle gradients or tinted surfaces
• one stronger accent per card is enough; do not decorate every layer
• reserve the strongest color treatment for the most important or exceptional metric
• one lead card or one stronger metric is often better than four equal cards

Interaction states

• hover may slightly elevate cards if they are actionable
• selected or drill-down cards need a persistent active state

When to use

• dashboards, reports, and contextual summaries above dense content

When to avoid

• avoid large stat grids when a page only needs one inline summary

Semantic locator examples

• sales-dashboard-page__stats-grid
• sales-dashboard-page__stat-card

Summary strip inside hero

Purpose

Keep 2-5 key summary items close to the page title on summary-first pages.

Required regions

• strip wrapper
• repeated summary items

Visual treatment

• lightweight glass or tinted surfaces work well inside a hero
• keep the strip compact so it supports the title instead of replacing it

Interaction states

• usually static
• if interactive, each item needs a full-row hover and focus treatment

When to use

• reports and dashboards with a strong context header

When to avoid

• avoid when the page already has a large stats grid directly below the header

Semantic locator examples

• inventory-report-page__summary-strip
• inventory-report-page__summary-item

Action cluster

Purpose

Group top-level page actions by intent.

Required regions

• primary action slot
• secondary action group
• optional refresh or export controls

Visual treatment

• primary action should visually lead
• secondary actions can share a quieter surface or pill group

Interaction states

• hover, active, loading, and disabled must be obvious
• avoid placing destructive actions in the same visual emphasis as safe actions

When to use

• any page with top-level actions

When to avoid

• do not mix row-level actions into this cluster

Semantic locator examples

• customers-page__action-bar
• warehouse-stats-page__hero-actions

Filter bar

Purpose

Collect search, filters, presets, and quick scopes into one clear working region.

Required regions

• filter wrapper
• grouped filter controls
• optional quick presets
• optional apply and clear actions

Visual treatment

• filters should read as a working surface separate from row actions
• use spacing and grouping before adding more color
• quick presets should look like workflow tools, not like navigation tabs unless they truly behave like navigation

Interaction states

• active filters should have a clear selected treatment
• loading and disabled states should remain readable

When to use

• CRUD pages, reports, and data-heavy modules

When to avoid

• do not create a large filter bar for pages with only one simple search field

Semantic locator examples

• customers-page__filter-bar
• product-items-report-page__filter-bar

Search input

Purpose

Provide a high-visibility search control without blending into row actions.

Required regions

• search wrapper
• icon or label
• input field

Visual treatment

• the search input should feel like a stable tool, not a stray form field
• icon-led inputs are fine when spacing keeps the text readable

Interaction states

• focus ring or border change must be obvious
• placeholder contrast must remain readable in dark mode

When to use

• inside filter bars or page tool regions

When to avoid

• avoid hiding the only important filter behind a tiny icon button

Semantic locator examples

• customers-page__search
• orders-page__search

Table wrapper

Purpose

Give dense data tables a strong, readable container with room for states and supporting controls.

Required regions

• wrapper surface
• optional header or toolbar
• table body
• empty/loading state region

Visual treatment

• keep the wrapper restrained so the table remains dominant
• use stronger borders, header styling, and row states instead of decorative backgrounds
• wrapper chrome should support scanning, not compete with the data

Interaction states

• row hover should tint the whole actionable area
• selected and active states must survive without hover
• loading and empty states should look intentional

When to use

• any table-heavy admin surface

When to avoid

• avoid putting tables directly on the page background with no clear containment

Semantic locator examples

• customers-page__table-wrap
• inventory-report-page__report-table-wrap

Mobile record cards for dense datasets

Purpose

Replace or supplement wide tables on smaller screens with scannable record cards.

Required regions

• mobile list wrapper
• repeated record cards
• inline action row

Visual treatment

• keep cards compact and label/value driven
• maintain the same data hierarchy as the table
• actions should stay discoverable without making each card visually noisy

Interaction states

• row actions need generous hit targets
• card hover is optional; focus and pressed states still matter

When to use

• CRUD pages where wide columns collapse poorly on mobile

When to avoid

• avoid duplicating both full table and cards at the same breakpoint without a clear rule

Semantic locator examples

• customers-page__mobile-record-list
• customers-page__record-card

Empty, loading, and error states

Purpose

Make non-happy states feel intentional and informative.

Required regions

• state wrapper
• icon or visual marker
• primary message
• optional recovery action

Visual treatment

• empty states can be light and inviting
• loading states should align with the surrounding surface
• error states should feel serious without overwhelming the page
• use the same design family as the surrounding page, not a disconnected placeholder block

Interaction states

• retry or recovery actions need the same quality as primary buttons

When to use

• every table, dashboard module, and async support panel

When to avoid

• avoid raw placeholder text such as "No data" with no context

Semantic locator examples

• customers-page__empty-state
• warehouse-stats-page__loading-state
• quote-workspace-page__error-state

Utility side panels / inspector panels

Purpose

Support the main workspace with notes, history, filters, or record inspectors.

Required regions

• panel root
• header
• content
• optional collapse handle or tabs

Visual treatment

• panel should feel secondary to the main workspace
• floating or docked surfaces work well when width must be protected

Interaction states

• collapse, expand, hover-reveal, and close behavior must be explicit
• panel tabs or sections should have clear active states

When to use

• workspace/detail pages and advanced reporting tools

When to avoid

• avoid permanent wide side panels for optional content on dense CRUD pages

Semantic locator examples

• quote-workspace-page__activity-panel
• order-review-page__inspector-panel

Recipe usage rule

Pick only the recipes the page actually needs. A polished office page usually comes from a few well-composed regions, not from stacking every pattern at once.

Framework Adaptation

Use this reference to carry the same UI rules across different stacks.

General rule

Translate the behavior and structure first. Bind it to the current component library second.

For every page recipe:

• keep the page archetype choice
• keep the semantic locator skeleton
• keep the interaction contract
• adapt the primitives to the host stack

PrimeVue projects

• Wrap important PrimeVue-heavy regions in semantic classes even when PrimeVue already provides internal classes.
• Use scoped CSS carefully; PrimeVue internals often need stronger selectors.
• For dark mode in scoped styles, target the actual runtime selector and real PrimeVue nodes.
• Keep semantic wrappers outside complex PrimeVue markup so agents can still locate regions reliably.
• Map recipes like this:
• hero or header band: regular template markup plus PrimeVue buttons, tags, and badges
• stats cards: native markup or Card only if it does not fight the layout
• filter bar: PrimeVue inputs, selects, date pickers, and buttons inside one semantic wrapper
• table wrapper: semantic wrapper around DataTable, with empty and loading slots treated as designed states
• Do not let PrimeVue defaults decide the whole visual hierarchy. PrimeVue is the primitive layer, not the page-composition layer.

Non-PrimeVue Vue projects

• Keep the same locator and shell rules.
• Use semantic wrappers around headless components, custom components, and slot-heavy structures.
• Do not replace clear semantic wrappers with composable-only indirection.
• Keep recipe structure visible in the template even if the internals come from composables or slots.

React and other SPA stacks

• Apply the same page, shell, panel, and flyout naming contract.
• Use className semantic wrappers for important regions even if styling is utility-first.
• If the project uses CSS Modules, expose stable semantic hooks where agents and humans still need shared naming.
• For shadcn or headless stacks:
• use Card, Tabs, Sheet, Table, and similar primitives as surface building blocks
• keep page hero, stats grid, filter bar, and table wrapper as explicit composition regions above those primitives
• prefer composition wrappers over editing third-party base components
• In React admin apps, avoid defaulting to a symmetric grid of identical Card components for every dashboard.
• If using shadcn, create the page personality with composition, spacing, and wrapper structure rather than by modifying base ui/* primitives.
• If the stack uses charts, keep chart containers visually subordinate to the page title and summary region.

Laravel / Blade / server-rendered UIs

• Add semantic classes directly to Blade partials and layout shells.
• Keep shared shell regions in predictable partials or layout templates.
• Treat repeated partials like reusable regions with stable names.
• For page recipes:
• render the page skeleton in Blade sections or partials first
• keep action bars and filter bars as named partials when repeated
• keep repeated record cards or summary cards under stable feature-prefixed class names
• Avoid server-rendered markup that hides all meaningful structure behind generic includes with no semantic wrapper.

Utility-first codebases

• Utility classes are fine for visual expression.
• They are not enough as the only locator for a major UI region.
• Pair utility-heavy markup with one stable semantic class at the important boundary.

Component-library codebases

• Use the library for primitives, not for naming the whole UI.
• Wrap third-party primitives with semantic region classes.
• Keep behavior contracts portable:
• flyout alignment
• hit area size
• hover coverage
• reserved padding around collapsed tabs or handles
• filter grouping
• table containment
• designed empty and loading states

Migration heuristic

When moving an office-style admin UI pattern into another project: 1. keep the interaction contract 2. keep the locator contract 3. adapt the visual layer to the host system 4. only reuse the reference visual treatment directly if the host app has no stronger language

Recipe translation shortcuts

• page hero / header band
• Vue: semantic wrapper with library buttons or tags inside
• React: semantic wrapper with Button, Badge, Card, or plain div structure
• Blade: semantic wrapper with partials for actions and status blocks
• stats card grid
• Vue: repeat semantic card wrappers with utility classes
• React: map over data into Card or div-based stat blocks
• Blade: repeated component partials are fine if each card still carries a stable class
• filter bar
• Vue: place all controls in one __filter-bar wrapper
• React: keep filters in one div or toolbar region; avoid scattering them across components
• Blade: render the full filter row together so the working region stays obvious
• table wrapper
• Vue: wrap DataTable or table markup in a semantic container
• React: wrap headless or shadcn table pieces in a semantic container
• Blade: wrap native tables or included partials the same way

React / shadcn composition shortcuts

• Use layout wrappers such as dashboard-page, dashboard-page__hero, dashboard-page__stats-grid, and dashboard-page__table-wrap as plain div structure around shadcn primitives.
• Prefer building stat cards as one shared wrapper pattern plus small internal variants instead of many unrelated custom cards.
• Use Sheet or Dialog for mobile or temporary inspector behavior, and Card or bordered panels for persistent desktop support regions.
• Keep Tabs for true view switching or scoped filters, not as decoration for ordinary action clusters.

Locator Class Contract

Use this reference to make important UI regions easy to find and discuss.

Goal

Users and agents should be able to say “the flyout header”, “the quote side panel”, or “the topbar tools pill” and land in the right file quickly.

Rule

Important UI regions must have readable semantic classes.

Do not rely on raw utility strings alone for:

• page roots
• shell regions
• topbars and sidebars
• flyouts
• panels and docks
• toolbar and filter rows
• search wrappers
• table wrappers
• action groups
• major cards or grouped card stacks

Recommended naming shapes

• Page root: feature-page
• Page section: feature-page__section
• Panel root: feature-panel
• Panel subregion: feature-panel__header
• Dock root: feature-dock
• Shell element: layout-topbar-tools-pill
• State modifier: feature-panel--collapsed

Preferred patterns

• Use one stable base name per feature or shell region.
• Use __ for structural subregions.
• Use -- for state or variants.
• Keep names human-readable.
• Prefer nouns that describe UI purpose, not implementation detail.

Good examples

• layout-sidebar-flyout
• layout-topbar-status-pill
• sales-dashboard-page
• sales-dashboard-page__hero
• sales-dashboard-page__stats-grid
• sales-dashboard-page__filter-bar
• sales-dashboard-page__table-wrap
• inventory-report-page__summary-strip
• quote-create-page__side-panel-stack
• quote-workspace-dock__section-actions
• technical-orders-page__filter-bar

Bad examples

• div-3
• main-box
• content-wrapper-2
• a page root identified only by min-h-screen bg-gray-50 dark:bg-gray-900
• a flyout identified only by absolute top-0 right-0 rounded-xl shadow-lg

Uniqueness policy

• Major-region classes should usually map to one place within a page or shell.
• Repeated classes are acceptable for:
• list items
• table rows
• cards in a repeated collection
• stat cards inside one named stats grid
• mobile record cards inside one named record list
• repeated controls inside one component family
• If a major-region class appears across unrelated files, rename it to be feature-specific.

Locator-first implementation rule

When editing a major UI region: 1. add or confirm the semantic locator class 2. group related markup under that class 3. apply utilities or component-library props underneath it 4. verify the class can be found by scanner and by repo search

Practical heuristics

• Prefer feature prefix for page-local components.
• Prefer layout- prefix for global shell components.
• Prefer *-page__* for page-specific regions.
• Prefer *-panel, *-dock, *-toolbar, *-filter-bar, *-table-wrap for high-signal regions.
• Prefer *-page__hero, *-page__stats-grid, *-page__summary-strip, *-page__action-bar for repeated dashboard and report structures.

Scanner usage

Run:

python3 scripts/scan_ui_locators.py /path/to/repo

Use the scanner before asking the user where something lives.

Navigation And Panels

Use this reference when building shells, side navigation, flyouts, docks, and utility panels.

Topbar contract

• Treat the topbar as a transparent shell when the app already supports layered surfaces.
• Group actions into stable pill clusters.
• Left pill usually contains brand and primary shell toggle.
• Right pills usually contain status, quick toggles, notifications, and user actions.
• Readability should come from pill surfaces, not from a single solid full-width bar.

Sidebar contract

• Desktop sidebar may have:
• expanded mode for full navigation
• icon rail mode for space-saving navigation
• Mobile and tablet should keep drawer or overlay behavior unless the host product already has a different mobile pattern.

Icon rail + flyout

• Rail icons represent root groups, not every page-level route.
• The icon button itself must have a large click and hover target.
• Hover, focus, or click may open the flyout on desktop.
• The flyout should align to the hovered rail icon instead of snapping to sidebar top.
• The gap between rail and flyout must be minimal to avoid a dead zone.
• The flyout must float over content, not push the main workspace horizontally.

Flyout content

• Use a floating card surface with blur, border, radius, and restrained shadow.
• Include a small header with:
• root group icon
• group label
• optional short navigation hint
• Menu items must be full-width rows, not text-sized inline links.
• Use generous hit areas for dense internal navigation.
• Hover and focus should tint the entire row, not only the label.
• Active route state must stay visible without hover.

Side utility panels

• Use side panels for history, notes, filters, inspectors, and similar supporting tools.
• The main workspace must remain dominant.
• If a panel competes with a table-heavy workspace, support collapse or hover-reveal behavior.
• Collapsed panels may leave behind a narrow visible handle or tab.
• When collapsed, reserve enough padding so the handle does not cover critical content.
• If the panel state is a user preference, persist it per user when reasonable.

Docks

• Docks work well for summaries, tabs, actions, and compact secondary controls.
• Use docks to keep workflow controls nearby without stealing workspace height.
• Group related controls into clear sections with semantic wrappers.

Closing behavior

• Flyouts and temporary panels should close on outside click or Escape when appropriate.
• Hover-driven overlays should allow a small grace period so users can move into the panel without flicker.

Anti-patterns

• Flyout fixed at the wrong vertical anchor
• Tiny hover targets in dense menus
• Panels that permanently consume workspace width for optional information
• Hidden handles that overlap content with no reserved spacing
• Overlay behavior on desktop that feels like a mobile drawer

Page Type Playbook

Use this reference to decide how a page should be composed before choosing detailed styling.

Mandatory step

Choose one page archetype before styling:

• dashboard/report
• CRUD/list
• workspace/detail
• form/wizard

This choice controls layout, density, action placement, and visual intensity.

Visual intensity scale

• Restrained: mostly neutral surfaces, minimal decoration, emphasis on clarity and width
• Balanced: one expressive area plus restrained working surfaces
• Expressive: stronger gradients, glass, overlap, and richer stat treatments where context benefits from it

Do not choose intensity in isolation. Match it to the page archetype.

Dashboard / report

Use when

• the page summarizes many metrics or trends
• the page combines high-level context with charts, cards, or a report table
• users need orientation before drilling into detail

Default structure

• page root
• optional hero or header band
• summary strip or stats grid near the title
• filters and export actions
• charts, report modules, or report table

Recommended intensity

• Balanced by default
• Expressive only when the page is genuinely summary-first

Actions

• primary actions live in the page header area
• secondary actions and quick ranges live near filters
• export belongs with report controls, not mixed into row actions

Hero / overlap / glass

• Hero is appropriate when it clarifies the reporting context
• Hero summary cards can live inside the hero if they remain readable
• Overlap is optional; use it only when the hero and main content are visually distinct

Responsive behavior

• collapse multi-card summary grids cleanly
• keep header actions wrapping into rows on smaller screens
• charts may stack before tables on mobile

Anti-patterns

• decorative hero with no useful summary
• oversized hero that pushes critical report controls below the fold
• dashboard cards with no hierarchy or no clear difference between primary and secondary metrics

Semantic class examples

• sales-dashboard-page
• sales-dashboard-page__hero
• sales-dashboard-page__summary-strip
• sales-dashboard-page__stats-grid
• sales-dashboard-page__report-table-wrap

CRUD / list

Use when

• the page is mainly for searching, filtering, sorting, or batch-operating on records
• the table or record list is the primary workspace

Default structure

• page root
• restrained header band or compact page header
• action cluster
• filter bar and search
• table wrapper
• mobile record cards if the data needs a narrower presentation

Recommended intensity

• Restrained by default
• Balanced only when the module needs stronger status context

Actions

• create, refresh, import, and batch actions live above the filter bar or beside the title
• row actions stay inside the table or mobile cards

Hero / overlap / glass

• use only a light header band or restrained hero
• avoid large expressive hero treatments on dense table pages
• keep the table visually dominant

Responsive behavior

• filters wrap into rows without hiding primary actions
• tables may switch to record cards on small screens
• maintain clear pagination and bulk action access

Anti-patterns

• huge decorative hero above a simple table
• filters visually mixed with row actions
• cramped search and filter controls with tiny click targets

Semantic class examples

• customers-page
• customers-page__header
• customers-page__action-bar
• customers-page__filter-bar
• customers-page__table-wrap
• customers-page__mobile-record-list

Workspace / detail

Use when

• the page centers on a single record plus supporting tools
• users need inspectors, notes, histories, docks, or related panels while working

Default structure

• page root
• contextual header
• main workspace
• support panel stack, dock, or inspector region
• optional summary cards for the active record

Recommended intensity

• Balanced by default
• Restrained for highly operational tools

Actions

• primary record actions stay near the page header
• local actions stay inside the panel or section they affect
• inspector actions stay inside the side panel, not in the global topbar

Hero / overlap / glass

• usually avoid a large hero
• a restrained contextual header or elevated title region is enough
• use floating support panels or docks when they preserve main workspace width

Responsive behavior

• support panels collapse, dock, or move below the main workspace
• critical record information remains visible without opening every panel

Anti-patterns

• optional panels permanently consuming too much width
• one giant undifferentiated page with no main vs support hierarchy
• forcing mobile drawer behavior on desktop inspectors

Semantic class examples

• quote-workspace-page
• quote-workspace-page__main
• quote-workspace-page__side-panel-stack
• quote-workspace-page__dock
• quote-workspace-page__activity-panel

Form / wizard

Use when

• the page is mainly about data entry, review, and submission
• the user is progressing through one or more sections with validation states

Default structure

• page root
• compact context header
• form sections or step panels
• sticky or repeated action bar when needed
• optional summary or debug region

Recommended intensity

• Restrained by default
• Balanced only when the form needs stronger onboarding context

Actions

• save, continue, submit, and cancel remain close to the form context
• do not bury primary form actions inside unrelated side content

Hero / overlap / glass

• avoid expressive hero by default
• if used at all, keep it compact and supportive

Responsive behavior

• form fields should stack cleanly
• action bars remain reachable without forcing excessive scrolling
• step indicators wrap or collapse without losing clarity

Anti-patterns

• decorative page header that competes with validation and field hierarchy
• important submit actions only at the very bottom of a long wizard
• mixing debug or support content directly into the main form flow

Semantic class examples

• order-create-page
• order-create-page__header
• order-create-page__form-sections
• order-create-page__action-bar
• order-create-page__debug-panel

Selection heuristics

• If the table is the main product, choose CRUD/list.
• If metrics and summaries lead the story, choose dashboard/report.
• If one record plus supporting tools dominate the screen, choose workspace/detail.
• If validation and structured entry dominate the screen, choose form/wizard.

When a page has mixed traits, choose the archetype for the primary task and borrow only the needed secondary recipes.

Visual Language

Use this reference for the visual defaults behind the skill.

Core direction

• Favor modern minimalism with professional density.
• Keep interfaces clean, high-signal, and data-first.
• Use depth deliberately: blur, subtle gradients, soft shadows, glass surfaces.
• Preserve strong hierarchy with spacing, contrast, and grouping instead of noisy decoration.
• Prefer interfaces that feel intentional over generic dashboard boilerplate.

Visual hierarchy

Build office pages in this order: 1. shell first 2. page title and context second 3. actions and filters third 4. data surface fourth

If decoration competes with that order, reduce the decoration.

Expressive vs restrained

• Restrained pages use mostly neutral surfaces, light tinting, and minimal decorative depth.
• Balanced pages allow one expressive region, usually the page header or summary area.
• Expressive pages may use stronger gradients, glass, overlap, and richer stat cards, but only when they help users orient quickly.

Choose expressive treatment sparingly:

• dashboards and reports can support it
• table-heavy CRUD pages usually should not
• forms and workspace tools should stay clearer than they are dramatic

Make it feel like a product

• Give each page a visual point of view, not just a collection of components.
• Usually that point of view comes from one of these:
• a strong title and summary band
• a distinct stats system
• a disciplined filter and table composition
• a clear main-workspace vs support-panel relationship
• Do not try to make every component special. Pick a few signature regions and let the rest support them.

Shell and page composition

• Treat office apps as shells, not isolated pages.
• Use a stable navigation shell first, then build page content inside it.
• For table-heavy pages, bias toward full-width layouts.
• For content-heavy pages, use constrained widths only when readability benefits.
• Use overlap, hero, and elevated content cards only when they improve hierarchy without wasting space.

Surfaces

• Use card, pill, panel, and flyout surfaces with soft borders and clear separation.
• Keep radii generous on major containers.
• Prefer translucent or layered surfaces over flat, lifeless blocks when the app already supports that language.
• Do not stack heavy shadows everywhere; reserve stronger elevation for overlays, flyouts, and active surfaces.
• When using glass, keep text contrast and edge definition strong enough that the surface still reads as a container.

Gradients, glass, and decoration

• Use gradients to define major context regions, not every component.
• One gradient header plus restrained content surfaces is often stronger than many tinted cards.
• Decorative shapes, blurs, and glow effects should stay behind content and never obscure labels or controls.
• Overlap cards are useful when they clarify the transition from page context to working surface.
• If the host app already uses flat surfaces, adapt the reference style into softer borders and tinting instead of forcing glass everywhere.

Stat card coloring

• Give each stat card one visual idea: status tint, accent icon, or trend treatment.
• Use semantic color families intentionally:
• blue or indigo for default metrics
• green for healthy or positive metrics
• amber for warnings
• red for risk, loss, or destructive metrics
• Avoid rainbow dashboards where every card fights for equal attention.
• Reserve the strongest accent for the most important metric or exceptional condition.

Dashboard aesthetics

• Keep one anchor metric or summary region more prominent than the rest.
• Mix scale intentionally:
• one larger summary band or lead card
• a supporting grid of quieter cards
• Use repetition to make the page feel designed:
• consistent radii
• repeated icon container shapes
• repeated internal spacing rhythm
• If charts are present, keep them subordinate to the page story instead of letting the page become chart clutter.

Rhythm and spacing

• Major page sections should feel block-based and deliberate, not evenly padded by habit.
• Use tighter spacing inside working surfaces and more generous spacing between major regions.
• Let title, summary, filters, and table read as separate bands of information.

Density

• Admin/internal apps may be dense, but interaction targets must remain forgiving.
• On compact tools, prioritize usable width for the primary workspace.
• Secondary information belongs in side panels, docks, or collapsible surfaces when possible.

Interaction states

• Hover must be obvious on actionable rows, tiles, and menu items.
• Focus must remain visible for keyboard users.
• Active route or selected state must survive without hover.
• Loading, empty, and error states should feel designed, not bolted on.

Dark mode

• Verify real readability in both light and dark mode.
• Use dark translucent surfaces, not flat black slabs.
• For custom CSS in scoped styles, target the actual runtime selector and real component internals.
• Inspect computed styles on the true rendered node when overrides seem correct but do not apply.

Good defaults for internal web apps

• Clear page title and status context
• Action clusters grouped by intent
• Search and filters visually distinct from row actions
• Strong table wrappers for data-heavy pages
• Utility panels that can collapse without breaking the main workspace
• Designed empty, loading, and error states that fit the surrounding page
• Restrained working surfaces underneath any expressive header treatment

Anti-patterns

• Utility-only markup on important layout regions
• Huge hero treatments on pages that are mostly tables
• Hero sections used by default even when a compact header would be clearer
• Every card using a different gradient or accent treatment
• Pages where all summary cards have identical visual weight
• Weak hover contrast on dense list items
• Glass, blur, and shadow applied to every layer
• Stat cards with random accent colors and no hierarchy
• Full-width solid bars where pill grouping would be clearer
• New visual directions that ignore the host app’s established language