Application Shell Layout
Relevant source files
The following files were used as context for generating this wiki page:
The Application Shell Layout defines the top-level structural framework of the HX-UI library. It establishes the visual identity and navigational hierarchy of the application, utilizing a system of outer margins and rounded panels to organize content. The layout ensures a consistent user experience by standardizing page headers, sidebar navigation, and content containers across different modules.
This architectural pattern is categorized as "Layout Components" (版式件) within the library, which specifically determines how a page is presented rather than providing low-level interactive primitives.
Sources: README.md:36-37, src/index.ts:13-14
Core Structural Architecture
The layout architecture relies on the AppFrame component to provide the primary container. This shell facilitates a consistent spacing strategy, typically involving outer margins and distinct rounded panels for different application areas.
The diagram above illustrates the relationship between the top-level AppFrame and its child layout components.
Sources: README.md:38, src/layout/AppFrame.tsx
Layout Components Summary
| Component | Description | Key Properties |
|---|---|---|
AppFrame | The main application wrapper providing margins and panel styling. | children |
PageHeader | A standardized header with title, description, and action area. | title, desc, right, extra, compact |
SidebarNavItemButton | A navigation entry for the sidebar with icons and badges. | item, active, onClick |
SettingSection | A container for grouped settings, often rendered as a card. | section, title, children |
DataTable | A structured data display with sticky headers and rounded corners. | columns, rows, maxHeight, bare |
Sources: src/layout/PageHeader.tsx:21-29, src/layout/SidebarNav.tsx:64-68, src/layout/SettingChrome.tsx:43-51, src/layout/DataTable.tsx:55-72
Navigation and Sidebar
The navigation system uses SidebarNavItemButton to render interactive links. These items support icons, text labels, and status badges. The visual design decouples the selection state from the button's internal drawing; the active state is indicated by font weight and color changes, while the background highlighting is managed by an external container to optimize performance during movement.
Sidebar Item Structure
Navigation icons are rendered using mask-image to follow the current text color (currentColor). This allows the icon to change color automatically when the item becomes active without requiring separate assets.
The flow shows how a sidebar item is composed and how visual states are applied.
Sources: src/layout/SidebarNav.tsx:39-44, src/layout/SidebarNav.tsx:75-84
Page Header and Content Alignment
The PageHeader component standardizes the top section of every page. It enforces specific alignment rules to maintain vertical rhythm and visual balance:
- Baseline Alignment: The title and the right-hand action area (e.g., buttons, search boxes) are centered along their middle axis (
items-center). This prevents shorter buttons from appearing to float above the text title. - Overflow Protection: Titles use truncation (
truncate) to prevent long text from pushing the right-hand actions to a new line, which would disrupt the page's vertical layout.
Sources: src/layout/PageHeader.tsx:7-16
Page Header Configuration
| Property | Type | Description |
|---|---|---|
title | ReactNode | The main page title (Required). |
desc | ReactNode | Subtext or explanation below the title. |
right | ReactNode | Action area for buttons or controls. |
extra | ReactNode | Additional row for breadcrumbs or tags. |
compact | boolean | Reduces spacing for use within cards or drawers. |
Sources: src/layout/PageHeader.tsx:21-29
Visual Styling and Design Tokens
The Shell Layout is driven by design tokens defined in tokens.css. This system ensures that the entire shell responds to theme changes without modification to the component logic.
- Color Scheme: Uses CSS variables like
--background,--foreground, and--cardfor structural elements. - Typography: Implements a standard scale for font sizes ranging from
--fs-3xs(9px) to--fs-4xl(26xl). - Layering: Manages Z-index levels through tokens such as
--z-sticky(10) for headers and--z-modal(50) for overlays.
Sources: src/tokens.css:17-38, src/tokens.css:186-218
Global Styles and Layout Constants
The layout enforces a 1px border for interactive controls instead of standard outlines (:focus-visible { outline: none; }). It also uses a custom overlay scrollbar that is transparent by default and only appears when a container is hovered or focused, preventing layout shifts during scrollbar activation.
Sources: src/tokens.css:96-100, src/tokens.css:103-116
Conclusion
The Application Shell Layout provides the foundational grid and navigational elements for the HX-UI ecosystem. By centralizing structural logic into components like AppFrame, PageHeader, and SidebarNav, the system maintains a rigid visual rhythm while allowing flexible content placement. The integration with design tokens ensures that these layout structures remain theme-agnostic and consistent across all modules.
Sources: README.md:36-39, src/index.ts:13-16