Skip to content

Seed design system for OpenClaw Windows Hub - #962

Closed
karkarl wants to merge 9 commits into
openclaw:mainfrom
karkarl:karkarl-seed-design-system
Closed

Seed design system for OpenClaw Windows Hub#962
karkarl wants to merge 9 commits into
openclaw:mainfrom
karkarl:karkarl-seed-design-system

Conversation

@karkarl

@karkarl karkarl commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Seeds a design system under .agents/design/ for the OpenClaw Windows Hub (WinUI 3 tray app), named Windows Fluent UI for OpenClaw. No application code is changed — this only adds files under .agents/design/.

Built with Colophon

Authored and previewed with the Colophon Copilot plugin — an experimental design-system canvas that treats .agents/design/ as the source of truth and renders design.json + components.jsx live (and feeds them back to Copilot when it builds UI). The tokens here were seeded from the app's own WinUI/Fluent surfaces and refined in the canvas.

image image image

What's included

  • design.json — token source of truth: colors, typography, spacing, radii, shadows, brand metadata. Tokens are derived from the app's real Fluent/WinUI usage (SystemAccentColor, Card/Subtle fill colors, Segoe UI Variable, Cascadia Mono) via manual XAML/C# inspection (the CSS scanner finds 0 files in a XAML repo).
  • components.jsx — living component patterns rendered in the Design System canvas: Button, Field, Card, Badge, plus chat patterns (ChatBubble, ChatComposer, ChatThread) grounded in the native chat code.
  • principles.md — prose companion: voice, personality, and Fluent-first principles ("defer to Windows", one-accent, no hard-coded hex).

Chat components

  • ChatBubble — user (right, accent, no chrome) vs assistant (left, surface + 1px line, 36px avatar), muted timestamp footer; assistant footer adds usage string + inline copy button. Mirrors OpenClawChatTimeline metrics.
  • ChatComposer — GitHub-Copilot-style toolbar: Add(+) / model / reasoning pickers on the left, mic + accent Send on the right, using WinUI SubtleButton hover/pressed tokens.

Tokens of note

  • radii: added bubble (16px) matching the native chat bubble corner radius.
  • colors: added subtleHover / subtlePressed for subtle/transparent controls (Fluent SubtleFillColorSecondary/Tertiary).

Validation

  • All 8 canvas exports transpile and render through the extension's Babel (classic runtime) + new Function pipeline.
  • design.json validated as JSON.

Stacked work

A follow-up branch applies the ChatComposer pattern to the real app chat UI (stacked on this branch): karkarl#1.

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

karkarl and others added 4 commits July 8, 2026 12:22
@karkarl
Seed design system for OpenClaw Windows Hub
85d33e0 
Add .agents/design/ (design.json, components.jsx, principles.md) with tokens derived from the WinUI 3/XAML surfaces. The app themes off Windows Fluent system resources, so color/type/radius tokens map to Fluent (SystemAccentColor, Segoe UI Variable, Cascadia Mono) rather than a bespoke palette. No application code changed.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
Refine design system components and add chat patterns
7c457b2 
Refine control padding to WinUI defaults (Button 11,5,11,6 with 100px
min-width; Field TextControlThemePadding 10,5,6,6, min-height 32; Card
Gallery padding 16,12) and add reusable chat components grounded in the
native timeline and composer: ChatBubble, ChatComposer, ChatThread.

Add a 'bubble' (16px) radius token mirroring OpenClawChatTimeline
CornerRadius and point ChatBubble at var(--radius-bubble).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
Refine ChatBubble: avatar, roles, timestamp, usage, copy
f7086b0 
Distinguish user vs assistant bubbles and enrich the assistant footer to
match the native timeline (OpenClawChatTimeline):
- Add a 36x36 circular assistant avatar (subtle fill + 1px line border,
  top-aligned, 8px gap) left of the agent bubble; user bubbles show none,
  mirroring showUserAvatar=false. Sparkle glyph stands in for the app logo.
- Give every bubble a muted timestamp footer; assistant footer also shows
  the context-usage readout (ChatUsageFormatter's used/context (pct%)) with
  a subtle inline Copy affordance right of the usage text.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
Rework ChatComposer toolbar with WinUI subtle controls
1b2b6bf 
Mirror the GitHub Copilot composer layout: left cluster = Add, model
picker, reasoning-effort picker; right cluster = mic + Send. Only Send
carries the accent; every other control is subtle chrome.

Give the icon buttons and inline pickers WinUI SubtleButtonStyle
interaction states — SubtleFillColorSecondary on hover, the lighter
SubtleFillColorTertiary on press, glyph/label darkening to primary text,
120ms ease-out. Add subtleHover / subtlePressed tokens (Fluent subtle
fills) so no hex is hard-coded in the component.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl karkarl mentioned this pull request Jul 10, 2026
Closed
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. labels Jul 10, 2026
@clawsweeper

clawsweeper Bot commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown

Codex review: found issues before merge. Reviewed August 23, 2026, 4:06 PM ET / 20:06 UTC.

ClawSweeper review

What this changes

The PR adds 474 lines of non-shipping design tokens, JSONC component examples, and design guidance under .agents/design for the Windows Hub.

Merge readiness

⛔ Blocked by patch quality or review findings - 10 items remain

Keep open for maintainer direction: this collaborator-authored draft adds a new agent-facing design authority, but its catalog and proof no longer match the current Reactor chat implementation.

Priority: P2
Reviewed head: d03a4ffcda603e12fc6a75bfadf731dec6e21b55
Owner decision: Required. See Decision needed.

Review scores

Measure Result What it means
Overall readiness 🧂 unranked krab (1/6) PR readiness rating was derived from proof quality, review findings, security review, and reviewer confidence.
Proof confidence 🌊 off-meta tidepool Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.
Patch quality 🧂 unranked krab (1/6) 5 actionable review findings remain.

Verification

Check Result Evidence
Real behavior Not applicable Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.
Evidence reviewed 5 items Current shipping chat owner: Current main directly imports Microsoft.UI.Reactor for the composer, while the project declares the Reactor package as a dependency.
Main has moved beyond the catalog snapshot: Current-main history identifies commit d3ed6c7 as removing the retired FunctionalUI chat surface; current main instead mounts the Reactor surface and passes attachment, mute, session, and read-aloud behavior into it.
Catalog claims an upstream authority: The proposed guidance tells contributors to add uncovered values to the design files before porting them into native/Reactor code, creating a parallel authority despite the maintainer review requesting native behavior remain canonical.
Findings 5 actionable findings [P1] Keep native UI as the canonical design contract
[P2] Mark chat patterns as incomplete references
[P2] Replace retired JSX catalog references
Security None None.

Live Verification

Command: pwsh -NoProfile -Command "Get-Content .agents/design/design.json -Raw | ConvertFrom-Json | Out-Null; 'design.json parsed'"

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.23.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.23.0.tgz

Assertions:

  • FAIL expect_output: design.json parsed

How this fits together

The design catalog is intended to guide agents and a design canvas before UI work is ported into the Windows tray application. The shipping chat surface is now a native WinUI application using Microsoft.UI.Reactor, which consumes connection, session, attachment, and send-state data.

flowchart LR
A[Design intent] --> B[Design catalog files]
B --> C[Agents and design canvas]
C --> D[Porting guidance]
D --> E[WinUI and Reactor chat]
E --> F[Windows Hub users]
Loading

Decision needed

Question Recommendation
Should OpenClaw adopt .agents/design as a maintained, derived design catalog for agents, or keep the existing native WinUI/Reactor implementation as the only design contract? Keep native source canonical: Do not add this catalog unless a maintainer later sponsors a narrowly scoped, maintained design-guidance contract.

Why: This choice creates a new repository-wide authority and maintenance obligation; source inspection cannot determine whether maintainers want to support that product workflow.

Before merge

  • Keep native UI as the canonical design contract (P1) - This says uncovered values must be added to the catalog before native/Reactor code, but current main owns the shipping chat contract in Reactor. Make the catalog derived from named native owners instead of directing implementation through a parallel authority.
  • Mark chat patterns as incomplete references (P2) - The composer sample omits current session routing, speaker mute, attachment handling, queued-message state, and the Send/Stop action. Label it partial and link the current Reactor owners, or model the complete shipping contract.
  • Replace retired JSX catalog references (P2) - The branch migrated to components.jsonc, but this guidance still tells readers that components.jsx is the preview implementation. Correct the stale references in all three catalog files so agents do not look for or validate a nonexistent artifact.
  • Remove em dashes from agent-facing catalog guidance (P2) - This prior review blocker remains throughout the new agent-facing files. Normalize the prose to the repository's requested plain guidance style before treating it as durable instruction for automation.
  • Add repository-owned catalog validation (P2) - The catalog claims a JSON-to-DOM schema and component references, but this repository has no focused check for JSONC parsing, reference resolution, or schema drift. Add a focused smoke test or validation script so future edits cannot silently break the agent artifact.
  • Resolve merge risk (P1) - Merging the catalog as written would give agents an outdated parallel chat contract, omitting current session, attachment, queue, mute, and Send/Stop behavior.
  • Resolve merge risk (P1) - The screenshots and validation claim target the removed JSX/Babel implementation rather than the current JSONC catalog, so the catalog's current rendering and themed behavior remain unproven.
  • Complete next step (P2) - A maintainer must first decide whether this repository should own a derived agent-facing design catalog; the remaining fixes and proof depend on that choice.
  • Improve patch quality - Address the highest-priority review finding and re-run the changed-surface validation.

Findings

  • [P1] Keep native UI as the canonical design contract — .agents/design/principles.md:19-21
  • [P2] Mark chat patterns as incomplete references — .agents/design/components.jsonc:156-162
  • [P2] Replace retired JSX catalog references — .agents/design/principles.md:8-10
Agent review details

Security

None.

Review metrics

Metric Value Why it matters
Catalog surface 3 files added, 474 lines All added content is agent-facing guidance, so its authority and drift contract matter more than application build output.

Merge-risk options

Maintainer options:

  1. Rebase the catalog on current UI ownership (recommended)
    Make it derived-only, cover or explicitly exclude current Reactor composer behavior, and add a repository-owned validation and current-head proof before merge.
  2. Defer the new authority surface
    Close or leave the draft parked if maintainers do not want to own a parallel agent-facing design contract.

Technical review

Best possible solution:

Either keep native WinUI/Reactor source as the sole canonical contract and defer this catalog, or explicitly adopt a derived-only catalog that links to current owners, declares incomplete examples, and has repository-owned validation.

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

Yes for the documentation defect: the current head contains JSONC while its guidance and PR proof still reference the retired JSX/Babel path; source inspection also shows current main uses Reactor chat owners absent from the examples.

Is this the best way to solve the issue?

No: a standalone source-of-truth catalog is not yet the safest approach because it conflicts with the current native implementation's ownership and lacks a maintained synchronization contract.

Full review comments:

  • [P1] Keep native UI as the canonical design contract — .agents/design/principles.md:19-21
    This says uncovered values must be added to the catalog before native/Reactor code, but current main owns the shipping chat contract in Reactor. Make the catalog derived from named native owners instead of directing implementation through a parallel authority.
    Confidence: 0.94
  • [P2] Mark chat patterns as incomplete references — .agents/design/components.jsonc:156-162
    The composer sample omits current session routing, speaker mute, attachment handling, queued-message state, and the Send/Stop action. Label it partial and link the current Reactor owners, or model the complete shipping contract.
    Confidence: 0.96
  • [P2] Replace retired JSX catalog references — .agents/design/principles.md:8-10
    The branch migrated to components.jsonc, but this guidance still tells readers that components.jsx is the preview implementation. Correct the stale references in all three catalog files so agents do not look for or validate a nonexistent artifact.
    Confidence: 0.99
  • [P2] Remove em dashes from agent-facing catalog guidance — .agents/design/components.jsonc:1-8
    This prior review blocker remains throughout the new agent-facing files. Normalize the prose to the repository's requested plain guidance style before treating it as durable instruction for automation.
    Confidence: 0.82
  • [P2] Add repository-owned catalog validation — .agents/design/components.jsonc:10-22
    The catalog claims a JSON-to-DOM schema and component references, but this repository has no focused check for JSONC parsing, reference resolution, or schema drift. Add a focused smoke test or validation script so future edits cannot silently break the agent artifact.
    Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ccd64bbb7d68.

Labels

Label changes:

  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
  • add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.
  • remove status: 📣 needs proof: Current PR status label is status: ⏳ waiting on author.
  • remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.
  • remove proof: 📸 screenshot: Current real behavior proof evidence kind is not_applicable.

Label justifications:

  • P2: The draft can misguide future Windows Hub UI work but does not change the released application.
  • merge-risk: 🚨 compatibility: A parallel design authority can cause future UI changes to diverge from the current native WinUI/Reactor contract.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.

Evidence

What I checked:

  • Current shipping chat owner: Current main directly imports Microsoft.UI.Reactor for the composer, while the project declares the Reactor package as a dependency. (src/OpenClaw.Tray.WinUI/Chat/ReactorChatComposer.cs:2, ccd64bbb7d68)
  • Main has moved beyond the catalog snapshot: Current-main history identifies commit d3ed6c7 as removing the retired FunctionalUI chat surface; current main instead mounts the Reactor surface and passes attachment, mute, session, and read-aloud behavior into it. (src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs:227, d3ed6c78bf14)
  • Catalog claims an upstream authority: The proposed guidance tells contributors to add uncovered values to the design files before porting them into native/Reactor code, creating a parallel authority despite the maintainer review requesting native behavior remain canonical. (.agents/design/principles.md:19, d03a4ffcda60)
  • Current-head documentation is internally stale: The branch contains components.jsonc, but both the principles and metadata still describe components.jsx as the preview artifact. (.agents/design/principles.md:9, d03a4ffcda60)
  • Repository proof policy: Repository policy explicitly covers agent-facing instructions and requires current-head proof plus focused validation; the PR has no repository-owned parser/render check and its body describes the retired JSX/Babel pipeline. (AGENTS.md:51, d03a4ffcda60)

Likely related people:

  • calebeden: Current main's removal of the retired FunctionalUI chat surface and the current Reactor chat path are attributed to this recent work. (role: recent chat-architecture contributor; confidence: high; commits: d3ed6c78bf14, a76c85218c7d; files: src/OpenClaw.Tray.WinUI/Chat/ReactorChatComposer.cs, src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs)
  • Barbara Kudiess: The current composer ownership refactor provides the source contract that the proposed static composer example would need to follow. (role: composer ownership contributor; confidence: high; commits: 686afdc8d4a2; files: src/OpenClaw.Tray.WinUI/Chat/ReactorChatComposer.cs, src/OpenClaw.Tray.WinUI/Chat/ChatComposerFactory.cs)
  • shanselman: The existing review discussion specifically asks that native behavior remain canonical and that derived artifacts state their coverage limits. (role: design-boundary reviewer; confidence: medium; files: .agents/design/design.json, .agents/design/principles.md)

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 (44 earlier review cycles; latest 8 shown)
  • reviewed 2026-08-07T21:27:26.140Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native behavior the canonical design contract | [P2] Mark chat patterns as incomplete references | [P2] Remove retired JSX catalog references | [P2] Remove em dashes from agent-facing guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-08T14:24:24.565Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native UI the canonical design contract | [P2] Mark chat patterns as incomplete references | [P2] Remove retired JSX catalog references | [P2] Remove em dashes from agent-facing guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-08T15:40:17.037Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Keep native UI as the canonical design contract | [P2] Label static chat examples as incomplete references | [P2] Replace retired JSX catalog references | [P2] Remove em dashes from agent-facing guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-09T00:05:54.512Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native UI the canonical design contract | [P2] Mark chat examples as incomplete references | [P2] Replace retired JSX catalog references | [P2] Remove em dashes from agent-facing guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-09T03:16:48.271Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Keep native UI as the canonical contract | [P2] Label chat patterns as incomplete references | [P2] Remove retired JSX catalog references | [P2] Remove em dashes from agent guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-09T09:28:12.979Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native UI the canonical design contract | [P2] Mark chat patterns as incomplete references | [P2] Reference the JSONC catalog instead of retired JSX | [P2] Remove em dashes from agent-facing guidance | [P2] Add repository-owned catalog validation
  • reviewed 2026-08-09T11:59:59.341Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native UI the canonical catalog authority | [P2] Mark chat catalog patterns as partial references | [P2] Replace retired JSX catalog references | [P2] Remove em dashes from agent-facing guidance | [P2] Add a repository-owned catalog smoke check
  • reviewed 2026-08-09T14:50:44.194Z sha d03a4ff :: needs real behavior proof before merge. :: [P1] Make native behavior the canonical design contract | [P2] Mark chat catalog patterns as incomplete references | [P2] Replace retired JSX catalog references | [P2] Remove em dashes from agent-facing catalog guidance | [P2] Add a repository-owned catalog smoke check

@karkarl
karkarl marked this pull request as draft July 10, 2026 19:46
karkarl and others added 2 commits July 10, 2026 12:58
@karkarl
Rename design system to Windows Fluent UI for OpenClaw
c95ed9c 
Rename the design system's brand from the product name (OpenClaw Windows
Hub) to Windows Fluent UI for OpenClaw, reflecting its basis in Windows
Fluent design conventions. Clarify that it is the design system for the
OpenClaw Windows Hub app in design.json and principles.md.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
Correct design.json meta provenance
536aa36 
The CSS/JSX scanner finds no files in this XAML repo; every token was
derived by manual inspection of the WinUI 3 XAML and C# surfaces. Update
meta.updatedBy and meta.note to reflect that accurately.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. labels Jul 10, 2026
@karkarl
karkarl marked this pull request as ready for review July 10, 2026 20:23
@clawsweeper clawsweeper Bot added proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jul 10, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jul 13, 2026
Merged
@shanselman

shanselman commented Jul 15, 2026

Copy link
Copy Markdown
Collaborator

🤖 Copilot assistant note, posted on Scott's behalf — this is not Scott writing personally.

I was initially confused about the intended authority boundary here. I inferred that the JSX was a non-shipping visual reference derived from the native WinUI app, but the current wording sends mixed signals:

  • design.json says the tokens were derived from the repository's native XAML/C# surfaces.
  • principles.md calls this “the design system” and says designers write here while developers and Copilot read it.
  • The PR description calls .agents/design/ a “source of truth.”

Because this is a native WinUI application, I suggest making the boundary explicit for future agents and contributors:

Native WinUI XAML/C# and observed product behavior are canonical. The JSX and design files are non-shipping, derived visual examples for Colophon and Copilot. When they differ, native wins.

It would also help to qualify or remove “source of truth,” and name who is responsible for synchronizing these derived examples after native UI changes. That clarity would have prevented my initial misreading and should keep future bots from treating the JSX as a parallel product authority.

Adopt Colophon port-target authority model in seed
ed110a1 
Design files are the source of truth for design (framework-agnostic);
components.jsx is design intent for the canvas preview, not shipping code.
Record how the design ships via authority.port targets:
- default: Native WinUI 3 / C# (Windows Fluent), ported via win-dev-skills
- chat surface (ChatBubble, ChatComposer, ChatThread): Reactor
  (microsoft-ui-reactor); no dedicated porting agent yet (WIP)

Updates meta.note, components.jsx header, and principles.md to match.

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

karkarl commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator Author

Pushed an update that reworks the authority framing in response to @scott's note about .agents/design/ being described as "the source of truth".

The seed now uses Colophon's new port-target model instead of a flat source-of-truth claim:

  • The design files stay the source of truth for design (tokens, component intent, principles) and are framework-agnostic. components.jsx is design intent for the canvas preview — explicitly not shipping code.
  • How a design ships is now recorded per-surface in design.json under authority:
    • Default: ships as Native WinUI 3 / C#, ported via win-dev-skills.
    • Chat surface (ChatBubble, ChatComposer, ChatThread): ships via Reactor (no dedicated porting agent yet — WIP).

So the boundary Scott asked for is now explicit: native XAML/C# (and Reactor for chat) is what ships; the JSX/design files are the upstream design intent that gets ported into it, and the syncSource/helperAgent name how and who. components.jsx and principles.md say the same thing in prose.

@karkarl
karkarl marked this pull request as draft July 16, 2026 20:53
@shanselman

shanselman commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

GitHub Copilot maintainer-assistant review — this is automated feedback, not a comment written personally by Scott.

Reviewed head: ed110a1c21c6065de3398f84d88fcdda4b2429e5

This should remain draft. The design-system idea is useful, but the current artifacts are not yet safe as authoritative guidance for a native WinUI app.

The main issues from the paired review:

  1. Theme/high-contrast contract: design.json contains fixed light-theme hex/rgba values while the shipping app relies on semantic ThemeResource/system brushes. Please either model Light/Dark/HighContrast variants or mark every color as preview-only and map it to the WinUI resource key agents must use. Raw preview hex must not become implementation guidance.
  2. Native remains canonical: the repository’s native WinUI behavior is the source of truth. JSX/catalog artifacts should be described as derived visual examples, not a parallel upstream authority. Please revise the authority block and principles accordingly, and name an owner/sync process for keeping examples aligned.
  3. Component parity: the catalog composer omits shipping controls/state such as channel/session routing, speaker mute, send/stop behavior, pending attachments/queue state, and additional action slots. The assistant footer also omits Read Aloud and its state. Either represent the complete shipping contract or label these examples explicitly partial with links to the canonical native owners.
  4. Proof/validation: add current-head gallery proof for every exported component, including Light, Dark, and High Contrast behavior where applicable. Add a schema/parse/render smoke check for .agents/design/* so future drift is caught automatically.

Recommended framing: keep native XAML/C# behavior canonical; use this catalog to explain visual intent and reusable patterns, with semantic resource mappings and explicit coverage limits. That would preserve the value of the design artifacts without teaching future agents to hard-code colors or omit native functionality.

@karkarl karkarl mentioned this pull request Jul 20, 2026
Merged
karkarl and others added 2 commits July 20, 2026 12:18
@karkarl
Complete authority model for current colophon validation
dc55060 
The seed adopted the port-target authority model, but the latest colophon
validator now requires more once a port is set. Add the missing pieces so
design.json passes cleanly (0 errors / 0 warnings):

- authority.owner + authority.syncProcess (required when a port exists)
- per-color `resource` (WinUI Fluent ThemeResource brush keys) so agents bind
  system brushes instead of the preview-only hex
- per-color `themes` (dark + highContrast) for dark/high-contrast previews,
  matching the brand's stated "never hard-code hex that breaks in dark or
  high-contrast" principle

Keeps the existing port authoritySource (Native WinUI 3 / Windows Fluent),
win-dev-skills syncSource/helperAgent, and the chat -> Reactor portOverride.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
Migrate design system components to components.jsonc
d03a4ff 
Colophon replaced the pseudocode-React components.jsx format with a structured,
framework-agnostic components.jsonc element tree (rendered by a pure JSON->DOM
interpreter, no React/Babel). Port the seed's components over faithfully:

- Button, Field, Card, Badge, ChatBubble, ChatComposer, ChatThread, ExampleScreen
  translated to the element-tree schema at their rest state, keeping the ds-* classes,
  CSS-variable styling, WinUI-derived metrics, and SVG glyphs (send/mic/add/copy/chevron/
  sparkle) intact. ComposerPicker factored out as a reusable component.
- Interactive hover/press JS (not expressible in the static scene graph) is dropped;
  the preview shows the documented rest state.

Validates clean (0 errors / 0 warnings); all prototypes.jsonc component references
resolve.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl karkarl mentioned this pull request Jul 21, 2026
Closed
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. labels Jul 30, 2026
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. labels Aug 23, 2026
@shanselman

shanselman commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Closing stale parallel design-authority work. The catalog guidance is obsolete relative to the current native UI and should not remain an alternate source of truth.

@shanselman shanselman closed this Sep 2, 2026
@karkarl karkarl mentioned this pull request Sep 10, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@karkarl @shanselman