base
├── normal (default state)
│   ├── fg    # Primary text
│   ├── bg    # Primary background
│   └── border # Default border
├── master (accent/brand)
│   ├── fg    # Text on accent
│   ├── bg    # Accent color
│   └── alt   # Secondary accent
├── content (content areas)
│   ├── fg, bg, border
│   ├── selection, hover, focus, selected
├── states
│   ├── disabled, pressed, focus, hover, selected
└── feedback
    ├── error, warning, info, danger

font-family: 
  -apple-system,           /* macOS */
  BlinkMacSystemFont,      /* macOS Chrome */
  "Segoe UI",              /* Windows */
  "Microsoft YaHei",       /* Windows CJK */
  "Noto Sans",             /* Linux */
  "Helvetica Neue",        /* Fallback */
  sans-serif;

/* Scrollbar track */
width: 10px;           /* Vertical */
height: 10px;          /* Horizontal */
background: transparent;
margin: 2px;

/* Scrollbar handle */
min-height: 40px;
min-width: 40px;
background: rgba(128,128,128, 0.3);
border-radius: 4px;

/* Handle states */
:hover   → rgba(128,128,128, 0.5)
:pressed → rgba(128,128,128, 0.7)

/* No arrow buttons */
::add-line, ::sub-line {
  width: 0; height: 0;
}

padding: 6px 12px;
min-width: 64px;
border-radius: 4px;
border: 1px solid [border-color];
background: transparent;

:hover   → background: [hover-bg]
:pressed → background: [pressed-bg]
:focus   → border-color: [accent]
:default → border-color: [accent]

padding: 4px;
margin: 2px;
border: none;
border-radius: 4px;
background: transparent;

:hover   → background: [hover-bg]
:pressed → background: [pressed-bg]
:checked → background: [selected-bg]

padding: 4px 8px;
min-height: 28px;
border: 1px solid [border-color];
border-radius: 4px;
background: [content-bg];

:hover → border-color: [hover-border]; background: [hover-bg]
:focus → border-color: [accent]; background: [focus-bg]

border: 1px solid [border-color];
border-radius: 6px;
padding: 4px 0;
background: [menu-bg];

/* Menu items */
::item {
  padding: 6px 16px 6px 8px;  /* Tighter left padding */
  margin: 0 4px;
  border-radius: 4px;
}
::item:selected {
  background: [selected-bg];
}

/* Icons */
::icon {
  margin: 4px 4px 4px 8px;  /* Balanced icon spacing */
}

/* Checkbox/Radio indicators */
::indicator {
  width: 16px;
  height: 16px;
  margin-left: 6px;  /* Tight spacing to text */
}

/* Separator */
::separator {
  height: 1px;
  margin: 4px 12px;
}

/* Tab item */
::tab {
  padding: 6px 16px;
  border: none;
  border-bottom: 2px solid transparent;  /* Indicator */
}
::tab:selected {
  border-bottom-color: [accent];
  background: [content-bg];
}
::tab:hover:!selected {
  background: [hover-bg];
}

border: none;
background: [content-bg];
show-decoration-selected: 0;  /* Branch area not highlighted */

::item {
  padding: 4px 8px;
  /* No margin/border-radius - full-width selection avoids
     visual gaps with branch indicators */
}
::item:hover {
  background: [hover-bg];
}
::item:selected {
  background: [selected-bg];
}

padding: 6px 10px;
border: none;
border-radius: 6px;
background: [tooltip-bg];
color: [tooltip-fg];

/* Title bar */
::title {
  background: [title-bg];
  border-radius: 6px;
  padding: 4px;
}

/* Title bar buttons (close, float) */
::close-button, ::float-button {
  border: none;
  border-radius: 4px;
  padding: 2px;
}
::close-button:hover, ::float-button:hover {
  background: [hover-bg];
}
::close-button:pressed, ::float-button:pressed {
  background: [pressed-bg];
}

border-radius: 8px;  /* If platform supports */
background: [dialog-bg];

height: 6px;
border: none;
border-radius: 3px;
background: [groove-bg];

::chunk {
  border-radius: 3px;
  background: [accent];
}

/* Groove */
::groove:horizontal {
  height: 4px;
  border-radius: 2px;
  background: [groove-bg];
}

/* Handle */
::handle:horizontal {
  width: 16px;
  height: 16px;
  border-radius: 8px;  /* Circular */
  background: [accent];
  margin: -6px 0;
}

themes/[theme-name]/
├── palette.json        # Color definitions
├── interface.qss       # Qt stylesheet
├── web.css             # Markdown preview styles
├── highlight.css       # Code syntax highlighting
├── text-editor.theme   # Editor colors
└── *.svg               # Theme-specific icons