# MoonSuite UI Generation Guidelines

Read `HANDBOOK.md` for rationale and handover detail. These are the concise
rules for implementation and AI-assisted UI generation.

## Core Direction

- Use Smoked Spatial Glass as the single primary MoonSuite visual language.
- Make the real object of work the largest visual surface.
- Compose screens as World, Glass, and Signal layers.
- Use color for state, consequence, route, focus, or selection, not decoration.
- Keep product character in content and layer emphasis, not a separate theme.

## Tokens

- Resolve tokens from the MoonBit `visual_system/` package (directly or through
  `moonvis/visual.asset-bundle.resolve@0.1.0`). Treat
  `src/styles/theme.css` as a legacy consumer and visual reference, not an
  independent source of truth.
- Record the resolved token version, asset version, and bundle digest. Surface
  drift instead of silently accepting a changed value.
- Canvas: Obsidian `#080B0D`; raised surface: Carbon `#111719`.
- Primary text: Frost `#F0F4F2`; secondary text: Mineral `#98A49F`.
- Healthy/active: Signal `#8EC97F`; attention/path: Route `#D8B56A`;
  urgent/destructive: Critical `#FF5B61`.
- Structural glass: `.86`; floating glass: `.66`; control glass: `.10`;
  standard blur: `28px`.
- Radius hierarchy: frame `12px`, panel `24px`, control `18px`, pill `999px`.
- Use an `8px` spacing base and a minimum `44px` interactive target.
- Record a missing semantic token instead of inventing an untracked value.

## Layout

- Start with user, task, object, state, and primary action.
- Prefer one dominant world surface with contextual tools over equal card grids.
- Do not put cards inside cards or wrap every section in a floating panel.
- Use responsive grid/flex layouts and stable min/max or aspect-ratio constraints.
- Keep labels and controls inside their containers at all supported widths.
- Preserve layout geometry during hover, loading, and live updates.

## Typography And Icons

- Use Inter/Noto Sans SC for UI and IBM Plex Mono for technical metadata.
- Use compact type inside tools; reserve large type for true section statements.
- Always show units, timeframes, ownership, and state explicitly.
- Use Lucide for familiar commands: `18px` glyph, `1.35` stroke, `44px` target.
- Give unfamiliar icon buttons an accessible name and tooltip.
- Do not place a visible rounded tile behind every icon.

## Components

- Choose components by semantics, not visual resemblance.
- Status pill = health or state; tag = category; badge = attached count or risk.
- Drawer = complex contextual detail; dialog = interrupting decision.
- Use a segmented control for a small exclusive mode set and tabs for peer views.
- Define purpose, content, variants, states, interaction, accessibility, and
  misuse for every shared component.
- Generated UI must map structured intent and state to registered components.
  Do not ship arbitrary model-generated HTML, CSS, or domain logic.

## States And Motion

- Cover loading, refreshing, empty, no match, error, permission, offline, stale,
  partial success, and destructive confirmation states.
- Below `300ms`: no loading UI. `300ms` to `2s`: skeleton. Above `2s`:
  explained progress. Above `10s`: timeout, preserve work, and retry.
- Motion must explain feedback, change, location, or causality.
- Prefer transform and opacity, stop state animation after it communicates, and
  preserve meaning with reduced motion.

## Review Gate

- Verify DOM/CSS, the full state matrix, the primary click path, and screenshots.
- Review product intent, domain trust, information architecture, interaction
  readiness, system craft, and brand expression.
- A screenshot failure overrides a metadata-only pass.
- Block release for unclear primary task, broken/dead-end flow, disconnected
  controls and state, wrong domain semantics, generic template output,
  inconsistent tokens, unreadable glass, or missing evidence.
- Report review findings as Issue, Source, and executable Fix.