# Visual Spec

> Visual Spec is an open visual intermediate representation (Visual IR): a machine-readable JSON contract for visual intent, independent of tool, framework, or platform.

The document format is visualSpec 1.0 (release 1.0.0-rc.1). Canonical schema id: https://visualspec.dev/schema/1.0/schema.json. License: Apache-2.0. Maintainer: Gustavo Franco.

Visual Spec is not a UI library, renderer, game engine, or replacement for HTML, CSS, Figma, glTF, USD, Flutter, SwiftUI, Compose, Unity, or Unreal. It records what exists, how it appears, how it behaves, how it moves, and which evidence defines the expected result.

## Specification

- [Visual Spec 1.0](https://visualspec.dev/specification/1.0/): Normative specification
- [Behavior](https://visualspec.dev/specification/1.0/behavior/)
- [Components](https://visualspec.dev/specification/1.0/components/)
- [Media](https://visualspec.dev/specification/1.0/media/)
- [References](https://visualspec.dev/specification/1.0/references/)
- [Rendering](https://visualspec.dev/specification/1.0/rendering/)
- [World](https://visualspec.dev/specification/1.0/world/)

## Schema

- [Root JSON Schema 1.0](https://visualspec.dev/schema/1.0/schema.json): Canonical schema id
- [Standalone schema bundle](https://visualspec.dev/schema/1.0/schema.bundle.json)
- [Semantic rules](https://visualspec.dev/schema/1.0/semantic-rules.json)
- [Schema catalog](https://visualspec.dev/schema/1.0/catalog.json)
- [Schema reference](https://visualspec.dev/reference/): Generated module reference
- [Schema downloads](https://visualspec.dev/schemas/)

## Learn

- [Why Visual Spec?](https://visualspec.dev/why/): Visual intent deserves a persistent, portable contract.
- [Quick start](https://visualspec.dev/learn/quick-start/): Write, validate and explore your first visual contract.
- [The mental model](https://visualspec.dev/learn/concepts/): A few independent models describe one visual experience.
- [Visual references](https://visualspec.dev/learn/visual-references/): Address evidence precisely and preserve what it actually proves.
- [Profiles](https://visualspec.dev/learn/profiles/): Nine specializations, one shared visual model.
- [Conformance and validation](https://visualspec.dev/learn/conformance/): Separate a well-formed document from a verified rendering.
- [Extensions and namespaces](https://visualspec.dev/learn/extensions/): Extend the vocabulary without changing the meaning of the core.
- [Build an adapter](https://visualspec.dev/learn/adapter-guide/): Translate visual intent while making capability boundaries visible.
- [Accessibility is a contract](https://visualspec.dev/learn/accessibility/): Meaning, names, focus and keyboard behavior travel with the visual model.
- [Motion, state and time](https://visualspec.dev/learn/motion/): Describe the change, its cause and its interruption policy.
- [Versioning and migration](https://visualspec.dev/learn/versioning/): Pin contracts and make transformations reproducible.
- [Component ontology](https://visualspec.dev/learn/components/): Reuse semantic patterns, not rectangles or framework names.
- [Worlds, entities and scenes](https://visualspec.dev/learn/entities/): Keep identity stable as representation and viewpoint change.
- [Rendering and visual verification](https://visualspec.dev/learn/rendering/): Specify the conditions before judging the result.
- [Contribute to Visual Spec](https://visualspec.dev/learn/contributing/): Improve the contract, examples and interoperability evidence.

## Profiles

- [User interfaces](https://visualspec.dev/profiles/ui/): Responsive interfaces with reusable components, semantics and observable behavior.
- [Images](https://visualspec.dev/profiles/image/): Still-image intent with identifiable subjects, composition, lighting and visual references.
- [Illustration](https://visualspec.dev/profiles/illustration/): A shared contract for shape language, graphic style and vector or raster representations.
- [Documents](https://visualspec.dev/profiles/document/): Paginated visual structure, typography and accessible reading relationships.
- [Presentations](https://visualspec.dev/profiles/presentation/): Slide order, repeated visual structures and time-based presentation behavior.
- [Video](https://visualspec.dev/profiles/video/): Shots, temporal composition, camera intent and synchronized audio-visual cues.
- [Motion graphics](https://visualspec.dev/profiles/motion-graphics/): Animated typography, shapes and graphic sequences with explicit timing.
- [3D](https://visualspec.dev/profiles/3d/): Spatial scenes with persistent entities, materials, lights and cameras.
- [Games](https://visualspec.dev/profiles/game/): World and character state visualization, HUDs, effects and cutscenes.

## Use cases

- [Hello Visual Spec](https://visualspec.dev/use-cases/hello/): ui
- [Checkout card](https://visualspec.dev/use-cases/ui/): ui
- [Ceramic cup still](https://visualspec.dev/use-cases/image/): image
- [Mark study](https://visualspec.dev/use-cases/illustration/): illustration
- [Field notes](https://visualspec.dev/use-cases/document/): document
- [Intent deck](https://visualspec.dev/use-cases/presentation/): presentation
- [Four second still](https://visualspec.dev/use-cases/video/): video
- [Title fade](https://visualspec.dev/use-cases/motion-graphics/): motion-graphics
- [Cup study](https://visualspec.dev/use-cases/3d/): 3d
- [Grove HUD](https://visualspec.dev/use-cases/game/): game
- [Product configurator](https://visualspec.dev/use-cases/ui-3d/): ui, 3d
- [Narrated deck](https://visualspec.dev/use-cases/presentation-video/): presentation, video

## Optional

- [Full text for language models](https://visualspec.dev/llms-full.txt)
- [GitHub repository](https://github.com/gfrancodev/visualspec)
- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)