refactor: adopt shared OpenClaw design system (#200)

* chore: install OpenClaw design system

* feat: consume shared design tokens

* chore: automate design system updates

* chore: pin design system to v0.0.1

* chore: pin design system to v0.0.1

* chore: pin design system to v0.0.1

* fix: use public design system installs

* refactor: adopt canonical design system tokens

* chore: generalize skills updater

* chore: retry preview deployments

* fix: align js-yaml with Astro

Author: Patrick-Erichsen

.agents/skills/openclaw-brand/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: openclaw-brand
+description: Apply OpenClaw visual identity to logos, typography, imagery, voice, documents, presentations, social graphics, and launch materials. Use when the task changes brand identity rather than ordinary product UI or public-page composition.
+---
+
+# OpenClaw Brand
+
+Use the canonical identity without turning every surface into a marketing page.
+
+## Workflow
+
+1. Read [identity.md](references/identity.md) for palette, typography, logo, and voice.
+2. Read [asset-rights.md](references/asset-rights.md) before copying or redistributing assets.
+3. Identify the artifact's audience and whether it is product, documentation, or marketing.
+4. Use semantic design tokens when the artifact is code.
+5. Keep status colors functional; do not use them as arbitrary decoration.
+6. Verify contrast, responsive cropping, and text legibility.
+7. Verify logo clearspace only when approved consumer-local guidance defines it;
+   otherwise report that check as unavailable rather than inventing a measurement.
+
+## Rules
+
+- Use sentence case for headings, labels, buttons, and navigation.
+- Let OpenClaw coral carry primary brand emphasis.
+- Use sea-glass green as a restrained secondary accent.
+- Use neutral ink and warm-paper surfaces as the foundation.
+- Prefer Switzer-compatible sans-serif stacks for interface and body copy.
+- Reserve Sentient-compatible serif stacks for editorial accents and quotations.
+- Use system monospace for code unless the consumer already licenses another face.
+- Preserve logo proportions and colors. Do not rotate, distort, outline, or add effects.
+- Use real product, interface, community, or mascot imagery when imagery is needed.
+- Avoid generic technology gradients, decorative blobs, and ornamental glow as a substitute for content.

.agents/skills/openclaw-brand/references/asset-rights.md

@@ -0,0 +1,25 @@
+# Asset Rights
+
+This repository distributes CSS and guidance, not brand asset binaries.
+
+## Current Rule
+
+- Do not copy Switzer or Sentient font files into a consumer or release artifact.
+- Do not redistribute logos, lobster artwork, mascot files, photos, or
+  illustrations without a repository-local license or explicit recorded grant.
+- A public URL or an asset already committed to a site is not proof of
+  redistribution rights.
+- System and fallback font stacks are always acceptable.
+
+## Before Adding An Asset
+
+Record:
+
+1. source and owner
+2. license or written permission
+3. allowed uses and redistribution terms
+4. required attribution
+5. the repository path where that evidence lives
+
+If any item is unknown, keep the asset in the existing consumer and reference it
+only from that consumer.

.agents/skills/openclaw-brand/references/identity.md

@@ -0,0 +1,42 @@
+# OpenClaw Identity
+
+## Color
+
+Use semantic variables in code. The palette names below explain the identity;
+they are not permission to replace semantic tokens with raw values.
+
+| Role | Dark | Light |
+| --- | --- | --- |
+| Page | Ink `#101012` | Warm paper `#f6f5f3` |
+| Surface | Ink `#19191c` | Warm paper `#eceae6` |
+| Primary text | `#ededed` | `#17171a` |
+| Secondary text | `#bcbcc4` | `#46464e` |
+| Primary coral | `#f5654a` | `#d84a31` |
+| Secondary sea glass | `#4fc8ae` | `#14806e` |
+
+Coral is the primary brand and action color. Sea glass is a secondary accent for
+focus, contrast, and occasional supporting emphasis. Neither replaces functional
+success, warning, error, or information colors.
+
+## Typography
+
+- Display and body: Switzer when the consumer holds a license, otherwise the
+  `--oc-font-display` and `--oc-font-body` fallback stack.
+- Editorial accent: Sentient when licensed, otherwise `--oc-font-serif`.
+- Code: the consumer's licensed monospace or `--oc-font-mono`.
+- Use sentence case. Keep headings direct, concrete, and proportional to the
+  surface that contains them.
+
+## Voice
+
+OpenClaw should sound capable, direct, curious, and human. Prefer plain verbs,
+specific nouns, and short explanations. Avoid inflated futurism, vague claims,
+and novelty language that obscures what the product does.
+
+## Marks And Imagery
+
+- Preserve the supplied logo's aspect ratio and colors. Apply clearspace only
+  from approved consumer-local guidance; do not invent a measurement.
+- Do not reconstruct the logo from screenshots.
+- Use product interfaces, real community work, or approved mascot imagery.
+- Keep backgrounds useful to the subject; avoid generic gradients and glow.

.agents/skills/openclaw-design-audit/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: openclaw-design-audit
+description: Audit OpenClaw frontend code and rendered interfaces for design-system drift, token misuse, primitive reimplementation, accessibility problems, responsive defects, and off-brand copy. Use for design reviews, compliance checks, or scheduled audit-and-fix workflows.
+---
+
+# OpenClaw Design Audit
+
+Separate mechanical violations from judgment. Report suggestions as suggestions
+unless a documented rule makes them violations.
+
+## Workflow
+
+1. Read [rubric.md](references/rubric.md) and run every applicable category.
+2. Read the consumer's installed design-system version and current commit SHA.
+3. Read the version-matched
+   [token contract](../openclaw-design-system/references/tokens.md) and
+   [consumer adapters](../openclaw-design-system/references/consumer-adapters.md).
+4. Read the brand or marketing references when those categories apply.
+5. Run deterministic source checks before judgment-based review.
+6. Inspect representative rendered routes at desktop and mobile sizes.
+7. Check light and dark themes where supported.
+8. Emit the JSON and Markdown defined in [report-format.md](references/report-format.md).
+9. When asked to fix findings, apply only narrow changes allowed by [fix-policy.md](references/fix-policy.md).
+10. For scheduled ClawHub delivery, follow [github-pr-delivery.md](references/github-pr-delivery.md).
+
+## Evidence
+
+Each finding must include:
+
+- file and line
+- category and severity
+- stable rule ID
+- concise remediation
+- design-system reference
+- whether the finding is mechanical or judgment-based
+
+## Curation
+
+- Include every error.
+- Rank warnings before informational findings, then by affected-file count.
+- Surface at most five non-error findings in the concise report.
+- Summarize remaining non-error findings by count.
+- Treat zero errors, zero warnings, and five or fewer informational findings as
+  no significant drift.
+- Never invent source locations or visual evidence.

.agents/skills/openclaw-design-audit/references/fix-policy.md

@@ -0,0 +1,25 @@
+# Audit Fix Policy
+
+An audit may automatically fix a finding only when the change is narrow,
+deterministic, and covered by an existing rule.
+
+## Allowed
+
+- replace a raw value with an equivalent canonical semantic token
+- replace a new legacy alias with its canonical token
+- use an established local primitive instead of a duplicate raw control
+- add a missing accessible label when intent is unambiguous
+- repair clipping or overflow without changing information architecture
+- update the pinned design-system tag in a dedicated dependency change
+
+## Requires Human Review
+
+- copy, hierarchy, navigation, or information-architecture changes
+- new components or abstractions
+- broad visual redesign
+- deletion of compatibility aliases
+- asset or license interpretation
+- changes that intentionally alter current rendered behavior
+
+Do not combine unrelated dependency, redesign, and audit fixes in one pull
+request. Preserve tests and include real browser evidence for rendered changes.

.agents/skills/openclaw-design-audit/references/github-pr-delivery.md

@@ -0,0 +1,55 @@
+# GitHub Pull Request Delivery
+
+The scheduled ClawHub audit opens a pull request directly against
+`openclaw/clawhub`. It does not create or update a tracker issue.
+
+The schedule and credentials live in the consumer repository's GitHub Actions
+workflow. This design-system skill defines the audit and delivery contract; it
+does not schedule itself.
+
+## Branch And Scope
+
+- Use a stable automation branch such as `automation/design-audit`.
+- Start from current remote `main`.
+- Commit only the report and allowed deterministic fixes.
+- Do not overwrite unrelated human work on an existing branch.
+
+## Procedure
+
+1. Checkout `openclaw/clawhub` with full history and fetch remote `main`.
+2. Reset only the dedicated automation branch to `origin/main`.
+3. Install the design system at the workflow's pinned Git tag.
+4. Run source checks, browser checks, and report generation.
+5. Apply only fixes allowed by `fix-policy.md`.
+6. Write reports under the consumer's established audit-artifact path.
+7. If the decision table says `artifact only`, upload the reports and job
+   summary without pushing a branch.
+8. Otherwise commit, force-push the dedicated automation branch with
+   `--force-with-lease`, then use `gh pr create` or `gh pr edit` for the single
+   open pull request owned by that branch.
+
+## Pull Request
+
+The title must identify the audit and date. The body includes:
+
+- design-system version
+- audited ClawHub SHA
+- count by severity
+- commands and routes checked
+- concise expanded findings
+- whether fixes are included
+- paths to JSON, Markdown, and screenshot artifacts
+
+If an open audit pull request exists, update it only when it owns the same stable
+automation branch. Close it without merge when a later clean run makes its
+findings obsolete.
+
+## Decision Table
+
+| Findings | Delivery |
+| --- | --- |
+| One or more errors | Open or update the pull request |
+| Zero errors and one or more warnings | Open or update the pull request |
+| Zero errors, zero warnings, more than five informational findings | Open or update the pull request |
+| Zero errors, zero warnings, five or fewer informational findings | Artifact and job summary only |
+| No findings | Artifact and job summary only; close an obsolete open audit PR |

.agents/skills/openclaw-design-audit/references/report-format.md

@@ -0,0 +1,46 @@
+# Audit Report Format
+
+Produce both `design-audit.json` and `design-audit.md`.
+
+## JSON
+
+```json
+{
+  "designSystemVersion": "v0.0.1",
+  "consumerSha": "<sha>",
+  "summary": {
+    "errors": 0,
+    "warnings": 0,
+    "info": 0
+  },
+  "findings": [
+    {
+      "id": "token/raw-color",
+      "severity": "warning",
+      "kind": "mechanical",
+      "file": "src/example.css",
+      "line": 12,
+      "message": "Use the semantic accent token.",
+      "remediation": "Replace the raw coral value with var(--oc-accent-primary).",
+      "reference": "openclaw-design-system/references/tokens.md"
+    }
+  ]
+}
+```
+
+Sort findings by severity, rule ID, file, then line. Keep stable IDs so recurring
+automation can compare runs.
+
+## Markdown
+
+Include:
+
+1. audited design-system version and consumer SHA
+2. validation commands and rendered routes
+3. count by severity
+4. every error
+5. at most five warning or informational findings
+6. count of additional non-error findings not expanded
+
+Use repository-relative file links. State explicitly when no significant drift
+was found.

.agents/skills/openclaw-design-audit/references/rubric.md

@@ -0,0 +1,37 @@
+# Design Audit Rubric
+
+## Mechanical Rules
+
+| ID | Check |
+| --- | --- |
+| `token/raw-color` | New raw colors where a semantic token exists |
+| `token/undefined` | Custom properties used but not defined by package or consumer |
+| `token/legacy-alias` | New code depends on a migration-only alias |
+| `component/duplicate` | Raw control or primitive duplicates an established local primitive |
+| `component/state` | Missing hover, focus, disabled, loading, invalid, or selected state |
+| `layout/overflow` | Text or fixed-format UI clips or causes accidental horizontal scroll |
+| `a11y/name` | Interactive control lacks an accessible name |
+| `a11y/focus` | Keyboard focus is hidden, trapped, or incoherent |
+| `theme/parity` | Light or dark theme loses content, hierarchy, or contrast |
+| `asset/rights` | New distributable asset has no recorded rights |
+
+## Judgment Checks
+
+| ID | Check |
+| --- | --- |
+| `hierarchy/primary-action` | Competing primary actions obscure the decision |
+| `layout/card-overuse` | Sections or cards are unnecessarily nested or floated |
+| `typography/scale` | Type scale does not match its container or task density |
+| `brand/accent` | Coral, sea glass, or status colors are used without their intended role |
+| `marketing/subject` | First viewport hides the actual product, place, person, or offer |
+| `copy/clarity` | Interface text is vague, inflated, or does not name the action |
+
+## Severity
+
+- `error`: broken interaction, accessibility barrier, illegible theme, accidental
+  overflow, missing asset rights, or deterministic contract violation.
+- `warning`: likely drift or inconsistency with meaningful user impact.
+- `info`: improvement with limited current impact.
+
+Do not mark aesthetic preference as a violation. A finding needs source or
+rendered evidence and a documented rule.

.agents/skills/openclaw-design-system/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: openclaw-design-system
+description: Build or modify OpenClaw application UI using canonical semantic tokens, themes, shared CSS foundations, consumer adapters, and established local primitives. Use for product interfaces, component styling, theme work, or design-token integration.
+---
+
+# OpenClaw Design System
+
+Use the shared package for foundations and framework-neutral visual primitives.
+Keep consumer-specific behavior, data, routes, and layout composition local.
+
+## Workflow
+
+1. Read [tokens.md](references/tokens.md) before choosing colors, spacing, type, radii, or shadows.
+2. Read [consumer-adapters.md](references/consumer-adapters.md) for the current framework.
+3. Inspect the consumer's existing shared primitives before creating a component.
+4. Use semantic tokens for UI intent; use palette primitives only for documented exceptions.
+5. Keep application behavior, routes, and information architecture unchanged unless the task says otherwise.
+6. Validate the affected routes with existing tests and real browser screenshots.
+
+## Interface Rules
+
+- Import the complete CSS contract or its focused exported entry points.
+- Compose shared classes from `components.css` before adding a one-off visual implementation.
+- Use local shared primitives before raw controls or one-off component implementations.
+- Keep one primary action per decision area.
+- Use familiar icons for icon-only commands and provide accessible names.
+- Use status colors for status, warning, success, error, and informational meaning.
+- Keep cards, controls, and repeated fixed-format elements dimensionally stable.
+- Avoid nested decorative cards and page sections styled as floating cards.
+- Keep surfaces, controls, and insets square through their semantic radius tokens.
+- Reserve round geometry for avatars, status dots, and other truly circular indicators.
+- Keep focus, hover, active, disabled, loading, and invalid states coherent.
+- Keep text within its container at supported viewport sizes.
+- Prefer dense, scan-friendly composition for operational product surfaces.
+
+## Ownership
+
+Move visual implementation into this repository when its interface is
+framework-neutral and useful across consumers. Keep runtime behavior and
+framework adapters local until at least two consumers need the same interface
+and behavior.