view-contracts 0.3.0 → 0.3.3

package/README.md

@@ -78,19 +78,17 @@ A `.view.tsx` file defines:
 - component hierarchy
 - layout structure
 - visual composition
+- `variant` names (appearance resolved from `views/design/theme.yaml`)
 
-Example:
+### Design tokens and theme own appearance
 
-```tsx
-export default screen<AdminDashboardViewModel>(({ vm }) => (
-  <Page id={vm.screenId} title={vm.title}>
-    <Heading level={1}>{vm.title}</Heading>
-    <Table rows={vm.projects} />
-  </Page>
-));
-```
+Color, spacing, typography, and component variants are defined in project YAML — not in view source:
+
+- `views/design/tokens.yaml` — DTCG design tokens
+- `views/design/theme.yaml` — `Button.primary`, `Text.muted`, etc.
+- `views/design/extensions.css` — optional `ext-*` styles for extension components
 
-The view describes **structure only** — not API calls, routing logic, or styling implementation details.
+See [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md).
 
 ### Compile instead of hand-coding
 
@@ -112,11 +110,12 @@ The generated output is deterministic.
 
 ### Supported
 
-- React generation (`generated/react/`, `generated/components/`)
-- DSL preview runtime (`src/preview/`)
+- React generation (`generated/react/`, `generated/components/`, `generated/theme.css`)
+- Design tokens + theme variants (`views/design/tokens.yaml`, `theme.yaml`)
+- Live DSL preview (`dev:preview`) with `views/preview/*.mock.yaml` sample data
+- Extension registry (`extensions.yaml`) with plain HTML/CSS implementations
 - In-memory View IR compilation
 - Standalone app scaffold (`.vite/` per example project)
-- Static catalog generation
 
 ### Planned
 
@@ -139,15 +138,18 @@ flowchart TB
   end
 
   subgraph design ["Visual design"]
-    viewTsx["views/*.view.tsx<br/>layout · composition"]
+    viewTsx["views/*.view.tsx<br/>layout · composition · variant names"]
+    tokens["views/design/tokens.yaml"]
+    theme["views/design/theme.yaml"]
   end
 
   openapi --> microContracts["micro-contracts generate"]
   microContracts --> contractsTs["generated/contracts.ts"]
-  microContracts --> mockTs["generated/mock.ts"]
 
   openapi --> bindings["view-bindings.yaml"]
   viewTsx --> bindings
+  tokens --> build
+  theme --> build
 
   contractsTs -->|"imports ViewModel type<br/>validates vm.* and operationId"| viewTsx
 
@@ -156,14 +158,15 @@ flowchart TB
 
   build --> viewIr["View IR (in-memory)"]
   viewIr --> reactRenderer["renderComponents"]
+  reactRenderer --> generatedReact["generated/react/*.generated.tsx"]
   build --> runtimeCopy["renderRuntime → generated/"]
   build --> bridgeGen["render bridge"]
-
-  reactRenderer --> generatedReact["generated/react/*.generated.tsx"]
+  runtimeCopy --> generatedTheme["generated/theme.css"]
   bridgeGen --> bridgeTs["generated/view-bridge.generated.ts"]
   runtimeCopy --> generatedRuntime["generated/components + runtime/"]
 
   generatedReact --> app["Standalone app (src/main.tsx)"]
+  generatedTheme --> app
   bridgeTs --> app
   generatedRuntime --> app
 ```
@@ -175,6 +178,7 @@ flowchart TB
 | Authoring | OpenAPI types flow into `.view.tsx` via `generated/contracts.ts` | Type-safe view source |
 | Binding | `view-bindings.yaml` links a screen (`operationId`, `ViewModel`) to a view file | No schema duplication |
 | Compilation | Compiler reads layout from TSX and lowers `vm.*` / `action` to language-neutral IR | In-memory View IR |
+| Design | `tokens.yaml` + `theme.yaml` validate and emit `generated/theme.css` | CSS variables + `.vc-*` variant rules |
 | Generation | Renderer copies runtime + emits React from IR + bridge registry | `generated/` (no `@view-contracts` imports) |
 
 ### Preview path (no compile step)
@@ -183,18 +187,18 @@ flowchart TB
 flowchart LR
   openapi["openapi.yaml"] --> microContracts["micro-contracts"]
   microContracts --> contractsTs["contracts.ts"]
-  microContracts --> mockTs["mock.ts"]
 
   contractsTs --> viewTsx["*.view.tsx"]
-  viewTsx --> preview["src/preview/"]
-  mockTs --> preview
+  mockYaml["views/preview/*.mock.yaml"] --> previewPlugin["preview mock plugin"]
+  viewTsx --> preview["Vite preview"]
+  previewPlugin --> preview
 
   preview --> reactDev["Vite dev server<br/>design verification"]
 ```
 
-Designers and developers validate layouts **without running the full build**. The preview still consumes OpenAPI-derived ViewModel types and mock data.
+Designers and developers validate layouts **without running the full build**. Preview loads sample ViewModels from `views/preview/*.mock.yaml` (not from `generated/`). Production apps load real data via `operationId` in view-bindings.
 
-See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and [docs/SPEC_COVERAGE.md](./docs/SPEC_COVERAGE.md) for implementation details.
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md), [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md), [docs/extensions.md](./docs/extensions.md), and [docs/SPEC_COVERAGE.md](./docs/SPEC_COVERAGE.md).
 
 ---
 
@@ -219,7 +223,6 @@ Other useful commands:
 npm run dev:preview     # preview only
 npm run dev:app         # standalone dev app only
 npm run check:both      # build + preview dev + production bundle (4174)
-npm run build:catalog   # static gallery HTML
 ```
 
 ---
@@ -230,10 +233,13 @@ The repository includes an example admin dashboard:
 
 ```txt
 examples/admin-dashboard/
-├── views/              # restricted .view.tsx (may import @view-contracts/*)
-├── src/                # app wiring, extension components, handlers
+├── views/              # restricted .view.tsx (preview compiles live)
+│   ├── design/         # tokens.yaml, theme.yaml, extensions.css
+│   └── preview/        # *.mock.yaml — preview sample ViewModels only
+├── src/                # app wiring, extension components (HTML/CSS), handlers
 ├── generated/          # build output (standalone — no @view-contracts imports)
 ├── contracts/          # OpenAPI + micro-contracts config
+├── extensions.yaml     # extension registry (Grid, Table, …)
 ├── dev.ports.ts        # fixed dev server ports
 ├── scripts/            # dev-both.sh, check-both.sh, ports.sh
 └── .vite/              # auto-generated Vite configs (gitignored)
@@ -241,6 +247,10 @@ examples/admin-dashboard/
 
 See [examples/admin-dashboard/README.md](./examples/admin-dashboard/README.md) for local verification steps.
 
+**Extensions** (`Grid`, `Table`, …) are declared in `extensions.yaml` and implemented in `src/components/extensions.tsx` with plain HTML/CSS — not DSL. See [docs/extensions.md](./docs/extensions.md).
+
+**Appearance** for vocabulary elements comes from `views/design/theme.yaml` and `tokens.yaml`. See [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md).
+
 ---
 
 ## Project Layout
@@ -248,24 +258,26 @@ See [examples/admin-dashboard/README.md](./examples/admin-dashboard/README.md) f
 ```txt
 src/
 ├── compiler/           # TSX → View IR
-├── renderer/
-│   └── react/
-│       ├── renderComponents.ts   # IR → generated/react/*.tsx
-│       ├── renderRuntime.ts      # runtime SSoT → example/generated/
-│       └── runtime/              # React primitives (@view-contracts/components SSoT)
-├── preview/            # DSL preview helpers (@view-contracts/preview)
+├── design/             # tokens/theme parse, validate, CSS emit
+├── extensions/         # extension registry load + validation
+├── preview/            # Vite plugins (live views, theme, mock YAML)
 ├── scaffold/           # .vite/ + package.json for example projects
-├── catalog/            # static catalog builder
 └── commands/           # CLI handlers (build orchestrator)
 
 packages/
 ├── core/               # screen(), types (@view-contracts/core)
-└── runtime/            # action dispatcher (@view-contracts/runtime)
+└── runtime/            # legacy preview shim
 
 renderers/
-├── react/              # element/property maps, routes.yaml
+├── react/              # lowering, element map, runtime, templates
 ├── swiftui/            # (planned)
 └── compose/            # (planned)
+
+docs/
+├── design-tokens-and-theme.md
+├── extensions.md
+├── ARCHITECTURE.md
+└── SPEC_COVERAGE.md    # auto-generated vocabulary reference
 ```
 
 ---

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
 
 info:
   title: view-contracts CLI
-  version: 0.3.0
+  version: 0.3.3
   description: >-
     Contract-first UI design toolchain. Compiles restricted view-contract TSX
     to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
@@ -162,40 +162,3 @@ command_sets:
             description: Lint passed.
           '1':
             description: Lint failed.
-
-      catalog.build:
-        summary: Build static catalog HTML for design review.
-        description: >-
-          Renders all registered views with mock ViewModels into a single HTML file
-          for design review, screenshot baselines, and accessibility checks.
-        usage:
-          - view-contracts catalog build
-          - view-contracts catalog build -c view-contracts.config.yaml
-          - view-contracts catalog build -o dist/catalog.html
-        options:
-          - name: config
-            aliases: [c]
-            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
-            value_name: path
-            schema:
-              type: string
-          - name: output
-            aliases: [o]
-            description: Output HTML path (defaults to dist/catalog.html next to bindings).
-            value_name: path
-            schema:
-              type: string
-            file:
-              mode: write
-              media_type: text/html
-              encoding: utf-8
-        exits:
-          '0':
-            description: Catalog built.
-            files:
-              - path: dist/catalog.html
-                required: false
-                media_type: text/html
-                encoding: utf-8
-          '1':
-            description: Build failed.