feat: Spectral Dark — MuseHub design system & component theme

What This Is — Read First

This is a CSS theme delivery. The mental model: imagine you purchased a premium dark-mode theme called Spectral Dark and dropped it into MuseHub. When the theme is complete, every page in the app renders correctly simply by applying the right class names — no page-specific color, typography, or visual rules anywhere.

The contract every agent must follow:

• HTML templates apply class names: class="btn btn--primary", class="hero hero--agent", class="card card--repo"
• The CSS theme defines what those classes look like — once, in one file, for the entire app
• pages/ SCSS files contain structural layout only — grid columns, flex direction, max-width, sticky positioning — zero colors, zero typography, zero visual appearance

If you find yourself writing color:, background:, border-color:, or font-size: in a pages/ file — stop. That rule belongs in a components/ or patterns/ file.

---

What Agents Must NOT Do

• Do not write visual/color CSS in page files. Page files are structural layout only.
• Do not tokenize old flat SCSS files. The old flat files (_user-profile.scss, _commit-detail.scss, _blob.scss, etc.) are being deleted entirely, not migrated. Stop touching them.
• Do not create one-off component classes per page. .prof-hero should not exist. Use .hero.hero--human. .prof-repo-card should not exist. Use .card.card--repo.
• Do not write a pages/ file before its template uses component classes. Update the template first, then write the minimal structural layout file.
• Do not read entire flat SCSS files line by line looking for hex values. Those files are going away. The component files are the source of truth.

---

How To Deliver This (Exact Steps)

One page at a time. Build and visually verify after each step.

1. Pick a page (start with profile)
2. Open its HTML template
3. Replace one-off page classes with canonical component classes (.prof-hero → .hero.hero--human, .prof-repo-card → .card.card--repo, etc.)
4. Write pages/_[page].scss with structural layout only — grids, max-widths, flex direction
5. Build: npm run build:css
6. Verify the page visually on https://localhost:1337
7. Delete the old flat SCSS file
8. Repeat for next page

---

The Complete Component Inventory

Every element below must be defined once in src/scss/components/ or src/scss/patterns/. These are the canonical class names. HTML uses these. Nothing else.

Base HTML elements — globally styled, no class required

h1 h2 h3 h4 h5 h6 — size, weight, line-height flowing from --text-* and --weight-* tokens p a strong em small blockquote code pre pre code — mono font, --bg-surface background, --border-default border ul ol li table thead tbody tr th td hr details summary input textarea select button — base reset, visual styling in components

Buttons — components/_buttons.scss

Every button is class="btn" plus a modifier. All variants need: default, :hover, :active, :focus-visible, [disabled].

• .btn--primary — spectral gradient fill, white text, glow on hover
• .btn--ghost — transparent, --border-default edge, lifts on hover
• .btn--danger — red fill, destructive actions only
• .btn--secondary — --bg-surface fill, muted text
• .btn--create — success green, create/publish actions
• .btn--accent — accent blue tint
• .btn--cta — full spectral gradient, largest CTA
• .btn--sm .btn--lg — size modifiers

Inputs — components/_inputs.scss

All need: default, :focus, :disabled, [aria-invalid] states.

• .form-input — text, email, password, search
• .form-select — dropdown with chevron
• .form-textarea — multiline
• .form-checkbox .form-radio
• .form-toggle — on/off switch
• .form-label .form-group .form-error .form-hint
• .tag-input-container .tag-pill — multi-tag input
• .token-form — API token display

Cards — components/_cards.scss

• .card — base: --bg-surface, --border-default, --radius-md
• .card--elevated — stronger shadow/glow
• .card--hover — pointer cursor, lift transform on hover
• .card--repo — repo card with domain-colored left accent bar, name, description, footer stats
• .card--stat — number + label layout for dashboard stats
• .card--accent-top .card--accent-success .card--accent-warning .card--accent-danger — top border accent variants

Navigation — components/_nav.scss

• .site-nav — top navigation bar, full width, --bg-base background
• .site-nav__logo .site-nav__links .site-nav__actions
• .tab-list .tab .tab--active — horizontal tab bar with bottom border indicator
• .tab-btn .tab-count — tab button with numeric count badge
• .breadcrumb .breadcrumb__item .breadcrumb__sep
• .sidebar-nav .sidebar-nav__item .sidebar-nav__item--active
• .sort-btn — sort/filter button in list headers
• .sidebar-section .sidebar-section-title

Surfaces and Overlays — patterns/_surfaces.scss

• .panel — base panel surface (background + border + radius)
• .panel--overlay — floating elevated panel
• .hero — full-width section with dark gradient background
• .hero--human — subtle blue-tinted gradient glow
• .hero--agent — subtle purple-tinted gradient glow
• .hero--org — subtle amber-tinted gradient glow
• .modal .modal-backdrop .modal-panel .modal-header .modal-footer
• .dropdown .dropdown__item .dropdown__divider
• .comment-block .comment-header-row .comment-body-text

Badges — components/_badges.scss

• .badge — base inline badge
• .badge--open .badge--closed .badge--merged .badge--active
• .badge--success .badge--failure .badge--running .badge--pending .badge--cancelled .badge--warning — CI/CD states
• .badge--human .badge--agent .badge--verified .badge--deprecated — identity/provenance
• .badge-dim-harmonic .badge-dim-rhythmic .badge-dim-melodic .badge-dim-structural .badge-dim-dynamic — dimension badges

Pills — components/_pills.scss

• .pill[data-domain="code"] .pill[data-domain="midi"] .pill[data-domain="mist"] .pill[data-domain="agent"] .pill[data-domain="generic"]
• .pill--status[data-status="open"] .pill--status[data-status="merged"] .pill--status[data-status="closed"]

Chips — components/_chips.scss

• .chip--code .chip--midi .chip--mist .chip--agent .chip--generic
• .filter-chip — toggleable filter
• .ticker-chip — numeric data chip
• .mono-badge .mono-badge--accent .mono-badge--success
• .label-chip .label-dot

Avatars — components/_avatars.scss

• .avatar — base circular avatar
• .avatar--sm .avatar--lg
• .avatar--agent — purple spectral ring
• .avatar--org — rounded-square
• .participant-stack .participant-avatar .participant-overflow — stacked avatar row

Activity Canvas — components/_canvas.scss

• .prof-canvas .prof-canvas__domain .prof-canvas__cell[data-intensity="0-4"]
• Cell colors map: 0 → --canvas-0 through 4 → --canvas-4

Code and Diff — components/_code.scss

• pre code pre code — base monospace styling
• .diff-track-row .diff-track-added .diff-track-removed .diff-track-changed
• .diff-sign-add .diff-sign-del .diff-sign-ctx

Timeline and Activity Rows — components/_timeline.scss

• .commit-row .proposal-row .issue-row .session-row
• .commit-sha .commit-msg .commit-meta
• .session-row--active .session-live — live pulse animation
• .branch-pill — inline branch name chip

Feedback States — components/_toasts.scss

• .loading — spinner + muted message
• .error — red tinted error state
• .empty-state .empty-icon .empty-title .empty-desc
• .toast .toast--success .toast--error .toast--info
• [data-tooltip] — CSS-only tooltip on hover
• .notif-badge — notification count dot

Spectral Patterns — patterns/_spectral.scss

• .spectral-text — gradient background-clip text (hero handles, callout names)
• .spectral-glow — layered box-shadow glow
• .spectral-glow--accent .spectral-glow--agent
• .spectral-shimmer — animated shimmer for loading states

Agent Patterns — patterns/_agents.scss

• .agent-badge — agent identity badge
• .agent-ring — spectral ring around agent avatar
• .agent-commit-marker — marker on timeline for agent-authored commits
• .fleet-dot .fleet-dot--active .fleet-dot--idle .fleet-dot--error

---

Page Layout Files — Structural Only

These four files cover every page. They contain zero visual rules — only layout.

File	Pages covered	Key structural rules
pages/_profile.scss	profile, forks, commit graph	hero layout, canvas grid, repo card grid, DAG viewport
pages/_repo.scss	repo home, blob, branches, tags, releases, new-repo	file tree layout, blob viewer, list layouts
pages/_commit.scss	commit detail, diff, symbols, symbol-view	diff layout, symbol sidebar, two-column
pages/_docs.scss	docs, MCP docs, legal, credits	prose layout, sidebar TOC, section spacing

---

Vision

MuseHub is not GitHub. This is a domain-agnostic version control system for multi-dimensional state with agents, humans, and organizations as first-class citizens. The UI should feel like what you'd get if a recording studio, a particle accelerator control room, and a very clean dark-mode IDE had a child.

Theme name: Spectral Dark

The visual metaphor: you're looking through a viewport into a void where agents and humans deposit work as luminous crystalline structures. Everything is dark and precise, with spectral color as signal — not decoration.

---

The Color System

Two channels, one spectrum

Cold → Hot axis (maps to domain types):

Cold                                              Hot
#1d4ed8  #3730a3  #6d28d9  #7c3aed  #9333ea  #a855f7  #c084fc
 blue     indigo   deep     violet   purple   amethyst  lavender
 code     base     midi     accent   mist     agent     soft

The palette we have is directionally right but slightly garish at the hot end. The fix is not to remove the warmth — this should still breathe and feel alive — but to pull the fuchsia/pink back from fully saturated neon toward a richer, more luminous purple-magenta. Think: bioluminescent, not neon sign.

Refined intensity palette (for canvas, heatmaps, intensity UI):

level 0:  #0d0d1a  ← void, empty
level 1:  #1e1b4b  ← indigo shadow
level 2:  #4c1d95  ← deep violet
level 3:  #7c3aed  ← violet (current, keep)
level 4:  #a855f7  ← amethyst (replaces fuchsia #c026d3 — less neon, same energy)

Spectral name gradient:

before: linear-gradient(90deg, #388bfd, #7c3aed, #c026d3, #f472b6)
after:  linear-gradient(90deg, #60a5fa, #818cf8, #a78bfa, #c084fc)

This shifts the whole gradient about 20° cooler — still spectral, still alive, but the landing color is lavender instead of fuchsia. It reads as "cosmic" rather than "rave."

Domain color assignments

Domain	Primary	Muted bg	Border	Feeling
code	#60a5fa	rgba(96,165,250,0.08)	rgba(96,165,250,0.18)	electric blue, precision
midi	#a78bfa	rgba(167,139,250,0.08)	rgba(167,139,250,0.18)	violet, resonant
mist	#c084fc	rgba(192,132,252,0.08)	rgba(192,132,252,0.18)	lavender, ambient
generic	#64748b	rgba(100,116,139,0.08)	rgba(100,116,139,0.18)	slate, neutral
agent	#e879f9	rgba(232,121,249,0.08)	rgba(232,121,249,0.18)	fuchsia, alive

Agent intentionally gets the most saturated treatment — agents are special, they should pop.

Background layers

--bg-void:      #07070f   /* page background — the deepest dark */
--bg-base:      #0d1117   /* familiar grounded dark */
--bg-surface:   #161b22   /* cards, panels */
--bg-elevated:  #1c1c2e   /* modals, dropdowns, canvas cells */
--bg-overlay:   #21213a   /* hover states, active rows */

Text

--text-primary:   #e2e8f0   /* main content */
--text-secondary: #94a3b8   /* labels, metadata */
--text-muted:     #4a5568   /* timestamps, counts, disabled */

Borders (crystalline — thin, barely there)

--border-subtle:  rgba(99, 102, 241, 0.07)   /* almost invisible */
--border-default: rgba(99, 102, 241, 0.14)   /* card edges */
--border-strong:  rgba(139, 92, 246, 0.28)   /* focused inputs, active */
--border-glow:    rgba(167, 139, 250, 0.45)  /* hover, selected */

Named gradients

--gradient-spectral:    linear-gradient(90deg, #60a5fa, #818cf8, #a78bfa, #c084fc);
--gradient-spectral-45: linear-gradient(45deg, #60a5fa, #818cf8, #a78bfa, #c084fc);
--gradient-agent:       linear-gradient(90deg, #a78bfa, #e879f9);
--gradient-void:        linear-gradient(180deg, #0d1117 0%, #07070f 100%);
--gradient-surface:     linear-gradient(135deg, #161b22 0%, #1c1c2e 100%);

---

Typography

UI text: Inter — clean, humanist, excellent legibility. CDN with local fallback.

--font-sans: 'Inter', 'Helvetica Neue', Helvetica, Arial, sans-serif;
--font-mono: 'JetBrains Mono', 'Berkeley Mono', 'Fira Code', 'Cascadia Code', monospace;

Scale:

--text-xs:   11px   /* timestamps, labels, canvas totals */
--text-sm:   13px   /* secondary content, metadata */
--text-base: 15px   /* body, default */
--text-md:   17px   /* sub-headings */
--text-lg:   20px   /* section headings */
--text-xl:   24px   /* page titles */
--text-2xl:  32px   /* hero */
--text-3xl:  48px   /* display */

Weights:

--weight-normal:   400
--weight-medium:   500
--weight-semibold: 600
--weight-bold:     700

---

Spacing — 8pt grid

--space-1: 4px   --space-2: 8px    --space-3: 12px   --space-4: 16px
--space-5: 20px  --space-6: 24px   --space-7: 32px   --space-8: 40px
--space-9: 48px  --space-10: 64px  --space-11: 80px  --space-12: 96px

---

Motion

--ease-out:  cubic-bezier(0.0, 0, 0.2, 1)
--ease-in:   cubic-bezier(0.4, 0, 1, 1)
--ease-snap: cubic-bezier(0.0, 0, 0.1, 1)
--duration-fast:   80ms
--duration-base:   150ms
--duration-slow:   250ms
--duration-reveal: 400ms

---

Key Component Signatures

Buttons

• .btn--primary — spectral gradient fill, white text, box-shadow: 0 0 12px rgba(139,92,246,0.25) on hover
• .btn--ghost — transparent, --border-default, lifts on hover
• .btn--danger — #dc2626 tint, destructive actions only

Hero sections

• .hero — full-width, --bg-base background
• .hero--human — radial gradient glow using --color-accent
• .hero--agent — radial gradient glow using --color-purple
• .hero--org — radial gradient glow using --color-warning
• Every profile, repo, and commit page uses .hero + a modifier. No page-specific hero styling.

Cards

• Base: --bg-surface + --border-default + 8px radius
• Hover: border lifts to --border-glow, 200ms
• No drop shadows — in dark theme, use border lift instead

Spectral text

.spectral-text {
  background: var(--gradient-spectral);
  -webkit-background-clip: text;
  background-clip: text;
  -webkit-text-fill-color: transparent;
}

Used on hero handles and featured callouts. Sparingly — maximum impact.

Glow

.spectral-glow {
  box-shadow:
    0 0 0 1px rgba(139, 92, 246, 0.2),
    0 0 16px rgba(139, 92, 246, 0.12),
    0 0 32px rgba(139, 92, 246, 0.06);
}

Used on focused inputs, selected cards, active nav items, primary CTAs.

---

Light Mode

Secondary target — dark is primary. Spectral colors unchanged, backgrounds invert:

[data-theme="light"] {
  --bg-void:        #ffffff;
  --bg-base:        #f8fafc;
  --bg-surface:     #f1f5f9;
  --bg-elevated:    #e2e8f0;
  --text-primary:   #0f172a;
  --text-secondary: #475569;
  --text-muted:     #94a3b8;
  --border-default: rgba(99, 102, 241, 0.18);
  --border-strong:  rgba(99, 102, 241, 0.35);
}

---

File Architecture

src/scss/
├── theme/
│   ├── _tokens.scss         ← ALL CSS custom properties (dark default + light override)
│   ├── _typography.scss     ← font declarations, scale vars
│   ├── _spacing.scss        ← --space-1 through --space-12
│   └── _motion.scss         ← easing, durations, transition helpers
│
├── components/              ← one file per UI element; visual rules only
│   ├── _buttons.scss
│   ├── _pills.scss
│   ├── _cards.scss
│   ├── _inputs.scss
│   ├── _badges.scss
│   ├── _chips.scss
│   ├── _canvas.scss
│   ├── _avatars.scss
│   ├── _code.scss
│   ├── _timeline.scss
│   ├── _nav.scss
│   └── _toasts.scss
│
├── patterns/                ← multi-component compositions
│   ├── _spectral.scss       ← .spectral-text, .spectral-glow, shimmer
│   ├── _surfaces.scss       ← .hero, .panel, .modal, .dropdown
│   └── _agents.scss         ← agent visual language, fleet indicators
│
├── pages/                   ← structural layout ONLY, zero colors
│   ├── _profile.scss
│   ├── _repo.scss
│   ├── _commit.scss
│   └── _docs.scss
│
└── app.scss                 ← @use in order: theme → components → patterns → pages

_tokens.scss is the single source of truth. Every value in every other file is either a token or a local calc derived from tokens. No raw hex values outside _tokens.scss.

---

Acceptance Criteria

• Every component listed above is defined in the correct file with all variants and states
• Base HTML elements (h1–h6, a, p, table, input, etc.) are globally styled — no class required
• .hero, .hero--human, .hero--agent, .hero--org exist in patterns/_surfaces.scss — no page uses a one-off hero class
• All four pages/ files contain zero color/typography rules
• All old flat SCSS files deleted (_user-profile.scss, _commit-detail.scss, _blob.scss, _diff.scss, _repo-home.scss, etc.)
• app.scss imports only: theme → components → patterns → pages (no flat legacy files)
• Profile, repo, and commit pages visually verified in dark mode on https://localhost:1337
• Agent-created commits visually distinct from human commits everywhere they appear
• No raw hex values outside _tokens.scss