mirror of
https://github.com/willmiao/ComfyUI-Lora-Manager.git
synced 2026-06-10 04:49:24 -03:00
f51f125cf1
- Add semantic OKLch color tokens with light/dark themes - Add typography, spacing, effects, breakpoints, z-index tokens - Refactor base.css with backward-compatible aliases - Add prefers-reduced-motion support - Add MIGRATION.md for Phase 2 component audit
143 lines
6.3 KiB
Markdown
143 lines
6.3 KiB
Markdown
# Lora-Manager UI Token Migration Guide
|
|
|
|
## Overview
|
|
|
|
The design token system has been created in `static/css/tokens/`. `base.css` now imports the tokens and provides backward-compatible aliases for existing component CSS.
|
|
|
|
## Token Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `tokens/colors.css` | OKLch color primitives + semantic light/dark tokens |
|
|
| `tokens/typography.css` | Font stacks, type scale, weights, line heights |
|
|
| `tokens/spacing.css` | 4px-base grid with legacy aliases |
|
|
| `tokens/effects.css` | Border radius, shadows, transitions |
|
|
| `tokens/breakpoints.css` | Named breakpoint variables |
|
|
| `tokens/z-index.css` | Stacking context scale |
|
|
| `tokens/index.css` | Aggregator that imports all token files |
|
|
|
|
## Backward Compatibility
|
|
|
|
Old variable names in component CSS still work via aliases in `base.css`:
|
|
|
|
| Old Name | Maps To |
|
|
|----------|---------|
|
|
| `--bg-color` | `--bg-base` |
|
|
| `--text-color` | `--text-primary` |
|
|
| `--text-muted` | `--text-secondary` |
|
|
| `--card-bg` | `--surface-base` |
|
|
| `--border-color` | `--border-base` |
|
|
| `--lora-accent` | `--color-accent` |
|
|
| `--lora-surface` | `--bg-elevated` |
|
|
| `--lora-border` | `--border-subtle` |
|
|
| `--space-1` (8px) | `--space-1-legacy` |
|
|
| `--border-radius-base` | `--radius-lg` |
|
|
|
|
## Phase 2: Component Audit Checklist
|
|
|
|
Below are the hardcoded values found across component CSS that should be replaced with tokens.
|
|
|
|
### Critical Fixes (P0)
|
|
|
|
- [ ] **card.css line 441**: `.base-model { background: #f0f0f0; }` → use `--bg-hover` or new `--surface-variant`
|
|
- [ ] **card.css line 369**: `.favorite-active { color: #ffc107 !important; }` → use `--favorite-color` (already defined in tokens)
|
|
- [ ] **layout.css line 134**: `.control-group button.favorite-filter i { color: #ffc107; }` → use `--favorite-color`
|
|
- [ ] **header.css lines 233-250**: Hardcoded dark theme colors (`#3a3a3a`, `#888888`, `#555555`) → use `--bg-disabled`, `--text-secondary`, `--border-base`
|
|
|
|
### Spacing Normalization (P1)
|
|
|
|
Replace hard pixel values with token equivalents:
|
|
|
|
- [ ] `padding: 4px 10px` → `padding: var(--space-1) var(--space-3)`
|
|
- [ ] `gap: 6px` → `gap: var(--space-1-legacy)` or `gap: var(--space-2)`
|
|
- [ ] `gap: 8px` → `gap: var(--space-2)`
|
|
- [ ] `gap: 12px` → `gap: var(--space-3)`
|
|
- [ ] `padding: 15px` → `padding: var(--space-4)`
|
|
- [ ] `padding: 16px` → `padding: var(--space-4)`
|
|
- [ ] `margin-top: 2px` → `margin-top: var(--space-0-5)`
|
|
- [ ] `padding: 2px 6px` → `padding: var(--space-0-5) var(--space-2)`
|
|
- [ ] `border-radius: 50%` → `border-radius: var(--radius-full)`
|
|
|
|
### Shadow Standardization (P1)
|
|
|
|
Replace hardcoded shadows with token equivalents:
|
|
|
|
- [ ] `box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05)` → `box-shadow: var(--shadow-xs)`
|
|
- [ ] `box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05)` → `box-shadow: var(--shadow-sm)`
|
|
- [ ] `box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1)` → `box-shadow: var(--shadow-md)`
|
|
- [ ] `box-shadow: 0 3px 5px rgba(0, 0, 0, 0.08)` → `box-shadow: var(--shadow-lg)`
|
|
- [ ] `box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15)` → `box-shadow: var(--shadow-xl)`
|
|
- [ ] `box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08)` → combine or add new token
|
|
|
|
### Typography Normalization (P1)
|
|
|
|
Replace scattered font sizes with type scale:
|
|
|
|
- [ ] `font-size: 0.8em` → `font-size: var(--text-xs)`
|
|
- [ ] `font-size: 0.85em` → `font-size: var(--text-sm)`
|
|
- [ ] `font-size: 0.9em` → `font-size: var(--text-sm)`
|
|
- [ ] `font-size: 0.95em` → `font-size: var(--text-md)`
|
|
- [ ] `font-size: 1.1em` → `font-size: var(--text-lg)`
|
|
- [ ] `font-size: 11px` → `font-size: var(--text-xs)`
|
|
|
|
### Breakpoint Normalization (P2)
|
|
|
|
Replace magic numbers with named breakpoints:
|
|
|
|
- [ ] `@media (min-width: 2150px)` → `@media (min-width: var(--bp-ultrawide))`
|
|
- [ ] `@media (min-width: 3000px)` → `@media (min-width: var(--bp-4k))`
|
|
- [ ] `@media (max-width: 768px)` → `@media (max-width: var(--bp-mobile))`
|
|
- [ ] `@media (max-width: 1200px)` → `@media (max-width: var(--bp-desktop))`
|
|
|
|
### Z-Index Cleanup (P2)
|
|
|
|
Replace magic z-index values with tokens:
|
|
|
|
- [ ] `z-index: 2` / `z-index: 3` / `z-index: 4` in card.css → use `--z-base` + calc
|
|
- [ ] `z-index: 200` in header.css (hamburger dropdown) → use `--z-dropdown`
|
|
|
|
### Remaining Hardcoded Colors (P2)
|
|
|
|
- [ ] `rgba(0, 184, 122, 0.05)` and `#00B87A` in import-modal.css → use `--color-success`
|
|
- [ ] `rgba(255, 255, 255, 0.12)` in card.css (base-model-label background) → use token
|
|
- [ ] `rgba(255, 255, 255, 0.25)` in card.css (separator) → use `--border-inverse`
|
|
- [ ] `rgba(0, 0, 0, 0.5)` and `rgba(0, 0, 0, 0.7)` in card.css (toggle blur btn) → use `--bg-overlay` variants
|
|
- [ ] `rgba(46, 204, 113, 0.3)` and `rgba(231, 76, 60, 0.3)` in card.css → use success/error tokens
|
|
|
|
## New Tokens Added
|
|
|
|
The following tokens were added beyond the existing system:
|
|
|
|
| Token | Value | Use Case |
|
|
|-------|-------|----------|
|
|
| `--color-accent-hover` | oklch(58% 0.28 256) | Hover states for accent buttons |
|
|
| `--color-accent-subtle` | accent @ 12% opacity | Subtle accent backgrounds |
|
|
| `--color-accent-border` | accent @ 25% opacity | Accent borders |
|
|
| `--color-accent-transparent` | accent @ 60% opacity | Glow effects, pulse animations |
|
|
| `--bg-hover` | oklch(95% 0.02 256) / dark: oklch(35% 0.02 256) | Hover backgrounds |
|
|
| `--bg-disabled` | #f5f5f5 / dark: #3a3a3a | Disabled input backgrounds |
|
|
| `--bg-overlay` | oklch(0% 0 0 / 0.75) | Modal overlays, gradients |
|
|
| `--surface-hover` | oklch(95% 0.02 256) / dark: oklch(35% 0.02 256) | Card/panel hover |
|
|
| `--favorite-color` | #d4a017 | Accessible gold for favorites |
|
|
| `--shadow-focus` | 0 0 0 1px accent | Focus ring shadow |
|
|
| `--shadow-glow` | 0 2px 6px info-glow | Badge glow effects |
|
|
| `--transition-bounce` | 200ms cubic-bezier | Playful hover transitions |
|
|
|
|
## Migration Order Recommendation
|
|
|
|
1. **Start with colors**: Replace `#ffc107` and `#f0f0f0` (highest visual impact)
|
|
2. **Then spacing**: Unify padding/gap values (biggest consistency win)
|
|
3. **Then shadows**: Replace rgba shadows with tokens
|
|
4. **Then typography**: Standardize font sizes
|
|
5. **Finally breakpoints + z-index**: Lower priority but good for maintainability
|
|
|
|
## Testing Checklist
|
|
|
|
After each component file is migrated:
|
|
|
|
- [ ] Light theme renders correctly
|
|
- [ ] Dark theme renders correctly
|
|
- [ ] No visual regressions in card grid, header, modals
|
|
- [ ] Focus states still visible
|
|
- [ ] Hover transitions still work (unless prefers-reduced-motion)
|