Use this when building interfaces with UnoCSS in any framework (React, Vue, Svelte, Solid, or plain HTML), from dense devtools panels to landing pages. Read core-design-read first to set the direction, then apply the token system plus the polish and anti-slop rules.
Core Rules
- Use semantic shortcuts (
bg-base, border-base, color-active, btn-action) instead of raw utility chains in markup.
- Design light and dark mode together. Core tokens must work in both themes.
- Name z-index layers (
z-top-nav, z-panel-content, z-drawer-content). Do not use raw z values in templates.
- Generate class-based utilities only (
class="..."). Avoid Attributify syntax in generated code.
- Keep icon/status class strings literal so UnoCSS can statically extract them (
// @unocss-include when needed).
- Use
font-mono + tabular-nums for technical values (paths, SHAs, counters, timestamps, percentages).
- For long paths and IDs, truncate visually but keep the full value in
title.
- Read the brief and set the three dials before choosing a look (core-design-read).
- Borders for dense or structural surfaces, layered shadows for elevated ones (features-micro-interactions).
- Zero em-dash and en-dash characters in any user-facing text (best-practices-anti-slop).
Starter shortcuts
A minimal semantic core. See core-starter-kit for the full uno.config.ts and base styles.
shortcuts: [
{
'color-base': 'color-neutral-800 dark:color-neutral-200',
'bg-base': 'bg-white dark:bg-#111',
'bg-secondary': 'bg-#eee dark:bg-#222',
'border-base': 'border-#8882',
'bg-active': 'bg-#8881',
'color-active': 'color-primary-600 dark:color-primary-300',
'border-active': 'border-primary-600/25 dark:border-primary-400/25',
'btn-action': 'inline-flex items-center gap-2 rounded border border-base px2 py1 op75 hover:op100 hover:bg-active disabled:pointer-events-none disabled:op30!',
'op-fade': 'op65 dark:op55',
'op-mute': 'op30 dark:op25',
'z-top-nav': 'z-60',
'z-panel-content': 'z-70',
'z-drawer-content': 'z-100',
},
]
Core References
| Topic | Description | Reference |
|---|
| Core Principles | Semantic tokens, dark mode parity, z-index naming, class-first output | core-principles |
| Starter Kit | Copy-paste UnoCSS starter config and base light/dark styles | core-starter-kit |
| Tokens and Combos | Token families, reusable class combinations, mobile-safe shell tokens | core-tokens-and-combinations |
| Design Read and Dials | Read the brief, declare a design read, set variance/motion/density dials | core-design-read |
Best Practices
Features
| Topic | Description | Reference |
|---|
| Data Presentation | Paths, icons, time, date, numbers, badges, buttons | features-data-presentation |
| Micro-Interactions | Radius, alignment, shadows, animation, numbers, outlines, hit areas | features-micro-interactions |
| Floating Vue Overrides | Shared Floating Vue setup and popper styling | features-floating-vue-overrides |
Advanced
