# MoonSuite Visual System Handover Handbook

Version 02.3 · Primary direction: Smoked Spatial Glass

This handbook explains how to understand, apply, review, and extend the
MoonSuite visual system. It is the handover document for designers, engineers,
product owners, and AI agents working across Moondesk, Moonrobo, Moonstat,
Moonclaw, Moonbook, Moontown, and future MoonSuite products.

The live visual reference is the MoonVis app. This handbook carries the rules,
decision logic, and working process behind that reference.

## How To Use This Book

- **Learn:** read sections 1 through 10 to understand the visual language.
- **Adapt:** use sections 11, 12, and 14 when bringing a product into MoonSuite.
- **Review:** use section 13 and the templates in section 17.
- **Ship:** satisfy the definition of done in section 18.
- **Extend:** follow the governance rules in section 19.

Do not begin by copying a reference screen. Begin with the product's user,
world object, task, state model, and risk; then apply the system.

## 1. The System In One Minute

MoonSuite is a family of serious tools with different domains. It uses one
primary visual language instead of a separate style for every product.

The system is called **Smoked Spatial Glass**:

- The object of work is the largest and clearest thing on screen.
- Dark smoked glass holds controls and interpretation above that object.
- Color reports health, attention, urgency, route, or selection.
- Information stays precise even when surfaces are atmospheric.
- Motion explains change and location; it does not decorate idle screens.
- Product character comes from content, density, and spatial emphasis rather
  than a different palette or component grammar.

The design test is simple: can someone understand what they are looking at,
what changed, and what they can do next within five seconds?

## 2. Ownership And Sources Of Truth

Use these sources in this order:

1. `visual_system/` for canonical token values, asset metadata and digests,
   semantic roles, contrast expectations, and product/channel resolution.
2. The Rabbita MoonVis inspector for the resolved contract and drift state.
3. This handbook for rationale, workflow, and adaptation rules.
4. `guidelines/Guidelines.md` for concise implementation and AI-generation
   constraints.
5. `src/styles/theme.css` and the React app for legacy visual-reference
   composition, not independent token truth.
6. `src/imports/moonsuite-mark-1024-centered.svg` for the current primary mark;
   its accepted digest and usage status are recorded in `visual_system/`.

When a consumer disagrees with the resolver, record token or asset drift and
resolve it in MoonVis before copying the decision into another product. A
screen may add a domain token, but it must not silently redefine a canonical
semantic token.

MoonVis owns shared visual guidance and mark assets. Product repositories own
their workflows, domain rules, accessibility implementation, and production
components.

## 3. Audience Responsibilities

### Product designers

- Start with the real object and task, not a dashboard template.
- Define hierarchy, states, recovery, and responsive behavior before polish.
- Use the shared tokens and component semantics.
- Supply evidence for the important states, not only the ideal state.

### Engineers

- Map MoonVis tokens into product-native variables rather than copying values
  throughout feature code.
- Preserve semantic component boundaries and interaction behavior.
- Test loading, empty, error, permission, stale, and offline states.
- Verify the rendered interface at representative desktop and mobile sizes.

### Product owners

- Name the primary user, object, decision, and operational risk.
- Resolve domain ambiguity before visual review.
- Treat release blockers as product defects, not visual preferences.

### AI agents

- Read `guidelines/Guidelines.md` before generating or changing UI.
- Use registered product components and tokens.
- Do not invent arbitrary colors, radii, spacing, or domain behavior.
- Return evidence and a small set of executable fixes after review.

## 4. The Three Spatial Layers

Every screen is composed from three functional layers.

### Layer 01: World

The world is the real object of work: a map, document, codebase, machine,
timeline, model, table, media surface, or shared space. It should dominate the
composition whenever the task depends on inspecting or manipulating it.

Good examples:

- Moonrobo: robot state, route, camera, or environment.
- Moonbook: document, reading surface, or knowledge graph.
- Moondesk: project, conversation, task board, or workspace.
- Moonstat: evidence, comparison, and selected analytical object.

### Layer 02: Glass

Glass contains controls, navigation, interpretation, and contextual details.
It must explain a layer relationship. Do not wrap every section in glass.

Use structural glass for persistent navigation and working context. Use
floating glass for metrics, recommendations, and object details. Use control
glass for compact icon groups and mode selectors.

### Layer 03: Signal

Signal is attached to consequence: health, warning, route, focus, selection,
or temporal change. A signal should identify both the state and the affected
object.

Never use signal colors as large decorative washes.

## 5. Foundation Tokens

Tokens are a versioned contract. Product implementations may translate their
names to a local convention, but should preserve their meaning and record the
resolved `token_version` and `bundle_digest`.

### Color

| Token | Value | Meaning |
| --- | --- | --- |
| Obsidian | `#080B0D` | Primary canvas |
| Carbon | `#111719` | Raised surface |
| Smoke | `#1A2224` | Glass tint and muted surface |
| Frost | `#F0F4F2` | Primary text and strong neutral |
| Mineral | `#98A49F` | Secondary text and quiet metadata |
| Signal | `#8EC97F` | Healthy, available, selected, active |
| Route | `#D8B56A` | Attention, path, scheduled variance |
| Critical | `#FF5B61` | Urgent or destructive state only |

Use neutrals for the majority of every screen. Color should remain scarce
enough that a status change is immediately visible.

### Glass

| Layer | Value | Use |
| --- | --- | --- |
| Structural | `rgba(12, 16, 17, .86)` | Navigation and persistent inspectors |
| Floating | `rgba(18, 24, 23, .66)` | Metrics, details, recommendations |
| Control | `rgba(230, 238, 233, .10)` | Tool groups and segmented modes |
| Warning | `rgba(74, 37, 38, .68)` | Focused urgent context |
| Blur | `28px` | Atmospheric separation where supported |

Glass must remain readable without backdrop blur. Blur is enhancement, not a
contrast strategy.

### Radius

| Token | Value | Use |
| --- | --- | --- |
| Frame | `12px` | App frames, large fixed-format work areas |
| Panel | `24px` | Floating or structural panels |
| Control | `18px` | Inputs and rectangular commands |
| Pill | `999px` | Status, icon targets, compact modes |

Do not apply the largest radius everywhere. The hierarchy should read from
precise outer frame to softer contextual surface.

### Spacing And Sizing

- Base spacing unit: `8px`.
- Minimum interactive target: `44px` square.
- Default command bar: approximately `64px` high.
- Desktop tool rail: approximately `48px` wide.
- Context panels: usually `320px` to `420px` wide.
- Use stable grid tracks, aspect ratios, and min/max constraints for fixed
  tools and visual surfaces.

## 6. Typography And Icons

Use Inter with Noto Sans SC fallback for interface text. Use IBM Plex Mono for
units, coordinates, timestamps, token names, compact labels, and technical
metadata.

Typography rules:

- Use large type only for true section or product-level statements.
- Keep operational panels compact and easy to scan.
- Never shrink essential labels until they become difficult to read.
- Write explicit units, timeframes, and state labels.
- Avoid decorative letter spacing in dense product interfaces.

Use Lucide for familiar commands. Standard icon geometry is an `18px` glyph
with a light `1.35` stroke inside a `44px` target.

Domain icons should be schematic and technical. Use fill only when it carries
state. Do not place a visible rounded tile behind every icon.

## 7. Layout Patterns

### Operational desktop

Use a stable command bar, one dominant world surface, a compact tool rail, and
context panels positioned near the affected object. Do not divide the screen
into an equal-weight grid of generic cards.

### Object plus evidence

For every important measurement:

1. Name the object.
2. Show the value and unit.
3. State the timeframe.
4. Provide a target, comparison, or expected range.
5. Explain anomalies in plain language.
6. Place the next relevant action nearby.

### Reading and knowledge

Moonbook may use more open neutral space and lower signal intensity, but it
must retain the shared typography, controls, status colors, and state behavior.
Do not recreate a separate GitHub-like visual system.

### Shared and social space

Moontown may show more world imagery, spatial presence, and expressive content.
Its controls and operational states still follow MoonSuite rules. Character
comes from the world layer, not playful chrome.

## 8. Component Semantics

Choose components by meaning, not appearance.

- **Status pill:** health, connectivity, progress, or state.
- **Tag:** category, type, environment, or user-applied classification.
- **Badge:** small count, risk, or compact status attached to another object.
- **Context panel:** selected-object details and related actions.
- **Drawer:** complex details that preserve the underlying workspace.
- **Dialog:** interrupting confirmation or a decision that must be resolved.
- **Toast:** brief confirmation; never the only record of a critical event.
- **Segmented control:** a small mutually exclusive mode set.
- **Tabs:** distinct peer views whose content remains in the same context.
- **Icon button:** a familiar compact command with an accessible name and
  tooltip when its meaning is not universal.

Every component specification should define purpose, content, variants,
states, interaction, accessibility, and misuse.

## 9. State And Latency Rules

Every production workflow must account for:

- Initial loading
- Refreshing or background update
- Empty result
- No match after filtering
- Recoverable error
- Permission denied
- Offline or disconnected
- Stale data
- Partial success
- Destructive confirmation

Latency treatment:

| Duration | Treatment |
| --- | --- |
| Below `300ms` | Keep the layout still; show no loading flash |
| `300ms` to `2s` | Show a skeleton that reserves final geometry |
| Above `2s` | Explain progress and what the system is doing |
| Above `10s` | Time out, preserve work, explain recovery, offer retry |

Loading UI must not cause the surrounding layout to jump.

## 10. Motion

Motion reports change, location, and causality.

- Press feedback: approximately `120ms`.
- Panel transition: approximately `220ms`.
- World or canvas transition: up to `320ms` when spatial continuity matters.
- Prefer `transform` and `opacity`.
- Animate a status change once, then become still.
- Respect reduced-motion preferences without removing meaning.

Do not continuously float panels, pulse healthy states, or animate decorative
background elements.

## 11. Product Adaptation Dial

All products share the same visual language. They adjust the proportion of
world, glass, and signal.

| Product | World | Glass | Signal | Primary emphasis |
| --- | ---: | ---: | ---: | --- |
| Moondesk | 35 | 85 | 45 | Work orchestration |
| Moonrobo | 90 | 65 | 75 | Robotics and telemetry |
| Moonstat | 45 | 80 | 70 | Analytical evidence |
| Moonclaw | 30 | 75 | 55 | Developer operations |
| Moonbook | 20 | 55 | 20 | Reading and knowledge |
| Moontown | 75 | 45 | 40 | Living shared spaces |

These values are directional ratios, not percentages that must sum to 100.
They help teams discuss emphasis without inventing a new theme.

To adapt the system for a new product:

1. Name the product's world object.
2. Name its most important decision and highest-risk state.
3. Choose a world/glass/signal emphasis.
4. Map the shared tokens into the product stack.
5. Register domain components and state transitions.
6. Build one representative workflow with all edge states.
7. Review it through the evaluation gate before expanding the system.

## 12. Design I/O Workflow

Visual guidance participates in the full design process:

1. **Intent:** user, outcome, context, and risk.
2. **Structure:** objects, states, hierarchy, and information architecture.
3. **Components:** registered semantic behavior and boundaries.
4. **Interaction:** transitions, feedback, recovery, and accessibility.
5. **Evidence:** rendered screens, state checks, task-path tests, and review.

The token, semantic, accessibility, and domain contracts remain active at every
stage. When review fails, return to the stage that caused the problem. Do not
regenerate the entire interface without diagnosis.

### Required design declarations

Maintain these declarations in a form the team and tools can read:

- Experience specification
- Domain semantics
- Craft rules
- Visual contract
- Component registry
- Scenario shell

For generated interfaces, data describes intent, content, state, severity, and
actions. The client maps that declaration to registered components. Models do
not emit arbitrary production HTML, styling, or domain logic.

## 13. Evaluation Gate

First classify the screen: operational product, conversational interface, data
dashboard, content/documentation, or brand surface. Weight review dimensions
according to that purpose.

For MoonSuite operational products, use this baseline:

| Dimension | Weight |
| --- | ---: |
| Product intent | 18% |
| Domain trust | 20% |
| Information architecture | 20% |
| Interaction readiness | 18% |
| System craft | 14% |
| Brand expression | 10% |

Use a `0` to `2` score for each subcheck: fail, partial, pass. Record critical
failures separately so a high average cannot hide a broken workflow.

### Evidence chain

1. DOM and CSS checks: structure, tokens, contrast, and overflow.
2. State matrix: loading, empty, error, permission, stale, and offline.
3. Click smoke test: primary path, interruption, and recovery.
4. Screenshots: hierarchy, composition, readability, and brand fit.

When implementation metadata says pass but the screenshot visibly fails, the
screenshot wins.

### Stage gates

- Direction: at least `7.5`; intent and hierarchy hold.
- Prototype: at least `8.0`; the primary path is complete.
- Release: at least `8.5`; no blocker remains and evidence is attached.

### Release blockers

- The primary task is unclear.
- A key task path is broken or ends without recovery.
- Controls and visible state are disconnected.
- Domain logic, units, or permissions are wrong.
- The screen looks like a generic template rather than the product.
- Tokens or shared component behavior are inconsistent.
- Glass, imagery, or hierarchy makes information unreadable.
- Required evidence is missing.

Critique should use this format:

```text
Issue: What visibly or behaviorally fails.
Source: The declaration, component, state, or rule responsible.
Fix: One executable correction with a clear expected result.
```

## 14. Migration From An Existing Product

Do not redesign every screen at once.

1. Inventory current colors, type, spacing, radii, icons, and surface patterns.
2. Map existing values to MoonSuite tokens and record genuine gaps.
3. Choose one frequent, representative workflow.
4. Correct its information hierarchy before changing visual styling.
5. Replace generic containers with world, glass, and signal layers.
6. Migrate shared components and their complete state behavior.
7. Test with real content and worst-case labels.
8. Run the evaluation gate and resolve blockers.
9. Use the accepted workflow as the product's migration reference.

Keep temporary compatibility aliases when necessary, but give each one an owner
and removal condition.

## 15. The MoonSuite Mark

Use the corrected centered vector source. The primary treatment is a frost
monochrome mark on a dark surface. The foggy blue vector is an identity accent,
not a per-product recoloring system.

- Keep the mark centered and optically still.
- Preserve clear space equal to one quarter of its diameter.
- Do not distort, re-trace, decorate, texture, or animate the geometry.
- Do not place it in a new outer container unless the application icon format
  requires one.
- Do not use old generated style variants as primary brand assets.

## 16. Common Failure Modes

- Beginning with an equal card grid instead of the task.
- Applying glass to every container.
- Using green, amber, or red as decoration.
- Hiding units, timestamps, ownership, or state behind hover.
- Making every corner a pill.
- Using oversized marketing typography inside product tools.
- Creating a new product palette instead of adjusting the adaptation dial.
- Treating loading as a spinner rather than a complete state.
- Generating interfaces from arbitrary HTML instead of registered components.
- Reviewing only the ideal screenshot.
- Copying a reference's brand identity instead of extracting its system logic.

## 17. Working Templates

### Screen brief

```text
Product:
Primary user:
World object:
Primary task:
Decision to support:
Highest-risk state:
Primary action:
Required evidence:
World / glass / signal emphasis:
```

### Component registration

```text
Name:
Semantic purpose:
Required content:
Variants:
States:
Interaction:
Accessibility:
Must not be used for:
```

### Review record

```text
Screen type:
Review stage:
Evidence links:
Dimension scores:
Blockers:
Executable fixes:
Accepted exceptions and owner:
Result:
```

## 18. Definition Of Done

A MoonSuite screen is ready when:

- The object of work is visually dominant.
- Glass communicates a real layer relationship.
- Color carries state rather than decoration.
- The primary state is clear within five seconds.
- Labels, units, timestamps, ownership, and status are explicit.
- One action is dominant for the current workflow.
- Alerts explain consequence and recovery.
- Loading and dynamic updates preserve layout.
- The interface remains readable without backdrop blur.
- Reduced motion preserves all meaning and workflows.
- Domain objects, components, and transitions are explicit.
- Desktop and mobile screenshots have been reviewed.
- The primary path and edge states work.
- No release blocker remains.

## 19. Governance

Propose changes in MoonVis before spreading them across the suite. A proposal
should include the problem, affected products, new or changed semantics, token
impact, responsive examples, state behavior, accessibility impact, and migration
cost.

Add an abstraction only after repeated use proves it is shared. A product may
extend the system for a real domain need, but should not fork the visual language
for novelty.

MoonVis changes are released through a new pack, token, or asset version. A
consumer supplies its expected versions to the resolver; a mismatch is emitted
as explicit drift. Never overwrite a released version in place.

The MoonFlow operation materializes a reviewed bundle manifest only. MoonVis
does not become an agent node merely because a workflow consumes an asset
bundle, and it never claims arbitrary UI composition.

Record external inspiration in `ATTRIBUTIONS.md`. Extract transferable design
logic; do not copy another product's brand identity or protected assets.