Seed v3 Colophon design system for OpenClaw Windows Hub

[karkarl]

Summary

Seeds a fresh v3-schema Colophon design system into .agents/design/ for the OpenClaw Windows Hub app, carrying over the design decisions from the earlier v1 seed (PR #962, closed/unmerged) and re-expressing the component patterns in the updated v3 schema. Branches off main.

This PR is design-system seeding only. It adds .agents/design/* and the idempotent Colophon pointer block in repo-root AGENTS.md. No application code, tests, or build files are modified.

What's here

• design.json — carried over from the v1 seed (tokens format is unchanged in v3): Fluent color tokens (each with its resource ThemeResource key + light/dark/highContrast themes), authority port targets, brand, typography, spacing, radii, shadows, principles. Preview hex is preview-only; shipping code binds the Fluent resource keys. Now carries 15 color tokens (12 from the v1 seed + control / controlLine / accentSubtle for inputs/chat) and a WinAppCli entry in the port authority (see below).
• principles.md — carried over verbatim from the v1 seed.
• components.jsonc — 10 components authored to v3 (meta.version: 3): Button, Field, Card, Badge, ComposerPicker, ComposerPickerOptions, ChatBubble, ChatComposer, ChatThread, ExampleScreen. Every raw-CSS attrs.style string is replaced with semantic, token-bound layout / position / appearance. Every object node has a stable unique id. WinUI-provenance and Reactor-port notes are preserved; ExampleScreen uses a v3 freeform status board to exercise absolute positioning alongside Auto Layout.
• colophon.jsonc — new v3 presentation profile (schemaVersion: 1, extends: "colophon/default") mapping OpenClaw tokens to theme roles for light + dark, brand, navigation, and component template config.
• AGENTS.md — idempotent Colophon pointer block; em dashes removed so the repo doc validator (no em dashes in user-facing docs) passes.

Chat components reconciled to the shipping Reactor UI (design data only)

The chat entries in components.jsonc describe what the app actually ships today, so the design stays in sync with the implementation:

• ComposerPicker — the subtle inline dropdown the composer's session / model / reasoning selectors use: borderless, transparent resting fill (SubtleFillColorTransparent), hover subtleHover / press subtlePressed, muted value text with a trailing muted chevron, sm radius, gap/padding tokens 1/2. Opens a flyout of single-select options in-app (Reactor port note).
• ChatComposer — toolbar matches the implemented layout (session picker + Attach/Model/Reasoning/Voice/Speaker/Settings/Send), container binds control / controlLine with a 12px margin; note documents the Send↔Stop toggle.
• ChatThread / ChatBubble — user bubble uses the softer accentSubtle with a hover Copy; assistant bubble uses subtleHover fill + controlLine border with a Read-aloud footer and max-width 720.
• 3 new tokens the system didn't previously cover (preview hex are approximations; shipping code binds the resource keys): control → ControlFillColorDefaultBrush, controlLine → ControlStrokeColorDefaultBrush, accentSubtle → AccentFillColorSecondaryBrush.

Composer input + pickers use the colophon #16 interaction model (design data only)

The composer's input, subtle buttons, and picker flyout are expressed with the schema-pure interaction keys (control / states / on) from the colophon #16 components schema, so the preview matches Windows Fluent (not Fluent-web) behavior with no raw CSS:

• Borderless, typeable input — chat-composer-input (a contenteditable textbox) sets control.chrome: none to drop the web button/input border and control.focus: { kind: underline, color: accent } for a Windows accent underline on focus instead of a web focus ring. It stays selectable and editable in the canvas.
• Real subtle buttons with WinUI states — ComposerPicker and the four composer icon buttons (add context, dictate, read aloud, chat settings) are real button elements with a transparent rest state ($none), control.chrome: none + control.focus outline, and states carrying subtleHover / subtlePressed (hover / pressed / hoverPressed). ComposerPicker also gets a disabled shade for single-choice selectors.
• Click-to-open flyout — ComposerPicker's on: { click: { open: "ComposerPickerOptions" } } opens the new ComposerPickerOptions component, a WinUI RadioMenuItem-style single-select flyout on a surface sheet with md radius/shadow. Flyout targets take no props, so it is a representative shared model list; the real per-picker option sets are a Reactor port note.
• Notes were refreshed to describe the real button + control model and to drop the obsolete combobox-div and web-focus-ring caveats.

WinAppCli in the port authority (design data)

Per the maintainer, XAML and Reactor now build/package through winapp (WinAppCli, https://github.com/microsoft/WinAppCli). design.json's authority gains a tooling descriptor and a toolingSource on the default WinUI 3 port and the Reactor chat override. This is design-system metadata about how the design ports to code; it changes no code. The design→code syncSource references (win-dev-skills / microsoft-ui-reactor) are unchanged.

px → token approximations (worth a human eye)

Raw WinUI pixel padding snapped to the nearest 4px token, each recorded in the component note: Button ButtonPadding 11,5,11,6 → 3/1 (MinWidth 100 = port note); Field TextControlThemePadding 10,5,6,6 → 2/1 (MinHeight 32 = port note); Card 16,12 → 4/3 (exact). Chat bubble/composer max-width/min-height growth values have no token equivalent and remain Reactor port notes. The 3 input/chat tokens' preview hex are approximations of the real Fluent brushes; shipping code binds the resource keys, so the hex is preview-only.

Required proof pools

none — this PR only adds framework-agnostic design-system data files under .agents/design/ plus the AGENTS.md pointer. No shipping UI, MCP, node, setup, pairing, or gateway code changes, so the app-behavior proof pools in docs/PROOF_POOLS.md don't apply.

Validation

Validated against the Colophon extension's own read-only validators (componentsio.mjs, profileio.mjs, validate.mjs):

• components.jsonc parses at meta.version: 3; validateComponentsDoc(doc, { tokens }) passes (all appearance / states / control token refs, including the 3 new tokens, resolve against design.json; every on.click.open target resolves to a defined component); all 10 components expandInstance successfully; guard confirms no raw "style" attrs remain.
• colophon.jsonc $schema matches PROFILE_SCHEMA_URL; validatePresentationProfile passes.
• Aggregate validateDesignDir('.agents/design') → ok: true, 0 errors, 0 warnings.
• Against the main merge-base, this branch changes only .agents/design/* and AGENTS.md (verified via git diff --stat). No C#, test, or build files are touched, so repo build/test suites are not applicable to this change.

Real behavior proof

The design system renders in the Colophon canvas from these files; the extension validators above exercise the same parse/validate/expand path the canvas uses. No runtime app behavior changes in this PR.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 17, 2026, 1:49 AM ET / 05:49 UTC (Revision 14).

ClawSweeper review

What this changes

Adds Fluent design tokens, ten interactive component previews, Colophon presentation metadata, and agent guidance for translating the catalog into native Windows UI.

Merge readiness

⛔ Needs changes before merge - 7 items remain

The design seed remains useful and is absent from current main. All five prior findings remain unresolved, and the latest glyph change introduces an additional styling defect.

Priority: P3
Reviewed head: 5a12399d5ad8d057673e464d31be10d7f21a650f

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The bounded design seed is useful, but unresolved consumer and guidance defects prevent a correctness pass.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored design seed is exempt from the ordinary contributor runtime-proof gate. Inspected historical screenshots show the earlier brand and typography catalog, but do not establish current picker behavior or profile support.
Patch quality	🦐 gold shrimp (3/6)	6 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored design seed is exempt from the ordinary contributor runtime-proof gate. Inspected historical screenshots show the earlier brand and typography catalog, but do not establish current picker behavior or profile support.
Evidence reviewed	11 items	Applicable repository policy: Read the complete root AGENTS.md and the required proof-validation skill. No ancestor-scoped AGENTS.md applies under .agents/design, and .agents/maintainer-notes is absent. Agent-facing copy and canonical native implementation guidance apply; no builds or tests were executed during this read-only review. Verified introduced scope: The pinned merge-base-to-head delta adds four design files and the root policy pointer: 1,494 added lines across five files, with no production code or tests changed. Current-main necessity and release boundary: The fetched main revision has no .agents/design catalog and is tagged v2026.9.4. The earlier #962 (Seed design system for OpenClaw Windows Hub) is closed unmerged, so it does not supply an implemented replacement.
Findings	6 actionable findings	[P2] Preserve functional radio controls in the picker preview [P2] Preserve token styles when applying the icon font [P2] Use an available Colophon presentation-profile contract
Security	None	None.

How this fits together

The design catalog feeds Colophon’s preview canvas and guides agents implementing Windows UI. The native WinUI and Reactor application remains the canonical shipping implementation.

flowchart LR
  A[Shipping Windows UI] --> B[Fluent design tokens]
  B --> C[Component catalog]
  C --> D[Colophon renderer]
  E[Preview interactions] --> D
  D --> F[Design canvas]
  B --> G[Agent implementation guidance]

Loading

Before merge

• Preserve functional radio controls in the picker preview (P2) - The previous finding remains: these labels contain no radio inputs or selection handlers. Colophon closes the flyout on an input[type="radio"] change and does not implement selection for role="menuitemradio". Clicking another option therefore cannot select it or dismiss the flyout, and the rows are not keyboard-focusable. Restore supported radio controls while preserving the intended visual treatment.
• Preserve token styles when applying the icon font (P2) - The new attrs.style replaces the entire inline style after Colophon applies layout and appearance. Its font-family-only value therefore removes the selected glyph’s 16px width, accent color, and centered alignment; the glyph inherits the menu text color instead. Use a supported representation, such as a token-colored SVG, that does not overwrite generated styles.
• Use an available Colophon presentation-profile contract (P2) - The referenced schema still returns 404, and the inspected Colophon main tree contains neither that schema nor profileio.mjs. Its directory validator reads only tokens and components, so a successful aggregate validation does not establish that this profile is consumed. Remove the unsupported profile or identify an available consumer revision that implements and validates these settings.
• Describe WinAppCLI as the optional launcher it currently is (P2) - This still tells agents that both native surfaces build and package through WinAppCLI. Current main builds through dotnet in build.ps1; run-app-local.ps1 -UseWinApp is an optional manifest-based launch path. Because the new root pointer requires agents to read this guidance, the incorrect tooling authority sends subsequent work toward a workflow the repository does not implement. Describe the existing build and launch roles accurately.
• Replace references to the nonexistent JSX catalog (P3) - The principles still direct readers to React in components.jsx, but this PR supplies components.jsonc and uses Colophon’s JSON interpreter. The same stale reference remains in design.json’s introductory note. Update both references so agents follow the actual catalog rather than searching for or recreating a nonexistent JSX implementation.
• Remove prohibited em dashes from agent-facing prose (P3) - The previous copy-policy finding remains in the new principles, token descriptions, and component notes. Root AGENTS.md explicitly prohibits em dashes in agent-facing help, and its new pointer makes these files required reading. Replace the prose separators with permitted punctuation; the documentation validator excludes .agents, so its success does not establish compliance here.
• Complete next step (P2) - Repair the picker interaction and glyph styling, resolve the unsupported profile, and correct the build, catalog, and copy guidance before merge.

Findings

• [P2] Preserve functional radio controls in the picker preview — .agents/design/components.jsonc:258-263
• [P2] Preserve token styles when applying the icon font — .agents/design/components.jsonc:253
• [P2] Use an available Colophon presentation-profile contract — .agents/design/colophon.jsonc:2-4

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Design-only scope	5 files, +1,494 lines; production +0, tests +0	All growth is the proposed catalog and agent guidance, so repairs can remain outside the shipping application.

Technical review

Best possible solution:

Keep the catalog aligned with native Windows behavior, using supported Colophon interactions and accurate build guidance without introducing a new consumer or changing application code.

Do we have a high-confidence way to reproduce the issue?

Yes, source inspection establishes the picker’s missing selection behavior and the glyph style replacement in the actual Colophon consumer; no runtime reproduction or tests were executed.

Is this the best way to solve the issue?

Not yet: the design-only boundary is appropriate, but the catalog must use working consumer contracts and describe the repository’s actual build workflow.

Full review comments:

• [P2] Preserve functional radio controls in the picker preview — .agents/design/components.jsonc:258-263
  The previous finding remains: these labels contain no radio inputs or selection handlers. Colophon closes the flyout on an input[type="radio"] change and does not implement selection for role="menuitemradio". Clicking another option therefore cannot select it or dismiss the flyout, and the rows are not keyboard-focusable. Restore supported radio controls while preserving the intended visual treatment.
  Confidence: 0.99
• [P2] Preserve token styles when applying the icon font — .agents/design/components.jsonc:253
  The new attrs.style replaces the entire inline style after Colophon applies layout and appearance. Its font-family-only value therefore removes the selected glyph’s 16px width, accent color, and centered alignment; the glyph inherits the menu text color instead. Use a supported representation, such as a token-colored SVG, that does not overwrite generated styles.
  Confidence: 0.99
• [P2] Use an available Colophon presentation-profile contract — .agents/design/colophon.jsonc:2-4
  The referenced schema still returns 404, and the inspected Colophon main tree contains neither that schema nor profileio.mjs. Its directory validator reads only tokens and components, so a successful aggregate validation does not establish that this profile is consumed. Remove the unsupported profile or identify an available consumer revision that implements and validates these settings.
  Confidence: 0.98
• [P2] Describe WinAppCLI as the optional launcher it currently is — .agents/design/design.json:12-15
  This still tells agents that both native surfaces build and package through WinAppCLI. Current main builds through dotnet in build.ps1; run-app-local.ps1 -UseWinApp is an optional manifest-based launch path. Because the new root pointer requires agents to read this guidance, the incorrect tooling authority sends subsequent work toward a workflow the repository does not implement. Describe the existing build and launch roles accurately.
  Confidence: 0.99
• [P3] Replace references to the nonexistent JSX catalog — .agents/design/principles.md:8-10
  The principles still direct readers to React in components.jsx, but this PR supplies components.jsonc and uses Colophon’s JSON interpreter. The same stale reference remains in design.json’s introductory note. Update both references so agents follow the actual catalog rather than searching for or recreating a nonexistent JSX implementation.
  Confidence: 0.99
• [P3] Remove prohibited em dashes from agent-facing prose — .agents/design/principles.md:8-9
  The previous copy-policy finding remains in the new principles, token descriptions, and component notes. Root AGENTS.md explicitly prohibits em dashes in agent-facing help, and its new pointer makes these files required reading. Replace the prose separators with permitted punctuation; the documentation validator excludes .agents, so its success does not establish compliance here.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 3c43751b2bac.

Labels

Label justifications:

• P3: This is design tooling and documentation work with no introduced change to shipping Windows behavior.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This collaborator-authored design seed is exempt from the ordinary contributor runtime-proof gate. Inspected historical screenshots show the earlier brand and typography catalog, but do not establish current picker behavior or profile support.

Evidence

Acceptance criteria:

• [P1] git diff --check.
• [P1] Colophon /design-validate against the repaired .agents/design catalog using an identified consumer revision.
• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.

What I checked:

• Applicable repository policy: Read the complete root AGENTS.md and the required proof-validation skill. No ancestor-scoped AGENTS.md applies under .agents/design, and .agents/maintainer-notes is absent. Agent-facing copy and canonical native implementation guidance apply; no builds or tests were executed during this read-only review. (AGENTS.md:69, 5a12399d5ad8)
• Verified introduced scope: The pinned merge-base-to-head delta adds four design files and the root policy pointer: 1,494 added lines across five files, with no production code or tests changed. (5a12399d5ad8)
• Current-main necessity and release boundary: The fetched main revision has no .agents/design catalog and is tagged v2026.9.4. The earlier Seed design system for OpenClaw Windows Hub #962 (Seed design system for OpenClaw Windows Hub) is closed unmerged, so it does not supply an implemented replacement. (.agents/design, 3c43751b2bac)
• Re-review continuity: GitHub’s exact-head commit patch changes only the picker note, its selected glyph and raw font style, and the icon typography entry. It does not repair radio interaction, presentation-profile availability, build-tool guidance, JSX references, or prohibited punctuation. A local comparison encountered an unavailable historical blob; the GitHub commit patch supplied the comparison instead. (.agents/design/components.jsonc:253, 5a12399d5ad8)
• Affirmative Colophon dependency boundary: The new profile explicitly references karkarl/colophon’s schema, and the captured PR body claims validation through its componentsio.mjs, profileio.mjs, and validate.mjs. The component catalog also consumes its control, states, and on.click.open contract, making Colophon consumer inspection directly relevant. (.agents/design/colophon.jsonc:2, 5a12399d5ad8)
• Profile contract unavailable in inspected consumer: Verified repository identity and pinned its main tree at this SHA. The complete tree contains neither profileio.mjs nor colophon.schema.json; fetching the referenced schema returns 404. validateDesignDir reads design.json and components.jsonc, so its success does not validate the added presentation profile. (extensions/colophon/validate.mjs:144, 5407db7f0341)

Likely related people:

• shanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• karkarl: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Restore working picker selection and preserve the glyph’s token-bound styling.
• Remove the unsupported profile or identify its available, validated consumer.
• Correct build-tool guidance, catalog references, and prohibited punctuation, then refresh the validation claims.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (13 earlier review cycles; latest 8 shown)

• reviewed 2026-09-10T23:23:54.688Z sha eaa530f :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-11T17:57:22.040Z sha ba2beae :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-11T18:08:54.851Z sha ada5a62 :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-14T17:47:48.923Z sha 3b62bbf :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-14T18:39:19.799Z sha c59d186 :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-15T18:02:14.753Z sha 9aded00 :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-15T23:43:55.677Z sha 3752e58 :: needs changes before merge. :: [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from the new agent-facing prose
• reviewed 2026-09-17T05:43:41.539Z sha 5b0fcdf :: needs changes before merge. :: [P2] Preserve functional radio controls in the picker preview | [P2] Use an available Colophon presentation-profile contract | [P2] Describe WinAppCLI as the optional launcher it currently is | [P3] Replace references to the nonexistent JSX catalog | [P3] Remove prohibited em dashes from agent-facing prose