Design System & UnoCSS Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Design System and UnoCSS integration provide a lightweight, high-performance styling architecture for the Zephyr project. Zephyr utilizes an atomic CSS approach powered by UnoCSS and a multi-layered design token system managed through Style Dictionary. This system replaces traditional heavy frontend frameworks with native JavaScript and utility-first CSS to achieve a minimal footprint and maximum rendering efficiency.
Sources: README_en.md, FEATURES.md, AUDIT_REPORT.md:271-275
Core Architecture
The styling architecture follows a "Zero Framework" philosophy. It uses native Web technologies to eliminate Virtual DOM overhead and reduce the supply chain attack surface.
Technical Stack
| Component | Technology | Role |
|---|---|---|
| CSS Engine | UnoCSS (presetWind4) | On-demand atomic CSS generation |
| Design Tokens | Style Dictionary | Multi-layer token pipeline (Primitive → Semantic → Component) |
| UI Components | Native JS + HTML | Framework-less component implementation |
| Graphics | Canvas 2D | High-performance real-time traffic rendering |
Sources: README_en.md, FEATURES.md, landing.html:361-365
Styling Data Flow
The following diagram illustrates how styles are processed from design tokens to final browser rendering.
The design system passes through a token pipeline that generates CSS variables, which are then integrated with the UnoCSS utility engine.
Sources: AUDIT_REPORT.md:25-30, FEATURES.md
Design Token System
Zephyr organizes design decisions into three distinct layers to ensure consistency and maintainability.
Token Layers
- Primitive Tokens: Define raw values for colors, spacing, and typography.
- Semantic Tokens: Assign meaning to primitives, such as
surface-page,text-primary, orfocus-color. - Component Tokens: Apply semantic tokens to specific UI elements like buttons, inputs, and cards.
Sources: FEATURES.md, AUDIT_REPORT.md:46-55
Radius and Elevation System
The system enforces a 4-level corner radius strategy to distinguish between different UI depths:
- Control: 8px (Buttons, Inputs)
- Surface: 12px (Cards, Panels)
- Overlay: 16px (Modals, Dialogs)
- Full: 9999px (Pills, Badges)
Sources: FEATURES.md, AUDIT_REPORT.md:41-45
UnoCSS Integration
Zephyr migrated from Tailwind CSS to UnoCSS to leverage an instant, on-demand atomic CSS engine. The configuration uses presetWind4 and supports native dark mode via the class strategy.
Configuration and Build
The integration scans src/**/*.{html,js} files for utility classes and generates a single optimized CSS file. The build process utilizes the @unocss/cli with a custom configuration file (uno.config.js).
Sources: AUDIT_REPORT.md:15-25, FEATURES.md
Component Short-circuits (Shortcuts)
UnoCSS shortcuts define reusable utility combinations to keep HTML templates clean and semantically meaningful.
| Shortcut | Description |
|---|---|
surface-1 | Base background level |
surface-2 | Raised background level |
surface-3 | Elevated background level |
panel | Standard container styling |
panel-interactive | Containers with hover/active states |
Sources: AUDIT_REPORT.md:73-77
State and Accessibility
The design system incorporates comprehensive states and accessibility (a11y) features as core requirements.
Component State Matrix
Components like buttons and form controls implement a full state matrix:
- Focus-visible: Unified outline system with platform-specific adapters.
- Disabled: Opacity reduction and cursor guards (
cursor: not-allowed). - Loading:
aria-busystate integration with CSS-based spinners and keyframe animations. - Reduced Motion: Global overrides to disable decorative animations for users with motion sensitivity.
Sources: AUDIT_REPORT.md:95-107, FEATURES.md, apps/desktop/src/index.html:158-160
Transition and Motion
Standardized timing tokens ensure uniform motion across the application.
--zephyr-time-standard: Used for most transitions (hover, active).--zephyr-time-page: Used for page entry and exit animations.
Sources: AUDIT_REPORT.md:108-112, apps/desktop/src/index.html:18-24
Layout and Responsive Design
Zephyr uses a transparent, frameless window architecture. The layout is primarily driven by Flexbox and Grid utilities.
UI Scaling System
The system supports interface scaling from 0.5x to 2.0x. Scaling is implemented via CSS transform: scale() on the root container, with logic to correct positioning for absolute elements like dropdowns and context menus.
Sources: FEATURES.md, apps/desktop/src/index.html:435-442
Theme Support
The system supports dark/light mode switching and custom accent colors.
Themes are applied by toggling attributes on the <html> element, which triggers updates to CSS custom properties defined in the semantic token layer.
Sources: landing.html:314-319, apps/desktop/src/index.html:1-5, FEATURES.md
Conclusion
The Design System and UnoCSS integration provide Zephyr with a robust, scalable, and lightweight UI framework. By combining a structured token pipeline with an on-demand CSS engine, the project maintains high visual standards while minimizing runtime performance costs and security risks associated with third-party frontend frameworks.