Add harness workflow and Material showcase design system

README.md

@@ -18,6 +18,7 @@ default styling with its own tokens, motion recipes, and component contract.
 - The public UI surface now includes the core form and overlay set plus advanced patterns such as `DataTable`, `Command`, `Combobox`, `Sheet`, and `EmptyState`.
 - The default distribution path is package-first: `@ai-ui/ui` and `@ai-ui/tokens` are versioned and validated for package consumption.
 - The internal source-copy registry flow remains available as an optional mode for teams that want local ownership of copied component source.
+- The active visual direction is documented in [DESIGN.md](/Users/xd/project/cadence-ui/DESIGN.md): a single Material You inspired language with dynamic color, tonal surfaces, large radii, and one shared motion system.
 
 ## System principles
 
@@ -27,6 +28,20 @@ default styling with its own tokens, motion recipes, and component contract.
 - Accessibility by default: keyboard, focus, ARIA, and reduced motion are baseline expectations.
 - Motion with purpose: animation should communicate state and hierarchy, not decorate at random.
 
+## System Of Record
+
+When changing public visuals, docs, or interaction behavior, treat these files as the baseline
+context before making non-trivial changes:
+
+- [DESIGN.md](/Users/xd/project/cadence-ui/DESIGN.md)
+- [README.md](/Users/xd/project/cadence-ui/README.md)
+- [CONTRIBUTING.md](/Users/xd/project/cadence-ui/CONTRIBUTING.md)
+- [roadmap.md](/Users/xd/project/cadence-ui/roadmap.md)
+- [packages/ui/src/lib/contracts.ts](/Users/xd/project/cadence-ui/packages/ui/src/lib/contracts.ts)
+- [apps/docs/src/component-authoring.stories.tsx](/Users/xd/project/cadence-ui/apps/docs/src/component-authoring.stories.tsx)
+- [docs/harness-engineering.md](/Users/xd/project/cadence-ui/docs/harness-engineering.md)
+- [docs/orchestration.md](/Users/xd/project/cadence-ui/docs/orchestration.md)
+
 ## Getting started
 
 Requirements:
@@ -103,7 +118,7 @@ import { Button } from "@ai-ui/ui";
 This keeps the app on one UI package import path while still pulling in token and skin
 styles together. Consumers that want lower-level control can still import
 `@ai-ui/tokens/styles.css` and `@ai-ui/ui/skins.css` separately. If you need token helpers
-such as `setTheme`, add `@ai-ui/tokens` directly as well.
+such as `setTheme` or `setDynamicColor`, add `@ai-ui/tokens` directly as well.
 
 If you need source ownership instead of package upgrades, use the optional registry
 installer to copy component source into another project:
@@ -166,6 +181,34 @@ uses:
 - Playwright smoke coverage for core Storybook flows
 - Storybook a11y checks as part of the docs review surface
 
+## Harness engineering
+
+Cadence UI now includes a first-pass harness workflow for agent-friendly engineering. The goal is
+to make the repository easier to understand, plan against, and validate mechanically.
+
+- System guidance lives in [docs/harness-engineering.md](/Users/xd/project/cadence-ui/docs/harness-engineering.md).
+- Non-trivial work should start with an execution plan under
+  [docs/exec-plans](/Users/xd/project/cadence-ui/docs/exec-plans/README.md).
+- Shared validation suites are exposed through the root `pnpm harness:*` scripts.
+- Worktree-oriented orchestration defaults live in
+  [docs/orchestration.md](/Users/xd/project/cadence-ui/docs/orchestration.md).
+
+Useful commands:
+
+```bash
+pnpm harness:select
+pnpm harness:suites
+pnpm harness:validate:static
+pnpm harness:validate:changed
+pnpm harness:validate:component
+pnpm harness:validate:docs
+pnpm harness:validate:docs-smoke
+pnpm harness:validate:consumers
+pnpm harness:validate:pr
+pnpm harness:validate:release
+pnpm harness:orch -- status --run <run-id>
+```
+
 ## Contributing
 
 Read [CONTRIBUTING.md](/Users/xd/project/cadence-ui/CONTRIBUTING.md) before adding or