From 68360d03913ac7698bff949aa08cdc809407e04d Mon Sep 17 00:00:00 2001 From: Patrick Erichsen Date: Wed, 8 Jul 2026 16:17:40 -0700 Subject: [PATCH 1/3] chore: install OpenClaw design system --- .agents/skills/openclaw-brand/SKILL.md | 32 +++++++++++ .../openclaw-brand/references/asset-rights.md | 25 +++++++++ .../openclaw-brand/references/identity.md | 42 ++++++++++++++ .agents/skills/openclaw-design-audit/SKILL.md | 45 +++++++++++++++ .../references/fix-policy.md | 25 +++++++++ .../references/github-pr-delivery.md | 55 +++++++++++++++++++ .../references/report-format.md | 46 ++++++++++++++++ .../references/rubric.md | 37 +++++++++++++ .../skills/openclaw-design-system/SKILL.md | 38 +++++++++++++ .../references/consumer-adapters.md | 53 ++++++++++++++++++ .../references/tokens.md | 42 ++++++++++++++ .agents/skills/openclaw-design/SKILL.md | 31 +++++++++++ .../skills/openclaw-marketing-pages/SKILL.md | 32 +++++++++++ .../references/page-patterns.md | 36 ++++++++++++ package-lock.json | 11 ++++ package.json | 4 ++ skills-lock.json | 40 ++++++++++++++ 17 files changed, 594 insertions(+) create mode 100644 .agents/skills/openclaw-brand/SKILL.md create mode 100644 .agents/skills/openclaw-brand/references/asset-rights.md create mode 100644 .agents/skills/openclaw-brand/references/identity.md create mode 100644 .agents/skills/openclaw-design-audit/SKILL.md create mode 100644 .agents/skills/openclaw-design-audit/references/fix-policy.md create mode 100644 .agents/skills/openclaw-design-audit/references/github-pr-delivery.md create mode 100644 .agents/skills/openclaw-design-audit/references/report-format.md create mode 100644 .agents/skills/openclaw-design-audit/references/rubric.md create mode 100644 .agents/skills/openclaw-design-system/SKILL.md create mode 100644 .agents/skills/openclaw-design-system/references/consumer-adapters.md create mode 100644 .agents/skills/openclaw-design-system/references/tokens.md create mode 100644 .agents/skills/openclaw-design/SKILL.md create mode 100644 .agents/skills/openclaw-marketing-pages/SKILL.md create mode 100644 .agents/skills/openclaw-marketing-pages/references/page-patterns.md create mode 100644 skills-lock.json diff --git a/.agents/skills/openclaw-brand/SKILL.md b/.agents/skills/openclaw-brand/SKILL.md new file mode 100644 index 0000000000..9366d4e4a1 --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-brand/references/asset-rights.md b/.agents/skills/openclaw-brand/references/asset-rights.md new file mode 100644 index 0000000000..24c34b9f65 --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-brand/references/identity.md b/.agents/skills/openclaw-brand/references/identity.md new file mode 100644 index 0000000000..4f6013161a --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-design-audit/SKILL.md b/.agents/skills/openclaw-design-audit/SKILL.md new file mode 100644 index 0000000000..064aecbf4f --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-design-audit/references/fix-policy.md b/.agents/skills/openclaw-design-audit/references/fix-policy.md new file mode 100644 index 0000000000..6e1a4fcc13 --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-design-audit/references/github-pr-delivery.md b/.agents/skills/openclaw-design-audit/references/github-pr-delivery.md new file mode 100644 index 0000000000..0bb1091f12 --- /dev/null +++ b/.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 | diff --git a/.agents/skills/openclaw-design-audit/references/report-format.md b/.agents/skills/openclaw-design-audit/references/report-format.md new file mode 100644 index 0000000000..506336c82a --- /dev/null +++ b/.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.3", + "consumerSha": "", + "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. diff --git a/.agents/skills/openclaw-design-audit/references/rubric.md b/.agents/skills/openclaw-design-audit/references/rubric.md new file mode 100644 index 0000000000..c803b7a830 --- /dev/null +++ b/.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. diff --git a/.agents/skills/openclaw-design-system/SKILL.md b/.agents/skills/openclaw-design-system/SKILL.md new file mode 100644 index 0000000000..c900deedc6 --- /dev/null +++ b/.agents/skills/openclaw-design-system/SKILL.md @@ -0,0 +1,38 @@ +--- +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 the consumer repository for product +components and layouts. + +## 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. +- 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. +- Use an 8px maximum default radius unless a documented consumer pattern requires otherwise. +- 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 an implementation into this repository only when at least two consumers need +the same interface and behavior. Token aliases and thin framework adapters are +shared; application components remain local by default. diff --git a/.agents/skills/openclaw-design-system/references/consumer-adapters.md b/.agents/skills/openclaw-design-system/references/consumer-adapters.md new file mode 100644 index 0000000000..c2bdb29787 --- /dev/null +++ b/.agents/skills/openclaw-design-system/references/consumer-adapters.md @@ -0,0 +1,53 @@ +# Consumer Adapters + +## Plain CSS And Astro + +Use the complete contract when the global reset is desired: + +```css +@import "@openclaw/design-system"; +``` + +For a controlled migration, import `tokens.css`, `themes.css`, and +`typography.css`, then retain consumer-specific base and component CSS. +Theme switching remains application-owned. The canonical public-site selector is +`html[data-theme="light"|"dark"]`. + +## Tailwind 4 + +Import in this order: + +```css +@import "@openclaw/design-system/tokens.css"; +@import "@openclaw/design-system/themes.css"; +@import "@openclaw/design-system/typography.css"; +@import "@openclaw/design-system/themes/product.css"; +@import "@openclaw/design-system/compat/clawhub.css"; +@import "@openclaw/design-system/tailwind.css"; +``` + +The Tailwind adapter exposes theme utilities; it does not add components. Keep +Radix, React, route, and product primitives in the consumer. + +The ClawHub compatibility adapter understands: + +- `data-theme-family="claw"` +- `data-theme-resolved="light"|"dark"` +- `data-theme-mode="system"` +- the existing unprefixed token aliases + +Remove aliases only after source search and browser validation prove that no +consumer uses them. + +## Static Documentation Builders + +Copy or resolve the focused CSS exports as build inputs. Import tokens, themes, +and typography before the docs shell CSS. Do not import `base.css` until the +generated navigation, prose, search, code, and Mermaid views have been compared +in a real browser. + +## Versioning + +Install an immutable Git tag. Runtime CSS and skill guidance use the same tag. +Dependabot or a scheduled update workflow may propose a newer tag, but migration +and visual validation remain consumer responsibilities. diff --git a/.agents/skills/openclaw-design-system/references/tokens.md b/.agents/skills/openclaw-design-system/references/tokens.md new file mode 100644 index 0000000000..9663b658f1 --- /dev/null +++ b/.agents/skills/openclaw-design-system/references/tokens.md @@ -0,0 +1,42 @@ +# Token Contract + +Import `@openclaw/design-system` for the complete foundation or use focused +exports when the consumer must control reset and adapter order. + +## Layers + +| Layer | Prefix | Purpose | +| --- | --- | --- | +| Palette | `--oc-palette-*` | Fixed source colors; rare direct use | +| Semantic | `--oc-bg-*`, `--oc-text-*`, `--oc-accent-*` | Theme-aware UI intent | +| Scale | `--oc-space-*`, `--oc-font-size-*`, `--oc-radius-*` | Shared dimensions | +| Product | `--oc-status-*`, `--oc-input-*`, `--oc-diff-*` | Opt-in operational UI | +| Consumer alias | Unprefixed legacy names | Migration compatibility only | + +## Semantic Choices + +- Page background: `--oc-bg-page` +- Ordinary surface: `--oc-bg-surface` +- Elevated surface: `--oc-bg-elevated` +- Primary, secondary, muted text: `--oc-text-primary`, + `--oc-text-secondary`, `--oc-text-muted` +- Primary action: `--oc-accent-primary`; hover: + `--oc-accent-primary-hover` +- Secondary accent: `--oc-accent-secondary` +- Subtle and accent borders: `--oc-border-subtle`, + `--oc-border-accent` +- Focus: `--oc-focus-ring` + +Use `color-mix()` from semantic variables for a local translucent state. Add a +new shared semantic token only when the same intent recurs across consumers. + +## Radius + +The shared default is `--oc-radius-md` (8px). Larger radii require an existing +consumer pattern or a clear content reason. Pills are reserved for compact +status, filtering, or segmented-control semantics. + +## Ownership + +Consumer repositories own component geometry, page layout, and application +states. This package owns stable visual foundations and thin migration aliases. diff --git a/.agents/skills/openclaw-design/SKILL.md b/.agents/skills/openclaw-design/SKILL.md new file mode 100644 index 0000000000..967777e91c --- /dev/null +++ b/.agents/skills/openclaw-design/SKILL.md @@ -0,0 +1,31 @@ +--- +name: openclaw-design +description: Route OpenClaw design work to the canonical brand, product design-system, marketing-page, or design-audit guidance. Use when a task touches OpenClaw visual identity, shared CSS tokens, product UI, public web pages, or design-system compliance. +--- + +# OpenClaw Design + +Choose one focused branch before changing an interface. Load multiple branches +only when the task genuinely crosses them. + +| Skill | Use for | +| --- | --- | +| `openclaw-brand` | Identity decisions, typography, logos, imagery, voice, and non-product brand artifacts | +| `openclaw-design-system` | Application UI, semantic tokens, themes, component reuse, and framework adapters | +| `openclaw-marketing-pages` | Public-page composition, landing/content pages, navigation, SEO, and responsive layout | +| `openclaw-design-audit` | Design drift, token misuse, component substitution, accessibility, and recurring audits | + +For a public website change, start with `openclaw-marketing-pages` and add +`openclaw-brand` only when the task changes identity, logo, imagery, typography, +or voice. For a product application, start with `openclaw-design-system`. + +## Shared Contract + +- Treat this repository's release tag as the version of both runtime CSS and agent guidance. +- Prefer semantic tokens over raw palette values. +- Keep product-specific components and layouts in their consumer repository. +- Add shared implementation only after at least two consumers demonstrate the same interface. +- Preserve consumer behavior while changing the visual foundation. +- Validate rendered pages in a real browser at desktop and mobile sizes. +- Check both light and dark themes where the consumer supports them. +- Do not redistribute fonts, logos, or artwork without recorded permission. diff --git a/.agents/skills/openclaw-marketing-pages/SKILL.md b/.agents/skills/openclaw-marketing-pages/SKILL.md new file mode 100644 index 0000000000..de15f61b5d --- /dev/null +++ b/.agents/skills/openclaw-marketing-pages/SKILL.md @@ -0,0 +1,32 @@ +--- +name: openclaw-marketing-pages +description: Create or update OpenClaw public-page composition for websites, landing pages, content pages, ecosystem pages, and campaigns. Use for page structure, navigation, responsive layout, media, SEO presentation, or public-site visual polish. +--- + +# OpenClaw Marketing Pages + +Build the real public experience first. Do not replace it with a generic landing-page +template or an explanatory feature tour. + +## Workflow + +1. Read [page-patterns.md](references/page-patterns.md). +2. Inspect the consumer's existing header, footer, sections, and page primitives. +3. Reuse local public-site patterns before adding another composition. +4. Use the canonical tokens and typography contract. +5. Make the brand, product, place, or object visible in the first viewport. +6. Keep a hint of the next section visible at common desktop and mobile heights. +7. Validate navigation, content hierarchy, media, light/dark themes, and responsive behavior in a browser. + +## Rules + +- Use the literal brand, product, place, person, or offer as the primary headline. +- Put value propositions in supporting copy rather than an abstract headline. +- Use relevant product or community imagery instead of atmospheric stock media. +- Keep page sections unframed; use cards only for genuinely repeated items. +- Avoid repetitive social-proof, feature-grid, and CTA sections without a content need. +- Keep headings proportionate to their container. +- Use icons for tools and familiar actions; do not use decorative icon boxes. +- Preserve readable line length and clear section rhythm. +- Use motion to explain state or progression, not as ambient decoration. +- Preserve SEO metadata, semantic heading order, and accessible navigation. diff --git a/.agents/skills/openclaw-marketing-pages/references/page-patterns.md b/.agents/skills/openclaw-marketing-pages/references/page-patterns.md new file mode 100644 index 0000000000..bc4d566ac6 --- /dev/null +++ b/.agents/skills/openclaw-marketing-pages/references/page-patterns.md @@ -0,0 +1,36 @@ +# Public Page Patterns + +## First Viewport + +- Show the literal product, project, venue, person, or offer immediately. +- Use the name or literal category as the primary heading. +- Keep supporting copy specific: what it is, who it helps, and the next action. +- Let the next section remain partially visible at common viewport heights. +- Use an approved real image or an actual product state when media helps. + +## Structure + +- Reuse the consumer's header, footer, content width, and navigation behavior. +- Build sections as full-width bands or unframed layouts with constrained inner + content. +- Use cards for repeated comparable items, not as wrappers around every section. +- Keep one primary action per decision area and avoid repeated CTA blocks. +- Preserve semantic heading order, metadata, canonical URLs, and readable prose + widths. + +## Responsive Checks + +Check at least one narrow mobile viewport and one desktop viewport. Verify: + +- navigation and menus remain reachable +- headings and buttons wrap without clipping +- media shows the important subject +- fixed controls do not cover content +- horizontal scrolling is intentional +- light and dark themes preserve hierarchy and contrast + +## Local Ownership + +Marketing layouts, decorative textures, film grain, dot grids, site headers, +footers, article prose, and route-specific media remain in the consumer unless +multiple sites prove the same reusable interface. diff --git a/package-lock.json b/package-lock.json index a657283bca..7cd3c645b7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5,6 +5,9 @@ "packages": { "": { "name": "openclaw-docs-site", + "dependencies": { + "@openclaw/design-system": "github:openclaw/design-system#v0.0.3" + }, "devDependencies": { "@resvg/resvg-js": "^2.6.2", "highlight.js": "11.11.1", @@ -73,6 +76,14 @@ "@chevrotain/types": "~11.1.2" } }, + "node_modules/@openclaw/design-system": { + "version": "0.0.3", + "resolved": "git+ssh://git@github.com/openclaw/design-system.git#35c800b212fa0f8377012c2db70125f1babb74e9", + "license": "MIT", + "engines": { + "bun": ">=1.3.0" + } + }, "node_modules/@pagefind/darwin-arm64": { "version": "1.5.2", "resolved": "https://registry.npmjs.org/@pagefind/darwin-arm64/-/darwin-arm64-1.5.2.tgz", diff --git a/package.json b/package.json index d94f0cf025..0791272ed4 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "docs:smoke:shell": "DOCS_SITE_ARTIFACT_MODE=shell node scripts/docs-site/smoke.mjs", "docs:visual": "node scripts/docs-site/visual-smoke.mjs", "docs:check": "npm run docs:build && npm run docs:smoke && npm run docs:visual && node --check scripts/docs-site/llms-full.mjs", + "skills:install": "npm exec --yes --package=skills@1.5.15 -- skills add 'git@github.com:openclaw/design-system.git#v0.0.3' --skill '*' --agent codex --copy --yes --full-depth", "test": "node --test scripts/docs-site/frontmatter.test.mjs" }, "devDependencies": { @@ -27,5 +28,8 @@ "pagefind": "1.5.2", "playwright": "^1.61.1", "yaml": "2.9.0" + }, + "dependencies": { + "@openclaw/design-system": "github:openclaw/design-system#v0.0.3" } } diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 0000000000..1feacf569e --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,40 @@ +{ + "version": 1, + "skills": { + "openclaw-brand": { + "source": "git@github.com:openclaw/design-system.git", + "ref": "v0.0.3", + "sourceType": "git", + "skillPath": "openclaw-brand/SKILL.md", + "computedHash": "d4bf50bb9d512dbfbcd4abde7a75d8399b0187ca9486dd7854844aab0cd02e6a" + }, + "openclaw-design": { + "source": "git@github.com:openclaw/design-system.git", + "ref": "v0.0.3", + "sourceType": "git", + "skillPath": "SKILL.md", + "computedHash": "8de963d26ec19a920da5e2a5d029764bba7c941d5cb051c67a877d0e5d91c6a4" + }, + "openclaw-design-audit": { + "source": "git@github.com:openclaw/design-system.git", + "ref": "v0.0.3", + "sourceType": "git", + "skillPath": "openclaw-design-audit/SKILL.md", + "computedHash": "8cd4a597e67e6687e683924b0c1889f06d773340787681e168eceda1da35a9c3" + }, + "openclaw-design-system": { + "source": "git@github.com:openclaw/design-system.git", + "ref": "v0.0.3", + "sourceType": "git", + "skillPath": "openclaw-design-system/SKILL.md", + "computedHash": "0078deaff141b1685c4b74811f785e47c21089741c0538b7559b87d4cb25adb4" + }, + "openclaw-marketing-pages": { + "source": "git@github.com:openclaw/design-system.git", + "ref": "v0.0.3", + "sourceType": "git", + "skillPath": "openclaw-marketing-pages/SKILL.md", + "computedHash": "7da44d258d5a1e87b26535effa13cf20931fd04a884fd95225a4ff603932ef84" + } + } +} From ff2560cfe6c592239c799399526ab41c86946121 Mon Sep 17 00:00:00 2001 From: Patrick Erichsen Date: Wed, 8 Jul 2026 20:58:18 -0700 Subject: [PATCH 2/3] chore: pin design system to v0.0.1 --- .../references/report-format.md | 2 +- .../skills/openclaw-design-system/SKILL.md | 15 +++++++++------ .../references/consumer-adapters.md | 8 +++++--- .../references/tokens.md | 19 ++++++++++++++----- package-lock.json | 6 +++--- package.json | 4 ++-- skills-lock.json | 14 +++++++------- 7 files changed, 41 insertions(+), 27 deletions(-) diff --git a/.agents/skills/openclaw-design-audit/references/report-format.md b/.agents/skills/openclaw-design-audit/references/report-format.md index 506336c82a..225a179387 100644 --- a/.agents/skills/openclaw-design-audit/references/report-format.md +++ b/.agents/skills/openclaw-design-audit/references/report-format.md @@ -6,7 +6,7 @@ Produce both `design-audit.json` and `design-audit.md`. ```json { - "designSystemVersion": "v0.0.3", + "designSystemVersion": "v0.0.1", "consumerSha": "", "summary": { "errors": 0, diff --git a/.agents/skills/openclaw-design-system/SKILL.md b/.agents/skills/openclaw-design-system/SKILL.md index c900deedc6..2b6677e6c8 100644 --- a/.agents/skills/openclaw-design-system/SKILL.md +++ b/.agents/skills/openclaw-design-system/SKILL.md @@ -5,8 +5,8 @@ description: Build or modify OpenClaw application UI using canonical semantic to # OpenClaw Design System -Use the shared package for foundations and the consumer repository for product -components and layouts. +Use the shared package for foundations and framework-neutral visual primitives. +Keep consumer-specific behavior, data, routes, and layout composition local. ## Workflow @@ -20,19 +20,22 @@ components and layouts. ## 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. -- Use an 8px maximum default radius unless a documented consumer pattern requires otherwise. +- 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 an implementation into this repository only when at least two consumers need -the same interface and behavior. Token aliases and thin framework adapters are -shared; application components remain local by default. +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. diff --git a/.agents/skills/openclaw-design-system/references/consumer-adapters.md b/.agents/skills/openclaw-design-system/references/consumer-adapters.md index c2bdb29787..bfa8ac0b03 100644 --- a/.agents/skills/openclaw-design-system/references/consumer-adapters.md +++ b/.agents/skills/openclaw-design-system/references/consumer-adapters.md @@ -9,7 +9,7 @@ Use the complete contract when the global reset is desired: ``` For a controlled migration, import `tokens.css`, `themes.css`, and -`typography.css`, then retain consumer-specific base and component CSS. +`typography.css`, then `components.css`. Retain consumer-specific layout CSS. Theme switching remains application-owned. The canonical public-site selector is `html[data-theme="light"|"dark"]`. @@ -21,13 +21,15 @@ Import in this order: @import "@openclaw/design-system/tokens.css"; @import "@openclaw/design-system/themes.css"; @import "@openclaw/design-system/typography.css"; +@import "@openclaw/design-system/components.css"; @import "@openclaw/design-system/themes/product.css"; @import "@openclaw/design-system/compat/clawhub.css"; @import "@openclaw/design-system/tailwind.css"; ``` -The Tailwind adapter exposes theme utilities; it does not add components. Keep -Radix, React, route, and product primitives in the consumer. +The Tailwind adapter exposes theme utilities. `components.css` provides +framework-neutral classes; keep Radix, React, route, and product behavior in the +consumer. The ClawHub compatibility adapter understands: diff --git a/.agents/skills/openclaw-design-system/references/tokens.md b/.agents/skills/openclaw-design-system/references/tokens.md index 9663b658f1..32303f2256 100644 --- a/.agents/skills/openclaw-design-system/references/tokens.md +++ b/.agents/skills/openclaw-design-system/references/tokens.md @@ -10,6 +10,7 @@ exports when the consumer must control reset and adapter order. | Palette | `--oc-palette-*` | Fixed source colors; rare direct use | | Semantic | `--oc-bg-*`, `--oc-text-*`, `--oc-accent-*` | Theme-aware UI intent | | Scale | `--oc-space-*`, `--oc-font-size-*`, `--oc-radius-*` | Shared dimensions | +| Motion | `--oc-duration-*`, `--oc-ease-*` | Shared interaction timing | | Product | `--oc-status-*`, `--oc-input-*`, `--oc-diff-*` | Opt-in operational UI | | Consumer alias | Unprefixed legacy names | Migration compatibility only | @@ -32,11 +33,19 @@ new shared semantic token only when the same intent recurs across consumers. ## Radius -The shared default is `--oc-radius-md` (8px). Larger radii require an existing -consumer pattern or a clear content reason. Pills are reserved for compact -status, filtering, or segmented-control semantics. +Use semantic geometry roles in product UI: + +- `--oc-radius-surface`: cards, panels, and framed sections +- `--oc-radius-control`: buttons, fields, chips, and segmented controls +- `--oc-radius-inset`: nested interactive or decorative surfaces +- `--oc-radius-round`: avatars, status dots, and genuinely circular indicators + +The first three roles are square in the canonical OpenClaw system. Raw +`--oc-radius-*` scale values remain available for documented exceptions, but +must not replace the semantic defaults. ## Ownership -Consumer repositories own component geometry, page layout, and application -states. This package owns stable visual foundations and thin migration aliases. +Consumer repositories own page composition and application states. This package +owns stable visual foundations, framework-neutral component primitives, and +thin migration aliases. diff --git a/package-lock.json b/package-lock.json index 7cd3c645b7..f25efb0926 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,7 +6,7 @@ "": { "name": "openclaw-docs-site", "dependencies": { - "@openclaw/design-system": "github:openclaw/design-system#v0.0.3" + "@openclaw/design-system": "github:openclaw/design-system#v0.0.1" }, "devDependencies": { "@resvg/resvg-js": "^2.6.2", @@ -77,8 +77,8 @@ } }, "node_modules/@openclaw/design-system": { - "version": "0.0.3", - "resolved": "git+ssh://git@github.com/openclaw/design-system.git#35c800b212fa0f8377012c2db70125f1babb74e9", + "version": "0.0.1", + "resolved": "git+ssh://git@github.com/openclaw/design-system.git#7b097d79eef6e9a0a4632f72727ac7450f07a1f2", "license": "MIT", "engines": { "bun": ">=1.3.0" diff --git a/package.json b/package.json index 0791272ed4..bc853f7081 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "docs:smoke:shell": "DOCS_SITE_ARTIFACT_MODE=shell node scripts/docs-site/smoke.mjs", "docs:visual": "node scripts/docs-site/visual-smoke.mjs", "docs:check": "npm run docs:build && npm run docs:smoke && npm run docs:visual && node --check scripts/docs-site/llms-full.mjs", - "skills:install": "npm exec --yes --package=skills@1.5.15 -- skills add 'git@github.com:openclaw/design-system.git#v0.0.3' --skill '*' --agent codex --copy --yes --full-depth", + "skills:install": "npm exec --yes --package=skills@1.5.15 -- skills add 'git@github.com:openclaw/design-system.git#v0.0.1' --skill '*' --agent codex --copy --yes --full-depth", "test": "node --test scripts/docs-site/frontmatter.test.mjs" }, "devDependencies": { @@ -30,6 +30,6 @@ "yaml": "2.9.0" }, "dependencies": { - "@openclaw/design-system": "github:openclaw/design-system#v0.0.3" + "@openclaw/design-system": "github:openclaw/design-system#v0.0.1" } } diff --git a/skills-lock.json b/skills-lock.json index 1feacf569e..696022f620 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -3,35 +3,35 @@ "skills": { "openclaw-brand": { "source": "git@github.com:openclaw/design-system.git", - "ref": "v0.0.3", + "ref": "v0.0.1", "sourceType": "git", "skillPath": "openclaw-brand/SKILL.md", "computedHash": "d4bf50bb9d512dbfbcd4abde7a75d8399b0187ca9486dd7854844aab0cd02e6a" }, "openclaw-design": { "source": "git@github.com:openclaw/design-system.git", - "ref": "v0.0.3", + "ref": "v0.0.1", "sourceType": "git", "skillPath": "SKILL.md", "computedHash": "8de963d26ec19a920da5e2a5d029764bba7c941d5cb051c67a877d0e5d91c6a4" }, "openclaw-design-audit": { "source": "git@github.com:openclaw/design-system.git", - "ref": "v0.0.3", + "ref": "v0.0.1", "sourceType": "git", "skillPath": "openclaw-design-audit/SKILL.md", - "computedHash": "8cd4a597e67e6687e683924b0c1889f06d773340787681e168eceda1da35a9c3" + "computedHash": "12fec90fd4aa1aa569de1beb5a3c85d06887a5e548704dbd094355edc0f52ad3" }, "openclaw-design-system": { "source": "git@github.com:openclaw/design-system.git", - "ref": "v0.0.3", + "ref": "v0.0.1", "sourceType": "git", "skillPath": "openclaw-design-system/SKILL.md", - "computedHash": "0078deaff141b1685c4b74811f785e47c21089741c0538b7559b87d4cb25adb4" + "computedHash": "475604f08f37186237fa62605fbfe16ea04367af81f4c3a8c59bcb395ae70cca" }, "openclaw-marketing-pages": { "source": "git@github.com:openclaw/design-system.git", - "ref": "v0.0.3", + "ref": "v0.0.1", "sourceType": "git", "skillPath": "openclaw-marketing-pages/SKILL.md", "computedHash": "7da44d258d5a1e87b26535effa13cf20931fd04a884fd95225a4ff603932ef84" From 6d2c6d4cada9e35278653418abe73bd4e8e15ef0 Mon Sep 17 00:00:00 2001 From: Patrick Erichsen Date: Thu, 9 Jul 2026 10:55:28 -0700 Subject: [PATCH 3/3] fix: use public design system installs --- package-lock.json | 5 +++-- package.json | 4 ++-- skills-lock.json | 20 ++++++++++---------- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/package-lock.json b/package-lock.json index f25efb0926..a9d8c75a47 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,7 +6,7 @@ "": { "name": "openclaw-docs-site", "dependencies": { - "@openclaw/design-system": "github:openclaw/design-system#v0.0.1" + "@openclaw/design-system": "https://github.com/openclaw/design-system/archive/refs/tags/v0.0.1.tar.gz" }, "devDependencies": { "@resvg/resvg-js": "^2.6.2", @@ -78,7 +78,8 @@ }, "node_modules/@openclaw/design-system": { "version": "0.0.1", - "resolved": "git+ssh://git@github.com/openclaw/design-system.git#7b097d79eef6e9a0a4632f72727ac7450f07a1f2", + "resolved": "https://github.com/openclaw/design-system/archive/refs/tags/v0.0.1.tar.gz", + "integrity": "sha512-lHrGhA5J52PLQcRTaIWLXMx/sCpd95zVnCFaJQfu2aJwsoLtRe1CgkHubuIjDKIpq4i8lPClFYGbdUKeTupeUQ==", "license": "MIT", "engines": { "bun": ">=1.3.0" diff --git a/package.json b/package.json index bc853f7081..508748cb5e 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "docs:smoke:shell": "DOCS_SITE_ARTIFACT_MODE=shell node scripts/docs-site/smoke.mjs", "docs:visual": "node scripts/docs-site/visual-smoke.mjs", "docs:check": "npm run docs:build && npm run docs:smoke && npm run docs:visual && node --check scripts/docs-site/llms-full.mjs", - "skills:install": "npm exec --yes --package=skills@1.5.15 -- skills add 'git@github.com:openclaw/design-system.git#v0.0.1' --skill '*' --agent codex --copy --yes --full-depth", + "skills:install": "npm exec --yes --package=skills@1.5.15 -- skills add 'openclaw/design-system#v0.0.1' --skill '*' --agent codex --copy --yes --full-depth", "test": "node --test scripts/docs-site/frontmatter.test.mjs" }, "devDependencies": { @@ -30,6 +30,6 @@ "yaml": "2.9.0" }, "dependencies": { - "@openclaw/design-system": "github:openclaw/design-system#v0.0.1" + "@openclaw/design-system": "https://github.com/openclaw/design-system/archive/refs/tags/v0.0.1.tar.gz" } } diff --git a/skills-lock.json b/skills-lock.json index 696022f620..b45218b325 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -2,37 +2,37 @@ "version": 1, "skills": { "openclaw-brand": { - "source": "git@github.com:openclaw/design-system.git", + "source": "openclaw/design-system", "ref": "v0.0.1", - "sourceType": "git", + "sourceType": "github", "skillPath": "openclaw-brand/SKILL.md", "computedHash": "d4bf50bb9d512dbfbcd4abde7a75d8399b0187ca9486dd7854844aab0cd02e6a" }, "openclaw-design": { - "source": "git@github.com:openclaw/design-system.git", + "source": "openclaw/design-system", "ref": "v0.0.1", - "sourceType": "git", + "sourceType": "github", "skillPath": "SKILL.md", "computedHash": "8de963d26ec19a920da5e2a5d029764bba7c941d5cb051c67a877d0e5d91c6a4" }, "openclaw-design-audit": { - "source": "git@github.com:openclaw/design-system.git", + "source": "openclaw/design-system", "ref": "v0.0.1", - "sourceType": "git", + "sourceType": "github", "skillPath": "openclaw-design-audit/SKILL.md", "computedHash": "12fec90fd4aa1aa569de1beb5a3c85d06887a5e548704dbd094355edc0f52ad3" }, "openclaw-design-system": { - "source": "git@github.com:openclaw/design-system.git", + "source": "openclaw/design-system", "ref": "v0.0.1", - "sourceType": "git", + "sourceType": "github", "skillPath": "openclaw-design-system/SKILL.md", "computedHash": "475604f08f37186237fa62605fbfe16ea04367af81f4c3a8c59bcb395ae70cca" }, "openclaw-marketing-pages": { - "source": "git@github.com:openclaw/design-system.git", + "source": "openclaw/design-system", "ref": "v0.0.1", - "sourceType": "git", + "sourceType": "github", "skillPath": "openclaw-marketing-pages/SKILL.md", "computedHash": "7da44d258d5a1e87b26535effa13cf20931fd04a884fd95225a4ff603932ef84" }