Cosmic Harbor Design System

Use this skill for any OrbitDock UI work: new views, styling changes, layout adjustments, component refinements, token updates, or design reviews.

This skill is adapted for Codex and the rest of the agents working in this repo. It should help you move quickly without inventing a parallel design language or copying existing visual mistakes forward.

This is the fast path, not the handbook. For deeper detail, open:

• docs/design-system.md for the canonical design system
• docs/typography.md when text treatment or hierarchy matters
• docs/UI_CROSS_PLATFORM_GUIDELINES.md for platform-specific ergonomics
• docs/CLIENT_DESIGN_PRINCIPLES.md and docs/SWIFT_CLIENT_ARCHITECTURE.md when shared SwiftUI structure is involved
• reference.md in this skill when you need the copied long-form spec

Workflow

1. Open docs/design-system.md first for any non-trivial UI change.
2. Check the nearby implementation before inventing a new component shape or token.
3. If the current UI conflicts with the design system, prefer fixing the mismatch over preserving it.
4. If the real gap is a missing token, add it in the canonical token file first, then consume it from the view.
5. Read only the sections relevant to the task so the skill stays cheap in context.

Core Principles

1. Mission Control, Not a Toy: dense, precise, urgency-first, never decorative sci-fi fluff
2. Calm Density: information-rich without visual panic; whitespace separates groups, not every border
3. Status at a Glance: the user should know what needs attention in under a second
4. Platform-Native, Visually Unified: same tokens and hierarchy everywhere, ergonomics tuned per platform

Token Quick Reference

Status Colors

Background Depth

backgroundCode -> backgroundPrimary -> backgroundSecondary -> backgroundTertiary

Text Hierarchy

Never use SwiftUI .foregroundStyle(.tertiary) or .quaternary on OrbitDock dark surfaces.

Spacing

xxs(2) gap(3) xs(4) sm_(6) sm(8) md_(10) md(12) lg_(14) lg(16) section(20) xl(24) xxl(32)

Radius

xs(2) sm(4) sm_(5) md(6) ml(8) lg(10) xl(14) with continuous corners

Motion

Rules That Prevent Bugs

1. No ad-hoc colors. Every color comes from Theme.swift.
2. No ad-hoc spacing. Use tokenized spacing values only.
3. No ad-hoc radii. Use tokenized corner radii only.
4. No ad-hoc animations. Use motion presets only.
5. Status uses the defined five-state system. Do not invent extra UI status colors casually.
6. feedback* colors are for general UI feedback, not session state.
7. Long paths, identifiers, and model names must truncate safely.
8. Shared layouts start from phoneCompact and scale up.
9. Dark mode only. Do not introduce light-mode branches.
10. No hover-only affordances as the sole interaction path.

Component Patterns

Reuse nearby OrbitDock patterns before introducing a new component shape.

Badge

HStack(spacing: Spacing.gap) {
  Image(systemName: icon).font(.system(size: IconScale.sm, weight: .semibold))
  Text(label).font(.system(size: TypeScale.mini, weight: .semibold))
}
.foregroundStyle(color)
.padding(.horizontal, Spacing.sm_)
.padding(.vertical, Spacing.gap)
.background(color.opacity(OpacityTier.light), in: Capsule())

Card

content
  .padding(Spacing.md)
  .background(Color.backgroundTertiary)
  .clipShape(RoundedRectangle(cornerRadius: Radius.md, style: .continuous))
  .overlay(
    RoundedRectangle(cornerRadius: Radius.md, style: .continuous)
      .stroke(Color.surfaceBorder, lineWidth: 1)
  )

Permission Banner

HStack(spacing: Spacing.md) {
  Image(systemName: "exclamationmark.triangle.fill")
    .foregroundStyle(Color.statusPermission)
  VStack(alignment: .leading, spacing: Spacing.xs) { /* tool info */ }
}
.padding(Spacing.lg_)
.background(
  Color.statusPermission.opacity(OpacityTier.light),
  in: RoundedRectangle(cornerRadius: Radius.lg, style: .continuous)
)

Cross-Platform Layout

Accessibility

• Text tiers must maintain the documented contrast on dark backgrounds
• Every status color needs a non-color signal, usually an icon
• Respect reduced motion on native platforms
• Decorative elements should be hidden from accessibility APIs
• Do not make hover the only way to discover or perform an action
• Prefer safe truncation and bottom-pinned actions on iPhone shared views

Codex-Specific Guidance

• Open the design docs before editing UI, but only read the sections relevant to the task
• Prefer extending existing OrbitDock patterns over inventing a parallel style language
• If the current code violates the design system, fix the mismatch instead of copying it forward
• If a missing token is the real issue, add it in the canonical token file first, then use it from the component
• When reviewing UI changes, check token compliance, urgency hierarchy, truncation safety, reduced motion, and platform fit before polishing details
• Keep the source of truth in repo docs and token files, not in scattered component-local comments or magic values

See reference.md for the longer copied reference, and docs/design-system.md for the canonical repo version.